open-buildings

用于处理开放建筑数据集的工具

• 免费软件：Apache软件许可协议2.0
• 文档： https://opengeos.github.io/open-buildings
• 创建者： Chris Holmes

简介

此仓库旨在提供一组有用的脚本，用于使用Cloud Native Geospatial格式获取和转换开放建筑数据集。最初重点是Google的Open Buildings数据集和Overture的建筑数据集。

大多数人最感兴趣的工具有get_buildings命令，它允许您向命令行界面提供一个GeoJSON文件，然后它会下载该区域的所有建筑，并以常见的GIS格式（GeoPackage、FlatGeobuf、Shapefile、GeoJSON和GeoParquet）输出。

该工具通过利用分区后的GeoParquet文件，使用DuckDB查询所需的内容。这一切都无需服务器 - 您的计算机上的DuckDB查询、过滤并下载您想要的行。目前，您可以查询两个数据集，它们位于Source Cooperative上，谷歌数据集请见此处，Overture数据集请见此处。CLI和其他脚本用于创建这些数据集，并添加了一些用于性能基准测试的附加功能。

这基本上是我的第一个Python项目，也是我的第一个开源项目。这要归功于ChatGPT，因为我不是Python程序员，而且总体上也不是一个优秀的程序员（专业编码大约两年，然后转向做很多其他事情）。所以代码可能并不出色，但迭代它很有趣，并且可能对其他人有用。欢迎贡献！我正在努力使问题跟踪器可访问，这样任何想尝试一些开源编码的人都可以加入。

安装

使用pip安装

pip install open-buildings

这将添加一个您可以使用的控制台命令行。如果它正常工作，则

ob

会打印出帮助信息。然后您就可以运行CLI（下载1.json）

ob tools get_buildings 1.json my-buildings.geojson --country_iso RW

您也可以直接在一行中流式传输json

curl https://data.source.coop/cholmes/aois/1.json | ob get_buildings - my-buildings.geojson --country_iso RW

功能

get_buildings

对于大多数人来说，主要的工具是get_buildings。它查询GeoJSON提供的完整全球建筑数据集，并以常见的地理空间格式输出结果。完整的选项和说明可以在--help命令中找到。

% ob get_buildings --help
Usage: ob get_buildings [OPTIONS] [GEOJSON_INPUT] [DST]

  Tool to extract buildings in common geospatial formats from large archives
  of GeoParquet data online. GeoJSON input can be provided as a file or piped
  in from stdin. If no GeoJSON input is provided, the tool will read from
  stdin.

  Right now the tool supports two sources of data: Google and Overture. The
  data comes from Cloud-Native Geospatial distributions on
  https://source.coop, that are partitioned by admin boundaries and use a
  quadkey for the spatial index. In time this tool will generalize to support
  any admin boundary partitioned GeoParquet data, but for now it is limited to
  the Google and Overture datasets.

  The default output is GeoJSON, in a file called buildings.json. Changing the
  suffix will change the output format - .shp for shapefile .gpkg for
  GeoPackage, .fgb for FlatGeobuf and .parquet for GeoParquet, and .json or
  .geojson for GeoJSON. If your query is all within one country it is strongly
  recommended to use country_iso to hint to the query engine which country to
  query, as this  will speed up the query significantly (5-10x). Expect query
  times of 5-10 seconds for a queries with country_iso and 30-60 seconds
  without country_iso.

  You can look up the country_iso for a country here:
  https://github.com/lukes/ISO-3166-Countries-with-Regional-
  Codes/blob/master/all/all.csv If you get the country wrong you will get zero
  results. Currently you can only query one country, so if your query crosses
  country boundaries you should not use country_iso. In future versions of
  this tool we hope to eliminate the need to hint with the country_iso.

Options:
  --source [google|overture]  Dataset to query, defaults to Overture
  --country_iso TEXT          A 2 character country ISO code to filter the
                              data by.
  -s, --silent                Suppress all print outputs.
  --overwrite                 Overwrite the destination file if it already
                              exists.
  --verbose                   Print detailed logs with timestamps.
  --help                      Show this message and exit.

请注意，get_buildings操作不太稳健，可能有多种方法使其失败。#13用于跟踪，但如果您有任何问题，请通过问题跟踪器报告，以帮助我们改进。

我们希望消除提供iso_country以快速查询的需求，有关跟踪问题，请参阅#29。我们还希望添加更多建筑数据集，从Google-Microsoft Open Buildings by VIDA开始，有关更多信息，请参阅#26。

谷歌建筑处理

在CLI的谷歌部分有两个函数

• convert以输入单个CSV文件或从本地下载的谷歌建筑数据集的CSV文件目录。它可以写入GeoParquet、FlatGeobuf、GeoPackage和Shapefile，并使用DuckDB、GeoPandas或OGR处理数据。
• benchmark针对一个或多个不同格式和一个或多个不同过程运行convert命令，并报告每个过程所需的时间。

在219_buildings.csv（一个101MB的CSV文件）上运行benchmark的示例输出为

Table for file: 219_buildings.csv
╒═══════════╤═══════════╤═══════════╤═══════════╤═══════════╕
│ process   │ fgb       │ gpkg      │ parquet   │ shp       │
╞═══════════╪═══════════╪═══════════╪═══════════╪═══════════╡
│ duckdb    │ 00:02.330 │ 00:00.000 │ 00:01.866 │ 00:03.119 │
├───────────┼───────────┼───────────┼───────────┼───────────┤
│ ogr       │ 00:02.034 │ 00:07.456 │ 00:01.423 │ 00:02.491 │
├───────────┼───────────┼───────────┼───────────┼───────────┤
│ pandas    │ 00:18.184 │ 00:24.096 │ 00:02.710 │ 00:20.032 │
╘═══════════╧═══════════╧═══════════╧═══════════╧═══════════╛

每个命令后的--help中都可以找到完整的选项，我将它们放在这里以供参考

Usage: open_buildings convert [OPTIONS] INPUT_PATH OUTPUT_DIRECTORY

  Converts a CSV or a directory of CSV's to an alternate format. Input CSV's
  are assumed to be from Google's Open Buildings

Options:
  --format [fgb|parquet|gpkg|shp]
                                  The output format. The default is FlatGeobuf (fgb)
  --overwrite                     Whether to overwrite any existing output files.
  --process [duckdb|pandas|ogr]   The processing method to use. The default is 
                                  pandas.
  --skip-split-multis             Whether to keep multipolygons as they are
                                  without splitting into their component polygons.
  --verbose                       Whether to print detailed processing
                                  information.
  --help                          Show this message and exit.

Usage: open_buildings benchmark [OPTIONS] INPUT_PATH OUTPUT_DIRECTORY

  Runs the convert function on each of the supplied processes and formats,
  printing the timing of each as a table

Options:
  --processes TEXT      The processing methods to use. One or more of duckdb,
                        pandas or ogr, in a comma-separated list. Default is
                        duckdb,pandas,ogr.
  --formats TEXT        The output formats to benchmark. One or more of fgb,
                        parquet, shp or gpkg, in a comma-separated list.
                        Default is fgb,parquet,shp,gpkg.
  --skip-split-multis   Whether to keep multipolygons as they are without
                        splitting into their component polygons.
  --no-gpq              Disable GPQ conversion. Timing will be faster, but not
                        valid GeoParquet (until DuckDB adds support)
  --verbose             Whether to print detailed processing information.
  --output-format TEXT  The format of the output. Options: ascii, csv, json,
                        chart.
  --help                Show this message and exit.

警告 - 注意，--no-gpq目前实际上不起作用，请参阅https://github.com/opengeos/open-buildings/issues/4以跟踪。它始终设置为true，因此使用Parquet的DuckDB时间会被夸大（您可以在Python代码的全局变量中更改它）。请注意，ogr过程不与--skip-split-multis一起工作，因此只会报告非常少的耗时，因为它跳过了任何操作，请参阅https://github.com/opengeos/open-buildings/issues/5以跟踪。

格式说明

我主要关注GeoParquet和FlatGeobuf，它们是优秀的云原生地理格式。我包括GeoPackage和Shapefile主要是为了基准测试的目的。我认为GeoPackage对于Esri和其他一些不太愿意采用新格式的传统软件是个不错的选择。Shapefile在这个用例中简直就是垃圾——它无法处理大于4GB的文件，而且许多来源的S2 Google Building CSV文件都大于这个大小，所以它对于翻译来说没有用。字段名称的截断也很烦人，因为CSV文件没有尝试创建简短的名字（也不应该这样做，限制太愚蠢了）。

GeoPackage与DuckDB配合特别慢，它可能存在一些bug。但与Pandas和OGR配合得很好。

处理注意事项

当我处理谷歌建筑数据集的V2版本时，我主要使用GeoPandas完成了大部分初步工作，它非常棒，拥有最好的GeoParquet实现。但是数据量太大，使得内存处理变得不可行。我最终使用了PostGIS，这是一个相当不错的工具，但接近这个过程结束时，我发现DuckDB，它的速度和内存管理能力让我印象深刻。所以对于这个工具，我主要关注这两个。

请注意，目前DuckDB的fgb、gpkg和shp输出不包含投影信息，所以如果你想使用输出，则需要运行ogr2ogr。听起来这个问题可能很快就会得到解决，所以我不会添加一个包含ogr转换的步骤。

OGR是后来添加的，但到目前为止还没有实现分割多边形这一关键步骤，因为它只是使用ogr2ogr作为子进程，我还没有找到一种从CLI（尽管GDAL/OGR可能存在这样的方法——请告诉我）实现这一功能的方法。要使用它进行基准测试，你需要做--skip-split-multis，否则它的运行时间将为0（除了Shapefile，因为它不会区分多边形和普通多边形）。我希望添加这一功能，并使其与其他工具相当，这可能意味着使用Fiona。但看起来这可能会影响性能，因为Fiona不使用GDAL/OGR列导向API。

代码定制

你可以在Python代码中设置3个作为全局变量的选项，但目前它们还不是CLI选项。这些是

• RUN_GPQ_CONVERSION - 是否让DuckDB默认运行的GeoParquet通过gpq处理，这会增加很多处理时间。这使得DuckDB的处理输出比如果DuckDB原生写入GeoParquet元数据要慢，我认为这可能是他们的路线图之一。所以这可能会成为最快的基准时间。在代码中，你可以将RUN_GPQ_CONVERSION在Python代码中设置为false，如果你想了解它。在上面的基准测试中，没有在DuckDB Parquet输出上运行gpq转换的Parquet运行时间为0.76秒。
• PARQUET_COMPRESSION - 用来对Parquet进行编码的压缩方式。请注意，并非所有进程都支持所有压缩选项，而且当前的OGR转换器也忽略了此选项。
• SKIP_DUCK_GPKG - 是否在DuckDB上跳过GeoPackage转换选项，因为它运行起来要花费很长时间。

贡献

欢迎所有贡献，我喜欢运行开源项目。我明显还在学习Python编程，所以对糟糕的代码没有评判。我很高兴从别人那里学习更好的代码。请自由地参与问题，创建新的，取一个，或者提交一个PR。有很多事情可以添加。如果你是编程新手，请不要犹豫在讨论中询问基本问题。