数据分析GIS【免费下载链接】geopandasPython tools for geographic data项目地址https://gitcode.com/gh_mirrors/ge/geopandas点击查看免费下载导读本文以 GeoPandas 官方 API 参考手册中 Input/output 索引页 为骨架系统讲解 GeoPandas 数据读写体系的四大板块GIS 矢量文件读写、PostGIS 空间数据库读写、Apache Parquet 与 Feather 二进制格式的快速往返。读完本文你将掌握read_file/to_file的参数细节与引擎切换机制、PostGIS 的 SRID 与几何类型推导逻辑、GeoParquet 元数据与编码选项并能在实际项目中按需选择最合适的读写方案。一、API 全景四大读写通道GeoPandas 的 I/O 功能通过geopandas.io模块实现公开函数在 geopandas/init.py 中统一注册为顶层 API并全部以GeoDataFrame的实例方法形式暴露。官方参考文档将其划分为四组分类读取函数写入方法底层依赖GIS 矢量文件read_file、read_file_info、list_layersGeoDataFrame.to_filepyogrio / fionaGDALPostGIS 数据库read_postgisGeoDataFrame.to_postgisSQLAlchemy GeoAlchemy2 psycopgFeatherread_featherGeoDataFrame.to_featherpyarrow 0.17Parquetread_parquetGeoDataFrame.to_parquetpyarrow这四组通道覆盖了从本地文件、URL、压缩包、对象存储到空间数据库的全部常见数据源是 GeoPandas 日常数据处理的基础设施。二、GIS 矢量文件读写read_file 与 to_file2.1 read_file一网打尽矢量格式geopandas.read_file(filename)是使用最频繁的入口几乎可以读取 GDAL/OGR 支持的任何矢量格式ESRI Shapefile、GeoJSON、GeoPackage、GML、GPX、FlatGeobuf 等。它的核心实现在 geopandas/io/file.py。参数速查表来自_read_file的 docstring 与实现参数类型/默认值说明filenamestr / pathlib.Path / file-like文件路径、URL或任何带read()方法的对象如打开的文件句柄、StringIO、BytesIObboxtuple(minx, miny, maxx, maxy)/ GeoDataFrame / GeoSeries / shapely Geometry仅加载与包围盒相交的要素不能与mask同时使用maskdict / GeoDataFrame / GeoSeries / shapely Geometry仅加载与给定几何相交的要素多几何时先做 union可能开销较大columnslist只读取指定列列名必须与数据源完全一致传空 list 可跳过所有属性列rowsint 或 slice只加载前 N 行或切片范围内的行enginepyogrio或fiona底层读取库见下文引擎机制**kwargs透传传给pyogrio.read_dataframe或fiona.open支持的输入形态路径对象直接传pathlib.Path源码 会先做~展开URL_read_file会先探测服务器是否支持 Range 请求随机访问支持则把 URL 原样传给引擎让 GDAL 通过网络文件系统流式读取不支持则先整体下载再传入内存源码ZIP 包使用 GDAL 虚拟文件系统语法如zip:///path/to/file.zip或带内部路径的zip:///file.zip!data/layer.shpfile-like 对象文件句柄、io.StringIO/BytesIO、fsspec 打开的流均可fiona 引擎会读取其内容转换为字节流处理。import geopandas # 最基本用法 df geopandas.read_file(nybb.shp) # 多图层文件指定 layer countries geopandas.read_file(package.gpkg, layercountries) # 只读前 10 行 df geopandas.read_file(nybb.shp, rows10) # 按包围盒过滤 df geopandas.read_file(nybb.shp, bbox(0, 0, 10, 20)) # 按几何 mask 过滤 df geopandas.read_file(nybb.shp, maskpolygon) # 只读取部分字段pyogrio 或 Fiona 1.9 df geopandas.read_file(nyc.gpkg, columns[name, rent2008]) # 跳过几何列返回纯 pandas.DataFrame pdf geopandas.read_file(nyc.gpkg, ignore_geometryTrue) # 用 SQL WHERE 子句过滤Fiona 1.9 或 pyogrio df geopandas.read_file(nyc.gpkg, wheresubboroughConey Island) # 将 GPKG 的 fid 作为索引pyogrio 引擎 df geopandas.read_file(columbus.gpkg, fid_as_indexTrue)引擎机制这是 GeoPandas 的一个关键设计。_check_enginegeopandas/io/file.py#L123-L154的判定顺序为显式传入的engine参数 全局选项geopandas.options.io_engine 自动探测优先 pyogrio其次 fiona。两引擎对同一批参数的处理存在差异从源码可归纳出bbox 的 CRS 处理fiona 引擎若传入 GeoSeries/GeoDataFrame 会先转换 CRS 对齐pyogrio 引擎要求 bbox 与数据集同一 CRS源码 中会读取数据集 CRS 后对 GeoSeries 做to_crsrows 的 slice 支持pyogrio 引擎支持rows10与rowsslice(10, 20)但不支持带 step 的切片也不支持负索引源码编码处理_read_file_fiona对 datetime 字段做毫秒级截断处理fiona 精度限制源码。加速读取使用默认 pyogrio 引擎时传use_arrowTrue可将读取速度提升约 2–4 倍需要环境中安装 pyarrow也可通过环境变量PYOGRIO_USE_ARROW1全局开启。2.2 list_layers 与 read_file_info图层探测对于多图层文件GeoPackage 等可用两个辅助函数先行探测geopandas.list_layers(filename)返回一个含name与geometry_type两列的DataFrame每行对应一个图层非空间图层如属性表的geometry_type为None实现见 geopandas/io/file.py#L873-L901geopandas.read_file_info(filename, layerNone)返回指定图层默认第一层的元数据字典包含字段名、几何类型、CRS 等信息实现见 geopandas/io/file.py#L904-L929。两者都直接包装pyogrio.list_layers与pyogrio.read_info因此仅在使用 pyogrio 引擎时可用。2.3 to_file写出矢量文件GeoDataFrame.to_file(filename, driverNone, ...)将数据写出到任意 OGR 支持的格式公开方法定义底层实现 geopandas/io/file.py#L620-L799。关键参数driver默认None从文件扩展名自动推断。内置映射表_EXTENSION_TO_DRIVERgeopandas/io/file.py#L157-L178覆盖.shp/.dbf → ESRI Shapefile、.geojson/.json → GeoJSON、.gpkg → GPKG、.gml/.xml → GML、.fgb → FlatGeobuf等无扩展名时按 Shapefile 文件夹处理schemafiona 引擎可传 schema 字典精细控制写出结构pyogrio 引擎不支持会抛ValueError源码index默认None仅当索引有名字、是 MultiIndex 或非整数 dtype 时才写出True/False强制写出或不写出modew覆盖、a追加并非所有 driver 支持追加pyogrio 引擎对应appendTrue参数crsfiona 引擎可显式指定 CRSGDAL 3.0 时写 WKT 而非 WKT1_GDAL源码pyogrio 引擎不支持传 crs一律使用 GeoDataFrame 自带的df.crsmetadatadict[str, str]仅 GPKG driver 支持写入文件元数据要求 Fiona 1.9 或 pyogrio 0.6校验逻辑见 geopandas/io/file.py#L109-L121。写出时的数据约束来自 geopandas/io/file.py#L716-L730 与用户指南列名超过 10 字符写 Shapefile 会被截断发出警告包含多个 geometry 列时直接抛错——建议先用GeoSeries.to_wkt()/to_wkb()转换非活动几何列或改用 Parquet/Feather原生支持多几何列GeoDataFrame 中的 Python 对象列如 tuple、list无法直接写入大部分格式需先转换。# 写 Shapefile默认推断 driver countries_gdf.to_file(countries.shp) # 显式指定 GeoJSON driver countries_gdf.to_file(countries.geojson, driverGeoJSON) # 多图层写 GeoPackage countries_gdf.to_file(package.gpkg, layercountries, driverGPKG) cities_gdf.to_file(package.gpkg, layercities, driverGPKG) # 多几何列处理非活动几何列转 WKT 后再写 countries_gdf[country_center] countries_gdf[geometry].centroid countries_gdf[country_center] countries_gdf[country_center].to_wkt() countries_gdf.to_file(countries.geojson, driverGeoJSON) # pyogrio 引擎下加速写出 countries_gdf.to_file(countries.shp, use_arrowTrue)schema 推断细节fiona 引擎在未显式传schema时调用infer_schemageopandas/io/file.py#L802-L850object/string 类型映射为str、datetime 映射为datetime、Int32/Int64/boolean 有专门映射几何类型通过_geometry_types区分 2D/3D3D 前缀与混合类型空数据默认Unknown。写空 DataFrame 时会发出警告因为部分 driver 可能失败。三、PostGIS 数据库读写3.1 read_postgis从空间数据库取数geopandas.read_postgis(sql, con, geom_colgeom, crsNone, ...)返回GeoDataFrame核心实现在 geopandas/io/sql.py#L126-L209。它的工作方式是用pandas.read_sql执行查询再把查询结果中的 WKB 几何列转换为 shapely 几何shapely.wkb.loads自动识别 bytes 与 hex 文本两种形式最后包装为GeoDataFrame。参数要点sqlSQL 查询字符串或表名查询结果必须包含一个 WKB 表示的几何列conSQLAlchemyEngine或Connectiongeom_col几何列名默认geomcrs可显式指定不指定时从数据库返回的首个几何的 SRID 自动推导——优先查询spatial_ref_sys表得到权威 CRS 名如EPSG:4326表缺失或查不到时回退为epsg:srid并发出警告源码chunksize设置后返回生成器每次产出指定行数的GeoDataFrame分块读取大结果集其余index_col、coerce_float、parse_dates、params与pandas.read_sql语义一致。from sqlalchemy import create_engine db_connection_url postgresql://myusername:mypasswordmyhost:5432/mydatabase con create_engine(db_connection_url) # PostGIS直接取含 geometry 的列 sql SELECT geom, highway FROM roads df geopandas.read_postgis(sql, con) # SpatiaLite需要显式转 WKB sql SELECT ST_AsBinary(geom) AS geom, highway FROM roads df geopandas.read_postgis(sql, con)3.2 to_postgis上传到 PostGISGeoDataFrame.to_postgis(name, con, schemaNone, if_existsfail, indexFalse, index_labelNone, chunksizeNone, dtypeNone)需要 SQLAlchemy、GeoAlchemy2 和 psycopg/psycopg2底层实现在 geopandas/io/sql.py#L343-L460。写入流程从源码还原的调用链SRID 提取_get_srid_from_crsgeopandas/io/sql.py#L259-L286按置信度 100 → 70 → 25 依次尝试to_epsg再尝试 ESRI 权威码全部失败则 SRID 记为 0未定义 CRS并警告几何类型推导_get_geometry_typegeopandas/io/sql.py#L212-L256——所有几何同型则用该类型LinearRing 转为 LineString混合类型或含 GeometryCollection 时降级为GEOMETRY任一几何含 Z 坐标则整体加Z后缀EWKB 转换_convert_to_ewkb用shapely.to_wkb(include_sridTrue)把几何序列化为带 SRID 的 EWKB写入通过pandas.DataFrame.to_sql配合自定义的_psql_insert_copygeopandas/io/sql.py#L316-L340方法——用COPY ... FROM STDIN WITH CSV批量灌入psycopg3 走cursor.copy()psycopg2 走copy_expert()比逐行 INSERT 快得多append 校验if_existsappend时先查目标表的Find_SRID若与当前 GeoDataFrame 的 SRID 不一致直接抛ValueError避免几何语义错乱。from sqlalchemy import create_engine engine create_engine(postgresql://myusername:mypasswordmyhost:5432/mydatabase) countries_gdf.to_postgis(countries_table, conengine) # 追加时 SRID 必须一致 countries_gdf.to_postgis(countries_table, conengine, if_existsappend)if_exists取值fail默认表已存在抛 ValueError、replace先删表再写入、append追加数据。schema默认public。四、Apache Parquet 与 Feather二进制快速往返4.1 格式背景Parquet 是 Hadoop 生态起源的高效列式存储格式Feather 是 Apache Arrow 内存格式的磁盘表示。两者都基于列式存储特别适合大数据分析与数据湖场景。GeoPandas 自 0.8 起支持这两种格式写入文件时遵循 GeoParquet 规范geo.columns.name记录每个几何列的encodingWKB / geoarrow、geometry_types、crsPROJJSON、bbox、covering等信息primary_column标记主几何列version标记规范版本creator记录写入方geopandas 及版本号。4.2 写入to_parquet 与 to_feather两个方法的完整签名与说明在 geodataframe.py#L1436-L1570底层实现_to_parquet/_to_feather在 geopandas/io/arrow.py#L462-L567。参数to_parquetto_featherindexTrue/False/NoneNone时 RangeIndex 只存元数据其余写为列同左compressionsnappy默认、gzip、brotli、lz4、zstd、Nonezstd、lz4、uncompressed默认 LZ4 可用则用 LZ4否则不压缩geometry_encodingWKB默认互操作性最好或geoarrowGeoParquet 1.1 实验性原生编码固定 WKBwrite_covering_bbox默认False开启后每行写bbox列支持read_parquet的 bbox 过滤读取计算开销较大仅 GeoParquet 1.1.0 支持不支持schema_version0.1.0/0.4.0/1.0.0/1.1.0/2.0.0默认最新稳定版 1.1.00.1.0–1.1.0默认 1.1.0额外 kwargs传给pyarrow.parquet.write_table传给pyarrow.feather.write_feather需要注意的约束从 geopandas/io/arrow.py#L178-L183 可确认写 GeoParquet 2.0.0 时仅支持 WKB 编码要用geoarrow编码需显式指定schema_version1.1.0。另外to_parquet只接受engineauto或pyarrow与 pandas API 兼容性处理源码。gdf.to_parquet(data.parquet) # 默认 snappy WKB gdf.to_parquet(data.parquet, compressionzstd) gdf.to_parquet(data.parquet, geometry_encodinggeoarrow, schema_version1.1.0) gdf.to_parquet(data.parquet, write_covering_bboxTrue) # 便于后续 bbox 过滤 gdf.to_feather(data.feather) gdf.to_feather(data.feather, compressionzstd)4.3 读取read_parquet 与 read_feather两个读取函数共享_arrow_to_geopandas主逻辑geopandas/io/arrow.py#L570-L611支持从路径、file-like 对象和带://的远程地址fsspec/pyarrow.fs含 S3、GCS 等读取。参数要点columns列子集。若读出的列里没有任何几何列则抛ValueError提示改用pandas.read_parquet若主几何列不在其中会把第一个读到的几何列提升为返回 GeoDataFrame 的活动几何列多几何列时发出警告bbox仅当文件写入了 covering bbox 元数据或 GeoParquet 2.0时可用(xmin, ymin, xmax, ymax)四元组。实现上优先把 bbox 转成 pyarrow 过滤表达式在行组层面裁剪无 bbox 列时退化为行组级手动过滤 行级后过滤源码以保证语义一致storage_optionsHTTP(S) URL 转发给 urllibs3://、gcs://等转发给 fsspec不传时若 pyarrow.fs 与 fsspec 都实现了某文件系统优先用 pyarrow.fsto_pandas_kwargs控制非几何列转 pandas 的行为如 dtype 转换其余 kwargs 透传给pyarrow.parquet.read_table/read_feather如filters谓词下推会与 bbox 过滤用拼接。兼容性读取支持 GeoParquet 0.1.0、0.4.0、1.0.0、1.1.0、2.0.0 全部版本若元数据缺少crs键按规范默认OGC:CRS84。gdf geopandas.read_parquet(data.parquet) gdf geopandas.read_parquet(data.parquet, columns[geometry, pop_est]) # 基于 covering bbox 的过滤读取 gdf geopandas.read_parquet(data.parquet, bbox(100, 40, 110, 50)) # 从字节流读取 with BytesIO(p_data) as geo_bytes: gdf geopandas.read_parquet(geo_bytes) gdf geopandas.read_feather(data.feather)Parquet 与 Feather 相比矢量文件格式的最大优势原生支持多个几何列矢量格式通常只支持一个活动几何列、保留完整 CRS 信息、读写速度极快、天然适配 Arrow 生态的数据分析链路。五、底层原理与实现佐证5.1 模块组织与公开 API 注册geopandas.io内部按数据源拆分为三个模块file.py矢量文件、sql.py数据库、arrow.pyParquet/Feather。顶层 geopandas/init.py 中通过别名导入暴露公共函数如from geopandas.io.file import _read_file as read_file同时这些函数以方法形式绑定在GeoDataFrame上。测试方面geopandas/io/tests/test_file.py 覆盖了 bbox/rows 过滤、URL 读取、file-like 对象、datetime 精度、Z 坐标写出、重复列检测等行为可作为参数边界的权威参考。5.2 两个容易踩坑的差异点fiona 与 pyogrio 的参数不对称schema、crs仅 fiona 引擎支持fid_as_index、use_arrow仅 pyogrio 支持metadata两者都要求 GPKG driver。跨引擎迁移代码时需先确认geopandas.options.io_engine的取值write 前请检查列与几何写 Shapefile 前列名超过 10 字符会被截断多几何列、重复列名pyogrio 引擎直接抛错、非标量对象列都会导致写出失败——这些校验逻辑集中在 geopandas/io/file.py#L716-L730 与 geopandas/io/file.py#L795-L797。六、选型建议场景推荐方案理由读取/写出各类标准 GIS 格式shp、GeoJSON、GPKG、GMLread_file/to_file覆盖最全自动推断 driver多图层文件如 GeoPackagelist_layersread_file(layer...)先探测再定向读取与 PostGIS 数据库交互read_postgis/to_postgisSQL 灵活SRID 自动推导COPY 批量灌入大数据分析、数据湖、多几何列往返read_parquet/to_parquet列式压缩存储、bbox 下推过滤、原生多几何列快速落盘/加载、Arrow 生态内交换read_feather/to_feather读写开销最低追求读取/写出极限速度各函数加use_arrowTruepyogrio 引擎官方文档说明可快 2–4 倍以上 API 的全部签名与完整参数说明还可直接查看官方参考页 docs/reference/io.rst 及其生成的 API 文档并结合 用户指南 io 章节 获得更多带示例的实战讲解。赞分享数据分析GIS【免费下载链接】geopandasPython tools for geographic data项目地址https://gitcode.com/gh_mirrors/ge/geopandas点击查看免费下载相关推荐GeoPandas 空间数据读写实战指南read_file / to_file / Parquet 与 PostGIS 全解析GeoPandas 空间数据读写实战指南read_file / to_file / Parquet 与 PostGIS 全解析 本指南以 GeoPandas数据分析GISpandas-on-Spark 输入输出I/OAPI 全解析从 CSV、Parquet 到 Delta Lake 与 JDBCpandas on Spark 输入输出I/OAPI 全解析从 CSV、Parquet 到 Delta Lake 与 JDBC Apache Spark大数据数据分析批处理流处理机器学习图计算ESP-IDF 标准输入输出Standard I/O与 Console 输出配置完全指南ESP IDF 标准输入输出Standard I/O与 Console 输出配置完全指南 导读 本文基于 ESP IDF 官方文档 docs/en/api物联网嵌入式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考