Merge branch 'release/v0.10.0' into main

CHANGELOG.md

@@ -5,7 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.9.01] - 2021-07-20
+## [0.10.0] - 2021-07-21
+### Added
+- A bake-friendly layer name to the `Report` output parameter
+- Documentation at [https://caribou.philipbelesky.com](caribou.philipbelesky.com)
+
+## [0.9.1] - 2021-07-20
 ### Changed
 - Removed pre-release marker
 

Caribou/Models/TreeFormatters.cs

@@ -47,18 +47,23 @@ public static GH_Structure<GH_String> MakeTreeForMetaDataReport(RequestHandler r
                 var metaData = result.RequestedMetaData.Requests[i];
                 var count = result.FoundData[metaData].Count;
                 var colorForItem = GetPerceptualColorForTreeItem(requestMetaDataCount, i);
+                var metaDataTitle = tInfo.ToTitleCase(metaData.Name);
 
-                output.Append(new GH_String(tInfo.ToTitleCase(metaData.Name)), path);
+                output.Append(new GH_String(metaDataTitle), path);
                 output.Append(new GH_String(metaData.ToString()), path);
                 output.Append(new GH_String($"{count} found"), path);
                 output.Append(new GH_String(colorForItem.ToString()));
                 if (metaData.ParentType != null)
                 {
-                    output.Append(new GH_String(tInfo.ToTitleCase(metaData.ParentType.Name)), path);
+                    var titleName = tInfo.ToTitleCase(metaData.ParentType.Name);
+                    output.Append(new GH_String(titleName), path);
+                    var layerName = titleName + "::" + metaDataTitle;
+                    output.Append(new GH_String(layerName), path); // Layer path helper
                 }
                 else
                 {
                     output.Append(new GH_String("(No Parent Feature)"), path);
+                    output.Append(new GH_String(metaDataTitle + "::"), path); // Layer path helper
                 }
 
                 if (!string.IsNullOrEmpty(metaData.Explanation))

Caribou/bin/Release/net45/manifest.yml

@@ -1,5 +1,5 @@
 name: Caribou
-version: 0.9.1
+version: 0.10.0
 authors:
   - Philip Belesky
 keywords:

docs/index.md

@@ -48,13 +48,16 @@ Regardless of the type of `Extract` component you are using, the workflow is the
 5. Connect the `OSM Features` output from `Specify Features` to the `OSM Features` input of your `Extract` component(s).
 6. Done!
 
+![A minimum viable definition](/assets/minimum-viable-definition.png)
+
 ### 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
@@ -64,38 +67,66 @@ name=Cubana Apartments
 ref: linz: address id=stack(20 61327-2061340)
 ````
 
-*Report* lists information related to the parsing process itself:
+In this case the `1` in the path would refer to the queried feature (e.g. `apartments`) while the `2` would correspond to the geometry outputs (e.g. the second item).
+
+*Report* lists information related to the feature types requested for parsing, e.g.:
 
 ```
+{3}
 Office
 building=office
 35 found
 233,0,10
 Building
 building::office
+An Office Building.
 ```
 
-This data is provided as:
+The `3` in the path relates to the queried feature, e.g. this is the report for the 3rd feature requested. This data provided corresponds to:
 
-1. The specific type of information (Office)
+1. The specific type of feature
 2. The 'raw' query string
 3. The number of items found
 4. A suggested color for this layer (colors are developed to maximise perceptual difference)
 5. The 'parent' type of the information
 6. A layer path string (to aid baking)
+7. The description of the type according to the [OSM Wiki](https://wiki.openstreetmap.org/wiki/Main_Page).
+
+### Open Street Map Data Types
+
+![The Selection filtering UI](/assets/selection-filtering.png)
+
+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 have 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 types. E.g. **building**=*church* or **craft**=*jeweller*. These 'defined' features/subfeatures are what are presented within Caribou's *Specify Features* pop-up.
 
-### Filtering Open Street Map Data
+It is important to note that, although the features/subfeatures are presented in a series of lists, they are not mutually-exclusive categories. A piece of geometry 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**.
 
-TODO
+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 feature and then select all the subfeatures.
 
-### Baking and Labeling Geometry
+### Querying Arbitrary Metadata
 
-You can download this definition to see examples of how to:
+If you want to search for a piece of metadata 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 a number of pairs, 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
+```
+
+### Previewing, Baking, and Labeling Geometry
+
+You can download [this definition](https://raw.githubusercontent.com/philipbelesky/Caribou/main/examples/Caribou%20-%20Simple%20Example.ghx) to see examples of how to:
 
 1. Color the geometry in Grasshopper according to it's metadata data
 2. Display a legend in Rhino with the above color codes.
 3. Bake out the geometry to individually-labelled layers
-  - This requires the use of the [*human* plugin](https://discourse.mcneel.com/c/grasshopper/human/88) which is available for Rhino 6/7 on Windows/Mac.
+  - This requires the use of the [*human* plugin](https://discourse.mcneel.com/c/grasshopper/human/88) which is available for Rhino 6/7 on Windows/Mac. Opening the definition should prompt you to install it.
+
+*When saving the file you will probably need to remove the `.txt` extension, e.g. save it as `Caribou - Simple Example.ghx`.*
 
 ## Support and Source