皮奥格里奥简介
显示GDAL版本
您可以显示Pyogrio所根据的GDAL版本
>>> pyogrio.__gdal_version__
列出可用的驱动程序
使用 pyogrio.list_drivers() 列出GDAL安装中所有可用的驱动程序。然而，列出了驱动程序并不意味着它当前与Pyogrio兼容。
警告
并非所有驱动程序都支持所有几何或字段类型。
>>> from pyogrio import list_drivers
>>> list_drivers()
{...'GeoJSON': 'rw', 'GeoJSONSeq': 'rw',...}
支持GDAL版本中写入功能的驱动程序结束 "w" . Pyogrio中已知不支持的某些驱动程序被禁用写功能。
注：并非所有驱动程序都支持写入GeoDataFrame的内容;在写入数据源时，您可能会遇到由于不支持的数据类型、不支持的几何类型或其他与驱动程序相关的错误而导致的错误。
要查找支持读或写功能的驱动程序子集：
>>> list_drivers(read=True)
>>> list_drivers(write=True)
查看完整列表 [drivers] （https：//gdal.org/Drivers/vector/index.html）了解有关特定驱动程序的更多信息，包括其写入支持和配置选项。
众所周知，以下驱动程序在Pyogrio中得到了良好的支持和测试：
ESRI ShapefileFlatGeobufGeoJSONGeoJSONSeqGPKG
列出可用层
要列出数据源中的可用层：
>>> from pyogrio import list_layers
>>> list_layers('ne_10m_admin_0_countries.shp')
# Outputs ndarray with the layer name and geometry type for each layer
array([['ne_10m_admin_0_countries', 'Polygon']], dtype=object)
一些数据源（例如，ESRI FGDB）支持多层，其中一些可能是非空间的。在这种情况下，几何类型将是 None 。
阅读有关数据层的基本信息
要列出有关数据源中数据层的信息，请使用数据源中层的名称或其索引（从0开始）。默认情况下，这从第一层读取。
>>> from pyogrio import read_info
>>> read_info('ne_10m_admin_0_countries.shp')
# Outputs a dictionary with `crs`, `driver`, `encoding`, `fields`, `geometry_type`, and
# `features`
{
'crs': 'EPSG:4326',
'encoding': 'UTF-8',
'fields': array(['featurecla', 'scalerank', 'LABELRANK', ...], dtype=object),
'dtypes': array(['int64', 'object', 'object', 'object', 'float64'], dtype=object),
'geometry_type': 'Polygon',
'features': 255,
'driver': 'ESRI Shapefile',
}
注：pyogrio将报告 UTF-8 如果本地编码可能是 UTF-8 或者GDAL可以自动从检测到的原生编码转换为 UTF-8 。
使用名称或索引（以下内容等效）从层中读取：
>>>read_info('ne_10m_admin_0_countries.shp', layer='ne_10m_admin_0_countries')
>>>read_info('ne_10m_admin_0_countries.shp', layer=0)
将数据层读取到GePandas GeDataFrame中
从空间数据层读取所有要素。默认情况下，这在第一层上操作，除非 layer 使用层名称或索引指定。
>>> from pyogrio import read_dataframe
>>> read_dataframe('ne_10m_admin_0_countries.shp')
featurecla ... geometry
0 Admin-0 country ... MULTIPOLYGON (((117.70361 4.16341, 117.70361 4...
1 Admin-0 country ... MULTIPOLYGON (((117.70361 4.16341, 117.69711 4...
2 Admin-0 country ... MULTIPOLYGON (((-69.51009 -17.50659, -69.50611...
3 Admin-0 country ... POLYGON ((-69.51009 -17.50659, -69.51009 -17.5...
4 Admin-0 country ... MULTIPOLYGON (((-69.51009 -17.50659, -69.63832...
.. ... ... ...
250 Admin-0 country ... MULTIPOLYGON (((113.55860 22.16303, 113.56943 ...
251 Admin-0 country ... POLYGON ((123.59702 -12.42832, 123.59775 -12.4...
252 Admin-0 country ... POLYGON ((-79.98929 15.79495, -79.98782 15.796...
253 Admin-0 country ... POLYGON ((-78.63707 15.86209, -78.64041 15.864...
254 Admin-0 country ... POLYGON ((117.75389 15.15437, 117.75569 15.151...
阅读列的子集
您可以通过包含 columns 参数.这仅影响非几何柱：
>>> read_dataframe('ne_10m_admin_0_countries.shp', columns=['ISO_A3'])
ISO_A3 geometry
0 IDN MULTIPOLYGON (((117.70361 4.16341, 117.70361 4...
1 MYS MULTIPOLYGON (((117.70361 4.16341, 117.69711 4...
2 CHL MULTIPOLYGON (((-69.51009 -17.50659, -69.50611...
3 BOL POLYGON ((-69.51009 -17.50659, -69.51009 -17.5...
4 PER MULTIPOLYGON (((-69.51009 -17.50659, -69.63832...
.. ... ...
250 MAC MULTIPOLYGON (((113.55860 22.16303, 113.56943 ...
251 -99 POLYGON ((123.59702 -12.42832, 123.59775 -12.4...
252 -99 POLYGON ((-79.98929 15.79495, -79.98782 15.796...
253 -99 POLYGON ((-78.63707 15.86209, -78.64041 15.864...
254 -99 POLYGON ((117.75389 15.15437, 117.75569 15.151...
阅读功能子集
您可以使用阅读要素的子集 skip_features 和 max_features 。
要跳过前10个功能：
>>> read_dataframe('ne_10m_admin_0_countries.shp', skip_features=10)
注：如果驱动程序不支持随机寻找特定功能的能力，使用此参数可能会产生巨大的负担，因为它需要重写所有先前的功能。
注意：GeoDataFrame的索引基于从文件读取的要素，它不是从 skip_features 。
仅阅读前10个功能：
>>> read_dataframe('ne_10m_admin_0_countries.shp', max_features=10)
这些可以组合起来读取数据集中定义的范围，也许可以在多个过程中：
>>> read_dataframe('ne_10m_admin_0_countries.shp', skip_features=10, max_features=10)
注意：如果 use_arrow 是 True ， skip_features 和 max_features 将产生额外的负担，因为所有功能直到上面下一批大小 max_features (or数据层的大小）将在切片所请求的特征范围之前被读取。如果 max_features 仅小于Arrow的最大批量（65，536个功能） max_features 将被阅读。所有功能高达 skip_features 从数据源读取，然后丢弃，因为Arrow界面不支持随机寻找启动功能。与通过不使用这些参数的Arrow读取相比，这通常比不使用Arrow快得多。
按属性值过滤记录
您可以使用 where 参数用于按属性值过滤层中的要素。如果数据源原生支持SQL，则应使用其特定的SQL方言（例如SQLite和地理包： [SQLITE] （https：//gdal.org/user/ml_SQlite_dialog.html#ml-SQlite-dialogue），PostgreSQL）。如果没有， [OGRSQL WHERE] （https：//gdal.org/user/ogr_SQl_dialog.html#where）语法。请注意，不可能否决SQL方言，只有当您使用 sql 参数。
>>> read_dataframe('ne_10m_admin_0_countries.shp', where="POP_EST >= 10000000 AND POP_EST < 100000000")
按空间范围过滤记录
您可以使用 bbox 参数仅选择与bbox相交的那些要素。
>>> read_dataframe('ne_10m_admin_0_countries.shp', bbox=(-140, 20, -100, 40))
注： bbox 值必须与数据集位于同一个CRS中。
注意：如果GDAL存在并使用GEOS，则仅限相交的几何体 bbox 将返回;如果GEOS不可用或GDAL未使用，则将返回具有与此bbox相交的边界框的所有几何。 pyogrio.__gdal_geos_version__ 将会是 None 如果未检测到GEOS。
按几何图形过滤记录
您可以使用 mask 参数仅选择与Shapely（>= 2.0）几何相交的那些要素。
>>> mask = shapely.Polygon(([-80,8], [-80, 10], [-85,10], [-85,8], [-80,8]))
>>> read_dataframe('ne_10m_admin_0_countries.shp', mask=mask)
注： mask 值必须与数据集位于同一个CRS中。
如果您的面罩几何体处于其他表示形式（例如GeoJSON）中，则需要在使用之前将其转换为Shapely几何体 mask 。
>>> mask_geojson = '{"type":"Polygon","coordinates":[[[-80.0,8.0],[-80.0,10.0],[-85.0,10.0],[-85.0,8.0],[-80.0,8.0]]]}'
>>> mask = shapely.from_geojson(mask_geojson)
>>> read_dataframe('ne_10m_admin_0_countries.shp', mask=mask)
注意：如果GDAL存在并使用GEOS，则仅限相交的几何体 mask 将返回;如果GEOS不可用或GDAL未使用，则所有边界框与的边界框相交的几何 mask 将会被退还。 pyogrio.__gdal_geos_version__ 将会是 None 如果未检测到GEOS。
执行sql查询
您可以使用 sql 参数对数据集执行SQL查询。
根据数据集，您可以使用不同的SQL方言。默认情况下，如果数据集本机支持SQL，则SQL声明将原样传递。因此，SQL查询应该用相关的原生SQL方言编写（例如 [GeoPackage] （https：//gdal.org/Drivers/vector/gpkg.html）/ [Sqlite] （https：//gdal.org/Drivers/vector/SQlite.html）， [PostgreSQL] （https：//gdal.org/Drivers/vector/pg.html）。如果数据源本身不支持SQL（例如 [ESRI Shapefile] （https：//gdal.org/Drivers/vector/Shapefile.html）， [FlatGeobuf] （https：//gdal.org/Drivers/vector/flatgeobuf.html），您可以在'之间进行选择 [OGRSQL] （https：//gdal.org/user/ogr_SQl_dialog.html#ogr-SQl-dialogue）'（默认）和' [SQLITE] （https：//gdal.org/user/ml_SQlite_dialog.html#ml-SQlite-dialogue '。对于SELECT陈述，“SQLITE”方言往往会提供更多的空间要素 [spatialite] （https：//www.gaia-gis.it/gaia-sins/spatialite-ml-latest.html）可以使用函数。如果gdal在SQLite中没有支持spatialite，则可以使用 sql_dialect="INDIRECT_SQLITE" 能够在Geopackage等原生SQLite文件上使用spacealite函数。
您可以将SQL查询与用于过滤数据集的其他参数结合起来。当使用 columns ， skip_features ， max_features 和/或 where 重要的是要注意，它们将在SQL声明之后应用，因此您需要注意以下一些事情：
如果为SQL陈述中的列指定别名，则在使用
columns关键字。skip_features和max_features将应用于SQL查询返回的行，而不是原始数据集。
对于 bbox 参数，取决于SQL查询的方言和数据集的组合，将使用或不使用空间索引，例如：
ESRI Shape file：空间索引与“OGRSQL”一起使用，而不是与“SQPLE”一起使用。
Geopackage：始终使用空间索引。
以下SQL查询返回邻国最多的5个西欧国家：
>>> sql = """
SELECT geometry, name,
(SELECT count(*)
FROM ne_10m_admin_0_countries layer_sub
WHERE ST_Intersects(layer.geometry, layer_sub.geometry)) AS nb_neighbours
FROM ne_10m_admin_0_countries layer
WHERE subregion = 'Western Europe'
ORDER BY nb_neighbours DESC
LIMIT 5"""
>>> read_dataframe('ne_10m_admin_0_countries.shp', sql=sql, sql_dialect='SQLITE')
NAME nb_neighbours geometry
0 France 11 MULTIPOLYGON (((-54.11153 2.114...
1 Germany 10 MULTIPOLYGON (((13.81572 48.766...
2 Austria 9 POLYGON ((16.94504 48.60417, 16...
3 Switzerland 6 POLYGON ((10.45381 46.86443, 10...
4 Belgium 5 POLYGON ((2.52180 51.08754, 2.5...
强制几何图形被解读为2D几何图形
您可以使用以下功能将3D数据集强制为2D force_2d ：
>>> df = read_dataframe('has_3d.shp')
>>> df.iloc[0].geometry.has_z
True
>>> df = read_dataframe('has_3d.shp', force_2d=True)
>>> df.iloc[0].geometry.has_z
False
在没有几何的情况下读取Pandas数据框架
您可以通过设置从空间数据层中省略几何 read_geometry 至 False ：
>>> read_dataframe('ne_10m_admin_0_countries.shp', columns=['ISO_A3'], read_geometry=False)
ISO_A3
0 IDN
1 MYS
2 CHL
3 BOL
4 PER
.. ...
250 MAC
251 -99
252 -99
253 -99
任何不包括几何列的读取操作，无论是从非空间数据层读取还是省略上面的几何列，都会返回 Pandas DataFrame 。
您还可以将非空间表（例如ESRI文件地理数据库或DBF文件中的表）直接读取到Pandas中 DataFrame 。
读取要素界限
您可以读取数据集中所有要素或要素子集的边界，以便创建要素的空间索引，而无需读取所有基础几何。这通常比读取完整要素数据快2- 3倍，但主要好处是避免将所有要素数据读取到超大数据集的内存中。
>>> from pyogrio import read_bounds
>>> fids, bounds = read_bounds('ne_10m_admin_0_countries.shp')
fids 提供每个功能的全局功能id。 bounds 提供形状（4，n）的nd数组，其值为 xmin ， ymin ， xmax ， ymax 。
此功能支持从数据集中对要素进行子集化的选项：
skip_featuresmax_featureswherebboxmask
编写GePandas GeoDataFrame
您可以编写一个 GeoDataFrame df 文件如下：
>>> from pyogrio import write_dataframe
>>> write_dataframe(df, "/tmp/test.gpkg")
默认情况下，根据文件名的扩展名推断适当的驱动程序：
.fgb： [FlatGeobuf] （https：//gdal.org/Drivers/vector/flatgeobuf.html）.geojson： [GeoJSON] （https：//gdal.org/Drivers/vector/geojson.html）.geojsonl，.geojsons： [GeoJSONSeq] （https：//gdal.org/Drivers/vector/geojsonseq.html）.gpkg： [GPKG] （https：//gdal.org/Drivers/vector/gpkg.html）.shp： [ESRI Shapefile] （https：//gdal.org/Drivers/vector/Shapefile.html）
如果您想编写GDAL支持的其他文件格式，或者如果您想推翻扩展名的默认驱动程序，则可以使用 driver 关键词，例如 driver="GPKG" 。
引用现有数据源
某些驱动程序可能支持将记录附加到现有数据源中的现有数据层的能力。看到 [GDAL driver listing] （https：//gdal.org/Drivers/vector/index.html）了解有关您的GDAL版本的驱动程序功能的详细信息。
>>> write_dataframe(df, "/tmp/existing_file.gpkg", append=True)
注意：要附加到现有数据源的数据帧的数据结构必须与现有数据源的结构完全匹配。
注：并非所有支持写功能的驱动程序都支持给定GDAL版本的附加功能。
读取压缩文件/档案
GDAL支持直接从存档（例如压缩文件夹）读取，而无需首先手动解压存档。当数据集（例如ESRI Shapetime）由多个文件组成并作为压缩存档分发时，这尤其有用。
GDAL通过以下概念处理这一问题 [virtual file systems] （https：//gdal.org/user/virtual_file_Systems.html）使用 /vsiPREFIX/.. 路径（例如 /vsizip/.. ).为了方便起见，pyogrio还支持使用更常见的URI语法传递路径 zip://.. ：
>>> read_dataframe("/vsizip/ne_10m_admin_0_countries.zip")
>>> read_dataframe("zip://ne_10m_admin_0_countries.zip")
如果您的档案包含多个数据集，您需要指定使用哪一个数据集;否则GDAL将默认使用找到的第一个数据集。
>>> read_dataframe("/vsizip/multiple_datasets.zip/a/b/test.shp")
>>> read_dataframe("zip://multiple_datasets.zip/a/b/test.shp")
>>> read_dataframe("zip://multiple_datasets.zip!a/b/test.shp")
如果文件名或存档路径以结尾，Pyogrio将尝试自动检测压缩文件 .zip 并将添加 /vsizip/ 为您准备的前置码，但您必须使用 "!" 表示档案名称以读取档案中的特定数据集：
>>> read_dataframe("multiple_datasets.zip!/a/b/test.shp")
从远程文件系统读取
GDAL通过虚拟文件系统的概念支持多种远程文件系统，例如S3、Google Cloud或Azure。看到 [GDAL's docs on network file systems] （https：//gdal.org/user/virtual_file_Systems.html#network-based-file-Systems）了解更多详细信息。您可以使用GDAL的原生版本 /vsi../ 符号，但为了方便起见，pyogrio还支持用更常见的URI语法传递路径：
>>> read_dataframe("/vsis3/bucket/data.geojson")
>>> read_dataframe("s3://bucket/data.geojson")
还可以组合多个虚拟文件系统，例如从远程文件系统读取压缩文件夹（请参阅上面的部分）：
>>> read_dataframe("vsizip/vsis3/bucket/shapefile.zip")
>>> read_dataframe("zip+s3://bucket/shapefile.zip")
您还可以从具有以下语法的URL中读取：
>>> read_dataframe("https://s3.amazonaws.com/bucket/data.geojson")
>>> read_dataframe("zip+https://s3.amazonaws.com/bucket/shapefile.zip")
阅读和写作日期时报
GDAL仅支持毫秒分辨率的日期时间。因此，读取数据将提供最多毫秒的分辨率 (datetime64[ms] 数据类型）。Pandas2.0 pyogrio.read_dataframe() 将返回日期时间数据为 datetime64[ms] 相应地。对于之前版本的Pandas， datetime64[ns] 使用是因为不支持ms精度。写入时，仅保留高达ms的精度。
并非所有文件格式都专门支持存储日期时间数据，例如ESRI Shapetime。对于此类格式，或者如果您要求精度> ms，解决办法是将日期时间转换为字符串。
尽可能保留时区信息，但GDAL仅将时区表示为UTC偏差，而pandas使用ANA时区（通过 pytz 或 zoneinfo ).这意味着具有包含多个偏差的列的日历（例如，当从标准时间切换到夏令时）将被正确写入，但当通过 pyogrio.read_dataframe() 将作为UTC日期时间列返回，因为无法从存在的各个偏差重建原始时区。
数据集和层创建选项
可以使用GDAL中给定驱动程序可用的数据集和层创建选项（请参阅相关 [GDAL driver page] （https：//gdal.org/Drivers/vector/index.html）。这些可以作为额外的传递 kwargs 至 write_dataframe 或使用数据集或层级选项的字典。
在可能的情况下，Pyogrio使用驱动程序的元数据来确定给定选项是否适用于数据集或层级别。对于两个级别都提供相同选项的驱动程序，您需要使用 dataset_options 或 layer_options 以指定正确的级别。
选项名称自动转换为收件箱。
True / False 值自动转换为 'ON' / 'OFF' 。
例如，您可以使用创建选项为 [shapefile] （https：//gdal.org/Drivers/vector/Shapefile.html#layer-creation-ensions）。
>>> write_dataframe(df, "/tmp/test.shp", spatial_index=True)
您可以使用大写选项名称和值来完全匹配GDAL选项（默认情况下，创建选项转换为RST）：
>>> write_dataframe(df, '/tmp/test.shp', SPATIAL_INDEX="YES")
您还可以使用字典指定 dataset_options 或 layer_options 适合驾驶员：
>>> write_dataframe(df, '/tmp/test.shp', layer_options={"spatial_index": True})
>>> write_dataframe(df, '/tmp/test.gpkg', dataset_options={"version": "1.0"}, layer_options={"geometry_name": "the_geom"})
配置选项
可以设置 [GDAL configuration options] （https：//Trac.osgeo.org/gdal/wiki/SecurePoints）用于整个会话：
>>> from pyogrio import set_gdal_config_options
>>> set_gdal_config_options({"CPL_DEBUG": True})
True / False 值自动转换为 'ON' / 'OFF' 。