diff --git a/docusaurus/docs/gers/gers.mdx b/docusaurus/docs/gers/gers.mdx deleted file mode 100644 index 974ad872..00000000 --- a/docusaurus/docs/gers/gers.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Global Entity Reference System -label: GERS ---- - -## Overview of GERS - -Overture's Global Entity Reference System (GERS) is a framework for structuring, encoding and matching map data to a shared universal reference. Overture is building this common ID system to solve the difficult problem of integrating geospatial datasets; to make it easier to share and sell map data; and to enable cooperation among companies, non-profits, government agencies and other organizations. - -GERS provides a mechanism to conflate datasets, matching one or more features via unique IDs. For example, two geospatial datasets each containing a polygon that represents the footprint of the Empire State Building can be easily matched because both polygons will contain the same GERS ID. The resulting dataset will have a single polygon feature, with one GERS ID, that represents the real-world entity known as "New York's Empire State Building." - -## What is an entity? -Overture defines an entity as a physical thing or concept in the real world, represented as a feature in a geospatial dataset. It could be a segment of road, a city boundary, a grocery store, a building or a park. Overture assigns unique IDs to these features. In most cases it's helpful to think of an entity and a feature as the same thing, but in practice it can be more complicated. An entity in the world could be represented by multiple features in a dataset, and a feature in a dataset might be a representation of multiple entities in the world. For example, a school building and its entrances and exits might be considered a single entity in the world but could be represented as multiple features in a dataset, each feature with its own GERS ID. - -## What does a GERS ID look like? - -Each unique ID generated by Overture is 128 bits. Here is an example query that outputs a list of GERS IDs for five building features in Overture's March 2024 data release. - -```sql -D SET s3_region='us-west-2'; -D SELECT id FROM read_parquet('s3://overturemaps-us-west-2/release/2024-03-12-alpha.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 - -## Using GERS - -Currently, Overture's partners are using GERS in two ways: - -1. **Contributing data.** If an organization contributes data to the Overture Maps Foundation, the Overture engineering team matches the features in that dataset to existing features in the current Overture datasets. Matched features are assigned an existing GERS ID. New features may be assigned a new GERS ID. -2. **Associating data.** Users can independently conflate their own data with a current Overture dataset, identifying matches among features in both datasets. Only the features in the associated dataset that match an existing feature in the Overture data corpus can be assigned a GERS ID. The associated data will not become part of the Overture corpus, but it will become GERS-enabled data, ready to be matched to any of the available datasets in the Overture data ecosystem. - -See the [scenarios](scenarios) section of this documentation for more detailed examples of GERS use cases. Feedback on GERS is welcome on [GitHub](https://github.com/OvertureMaps/schema/discussions). - -## Licensing -Overture's data themes and schema are licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). GERS IDs are licensed under [CDLA Permissive v 2.0](https://cdla.dev/permissive-2-0/). Data that are associated with the themes through GERS can carry different licenses. However, if the data associated though GERS with an [ODbL](https://opendatacommons.org/licenses/odbl/) licensed theme constitutes a derivative dataset, it must be licensed under ODbL. See [OpenStreetMap Community Guidelines](https://osmfoundation.org/wiki/Licence/Community_Guidelines/Collective_Database_Guideline_Guideline) for definitions of a derivative database. \ No newline at end of file diff --git a/docusaurus/docs/gers/scenarios.mdx b/docusaurus/docs/gers/scenarios.mdx deleted file mode 100644 index 3d03330f..00000000 --- a/docusaurus/docs/gers/scenarios.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Scenarios ---- - -## Live Traffic Data -A company providing live traffic data operates by ingesting sensor data and then conflating, cleaning, and calculating traffic density for a variety of locations through proprietary methods. Ultimately, they provide customers with a data feed of live traffic conditions for a monthly access fee. - -**Before GERS + Overture**: This company maintains a version of the OpenStreetMap road network to which they associate their traffic density information. The data-feed product is made of GeoJSON features, each with a LineString geometry representing a segment of the road (from OSM) and properties including a timestamp and traffic information along that section of the road. Using OSM is preferred because the geometries in the data feed will match road segment geometries for any customer using OSM. However, a more computationally expensive geospatial match operation is required to associate the traffic information with the road network. - -**With GERS + Overture**: The company uses the Overture road network internally. When they associate their traffic information with a road segment, they can publish the data feed with a GERS ID that represents the given road segment. Consumers that are also using Overture can then match this data by `GERS ID` to the Overture road segment, without needing to perform any geospatial computation. Making the process even smoother, thehe geometry of the road segment can be omitted from the feed, since the ID will match for any customer also using the Overture road network. - -**What if the company has proprietary (better) road segment data extracted from their sensor network that they do not / cannot share?** - -Because these road segments are not shared with Overture, they can’t be assigned a `GERS ID`. The ID is of little value to these segments because they do not exist in other datasets, so conflating or matching them is meaningless. - -However, by sharing _just the new road segment_ geometries with Overture (not the entire proprietary traffic feed), Overture will add it to the Overture corpus and generate GERS IDs accordingly. The Overture road network will be improved and 100% of the company's data feed can become GERS-enabled. - -## Place enrichment -Venues – both private and public – are often an atomic unit in data environments. For example: - -- Businesses organize customer records based on home addresses. -- Municipalities map property information and status by parcel identifiers. -- Insurance companies use various building identifiers to organize policy information. -- Retailers organize and analyze market opportunities and challenges through their own competitive retail outlets. -- Delivery companies optimize services by destination address. - -Despite these common use cases, location is under-utilized as an organizing mechanism for data, applications and analytics. Addresses are often inconsistent, messy or simply wrong. Coordinate pairs are precise but often inaccurate and can be difficult to cluster correctly. Many organizations lack the resources to run their own GIS infrastructure, while others relegate GIS tasks toa small, specialty team at the fringes of the group. - -It can be a huge unlock, then, to associate location data with easy-to-use standard identifiers. When this happens, data owners and consumers can use locations as a common-denominator, which encourages data sharing and enriches the broader data pipeline. GERS can make location as valuable and universally useful as phone numbers or email addresses. - -#### Scenario -A data analyst at a pet-focused retail company is evaluating a metropolitan area in order to understand supply and demand in their market. The pet company has 1st-party customer data organized by delivery address, as well as addresses for their retail locations and a list of potential store locations provided by their real estate team. The company’s data infrastructure team has staged an Overture dataset in their environment, which they use as “ground truth” for the region. The company's executive team has asked the data analyst to review the potential store locations, recommend the most valuable sites for new stores and model the expected market impact if they opened a new store at each site. - -The data analyst plans on using Overture's GERS to quickly onboard necessary external data for their analysis. - -- The analyst matches customer residences and store locations to GERS by conflating street addresses with venues in their local Overture basemap. -- She then requests retail foot traffic data and residential demographic data from external vendors, specifying the data should be organized by GERS ID. -- The external data vendors maintain a version of their data products keyed off `GERS ID` (matched via a conflation pipeline that accounts for street address, business name, and coordinate pair), which they provide to the requesting analyst. -- The analyst is able to quickly ingest and join the external datasets without relying on the company’s data infrastructure team, thanks to the simplicity of joining using consistent GERS identifiers. -- The analyst performs her work, taking into account the company’s current customer base, market potential, competitive footprint and more. - -This is an example of ad-hoc enrichment — enrichment that occurs within the confines of a single project. However, this company could also subscribe to other datasets that would be managed by the data ops or infrastructure teams. GERS brings significant benefits in this scenario as well, because it reduces the time to usage, allows for easy updates (vendors simply ship diff files keyed to GERS ID) and facilitates the sharing of data both internally and externally. diff --git a/docusaurus/docs/gers/terminology.mdx b/docusaurus/docs/gers/terminology.mdx deleted file mode 100644 index 6f61aafb..00000000 --- a/docusaurus/docs/gers/terminology.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Terminology ---- - -| Term | Description | -| - | - | -| GERS ID| A unique ID representing a real-world `entity`, such as a building, road segment, parking lot, or even a park bench. | -| Contributed dataset | A dataset maintained by Overture that a foundation member has contributed to Overture. These datasets are converted to the appropriate Overture schema for their type. For GERS-enabled layers (buildings, transportation, etc.), data is given a GERS ID. These data are now forever part of the Overture Corpus| -| Overture dataset | An open dataset that is registered with Overture and thereby is included in GERS, but not maintained by Overture. | -| Outside dataset / proprietary data | A dataset outside of Overture is proprietary data that a company or individual does not want to make fully open, but desires to associate with Overture data.

The dataset owner can conflate their data against the current Overture map to identify any existing GERS IDs that map to their own data, but they cannot generate new GERS IDs for entities that do not already exist in the Overture corpus. | diff --git a/docusaurus/docs/overview/feature-model/geojson.mdx b/docusaurus/docs/overview/feature-model/geojson.mdx deleted file mode 100644 index b885fd51..00000000 --- a/docusaurus/docs/overview/feature-model/geojson.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -slug: /overview/names -title: GeoJSON mental model ---- - -_Coming Soon_ diff --git a/docusaurus/docs/overview/feature-model/index.mdx b/docusaurus/docs/overview/feature-model/index.mdx deleted file mode 100644 index 44ce403f..00000000 --- a/docusaurus/docs/overview/feature-model/index.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Feature Model ---- - -## Key Concepts - -Overture data is described using the [simple feature model](https://www.ogc.org/standard/sfa/) specified by the Open Geospatial Consortium. Each feature includes a geometric object with a unique ID and associated properties. For example, the Town Hall building in Seattle is represented in the Overture buildings dataset as a [GeoJSON](https://geojson.org/) feature that looks like this: - - - -```json -{ - "id": "08828d542c9fffff02ffffff1953aec1", - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [ [-122.3301821, 47.6090116],[-122.3301197, 47.6089409],[-122.3300642, 47.6088779],[-122.3300094, 47.6088158],[-122.329729, 47.6089282],[-122.3297466, 47.6089481],[-122.3296561, 47.6089844],[-122.3296934, 47.6090266],[-122.3297562, 47.6090978], [-122.3298113, 47.6091603],[-122.3298611, 47.6092168],[-122.3299517, 47.6091804],[-122.329963, 47.6091932],[-122.3299793, 47.6091867],[-122.3301728, 47.6091091],[-122.3301916, 47.6091016],[-122.3301714, 47.6090787],[-122.330223, 47.609058] ] - ] - }, - "properties": { - "theme": "buildings", - "type": "building", - "version": 0, - "update_time": "2023-01-30T00:04:13.000Z", - "height": 22.7, - "num_floors": 3, - "class": "civic", - "names": { - "primary": "Town Hall Seattle" - }, - "sources": [ - { - "property": "dataset", - "dataset": "OpenStreetMap," - "record_id": "w140675988@10" - }, - { - "property": "/properties/height", - "dataset": "USGS Lidar" - } - ] - } -} -``` - -## Features Represent Entities -Features in the Overture corpus represent entities in the real world. An entity is a physical thing or concept: a segment of road, a city boundary, a grocery store, a building or a park. Overture assigns unique IDs, called GERS IDs, to these features. In most cases it's helpful to think of an entity and a feature as the same thing, but in practice it can be more complicated. An entity could be represented by multiple features in a geospatial dataset, and a feature in a dataset might be a representation of multiple entities. For example, a school building and its entrances and exits might be considered a single entity in the real world but could be represented as multiple features in a dataset, each feature with its own GERS ID. - - -## Common Properties - -The Overture corpus has a core set of properties for every feature. -- `theme`: -themes are top-level categories of map features. -- `type`: a theme may have multiple types of features; the transportation theme, for example, has both segments and connectors. -- `sources`: this is the array of information about the data sources from which a feature's attributes originated. -- `version`: the version number of a feature is incremented in each Overture release whenever the geometry or attributes of the feature change. -- `update_time`: the timestamp indicates when the feature was last updated. - -Different theme and type values will contribute additional properties to the schema. For example, in the building described above, the buildings `theme` with building `type` has a `class` property that defines what kind of building it is, in this case a civic building. It also has an optional `height` property. You can find more detail about the properties associated with each theme and type in the Schema Themes and Schema Reference sections of this documentation. - - -## Complex Attributes - -Some feature properties are quite complex and require further explanation in the documentation. - -- **[Global Entity Reference System (GERS) IDs](../../gers/gers.mdx)**: the [Global Entity Reference System](/gers) is responsible for handling persistent identification across entities in the Overture corpus. -- **[Names](names)**: where applicable, complex attributes such as names will always use the same schema across all themes. -- **[Scoped and rule-based properties](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. - -## Extensible Attributes - -Any additional top-level property prefixed with `ext_` may be added to an Overture feature, usually via the conflation of an external dataset and an Overture dataset. - -## Measurements - -Measurements of real-world objects and features follow [The International System of Units (SI)](https://www.bipm.org/en/publications/si-brochure): heights, widths, lengths, etc. In the Overture schema, these values are provided as scalar numeric value without units such as feet or meters. Overture does this to maximize consistency and predictability. - -Quantities specified in regulatory rules, norms and customs follow local specifications wherever possible. In the schema, these values are provided as two-element arrays where the first element is the scalar numeric value and the second value is the units. Overture uses local units of measurement -- feet in the United States and meters in the EU, for example. - - -## Data Formats - -Overture describes data using a GeoJSON mental model and represents data as GeoJSON features. Overture distributes data as [GeoParquet](https://geoparquet.org/). This documentation includes many examples of how to work with data stored in GeoParquet files. diff --git a/docusaurus/docs/overview/feature-model/names.mdx b/docusaurus/docs/overview/feature-model/names.mdx deleted file mode 100644 index aa9896c7..00000000 --- a/docusaurus/docs/overview/feature-model/names.mdx +++ /dev/null @@ -1,49 +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"; - -## Common Names Schema - -Named entities in Overture share a common name 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 primary, localized name of a feature. Example: "Empire State Building" or "Eiffel Tower" - -```yaml -names: - primary: The White House -``` - - -### Variations - -#### `common` -Common name variations are translations of a name. - -```yaml -names: - common: - es: La Casa Blanca -``` - -#### `rules` -Additional variations such as _official_, _alternate_, or _short_ name variations exist as `rules`. - -```yaml -names: - rules: - - variant: official - value: The White House - - variant: alternate - value: White House -``` - -## Official Names Schema - - diff --git a/docusaurus/docs/overview/feature-model/scoping-rules.mdx b/docusaurus/docs/overview/feature-model/scoping-rules.mdx deleted file mode 100644 index a546e714..00000000 --- a/docusaurus/docs/overview/feature-model/scoping-rules.mdx +++ /dev/null @@ -1,452 +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 transportation have -only a partial application, meaning they don't apply everywhere, or -they don't apply at all times, or to all travellers, 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 Transportation theme's schema model of the transportation -network 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](/themes/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 transportation 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](/themes/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](/themes/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: { ... } }` 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". - - - - - - -## 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: - 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/overview/index.mdx b/docusaurus/docs/overview/index.mdx deleted file mode 100644 index 976978b6..00000000 --- a/docusaurus/docs/overview/index.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: Introduction to the Overture Map Foundation's documentation -slug: / -title: Introduction ---- - -## Overture Map Overview - -The Overture Map consists of global datasets structured by a unified schema, referenced with a universal identification system and available to everyone under a [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode) license. - -Overture currently offers [data](https://github.com/OvertureMaps/data) across five themes: **buildings, places, transportation, admins and base**. - -In this documentation, you'll find explanatory and reference material about the Overture Map [feature model](/overview/feature-model), [schema](./reference) and data [themes](./themes) - -## The Overture Maps Foundation's Vision -**Address the core, enable the periphery.** The Overture schema doesn't solve every problem. It offers complete, out-of-the-box solutions for the most fundamental "core" use cases. At the same time, the schema's extensible structure enables a wide range of other use cases ("the periphery"). - -**Invent across the gap.** The mapping community already has access to many excellent tools, standards and practices. The Overture schema reuses these existing solutions to maximize compatibility and focus on solving unaddressed pain points. - -**Backward-compatible is forward-compatible.** No design is future-proof, but good designs stay relevant by adding features without breaking what already works. The Overture schema can be enhanced in a backward-compatible way. - -**Always open.** The Overture schema and data formats aim for compatibility with free and open-source tools, avoiding dependency on proprietary technologies. - -## Licensing - -Overture's data themes and schema are licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). GERS IDs are licensed under [CDLA Permissive v 2.0](https://cdla.dev/permissive-2-0/). Data associated with the themes through GERS can carry different licenses. However, if the data associated though GERS with an [ODbL](https://opendatacommons.org/licenses/odbl/) licensed theme constitutes a derivative dataset, it must be licensed under ODbL. See [OpenStreetMap Community Guidelines](https://osmfoundation.org/wiki/Licence/Community_Guidelines/Collective_Database_Guideline_Guideline) for definitions of a derivative database. diff --git a/docusaurus/docs/reference/admins/administrative-boundary.mdx b/docusaurus/docs/reference/admins/administrative-boundary.mdx index 89f18570..a3522106 100644 --- a/docusaurus/docs/reference/admins/administrative-boundary.mdx +++ b/docusaurus/docs/reference/admins/administrative-boundary.mdx @@ -17,18 +17,20 @@ import TabItem from '@theme/TabItem'; Administrative boundaries are borders surrounding administrative [localities](locality). - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry TypeLineString
Themeadmins
Typeadministrative_boundary
Geometry TypeLineString
Themeadmins
Typeadministrative_boundary
An administrative boundary is typically an officially defined border diff --git a/docusaurus/docs/reference/admins/locality.mdx b/docusaurus/docs/reference/admins/locality.mdx index ebabc3e8..efab752d 100644 --- a/docusaurus/docs/reference/admins/locality.mdx +++ b/docusaurus/docs/reference/admins/locality.mdx @@ -15,9 +15,10 @@ import AdminLocalityExample from '!!raw-loader!@site/docs/_examples/admins/local Localities are populated areas that are named. -Area polygons of localities, if known, are given by [locality area](locality-area) features. +Area polygons of localities, if known, are given by [locality area](locality_area) features. + @@ -30,6 +31,7 @@ Area polygons of localities, if known, are given by [locality area](locality-are +
Geometry Type PointType locality
## Sub-types @@ -39,10 +41,12 @@ A locality may have one of two possible sub-types. - - - - + + + + + +
subtypeadministrative_locality
subtypeadministrative_locality
Administrative localities represent countries and hierarchical @@ -58,10 +62,12 @@ The borders of administrative localities, if known, are given by - - - - + + + + + +
subtypenamed_locality
subtypenamed_locality
Named localities represent named areas that are not formally part of diff --git a/docusaurus/docs/reference/admins/locality-area.mdx b/docusaurus/docs/reference/admins/locality_area.mdx similarity index 80% rename from docusaurus/docs/reference/admins/locality-area.mdx rename to docusaurus/docs/reference/admins/locality_area.mdx index 4c26fd3d..c9132270 100644 --- a/docusaurus/docs/reference/admins/locality-area.mdx +++ b/docusaurus/docs/reference/admins/locality_area.mdx @@ -1,5 +1,5 @@ --- -title: locality area +title: locality_area --- import CodeBlock from '@theme/CodeBlock'; @@ -19,18 +19,20 @@ Property `locality_id` points at [locality](locality) feature that this area belongs to. - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry TypePolygon or MultiPolygon
Themeadmins
Typelocality_area
Geometry TypePolygon or MultiPolygon
Themeadmins
Typelocality_area
## Schema diff --git a/docusaurus/docs/reference/base/infrastructure.mdx b/docusaurus/docs/reference/base/infrastructure.mdx index 986dc086..7ba487ac 100644 --- a/docusaurus/docs/reference/base/infrastructure.mdx +++ b/docusaurus/docs/reference/base/infrastructure.mdx @@ -18,6 +18,7 @@ import TabItem from '@theme/TabItem'; Features in the infrastructure type come from OpenStreetMap features with tags like `aeroway`, `communication`, `bridge`, `man_made`, or `tower`. These features include bridges, aerialways, and airports. + +
Geometry Type @@ -32,6 +33,7 @@ Features in the infrastructure type come from OpenStreetMap features with tags l Type infrastructure
diff --git a/docusaurus/docs/reference/base/land.mdx b/docusaurus/docs/reference/base/land.mdx index dc1f4600..d848ae6a 100644 --- a/docusaurus/docs/reference/base/land.mdx +++ b/docusaurus/docs/reference/base/land.mdx @@ -18,6 +18,7 @@ import TabItem from '@theme/TabItem'; Features in the land theme come from OpenStreetMap features with the `natural` tag. + +
Geometry Type @@ -32,6 +33,7 @@ Features in the land theme come from OpenStreetMap features with the `natural` t Type land
diff --git a/docusaurus/docs/reference/base/land-use.mdx b/docusaurus/docs/reference/base/land_use.mdx similarity index 80% rename from docusaurus/docs/reference/base/land-use.mdx rename to docusaurus/docs/reference/base/land_use.mdx index cb8abd10..6983d6cf 100644 --- a/docusaurus/docs/reference/base/land-use.mdx +++ b/docusaurus/docs/reference/base/land_use.mdx @@ -1,5 +1,5 @@ --- -title: land use +title: land_use --- import CodeBlock from '@theme/CodeBlock'; @@ -19,20 +19,22 @@ import TabItem from '@theme/TabItem'; Features in the land use theme come primarily from OpenStreetMap features containing the `landuse` tag. - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry Type - Point, LineString, Polygon, or MultiPolygon -
Themebase
Typeland_use
Geometry Type + Point, LineString, Polygon, or MultiPolygon +
Themebase
Typeland_use
diff --git a/docusaurus/docs/reference/base/water.mdx b/docusaurus/docs/reference/base/water.mdx index 281accc7..7b2a3a10 100644 --- a/docusaurus/docs/reference/base/water.mdx +++ b/docusaurus/docs/reference/base/water.mdx @@ -19,20 +19,22 @@ import TabItem from '@theme/TabItem'; Features in the water theme are from OpenStreetMap features with the `natural=water` tag. - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry Type - Point, LineString, Polygon, or MultiPolygon -
Themebase
Typewater
Geometry Type + Point, LineString, Polygon, or MultiPolygon +
Themebase
Typewater
diff --git a/docusaurus/docs/reference/buildings/building.mdx b/docusaurus/docs/reference/buildings/building.mdx index c49200ec..de332d8f 100644 --- a/docusaurus/docs/reference/buildings/building.mdx +++ b/docusaurus/docs/reference/buildings/building.mdx @@ -20,18 +20,20 @@ import TabItem from '@theme/TabItem'; Buildings are human-made structures with roofs or interior spaces that are permanently or semi-permanently in one place ([OSM building definition](https://wiki.openstreetmap.org/wiki/Key:building)). - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry TypePolygon or MultiPolygon
Themebuildings
Typebuilding
Geometry TypePolygon or MultiPolygon
Themebuildings
Typebuilding
The most basic form of a _building_ feature in the Overture Schema. The geometry is expected to be the most outer footprint (or roofprint if traced from satellite/aerial imagery) of a building. diff --git a/docusaurus/docs/reference/buildings/building_part.mdx b/docusaurus/docs/reference/buildings/building_part.mdx index 03648d19..ec760376 100644 --- a/docusaurus/docs/reference/buildings/building_part.mdx +++ b/docusaurus/docs/reference/buildings/building_part.mdx @@ -16,18 +16,20 @@ import TabItem from '@theme/TabItem'; # Building part - - - - - - - - - - - - + + + + + + + + + + + + + +
Geometry TypePolygon or MultiPolygon
Themebuildings
Typebuilding_part
Geometry TypePolygon or MultiPolygon
Themebuildings
Typebuilding_part
diff --git a/docusaurus/docs/reference/divisions/boundary.mdx b/docusaurus/docs/reference/divisions/boundary.mdx new file mode 100644 index 00000000..e94bdeca --- /dev/null +++ b/docusaurus/docs/reference/divisions/boundary.mdx @@ -0,0 +1,65 @@ +--- +title: boundary +--- + +import CodeBlock from '@theme/CodeBlock'; +import JSONSchemaViewer from "@theme/JSONSchemaViewer"; +import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" +import yamlLoad from "@site/src/components/yamlLoad" +import divisions_boundary_schema from '!!raw-loader!@site/docs/_schema/divisions/boundary.yaml'; +import divisions_boundary_example_land from '!!raw-loader!@site/docs/_examples/divisions/boundary/land_region.yaml'; +import divisions_boundary_example_maritime from '!!raw-loader!@site/docs/_examples/divisions/boundary/maritime_country.yaml'; +import divisions_disputed_boundary_example_both from '!!raw-loader!@site/docs/_examples/divisions/boundary/disputed_both.yaml'; +import divisions_disputed_boundary_example_left from '!!raw-loader!@site/docs/_examples/divisions/boundary/disputed_left.yaml'; +import divisions_disputed_boundary_example_right from '!!raw-loader!@site/docs/_examples/divisions/boundary/disputed_right.yaml'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Boundary + +A boundary is a border between [divisions](division). + + + + + + + + + + + + + + + + +
Geometry TypeLineString
Themedivisions
Typeboundary
+ +A boundary is typically an officially-defined border +between two [divisions](division). In light of +geopolitical issues, some boundaries represent standalone +disputed or treaty lines and therefore do not coincide with the border +of a division. + +## Schema + + + + + + + {divisions_boundary_schema} + + + +## Examples + + + + { JSON.stringify(yamlLoad(divisions_boundary_example_land), null, 2) } + + + { JSON.stringify(yamlLoad(divisions_disputed_boundary_example_both), null, 2) } + + diff --git a/docusaurus/docs/reference/divisions/division.mdx b/docusaurus/docs/reference/divisions/division.mdx new file mode 100644 index 00000000..564772ef --- /dev/null +++ b/docusaurus/docs/reference/divisions/division.mdx @@ -0,0 +1,106 @@ +--- +title: division +--- + +import CodeBlock from '@theme/CodeBlock'; +import JSONSchemaViewer from "@theme/JSONSchemaViewer"; +import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" +import yamlLoad from "@site/src/components/yamlLoad" +import divisions_division_schema from '!!raw-loader!@site/docs/_schema/divisions/division.yaml'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import division_example_country from '!!raw-loader!@site/docs/_examples/divisions/division/country.yaml'; +import division_example_region from '!!raw-loader!@site/docs/_examples/divisions/division/region.yaml'; +import division_example_hierarchies_multiple from '!!raw-loader!@site/docs/_examples/divisions/division/hierarchies-multiple.yaml'; +import division_example_dependency from '!!raw-loader!@site/docs/_examples/divisions/division/dependency.yaml'; +import division_example_population from '!!raw-loader!@site/docs/_examples/divisions/division/population.yaml'; +import division_example_perspectives from '!!raw-loader!@site/docs/_examples/divisions/division/perspectives.yaml'; + +# Division + +A division is a recognized official or non-official organization of people as seen from a given political perspective. Examples of divisions include countries, provinces, cities, towns and neighborhoods. + + + + + + + + + + + + + + + + + +
Geometry TypePoint
Themedivisions
Typedivision
+ +## Sub-types + +A division may have one of two possible sub-types: `country` or `region`. + + + + + + + + + + +
subtypecountry
+ + +The border of a country, if known, is given by +[boundary](boundary) features. + + + + + + + + + + +
subtyperegion
+ +A region represents a named area that is not formally part of +the hierarchical subdivision of a country. + + + + +## Schema + + + + + + + {divisions_division_schema} + + + +## Examples + + + + { JSON.stringify(yamlLoad(division_example_country), null, 2) } + + + { JSON.stringify(yamlLoad(division_example_region), null, 2) } + + + { JSON.stringify(yamlLoad(division_example_hierarchies_multiple), null, 2) } + + + { JSON.stringify(yamlLoad(division_example_population), null, 2) } + + + { JSON.stringify(yamlLoad(division_example_perspectives), null, 2) } + + diff --git a/docusaurus/docs/reference/divisions/division_area.mdx b/docusaurus/docs/reference/divisions/division_area.mdx new file mode 100644 index 00000000..769bfd2b --- /dev/null +++ b/docusaurus/docs/reference/divisions/division_area.mdx @@ -0,0 +1,98 @@ +--- +title: division_area +--- + +import CodeBlock from '@theme/CodeBlock'; +import JSONSchemaViewer from "@theme/JSONSchemaViewer"; +import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" +import yamlLoad from "@site/src/components/yamlLoad" +import divisions_division_area_schema from '!!raw-loader!@site/docs/_schema/divisions/division_area.yaml'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import division_area_example_country_land from '!!raw-loader!@site/docs/_examples/divisions/division_area/country_land.yaml'; +import division_area_example_region_land from '!!raw-loader!@site/docs/_examples/divisions/division_area/region_land.yaml'; +import division_area_example_country_maritime from '!!raw-loader!@site/docs/_examples/divisions/division_area/country_maritime.yaml'; + + +# Division Area + +A division area is a polygon that represents the land or maritime area associated with a [division](division). + + + + + + + + + + + + + + + + + +
Geometry TypePolygon or MultiPolygon
Themedivisions
Typedivision_area
+ +## Sub-types + +Like a division, a division area may have one of two possible sub-types: `country` or `region`. + + + + + + + + + + +
subtypecountry
+ + +The border of a country, if known, is given by +[boundary](boundary) features. + + + + + + + + + + +
subtyperegion
+ +A region represents a named area that is not formally part of +the hierarchical subdivision of a country. + + + + +## Schema + + + + + + + {divisions_division_area_schema} + + + +## Examples + + + + { JSON.stringify(yamlLoad(division_area_example_country_land), null, 2) } + + + { JSON.stringify(yamlLoad(division_area_example_country_maritime), null, 2) } + + + { JSON.stringify(yamlLoad(division_area_example_region_land), null, 2) } + + diff --git a/docusaurus/docs/reference/index.mdx b/docusaurus/docs/reference/index.mdx new file mode 100644 index 00000000..e227851e --- /dev/null +++ b/docusaurus/docs/reference/index.mdx @@ -0,0 +1,13 @@ +--- +title: Schema Reference +slug: / +--- + +This section includes the reference documentation for Overture's data themes: admins, base, buildings, divisions, places and transportation. For an overview of each data theme with examples and use cases, see our user guides at [docs.overturemaps.org](https://docs.overturemaps.org/). + + + + +import DocCardList from '@theme/DocCardList'; + + diff --git a/docusaurus/docs/reference/places/place.mdx b/docusaurus/docs/reference/places/place.mdx index d68ea93b..84e50916 100644 --- a/docusaurus/docs/reference/places/place.mdx +++ b/docusaurus/docs/reference/places/place.mdx @@ -18,6 +18,7 @@ import TabItem from '@theme/TabItem'; A place is point of interest in the real world. + @@ -30,6 +31,7 @@ A place is point of interest in the real world. +
Geometry Type PointType place
diff --git a/docusaurus/docs/reference/transportation/connector.mdx b/docusaurus/docs/reference/transportation/connector.mdx index 715dbb44..6fc0ee7a 100644 --- a/docusaurus/docs/reference/transportation/connector.mdx +++ b/docusaurus/docs/reference/transportation/connector.mdx @@ -16,6 +16,7 @@ import TabItem from '@theme/TabItem'; Connectors create physical connections between [segments](segment). + @@ -28,6 +29,7 @@ Connectors create physical connections between [segments](segment). +
Geometry Type PointType connector
Connectors help define the topology of the transportation network by diff --git a/docusaurus/docs/reference/transportation/segment.mdx b/docusaurus/docs/reference/transportation/segment.mdx index 198855ba..6900b062 100644 --- a/docusaurus/docs/reference/transportation/segment.mdx +++ b/docusaurus/docs/reference/transportation/segment.mdx @@ -27,6 +27,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; Segments are paths which can be traveled by people or objects. + @@ -39,6 +40,7 @@ Segments are paths which can be traveled by people or objects. +
Geometry Type LineStringType segment
Segment geometry represents the center-line of a path that a person or object may @@ -62,37 +64,44 @@ A segment may have one of three possible sub-types. + +
subtype road
A `road` segment represents a section of any kind of road, street or path, including a dedicated path for walking or cycling, but excluding a railway. -To learn the core concepts of roads, see the + + + +
subtype rail
The schema for `rail` segments is under development. + +
subtype water
The schema for `water` segments is under development. diff --git a/docusaurus/docs/themes/admins/admins.mdx b/docusaurus/docs/themes/admins/admins.mdx deleted file mode 100644 index 9a01bd1c..00000000 --- a/docusaurus/docs/themes/admins/admins.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Admins ---- - - -# Admins Theme - -The Overture `admins` theme includes entities that describe named localities in the real world including settlements, cities, regions, provinces and countries. The current version of the schema does not support the modeling of multiple geo-political views. In future schema versions, Overture will have support for: - -- providing multiple views of a country boundary based on the user's region. -- modeling the relationship between a country and its overseas territories or other disputed territories. - - - -- providing multiple views of a country boundary based on the user's region. -- modeling the relationship between a country and its overseas territories or other disputed territories. - -**Clear country definitions.** There are no gaps or overlaps at the country level `admin_level=1` in order to support visualization, sectioning and other mapping use cases, even in cases of disputed boundaries. Additionally, all countries have been assigned an [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 ISO country code which has been kept as close as possible to the standard. For some disputed areas and remote overseas territories, custom ISO codes have been created to describe the region which can be easily identified. - -## Admin Types - -- [locality](/reference/admins/locality) describes a named and typically populated place. There are two sub-types: - - administrative localities model countries and their hierarchical subdivisions. Each administrative locality has an administrative level indicating its level within a country. Attributes like driving side and default language are also available. - - named localities model named places that are not part of a countries administrative hierarchy. -- [locality area](/reference/admins/locality-area) adds land or maritime polygons to [locality](/reference/admins/locality). -- [administrative boundary](/reference/admins/administrative-boundary) provides a boundary line of administrative localities. This feature allows for an easy display of country borders and administrative subdivisions within countries. Boundaries shared by different administrative localities are represented by one line. A maritime attribute supports filtering on boundaries located within seas or oceans. - -## Schema Reference - -- [Explore the schema for administrative boundaries](/reference/admins/administrative-boundary). -- [Explore the schema for the locality feature type](/reference/admins/locality). -- [Explore the schema for the locality area feature type](/reference/admins/locality-area). diff --git a/docusaurus/docs/themes/base/index.mdx b/docusaurus/docs/themes/base/index.mdx deleted file mode 100644 index b12542e5..00000000 --- a/docusaurus/docs/themes/base/index.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Base ---- - -# Base theme - -The Overture `base` theme provides the land and water features that are necessary to render a complete basemap. These features are currently derived from the [Daylight Earth Tables](https://daylightmap.org/earth/) schema and include the [Daylight Coastlines](https://daylightmap.org/coastlines.html). - - - - - -- basic classification of features into `type`, `subtype` and `class` where appropriate. -- parsing and normalization of common OSM tags, such as `height` and `ele`. -- extraction of consistent OSM tags, such as `wikidata` to top-level properties. -- direct pass-through of remaining relevant OSM tags. - -## Current Types - -- [infrastructure](/reference/base/infrastructure): Infrastructure features such as communication towers and lines, piers, and bridges. -- [land](/reference/base/land): physical representations of land surfaces. Global land derived from the inverse of OSM Coastlines. Translates `natural` tags from OpenStreetMap. -- [land_use](/reference/base/land-use): classifications of the human use of a section of land. Translates `landuse` from OpenStreetMap tag from OpenStreetMap. -- [water](/reference/base/water): physical representations of inland and ocean marine surfaces. Translates `natural` and `waterway` tags from OpenStreetMap. - -## Schema Reference - -- [Explore the schema for the infrastructure feature type](/reference/base/infrastructure). -- [Explore the schema for the land feature type](/reference/base/land). -- [Explore the schema for the land use feature type](/reference/base/land-use). -- [Explore the schema for the water feature type](/reference/base/water). diff --git a/docusaurus/docs/themes/buildings/building.mdx b/docusaurus/docs/themes/buildings/building.mdx deleted file mode 100644 index f3bcced7..00000000 --- a/docusaurus/docs/themes/buildings/building.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Buildings ---- - -# Buildings Theme - -The Overture `buildings` theme describes human-made structures with roofs or interior spaces that are permanently or semi-permanently in one place (source: [OSM building definition](https://wiki.openstreetmap.org/wiki/Key:building)). - - - -## Key Schema Design Choices - -- **Extensible attributes.** Overture starts from a basic model containing footprint polygons and a small number of optional attributes. Attributes currently not covered in the official schema release are allowed to exist with the prefix `ext` in their name. -- **Easy transformation from other data sources.** Classes such as `residential`, `commercial` or `education` are intended to be broad categories in which many different OSM tagging combinations can map to the same class. - -## Schema Reference - -- [Explore the schema for the building feature type](/reference/buildings/building). -- [Explore the schema for the building part feature type](/reference/buildings/building_part). diff --git a/docusaurus/docs/themes/places/place.mdx b/docusaurus/docs/themes/places/place.mdx deleted file mode 100644 index acd837df..00000000 --- a/docusaurus/docs/themes/places/place.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Places ---- - -# Places Theme - -The `places` theme contains datasets with point representations of real-world facilities, services, businesses or amenities. - - - - - -- **Extensible attributes.** Points of interest include basic attributes like phone, mail, website and brand. Attributes currently not covered in the official schema release are allowed to exist with a prefix or `ext` in their name. - -- **Controlled categories.** Overture has created a taxonomy that allows for the transformation of different hierarchical and non-hierarchical categorization systems to the Overture categorization system. - -## Schema reference -[Explore the schema for the place feature type](/reference/places/place). diff --git a/docusaurus/docs/themes/themes.mdx b/docusaurus/docs/themes/themes.mdx deleted file mode 100644 index 8889a34c..00000000 --- a/docusaurus/docs/themes/themes.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Schema Themes ---- - -import DocCardList from '@theme/DocCardList'; - - \ No newline at end of file diff --git a/docusaurus/docs/themes/transportation/index.mdx b/docusaurus/docs/themes/transportation/index.mdx deleted file mode 100644 index 63732042..00000000 --- a/docusaurus/docs/themes/transportation/index.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Transportation ---- - -import DocCardList from '@theme/DocCardList'; - -# Transportation Theme - -Overture's `transportation` layer 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 - -Some common use cases for Overture's `transportation` theme schema include: - -- **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 GERS ID stability. Read more on the [shape and connectivity](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](/overview/feature-model/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](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](travel-modes) page. - -- [Explore the schema for the connector feature type](/reference/transportation/connector). -- [Explore the schema for the segment feature type](/reference/transportation/segment). \ No newline at end of file diff --git a/docusaurus/docs/themes/transportation/roads.mdx b/docusaurus/docs/themes/transportation/roads.mdx deleted file mode 100644 index a456e961..00000000 --- a/docusaurus/docs/themes/transportation/roads.mdx +++ /dev/null @@ -1,673 +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'; - - -# Roads - -In the Overture `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](/reference/transportation/segment) features with the `subtype` property value set to the value `road`. - -## Geometry and granularity - -A road segment's geometry is a virtual 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. (🚧 Note that Overture's pedestrian model is embryonic and very much under construction.) -- 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 `road.class` property of a road specifies its general purpose of use -and its relative importance within the transportation network. The -`road.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](travel-modes) `foot` and deny access to all other -travel modes. Unlike many road segment properties, a road segment's `road.class` -property does not support [geometric scoping](/overview/feature-model/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](shape-connectivity#segmentation) algorithm will generate a segment split. - -Every road segment has a class. If the `road.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 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 -`road.class`. - -Like many road segment properties, the `road.surface` property supports -[geometric scoping](/overview/feature-model/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 road 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](/overview/feature-model/scoping-rules#geometric-scoping-linear-referencing) -(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 -`road.restrictions.access`. (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](/overview/feature-model/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](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](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 transportation schema -does not specify these local rules, norms, and customs, which are left -to the specific application to resolve.) - -Overture 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 `road.restrictions.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 -`road.restrictions.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](/overview/feature-model/scoping-rules#rules-and-rule-based-properties). - - - - -{ ExampleSpeedLimitsSimple } - - - - - - - -🐞 *There is an open issue with the schema that results in this example -not being fully functional in the current release. We are working to -correct it in an upcoming release.* 🐞 - -{ ExampleSpeedLimitsDirectional } - - - - - -{ ExampleSpeedLimitsVariableMax } - - - - -## Lanes - -A road may optionally carry a `road.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 `road.lanes` property applies to traffic lanes, not to -parking lanes. - -### Use cases for lanes - - - -Many 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 `road.lanes` property is omitted from a road segment, reasonable -default values should be assumed based on `road.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](/themes/transportation/shape-connectivity#direction-and-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](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](/overview/feature-model/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 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](https://docs.overturemaps.org/overview/feature-model/scoping-rules#rules-and-rule-based-properties) -in the optional `road.lanes` property. - -- A rule may be scoped [geometrically](https://docs.overturemaps.org/overview/feature-model/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](https://docs.overturemaps.org/overview/feature-model/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](https://docs.overturemaps.org/overview/feature-model/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](shape-connectivity#direction-and-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](/overview/feature-model/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/themes/transportation/shape-connectivity.mdx b/docusaurus/docs/themes/transportation/shape-connectivity.mdx deleted file mode 100644 index 8eb58164..00000000 --- a/docusaurus/docs/themes/transportation/shape-connectivity.mdx +++ /dev/null @@ -1,516 +0,0 @@ ---- -title: Shape and connectivity ---- - -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -# Shape and connectivity - -The Overture `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](/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](/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 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](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](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's segmentation process is to promote stability of -segment shape across Overture 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 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 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's success at this assessment -directly feeds into the stability and precision of -[Global Entity Reference System](/gers) (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 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](/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 data release would insert -coordinates in the middle of the north-south segments, if they did not already -exist, because Overture 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](/overview/feature-model/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](/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 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/themes/transportation/travel-modes.mdx b/docusaurus/docs/themes/transportation/travel-modes.mdx deleted file mode 100644 index 6a547a3c..00000000 --- a/docusaurus/docs/themes/transportation/travel-modes.mdx +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: Travel modes ---- - -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -# Travel modes - -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 transportation theme's schema model, the 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](/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](roads) segments, this implied set derives -from the [road class](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 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. As of our draft schema release `v0.4.0`, this enumeration -is relatively small and contains only travel modes which we have some -confidence will be generally-applicable both across jurisdictions and -over time. We expect the list to change in future schema updates, to be -larger once we reach a table `v1.0.0` schema, and 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](/overview/feature-model/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: { axle_count: { is_equal_to: 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](roads) -segments. Since travel modes are expressed via scoping properties, it -is recommended to read the section on -[scoped and rule-based properties](/overview/feature-model/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 travelling 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](/overview/feature-model/scoping-rules#vehicle-attributes-scoping). Where there is potential overlap, the method of scoping used in Overture -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](/overview/feature-model/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](/overview/feature-model/scoping-rules#status-scoping-membership-in-a-recognized-group), - which relates to a recognized status given to the person or thing - travelling, where the recognized status is distinct from the mode of - travel itself. Travel modes should ideally not embed a status. - -### The travel modes taxonomy - -Overture travel modes 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 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 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 that 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 iteration in -the transportation space. The speed of change raises the possibility -that no matter how quickly we extend the travel modes recognized in the -Overture schema, the schema will always be behind the real world, at -least in some local areas and with regard to some technologies, customs, -or local rules. - -One possibility to keep the Overture schema maximally usable for users -who are mapping 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 - -As alluded to [above](#vehicle-attribute-scoping-vehicle), there is some -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, however, 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. diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 45466b5e..897bb048 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -1,133 +1,8 @@ -/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ -const sidebars = { +module.exports = { docs: [ - /* - Overview - */ { - type: 'category', - label: 'Overview', - collapsed: false, - items: [ - { - type: 'doc', - id: 'overview/index' - }, - { - type: 'category', - label: 'Feature Model', - link: { - type: 'doc', - id: 'overview/feature-model/index' - }, - collapsed: false, - items: [ - // 'overview/feature-model/geojson', - 'overview/feature-model/names', - 'overview/feature-model/scoping-rules', - ] - } - - ] + type: 'autogenerated', + dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/) }, - /* - Themes - */ - { - type: 'category', - label: 'Schema Themes', - link: { - type: 'doc', - id: 'themes/themes' - }, - collapsed: true, - items: [ - { - type: 'doc', - id: 'themes/admins/admins', - label: 'Admins' - }, - 'themes/base/index', - 'themes/buildings/building', - 'themes/places/place', - { - type: 'category', - label: 'Transportation', - link: { - type: 'doc', - id: 'themes/transportation/index', - }, - collapsed: true, - items: [ - 'themes/transportation/shape-connectivity', - 'themes/transportation/roads', - 'themes/transportation/travel-modes', - ] - } - ] - }, - /* - Schema Reference - */ - { - type: 'category', - label: 'Schema Reference', - link: { - type: 'generated-index', - slug: '/reference', - }, - collapsed: true, - items: [ - { - type: 'category', - label: 'admins', - collapsed: false, - items: [ - 'reference/admins/administrative-boundary', - 'reference/admins/locality', - 'reference/admins/locality-area', - ] - }, - { - type: 'category', - label: 'base', - collapsed: false, - items: [ - 'reference/base/infrastructure', - 'reference/base/land', - 'reference/base/land-use', - 'reference/base/water', - ] - }, - { - type: 'category', - label: 'buildings', - collapsed: false, - items: [ - 'reference/buildings/building', - 'reference/buildings/building_part' - ] - }, - { - type: 'category', - label: 'places', - collapsed: false, - items: [ - 'reference/places/place', - ] - }, - { - type: 'category', - label: 'transportation', - collapsed: false, - items: [ - 'reference/transportation/connector', - 'reference/transportation/segment', - ] - } - ] - } ], }; - -module.exports = sidebars; diff --git a/docusaurus/src/components/shared-libs/yamlFileResolver.js b/docusaurus/src/components/shared-libs/yamlFileResolver.js index 24c1ac9a..aa0e7ada 100644 --- a/docusaurus/src/components/shared-libs/yamlFileResolver.js +++ b/docusaurus/src/components/shared-libs/yamlFileResolver.js @@ -16,10 +16,8 @@ function YAMLFileResolver(yamlPath) { if (YAML_FILES.hasOwnProperty(relativeYamlPath)){ var res = yaml.load(YAML_FILES[relativeYamlPath].default) - console.log("Found and returning " + relativeYamlPath) return res }else{ - console.warn("Didn't find: " + relativeYamlPath) return {} }