urbanflow¶

class urbanflow.RasterGrid(coordinate_reference_system='EPSG:32633', cell_size=1)¶

Bases: object

RasterGrid class. Stores the following information: 1. grid: an np.ndarray[np.uint8] with unsigned integer values. 2. transform an Affine transform object to transform points onto the grid 3. legend: a python dict describing the different grid values and their meaning.

Parameters:

coordinate_reference_system (str)
cell_size (float)

cell_size¶

Square cell width/height in CRS units

Type:: float

Interface¶

__init__¶

Type:: constructor

.save(filepath)¶

Type:: saving the grid, as small as possible

.laod(filepath)¶

Type:: load the grid, as quickly as possible

classmethod from_geojson_dataframes(buildings, streets, canals, *, courtyards=None, auto_courtyards=True, coordinate_reference_system='EPSG:32633', cell_size=1, legend={'building': 2, 'canal': 3, 'courtyard': 4, 'ocean': 0, 'street': 1})¶

Rasterize buildings, streets, and canals of Venice into a RasterGrid.

Parameters:

buildings (GeoDataFrames) – All must share the same CRS.
streets (GeoDataFrames) – All must share the same CRS.
canals (GeoDataFrames) – All must share the same CRS.
cell_size (float) – Square cell width/height in CRS units.
legend (Dict[str, int]) – A python dict that contains what cell values contian what. The dict must define: “ocean” : (default 0) “street” : (default 1) “building” : default 2) “canal” : (default 3)
courtyards (GeoDataFrame)
auto_courtyards (bool)
coordinate_reference_system (str)

Return type:

RasterGrid object with grid, transform, and legend.

classmethod load(filepath)¶: Create a RasterGrid object from a .npz compressed file.

save(filepath)¶

Save a RasterGrid to a .npz file.

Parameters:: filepath (str)

to_image(scale=1, palette=None)¶

Convert a uint8 grid of states into a PIL Image.

Parameters:

grid (ndarray[int] shape (rows, cols)) – Cell codes: 0=ocean, 1=street, 2=building (extend as you wish).
scale (int, default 1) – How many output pixels per cell (must be ≥1). 2 doubles width/height.
palette ({state: (R, G, B)}, optional) – Custom colors. Unspecified states default to white.

Return type:

PIL.Image.Image (mode “RGB”)

Notes

Uses pure NumPy → very fast, even for multi-million-cell grids.
Nearest-neighbour up-scaling keeps the crisp blocky CA look.

class urbanflow.RasterGridWithPOIs(POI_gdf, coordinate_reference_system='EPSG:32633', cell_size=1)¶

Bases: RasterGrid

Raster grid with Points of Interest (POIs).

Extends urbanflow.RasterGrid by attaching a geopandas.GeoDataFrame of POIs to the raster grid, aligning them to grid cells, and enabling pathfinding between POIs. Includes methods for saving/loading, path computation, and visualization.

Parameters:: POI_gdf (GeoDataFrame)

POI_gdf¶

GeoDataFrame of points of interest, with columns for grid coordinates (row, col) and optionally adjusted coordinates (row_adj, col_adj).

Type:: geopandas.GeoDataFrame

tcod_cost_grid¶

Grid suitable for tcod pathfinding, with impassable cells set to 0.

Type:: ndarray of int

POI_gdf: GeoDataFrame = None¶

compute_path_between_POIs(start_poi_uid, end_poi_uid, *, do_tcod_pathing=False, uid_column=None, do_logging=False)¶

Compute the shortest path between two POIs on the raster grid.

Parameters:

start_poi_uid (str) – UID of the source POI (index in POI_gdf).
end_poi_uid (str) – UID of the target POI.
do_tcod_pathing (bool, optional) – If True, use tcod pathfinding instead of the C++ planner. Defaults to False.
uid_column (str, optional) – Column name to set as index if POI_gdf is not indexed by UID.
do_logging (bool, optional) – If True, print diagnostic information. Defaults to False.

Returns:

path_r (ndarray of int) – Row indices of the computed path.
path_c (ndarray of int) – Column indices of the computed path.

Return type:

Tuple[ndarray, ndarray]

Notes

If row_adj/col_adj exist, adjusted coordinates are used.
If no path is found, empty arrays are returned.

classmethod from_RasterGrid_and_POIs(raster_grid, POI_gdf, *, do_adjusted=True, force_realignment=False)¶

Construct a RasterGridWithPOIs from an existing RasterGrid and POIs.

Parameters:

raster_grid (RasterGrid) – The base raster grid object.
POI_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing POIs.
do_adjusted (bool, optional) – Whether to compute adjusted POI coordinates (snapped to nearest street cell). Defaults to True.
force_realignment (bool, optional) – If True, realign POIs to the grid even if row/col columns exist. Defaults to False.

Returns:

A new instance with POIs aligned to the raster grid.

Return type:

RasterGridWithPOIs

Rasterize buildings, streets, and canals of Venice into a RasterGrid.

Parameters:

buildings (GeoDataFrames) – All must share the same CRS.
streets (GeoDataFrames) – All must share the same CRS.
canals (GeoDataFrames) – All must share the same CRS.
cell_size (float) – Square cell width/height in CRS units.
legend (Dict[str, int]) – A python dict that contains what cell values contian what. The dict must define: “ocean” : (default 0) “street” : (default 1) “building” : default 2) “canal” : (default 3)
courtyards (GeoDataFrame)
auto_courtyards (bool)
coordinate_reference_system (str)

Return type:

RasterGrid object with grid, transform, and legend.

classmethod from_geojson_dataframes_and_POIs(buildings, streets, canals, POI_gdf, *, courtyards=None, auto_courtyards=True, coordinate_reference_system='EPSG:32633', cell_size=1, legend={'building': 2, 'canal': 3, 'courtyard': 4, 'ocean': 0, 'street': 1}, do_adjusted=True, force_realignment=False)¶

Construct a RasterGridWithPOIs directly from GeoDataFrames of features and a POI GeoDataFrame.

Parameters:

buildings (geopandas.GeoDataFrame) – Feature layers used to generate the base raster grid.
streets (geopandas.GeoDataFrame) – Feature layers used to generate the base raster grid.
canals (geopandas.GeoDataFrame) – Feature layers used to generate the base raster grid.
courtyards (geopandas.GeoDataFrame) – Feature layers used to generate the base raster grid.
POI_gdf (geopandas.GeoDataFrame) – GeoDataFrame of POIs.
auto_courtyards (bool, optional) – Whether to automatically generate courtyard cells. Defaults to True.
coordinate_reference_system (str, optional) – Target CRS. Defaults to EPSG:32633.
cell_size (int, optional) – Grid resolution in coordinate units. Defaults to 1.
legend (dict, optional) – Mapping of feature types to integer codes. Defaults to {ocean:0, street:1, building:2, canal:3, courtyard:4}.
do_adjusted (bool, optional) – Compute adjusted POI coordinates. Defaults to True.
force_realignment (bool, optional) – If True, force POI realignment. Defaults to False.

Returns:

A raster grid with POIs aligned to grid cells.

Return type:

RasterGridWithPOIs

classmethod load(filepath)¶

Load a RasterGridWithPOIs from a saved directory.

Parameters:: filepath (str) – Directory containing saved raster grid and POI files.
Returns:: Loaded raster grid with POIs.
Return type:: RasterGridWithPOIs

save(filepath)¶

Save a RasterGridWithPOIs to a directory.

Parameters:: filepath (str) – Path to the directory where the object will be saved. Creates the directory if it does not exist.

Notes

POIs are stored as a Parquet file.
Grid, transform, legend, and metadata are stored in a compressed NPZ.

tcod_cost_grid: ndarray = None¶

to_image(scale=1, palette=None)¶

Convert a uint8 grid of states into a PIL Image.

Parameters:

grid (ndarray[int] shape (rows, cols)) – Cell codes: 0=ocean, 1=street, 2=building (extend as you wish).
scale (int, default 1) – How many output pixels per cell (must be ≥1). 2 doubles width/height.
palette ({state: (R, G, B)}, optional) – Custom colors. Unspecified states default to white.

Return type:

PIL.Image.Image (mode “RGB”)

Notes

Uses pure NumPy → very fast, even for multi-million-cell grids.
Nearest-neighbour up-scaling keeps the crisp blocky CA look.

to_image_with_POIs(scale=1, palette=None, function_col='PP_Function_TOP', color_map=None, default_color=(0, 0, 0), poi_radius=None)¶

Render the raster grid with POIs drawn as colored dots.

Parameters:

scale (int, optional) – Scale factor for rendering. Each cell becomes a square of size scale. Defaults to 1.
palette (dict of int -> (r,g,b), optional) – Mapping from raster values to RGB colors.
function_col (str, optional) – Column in POI_gdf used for categorical coloring. Defaults to "PP_Function_TOP".
color_map (dict of str -> (r,g,b), optional) – Mapping from categories to RGB colors. If None, a default matplotlib tab20 palette is used.
default_color (tuple of int, optional) – Fallback color (RGB). Defaults to black.
poi_radius (int, optional) – Radius of POI dots in pixels. Defaults to max(1, scale//2).

Returns:

Image of the raster grid with POIs overlayed.

Return type:

PIL.Image.Image

to_image_with_path(path_r, path_c, *, scale=5, palette=None, poi_start=None, poi_end=None, poi_colour=(0, 0, 0), path_colour=(255, 215, 0), path_width=None)¶

Render the raster grid with an overlayed path and optional POI markers.

Parameters:

path_r (ndarray of int) – Row and column indices of the path.
path_c (ndarray of int) – Row and column indices of the path.
scale (int, optional) – Scale factor for rendering. Defaults to 5.
palette (dict of int -> (r,g,b), optional) – Mapping from raster values to RGB colors.
poi_start (tuple of (row, col), optional) – Coordinates of start and end POIs to highlight.
poi_end (tuple of (row, col), optional) – Coordinates of start and end POIs to highlight.
poi_colour (tuple of int, optional) – Color of start/end POI dots. Defaults to black.
path_colour (tuple of int, optional) – Color of the path polyline. Defaults to gold.
path_width (int, optional) – Width of the path polyline in pixels. Defaults to max(1, scale//2).

Returns:

Image of the raster grid with path overlayed.

Return type:

PIL.Image.Image

Modules

`RasterGrid`([coordinate_reference_system, ...])	RasterGrid class.
`RasterGridWithPOIs`(POI_gdf[, ...])	Raster grid with Points of Interest (POIs).
`logging_config`	Centralized logging configuration for the urbanflow package.
`utils`