# OSM Export Tool
This project is in a usable state on Linux and Mac. The current [Export Tool web service](https://export.hotosm.org) repository is at [hotosm/osm-export-tool](https://github.com/hotosm/osm-export-tool/tree/master/ops).
## Motivation
This program filters and transforms OpenStreetMap data into thematic, tabular GIS formats.
Filtering of features is specified via SQL embedded in a YAML mapping file, for example:
```
buildings_with_addresses: # creates a thematic layer called "buildings_with_addresses"
types:
- polygons
select:
- building
- height
- addr:housenumber
where:
- building = 'yes' and addr:housenumber IS NOT NULL
```
It can also create files in non-tabular formats such as those for Garmin GPS devices or the OSMAnd Android app. (coming soon)
## Installation
* install via `pip install osm-export-tool`. Python 3 and a working GDAL installation are required. GDAL can be installed via Homebrew on Mac or the `ubuntugis` PPAs on Ubuntu.
PyOsmium is used to read OSM files and GDAL/OGR is used to write GIS files, so this program should be reasonably fast and light on memory. There is a built-in OSM reader available for GDAL/OGR, but this program is much more flexible.
This library will not automatically install GDAL because it needs to match the version on your system. You will need to separately run `pip install GDAL==2.3.2` (change 2.3.2 to match `gdalinfo --version`)
## Running with Docker
If you want to avoid installing the right version of GDAL on your system you can run the program as a docker container instead.
To build the docker image, use the following command.
```
docker build -t osm-export-tool .
```
To run the tool as a container, using your current directory as working directory, use the following command.
```
docker run -it --rm -v $(pwd):/work osm-export-tool INPUT_FILE.pbf OUTPUT_NAME
```
## Example usage
```
osm-export-tool INPUT_FILE.pbf OUTPUT_NAME
```
will create OUTPUT_NAME.gpkg.
All the below flags are optional.
* -m, --mapping : specify a mapping YAML. Defaults to `osm_export_tool/mappings/defaults.yaml`, which is a very broad selection of OSM tags ported from the [imposm3 defaults](https://github.com/omniscale/imposm3/blob/master/example-mapping.yml).
* `-f, --formats` : a comma-separated list of formats such as `gpkg,shp`. Defaults to just gpkg.
* `--omit-osm-ids`: By default, every table will have an `osm_id` column. Relation IDs are negative.
* `--clip <file>`: either a .poly or GeoJSON file.
* The GeoJSON must be either a Polygon or MultiPolygon geometry, or a FeatureCollection with one Polygon or MultiPolygon feature.
* Clipping is performed by Shapely and can be slow. It is recommended to filter the input PBF with a tool like [osmium-tool](https://github.com/osmcode/osmium-tool).
## YAML Mapping
* SQL statements must be comparisons of keys to constants with the key first.
* Valid examples:
* `height > 20`
* `amenity='parking' OR (building = 'yes' and height > 5)`
* Invalid examples:
* `20 < height`
* `building > height`
* More examples can be found in the [mappings directory](osm_export_tool/mappings).
* if the `types` key is omitted, it defaults to `points`, `lines` and `polygons`.
* At least one tag is required as a child of the `select` key.
* If the `where` key is omitted, it defaults to choosing all features where any of the `select`ed keys are present.
* if `where` is a list of SQL, it is equivalent to joining each SQL in the list with `OR`.
## Output formats
1. OGC GeoPackage (gpkg)
* This is the default export format, and the most flexible for modern GIS applications.
* tables will be created with the wkbUnknown geometry type, which allows heterogeneous geometry types.
2. Shapefile (shp)
* Each layer and geometry type is a separate .SHP file. This is because each .SHP file only supports a single geometry type and column schema.
3. KML (kml)
* Each layer and geometry type is a separate .KML file. This is because the GDAL/OGR KML driver does not support interleaved writing of features with different geometry types.
4. Maps.ME (coming soon)
5. OsmAnd (coming soon)
6. Garmin (coming soon)
Raw data
{
"_id": null,
"home_page": "https://github.com/hotosm/osm-export-tool-python",
"name": "osm-export-tool-python",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Hot Tech Team",
"author_email": "sysadmin@hotosm.org",
"download_url": "https://files.pythonhosted.org/packages/97/43/42c6e8e02685f47569e87d27b40aa33104ad0a9b1fc6816b9f9ee80ec2a6/osm-export-tool-python-2.0.16.tar.gz",
"platform": null,
"description": "# OSM Export Tool\n\nThis project is in a usable state on Linux and Mac. The current [Export Tool web service](https://export.hotosm.org) repository is at [hotosm/osm-export-tool](https://github.com/hotosm/osm-export-tool/tree/master/ops).\n\n## Motivation\n\nThis program filters and transforms OpenStreetMap data into thematic, tabular GIS formats. \nFiltering of features is specified via SQL embedded in a YAML mapping file, for example:\n```\nbuildings_with_addresses: # creates a thematic layer called \"buildings_with_addresses\"\n types:\n - polygons\n select:\n - building\n - height\n - addr:housenumber\n where:\n - building = 'yes' and addr:housenumber IS NOT NULL\n```\n\nIt can also create files in non-tabular formats such as those for Garmin GPS devices or the OSMAnd Android app. (coming soon)\n\n## Installation\n\n* install via `pip install osm-export-tool`. Python 3 and a working GDAL installation are required. GDAL can be installed via Homebrew on Mac or the `ubuntugis` PPAs on Ubuntu.\n\nPyOsmium is used to read OSM files and GDAL/OGR is used to write GIS files, so this program should be reasonably fast and light on memory. There is a built-in OSM reader available for GDAL/OGR, but this program is much more flexible.\n\nThis library will not automatically install GDAL because it needs to match the version on your system. You will need to separately run `pip install GDAL==2.3.2` (change 2.3.2 to match `gdalinfo --version`)\n\n## Running with Docker\n\nIf you want to avoid installing the right version of GDAL on your system you can run the program as a docker container instead.\n\nTo build the docker image, use the following command.\n\n```\ndocker build -t osm-export-tool .\n```\n\nTo run the tool as a container, using your current directory as working directory, use the following command.\n\n```\ndocker run -it --rm -v $(pwd):/work osm-export-tool INPUT_FILE.pbf OUTPUT_NAME\n```\n\n## Example usage\n\n```\nosm-export-tool INPUT_FILE.pbf OUTPUT_NAME\n```\nwill create OUTPUT_NAME.gpkg.\n\nAll the below flags are optional.\n\n* -m, --mapping : specify a mapping YAML. Defaults to `osm_export_tool/mappings/defaults.yaml`, which is a very broad selection of OSM tags ported from the [imposm3 defaults](https://github.com/omniscale/imposm3/blob/master/example-mapping.yml).\n* `-f, --formats` : a comma-separated list of formats such as `gpkg,shp`. Defaults to just gpkg. \n* `--omit-osm-ids`: By default, every table will have an `osm_id` column. Relation IDs are negative. \n* `--clip <file>`: either a .poly or GeoJSON file.\n\t* The GeoJSON must be either a Polygon or MultiPolygon geometry, or a FeatureCollection with one Polygon or MultiPolygon feature.\n\t* Clipping is performed by Shapely and can be slow. It is recommended to filter the input PBF with a tool like [osmium-tool](https://github.com/osmcode/osmium-tool).\n\n## YAML Mapping\n\n* SQL statements must be comparisons of keys to constants with the key first.\n\t* Valid examples:\n\t\t* `height > 20`\n\t\t* `amenity='parking' OR (building = 'yes' and height > 5)`\n\t* Invalid examples:\n\t\t* `20 < height`\n\t\t* `building > height`\n* More examples can be found in the [mappings directory](osm_export_tool/mappings).\n* if the `types` key is omitted, it defaults to `points`, `lines` and `polygons`.\n* At least one tag is required as a child of the `select` key.\n* If the `where` key is omitted, it defaults to choosing all features where any of the `select`ed keys are present.\n* if `where` is a list of SQL, it is equivalent to joining each SQL in the list with `OR`.\n\n## Output formats\n\n1. OGC GeoPackage (gpkg)\n* This is the default export format, and the most flexible for modern GIS applications. \n* tables will be created with the wkbUnknown geometry type, which allows heterogeneous geometry types.\n\n2. Shapefile (shp)\n* Each layer and geometry type is a separate .SHP file. This is because each .SHP file only supports a single geometry type and column schema. \n\n3. KML (kml)\n* Each layer and geometry type is a separate .KML file. This is because the GDAL/OGR KML driver does not support interleaved writing of features with different geometry types. \n\n4. Maps.ME (coming soon)\n\n5. OsmAnd (coming soon)\n\n6. Garmin (coming soon)\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Convert OpenStreetMap data into GIS and mobile mapping file formats.",
"version": "2.0.16",
"project_urls": {
"Homepage": "https://github.com/hotosm/osm-export-tool-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "974342c6e8e02685f47569e87d27b40aa33104ad0a9b1fc6816b9f9ee80ec2a6",
"md5": "e60595cbb3f389537b74c362dda11c05",
"sha256": "54799949f491817cb68339defe69d78858763409622543e9d48cbbdd9e2df86c"
},
"downloads": -1,
"filename": "osm-export-tool-python-2.0.16.tar.gz",
"has_sig": false,
"md5_digest": "e60595cbb3f389537b74c362dda11c05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26973,
"upload_time": "2024-02-12T06:48:41",
"upload_time_iso_8601": "2024-02-12T06:48:41.613794Z",
"url": "https://files.pythonhosted.org/packages/97/43/42c6e8e02685f47569e87d27b40aa33104ad0a9b1fc6816b9f9ee80ec2a6/osm-export-tool-python-2.0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 06:48:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hotosm",
"github_project": "osm-export-tool-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "osmium",
"specs": [
[
"~=",
"2.15.2"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"~=",
"2.4.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"~=",
"5.1.1"
]
]
},
{
"name": "shapely",
"specs": [
[
"~=",
"1.6.4"
]
]
},
{
"name": "requests",
"specs": [
[
"~=",
"2.26.0"
]
]
},
{
"name": "landez",
"specs": [
[
"~=",
"2.5.0"
]
]
},
{
"name": "deepdiff",
"specs": [
[
"~=",
"5.8.1"
]
]
}
],
"lcname": "osm-export-tool-python"
}
JSON
