cityImage API reference

This page documents the curated public API after the refactor. The package keeps cityImage-specific semantics at the top level and delegates generic operations to specialised libraries:

• file reading and CRS handling to GeoPandas;

• OpenStreetMap acquisition to OSMnx;

• graph algorithms to NetworkX, iGraph, and python-louvain;

• raster/zonal-statistics operations to rasterio/rasterstats;

• optional 3D mesh/ray operations to PyVista and Dask;

• optional static plotting to Matplotlib and mapclassify.

The public API therefore focuses on stable cityImage schemas and computational urban-image semantics: networks, barriers, regions, land use, landmarks, visibility, and imageability scoring. Low-level implementation helpers and generic GeoPandas/Shapely operations are intentionally not listed here.

Schema and adapters

SchemaError	Raised when a GeoDataFrame does not match a cityImage schema contract.
SchemaReport(name, ok[, missing_columns, ...])	Simple validation report returned by schema-checking helpers.
missing_columns(gdf, required_columns)	Return required columns that are absent from a DataFrame.
require_columns(gdf, required_columns, *[, ...])	Raise a SchemaError if required columns are missing.
require_geometry(gdf, *[, frame_name, ...])	Validate that a GeoDataFrame has a geometry column with valid entries.
require_land_use_lists(buildings_gdf, *[, ...])	Validate list-like land-use columns used by pragmatic scoring.
ensure_building_schema_defaults(buildings_gdf, *)	Return buildings with common non-semantic cityImage defaults populated.
validate_nodes_gdf(nodes_gdf)	Validate the minimal cityImage node table contract.
validate_edges_gdf(edges_gdf)	Validate the minimal cityImage edge table contract.
validate_buildings_gdf(buildings_gdf, *[, ...])	Validate the minimal cityImage building table contract.
standardize_nodes_gdf(nodes_gdf, *[, ...])	Return a nodes GeoDataFrame matching the minimal cityImage schema.
standardize_edges_gdf(edges_gdf, *[, ...])	Return an edges GeoDataFrame matching the minimal cityImage schema.
standardize_buildings_gdf(buildings_gdf, *)	Return a buildings GeoDataFrame matching the cityImage building schema.
standardize_cityimage_inputs(*[, nodes_gdf, ...])	Standardize any provided cityImage input tables.

IO and OSM bridge API

These helpers preserve cityImage output schemas while delegating acquisition and file IO to GeoPandas and OSMnx.

network_from_file(input_path, crs, *[, ...])	Load line geometries from file and convert them to cityImage network schema.
buildings_from_file(input_path, crs, *[, ...])	Load building polygons from file and convert them to cityImage schema.
features_from_osm(query, tags, *[, ...])	Download raw OSM features through OSMnx and optionally project them.
network_from_osm(query, *[, ...])	Download an OSM network and convert it to cityImage network schema.
buildings_from_osm(query, *[, ...])	Download OSM buildings and convert them to cityImage building schema.
barriers_from_osm(query, *[, ...])	Download OSM features and build the combined cityImage barrier layer.
network_from_lines(edges_gdf, crs, *[, ...])	Build cityImage nodes/edges from a line GeoDataFrame.
pedestrian_network_from_osm([query, ...])	Download OSM highway features with OSMnx and build a pedestrian network.
pedestrian_network_from_osm_features(...[, ...])	Build a cityImage pedestrian network from already-downloaded OSM features.
filter_pedestrian_osm_features(highways_gdf)	Filter OSM highway features using cityImage pedestrian-network semantics.

Buildings

select_buildings_by_study_area(...[, ...])

Select buildings within a polygon or centroid-distance study area.

Angles and graph semantics

get_coord_angle(origin, distance, angle)	Return coordinates at distance and bearing-like angle from an origin.
angle_line_geometries(line_geometryA, ...[, ...])	Compute the angle between two endpoint-connected LineStrings.
graph_fromGDF(nodes_gdf, edges_gdf)	Create an undirected NetworkX graph from cityImage node/edge GeoDataFrames.
multiGraph_fromGDF(nodes_gdf, edges_gdf)	Create an undirected NetworkX MultiGraph from cityImage graph GeoDataFrames.
dual_gdf(nodes_gdf, edges_gdf, crs[, ...])	Create dual-node and dual-edge GeoDataFrames from a primal street graph.
dual_graph_fromGDF(nodes_dual, edges_dual)	Create a NetworkX graph from dual-node and dual-edge GeoDataFrames.
dual_id_dict(dict_values, graph, node_attribute)	Map a dual-graph node dictionary to a dictionary keyed by primal edge IDs.
from_nx_to_gdf(graph, crs)	Convert a NetworkX graph with geometry attributes into node/edge GeoDataFrames.
nodes_degree(edges_gdf)	Return node degree counts from an edge GeoDataFrame with u/v columns.

Network topology

clean_network(nodes_gdf, edges_gdf[, ...])	Cleans a street network by applying a series of topology and geometry corrections to nodes and edges GeoDataFrames.
simplify_graph(nodes_gdf, edges_gdf[, ...])	The function identify pseudo-nodes, namely nodes that represent intersection between only 2 segments.
clean_duplicate_nodes(nodes_gdf, edges_gdf)	Removes duplicate nodes in a network based on coincident geometry, updating both nodes and edges GeoDataFrames.
clean_duplicate_edges(nodes_gdf, edges_gdf)	Cleans and deduplicates network edges, and removes unused nodes.
clean_same_vertexes_edges(nodes_gdf, edges_gdf)	Removes duplicate edges with the same start and end nodes (same vertexes) in a network GeoDataFrame.
fix_dead_ends(nodes_gdf, edges_gdf)	The function removes dead-ends.
fix_fake_self_loops(nodes_gdf, edges_gdf)	Fix the network topology by removing (fake) self-loops and adding fixed edges.
fix_network_topology(nodes_gdf, edges_gdf)	Node the network at shared, un-noded vertices.
remove_disconnected_islands(nodes_gdf, edges_gdf)	Remove disconnected islands from a graph.
correct_edge_geometries(nodes_gdf, edges_gdf)	The function adjusts the edges LineString coordinates consistently with their relative u and v nodes' coordinates.
consolidate_nodes(nodes_gdf, edges_gdf[, ...])	Consolidates nodes in a spatial network that are within a given distance (tolerance), preserving topology and unclustered nodes.
consolidate_edges(edges_gdf, ...)	Consolidate edge geometries after node consolidation.

Centrality

Centrality wrappers keep cityImage node/edge output semantics while delegating centrality algorithms to graph libraries.

calculate_centrality(nx_graph[, measure, ...])	Calculate centrality values for a NetworkX graph.
reach_centrality(ig_graph, weight, radius, ...)	Calculate reach centrality from an igraph graph.
straightness_centrality(ig_graph, weight[, ...])	Calculate straightness centrality from an igraph graph.
weight_nodes(nodes_gdf, services_gdf, ...[, ...])	Assign local opportunity counts to nodes and to the NetworkX graph.
append_edges_metrics(edges_gdf, graph, ...)	Attach edge-level centrality values to an edges GeoDataFrame.

Barriers

Barrier helpers convert roads, waterways, coastlines, railways, and parks into the Lynchian edge semantics used by cityImage.

barrier_osm_feature_tags()	Return OSM tag queries needed to build the full barrier layer externally.
barriers_from_osm_features(*[, roads_gdf, ...])	Build a combined cityImage barrier layer from already-downloaded OSM features.
road_barriers_from_osm_features(roads_gdf[, ...])	Build road barrier features from already-downloaded OSM highway features.
water_barriers_from_osm_features(*[, ...])	Build water barrier features from already-downloaded OSM water features.
railway_barriers_from_osm_features(railways_gdf)	Build railway barrier features from already-downloaded OSM railway features.
park_barriers_from_osm_features(parks_gdf[, ...])	Build park barrier features from already-downloaded OSM leisure features.
along_water(edges_gdf, barriers_gdf)	Assign water barriers lying along/crossing each street segment.
along_within_parks(edges_gdf, barriers_gdf)	Assign park barrier IDs lying along or containing each street segment.
barriers_along(ix_line, edges_gdf, ...[, offset])	Return barrier IDs along a given edge, excluding touching/crossing barriers.
assign_structuring_barriers(edges_gdf, ...)	Add boolean sep_barr indicating crossing with structuring barriers.

Regions and districts

identify_regions(dual_graph, edges_gdf[, weight])	Identify edge-based regions using delegated python-louvain partitioning.
identify_regions_primal(graph, nodes_gdf[, ...])	Identify node-based regions using delegated python-louvain partitioning.
regions_from_dual_partition(partition, ...)	Assign a precomputed dual-graph partition to primal street segments.
regions_from_primal_partition(partition, ...)	Assign a precomputed primal-graph partition to street nodes.
polygonise_partitions(edges_gdf, column[, ...])	Create district polygons from edge-based partition labels.
district_to_nodes_from_edges(nodes_gdf, ...)	Assign edge-based district IDs to nodes using nearest street segment.
districts_to_edges_from_nodes(nodes_gdf, ...)	Assign node-based district IDs to edges.
district_to_nodes_from_polygons(nodes_gdf, ...)	Assign polygon-based district IDs to nodes using nearest polygon.
amend_nodes_membership(nodes_gdf, edges_gdf, ...)	Amend node membership based on connectivity and minimum district size.
find_gateways(nodes_gdf, edges_gdf, column)	Identify nodes lying on a district boundary.

Land use

Land-use functions cover OSM-derived land-use semantics and sparse/non-OSM attribute workflows.

classify_land_use(buildings_gdf, ...)	Classify sparse attribute values using explicit category lists.
classify_land_uses_raws_into_OSMgroups(...)	Convert per-row triplets into per-row macro-group labels.
classify_land_uses_intoDMAs(buildings_gdf[, ...])	Classify cityImage land-use groups into DMA functional categories.
derive_land_uses_raw_fromOSM(buildings_gdf)	Derive raw cityImage land-use candidates from OSM-style tag columns.
land_use_from_other_gdf(buildings_gdf, ...)	Assign land-use labels to buildings by spatially matching against other_gdf.
land_use_from_points(buildings_gdf, ...)	Collect labels from Point/MultiPoint geometries intersecting each building.
land_use_from_polygons(buildings_gdf, ...[, ...])	Assign land-use labels from polygon layers to building polygons.
classify_sparse_land_uses(buildings_gdf, ...)	Classify sparse/non-OSM land-use attributes attached to buildings.
attach_sparse_land_uses(buildings_gdf, ...)	Spatially attach sparse/non-OSM land-use labels to buildings.
find_land_use_values_matching(buildings_gdf)	Find land-use labels in buildings_gdf[land_uses_column] matching a regex pattern.
find_unclassified_tokens_OSM_groups(...[, ...])	Find UNCLASSIFIED items in "<token>:<group>:<domain>" triplets.

Landmarks and imageability scoring

These functions implement the cityImage landmark and imageability model: structural, visual, cultural, and pragmatic salience, followed by global/local score composition.

LandmarkScoringConfig([...])	Configuration for high-level cityImage building scoring.
structural_score(buildings_gdf, ...[, ...])	The function computes the "Structural Landmark Component" sub-scores of each building.
visibility_score(buildings_gdf[, ...])	Calculate visibility landmark sub-scores.
cultural_score(buildings_gdf[, ...])	Compute a cultural landmark component per building.
pragmatic_score(buildings_gdf[, ...])	Compute a pragmatic landmark component from semantic land-use labels.
compute_global_scores(buildings_gdf, ...)	Compute component and global landmarkness scores.
compute_local_scores(buildings_gdf, ...[, ...])	The function computes landmarkness at the local level.
score_building_components(buildings_gdf, *)	Compute requested building-level cityImage component scores.
score_buildings_global(buildings_gdf, *[, ...])	Compute global cityImage landmarkness scores from component columns.
score_buildings_local(buildings_gdf, *[, ...])	Compute local cityImage landmarkness scores from component columns.
score_cityimage_buildings(buildings_gdf, *)	Run the high-level building component/global/local scoring pipeline.
validate_score_weights(weights, *[, name, ...])	Return numeric weights after validating their values and optional sum.

Building height and terrain elevation

Height helpers are optional. Raster workflows require the height extra.

Terminology: the DTM (bare-earth terrain) provides node z and building base; a surface model (DSM — first-return elevations including rooftops, often distributed under the generic name DEM) compared against the DTM provides above-ground building heights. assign_elevations_from_rasters is the one-stop entry point for cities without building-height data.

assign_elevations_from_rasters(nodes_gdf, ...)	One-stop elevation assignment from rasters, for cities without height data.
buildings_base_from_dtm(buildings_gdf, dtm_path)	Assign per-building ground elevation (base) from a bare-earth DTM.
buildings_height_from_dem_dtm(buildings_gdf, ...)	Compute per-building base elevation and height from DEM and DTM rasters.
assign_building_heights_from_other_gdf(...)	Assign base and height attributes from a detailed building layer.
assign_height_from_dtm(nodes_gdf, dtm_path)	Sample a DTM raster to assign elevation to point nodes.

Visibility

2D visibility is part of the core geospatial workflow. 3D sight-line workflows are optional and require the visibility3d extra, or all.

visibility_polygon2d(building_geometry, ...)	Return the area of the 2D advance-visibility polygon around a building.
compute_3d_sight_lines(nodes_gdf, ...[, ...])	Compute visible 3D sight lines between observer nodes and target buildings.
obstructions_2d(potential_sight_lines, ...)	Split candidate sight lines by 2D planimetric obstruction status.
obstructions_3d(potential_sight_lines, ...)	Check 3D visibility for sight lines with candidate obstructions.
filter_distance(chunk, targets, ...)	Filters potential observer-target pairs by minimum distance and generates sight line geometries.
downsample_coords(line, distance_along)	Sample representative coordinates along a LineString.
polygon_2d_to_3d(building_polygon, base, height)	Extrude a 2D building polygon into a 3D PyVista solid.
merge_gpkg_chunks_to_gdf(out_files, ...)	Merge temporary GeoPackage sight-line chunks.

Geometry and small utilities

Only cityImage-specific geometry helpers are exposed. Generic envelope, convex-hull, distance, file-loading, and arbitrary dataframe helpers were removed from the public API; use GeoPandas/Shapely/Pandas directly for those.

center_line(line_geometries)	Compute a centre line from consistently oriented LineStrings.
split_line_at_MultiPoint(line_geometry, ...)	Split a LineString at one or more point intersections.
fix_multiparts_LineString_gdf(gdf)	Merge or explode MultiLineString geometries into LineString rows.
gdf_multipolygon_to_polygon(gdf[, columnID])	Convert one-part MultiPolygons to Polygons and explode remaining MultiPolygons.
scaling_columnDF(series[, inverse])	Scale numeric values to the unit interval.

Plotting

Plotting is optional and imported lazily. Use these public plotting entry points rather than internal axis, legend, or colorbar helpers.

Plot(figsize, black_background, fontsize[, ...])	Class for creating a basic matplotlib plot with a title and customizable settings.
MultiPlot(figsize, nrows, ncols, ...[, title])	Create a grid of static GeoDataFrame plots.
plot_gdf(gdf[, column, title, ...])	It plots the geometries of a single GeoDataFrame, coloring on the bases of the values contained in column, using a given scheme.
plot_grid_gdfs_column([gdfs, column, ncols, ...])	It plots the geometries of different GeoDataFrames, coloring on the bases of the values contained in the provided column, using a given scheme.
plot_grid_gdf_columns(gdf[, columns, ncols, ...])	It plots the geometries of a GeoDataFrame, coloring on the bases of the values contained in two or more provided columns, using a given scheme.
rand_cmap(nlabels[, type_color])	It generates a categorical random color map, given the number of classes
kindlmann()	It returns a Kindlmann color map.
normalize(n, range1, range2)	Normalizes a value n from one range to another range.
lighten_color(color[, amount])	Lightens the given color by multiplying (1-luminosity) by the given amount.
random_colors_list(nlabels[, vmin, vmax, hsv])	Generates a list of random HSV colors given the number of classes, minimum and maximum values in the HSV spectrum.