Occupancy Map

class py123d.geometry.OccupancyMap2D

Class to represent a 2D occupancy map of shapely geometries using an str-tree for efficient spatial queries.

Public Data Attributes:

ids	Getter for geometry IDs in occupancy map
geometries	Getter for geometries in occupancy map.
id_to_idx	Mapping from geometry IDs to indices in the occupancy map.

Public Methods:

from_dict(geometry_dict[, node_capacity])	Constructs a 2D occupancy map from a dictionary of geometries.
intersects(geometry)	Searches for intersecting geometries in the occupancy map.
query(geometry[, predicate, distance])	Queries the str-tree for geometries that match the given predicate with the input geometry.
query_nearest(geometry[, max_distance, ...])	Queries the str-tree for the nearest geometry to the input geometry.
contains_vectorized(points)	Determines wether input-points are in geometries (i.e. polygons) of the occupancy map.

---

classmethod from_dict(geometry_dict, node_capacity=10)

Constructs a 2D occupancy map from a dictionary of geometries.

Parameters:

• geometry_dict (Union[Dict[str, BaseGeometry], Dict[int, BaseGeometry]]) – Dictionary mapping geometry identifiers to shapely geometries

• node_capacity (int) – Max number of child nodes in str-tree, defaults to 10

Return type:

OccupancyMap2D

Returns:

OccupancyMap2D instance

property ids: List[str] | List[int]

Getter for geometry IDs in occupancy map

Returns:

list of IDs

property geometries: Sequence[BaseGeometry]

Getter for geometries in occupancy map.

Returns:

list of geometries

property id_to_idx: Dict[int | str, int]

Mapping from geometry IDs to indices in the occupancy map.

Returns:

dictionary of IDs and indices

intersects(geometry)

Searches for intersecting geometries in the occupancy map.

Parameters:

geometry (BaseGeometry) – geometries to query

Return type:

Union[List[str], List[int]]

Returns:

list of IDs for intersecting geometries

query(geometry, predicate=None, distance=None)

Queries the str-tree for geometries that match the given predicate with the input geometry.

Parameters:

• geometry (Union[BaseGeometry, ndarray]) – Geometry or array_like

• predicate (Optional[Literal['intersects', 'within', 'dwithin', 'contains', 'overlaps', 'crosses', 'touches', 'covers', 'covered_by']]) – {None, ‘intersects’, ‘within’, ‘contains’, ‘overlaps’, ‘crosses’, ‘touches’, ‘covers’, ‘covered_by’, ‘contains_properly’, ‘dwithin’}, defaults to None

• distance (Optional[float]) – number or array_like, defaults to None.

Return type:

ndarray[tuple[Any, ...], dtype[int64]]

Returns:

ndarray with shape (n,) if geometry is a scalar. Contains tree geometry indices.

Returns:

ndarray with shape (2, n) if geometry is an array_like The first subarray contains input geometry indices. The second subarray contains tree geometry indices.

query_nearest(geometry, max_distance=None, return_distance=False, exclusive=False, all_matches=True)

Queries the str-tree for the nearest geometry to the input geometry.

Parameters:

• geometry (Union[BaseGeometry, ndarray]) – The input geometry to query.

• max_distance (Optional[float]) – The maximum distance to consider, defaults to None.

• return_distance (bool) – Whether to return the distance to the nearest geometry, defaults to False.

• exclusive (bool) – Whether to exclude the input geometry from the results, defaults to False.

• all_matches (bool) – Whether to return all matching geometries, defaults to True.

Return type:

Union[ndarray[tuple[Any, ...], dtype[int64]], Tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[float64]]]]

Returns:

The nearest geometry or geometries.

contains_vectorized(points)

Determines wether input-points are in geometries (i.e. polygons) of the occupancy map.

Notes

This function can be significantly faster than using the str-tree, if the number of geometries is relatively small compared to the number of input-points.

Parameters:

points (ndarray[tuple[Any, ...], dtype[float64]]) – array of shape (num_points, 2), indexed by Point2DIndex.

Return type:

ndarray[tuple[Any, ...], dtype[bool]]

Returns:

boolean array of shape (polygons, input-points)