Map API¶

class py123d.api.MapAPI[source]¶

The base class for all map APIs in 123D.

Public Data Attributes:

`map_metadata`	The `MapMetadata` of the map api.
`dataset`	The dataset name from the map metadata.
`location`	The location from the map metadata.
`map_is_local`	Indicates if the map is local (map for each log) or global (map for multiple logs in dataset).
`map_has_z`	Indicates if the map includes Z (elevation) data.
`version`	The version of the py123d library used to create this map metadata.

Public Methods:

`get_map_metadata`()	Returns the `MapMetadata` of the map api.
`get_available_map_layers`()	Returns the available `MapLayer`,
`get_map_object`(object_id, layer)	Returns a `BaseMapObject` by its ID
`get_map_objects_in_radius`(point, radius, layers)	Returns a dictionary of `MapLayer` to a list of
`query`(geometry, layers[, predicate, sort, ...])	Queries geometries against the map objects in the specified layers using an optional spatial predicate.
`query_object_ids`(geometry, layers[, ...])	Queries geometries against the map objects in the specified layers using an optional spatial predicate.
`query_nearest`(geometry, layers[, ...])	Return the nearest map objects in a spatial tree for each input geometry in

abstractmethod get_map_metadata()[source]¶

Returns the MapMetadata of the map api.

Return type:: MapMetadata
Returns:: The map metadata, e.g. location, dataset, etc.

abstractmethod get_available_map_layers()[source]¶

Returns the available MapLayer,: e.g. LANE, LANE_GROUP, etc.

Return type:: List[MapLayer]
Returns:: A list of available map layers.

abstractmethod get_map_object(object_id, layer)[source]¶

Returns a BaseMapObject by its ID: and MapLayer.

Parameters:

object_id (Union[str, int]) – The ID of the map object.
layer (MapLayer) – The layer the map object belongs to.

Return type:

Optional[BaseMapObject]

Returns:

The map object if found, None otherwise.

abstractmethod get_map_objects_in_radius(point, radius, layers)[source]¶

Returns a dictionary of MapLayer to a list of: BaseMapObject within a given radius around a center point.

Parameters:

point (Union[Point2D, Point3D]) – The center point to search around.
radius (float) – The radius to search within.
layers (List[MapLayer]) – The map layers to search in.

Return type:

Dict[MapLayer, List[BaseMapObject]]

Returns:

A dictionary mapping each layer to a list of map objects within the radius.

abstractmethod query(geometry, layers, predicate=None, sort=False, distance=None)[source]¶

Queries geometries against the map objects in the specified layers using an optional spatial predicate.

Notes

The implementation is aligned with the geopandas spatial index query method [1]_, used in the GPKGMapAPI. It is likely this method will be removed or improved in future versions of 123D.

References

[1] https://geopandas.org/en/stable/docs/reference/api/geopandas.sindex.SpatialIndex.query.html

Parameters:

geometry (Union[Geometry, Iterable[Geometry]]) – A shapely geometry or an iterable of shapely geometries to query against.
layers (List[MapLayer]) – The map layers to query against.
predicate (Optional[Literal['contains', 'contains_properly', 'covered_by', 'covers', 'crosses', 'intersects', 'overlaps', 'touches', 'within', 'dwithin']]) – An optional spatial predicate to filter the results.
sort (bool) – Whether to sort the results by distance, defaults to False.
distance (Optional[float]) – An optional maximum distance to filter the results, defaults to None.

Return type:

Dict[MapLayer, Union[List[BaseMapObject], Dict[int, List[BaseMapObject]]]]

Returns:

A dictionary mapping each layer to a list of map objects or a dictionary of indices to lists of map objects.

abstractmethod query_object_ids(geometry, layers, predicate=None, sort=False, distance=None)[source]¶

Queries geometries against the map objects in the specified layers using an optional spatial predicate. Instead of returning the map objects, it returns their IDs only.

Notes

The implementation is aligned with the geopandas spatial index query method [1]_, used in the GPKGMapAPI. It is likely this method will be removed or improved in future versions of 123D.

References

[1] https://geopandas.org/en/stable/docs/reference/api/geopandas.sindex.SpatialIndex.query.html

Parameters:

geometry (Union[Geometry, Iterable[Geometry]]) – A shapely geometry or an iterable of shapely geometries to query against.
layers (List[MapLayer]) – The map layers to query against.
predicate (Optional[str]) – An optional spatial predicate to filter the results.
sort (bool) – Whether to sort the results by distance, defaults to False.
distance (Optional[float]) – An optional maximum distance to filter the results, defaults to None.

Return type:

Dict[MapLayer, Union[List[int], Dict[int, List[int]]]]

Returns:

A dictionary mapping each layer to a list of map object IDs or a dictionary of indices to lists of map object IDs.

abstractmethod query_nearest(geometry, layers, return_all=True, max_distance=None, return_distance=False, exclusive=False)[source]¶

Return the nearest map objects in a spatial tree for each input geometry in

Notes

The implementation is aligned with the geopandas spatial index nearest method [1]_, used in the GPKGMapAPI. It is likely this method will be removed or improved in future versions of 123D.

References

[1] https://geopandas.org/en/stable/docs/reference/api/geopandas.sindex.SpatialIndex.nearest.html

Parameters:

geometry (Union[Geometry, Iterable[Geometry]]) – A shapely geometry or an iterable of shapely geometries to query against.
layers (List[MapLayer]) – The map layers to query against.
return_all (bool) – Whether to return all matching objects or just the closest one, defaults to True.
max_distance (Optional[float]) – An optional maximum distance to filter the results, defaults to None.
return_distance (bool) – Whether to return the distance to the nearest object, defaults to False.
exclusive (bool) – Whether to exclude the input geometries from the results, defaults to False.

Return type:

Dict[MapLayer, Union[List[BaseMapObject], Dict[int, List[BaseMapObject]]]]

Returns:

A dictionary mapping each layer to a list of nearest map objects or a dictionary of indices to lists of nearest map objects.

property map_metadata: MapMetadata¶: The MapMetadata of the map api.

property dataset: str¶: The dataset name from the map metadata.

property location: str¶: The location from the map metadata.

property map_is_local: bool¶: Indicates if the map is local (map for each log) or global (map for multiple logs in dataset).

property map_has_z: bool¶: Indicates if the map includes Z (elevation) data.

property version: str¶: The version of the py123d library used to create this map metadata.

class py123d.datatypes.map_objects.MapLayer[source]¶

Enum for different map layers (i.e. object types) in a map.

Public Data Attributes:

`LANE`	Lanes (surface).
`LANE_GROUP`	Lane groups (surface).
`INTERSECTION`	Intersections (surface).
`CROSSWALK`	Crosswalks (surface).
`WALKWAY`	Walkways (surface).
`CARPARK`	Carparks (surface).
`GENERIC_DRIVABLE`	Generic drivable (surface).
`STOP_ZONE`	Stop zones (surface).
`ROAD_EDGE`	Road edges (lines).
`ROAD_LINE`	Road lines (lines).

Inherited from Enum

Public Methods:

Inherited from SerialIntEnum

`serialize`([lower])	Serialize the type when saving.
`deserialize`(key)	Deserialize the type when loading from a string.
`from_int`(value)	Get the enum from an int.
`from_arbitrary`(value)	Get the enum from an int, string, or enum instance.

Private Methods:

_generate_next_value_(start, count, last_values)

Generate the next value when not given.

Inherited from SerialIntEnum

_generate_next_value_(start, count, last_values)

Generate the next value when not given.

Inherited from Enum

`_generate_next_value_`(start, count, last_values)	Generate the next value when not given.
`_missing_`(value)
`_new_member_`(value)	Create and return a new object.

LANE = 0¶: Lanes (surface).

LANE_GROUP = 1¶: Lane groups (surface).

INTERSECTION = 2¶: Intersections (surface).

CROSSWALK = 3¶: Crosswalks (surface).

WALKWAY = 4¶: Walkways (surface).

CARPARK = 5¶: Carparks (surface).

GENERIC_DRIVABLE = 6¶: Generic drivable (surface).

STOP_ZONE = 7¶: Stop zones (surface).

ROAD_EDGE = 8¶: Road edges (lines).

ROAD_LINE = 9¶: Road lines (lines).

serialize(lower=True)¶

Serialize the type when saving.

Return type:: str
Parameters:: lower (bool)

classmethod deserialize(key)¶

Deserialize the type when loading from a string.

Return type:: SerialIntEnum
Parameters:: key (str)

classmethod from_int(value)¶

Get the enum from an int.

Return type:: SerialIntEnum
Parameters:: value (int)

classmethod from_arbitrary(value)¶

Get the enum from an int, string, or enum instance.

Return type:: SerialIntEnum
Parameters:: value (int | str | SerialIntEnum)