osmpythontools 完整使用手册一、包基础概述1. 核心定义osmpythontools规范分隔包名osm-python-tools是面向OpenStreetMap(OSM)开源地图数据的Python专用工具库底层封装pyosmium、requests、shapely、geopandas一站式处理OSM原始数据.osm/.osm.pbf/.osm.gz、API拉取地图、要素解析、空间过滤、格式转换、路网分析、POI提取。区分易混淆包osmium底层PBF解析核心无高层业务封装osmpythontools上层封装工具提供开箱即用的OSM业务接口overpy仅Overpass API简易请求无本地PBF解析能力。2. 核心功能总览OSM数据源读取本地.osm.pbf/xml/gz文件流式解析支持超大文件内存分片加载避免OOMOverpass API交互在线拉取指定区域、标签筛选的OSM矢量数据要素分层解析区分Node(点POI)、Way(道路/建筑面)、Relation(多面复合要素)提取标签tags、坐标、属性空间几何转换OSM原始坐标转WGS84、shapely几何对象Point/LineString/Polygon数据格式导出导出GeoJSON、Shapefile、CSV、Geopandas DataFrame路网专项工具道路分级过滤、长度计算、连通性分析、人行道/车道提取POI批量提取餐饮、商铺、医院、学校、停车场等分类筛选数据清洗剔除无标签要素、过滤无效坐标、合并相邻道路、去除重复节点地理范围裁剪按经纬度矩形、多边形边界裁切OSM数据标签查询统计统计区域内各类设施数量、标签频次。二、安装方式环境依赖前置Python ≥3.8系统依赖Windows无需额外系统库自动预编译wheelUbuntu/Debiansudo apt install libosmium2-dev protobuf-compilerMacOSbrew install osmium-tool protobuf标准安装# PyPI稳定版推荐pipinstallosm-python-tools# 开发最新版GitHub源码pipinstallgithttps://github.com/osm-search/osmpythontools.git# 国内镜像加速pipinstallosm-python-tools-ihttps://pypi.tuna.tsinghua.edu.cn/simple配套依赖自动安装安装时自动附带pyosmium, shapely, geopandas, requests, pandas, numpy, pyproj缺失依赖手动补充pipinstallpyosmium shapely geopandas三、核心语法、类与参数详解顶层核心模块# 全部核心导入importosmpythontoolsasosmptfromosmpythontools.readerimportPBFReader,OSMXMLReaderfromosmpythontools.overpassimportOverpassClientfromosmpythontools.geoutilsimportosm2shapely,bounds_to_polygonfromosmpythontools.exporterimportGeoJSONExporter,CSVExporterfromosmpythontools.filterimportTagFilter,BBoxFilterfromosmpythontools.statsimportTagCounter1. PBFReader 本地OSM文件读取器最常用初始化参数PBFReader(file_path:str,# 本地pbf文件路径chunk_size:int10000,# 流式分片大小超大文件调小5000~20000skip_relations:boolFalse,# 是否跳过关系要素提速设Trueparse_geometry:boolTrue,# 自动转shapely几何对象filter_tags:dictNone# 读取时直接标签过滤减少内存占用)核心方法.iter_nodes()迭代所有点要素返回Node对象.iter_ways()迭代线/面要素返回Way对象.iter_relations()迭代复合关系要素.get_gdf()一次性返回geopandas.GeoDataFrame.filter_bbox(min_lon, min_lat, max_lon, max_lat)空间范围过滤要素对象通用属性# NodePOI点node.id:int# OSM唯一IDnode.lon,node.lat:float# WGS84经纬度node.tags:dict# 标签字典如{shop:cafe,name:星巴克}node.geom:shapely.Point# 几何对象# Way道路/建筑way.id:intway.nodes:list[int]# 组成该线/面的节点ID列表way.tags:dictway.geom:shapely.LineString/Polygon way.is_area():bool# 判断是否闭合面建筑、公园# Relation复杂区域行政区、多洞建筑relation.members:list# 子要素ID与类型relation.tags:dictrelation.geom:shapely.MultiPolygon2. OverpassClient 在线API拉取参数OverpassClient(endpoint:strhttps://overpass-api.de/api/interpreter,# 服务地址timeout:int30,# 请求超时秒数user_agent:strosmpythontools/1.0,# 请求头UAproxy:dictNone# 代理配置{http:xxx,https:xxx})查询方法.query(ql: str)传入Overpass QL语句返回要素列表内置简化快捷函数.query_bbox(bbox, tags)按经纬度框标签查询.query_city(city_name, tags)按城市名查询3. TagFilter 标签过滤器参数TagFilter(include:dictNone,# 保留匹配标签 {highway:residential}exclude:dictNone,# 剔除匹配标签 {natural:water}require_any:listNone# 匹配任一标签如[(shop,cafe),(shop,restaurant)])4. 导出模块参数 GeoJSONExporterGeoJSONExporter(features,output_path,crsEPSG:4326)# features要素迭代器/列表output_path输出文件crs坐标系默认WGS84四、8个完整可运行实战案例案例1读取本地城市PBF提取全部餐饮POI并导出GeoJSON场景本地下载城市osm.pbf批量提取餐厅、咖啡店并保存矢量文件fromosmpythontools.readerimportPBFReaderfromosmpythontools.filterimportTagFilterfromosmpythontools.exporterimportGeoJSONExporter# 1. 初始化PBF读取器readerPBFReader(shanghai.osm.pbf,chunk_size8000,skip_relationsTrue)# 2. 定义餐饮标签过滤器food_filterTagFilter(require_any[(shop,cafe),(shop,restaurant),(amenity,restaurant),(amenity,cafe),(amenity,fast_food)])# 3. 过滤所有点POIfood_poi[]fornodeinreader.iter_nodes():iffood_filter.match(node):food_poi.append(node)# 4. 导出geojson供QGIS/前端地图使用GeoJSONExporter(food_poi,shanghai_food.geojson).save()print(f提取餐饮点位共{len(food_poi)}个)案例2Overpass在线API拉取指定区域主干道路网场景无需本地文件在线获取上海内环快速路、主干道数据fromosmpythontools.overpassimportOverpassClient clientOverpassClient(timeout60)# Overpass QL语句限定经纬度框高速/主干道ql [out:json][timeout:60]; bbox121.45,31.2,121.55,31.3; way[highway~motorway|trunk|primary]-.roads; out body; ; out skel qt; # 请求数据road_featuresclient.query(ql)# 遍历打印道路名称与等级forwayinroad_features:tagsway.tags road_typetags.get(highway)road_nametags.get(name,无名道路)print(f道路{road_name}等级{road_type})案例3解析OSM建筑面计算建筑面积并导出CSV场景批量统计区域住宅建筑占地面积输出表格供数据分析fromosmpythontools.readerimportPBFReaderfromosmpythontools.filterimportTagFilterfromosmpythontools.exporterimportCSVExporterimportmath readerPBFReader(hangzhou.osm.pbf,parse_geometryTrue)building_filterTagFilter(include{building:True})build_data[]forwayinreader.iter_ways():ifbuilding_filter.match(way)andway.is_area():geomway.geom# WGS84面积转换平方米area_m2geom.area*(111320**2)*math.cos(math.radians(geom.centroid.y))build_data.append({osm_id:way.id,name:way.tags.get(name,),building_type:way.tags.get(building,),floors:way.tags.get(building:levels,1),area_m2:round(area_m2,2)})CSVExporter(build_data,hangzhou_buildings_area.csv).save()print(建筑面积计算完成已导出CSV)案例4空间裁剪——按经纬度框提取局部OSM数据场景超大全国PBF文件只截取目标区县范围减少数据量fromosmpythontools.readerimportPBFReaderfromosmpythontools.exporterimportGeoJSONExporter readerPBFReader(china-latest.osm.pbf,skip_relationsTrue)# 北京海淀区边界 minlon,minlat,maxlon,maxlatbbox(116.28,39.9,116.38,40.0)# 空间过滤subsetlist(reader.filter_bbox(*bbox).iter_all_features())# 导出裁剪后数据GeoJSONExporter(subset,haidian_cut.geojson).save()print(f裁剪后要素总数{len(subset)})案例5路网分析——计算所有主干道总长度场景交通规划统计区域高速、主干道总长单位kmfromosmpythontools.readerimportPBFReaderfromosmpythontools.filterimportTagFilter readerPBFReader(guangzhou.osm.pbf)road_filterTagFilter(require_any[(highway,motorway),(highway,primary),(highway,secondary)])total_length_km0forwayinreader.iter_ways():ifroad_filter.match(way):lineway.geom# 经纬度距离换算千米length_degline.length lon_m111320*math.cos(math.radians(line.centroid.y))lat_m111320length_mlength_deg*((lon_mlat_m)/2)total_length_kmlength_m/1000print(f主干道总长度{round(total_length_km,2)}km)案例6POI分类统计——统计医院、学校、停车场数量场景城市配套设施量化分析输出统计报表fromosmpythontools.readerimportPBFReaderfromosmpythontools.statsimportTagCounter readerPBFReader(chengdu.osm.pbf,skip_relationsTrue)counterTagCounter()# 遍历所有点位自动统计标签fornodeinreader.iter_nodes():counter.count_tags(node)# 筛选配套设施统计stat{医院:counter.get_count((amenity,hospital)),小学:counter.get_count((amenity,school)),停车场:counter.get_count((amenity,parking)),银行:counter.get_count((amenity,bank))}fork,vinstat.items():print(f{k}{v}个)案例7OSM数据转Geopandas DataFrame做空间筛选场景结合GeoPandas做复杂空间叠加与行政区边界相交筛选POIfromosmpythontools.readerimportPBFReaderimportgeopandasasgpd readerPBFReader(wuhan.osm.pbf)# 直接转为GeoDataFramegdfreader.get_gdf()# 筛选所有公园面要素park_gdfgdf[(gdf[tag_natural]park)|(gdf[tag_leisure]park)]# 筛选面积大于5000㎡的公园park_gdf[area_m2]park_gdf.geometry.area*(111320**2)large_parkpark_gdf[park_gdf[area_m2]5000]# 保存shp文件large_park.to_file(wuhan_large_park.shp,encodingutf-8)print(f大型公园数量{len(large_park)})案例8批量清洗OSM脏数据删除无名称、无效坐标要素场景原始OSM存在大量空白要素预处理清洗fromosmpythontools.readerimportPBFReaderfromosmpythontools.exporterimportGeoJSONExporter readerPBFReader(nanjing_raw.osm.pbf)clean_features[]forfeatinreader.iter_all_features():tagsfeat.tags lon,latgetattr(feat,lon,None),getattr(feat,lat,None)# 过滤规则剔除无标签、坐标为空、无名称POIifnottags:continueiflonisNoneorlatisNoneornot(-180lon180and-90lat90):continue# POI必须包含名称标签ifisinstance(feat,type(reader.iter_nodes().__next__()))andnamenotintags:continueclean_features.append(feat)GeoJSONExporter(clean_features,nanjing_clean.geojson).save()print(f清洗前总量{len(list(reader.iter_all_features()))}清洗后{len(clean_features)})五、常见错误、报错原因与解决方案1. ModuleNotFoundError: No module named ‘osmpythontools’原因包名混淆pip安装包是osm-python-tools导入名osmpythontools大小写错误修复pipinstallosm-python-toolsimportosmpythontools# 正确导入2. PyosmiumImportError / libosmium动态库缺失原因Linux/Mac缺少系统底层osmium库Windows少见修复# Ubuntusudoaptinstalllibosmium2-dev# Macbrewinstallosmium-tool# 重装pyosmiumpipinstall--force-reinstall pyosmium3. MemoryError 读取超大PBF文件内存溢出原因默认一次性加载全部要素全国/省级PBF文件体积几十GB修复使用流式chunk分片跳过无关relation要素readerPBFReader(china.pbf,chunk_size5000,skip_relationsTrue)# 不要调用get_gdf()一次性全加载改用iter循环迭代4. Overpass API TimeoutError 请求超时原因查询范围过大、要素过多官方接口限制60s超时修复缩小bbox范围拆分多次查询本地下载PBF替代在线请求切换备用Overpass节点延长timeout参数OverpassClient(timeout90)5. shapely.geometry.GeometryError 几何构建失败原因OSM Way节点顺序错乱、首尾不闭合生成无效面缺失节点ID修复读取时增加容错捕获异常跳过破损要素try:geomway.geomexceptException:continue6. 导出Shapefile中文乱码原因shp默认编码gbk工具默认utf-8修复导出时指定编码参数gdf.to_file(output.shp,encodinggbk)7. Tag过滤无任何返回结果原因标签键值拼写错误OSM区分大小写Shop≠shop混淆node/way要素排查打印单个要素tags查看真实键值print(node.tags)8. 坐标面积计算数值异常巨大原因未做WGS84经纬度到平面米的换算直接用度数算面积修复使用案例3、5中的球面距离换算公式不可直接使用geom.area六、使用注意事项与最佳实践文件读取性能优化超大PBF强制开启skip_relationsTrue行政区、复合关系极少业务场景可直接跳过优先流式iter_nodes/iter_ways避免一次性转GDF占用内存读取阶段使用filter_bbox空间预过滤减少后续计算量。Overpass API使用规范禁止高频循环请求官方限制单IP每分钟请求次数批量数据优先本地PBF查询语句必须加[timeout:60]大范围查询拆分多个小bbox自定义UA标识便于接口管理员定位请求来源。OSM标签规范OSM标签全小写键值存在标准分类查询前参考官方wiki区分点(amenity)、面(building)、道路(highway)标签同标签不会同时存在于点和面。坐标系统一OSM原生EPSG:4326WGS84经纬度如需投影计算面积/长度推荐转UTM分带坐标系精度更高。数据存储选型小范围数据GeoJSON矢量分析Shapefile/Geopackage超大OSM源文件保留.osm.pbf压缩格式体积远小于xml。合规说明OSM数据开源协议ODbL商用必须标注OpenStreetMap数据源Overpass API禁止爬虫高频批量抓取大规模业务自行部署本地Overpass服务。异常容错规范原始OSM存在大量破损几何、缺失标签、无效坐标业务代码必须增加try-except捕获几何解析异常避免程序中断。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。
