You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+165-57
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,24 @@
1
-
# OSM Building Extractor
2
-
3
-
*Under Construction*
1
+
# OSM Ox
4
2
5
3
A tool for extracting locations and features from Open Street Map (OSM) data.
6
4
5
+
## Why?
6
+
7
+
We use Osmox to extract locations from OSM for city or national scale agent based models. This tends to focus on extracting buildings and their likelly usages, for example `homes`, `schools`, `medical facilities` and `places of work`. But can also be abstracted to other objects such as parks or land use.
8
+
9
+
Under the hood Osmox is a collection of labelling and GIS type operations:
10
+
11
+
- filtering
12
+
- activity labelling
13
+
- simple spatial activity inference
14
+
- feature extraction (such as floor areas)
15
+
- filling missing data
16
+
17
+
Assembled togther they form part of our wider pipeline. But as a stadalone tool, Osmox is useful for extracting insights from OSM in a hihly reproducible manner.
Extract `home`, `work`, `education`, `shop` and various other activity locations ("facilities") for the Isle of Man:
33
+
34
+
`osmox run configs/example.json example_data/isle-of-man.osm example -crs "epsg:27700"` (paths given from osmox project root)
35
+
36
+
After about 30 seconds you should find locations for the extract facilities in the specified `example` directory. Each facility includes a number of facilities as per the config:
Outputs are written as WGS 84 (epsg:4326), so that they can be quickly inspected via [kepler](https://kepler.gl) or equivalent:
67
+
68
+
69
+
*^ Isle of Man facility `floor_area` feature. Approximated based on polygon areas and floor labels or sensible defaults.*
70
+
71
+
72
+
*^ Isle of Man `activities` feature. For simulations we use this information to control what agents can do where, but this is also a good disagregate proxy for land-use. In this example, blue areas are residential, orange commercial and brown is other work places.*
73
+
74
+
75
+
*^ Isle of Man `distance_to_nearest_transit`. See that other distances are available, such as distance to nearest education.*
76
+
77
+
## Osmox Run
19
78
20
79
`osmox run <CONFIG_PATH> <INPUT_PATH> <OUTPUT_PATH>` is the main entry point for OSMOX:
21
80
@@ -30,11 +89,11 @@ Options:
30
89
31
90
```
32
91
33
-
We describe configs below. The `<INPUT_PATH>` should point to an OSM map dataset (for example`osm.pbf`). The `<OUTPUT_PATH>` should point to an output directory.
92
+
We describe configs below. The `<INPUT_PATH>` should point to an OSM map dataset (`osm`(xml) and`osm.pbf` are supported). The `<OUTPUT_PATH>` should point to an exiting or new output directory.
34
93
35
94
## Configs
36
95
37
-
Configs are important. So we provide some examples in `mc/configs` and a validation method:
96
+
Configs are important. So we provide some examples in `mc/configs` and a validation method for when you start editing or building your own configs:
38
97
39
98
```{sh}
40
99
osmox validate <CONFIG PATH>
@@ -76,7 +135,7 @@ INFO:osmox.main:Done.
76
135
77
136
Once complete you will find osmox has created one or two output `.geojson` in the specified `<OUTPUT_PATH>`. If you have specified a crs, you will find your outputs as both this crs and as epsg4326.
78
137
79
-
We generally refer to the outputs collectively as `facilities` and the properties as `features`. Note that each facility has a unique id, a bunch of features (depending on the configuration) and a point geometry. In the case of areas or polygons, such as buildings, the point represents the centroid. Measured features such as `floor_area` and `distance_to_nearest_X` are measured in the specified crs. Generally we assume you will specify a grid crs such as 27700 for the UK.
138
+
We generally refer to the outputs collectively as `facilities` and the properties as `features`. Note that each facility has a unique id, a bunch of features (depending on the configuration) and a point geometry. In the case of areas or polygons, such as buildings, the point represents the centroid.
80
139
81
140
```{geojson}
82
141
{
@@ -101,12 +160,16 @@ We generally refer to the outputs collectively as `facilities` and the propertie
101
160
}
102
161
```
103
162
104
-
## Definitions
163
+
In the quick start demo, we specified the coordinate reference system as `epsg:27700` (this is the default, but we specified it for visibility) so that distance and area based features would have sensible units (metres in this case). If extracting data from other areas we would encourage using the relevant grid crs for that area.
164
+
165
+
## Configuration
166
+
167
+
### Definitions
105
168
106
169
**OSMObjects** - objects extracted from OSM. These can be points, lines or polygons. Objects have features.
107
170
**OSMFeatures** - OSM objects have features. Features typically include a key and value based on the [OSM wiki](https://wiki.openstreetmap.org/wiki/Map_features).
108
171
109
-
## Primary Functionality
172
+
###Primary Functionality
110
173
111
174
The primary use case for osmox is for extracting a representation of places where people can do various activities ('education' or 'work' or 'shop' for example). This is done applying a configured mapping to OSM tags:
112
175
@@ -119,17 +182,19 @@ The primary use case for osmox is for extracting a representation of places wher
119
182
"kindergarden",
120
183
"school",
121
184
"university",
122
-
"college"
185
+
"college",
186
+
"yes"
123
187
]
124
-
}
188
+
}, ...
125
189
}
126
190
```
127
191
128
192
-**Activity Map** object activities based on OSM tags (eg: this building type 'university' is an education facility). Activity mapping is based on the same `config.json`, but we add a new section `activity_mapping`. For each OSMTag (a key such as `building` and a value such as `hotel`,) we map a list of activities:
129
193
130
194
```{json}
131
195
{
132
-
"activity_mapping": {
196
+
...
197
+
"activity_mapping": {
133
198
"building": {
134
199
"hotel": ["work", "visit"],
135
200
"residential": ["home"]
@@ -138,20 +203,39 @@ The primary use case for osmox is for extracting a representation of places wher
138
203
}
139
204
```
140
205
206
+
Because an OSM tag key is often sufficient to make an activity mapping, we allow use of `*` as "all":
207
+
208
+
```{json}
209
+
{
210
+
...
211
+
"activity_mapping": {
212
+
...
213
+
"office": {
214
+
"*": ["work"]
215
+
}
216
+
}
217
+
}
218
+
```
219
+
220
+
Note that the filter controls the final objects that get extracted but that the activity mapping is more general. It is typical to map tags that are not included in the filter because these can be used by subsequent steps (such as inference) to assign activities where otherwise useful tags aren't included. There is no harm in over specifying the mapping.
221
+
141
222
These configs get looong - but we've supplied some full examples in the project.
142
223
143
-
## Spatial Inference
224
+
###Spatial Inference
144
225
145
-
Because OSMObjects do not always contain useful tags, we also infer object tags based on spatial operations with surrounding tags. The most common use case for this are building objects that are simply tagged as `building:yes`. We use the below logic to infer useful tags, such as 'building:shop' or 'building:residential'.
226
+
Because OSMObjects do not always contain useful tags, we also infer object tags based on spatial operations with surrounding tags.
146
227
147
-
-**Contains.** - If an OSMObject has no activity mappable tags (eg `building:yes`), tags are assigned based on the tags of objects that are contained within. For example, a building that contains an `amenity:shop` point is then tagged as `amenity:shop`.
228
+
The most common use case for this is building objects that are simply tagged as `building:yes`. We use the below logic to infer useful tags, such as 'building:shop' or 'building:residential'.
229
+
230
+
-**Contains.** - If an OSMObject has no mappable tags (eg `building:yes`), tags are assigned based on the tags of objects that are contained within. For example, a building that contains an `amenity:shop` point is then tagged as `amenity:shop`.
148
231
-**Within.** - Where an OSM object *still* does not have a useful OSM tag - tags are assigned based on the tags of objects that contain the object. The most common case is for untagged buildings to be assigned based on landuse objects. For example, a building within a `landuse:residential` area will be assigned with `landuse:residential`.
149
232
150
233
In both cases we need to add the OSMTags we plan to use to the `activity_mapping` config, eg:
151
234
152
235
```{json}
153
236
{
154
-
"activity_mapping": {
237
+
....
238
+
"activity_mapping": {
155
239
"building": {
156
240
"hotel": ["work", "visit"],
157
241
"residential": ["home"]
@@ -169,81 +253,105 @@ In both cases we need to add the OSMTags we plan to use to the `activity_mapping
169
253
-**Default.** - Where an OSMObject *still* does not have a useful OSM tag, we can optionally apply defaults. Again, these are set in the config:
170
254
171
255
```{json}
172
-
"default_activities": ["home"]
256
+
{
257
+
...
258
+
"default_tags": [["building", "residential"]],
259
+
...
260
+
}
173
261
```
174
262
175
-
## Feature Extraction
263
+
###Feature Extraction
176
264
177
265
Beyond simple assignment of human activities based on OSM tags, we also support the extraction of other features:
OSMOX also supports calculating distance to nearest features based on object activities. For example we can extract nearest distance to `transit`, `education`, `shop` and `medical` by adding the following to the config:
Note that the selected activities are based on the activity mapping config. Any activities should therefore be included in the activity mapping part of the config. You can use `osmox validate <CONFIG PATH>` to check if a config is correctly configured.
198
295
199
-
## Fill Missing Activities
296
+
###Fill Missing Activities
200
297
201
-
We have noted that it is not uncommon for some small urban areas to not have building objects, but to have an appropriate landuse area tagged as 'residential'.
298
+
We have noted that it is not uncommon for some small areas to not have building objects, but to have an appropriate landuse area tagged as 'residential'.
202
299
203
-
We therefore provide a general solution for filling such areas with a grid of objects. This fill method only fills areas that to not have the required activity.
300
+
We therefore provide a very ad-hoc solution for filling such areas with a grid of objects. This fill method only fills areas that do not have the required activities already within them.
204
301
205
302
For example, given an area tagged as `landuse:residential` by OSM, that does not contain any object of activity type `home`, the fill method will add a grid of new objects tagged `building:house`. The new objects will also have activity type `home`, size `10 by 10` and be spaced at `25 by 25`:
321
+
*^ Example Isle of Man activity filling in action for a residential area without building locations.*
241
322
242
323
Note that the selected activities are based on the activity mapping config. Any activities should therefore be included in the activity mapping part of the config. You can use `osmox validate <CONFIG PATH>` to check if a config is correctly configured.
0 commit comments