Graph utilities¶

Low-level access to Valhalla's tiled, hierarchical graph: tile identifiers, tile-to-coordinate math, and direct edge geometry retrieval via a configured GraphReader.

GraphUtils ¶

GraphUtils(config: Union[Path, str, dict])

Bases: _GraphUtils

Utility class for accessing Valhalla graph data structures.

Provides low-level access to graph tiles and edges using Valhalla's tiled routing data. Supports retrieving edge shapes and other graph properties.

Configuration can be provided as:

Path to a JSON config file
JSON string
Python dict

For dict input, the config is serialized to JSON internally.

Initialize GraphUtils with Valhalla configuration.

PARAMETER	DESCRIPTION
`config`	Valhalla configuration as Path, JSON string, or dict. Must contain valid mjolnir.tile_extract or mjolnir.tile_dir. TYPE: `Union[Path, str, dict]`

RAISES	DESCRIPTION
`RuntimeError`	When config is invalid or cannot be parsed
`TypeError`	When config is not Path, str, or dict
`AttributeError`	When config is missing required mjolnir settings
`FileNotFoundError`	When config file or tile data doesn't exist

get_edge_shape ¶

get_edge_shape(edge_id: GraphId) -> list[tuple[float, float]]

Get the shape (polyline) for an edge as a list of (lon, lat) tuples.

PARAMETER	DESCRIPTION
`edge_id`	GraphId of the edge TYPE: `GraphId`

RETURNS	DESCRIPTION
`list[tuple[float, float]]`	List of (lon, lat) tuples representing the edge geometry

RAISES	DESCRIPTION
`RuntimeError`	When the tile or edge is not found

get_graph_tile_header ¶

get_graph_tile_header(tile_id: GraphId) -> GraphTileHeader

Get the GraphTileHeader for the tile that contains this GraphId.

PARAMETER	DESCRIPTION
`tile_id`	GraphId of (or within) the tile TYPE: `GraphId`

RETURNS	DESCRIPTION
`GraphTileHeader`	GraphTileHeader with the tile's summary metadata

RAISES	DESCRIPTION
`RuntimeError`	When the tile is or edge not found

GraphId ¶

Identifier of a node or an edge within the tiled, hierarchical graph. Includes the tile Id, hierarchy level, and a unique identifier within the tile/level.

value `property` ¶

value: int

The integer representation of the bit-fielded GraphId.

tileid ¶

tileid() -> int

Gets the tile Id.

level ¶

level() -> int

Gets the hierarchy level.

id ¶

id() -> int

Gets the identifier within the hierarchy level.

is_valid ¶

is_valid() -> bool

Returns true if the id is valid.

tile_base ¶

tile_base() -> GraphId

Returns a GraphId omitting the id of the of the object within the level. Construct a new GraphId with the Id portion omitted.

tile_value ¶

tile_value() -> int

Returns a value indicating the tile (level and tile id) of the graph Id.

get_tile_base_lon_lat ¶

get_tile_base_lon_lat(graph_id: GraphId) -> tuple

Get the geographic coordinate of the south-western corner of this graph_id's tile.

PARAMETER	DESCRIPTION
`graph_id`	The tile's or object's GraphId TYPE: `GraphId`

RETURNS	DESCRIPTION
`tuple`	The lon/lat coordinate of the SW corner of the tile

get_tile_id_from_lon_lat ¶

get_tile_id_from_lon_lat(level: int, coord: tuple) -> GraphId

Get the tile at this hierarchy level and geographic coordinate.

PARAMETER	DESCRIPTION
`level`	The hierarchy level of the searched tiles. TYPE: `int`
`coord`	The geographic coordinate to intersect with tiles. TYPE: `tuple`

RETURNS	DESCRIPTION
`GraphId`	GraphId of found tile.

RAISES	DESCRIPTION
`ValueError`	When the level or coord are invalid.

get_tile_ids_from_bbox ¶

get_tile_ids_from_bbox(minx: float, miny: float, maxx: float, maxy: float, levels: Sequence[int] = []) -> list[GraphId]

Returns all tiles GraphIds for the specified levels (default: all), which intersect the bbox.

PARAMETER	DESCRIPTION
`minx`	The bbox's minimum longitude. TYPE: `float`
`miny`	The bbox's minimum latitude. TYPE: `float`
`maxx`	The bbox's maximum longitude. TYPE: `float`
`maxy`	The bbox's maximum latitude. TYPE: `float`
`levels`	The hierarchy levels for which to find tiles. TYPE: `Sequence[int]` DEFAULT: `[]`

RETURNS	DESCRIPTION
`list[GraphId]`	The list of tile GraphIds which intersect the bounding box

RAISES	DESCRIPTION
`ValueError`	When the level(s) or coord are invalid.

get_tile_ids_from_ring ¶

get_tile_ids_from_ring(ring_coords: Sequence[tuple], levels: Sequence[int] = []) -> list[GraphId]

Returns all tile GraphIds for the specified levels (default: all), which intersect or are contained within the polygon ring. The ring is assumed and coerced to be an outer ring. It's automatically closed if the last coordinate does not match the first.

PARAMETER	DESCRIPTION
`ring_coords`	List of (lon, lat) tuples forming a closed ring (polygon boundary). Must have at least 3 coordinates. TYPE: `Sequence[tuple]`
`levels`	The hierarchy levels for which to find tiles. TYPE: `Sequence[int]` DEFAULT: `[]`

RETURNS	DESCRIPTION
`list[GraphId]`	The list of tile GraphIds which intersect or are inside the ring.

RAISES	DESCRIPTION
`ValueError`	When the level(s), coords, or ring size are invalid.