Put it all on one page to reduce overhead

OvertureMaps · Aug 13, 2024 · b92e71f · b92e71f
1 parent db9613a
commit b92e71f
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 184 deletions.
diff --git a/docs/schema/concepts/by-theme/base/index.mdx b/docs/schema/concepts/by-theme/base/index.mdx
@@ -2,6 +2,18 @@
 title: Base
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import QueryBuilder from '@site/src/components/queryBuilder';
+
+import OSMtoOvertureInfrastructure from '!!raw-loader!@site/src/queries/partials/osm_conversion_logic/infrastructure.sql';
+import OSMtoOvertureLand from '!!raw-loader!@site/src/queries/partials/osm_conversion_logic/land.sql';
+import OSMtoOvertureLandUse from '!!raw-loader!@site/src/queries/partials/osm_conversion_logic/land_use.sql';
+import OSMtoOvertureWater from '!!raw-loader!@site/src/queries/partials/osm_conversion_logic/water.sql';
+
+
+
 ## Overview
 The Overture base theme
 
@@ -15,6 +27,41 @@ The base theme has five feature types.
 
 ## Theme concepts
 
+### OpenStreetMap Tags to Overture Properties
+The **subtype** and **class** of an `infrastructure`, `land`, `land_use`, or `water` feature in the base theme is the tags that are present on the feature in OpenStreetMap.
+
+Below is the logic that is currently used to convert from OSM tags into Overture schema.
+
+
+<details>
+    <summary>How do I interpret this query?</summary>
+
+    Each `WHEN` line in the `CASE` statement is a condition that defines both the **subtype** and the **class** of a feature. For example:
+    ```sql
+    WHEN element_at(tags,'highway') = 'bus_stop' THEN ROW('transit', 'bus_stop')
+    ```
+
+    Here, `element_at(tags, 'highway')` is accessing the value of the `highway` tag in OSM. So, when `highway=bus_stop` is present, then the statement returns `ROW(subtype, class)`, in this case, **subtype**=`transit` and **class**=`bus_stop`.
+
+    Since this particular statement is at the top of the list, it will take priority over other tags on the feature. If the same feature was also tagged as an airport gate, those tags would be ignored.
+</details>
+
+<Tabs>
+    <TabItem value="Infrastructure">
+        <QueryBuilder query={OSMtoOvertureInfrastructure}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Land">
+        <QueryBuilder query={OSMtoOvertureLand}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Land Use">
+        <QueryBuilder query={OSMtoOvertureLandUse}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Water">
+        <QueryBuilder query={OSMtoOvertureWater}></QueryBuilder>
+    </TabItem>
+</Tabs>
+
+
 ## Schema reference
 - [Explore the schema for the infrastructure feature type](/schema/reference/base/infrastructure)
 - [Explore the schema for the land feature type](/schema/reference/base/land)

diff --git a/docs/schema/concepts/by-theme/base/infrastructure.mdx b/docs/schema/concepts/by-theme/base/infrastructure.mdx
diff --git a/docs/schema/concepts/by-theme/base/land.mdx b/docs/schema/concepts/by-theme/base/land.mdx
diff --git a/docs/schema/concepts/by-theme/base/land_use.mdx b/docs/schema/concepts/by-theme/base/land_use.mdx
diff --git a/docs/schema/concepts/by-theme/base/water.mdx b/docs/schema/concepts/by-theme/base/water.mdx
diff --git a/docs/schema/concepts/by-theme/buildings/index.mdx b/docs/schema/concepts/by-theme/buildings/index.mdx
@@ -12,81 +12,55 @@ import OSMtoOvertureBuildingRoofMaterial from '!!raw-loader!@site/src/queries/pa
 import OSMtoOvertureBuildingRoofShape from '!!raw-loader!@site/src/queries/partials/osm_conversion_logic/building_roof_shape.sql';
 
 ## Overview
-The Overture buildings theme
+
+The Overture buildings theme captures the compilation of many building attributes from a variety of open data sources including OpenStreetMap, Esri Community Maps, Microsoft, and Google.
 
 ## Feature types
-The buildings theme has two feature types.
-- `building` is a feature type that... It has a Polygon or Multipolygon geometry
-- `building_part` is a feature type that... It has a Polygon geometry.
+
+The buildings theme has two feature types:
+
+- `building` is a polygon or multipolygon geometry that represents the building's footprint (or roofprint, if traced from imagery).
+- `building_part` is a polygon that describes part of a building. These come from the OSM features with the tag `building:part=yes`.
 
 ## Theme concepts
 
-Overture conflates buildings from many open data sources to a consistent schema.
+Both building and building_part types may have many **shape** related properties. These are useful for expressing the physical shape characteristics of the buidling including `roof_height`, `roof_shape`, `roof_material`, `facade_material`, etc.
+
+### OpenStreetMap Tags to Overture Properties
 
-### OSM Tags to Overture Properties
+In OpenStreetMap, an object is defined as a building by the presence of `building` tag. Most commonly, the value is simply, `building=yes`. However, in cases where there is a more descriptive value, we capture that information along with other building attributes such as height, roof shape, material, etc. and map them to a finite list of values defined in the building schema.
+
+You can see the SQL query logic that transforms OSM tags into Overture properties for each of these attributes below:
 
 <details>
     <summary>How do I interpret these queries?</summary>
 
-    Each `WHEN` line in the `CASE` statement is a condition that defines both the **subtype** and the **class** of a feature. For example:
+    Each `WHEN` line in the `CASE` statement is a condition that defines the value of the Overture property. For example:
     ```sql
-    WHEN element_at(tags,'natural') IN ('desert') THEN ROW('desert', element_at(tags,'natural'))
+    WHEN lower(trim(element_at(tags, 'building'))) IN ('clinic','hospital') THEN 'medical'
     ```
-    Here, `element_at(tags, 'natural')` is accessing the value of the `natural` tag in OSM. So, when `natural=desert` is present, then the statement returns `ROW(subtype, class)`, in this case, **subtype**=`desert` and **class**=`desert`.
-
-    Since this particular statement is at the top of the list, it will take priority over other tags on the feature. If the same feature was also tagged as an airport gate, those tags would be ignored.
+    Here, `lower(trim(element_at(tags, 'building')))` is accessing the value of the `building` tag in OSM (and ensuring it is lowercase). Therefore, when either the `building=clinic` or `building=hospital` tag is present, the statement returns `medical`. In this case, this defines the **subtype** for a medical building.
 </details>
 
-
 <Tabs>
-<TabItem value="Subtype">
-Subtypes
-
-
-<QueryBuilder query={OSMtoOvertureBuildingSubtype}></QueryBuilder>
-</TabItem>
-
-<TabItem value="Class">
-Classes
-<details>
-    <summary>How do I interpret this query?</summary>
-</details>
-
-<QueryBuilder query={OSMtoOvertureBuildingClass}></QueryBuilder>
-</TabItem>
-
-<TabItem value="Facade">
-Facade
-<details>
-    <summary>How do I interpret this query?</summary>
-</details>
-
-<QueryBuilder query={OSMtoOvertureBuildingFacade}></QueryBuilder>
-</TabItem>
-
-<TabItem value="Roof Shape">
-Roof Shape
-<details>
-    <summary>How do I interpret this query?</summary>
-</details>
-
-<QueryBuilder query={OSMtoOvertureBuildingRoofShape}></QueryBuilder>
-</TabItem>
-
-<TabItem value="Roof Material">
-Roof Material
-<details>
-    <summary>How do I interpret this query?</summary>
-</details>
-
-<QueryBuilder query={OSMtoOvertureBuildingRoofMaterial}></QueryBuilder>
-</TabItem>
-
-
+    <TabItem value="Subtype">
+        <QueryBuilder query={OSMtoOvertureBuildingSubtype}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Class">
+        <QueryBuilder query={OSMtoOvertureBuildingClass}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Facade">
+        <QueryBuilder query={OSMtoOvertureBuildingFacade}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Roof Shape">
+        <QueryBuilder query={OSMtoOvertureBuildingRoofShape}></QueryBuilder>
+    </TabItem>
+    <TabItem value="Roof Material">
+        <QueryBuilder query={OSMtoOvertureBuildingRoofMaterial}></QueryBuilder>
+    </TabItem>
 </Tabs>
 
-
-
 ## Schema reference
+
 - [Explore the schema for the building feature type](/schema/reference/buildings/building)
 - [Explore the schema for the building_part feature type](/schema/reference/buildings/building_part)