4.4.5. Geo-referencing¶
Geo-referencing is used to allocated location properties to object.
A typical user case is to bridge PDEF with Geographical Information System (GIS) or Geo-referenced Database.
4.4.5.1. GeoJSON¶
In PDEF, Geo-referencing is performed using JSON-fragments following the GeoJSON format specification.
Note
GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON). It defines several types of JSON objects and the manner in which they are combined to represent data about geographic features, their properties, and their spatial extents.*
4.4.5.2. Coordinate Reference System (crs)¶
When specifying Coordinates, it is essential to provide a reference to an explicit Coordinate Reference System (crs).
PDEF refers to EPSG codes for Coordinate Reference System (crs).
1 2 3 | {
"crs":"EPSG:4326"
}
|
The EPSG Geodetic Parameter Dataset is maintained by the Geodesy Subcommittee of the International Association of Oil & Gas Producers (IOGP) Geomatics Committee. EPSG codes are available at epsg.io.
In PDEF, the EPSG code is specified as a string of characters made of:
“EPSG:” + the 4 digits of the EPSG code
All the details for this reference system can then be sourced directly from epsg.io.
Note
EPSG provides a dedicated application programming interface (API) to access the geodesic parameters programmatically.
4.4.5.3. Coordinates¶
Coordinates are specified using arrays.
The first two elements are longitude and latitude, or easting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element.
1 2 3 | {
"coordinates": [2.3393476009368896, 48.857771121284145]
}
|
4.4.5.4. Geometry¶
A Geometry is a JSON fragment that represent one of the following seven items:
4.4.5.4.1. Point¶
A Point is a simple position. The “coordinates” member is therefore a single position.
-
pdef.model.geo_ref.Point Show JSON schema
{ "title": "Point", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "Point", "enum": [ "Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon" ], "type": "string" }, "coordinates": { "title": "Coordinates", "description": "Single position. A position is an array of 2 or 3 floats (long, lat, el), see GeoJSON documentation.", "examples": [ 2.3393476009368896, 48.857771121284145 ], "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
-
coordinates: Union[Tuple[float, float], Tuple[float, float, float]] = Ellipsis Single position. A position is an array of 2 or 3 floats (long, lat, el), see GeoJSON documentation.
- Constraints and examples:
examples = [2.3393476009368896, 48.857771121284145]
-
type: Literal[Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon] = 'Point' - Constraints and examples:
const = Point
-
For example, a Point JSON fragment can be:
{
"type": "Point",
"coordinates": [
2.349,
48.853169
],
"crs": "EPSG:4326"
}
4.4.5.4.2. MultiPoint¶
A MultiPoint is a convenient way to bundle several Point in single JSON fragment. The “coordinates” member is therefore an array of positions.
-
pdef.model.geo_ref.MultiPoint Show JSON schema
{ "title": "MultiPoint", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "MultiPoint", "type": "string" }, "coordinates": { "title": "Coordinates", "type": "array", "items": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] } }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
-
coordinates: List[Union[Tuple[float, float], Tuple[float, float, float]]] = Ellipsis
-
type: str = 'MultiPoint' - Constraints and examples:
const = MultiPoint
-
For example, a MultiPoint JSON fragment can be:
{
"type": "MultiPoint",
"coordinates": [
[
2.349,
48.853169
],
[
2.3393476009368896,
48.857771121284145
]
],
"crs": "EPSG:4326"
}
4.4.5.4.3. LineString¶
A LineString is a series of segment (one or more) stitched together. The “coordinates” member is therefore an array of two or more positions. A closed LineString is also refered as a Linear Ring, see below.
-
pdef.model.geo_ref.LineString Show JSON schema
{ "title": "LineString", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "LineString", "type": "string" }, "coordinates": { "title": "Coordinates", "minItems": 2, "type": "array", "items": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] } }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
-
coordinates: List[Union[Tuple[float, float], Tuple[float, float, float]]] = Ellipsis - Constraints and examples:
minItems = 2
-
type: str = 'LineString' - Constraints and examples:
const = LineString
-
For example, a LineString JSON fragment can be:
{
"type": "LineString",
"coordinates": [
[
2.337599,
48.858412
],
[
2.339444,
48.857738
]
],
"crs": "EPSG:4326"
}
4.4.5.4.4. Linear Ring¶
A Linear Ring is a closed LineString with four or more positions. The first and last positions are equivalent, and they must contain identical values; their representation should also be identical.
A Linear Ring is the boundary of a surface or the boundary of a hole in a surface.
Warning
A Linear Ring must follow the right-hand rule with respect to the area it bounds, i.e.: - exterior rings are counterclockwise, - and holes are clockwise.
An example Linear Ring that bounds Île de la Cité, in central Paris:
{
"type": "LineString",
"coordinates": [
[
2.339208,
48.858101
],
[
2.343156,
48.854699
],
[
2.345281,
48.853866
],
[
2.348671,
48.852482
],
[
2.353177,
48.85148
],
[
2.353177,
48.85148
],
[
2.352383,
48.854501
],
[
2.347834,
48.856209
],
[
2.339208,
48.858101
]
],
"crs": "EPSG:4326"
}
4.4.5.4.5. MultiLineString¶
A MultiLineString is a convenient way to bundle several LineString in a single JSON fragment. The Coordinates member is therefore an array of LineString coordinate arrays.
-
pdef.model.geo_ref.MultiLineString Show JSON schema
{ "title": "MultiLineString", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "MultiLineString", "type": "string" }, "coordinates": { "title": "Coordinates", "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] } } }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
-
coordinates: List[List[Union[Tuple[float, float], Tuple[float, float, float]]]] = Ellipsis
-
type: str = 'MultiLineString' - Constraints and examples:
const = MultiLineString
-
An example MultiLineString is provided below:
{
"type": "MultiLineString",
"coordinates": [
[
[
2.329102,
51.034486
],
[
3.164063,
42.504503
]
],
[
[
-4.790039,
48.472921
],
[
8.129883,
48.965794
]
]
],
"crs": "EPSG:4326"
}
4.4.5.4.6. Polygon¶
A Polygon is a bundle of Linear Ring.
The Polygon Coordinates member must be an array of Linear Ring coordinate arrays.
Warning
For Polygons with more than one of these rings, the first must be the exterior Linear Ring, and any others must be interior rings. The exterior Linear Ring bounds the surface, and the interior rings (if present) bound holes within the surface.
-
pdef.model.geo_ref.Polygon Show JSON schema
{ "title": "Polygon", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "Polygon", "type": "string" }, "coordinates": { "title": "Coordinates", "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] } } }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
- Validators
check_coordinates»coordinates
-
coordinates: List[List[Union[Tuple[float, float], Tuple[float, float, float]]]] = Ellipsis - Validated by
check_coordinates
-
type: str = 'Polygon' - Constraints and examples:
const = Polygon
-
check_coordinates» coordinates Validate that Polygon coordinates pass the GeoJSON spec
In the example below, a Polygon JSON fragment is used to bound Île de la Cité in central Paris, but excluding Square du vert Galant, which is equivalent to specifying a surface and a hole within that surface:
{
"type": "Polygon",
"coordinates": [
[
[
2.339208,
48.858101
],
[
2.347834,
48.856209
],
[
2.352383,
48.854501
],
[
2.353177,
48.85148
],
[
2.353177,
48.85148
],
[
2.348671,
48.852482
],
[
2.345281,
48.853866
],
[
2.343156,
48.854699
],
[
2.339208,
48.858101
]
],
[
[
2.340585,
48.85715
],
[
2.339637,
48.85762
],
[
2.339686,
48.857657
],
[
2.340772,
48.857365
],
[
2.340585,
48.85715
]
]
],
"crs": "EPSG:4326"
}
4.4.5.4.7. MultiPolygon¶
MultiPolygon is a convenient way to bundle several Polygon in a single JSON fragment. For type MultiPolygon, the Coordinates member is an array of Polygon coordinate arrays.
-
pdef.model.geo_ref.MultiPolygon Show JSON schema
{ "title": "MultiPolygon", "description": "Base model for all geo-referenced objects.", "type": "object", "properties": { "type": { "title": "Type", "const": "MultiPolygon", "type": "string" }, "coordinates": { "title": "Coordinates", "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "array", "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } ] } } } }, "crs": { "title": "Coordinate Reference System", "description": "Geodesic reference system used for the coordinate. PDEF recommend the use of EPSG code.", "examples": "EPSG:4326", "type": "string" } }, "required": [ "coordinates", "crs" ] }
-
coordinates: List[List[List[Union[Tuple[float, float], Tuple[float, float, float]]]]] = Ellipsis
-
type: str = 'MultiPolygon' - Constraints and examples:
const = MultiPolygon
-
For example, the MultiPolygon below represents two surface : Île de la Cité in central Paris, and Square du vert Galant.
{
"type": "MultiPolygon",
"coordinates": [
[
[
[
2.339208,
48.858101
],
[
2.347834,
48.856209
],
[
2.352383,
48.854501
],
[
2.353177,
48.85148
],
[
2.353177,
48.85148
],
[
2.348671,
48.852482
],
[
2.345281,
48.853866
],
[
2.343156,
48.854699
],
[
2.339208,
48.858101
]
]
],
[
[
[
2.340585,
48.85715
],
[
2.340772,
48.857365
],
[
2.339686,
48.857657
],
[
2.339637,
48.85762
],
[
2.340585,
48.85715
]
]
]
],
"crs": "EPSG:4326"
}
4.4.5.4.8. GeometryCollection¶
A GeometryCollection is a convenient way to bundle several geometries in a single object.
The various geometries that are included in the GeometryCollection can be of different types, eg MultiPolygon, Point and MultiPoint.
Note
The GeometryCollection does not require a Coordinate Reference System (crs). The Coordinate Reference System (crs) is specified with each geometry.
Warning
GeoJSON format specification states :
To maximize interoperability, implementations SHOULD avoid nested GeometryCollection. Furthermore, GeometryCollection composed of a single part or a number of parts of a single type SHOULD be avoided when that single part or a single object of multipart type (MultiPoint, MultiLineString, or MultiPolygon) could be used instead.
{
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"coordinates": [
2.349,
48.853169
],
"crs": "EPSG:4326"
},
{
"type": "MultiPoint",
"coordinates": [
[
2.349,
48.853169
],
[
2.3393476009368896,
48.857771121284145
]
],
"crs": "EPSG:4326"
},
{
"type": "LineString",
"coordinates": [
[
2.337599,
48.858412
],
[
2.339444,
48.857738
]
],
"crs": "EPSG:4326"
}
]
}
4.4.5.4.9. Feature¶
A Feature JSON fragment represents a spatially bounded thing.
a Feature object has a member with the name geometry. The value of the geometry member SHALL be […] a Geometry object as defined above.
In PDEF the optional members properties, id and bbox are accepted for interoperability.
An example Feature is provided below:
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
2.339208,
48.858101
],
[
2.343156,
48.854699
],
[
2.345281,
48.853866
],
[
2.348671,
48.852482
],
[
2.353177,
48.85148
],
[
2.353177,
48.85148
],
[
2.352383,
48.854501
],
[
2.347834,
48.856209
],
[
2.339208,
48.858101
]
],
"crs": "EPSG:4326"
},
"properties": null,
"id": null,
"bbox": null
}
4.4.5.4.10. FeatureCollection¶
A FeatureCollection object has a member with the name features. The value of features is a JSON array. Each element of the array is a Feature object as defined above.
An example FeatureCollection is provided below:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
2.339208,
48.858101
],
[
2.343156,
48.854699
],
[
2.345281,
48.853866
],
[
2.348671,
48.852482
],
[
2.353177,
48.85148
],
[
2.353177,
48.85148
],
[
2.352383,
48.854501
],
[
2.347834,
48.856209
],
[
2.339208,
48.858101
]
],
"crs": "EPSG:4326"
},
"properties": null,
"id": null,
"bbox": null
}
],
"bbox": null
}