Repository: sharedstreets/sharedstreets-ref-system
Branch: master
Commit: 00e8a872ef9c
Files: 7
Total size: 30.8 KB
Directory structure:
gitextract_wqq_4p6z/
├── LICENSE
├── OSMLR.md
├── README.md
└── proto/
├── linear_references.proto
├── sharedstreets.proto
├── speeds.proto
└── temporal_references.proto
================================================
FILE CONTENTS
================================================
================================================
FILE: LICENSE
================================================
MIT License
Copyright (c) 2017 SharedStreets
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: OSMLR.md
================================================
### OSMLR and SharedStreets
OSMLR v1.x was developed to support OpenTraffic under contract from the World Bank. SharedStreets is the continuation of this work as part of the Open Transport Partnership. The SharedStreets Referencing system is effectively "OSMLR v2.0" but drops the OSMLR name as it intends to support broad range of map data formats including, but not limited to, OpenStreetMap.
SharedStreets also addresses two problems in the OSMLR v1.x implementation:
**1) OSMLR v1.x segment references over 1km in length are unstable.**
The OSMLR v1.x implementation splits street segments into 1km sections. This design conflates location referencing (the identification of street segments) with linear reference (the identification of locations along segments).
As segment geometries change due to improved mapping, the length of segments changes, sometimes substantially. For longer segments this could create or destroy OSMLR references (e.g. a 10km stretch of road becomes 12km when the map is improved, resulting in two new OSMLR 1km segments). This undermines one the of the core ideas of OpenLR: underlying map geometries can change while segment references remain stable.
This problem is especially serious in developing countries where the quality of maps are rapidly improving. It also creates problems sharing data between users with different quality basemaps. Users with more precise maps will in most cases have longer street segments, resulting in new OSMLR segments that cannot be generated by users with coarser maps.
Pre-spliting segments into 1km sections also undermines applications that describe locations along segments (e.g curbside parking regulations) or features that span longer sections of road. Given the geometry changes may move (or even create or destroy) segment references, precise/stable linear referencing is not possible using OSMLR v1.x.
SharedStreets addresses this problem by decoupling location referencing and linear reference. All streets segments are mapped at intersection to intersection. Users with different quality maps should be able to overcome variations in geometry length by using other properties of the reference (segment end points, bearing, and "form of way") to match segments. SharedStreets provides a separate linear referencing format to describe points or sections of the segment.
**2) OSMLR shorthand IDs can't be reproduced without use of specialized software. This undermines OSMLR's value as a universal, non-proprietary standard.**
The OSMLR 1.x implementation depends on Valhalla routing engine to generate segment IDs. These IDs cannot be generated without deploying the Valhalla system. This creates a dependency on a specific piece of software, likely reducing the value of the OSMLR spec by non-Valhalla users.
SharedStreets addresses this by creating a deterministic, software-independent process for generating shorthand IDs. SharedStreets provides open source software as a reference, but the methods can be easily incorporated into other applications to independently generate matching IDs.
The above issues noted, OSMLR v1.x can be mapped to SharedStreets segments when needed. SharedStreets segments cannot be accurately described using OSMLR v1.x due to limitations of the OSMLR v1.x spec.
================================================
FILE: README.md
================================================
# SharedStreets Referencing System
## Introduction
SharedStreets data standards are a way to uniquely identify street space and connect data related to streets. SharedStreets makes maps connectable, and allows porting of data between different street representations, whether data linked to OpenStreetMap, a city-managed GIS system, or a commercial basemap.
Cities today depend on geographic information systems (GIS) to collect and share street data, but this process requires users to agree on a map, or to use predefined, and often proprietary IDs to describe streets.
This limits the potential for collaboration and data sharing between government agencies, and with the private sector. And use of proprietary maps and identification systems can undermine cities’ ability to use and share critical public information about streets.
SharedStreets provides a global, non-proprietary system for describing streets, designed to incorporate any source of street-linked data. This allows public and private entities to communicate with clarity and precision about streets while ensuring full compatibility with organizations’ internal map data.
The SharedStreets referencing system was originally created as part of the [OpenTraffic project](https://github.com/opentraffic/architecture/issues/1), as a mechanism for sharing dynamic traffic information. SharedStreets builds on the core concepts from [OpenLR](http://www.openlr.info/) and provides a collection of data formats and open source tools to re-imagine collaboration and sharing of street-linked data.
The SharedStreets referencing system is being released as a draft proposal, along with data samples and tools for generating references from OpenStreetMap and Shapefile data sources. Comments and suggestions on the format will be managed via this Github repository. Please open an Github issue or pull request to contribute.
**A production version of the SharedStreets Referencing System and a global data set will be released soon. During the preview phase, referencing data can be generated using open source tools for any location.**
### Example Applications
**Traffic data:** SharedStreets references are used to share basemap-independent descriptions of traffic conditions. In the OpenTraffic project fleet operators convert GPS data to to traffic observations (speeds along OpenStreetMap defined roadway segments). Traffic observations are shared externally using SharedStreets references to describe street segments.
**Street and curb inventory:** Cities produce detailed curb inventories (e.g. parking regulations and physical assets) using internally managed linear referencing systems (LRS), or latitude/longitude coordinates not linked with streets. Internal LRS data can be translated to SharedStreets references to allow interoperability with other city or external data sets.
**Incident/road closure reporting:** transport authorities share data about street conditions in real-time with consumer applications. SharedStreets references can be used to streamline reporting procedures by providing a shared, non-proprietary format for describing roadway incidents and closure events.
## Core Concepts
The SharedStreets Referencing system is built on four layers of data:
1. **SharedStreets References:** basemap-independent references for intersection to intersection street segments
2. **SharedStreets Intersection:** nodes connecting street street segments references
3. **SharedStreets Geometries:** geometries used to generate street segment references
4. **OSM Metadata:** underlying OSM way and node references used to construct SharedStreets data
### Segment references
The OpenLR-style street segment references are the foundation of the SharedStreets Referencing System. These references allow users to uniquely describe any street segment in the world using just a few high-level characteristics.
This allows users with different map geometries to describe the same street segments in identical or nearly identical terms. The references are used to find matching streets in users' existing internal maps. In cases where no matching street is found, users have the opportunity to update their map data to fill in missing or incorrectly mapped segments.
Street segment references protect users' intellectual property, as data can be shared without disclosing a complete map. Segment references also enable rapid reconciliation of data derived from different maps.
### BYOM
SharedStreets is based on the idea that users will maintain their own internal basemaps. Any basemap--open or proprietary--can generate SharedStreets references for sharing with others using a different map. With open basemap data users are encouraged to share the full set of SharedStreets data layers (references, geometries and metadata). Users with proprietary basemap data can share only the segment references, allowing exchange of information while protecting map street geometries and other intellectual property.
### Stable, non-proprietary shorthand IDs
SharedStreets uses 128-bit shorthand identifiers to relate data within the SharedStreets referencing system. These IDs provide a basemap-independent addressing system for street segment references, intersections and geometries. **These identifiers are generated deterministically using a hash of the underlying data.** This means that two different users with the same input data can generate matching SharedStreets identifiers. This simplifies data sharing, allowing users to match data using shorthand IDs whenever possible.
In the draft specification the 128-bit IDs are encoded as base-16 (hex) strings.
### Generating references + data tiles
SharedStreets street references, intersections and geometries can be generated from OSM data using the [SharedStreets Builder](https://github.com/sharedstreets/sharedstreets-builder) application.
As part of the draft release pre-generated a sample of SharedStreets tiles for New York City are included in this repository. A zip archive of the full NYC tile set can be [downloaded here](https://www.dropbox.com/s/ys1wb25aipmkbi2/nyc_sample_data.zip?dl=0) (146MB file). Users can generate their own tiles for any arbitrary OSM data set using the SharedStreets Builder application.
Once the data specification is finalized the SharedStreets program will generate and maintain a global data tile set, and provide tools to cities for reconciling their data with the referencing system.
The draft release of SharedStreets exports data as JSON files, cut into mercator tiles at zoom level 10. These draft tiles are verbose and are designed to support exploration and refinement of the specification. Once the specification is finalized SharedStreets will provide JSON and Protocol Buffer tile formats. SharedStreets is also exploring use of "lossy" vector tile formats for distribution of data for web visualization.
## DRAFT ShareStreets Data Formats
### Changelog
*2017-10-20:* Initial release for comments, using JSON tile representation.
*2017-11-10:* Updated spec to include "inbound" and "outbound" bearings for references, backwards compatible with OpenLR-derived data standards while allowing for more complex geometry matching workflows. (Thanks to [@migurski](https://github.com/migurski) and [@remix](https://github.com/remix) for this suggestion.)
*2017-11-20:* Switched from JSON to [protocol buffer encoded tiles](https://github.com/sharedstreets/sharedstreets-ref-system/blob/master/proto/sharedstreets.proto) as default output format.
*2018-01-14:* Switched IDs to base-16 (hex) encoding. Release of updated sharedstreets-builder application (v0.1.2) and sample tile set.
### Protocol Buffer Encoding
SharedStreets encodes reference data in protocol buffer encoded map tiles. The encoding format, [described here](https://github.com/sharedstreets/sharedstreets-ref-system/blob/master/proto/sharedstreets.proto), targets the Protocol Buffer v3 format, and uses the following conventions to enable efficient data storage:
- ["Oneof" wrappers](https://github.com/google/protobuf/issues/1606) allow null values for optional fields. This allows for space-efficient values, while ensuring that downstream users can differentiate between zero and null values for bearings and lengths.
- Strings of latitude/longitude values for geometries are encoded as a single stream of values (e.g. "[-74.003388, 40.634538],[-74.004107, 40.63406]" is encoded as "-74.003388,40.634538,-74.004107,40.63406".
- Distances are encoded in centimeters using int32 field types.
For more information about encoding see the [SharedStreets Builder](https://github.com/sharedstreets/sharedstreets-builder) application, which converts OpenStreetMap and other geospatial data into SharedStreets protocol buffer tiles.
### SharedStreets Intersections
```javascript
{
"type": "Feature",
"properties": {
"id": "5gRJyF2MT5BBErTyEesQLC",
"osmNodeId": 42460951,
"outboundReferenceIds": ["6mjqqv7YNsp4541DmrrRbV", "jwwKcUvHuCw6GJJAT3mDQ", "2Vw2XzW4cs7r32RLhQnqwA"],
"inboundReferenceIds": ["VmSkhzGKoEc767w98x35La", "VXKSEokmvBJ81XHYhUronG", "B7RPzs3hb1cSXqYcAKmUhE"]
},
"geometry": {
"type": "Point",
"coordinates": [-74.003388, 40.634538]
}
}
```
```javascript
{
"type": "Feature",
"properties": {
"id": "N38a21UGykpnqxwez7NGS3",
"osmNodeId": 42460956,
"outboundReferenceIds": ["VXKSEokmvBJ81XHYhUronG", "KxeV6ycjnarJU8pGEmkUx9", "V6aRcYcZgd5D58GaEaxCaF"],
"inboundReferenceIds": ["8ShvkUbHhu1SXzcE5XMj2L", "Ak3c8QdsYWVRn5Ap53hzcH", "2Vw2XzW4cs7r32RLhQnqwA"]
},
"geometry": {
"type": "Point",
"coordinates": [-74.004107, 40.63406]
}
}
```
### SharedStreets References
SharedStreets References (SSR) are directional edges in a road network. Two-way streets have two SSRs, one for each direction of travel, while one-way streets only have one SSR. In the draft specification these are labeled "forward references" and "back references," with the forward reference following the direction of the map geometry used to generate the references.
Each SharedStreets Reference consists of two or more location references (LRs) that describe the latitude and longitude of the beginning or end of a street segment. SSRs also describe type of road (or the "form of way," as defined by OpenLR), and length of the geometry connecting location reference points. In combination these attributes uniquely describe any road segment, and can be used to look up corresponding streets in users’ internal maps.
#### Forward Reference
```javascript
{
"id": "2Vw2XzW4cs7r32RLhQnqwA",
"geometryId": "NxPFkg4CrzHeFhwV7Uiq7K",
"formOfWay": 3,
"locationReferences": [{
"sequence": 1,
"point": [-74.003388, 40.634538],
"bearing": 228.890377,
"distanceToNextRef": 80.730221,
"intersectionId": "5gRJyF2MT5BBErTyEesQLC"
}, {
"sequence": 2,
"point": [-74.004107, 40.63406],
"intersectionId": "N38a21UGykpnqxwez7NGS3"
}]
}
```
#### Back Reference
```javascript
{
"id": "VXKSEokmvBJ81XHYhUronG",
"geometryId": "NxPFkg4CrzHeFhwV7Uiq7K",
"formOfWay": 3,
"locationReferences": [{
"sequence": 1,
"point": [-74.004107, 40.63406],
"bearing": 48.890138,
"distanceToNextRef": 80.730221,
"intersectionId": "N38a21UGykpnqxwez7NGS3"
}, {
"sequence": 2,
"point": [-74.003388, 40.634538],
"intersectionId": "5gRJyF2MT5BBErTyEesQLC"
}]
}
```
*Notes:*
- For long segments LRs are repeated every 15km, segments shorter than 15km have only a beginning and end LR.
- LRs describe the compass bearing of the street geometry for the 20 meters immediately following the LR. The final LR of a SSR does not provide a bearing.
- An initial set of SSRs are built using OpenStreetMap (OSM) data, however, in the future SharedStreets users will be able to publicly register SSRs for streets not found in OSM. These could include data found in commercial or government maintained basemaps. Users do not have to share the underlying data, only the SSR descriptor.
### SharedStreets Geometries
SharedStreets Geometries are street centerline data derived from the basemap used to produce SharedStreets References. A single geometry is shared by each set of forward and back references.
SharedStreets is premised on the idea that there's no one correct geometry for a given street. Just as street references can be generated from any basemap, street geometries can be derived from any data source.
```javascript
{
"type": "Feature",
"properties": {
"id": "NxPFkg4CrzHeFhwV7Uiq7K",
"fromIntersectionId": "5gRJyF2MT5BBErTyEesQLC",
"toIntersectionId": "N38a21UGykpnqxwez7NGS3",
"forwardReferenceId": "2Vw2XzW4cs7r32RLhQnqwA",
"backReferenceId": "VXKSEokmvBJ81XHYhUronG",
"roadClass": 3
},
"geometry": {
"type": "LineString",
"coordinates": [
[-74.003388, 40.634538],
[-74.003621, 40.634383],
[-74.003621, 40.634383],
[-74.004107, 40.63406]
]
}
}
```
### SharedStreets OSM Metadata
SharedStreets generates metadata about the map data used to generate references and geometries. For OSM-derived references the way and nodes are stored as part of metadata layer. This simplifies matching references back to underlying basemap data, and provides a framework to easily track changes in the underlying basemap data.
```javascript
{
"geometryId": "NxPFkg4CrzHeFhwV7Uiq7K",
"waySections": [{
"wayId": 420584810,
"roadClass": 3,
"oneWay": false,
"roundabout": false,
"link": false,
"nodeIds": [42460951, 4205392123]
}, {
"wayId": 420584817,
"roadClass": 3,
"oneWay": false,
"roundabout": false,
"link": false,
"nodeIds": [4205392123, 42460956]
}]
}
```
### Frequently Asked Questions
#### How does this relate to OpenStreetMap? (Or, doesn't OSM already do this?)**
SharedStreets complements OpenStreetMap. OSM does not attempt to provide stable IDs, and complex OSM ways make many applications difficult to build using raw OSM data.
SharedStreets provides a layer of abstraction on top of OSM, allowing users to work with the *topology* of OpenStreetMaps data without dealing with the details how OSM ways are encoded.
By providing direct references to OSM way and node IDs users can always query and relate SharedStreets references back to the underlying OSM data where needed.
We believe that SharedStreets will allow users to more rapidly improve OpenStreetMap data by making it easier to identify missing streets, or opportunities to improve street geometry and connectivity.
#### How does SharedStreets relate to OSMLR v1.x?
OSMLR v1.x was developed to support OpenTraffic under contract from the World Bank. SharedStreets is the continuation of this work as part of the Open Transport Partnership. The SharedStreets Referencing system is effectively "OSMLR v2.0" but drops the OSMLR name as it intends to support broad range of map data formats including, but not limited to, OpenStreetMap. SharedStreets also addresses two critical deficiencies in the OSMLR v1.x spec, [documented here](https://github.com/sharedstreets/sharedstreets-ref-system/blob/master/OSMLR.md).
================================================
FILE: proto/linear_references.proto
================================================
syntax = "proto3";
option java_outer_classname = "SharedStreetsLinearReferencesProto";
// linear referencing spec for SharedStreets allows description of point and segments features along street references
//
// [ SharedStreets Ref ]
// =============*=======
// ^ point at distance: 75 along reference
//
// [ SharedStreets Ref ]
// ========*******======
// ^ ^ linear segment from distance 50 to 75 along SharedStreets reference
message LinearReference {
uint64 startDistance = 1; // start distance along SharedStreets reference
oneof endDistance_present {
uint64 endDistance = 2;// end distance along SharedStreets reference, null for point linear references
}
}
message SharedStreetsLinearReferences {
string referenceId = 1; // SharedStreets Reference ID
uint64 referenceLength = 2; // total length of SharedStreets reference in centimeters (allows users to compare expected length with actual length in internal data)
repeated LinearReference references = 3; // one or more linear reference associated with a SharedStreets reference
}
// "binned" linear referencing spec for SharedStreets allows grouping of linear point features into segments along reference
//
// [ SharedStreets Ref ]
// referenceLength = 100m
// numberOfBins = 5
// =====*=====*=====*=====*=====
// 0 1 2 3 4 = bin position (20m/bin)
// 4 8 0 2 0 = bin value (count of grouped linear features)
//
message DataBin {
repeated string dataType = 1;
repeated uint64 count = 2;
repeated double value = 3;
}
message BinnedPeriodicData {
repeated uint32 periodOffset = 1;
repeated DataBin bins = 2;
}
message SharedStreetsBinnedLinearReferences {
string referenceId = 1; // SharedStreets Reference ID
bool scaledCounts = 2; // counts in histogram are stored as scaled numbers, otherwise stored as absolute counts
uint64 referenceLength = 3; // total length of SharedStreets reference in centimeters (allows users to compare expected length with actual length in internal data)
uint32 numberOfBins = 4; // number of bins, bin size is referenceLength / numberOfBins
repeated uint32 binPosition = 5; // bin position offset (0 to n-1 bins)
repeated DataBin bins = 6; // bin value ()
}
enum PeriodSize {
OneSecond = 0;
FiveSeconds = 1;
TenSeconds = 2;
FifteenSeconds = 3;
ThirtySeconds = 4;
OneMinute = 5;
FiveMinutes = 6;
TenMinutes = 7;
FifteenMinutes = 8;
ThirtyMinutes = 9;
OneHour = 10;
OneDay = 11;
OneWeek = 12;
OneMonth = 13;
OneYear = 14;
}
message SharedStreetsWeeklyBinnedLinearReferences {
string referenceId = 1; // SharedStreets Reference ID
PeriodSize periodSize = 2; // optional (hourly if ommited)
bool scaledCounts = 3; // counts in histogram are stored as scaled numbers, otherwise stored as absolute counts
uint64 referenceLength = 4; // total length of SharedStreets reference in centimeters (allows users to compare expected length with actual length in internal data)
uint32 numberOfBins = 5; // number of bins, bin size is referenceLength / numberOfBins
repeated uint32 binPosition = 6; // period
repeated BinnedPeriodicData binnedPeriodicData = 7; // bin value ()
}
================================================
FILE: proto/sharedstreets.proto
================================================
syntax = "proto3";
option java_outer_classname = "SharedStreetsProto";
message Delimiter {
uint32 length = 1;
}
message GISSectionMetadata {
string sectionId = 1; // source specific id
string sectionProperties = 2; // source specific encoding of properties
}
message GISMetadata {
string source = 1; // describes GIS source data (e.g. "gov.nyc:lion")
repeated GISSectionMetadata sections = 2;
}
enum RoadClass {
Motorway = 0;
Trunk = 1;
Primary = 2;
Secondary = 3;
Tertiary = 4;
Residential = 5;
Unclassified = 6;
Service = 7;
Other = 8;
}
message WaySection {
uint64 wayId =1 ;
RoadClass roadClass = 2;
bool oneWay = 3;
bool roundabout = 4;
bool link = 5;
repeated uint64 nodeIds = 6;
string name = 7; // name only stored here if different for each way section, otherwise captured in OSMMetadata
}
message OSMMetadata {
repeated WaySection waySections = 1;
string name = 2; // name stored here if same for all way sections
}
message SharedStreetsMetadata {
string geometryId = 1;
OSMMetadata osmMetadata = 2;
repeated GISMetadata gisMetadata = 3;
}
message SharedStreetsGeometry {
string id = 1;
string fromIntersectionId = 2;
string toIntersectionId = 3;
string forwardReferenceId = 4;
string backReferenceId = 5;
RoadClass roadClass = 6;
repeated double lonlats = 7; // interleaved lon/lat pairs in sequence
}
message LocationReference {
string intersectionId = 1;
double lon = 2;
double lat = 3;
oneof inboundBearing_present {
int32 inboundBearing = 4; // rounded to nearest degree 0-360 -- optional field, using proto3 oneof to allow for nulls
}
oneof outboundBearing_present {
int32 outboundBearing = 5; // rounded to nearest degree 0-360 -- optional field, using proto3 oneof to allow for nulls
}
oneof distanceToNextRef_present {
int32 distanceToNextRef = 6; // in centimeters -- max value of 15km -- optional field, using proto3 oneof to allow for nulls
}
}
message SharedStreetsReference {
string id = 1;
string geometryId = 2;
enum FormOfWay {
Undefined = 0;
Motorway = 1;
MultipleCarriageway = 2;
SingleCarriageway = 3;
Roundabout = 4;
TrafficSquare = 5; // yikes: https://giphy.com/gifs/square-addis-meskel-GYb9s3Afw0cWA
SlipRoad = 6;
Other = 7;
}
FormOfWay formOfWay = 3;
repeated LocationReference locationReferences = 4;
}
message SharedStreetsIntersection {
string id = 1;
uint64 nodeId = 2;
double lon = 3;
double lat = 4;
repeated string inboundReferenceIds = 5;
repeated string outboundReferenceIds = 6;
}
================================================
FILE: proto/speeds.proto
================================================
syntax = "proto3";
option java_outer_classname = "SharedStreetsSpeedsProto";
enum PeriodSize {
OneSecond = 0;
FiveSeconds = 1;
TenSeconds = 2;
FifteenSeconds = 3;
ThirtySeconds = 4;
OneMinute = 5;
FiveMinutes = 6;
TenMinutes = 7;
FifteenMinutes = 8;
ThirtyMinutes = 9;
OneHour = 10;
OneDay = 11;
OneWeek = 12;
OneMonth = 13;
OneYear = 14;
}
// temporal references for SharedStreets events (in UTC)
message TemporalPeriod {
PeriodSize periodSize = 1;
uint64 periodOffset = 2; // period offset from unix epoch
// For periodSize = oneYear:
// 1970-01-01 = 0
// 2015-01-01 = 45
// For periodSize = OneMonth:
// 1970-01-01 = 0
// 2015-01-01 = 540
// For periodSize = OneSecond: periodOffset = UNIX timestamp
}
// template for storing weekly cycles of events in local time -- used as a template for developing application specific data standards
// assumes Monday-Sunday week in local time. See OpenTraffic weekly speed data for example implementation.
message WeeklyCycle {
uint32 year = 1; // date for Monday of week (Monday midnight is zero for week cycle per ISO-8601)
uint32 month = 2;
uint32 day = 3;
PeriodSize periodSize = 4;
// repeated [...] periodData = ...; // replace with application specific data payload
}
// SharedStreets uses histograms to store speed observations
// This allows aggregation and calculation of statistics from distribution of speeds
//
// count
// 4 | *
// 3 | * * * *
// 2 | * * * * * * *
// 1 | * * * * * * * * * *
// ________________________
// 0 1 2 3 4 5 6 7 8 9
// Speed (km/h)
//
// Mean and variance can be calculated from distribution.
// Histograms with absolute counts can be added together to merge observations.
// Histograms can also be stored using scaled counts (0-100 default) to hide absolute observation counts
message SpeedHistogram {
repeated uint32 speedBin = 1; // repeated speed bins in km/h, bins are unordered and may not be sequential
repeated uint32 observationCount = 2; // number of observations for corresponding speedBin. Counts are repeated in same order as bins.
}
message SpeedHistogramByPeriod {
repeated uint32 periodOffset = 1; // repeated offset for period (Monday, midnight is zero for week cycle per ISO-8601)
repeated SpeedHistogram histogram = 2; // SpeedHistogram for period
}
message SpeedSummary{
uint32 meanSpead = 1; // mean speed in km/h
repeated uint32 percentile = 2; // repeated percentile value (e.g 50th, 85th stored as 50 or 85)
repeated uint32 observationCount = 3; // km/h value for corresponding percentile
}
message SpeedSummaryByPeriod{
repeated uint32 periodOffset = 1; // repeated offset for period (Monday, midnight is zero for week cycle per ISO-8601)
repeated SpeedSummary speedSummary = 3; // SpeedSummary for period
}
// defines weekly speeds based on speed histogram and/or summary + linear binning following approach used in SharedStreetsBinnedLinearReferences
message SharedStreetsWeeklySpeeds {
string referenceId = 1; // SharedStreets Reference ID
PeriodSize periodSize = 2; // optional (hourly if ommited)
bool scaledCounts = 3; // counts in histogram are stored as scaled numbers, otherwise stored as absolute counts
uint64 referenceLength = 4; // total length of SharedStreets reference in centimeters (allows users to compare expected length with actual length in internal data)
uint32 numberOfBins = 5; // number of linear bins. bin size is referenceLength / numberOfBins
repeated uint32 binPosition = 6; // linear bin position offset (0 to n-1 bins)
repeated SpeedHistogramByPeriod speedsByPeriod = 7; // repeated speed histogram
repeated SpeedSummaryByPeriod speedSummaryByPeriod = 8; // repeated speed summary
}
================================================
FILE: proto/temporal_references.proto
================================================
syntax = "proto3";
option java_outer_classname = "SharedStreetsTemporalReferencesProto";
enum PeriodSize {
OneSecond = 0;
FiveSeconds = 1;
TenSeconds = 2;
FifteenSeconds = 3;
ThirtySeconds = 4;
OneMinute = 5;
FiveMinutes = 6;
TenMinutes = 7;
FifteenMinutes = 8;
ThirtyMinutes = 9;
OneHour = 10;
OneDay = 11;
OneWeek = 12;
OneMonth = 13;
OneYear = 14;
}
// temporal references for SharedStreets events (in UTC)
message TemporalPeriod {
PeriodSize periodSize = 1;
uint64 periodOffset = 2; // period offset from unix epoch
// For periodSize = oneYear:
// 1970-01-01 = 0
// 2015-01-01 = 45
// For periodSize = OneMonth:
// 1970-01-01 = 0
// 2015-01-01 = 540
// For periodSize = OneSecond: periodOffset = UNIX timestamp
}
// template for storing weekly cycles of events in local time -- used as a template for developing application specific data standards
// assumes Monday-Sunday week in local time. See OpenTraffic weekly speed data for example implementation.
message WeeklyCycle {
uint32 year = 1; // date for Monday of week (Monday midnight is zero for week cycle per ISO-8601)
uint32 month = 2;
uint32 day = 3;
PeriodSize periodSize = 4;
// repeated [...] periodData = ...; // replace with application specific data payload
}
gitextract_wqq_4p6z/
├── LICENSE
├── OSMLR.md
├── README.md
└── proto/
├── linear_references.proto
├── sharedstreets.proto
├── speeds.proto
└── temporal_references.proto
Condensed preview — 7 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (33K chars).
[
{
"path": "LICENSE",
"chars": 1070,
"preview": "MIT License\n\nCopyright (c) 2017 SharedStreets\n\nPermission is hereby granted, free of charge, to any person obtaining a c"
},
{
"path": "OSMLR.md",
"chars": 3365,
"preview": "### OSMLR and SharedStreets\n\nOSMLR v1.x was developed to support OpenTraffic under contract from the World Bank. SharedS"
},
{
"path": "README.md",
"chars": 15324,
"preview": "# SharedStreets Referencing System\n\n## Introduction\n\nSharedStreets data standards are a way to uniquely identify street "
},
{
"path": "proto/linear_references.proto",
"chars": 3474,
"preview": "syntax = \"proto3\";\n\noption java_outer_classname = \"SharedStreetsLinearReferencesProto\";\n\n\n// linear referencing spec for"
},
{
"path": "proto/sharedstreets.proto",
"chars": 2607,
"preview": "syntax = \"proto3\";\n\noption java_outer_classname = \"SharedStreetsProto\";\n\nmessage Delimiter {\n uint32 length = 1;\n}\n\nmes"
},
{
"path": "proto/speeds.proto",
"chars": 4228,
"preview": "syntax = \"proto3\";\n\noption java_outer_classname = \"SharedStreetsSpeedsProto\";\n\nenum PeriodSize {\n OneSecond = 0;\n "
},
{
"path": "proto/temporal_references.proto",
"chars": 1515,
"preview": "syntax = \"proto3\";\n\noption java_outer_classname = \"SharedStreetsTemporalReferencesProto\";\n\nenum PeriodSize {\n OneSeco"
}
]
About this extraction
This page contains the full source code of the sharedstreets/sharedstreets-ref-system GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 7 files (30.8 KB), approximately 7.9k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.