Overview
Caribou is a Grasshopper plugin for parsing downloaded Open Street Map data into Rhino geometry. Caribou is currently in an beta state, but core functionality should be stable.
Features
- ✅ Windows and MacOS are both fully supported on Rhino 6, 7, and 8
- ✅ Very fast parsing of even very large files
- ✅ Data-rich GUI interface provided for understanding and filtering OSM metadata
- ✅ Parsing is performed asynchronously so Grasshopper remains responsive
- ✅ Parse multiple OSM files simultaneously with de-duplication of geometry
- ✅ Allows for querying for arbitrary data outside of the primary OSM features/sub-features taxonomy
- ✅ Outputs are tree-formatted and organised per data-type to allow for downstream filtering, tagging, baking, etc
Installation
Caribou is available to download via the Rhino Package Manager (search “Caribou”). If you are on Rhinoceros 6, note that the Package Manager needs to be loaded with the TestPackageManager
command.
When installing via the Package Manager, please ensure you fully restart all running copies of Rhinoceros after installing.
Setup and Use (Video)
Setup and Use (Instructions)
Downloading Open Street Map data
- Go to https://www.openstreetmap.org
- Locate the general area you wish to model and hit export, then manually select an area
- Click the OVERPASS API link to download the
xml
file
Note that Caribou can parse and combine multiple xml
downloads. If you are constrained by the maximum export area, you can use multiple crops/downloads to increase coverage of your site. Ensure there are clear overlaps between your crops - Caribou will handle de-duplication of any overlapping geometry.
Parsing the data into Grasshopper Geometry
Caribou’s Extract Nodes
and Extract Ways
components each process two distinct types of Open Street Map data.
- Nodes become
Points
in Grasshopper/Rhino and usually correspond to precise spatial markers; e.g. an ATM location, a traffic light, an address, or a tram stop. - Ways become
Polylines
in Grasshopper/Rhino and usually correspond to areas or routes; e.g. a road, a bus route, a coastline, or a park.
Caribou also provides an Extract Buildings
component that handles converting Way
geometry into 3D shapes if that Way
is marked as a building
and if metadata regarding that building’s height is present.
Regardless of the type of Extract
component you are using, the workflow is the same.
- Place Caribou’s
Extract Nodes
orExtract Ways
orExtract Buildings
component(s) - Place a standard Grasshopper
File Path
component, reference yourxml
file(s), and connect the outputs to theOSM File
input parameter - Place Caribou’s
Specify Features
component. - Click the button at the bottom of the
Specify Features
component and select the types of features you want to extract. - Connect the
OSM Features
output fromSpecify Features
to theOSM Features
input of yourExtract
component(s). - Done!
Download the minimal example definition
Non-Geometry Outputs
Each Extract
component also has two non-geometry outputs.
Tags list all the different pieces of metadata attached to a geometric output. For example, a Way
representing a building might have tags of:
{1;2}
addr: housenumber=158
addr: street=Cuba Street
addr: suburb=Te Aro
building-apartments
building:levels=8
name=Cubana Apartments
ref: linz: address id=stack(20 61327-2061340)
In this case the 1
in the path would refer to the queried tag (e.g. apartments
) while the 2
would correspond to its index relate to other geometry found with the apartments
tag.
Report lists information related to the tag types requested for parsing, e.g.:
{3}
Office
building=industrial
35 found
233,0,10
Building
building::industrial
An Office Building.
The 3
in the path relates to the queried tag, e.g. this is the report for the 3rd tag requested. This data provided corresponds to:
Office
The specific tagbuilding=industrial
The ‘raw’ query string of the tag35 found
The number of items found233,0,10
A suggested color for this layer (the colors produced aim to maximise perceptual difference)Building
The parent tag (e.g. the key that this tag is a value of)building::industrial
A Rhino layer path string (to aid baking)A building where some manufacturing process takes place.
The description of the tag according to the OSM Wiki.
Open Street Map Data Types
Because of the way that Open Street Maps assigns metadata, the Select Features interface has a number of nuances.
All metadata on Open Street Map is in a Key:Value
tag format where a Node
or Way
can be tagged with any number of pairs. For example, a tram stop might have a name of Stop 1: Spencer Street a network of PTV - Metropolitan Trams and a railway of tram_stop.
Certain types of pairs are specified as features and subfeatures which correspond to a broad set of common information types. E.g. building=church or craft=jeweller. These ‘defined’ features/subfeatures are what are presented within Caribou’s Specify Features pop-up.
It is important to note that, although the features/subfeatures are presented in a series of lists, they are not mutually-exclusive categories. A Node
or Way
might be a building feature with the subfeature of hotel while also being classified as an amenity feature of the subfeature type cafe. Many tags only specify a feature without a specific subfeature, e.g. just building or shop.
When using the feature selection UI, it matters if the top-level feature is checked or not. When searching for Public Transport feature types (with it and all child-items selected), Caribou will only output/classify items according to the main feature, e.g. Public Transport. If you want to output/classify items according to their subfeatures, you should uncheck the parent feature but select all of the subfeatures.
Querying Arbitrary Metadata
If you want to search for a tag that is not a defined feature/subfeature, you can use a Panel
component or Text
parameter and manually-specify a key-value pair to find using the key=value
format. To search for multiple tags to match, the text can be separated with a comma or a new line. For example:
network=PTV - Metropolitan Trams
cuisine=mexican
building:levels=4
addr:suburb=Te Aro
Filtering Arbitrary Metadata
Once data has been parsed using the Extract Nodes/Ways/Buildings component, all of the tags present across all items can be viewed and filtered using a Filter Tags component. This component takes as inputs the items (e.g. Node/Ways/Buildings
) and Tags
outputs from any of the Extract components.
Clicking the Filter Tags button will then bring up the style of window presented by the Specify Features component. However, it will show all tags present in the provided items — both features/subfeatures but also all other forms of tags. You can use successive Filter Tags components to perform GIS-style queries that look for the presence/absence of different types of tags.
Previewing, Baking, Filtering, and Labeling Geometry
You can download this definition to see examples of how to:
- Color the geometry in Grasshopper according to it’s feature/subfeature types.
- Display a legend in Rhino with the above color codes for features/subfeatures.
- Filter the results of the parsed geometry/data; e.g. to find all buildings with a height above 40m or more specific combinations of multiple tags.
- Bake out the geometry to individually-labelled layers.
- This requires the use of the human plugin which is available for Rhino 6/7 on Windows/Mac. Opening the definition should prompt you to install it.
- Use sets to identify items that don’t have a particular tag, e.g. all restaurants that are not wheelchair accessible.
- Visualise each object’s metadata using Text Tags so it can be seen in Rhino
When saving the file you will probably need to remove the .txt
extension, e.g. save it as Caribou - Extension Examples.ghx
.
Support and Source
Support can be requested, or feedback provided, by opening a discussion on GitHub. Issues and pull-requests are encouraged.
Caribou’s source code is available on GitHub under the LGPL v3.0 license.