giscience / ohsome2label

Historical OpenStreetMap Objects to Machine Learning Training Samples

ohsome2label

README | English | 简体中文 |

Historical OpenStreetMap Objects to Machine Learning Training Samples

The ohsome2label offers a flexible label preparation tool for satellite machine learning applications.

• Customized Object - user-defined geospatial objects are retrieved and extracted from OpenStreetMap full-history data by requesting ohsome web API.
• Various Satellite Images - user could downloads corresponding satellite imagery tiles from different data providers.
• Seamless Training - object labels together with images would be packaged and converted to Microsoft COCO .json format to provide a seamless connection to further model training.
• OSM Quality Measurement (currently under developing) - historical OpenStreetMap analysis allows us to provide exclusive intrinsic quality measurements in addition to the customized training samples.

The output package could support directly training of popular machine learning tasks (e.g., object detection, semantic segmentation, instance segmentation etc,).

Package Dependencies

• python 3.6

Installation

pip install ohsome2label

or clone the Github repo and install it locally

pip install --editable .

Configuration

We believe you are familiar with OpenStreetMap, otherwise you are highly recommended to check this out since OpenStreetMap contains a huge types of geographical data, ranging from highways to different buildings. Before you start playing around with ohsome2label, you have to specify parameters, such as the target bounding box or the geospatial object you are looking for.

Here is a example for config.yaml file.

project:
  name: HD_landuse
  workspace: ./example_result
  project_time: 2020-05-18
  task: segmentation

osm:
  api: ohsome
  url: https://api.ohsome.org/v1/elements/geometry
  bboxes: [8.625,49.3711,8.7334,49.4397]
  tags:
    - {'label': 'urban', 'key': 'landuse', 'value': 'residential'}
    - {'label': 'urban', 'key': 'landuse', 'value': 'garages'}
    - {'label': 'industry', 'key': 'landuse', 'value': 'railway'}
    - {'label': 'industry', 'key': 'landuse', 'value': 'industrial'}

  timestamp: 2019-10-20
  types: polygon

image:
  img_api: bing
  img_url: http://t0.tiles.virtualearth.net/tiles/a{q}.png?g=854&mkt=en-US&token={token}
  api_token : 'YOUR OWN API TOKEN'
  zoom: 16

Scheme	Parameter	Description
project	name	The title of project you want to have.
project	workspace	The relative path your want to store the project output.
project	project_time	The created time of the project.
project	task	The type of machine learning tasks you would like to use afterwards. This could be object detection, segmentation.
osm	api	The OSM data query API, which could be ohsome, overpass.
osm	url	The corresponding URL for OSM data query API , which could be https://api.ohsome.org/v1/elements/geometry, https://lz4.overpass-api.de/api/interpreter.
osm	bboxes	The box boundary of target area, which is given in form [xmin, ymin, xmax, ymin], x and y refer to longitude and latitude. Longitude ranges from -180 to 180, and latitude ranges from 0 to 90. The default map project is WGS84.
osm	tags	The target key and values pairs of OSM feature, where label could be defined by yourself and shared by several key-value paris. A valid OSM key is necessary, where OSM values could be empty means all values are included.
osm	timestamp	The timestamp of historical OSM data you want to retrieval. The date should be given in [year-month-day]
osm	types	The object types you are aimed at, which could be polygon, line.
image	image_api	The satellite imagery service you would like to use. Now bing,mapbox, sentinel are supported. Also, custom TMS is also supported
image	image_url	The url template of satellite imagery service you would like to use.
image	api_token	The API token should be applied individually by users. Please find the corresponding application pages as follows: bing, mapbox, sentinel
image	zoom	The zoom-in level of satellite imagery. This 'zoom level' would affect the spatial resolution in general.

Command line functions

Once the config.yaml is well prepared, now ohsome2label would help your to prepare your customized OSM training samples by using the following command line functions. Please notice, you could define your own config.yaml file for all command line functions, for instance ohsome2label --config PATH/OWN_config.yaml vector

Help

Check out the summary of ohsome2label command line function with the following command.

$ ohsome2label --help
-------------------------
Usage: ohsome2label [OPTIONS] COMMAND [ARGS]...

 Generate training label for deep learning via ohsomeAPI

Options:
 -v, --verbose
 --config PATH
 --schema PATH
 --help         Show this message and exit.

Commands:
 image      Download satellite image
 label      Generate tile
 printcfg   Print project config
 quality    Generate OSM quality figure
 vector     Download vector OSM data from ohsomeAPI
 visualize  Visualize of training samples

Vector

Download the historical OpenStreetMap vector data with the given timestamp by querying the ohsome API. The results is in geojson format.

$ ohsome2label vector
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------
Download OSM historical data into dir:

.\path\to\workspace\other\raw

Label

The downloaded OpenStreetMap data together with the target objects would be labelled with specific zoom level. The label output also depends on different ML_task, for examples, object bounding boxes for object detection, object footprints for semantic segmentation, and instance footprint for instance segmentation.

$ ohsome2label label
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------

Tile the OSM data into given zoom level: 14

24it [00:00, 119.13it/s]

Image

Based on the previous label results, user could download the correspondingly satellite image for training.

Templates of image_url for different image_api:

• For bing: http://t0.tiles.virtualearth.net/tiles/a{q}.png?g=854&mkt=en-US&token={token}
• For mapbox: http://a.tiles.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.jpg?access_token={token}
• For sentinel: https://services.sentinel-hub.com/ogc/wms/{token}?showLogo=false&service=WMS&request=GetMap&layers=ALL-BAND&styles=&format=image%2Ftiff&transparent=1&version=1.1.1&maxcc=20&time=2015-01-01%2F2020-01-01&priority=mostRecent&height=256&width=256&srs=EPSG%3A3857&bbox={bbox}
• For custom URL: only support x, y, z and token in image_url

$ ohsome2label image 
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------
Start download satellite image!
100%|███████████████████████████████████| 24/24 [00:03<00:00,  6.57it/s]

Visualization

Visualize example satellite image together with OpenStreetMap features. Requires the /tile folder from the previous step. Accepts an additional flag:

• -n or --num: integer number of examples images to create per class. (default: 50)
• -t or --type: str the visualization type should be selected from combined or overlay (default: combined)

$ ohsome2label visualize -n 10
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------
start visualize 10 pictures!

Visualization mode: combined the satellite image with OpenStreetMap features.

With the default Heidelberg example, you would get the following training samples for the landuse classes: urban and industry.

Quality

Generate intrinsic quality indications based on Historic OSM data, which give a insight into the intrinsic quality of OSM training samples.

ohsome2label quality
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------
100%|███████████████████████████████████| 3/3 [01:48<00:00, 36.24s/it]

As a example for the default Heidelberg example, we hard-code three intrinsic quality indications: 1. density of OSM polygon features areas (area of polygon divided by the total area in square-kilometers); 2.density of OSM polygon features numbers (number of elements divided by the total area in square-kilometers); 3.density of OSM users (number of contributors divided by the total area in square-kilometers). In general, if the density of OSM features are getting stable, this could refer to a relatively complete mapping status. In the future, one may develop more sophisticated indicators based on specific “fitness-for-use” purposes.

Print the configuration

Users could use the print configuration to check their configuration regarding the project.

$ ohsome2label printcfg
-------------------------
Options:
  -v, --verbose
  --config PATH
  --schema PATH
-------------------------
# # # # # # # # # # #  CONFIG  # # # # # # # # # # #
{'_config': {'image': {'api_token': '', 'img_api': 'bing', 'zoom': 16},
             'osm': {'api': 'ohsome',
                     'bboxes': [8.625, 49.3711, 8.7334, 49.4397],
                     'tags': [{'key': 'landuse',
                               'label': 'urban',
                               'value': 'residential'},
                              {'key': 'landuse',
                               'label': 'urban',
                               'value': 'garages'},
                              {'key': 'landuse',
                               'label': 'industry',
                               'value': 'railway'},
                              {'key': 'landuse',
                               'label': 'industry',
                               'value': 'industrial'}],
                     'timestamp': datetime.date(2019, 10, 20),
                     'types': 'polygon',
                     'url': 'https://api.ohsome.org/v1/elements/geometry'},
             'project': {'name': 'HD_landuse',
                         'project_time': datetime.date(2020, 5, 18),
                         'task': 'segmentation',
                         'workspace': './example_result'}}}

# # # # # # # # # # # #  END  # # # # # # # # # # # #

Citations

Wu, Zhaoyan, Li, Hao, & Zipf, Alexander. (2020).From Historical OpenStreetMap data to customized training samples for geospatial machine learning. In proceedings of the Academic Track at the State of the Map 2020 Online Conference, July 4-5 2020. DOI: http://doi.org/10.5281/zenodo.3923040

Raifer, M., Troilo, R., Kowatsch, F., Auer, M., Loos, L., Marx, S., Przybill, K., Fendrich, S., Mocnik, F.-B.& Zipf, A. (2019): OSHDB: a framework for spatio-temporal analysis of OpenStreetMap history data.Open Geospatial Data, Software and Standards 2019 4:3. https://doi.org/10.1186/s40965-019-0061-3

Acknowledgements

The package relies heavily on the OpenStreetMap History Database and the ohsome API. The idea of this package has been inspired by the nice work of label-maker. Last but not least, we would like to thanks for the contributions of OpenStreetMap volunteer to make this happen.

• OpenStreetMap historical data used that contains ODbL 1.0 licensed OSM history data for dates after September 12, 2012 and CC-BY-SA 2.0 licensed OSM history data for all dates prior to September 12, 2012.

ohsome2label's Issues

Mistake in building detection config.yaml

The config.yaml on contains the YAML code:

project:
  name: kalola
  workspace: ./tanzania
  project_time: 2021-3-25
  task: object detection

osm:
  api: ohsome
  url: https://api.ohsome.org/v1/elements/geometry
  bboxes: [32.463226318359375, -5.032122934090069, 32.48931884765625, -5.019810836520875]

tags:
  - {'label': 'building', 'key': 'building', 'value': ''}
  timestamp: 2020-10-20
  types: polygon

image:
  img_api: bing
  img_url: http://t0.tiles.virtualearth.net/tiles/a{q}.png?g=854&mkt=en-US&token={token}
  api_token : 'REPLACE BY YOURTOKEN'
  zoom: 18

But tags should be a subkey of osm:

project:
  name: kalola
  workspace: ./tanzania
  project_time: 2021-3-25
  task: object detection

osm:
  api: ohsome
  url: https://api.ohsome.org/v1/elements/geometry
  bboxes: [32.463226318359375, -5.032122934090069, 32.48931884765625, -5.019810836520875]
  tags:
    - {'label': 'building', 'key': 'building', 'value': ''}
    timestamp: 2020-10-20
    types: polygon

image:
  img_api: bing
  img_url: http://t0.tiles.virtualearth.net/tiles/a{q}.png?g=854&mkt=en-US&token={token}
  api_token : 'REPLACE BY YOURTOKEN'
  zoom: 18

ERROR ConnectionError when requesting from the server

It has been reported that one could get the following error:

when running ohsome2label vector from the server.

We found out this issue was related to the security certificate check in Python requests, especially via the server traffic.

One easy solution/walkaround is to change the following code in your repo:

ohsome2label/ohsome2label/utils.py

Line 22 in 5921866

r = requests.get(api, params)

just to disable the verification, while a better solution should be considered in the future:

r = requests.get(api, params, verify=False)

walkthrough setup.md tf version and geopandas installation error and fix.

While trying to setup training env, I came across the following error -

• python3.6 does not support tf v1.*
• geopandas had some broken file link to gdal (https://stackoverflow.com/questions/54734667/error-installing-geopandas-a-gdal-api-version-must-be-specified-in-anaconda).

The following two steps helped me go through these errors -

• use it to initiate an env with python 2.7 version
  virtualenv -p python2.7 venv
• install the following two packages while installing Install System Level Libraries
  apt-get install libgeos-dev
apt-get install libgdal-dev

Note that for ohsome2label we still need python3.6 version. One can use different virenv for that.

Hope it helps!

Copy-paste error in readme

Hey, I just flew over your readme and it seems like there happened some sort of formatting or copy-past error in your readme. In the section about "Command line functions", it seems the text that follows is also somehow formatted as a headline and appears twice.

Don't know how to proceed with "adding tf_record_from_coco.py to the ./ohsome2label/ directory"

I am finding the walkthrough for satellite image building detection quite confusing.

I am using a Google Colab instace to test it out.

I have installed the package and then downloaded the tanzania dataset

!pip install ohsome2label
!rm -r tanzania
!ohsome2label --config config.yaml --schema schema.yaml vector
!ohsome2label --config config.yaml --schema schema.yaml label
!ohsome2label --config config.yaml --schema schema.yaml image
!ohsome2label --config config.yaml --schema schema.yaml visualize -t overlay

This works, I have the data downloaded & visualized properly.

But now the walkthrough says that I have to "Copy tf_record_from_coco.py from this repo to the ./ohsome2label/ directory". How can I do this? The package is installed somewhere in the system's native Python directory. Do I really have to go searching for where this package was installed in site-packages to add this file?

label erro with dev branch

the command of "ohsome2label label" with default config gives me the following error:

I think it is related to

ohsome2label/ohsome2label/label.py

Line 354 in 19f456c

list_path = os.path.join(workspace.other, "tile_list")

@wuzyzy could you maybe check the dev branch?

Buffering lines for segmentation

Hi there,

Great tool!

I'm using it to make some segmentation masks for land cover analysis. I notice that a significant drawback in segmentation mode is that almost all highway=* attributes are lines, not polygons. This means that they are left blank in the segmentation labels. Is there any way around this? Otherwise the labels have large gaps where all the roads are. Given that at higher zoom levels, roads are actually extended objects several pixels wide, it would be good to be able to label these. Example below:

Thanks!

Error in `ohsome2label image` command with Sentinel image from SentineHub

During the execution of the comand ohsome2label --config config\config.yaml image with the following file config.ymal:

project:
  name: TestSentinel
  workspace: ./Sentinel_result
  project_time: 2020-05-18
  task: segmentation

osm:
  api: ohsome
  url: https://api.ohsome.org/v1/elements/geometry
  bboxes: [8.625,49.3711,8.7334,49.4397]
  tags:
    - {'label': 'urban', 'key': 'landuse', 'value': 'residential'}
    - {'label': 'urban', 'key': 'landuse', 'value': 'garages'}
    - {'label': 'industry', 'key': 'landuse', 'value': 'railway'}
    - {'label': 'industry', 'key': 'landuse', 'value': 'industrial'}

  timestamp: 2019-10-20
  types: polygon

image:
  img_api: sentinel
  img_url: https://services.sentinel-hub.com/ogc/wms/{token}?showLogo=false&service=WMS&request=GetMap&layers=ALL-BAND&styles=&format=image%2Ftiff&transparent=1&version=1.1.1&maxcc=20&time=2015-01-01%2F2020-01-01&priority=mostRecent&height=256&width=256&srs=EPSG%3A3857&bbox={bbox}
  api_token : 'TOKEN'
  zoom: 14

It provided the error below. I never use the operator <<, so I'm not confident in fixing it. From the guide seems that n = 1 << int(tile.z) could fix it, but this will produce other errors.

  File "c:\users\stucchi\documents\github\ohsome2label\ohsome2label\tile.py", line 148, in top_left
    n = 1 << tile.z
TypeError: unsupported operand type(s) for <<: 'int' and 'str'

I used python 3.6.8 and shapely 1.7.1, the suggested version of shapely (1.6.4) is not working and provides multiple errors. The 1.7.1 works in the command vector and label.

shapely install in Windows

If you may use pycharm or other IDE in Windows, there might be error when installing shaply with pip.

The potential solution could be: conda install -c conda-forge shapely=1.6.4

requests.exceptions.ConnectionError

when running for large-sccale image download, one might come up with an requests.exceptions.ConnectionError

Error message:

requests.exceptions.ConnectionError: HTTPConnectionPool(host='t0.tiles.virtualearth.net', port=80): Max retries exceeded with url: /tiles/a12020330203220030.png?g=854&mkt=en-US&token=your_token(Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7ff69bf7ecf8>: Failed to establish a new connection: [Errno 110] Connection timed out',))
44%|███████████████████████ | 11394/26174 [15:14<19:45, 12.47it/s]

Potential solution:

add request status check and random sleep