From b8185dbaa17514d818a48084a0e3a9970a33909f Mon Sep 17 00:00:00 2001 From: Jennings Anderson Date: Fri, 19 Jul 2024 10:57:16 -0700 Subject: [PATCH] [standing] Staging to Main (#253) Documentation for release --- docusaurus/docs/schema/0-Schema.mdx | 10 +- docusaurus/docs/schema/GERS.mdx | 35 - docusaurus/docs/schema/attributes/index.mdx | 38 -- docusaurus/docs/schema/attributes/names.mdx | 93 --- .../docs/schema/attributes/scoping-rules.mdx | 425 ------------ .../attributes/transportation/index.mdx | 53 -- .../attributes/transportation/roads.mdx | 619 ------------------ .../transportation/shape-connectivity.mdx | 497 -------------- .../transportation/travel-modes.mdx | 198 ------ 9 files changed, 5 insertions(+), 1963 deletions(-) delete mode 100644 docusaurus/docs/schema/GERS.mdx delete mode 100644 docusaurus/docs/schema/attributes/index.mdx delete mode 100644 docusaurus/docs/schema/attributes/names.mdx delete mode 100644 docusaurus/docs/schema/attributes/scoping-rules.mdx delete mode 100644 docusaurus/docs/schema/attributes/transportation/index.mdx delete mode 100644 docusaurus/docs/schema/attributes/transportation/roads.mdx delete mode 100644 docusaurus/docs/schema/attributes/transportation/shape-connectivity.mdx delete mode 100644 docusaurus/docs/schema/attributes/transportation/travel-modes.mdx diff --git a/docusaurus/docs/schema/0-Schema.mdx b/docusaurus/docs/schema/0-Schema.mdx index d96844ac0..34dbdcd8e 100644 --- a/docusaurus/docs/schema/0-Schema.mdx +++ b/docusaurus/docs/schema/0-Schema.mdx @@ -14,7 +14,7 @@ import yamlLoad from "@site/src/components/yamlLoad" import EmpireStateBuilding from "!!raw-loader!@site/docs/_examples/buildings/empire-state-building.json"; import MainDefs from "!!raw-loader!@site/docs/_schema/defs.yaml"; -Overture data is structured by three components: the schema, the data model, and the Global Entity Reference System ([GERS](https://docs.overturemaps.org/gers/)). The schema describes the shape of the data and devises the constraints applied to that data. The data model specifies what types of features exist, their geometries, how the features relate to each other, and what kind of properties they have. GERS is a framework for structuring, encoding, and matching Overture data to a shared universal reference. +Overture data is structured by three components: the schema, the data model, and the Global Entity Reference System ([GERS](https://docs.overturemaps.org/gers/)). The schema describes the shape of the data and devises the constraints applied to that data. The data model specifies what types of features exist, their geometries, how the features relate to each other, and what kind of properties they have. GERS is a framework for structuring, encoding, and matching Overture data to a shared universal reference. - -``` -D SET s3_region='us-west-2'; -D SELECT id FROM read_parquet('s3://overturemaps-us-west-2/release/2024-04-16-beta.0/theme=buildings/type=*/*', filename=true, hive_partitioning=1) limit 5; -┌──────────────────────────────────┐ -│ id │ -│ varchar │ -├──────────────────────────────────┤ -│ 08bf2a40219b0fff0200c394dae731bd │ -│ 08bf35ad6a05afff0200e90ab3b011fa │ -│ 08bf35ad6a058fff020009945ce09d65 │ -│ 08bf35ad6a04efff02006264a736fc56 │ -│ 08bf35ad6a04afff0200cf5e511a3f1b │ -├──────────────────────────────────┤ -│ 5 rows │ -└──────────────────────────────────┘ -``` - -## Stability and Traceability - -GERS IDs are intended to be stable (within a reasonable tolerance of error) across multiple versions of Overture data. When stability is not possible, Overture will attempt to provide traceability. For example: -- a single road segment is bisected by a new road and becomes two road segments: 1 unique ID → 2 new unique IDs; -a large building footprint is determined to be four smaller buildings when a higher resolution dataset becomes available: 1 unique ID → 4 new unique ID; -- a building is shifted 10 meters to the west when higher resolution imagery is made available: the unique ID is preserved for that feature diff --git a/docusaurus/docs/schema/attributes/index.mdx b/docusaurus/docs/schema/attributes/index.mdx deleted file mode 100644 index 9f1e65ddb..000000000 --- a/docusaurus/docs/schema/attributes/index.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Attributes ---- - -import CodeBlock from '@theme/CodeBlock'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import JSONSchemaViewer from "@theme/JSONSchemaViewer"; -import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" -import MainDefs from "!!raw-loader!@site/docs/_schema/defs.yaml"; - -## Common properties - -Overture Maps features are defined by three core properties: - -- `theme` is a mandatory property analogous to "layer". The term is deliberately chosen to avoid some of the baggage that goes along with the word "layer". - - Examples: `transportation`, `buildings`, `places`, `administrative` -- `type` is a mandatory property representing a feature type within the theme: - - Example: `theme=transportation`, `type=segment` - - Example: `theme=buildings`, `type=building` -- `subtype` is an optional property which can further refine the feature type within. - - Example: `theme=transportation`, `type=segment`, `subtype=road` - -Other common properties include: - -- `bbox` is the bounding box for the feature, defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. -- `version` is the version number of the feature, incremented in each Overture Maps release where the geometry or attributes of this feature changed. -- `update_time`is the timestamp when the feature was last updated -- `sources` is the array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. -- `ext_' is the prefix for any additional top-level properties. - -## Complex attributes - -Some feature properties are quite complex and require further explanation. - -- **[Names](/schema/attributes/names)**: where applicable, complex attributes such as names will always use the same schema across all themes. -- **[Scoped and rule-based properties](/schema/attributes/scoping-rules)**: a scoping property narrows the scope of its parent property and may only apply to a particular instance of the parent property; rule-based property is an array of rules, which are objects containing at least one scoping property. -- **[Transportation](/schema/attributes/transportation)**: the transportation schema is our most complex with many attributes that require additional documentation. diff --git a/docusaurus/docs/schema/attributes/names.mdx b/docusaurus/docs/schema/attributes/names.mdx deleted file mode 100644 index 0758d8d9a..000000000 --- a/docusaurus/docs/schema/attributes/names.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Names ---- - -import JSONSchemaViewer from "@theme/JSONSchemaViewer"; -import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" -import yamlLoad from "@site/src/components/yamlLoad" -import MainDefs from "!!raw-loader!@site/docs/_schema/defs.yaml"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -Named entities in Overture Maps share a common schema. - - - -## `primary` -If a feature has a name, expect the `names` attribute to have at least one property: `primary`. This will always be populated with the localized name of a feature. - -```yaml -id: 08b2aa845a18afff02009f7c732067c5 -names: - primary: The White House -``` - -## `common` - -Common name variations are translations of a name. - -```yaml -id: 08b2aa845a18afff02009f7c732067c5 -names: - common: - de: Weißes Haus - hi: व्हाइट हाउस - fi: Valkoinen talo - ru: Белый дом - pt: Casa Branca - lt: Baltieji Rūmai - hr: Bijela kuća - fr: Maison Blanche - hu: Fehér Ház - br: Ti Gwenn - si: ධවල මන්දිරය - uk: Білий дім - sk: Biely dom - sv: Vita huset - ko: 백악관 - en: White House - ku: Qesra Spî - it: Casa Bianca - es: Casa Blanca - zh: 白宫 - cs: Bílý dům - ja: ホワイトハウス - fa: کاخ سفید - ro: Casa Albă - nl: Witte Huis - tr: Beyaz Saray -``` - -## `rules` -Additional names variations such as _official_, _alternate_, or _short_ exist as `rules`. - -Rules can also have `side` and `geometric` range scoping. Read more about [scoping rules here](/schema/attributes/scoping-rules). - -```yaml -id: 08b2aa845a18afff02009f7c732067c5 -names: - rules: - - variant: alternate - language: hr - value: Bila kuća - between: null - side: null -``` - -## Languages - -Languages in the Overture Maps schema are identified by [IETF BCP-47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag); the same tag scheme is used for `common` map entries and `language` values in rules. - -This pattern recognizes BCP-47 language tags at the lexical or syntactic level. It verifies that candidate tags follow the grammar described in the [RFC](https://datatracker.ietf.org/doc/html/rfc5646), but not that they are validly registered tag in [IANA's language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). - -In the regular expression, `'(:?'` indicates a non-capturing group, and all the top-level or non-nested groups represent top-level components of `langtag` referenced in the syntax section of [https://www.rfc-editor.org/rfc/bcp/bcp47.txt](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). In particular, the top-level groups in left-to-right order represent: - -``` -1. language -2. ["-" script] -3. ["-" region] -4. *("-" variant) -5. *("-" extension) -``` diff --git a/docusaurus/docs/schema/attributes/scoping-rules.mdx b/docusaurus/docs/schema/attributes/scoping-rules.mdx deleted file mode 100644 index a42ebcd61..000000000 --- a/docusaurus/docs/schema/attributes/scoping-rules.mdx +++ /dev/null @@ -1,425 +0,0 @@ ---- -title: Scoping Rules ---- - - -import CodeBlock from '@theme/CodeBlock'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; -import ExampleGeometricScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/geometric-scoping.yaml'; -import ExampleTemporalScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/temporal-scoping.yaml'; -import ExampleSubjectiveHeadingScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/subjective-heading-scoping.yaml' -import ExampleSubjectiveUsagePurposeScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/subjective-usage-purpose-scoping.yaml'; -import ExampleSubjectiveStatusScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/subjective-status-scoping.yaml'; -import ExampleSubjectiveVehicleAttributesScoping from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/subjective-vehicle-attributes-scoping.yaml'; -import ExampleLanesAbsoluteForm from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/lanes-absolute-form.yaml'; - -## Scoped and rule-based properties - -In the real-world, many facts and rules affecting entities have -only a partial application, meaning they don't apply everywhere, or -they don't apply at all times, or to everyone, or to all sets of -external conditions. For example, access restrictions on a road segment -might not apply to all people or all kinds of vehicles, or they might -vary according to the day of the week. - -The Overture Maps schema uses two related concepts to capture the partial application of facts and rules: scoped values, and rule-based properties. - -### Scoped values and scoping properties - -A *scoped* value is a value which only applies within a limited scope. -Most scoped values are rules in the rule lists of -[rule-based properties](#rules-and-rule-based-properties). However, -scoped values also exist outside of rule-based properties. For -example, a signpost property belonging to a road segment might be -geometrically scoped to its position along the road. - -The scope in which a scoped value applies is controlled by one or more -special child properties of the value known as *scoping* properties. - -#### Geometric scoping (linear referencing) - - - - -The geometric scoping properties `at` and `between` limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the `at` or `between` property. - -The value of the `at` property is a single real number `a` where `0` ≤ `a` -≤ `1`. It represents a discrete position along the segment's geometry. The -value of the `between` property is a pair of numbers `[a, b]` where `0` ≤ -`a` < `b` ≤ `1`. It represents a range of positions along the segment's -geometry. The numbers `a` and `b` are interpreted as percentage displacements -along the parent segment's geometry starting from the start of the segment. -(*The terms "start" and "end" are explained in -[Shape and Connectivity](https://docs.overturemaps.org/guides/transportation/shape-connectivity).*) - -So, for example, the scoping property `"at": 0.15` scopes its parent value -to the position on the segment that is displaced 15% of the segment length from -the start. - -
- -
- - - -
- -
- -*The position along the segment geometry described by `"at": 0.15`.* - -
- -
-
- -
- -The scoping property `"between": [0.35, 0.75]` scopes its parent value to the -range of positions on the segment beginning at 35% and extending to 75% of the -segment length from the start. - -
- -
- - - -
- -
- -*The range on the segment geometry described by `"between": [0.35, 0.75]`.* - -
- -
-
- -
- - - - -The example below shows a road segment whose speed limit is defined by -two geometrically-scoped speed limit rules: - -{ ExampleGeometricScoping } - - - - -#### Temporal scoping (opening hours) - - - - -The temporal, or time-based, scoping construct `when: { during: "..." }` limits -the scope of its parent value to one or more recurring time ranges. When the -parent value is a rule object, the rule only matches the time range or time -ranges specified in the `during` property. - -The `during` property must contain a string expressed in the OpenStreetMap -[opening hours specification](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification). - - - - -The example below shows a road segment with a temporally-scoped access -restriction rule. The rule states that non-bus travellers are prohibited -from access to the segment on weekdays between 3PM and 6PM. - -{ ExampleTemporalScoping } - - - - - - -#### Subjective scoping - -Subjective scoping means that the scope of a property can be constrained based -on subjective factors like *who* or *what* is travelling on the transportation -network, or *how* they are doing it. - -The Overture Maps transportation schema supports the following subjective factors: - -1. [Travel mode](#travel-mode-scoping) -1. [Heading](#heading) -1. [Purpose of use](#purpose-of-use-scoping) -1. [Status, or membership in a recognized group](#status-scoping-membership-in-a-recognized-group) -1. [Vehicle attributes](#vehicle-attributes-scoping) - -The sub-headings below explain each of these subjective factors in greater -detail. - -##### Travel mode scoping - -A travel mode is a way of moving about the transportation network, for -example driving in a motor vehicle, or, more specifically, driving in a -high-occupancy vehicle. - -The property construct `when: { mode: [...] }` limits the scope its -parent value to apply only to people or things travelling using the -listed travel modes. - -To dive deeper into this topic, see the page on [travel modes](https://docs.overturemaps.org/guides/transportation/travel-modes). - -##### Heading - - - - -Heading scoping limits the the scope of a parent value to apply only -when the traveller is proceeding along the segment geometry in the named -direction, either `forward` or `backward`. (*The directions `forward` -and `backward` are defined on the [shape and connectivity](https://docs.overturemaps.org/guides/transportation/shape-connectivity) page.*) - -The property construct `when: { heading: forward|backward }` applies -heading scoping to a parent value. - - - - - -The example below shows a road segment with multiple heading-scoped -access restriction rules. The rules allow all standard travel modes for -the segment class to travel in the forward direction, but only allow -buses to travel in the backward direction. - -{ ExampleSubjectiveHeadingScoping } - - - - -#### Purpose of use scoping - - - - -Usage purpose scoping limits the scope of a parent value to apply only -when the user is using the feature for one of the listed purposes. This -type of scoping is common when it matters that a person is in the -process of doing something like making a delivery or acting as the -customer of a business. - -The property construct `when: { using: [...] }` applies usage purpose -scoping to a parent value. - - - - -The example below shows a road segment representing a hotel driveway -where through traffic is not permitted (only usage by hotel customers -or as a final destination is allowed): - -{ ExampleSubjectiveUsagePurposeScoping } - - - - -#### Status scoping (membership in a recognized group) - - - - -Status scoping limits the scope of a parent value to apply only when the -user has a certain recognized status or is a member of a recognized -group. This type of scoping is useful when it matters whether a person -or thing has a recognized characteristic, such as holding a permit or -being an employee of a business or student at an academic institution. - -The property construct `when: { recognized: [...] }` applies status -scoping to a parent value. - - - - -The example below shows a road segment modeling a private condominium -tower driveway where access is denied to the general public, but allowed -to privately-authorized individuals, such as condo unit owners: - -{ ExampleSubjectiveStatusScoping } - - - - -#### Vehicle attributes scoping - - - - -Vehicle attribute scoping limits the scope of a parent value to apply -only when the vehicle in use meets certain criteria. - -The property construct `when: { vehicle: [{ dimension: ..., comparison: ..., value: ... }] }` applies vehicle -attributes scoping to a parent value. - -Note that vehicle attribute scoping can overlap to some degree with -[travel mode scoping](#travel-mode-scoping). For example, some access -rules may be scoped to the travel mode "heavy goods vehicle", while -another equivalent access rule could be scoped to the vehicle attribute -"gross vehicle weight". - - - - -{ ExampleSubjectiveVehicleAttributesScoping } - - - - - - - -## Rules and rule-based properties - -A *rule-based* property is a property whose value in a given situation is -determined by evaluating a list of rules against the facts applicable to that -situation. Each individual rule in the list of rules is itself a scoped value, -a scoped value, and the assessment of which rule applies to a given set of facts -is done by the rule evaluation algorithm. - -### Absolute Form - -There are cases when specifying a property value using rules makes sense, and -cases where doing so is unnecessarily complicated because the real-world entity -being modeled has a single unchanging state which is the same in all fact -situations. In these cases, most rule-based properties support a simpler -absolute form without a list of rules. - -Consider the following two examples of road segments. On the left is a section -from a simple two-lane bidirectional city street in which there is always one -lane of traffic flowing in each direction. On the right is a section from a -one-way city street in which two of the lanes are only available for driving at -certain times of the day, being reserved for parking at other times. In the -example on the left, the lane list is specified absolutely; while in the example -on the right, it is given as a list of [temporally-scoped](#temporal-scoping-opening-hours) -lane rules. - -
- -
- -{ ExampleLanesAbsoluteForm } - -
- -
- -*An absolute list of lanes.* - -
- -
- -
- -
- -
- -
- - - -```yaml ---- -id: overture:transportation:example:lanes-rule -type: Feature -geometry: - type: LineString - coordinates: - - - -123.12244656918179 - - 49.280940587393815 - - - -123.12562968007902 - - 49.27884862879665 -properties: - theme: transportation - type: segment - version: 0 - update_time: "2023-06-16T15:57:00-06:00" - subtype: road - road: # The `road` property is deprecated and will be removed in the 2024-07 release - lanes: - - value: - - direction: forward - - direction: forward - - during: Mo-Fr 15:00-18:00 - value: - - direction: forward - - direction: forward - - direction: forward - - direction: forward -``` - -
- -
- -*A list of lane rules.* - -
- -
- -
- -
- -
- -### Rule evaluation algorithm - -Given a rule-based property, the actual value of the property in a given fact -pattern is determined by a three-step process: first, all matching rules are -identified; second, the single determining rule is chosen if possible; lastly, -if there is no applicable rule, an appropriate default value may be assumed. - -1. **Matching rules.** For a given rule and a given set of facts, the rule - *matches* the facts if the scope of the rule contains all the facts, *i.e.* - the facts fit within all of the scoping properties expressed in the rule. The - matching criteria for a rule can be thought of as the logical AND of all the - scoping properties expressed in the rule. -2. **Determining rule.** For a given rule-based property and a given set of - facts, *at most* one rule can *determine* the property value. If only one - rule matches, that rules determines the property value. If more than one rule - matches, the last matching rule in the list determines the value. (This is - similar to how OpenStreetMap [conditional restrictions](https://wiki.openstreetmap.org/wiki/Conditional_restrictions) - evaluated.) Therefore it is important to write more general rules before more - specific ones in a rule list. -3. **Fallback to default.** If there are no matching rules, an appropriate - default value may apply, depending on the property being evaluated. diff --git a/docusaurus/docs/schema/attributes/transportation/index.mdx b/docusaurus/docs/schema/attributes/transportation/index.mdx deleted file mode 100644 index 5494694c3..000000000 --- a/docusaurus/docs/schema/attributes/transportation/index.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Transportation ---- - -import DocCardList from '@theme/DocCardList'; - - -Overture Maps transportation theme is the collection of features and attributes that describe the infrastructure and conventions of how people and objects travel around the world. Transportation data includes highways, footways, cycleways, railways, ferry routes, and public transportation. - - -## Use cases - -You might use Overture Maps transportation data and schema for: - -- **mapping:** rendering a map of connected roads and paths. -- **routing:** calculating optimal routes from place to place. -- **navigation:** generating granular instructions on the maneuvers needed to - follow a route. -- **analytics:** transportation-related analysis including traffic safety - analysis and disaster planning. -- **geocoding:** getting the coordinates of street intersections (geocodes) or - the street intersection near specific coordinates (reverse geocodes). - -## Key concepts - -- **Shape and connectivity.** The transportation theme schema captures the shape -and connectivity of the transportation network using `segment` and `connector` -features. The schema design allows the segmentation process to promote shape -stability and ultimately feature ID stability. Read more on the [shape and connectivity](/schema/attributes/transportation/shape-connectivity) page. - -- **Scoped and rule-based properties.** The `transportation` theme schema allows property values to be specified for granular scopes at the sub-feature level. For example: - - a speed limit on a road segment might be scoped to apply only to part of the - road geometry using _geometric scoping_. - - the directionality of a segment, controlling the direction or directions in - which traffic can flow along the segment geometry, may be specified to change - at different times of day using _temporal scoping_. - - the categories of people and vehicles who are allowed to travel on a segment - can be controlled using _subjective scoping_. - - a real-world attribute that varies under changing environmental conditions can - be modeled using _environmental scoping_. - -Read more about these concepts on the [scoped and rule-based properties](/schema/attributes/scoping-rules) page. - -- **Roads.** The `transportation` theme schema models any kind of road, street or -path, including dedicated walking and cycling paths, as `road` segments. Roads -are currently the most developed part of the `transportation` schema. Read more about roads on the [roads](/schema/attributes/transportation/roads) page. - -- **Travel modes.** The `transportation` theme supports a fuzzy concept called -travel mode which can be used as a way of controlling the scope of scoped -and rule-based properties. Read more about the travel modes concept and how travel modes interact with other scoping properties on the [travel modes](/schema/attributes/transportation/travel-modes) page. - -- [Explore the schema for the connector feature type](/schema/reference/transportation/connector). -- [Explore the schema for the segment feature type](/schema/reference/transportation/segment). diff --git a/docusaurus/docs/schema/attributes/transportation/roads.mdx b/docusaurus/docs/schema/attributes/transportation/roads.mdx deleted file mode 100644 index da46799f0..000000000 --- a/docusaurus/docs/schema/attributes/transportation/roads.mdx +++ /dev/null @@ -1,619 +0,0 @@ ---- -title: Roads ---- - -import CodeBlock from '@theme/CodeBlock'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; -import ExampleAccessRestrictionsBlanketDeny from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/access-restriction-01-blanket.yaml'; -import ExampleAccessRestrictionPrivateAccessWithDeliveries from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/access-restriction-02-private-with-deliveries.yaml'; -import ExampleAccessRestrictionMotorVehiclesDestinationOnly from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/access-restriction-03-motor-vehicles-destination-only.yaml'; -import ExampleAccessRestrictionAxleLimit from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/access-restriction-04-axle-limit.yaml'; -import ExampleSpeedLimitsSimple from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/speed-limits-01-simple.yaml'; -import ExampleSpeedLimitsDirectional from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/speed-limits-02-directional.yaml'; -import ExampleSpeedLimitsVariableMax from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/speed-limits-03-variable-max.yaml'; -import ExampleLanesResolutionConnector from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/lanes-resolution-connector.yaml'; -import ExampleLanesResolutionSegment01 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/lanes-resolution-segment-01.yaml'; -import ExampleLanesResolutionSegment02 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/lanes-resolution-segment-02.yaml'; -import ExampleTurnRestriction1Source from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-source.yaml'; -import ExampleTurnRestriction1Target from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-target.yaml'; -import ExampleTurnRestriction1Exit from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-exit.yaml'; -import ExampleTurnRestriction1Connector1 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-connector1.yaml'; -import ExampleTurnRestriction1Connector2 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-connector2.yaml'; -import ExampleTurnRestriction1Connector3 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-01-connector3.yaml'; -import ExampleTurnRestriction2Source from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-02-source.yaml'; -import ExampleTurnRestriction2Target from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-02-target.yaml'; -import ExampleTurnRestriction2Via from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-02-via.yaml'; -import ExampleTurnRestriction2Connector1 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-02-connector1.yaml'; -import ExampleTurnRestriction2Connector2 from '!!raw-loader!@site/docs/_examples/transportation/docusaurus/turn-restriction-02-connector2.yaml'; - -In the Overture Maps `transportation` theme, a road is any kind of road, -street or path, including a dedicated path for walking or cycling, but excluding a railway. Road segments comprise the majority of ground-based transportation segments. Roads are modeled using [segment](/schema/reference/transportation/segment) features with the `subtype` property value set to the value `road`. - -## Geometry and granularity - -A road segment's geometry is a representation of the road which, -in many cases, approximates the physical centerline of the section of -road being modeled. Road segments support modeling the road network at a range of -granularities. For example, a single road segment can represent a: - -- bidirectional street including all of its lanes and sidewalks. -- sidewalk by itself. -- one-way street or one direction of a dual carriageway. -- single lane or single section of a multi-lane highway. -- dedicated cycleway. -- hiking path. - -## Basic properties - -### Road class - -The `class` property of a road specifies its general purpose of use -and its relative importance within the transportation network. The -`class` property also helps establish reasonable default values. -For example, the class `sidewalk` implies that the default -[access restrictions](#access-restrictions) for the segment allow access for the [travel mode](/schema/attributes/transportation/travel-modes) `foot` and deny access to all other -travel modes. Unlike many road segment properties, a road segment's `class` -property does not support [geometric scoping](/schema/attributes/scoping-rules#geometric-scoping-linear-referencing) (linear referencing). Consequently whenever a linear range of real-world road makes a class transition (for example, between secondary and residential), the Overture transportation -[segmentation](/schema/attributes/transportation/shape-connectivity#segmentation) algorithm will generate a segment split. - -Every road segment has a class. If the `class` property is missing -from a road segment, the default value `unknown` is assumed. The unknown -road class is meant to be a temporary value until a more specific class -is known. - - - -Like many aspects of Overture Maps transportation schema, -the `class` tag is heavily inspired by OpenStreetMap. In this -case, it is similar to, but not the same as, OSM's `highway=*` tag. - -### Surface - -The `road_surface` property of a road indicates its physical surface. If -omitted, a reasonable default value should be assumed based on the -`class`. - -Like many road segment properties, the `road_surface` property supports [geometric scoping](/schema/attributes/scoping-rules#geometric-scoping-linear-referencing) (linear referencing). Consequently, the effective road surface may vary -along different sub-ranges of a road segment's geometry. - -### Flags - -The `road_flags` property of a segment is a set of named flag values -indicating the presence or absence of simple physical characteristics. - -For example, a road segment with -`road_flags = [is_link, is_under_construction]` is a link segment that is -physically under construction. - -Like many road segment properties, the `road_flags` property supports [geometric scoping](/schema/attributes/scoping-rules#geometric-scoping-linear-referencing). Consequently, the applicable road flags may vary along different sub-ranges of a road segment's geometry. - -## Restrictions - -### Access restrictions - -Access restrictions on a road segment specify who is allowed to use the -road, and under what circumstances. - -Every road segment has an *implied* set of access restrictions defined -by its [road class](#road-class) and local rules, norms, and customs. -(The Overture transportation schema does not specify these implied -access restrictions, which are left to the specific application to -resolve.) - -The implied access restrictions may be modified for the road segment as -a whole by providing an explicit value for the property -`access_restrictions`. (Access restrictions may also be specified -at the level of individual [lanes](#lanes), as explained elsewhere.) - -It is technically possible to specify a blanket access grant or refusal -of access applying to everyone and everything; but where, as is typical, -a more precise outcome is needed, one or more [rules](/schema/attributes/scoping-rules#rules-and-rule-based-properties) will be used to specify access restrictions. As with all rule-based properties, if no rule matches the specific facts, then the default restrictions for the road class govern. - - - - -{ ExampleAccessRestrictionsBlanketDeny } - - - - - -{ ExampleAccessRestrictionPrivateAccessWithDeliveries } - - - - - -{ ExampleAccessRestrictionMotorVehiclesDestinationOnly } - - - - - -{ ExampleAccessRestrictionAxleLimit } - - - - -### Turn restrictions - -Turn restrictions on a road segment limit the transitions which are -allowed from that segment into other [physically connected](/schema/attributes/transportation/shape-connectivity#physical-connectivity) segments. - -Every road segment has an implied set of allowed transitions -defined by its [access restrictions](#access-restrictions) as well as -local rules, norms, and customs. An example of a transition restriction -implied by an access restriction, if the segment can only be used along the `forward` [heading](/schema/attributes/transportation/shape-connectivity#heading), then it is implied that no transitions are allowed to any connected segments if travelling -along the `backward` heading. An example of a transition restriction -implied by a local rule or norm would be a blanket prohibition on -U-turns in a given jurisdiction. (The Overture Maps transportation schema -does not specify these local rules, norms, and customs, which are left -to the specific application to resolve.) - -Overture Maps takes a permissive-by-default approach to transition -restrictions. By default, all implied transitions are allowed. The -set of allowed transitions may be reduced by adding explicit transition -restrictions in the `prohibited_transitions` property. - -Turn restrictions come in two flavors: simple and via: a simple turn -restriction allows a simple regulation to be stated, such as "No right -turn onto Elm Street"; a via restriction covers more elaborate cases -where the sequence of maneuvers is important. - - - - -
- -
- - - -
- -*Prohibited right turn from "source" to "target" segment at connector 2.* - -
- -
- -
- -
- -
-Source segment -{ ExampleTurnRestriction1Source } -
- -
-Connector 1 - -*This connector is not an important part of the example, since it does -not participate in the turn restriction, but it is included to bring -real-world context to the example.* - -{ ExampleTurnRestriction1Connector1 } -
- -
-Exit segment - -*This segment is not an important part of the example, since all implied -transitions are allowed on it. We include it to bring real-world context -to the example.* - -{ ExampleTurnRestriction1Exit } - -
- -
-Connector 2 - -*The right turn from the source segment (`forward` heading) to the -target segment (`forward` heading) is prohibited at this connector.* - -{ ExampleTurnRestriction1Connector2 } -
- -
-Target segment - -*Traffic heading `forward` on the source segment may not enter this -segment heading `forward`, i.e. the right turn from the source segment -to this segment is prohibited.* - -{ ExampleTurnRestriction1Target } -
- -
-Connector 3 - -*This connector is not an important part of the example, since it does -not participate in the turn restriction, but it is included to bring -real-world context to the example.* - -{ ExampleTurnRestriction1Connector3 } -
- - -
- -
- - - - - -
- -
- - - -
- -*Prohibited transition from "source" to "target" through `via` segment.* - -
- -
- -
- -
- -
-Source segment -{ ExampleTurnRestriction2Source } -
- -
-Connector 1 -{ ExampleTurnRestriction2Connector1 } -
- -
-Via segment -{ ExampleTurnRestriction2Via } -
- -
-Connector 2 -{ ExampleTurnRestriction2Connector2 } -
- -
-Target segment -{ ExampleTurnRestriction2Target } -
- -
- -
- - - - -### Speed limits - -Speed limits restrict the speed at which travel is permitted on a road. -Typically speed limits specify maximum allowed speeds, but the -Overture also allows minimum speed limits to be set and variable speed -corridors to be indicated. - -Every road segment has an implied speed limit or set of speed limits -defined by its [road class](#road-class) and local rules, norms, and -customs. Note: as with access and turn restrictions, the Overture -transportation schema does not attempt to specify these implied speed -limits. - -The implied speed limits may be configured for the whole road segment by -providing an explicit value for the property -`speed_limits`. Note: granular speed limits can also be -specified at the level of individual [lanes](#lanes), as explained -elsewhere. - -As with access restrictions and turn restrictions, speed limits can be specified using [rules](/schema/attributes/scoping-rules#rules-and-rule-based-properties). - - - - -{ ExampleSpeedLimitsSimple } - - - - - -{ ExampleSpeedLimitsDirectional } - - - - - -{ ExampleSpeedLimitsVariableMax } - - - - -## Lanes - -A road may optionally carry a `lanes` property which, if present, contains -a list of rules that can be used to resolve the applicable traffic lane block -for the road. A lane block is a list of lane objects. Each lane object in the -block describes the physical structure and properties applicable to one the -road's traffic lanes at a granularity sufficient to support the navigation use -case. Note that the `lanes` property applies to traffic lanes, not to -parking lanes. - -### Use cases for lanes - -Many transportation [use cases](/schema/attributes/transportation#use-cases) can be solved either entirely or in large part without examining the lane -structure of the road network. For example, optimal route calculation -can be entirely solved without lane-level information, as can most 2D -map rendering problems. Lane information is most interesting for -granular turn-by-turn or maneuver-by-maneuver navigation applications. - -### Default lane structure - -If the `lanes` property is omitted from a road segment, reasonable -default values should be assumed based on `class` and the -road-level [access restrictions](#access-restrictions). For example, for -a stock two-way road segment of class `primary` with no heading-scoped -access restrictions, a reasonable assumption is two lanes, one -`forward` and one `backward`. - -### Lane numbering - -The number of lanes at a given place and time on a road segment is equal to -the length of the lanes list within the resolved lane block. - -Each entry in the resolved lanes list represents one lane on the road. -Order is important. The list captures the lanes in left-to-right order -as they would be observed by a person standing on the physical road being modeled, facing in the [direction](/schema/attributes/transportation/shape-connectivity#directionality) -of the segment geometry. The leftmost lane has index `0`; the rightmost -lane, assuming there are N total lanes, has index N-1. The example -below illustrates how lane numbering works with example two-lane -segments oriented in the north, west, east, and south directions, -respectively. - -
- -
- -
- - - -
- -
- -
- - - -
- -
- -
- - - -
- -
- -
- - - -
- -
- -
- - -
- -
- -*How lanes are numbered for examples segments with geometry directions due west, north, east, and south.* - -
- -
- -
- -### Lane directionality - -Each lane within a segment has a directionality, documenting which -travel directions are allowed within the lane, with reference to the [orientation of the segment](/schema/attributes/transportation/shape-connectivity#start-end-and-orientation). Lane directionality is specified by the lane object's `directionality` -property. The allowed values are: - -
- -
- -| Directionality | Meaning | -|-|-| -| `forward` | Travel is only allowed along the `forward` heading. | -| `backward` | Travel is only allowed along the `backward` heading. | -| `both_ways` | Travel is allowed both `forward` and `backward` at the same time. | -| `alternating` | Travel is one-way and changes between `forward` and `backward` constantly. | -| `reversible` | Travel is one-way and changes between `forward` and `backward` infrequently. | - -
- -
- -
- -*Allowed values for lane `directionality`.* - -
- -
-
- -The `directionality` property is a mandatory property for lanes, and is -the only mandatory property. - -When the allowed travel heading changes based on a regular schedule, -the appropriate "definite" directionalities (`forward`, `backward`, and -`both_ways`) should be used along with [temporal scoping](/schema/attributes/scoping-rules#temporal-scoping-opening-hours) at the lane block level. - -When the allowed travel heading changes based on unpredictable local -factors, such that allowed heading at any given time can only be known -by an observer actually present at the real-world location, the -appropriate indefinite directionality (`alternating` or `reversible`) -should be used. - -### Lane restrictions - -Like the segment a whole, each lane within a lane block can have its own -restrictions, for example [access restrictions](#access-restrictions), -[turn restrictions](#turn-restrictions) and -[speed limits](#speed-limits). - -Lane-level restrictions reuse the same concepts as segment-level -restrictions and are typically phrased in the same way, except that the -restriction is stipulated on an individual lane object rather than for -the segment's `road` property as a whole. - -### Lane connectivity - -Lane connectivity refers to the maneuvers available to navigate from the -lane the traveller is currently occupying to a connected lane within the -next lane block in the traveller's current travel direction. Lane -connectivity is a necessary element for granular turn-by-turn -navigation instructions. - -The Overture Maps transportation schema does not currently support lane -connectivity, but it is something we are actively working on and hoping -to release soon. - -### Resolving the applicable lane block - -The traffic lane structure of a road segment can be different at different -points along the segment, or at different times of the day, or both. -Consequently, instead of having a static lane block, road segments carry a list of lane block [rules](/schema/attributes/scoping-rules#rules-and-rule-based-properties) -in the optional `lanes` property. - -- A rule may be scoped [geometrically](/schema/attributes/scoping-rules#geometric-scoping-linear-referencing), -which allows linear referencing to be used to specify the portion of the -segment geometry where the lane block exists. -- A rule may also be scoped [temporally](/schema/attributes/scoping-rules#temporal-scoping-opening-hours), which allows the time of day that the lane block exists to be specified. Temporal scoping is useful for modeling cases like lanes which are used -for parking at off hours and traffic during peak hours. In such a case, -the lane block rule would be scoped to peak hours. - -As with all rule-based properties in the Overture schema, the [rule evaluation algorithm](/schema/attributes/scoping-rules#rule-evaluation-algorithm) must be applied to determine which lane block rule, if any, is -applicable at a given place and time along the road segment. Once the -determining rule for a certain scope is known, its rule block defines -the lane structure within that scope. - -The example below illustrates lane block resolution for two connected -segments. - -- The blue shaded, or southwesterly, segment is [oriented](/schema/attributes/transportation/shape-connectivity#directionality) toward the north-east. It has two geometrically-scoped lane block rules: - - The first rule, applying to the first two thirds of the - segment's length, establishes three lanes: one going - `backward` (SW), and two `forward` (NE). - - The second rule, applying to the last third of the segment, - establishes two lanes, one in either direction. -- The green shaded, or northeasterly, segment is oriented due west. It - has a single static lane block that applies to the whole segment - geometry at all times. - - - - -
- -
- - - -
- -*A segment with two [geometrically-scoped](/schema/attributes/scoping-rules#geometric-scoping-linear-referencing) lane blocks connected to a segment oriented in the opposite direction.* - -
- -
- -
- - - - - -{ ExampleLanesResolutionSegment01 } - - - - - -{ ExampleLanesResolutionConnector } - - - - - - -{ ExampleLanesResolutionSegment02 } - - - - diff --git a/docusaurus/docs/schema/attributes/transportation/shape-connectivity.mdx b/docusaurus/docs/schema/attributes/transportation/shape-connectivity.mdx deleted file mode 100644 index 2813866e9..000000000 --- a/docusaurus/docs/schema/attributes/transportation/shape-connectivity.mdx +++ /dev/null @@ -1,497 +0,0 @@ ---- -title: Shape and connectivity ---- - -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -# Shape and connectivity - -The Overture Maps `transportation` theme captures the physical shape and connectivity -of the transportation network through the interaction of the theme's two feature -types: segments and connectors. - - -
- -
- - - -
- -*A connector physically joining three segments.* - -
-
- -
- -## Connectors - -The [connector](/schema/reference/transportation/connector) feature type carries point geometry which describes a location where a physical connection between two or more segments occurs (or may occur in the -future). - -Connectors have no properties apart from geometry and standard Overture -feature properties. All other aspects of the transportation theme are -modeled on segments. - - - -## Segments - -The [segment](/schema/reference/transportation/segment) feature type carries `LineString` geometry which describes the physical shape of a section of the transportation network. A segment may represent an entity with a -tangible real-world existence, such as a paved road; or it may represent -an intangible entity, such as a ferry route, which has a well-known -shape but no observable presence in the real world. - -### Physical connectivity - -Two or more segments are physically connected at a given connector if -each segment's connectors property contains a reference to the -connector. - -The connector geometry's coordinates should preferably be contained -within the segment geometry's coordinates, in which case the connector -coordinates define the point of physical connection. This constraint -will always be met by official Overture data releases. Where this is not -possible, the point of physical connection is the closest point to the -connector coordinates which intersects the segment geometry. - -Conversely, two segments are not physically connected if their -connectors properties do not reference a shared connector, even if -their geometries overlap or even share a coordinate in common. - -Travel from a point on one segment to a point on another -physically-connected segment is allowed, unless limited by an explicit -restriction such as an access or turn restriction. - -All segments in official Overture Maps transportation data releases have a -minimum of two connectors, one at each end of the geometry, even if -those endpoint connectors are not attached to any other segment. This is -not a mandatory minimum and is not enforced by the schema. It is done -to allow new segments to connect into the existing network without -needing to change the properties of existing segments. - -### Start, end, and orientation - -The first coordinate in a segment's geometry is the start of the -segment and the last coordinate is the end. A segment is oriented -away from the start and toward the end. The examples below show two -segment geometries with identical coordinates, oriented in opposite -directions. - -
- -
- -```yaml -type: LineString -coordinates: - - [1, 0] # Start - - [0, 0] - - [-1, 0] # End -``` - -
- - - -
- -
- -
- -*This segment geometry is oriented due west.* - -
- -
-
- -
- -
- -
- -```yaml -type: LineString -coordinates: - - [-1, 0] # Start - - [0, 0] - - [1, 0] # End -``` - -
- - - -
- -
- -
- -*This segment geometry is oriented due east.* - -
- -
-
- -
- -
- - -### Heading - -Travel along a segment's geometry can follow one of two possible -headings: forward or backward. The forward heading proceeds -toward the end of the segment; while the backward heading proceeds -back toward the start of the segment. - -
- -
- - - -
- -*Travel heading along a segment.* - -
-
- -
- -### Directionality - - - - -🚧 We are developing a segment-level directionality concept similar to [lane directionality](/schema/attributes/transportation/roads#lane-directionality) to indicate what travel headings are allowed or prohibited along the segment. This effort is -ongoing, so please check back soon. - -### Sub-types - -Segment features have a `subtype` property whose value gives more -specific information about the segment's role within the transportation -network. - -The `subtype` property may be one of `road`, `rail`, or `water` but -only `road` is currently well defined. A `road` segment models any kind -of road, street, or trail, including a dedicated path for walking, -cycling and similar activities. For more information about `road` segments, see the page on [roads](/schema/attributes/transportation/roads). - -### Level (Z-order) - -Segment geometry is two-dimensional. In the real, 3D, world, however the -entities represented by segments can be above or below each other, as -may happen with tunnels, bridges, overpasses, and stacked multi-level -highway interchanges. To accurately render top-down 2D maps, it is -important to know the relative stacking order, or Z-order, of segments. - -Segment Z-order is given by the `level` property. A `level` value of -`0` indicates visual level, with positive numbers indicating above -visual level, negative numbers indicating below visual level, and in -general, a lesser number indicating a lower position in the stacking -order than a greater number. - -
- -
- - - -
- -*Ground level segments stacking above tunnel segments.* - -
-
- -
- -Note that two segments with different `level` values may be physically -connected, since `level` is an approximation for rendering and is not -meant be a precise indication of elevation at different points along the -segment. Connectors do not have a `level`. - - - -## Segmentation - -The term segmentation describes the process of converting upstream source data -into Overture transportation shape and connectivity data modeled as segments and -connectors. - -### Shape stability - -A primary goal of Overture Maps' segmentation process is to promote stability of -segment shape across Overture Maps data releases. For example, if a certain -real-world stretch of Main Street is represented by a single segment with -particular geometry in release 1, we will strive to avoid slicing the exact same -geometry up into two, three, or four segments in release 2. - -Note that aiming for segment shape stability categorically does not mean that -Overture Maps aims for a stable transportation dataset. On the contrary, we aim to -continuously improve data accuracy and coverage, and expect the transportation -network dataset to constantly evolve and grow as a result. Our goal is simply -to minimize unnecessary, semantically meaningless, changes in how the geometry -is sliced into segments across data releases. - -Several features of the transportation theme schema were designed to allow the -segmentation process to achieve its segment stability goal. These features -include: - -- [interior connectors](#interior-connectors). -- [geometrically scoped](#geometric-scoping) segment properties. - - - -### GERS ID stability - -The reason Overture Maps pursues shape stability is to improve the ability to assess whether two segments from different points in time (or from different upstream data -sources) represent the same real-world entity. Overture Maps' success at this assessment directly feeds into the stability and precision of [Global Entity Reference System (GERS)](https://docs.overturemaps.org/guides/gers) IDs assigned to segments. In turn, higher GERS ID stability and precision makes transportation theme data more useful for conflation. - -### Interior connectors - -A key feature of the Overture Maps transportation schema which enables shape -stability is the ability of segments to support connectors at interior positions -along their geometry, not only at their endpoints. The ability to add internal -connectors prevents the segmentation process from having to blindly follow every -split or join introduced in upstream source data. - -For example, imagine a square city block bordered by road on all four sides has -been mapped in the source data, but a back alley dividing the block along the -east-west axis has not. If the back alley is subsequently mapped in the source -data, the Overture segmentation process can connect to the transportation -network without having to subdivide any existing segments by simply introducing -internal connectors on the north-south road segments bordering the block to the east and west. As a result, the [GERS](https://docs.overturemaps.org/guides/gers) IDs of the north-south road segments remain as they were and no data needs to be re-conflated. - -
- -
- - - -
- -
- - - -
- -
- -
- -
- -*A square city block bordered by four roads before (left) and after (right) mapping the back alley using internal connectors.* - -
- -
- -
- -Note that in the above example, an official Overture Maps data release would insert -coordinates in the middle of the north-south segments, if they did not already -exist, because Overture Maps data releases will always ensure that every segment's -geometry includes all of its connectors. From a computer's perspective, this is -a very minor alteration of the segment's shape. - -### Geometric scoping - -Many segment properties may include a linear reference so that they apply only -to a part of the segment geometry. We refer to these linearly-referenced -property values as being geometrically scoped and discuss geometric scoping at greater length in the page on [scoped properties](/schema/attributes/scoping-rules). - -Geometric scoping allows the segmentation algorithm to avoid introducing -segment splits simply because a certain property has different values along -different parts of the geometry. Like interior connectors, geometrically-scoped -properties enable the segmentation process to make decisions that promote shape -stability, ultimately resulting in more precise and stable [GERS](https://docs.overturemaps.org/guides/gers) IDs and less churn in conflated data. - -
- -
- - - -
- -*A single segment with multiple geometrically-scoped speed limit values.* - -
-
- -
- -### Loops - -Although it is technically possible to use the Overture Maps schema to express a -segment forming a connected loop, such loops are considered invalid and will -never be produced by the segmentation algorithm. - -An illegal loop where one of a segment connects to the other end can be -corrected by splitting the segment and introducing a second connector to -maintain physical connectivity. An illegal self-crossing loop of degree *N* -can be corrected by splitting the segment into N pieces. - -
- -
- -
- - - -
- -
- - - -
- -
- -
- -
- -*An illegal loop connected at its endpoints (left) and a possible correction (right).* - -
- -
-
- -
- -
- -
- -
- - - -
- -
- - - -
- -
- -
- -
- -*An illegal self-crossing loop (left) and a possible correction (right).* - -
- -
-
- -
- -
diff --git a/docusaurus/docs/schema/attributes/transportation/travel-modes.mdx b/docusaurus/docs/schema/attributes/transportation/travel-modes.mdx deleted file mode 100644 index 7480b816e..000000000 --- a/docusaurus/docs/schema/attributes/transportation/travel-modes.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Travel modes ---- - -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -In the real world, a travel mode can be thought of intuitively as a way -of getting from point A to point B. Travel modes can include non-vehicle -modes (foot), vehicle modes (a bicycle or motor vehicle) and -occasionally more granular details (that motor vehicle might be -classified as a high occupancy vehicle or a heavy goods vehicle). - -Within the Overture Maps transportation theme schema model, this real-world -intuition translates to the following definition: a travel mode is a -recognized mode by which a person or thing may use a [segment](/schema/reference/transportation/segment) feature. - -## Understanding travel modes - -### Implied travel modes - -Every segment has an *implied* set of travel modes that are allowed to use the segment. For [road](/schema/attributes/transportation/roads) segments, this implied set derives -from the [road class](/schema/attributes/transportation/roads#road-class), as well as local rules, norms, and customs operative where the road segment is situated. - -Since this implied set depends on locality or jurisdiction, and is -susceptible of varying over time, the Overture Maps transportation schema -does not try to specify the implied set. Resolution of the implied set -is done by the specific application in the case where this level of -detail is important for its proper functioning. Note: an accurate routing -engine may need this information, whereas a 2D map render or a geocoder -likely do not. - -### General definitions - -Overture's recognized travel modes are defined in general terms that are -broadly applicable, for example `hov` is a high-occupancy vehicle and -`hgv` is a heavy goods vehicle. In most jurisdictions, these general -terms map to a concept that is in use within the jurisdiction, even -though the local name for the concept may vary, for example one -jurisdiction may say heavy goods vehicle and another may say -large goods vehicle. - -Despite being broadly applicable, travel modes may have different -definitions in different places and at different times. - -- in one jurisdiction, an `hgv` might mean any vehicle with a gross - vehicle weight in excess of 3.5 tonnes (3,500 kg). In another place, - an `hgv` might have a gross vehicle weight of at least 10,001 lbs. -- in one jurisdiction, an `hov` might require a minimum of 2 passengers - while in another place it might have a higher minimum passenger count, - or include battery-electric vehicles, or exclude certain classes of - vehicle or usage. - -As a consequence of the variance in definition across place and time, -Overture gives only general definitions for travel modes, leaving -precise definition to those applications that require them. - -### When is a travel mode recognized? - -A travel mode is recognized by the Overture transportation schema when -it becomes part of the [`mode`](https://github.com/OvertureMaps/schema/blob/5f82f1d6a916031cb32730e1fac7e1a353f10c60/schema/transportation/segment.yaml#L103) -enumeration. This enumeration in early versions of the schema was relatively small and contained only travel modes that are generally-applicable both across jurisdictions and over time. As development of the schema has progressed, this list has grown and will to continue to expand as the world changes and new information arises. - -Our criteria for recognizing a proposed new travel mode are: - -- the proposed new travel mode should represent a generally-accepted - concept meaning that the concept exists in many places with roughly - the same definition. -- the proposed new travel mode should be referred to with well-known - sign iconography or sign text in those jurisdictions where the - concept exists; and this iconography or sign text is preferably - somewhat consistent across many jurisdictions and over time. -- it must be possible to give a relatively precise definition to the - proposed new travel mode and explain how it differs from, or - *intersects* with, other similar travel modes which are already - recognized in the Overture schema. -- the proposed new travel mode should preferably not be trivially - expressible using another existing [scoping property](/schema/attributes/scoping-rules#scoped-values-and-scoping-properties).(*An example of such a trivially-expressible concept might be a three-axle vehicle which is more appropriately phrased as `vehicle: [{dimension: axle_count, comparison: equal_to, value: 3}]`.*) -- the proposed new travel mode must be supported by existing data in at - least one of Overture's upstream data sources. - -There is a risk that the above-described approach will be too slow to -adapt to our users' needs in a vast, ever-changing world. One possible -avenue to mitigate this risk is supporting [custom extensions](#should-we-support-extension-travel-modes) to the built-in list of recognized travel modes. - -## Travel mode schema - -### Scoping to travel modes - -Travel modes can be used to change the scope of scoped and rule-based -properties within the schema. For example, they can affect the scope of access restrictions, turn restrictions, or speed limits on [road](/schema/attributes/transportation/roads) segments. Since travel modes are expressed via scoping properties, we recommend you read the section on [scoped and rule-based properties](/schema/attributes/scoping-rules) before proceeding further. - -#### Travel mode scoping: `mode` - -The scoping property `mode` controls whether a given scoped property -applies when a given travel mode is being used for traveling along a -road segment. - -If `mode` is provided, it must be a non-empty array of string values -identifying travel modes, and is interpreted as a set. Values must be -unique, but order is not important. - -#### Vehicle attribute scoping: `vehicle` - -Because travel modes are an fuzzy concept, there are inevitably areas -of overlap between with the more precise, but more limited, `vehicle` -scoping property which is used for [vehicle attributes scoping](/schema/attributes/scoping-rules#vehicle-attributes-scoping). Where there is potential overlap, the method of scoping used in Overture Maps data releases will depend on how the upstream data source has expressed the equivalent concept. Where there is choice, it is preferable to select the scoping method that most accurately reflects the intention expressed on local signage. - -#### Similar scoping properties: `using` and `recognized` - -The scoping properties `using` and `recognized` express concepts that -are meant to be orthogonal to (completely separate from) travel modes. - -- The `using` property indicates [purpose of use](/schema/attributes/scoping-rules#purpose-of-use-scoping) scoping, which relates to the purpose for which the person or thing travelling is using a given segment of the transportation network. Travel modes should ideally not embed a purpose of use. -- The `recognized` property indicates [status scoping](/schema/attributes/scoping-rules#status-scoping-membership-in-a-recognized-group), which relates to a recognized status given to the person or thing traveling, where the recognized status is distinct from the mode of travel itself. Travel modes should ideally not embed a status. - -### The travel modes taxonomy - -Travel modes in Overture Maps form a shallow taxonomy. Some travel modes are -more general, while others are more specific, and a more general travel -mode may contain a more specific one. For example, the general travel -mode `vehicle` contains the more specific mode `motor_vehicle`. The -taxonomy supported in our draft schema `v0.8.0` can be visualized in the -diagram below. - -
- -
- - - -
- -
- -
- -*The Overture travel modes taxonomy.* - -
- -
- -
- -As many of the above travel modes draw on the body of knowledge -accumulated in relation to OpenStreetMap -[transport mode access restrictions](https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions), -Overture Maps would like acknowledge a intellectual debt to the OSM community in -relation to travel modes as well as to other aspects of the transportation schema. - -## Open questions - -This section discusses some open questions we are debating internally with -regard to travel modes. We would love to hear [your feedback](https://github.com/OvertureMaps/schema/discussions) on these questions and any others you may have. - -### Minimum required travel modes - -We're not yet certain on the minimum set of recognized travel modes is -that will make the Overture Transportation schema as usable as possible -to as broad an audience as possible. What do you think we are missing? - -### Should we support extension travel modes? - - - -We live in a time of rapid technological and regulatory change in -the transportation space. No matter how quickly we extend the travel modes in the Overture Maps schema it will always be behind the real world with regard to some technologies, customs, or local rules. - -One way to support users working at the cutting edge is to allow custom extensions to -the list of travel modes. If we did this consistently with how extension -properties -work for features, we could, for example, allow travel mode names with -the `ext_*` to be ignored by the schema validation rules. - -### Internal consistency - -In [another section of this documentation](#vehicle-attribute-scoping-vehicle), we alluded to an overlap between the fuzzy concept of travel modes and vehicle attribute -scoping. We're aware of this overlap and view it as limited but inevitable. - -Our intention is to reduce or eliminate the overlap between travel modes and the other [similar scoping properties](#similar-scoping-properties-using-and-recognized) -(`using` and `recognized`). One area where we may have been unsuccessful -is the `emergency` travel mode in the [current taxonomy](#the-travel-modes-taxonomy). -Arguably, `emergency` should be removed from the taxonomy, and an -`as_emergency_responder` should be included in the status values enumeration for the `recognized` property.