cityImage API reference#

angles#

get_coord_angle(origin, distance, angle)

The function returns the coordinates of the line starting from a tuple of coordinates, which forms with the y axis an angle in degree of a certain magnitude, given the distance from the origin.

angle_line_geometries(line_geometryA, ...[, ...])

Given two LineStrings it computes the angle between them.

Barriers#

road_barriers(place, download_method[, ...])

The function downloads major roads from OSM.

water_barriers(place, download_method[, ...])

The function downloads water bodies from OSM.

railway_barriers(place, download_method[, ...])

The function downloads overground railway structures from OSM.

park_barriers(place, download_method[, ...])

The function downloads parks areas with a certain extent and converts them to LineString features.

along_water(edges_gdf, barriers_gdf)

The function assigns to each street segment in a GeoDataFrame the list of barrierIDs corresponding to waterbodies which lay along the street segment.

along_within_parks(edges_gdf, barriers_gdf)

The function assigns to each street segment in a GeoDataFrame the list of barrierIDs corresponding to parks which lie along the street segments.

barriers_along(ix_line, edges_gdf, ...[, offset])

The function returns list of barrierIDs along the edgeID of a street segment, given a certain offset.

assign_structuring_barriers(edges_gdf, ...)

The function return a GeoDataFrame with an added boolean column field that indicates whether the street segment intersects a separating/structuring barrier.

get_barriers(place, download_method[, ...])

The function returns all the barriers (water, park, railways, major roads) within a certain urban area.

centrality#

reach_centrality(G, weight, radius, attribute)

Calculates the reach centrality of each node in the graph G based on the attribute of the reachable nodes within a given radius.

straightness_centrality(G, weight[, normalized])

Straightness centrality compares the length of the path between two nodes with the straight line that links them capturing a centrality that refers to ‘being more directly reachable’.

weight_nodes(nodes_gdf, services_gdf, G, ...)

Given a nodes' and a services/points' GeoDataFrame, the function assigns an attribute to nodes in the graph G (prevously derived from nodes_gdf) based on the amount of features in the services_gdf in a buffer around each node.

append_edges_metrics(edges_gdf, G, dicts, ...)

"

clean#

clean_network(nodes_gdf, edges_gdf[, ...])

It calls a series of functions to clean nodes and edges GeoDataFrames. It handles: - pseudo-nodes; - duplicate-geometries (nodes and edges); - disconnected islands - optional; - edges with different geometry but same nodes - optional; - dead-ends - optional; - self-loops - optional; - toplogy issues - optional.

simplify_graph(nodes_gdf, edges_gdf[, ...])

The function identify pseudo-nodes, namely nodes that represent intersection between only 2 segments.

duplicate_nodes(nodes_gdf, edges_gdf[, nodeID])

The function checks the existencce of duplicate nodes through the network, on the basis of geometry.

fix_dead_ends(nodes_gdf, edges_gdf)

The function removes dead-ends.

is_nodes_simplified(nodes_gdf, edges_gdf[, ...])

The function checks the presence of pseudo-junctions, by using the edges_gdf GeoDataFrame.

is_edges_simplified(edges_gdf, ...)

The function checks the presence of possible duplicate geometries in the edges_gdf GeoDataFrame.

merge_pseudo_edges(first_edge, second_edge, ...)

Merge pseudo-edges by updating node and edge information in the corresponding GeoDataFrames.

simplify_same_vertexes_edges(edges_gdf, ...)

This function is used to simplify edges that have the same start and end point (i.e.

fix_network_topology(nodes_gdf, edges_gdf)

Fix the network topology by splitting intersecting edges and adding fixed edges to the network.

fix_self_loops(nodes_gdf, edges_gdf)

Fix the network topology by removing (fake) self-loops and adding fixed edges.

remove_disconnected_islands(nodes_gdf, ...)

Remove disconnected islands from a graph.

correct_edges(nodes_gdf, edges_gdf)

The function adjusts the edges LineString coordinates consistently with their relative u and v nodes' coordinates.

colors#

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.

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.

graph#

graph_fromGDF(nodes_gdf, edges_gdf[, nodeID])

From two GeoDataFrames (nodes and edges), it creates a NetworkX undirected Graph.

multiGraph_fromGDF(nodes_gdf, edges_gdf, ...)

From two GeoDataFrames (nodes and edges), it creates a NetworkX.MultiGraph.

dual_gdf(nodes_gdf, edges_gdf, epsg[, ...])

It creates two dataframes that are later exploited to generate the dual graph of a street network.

dual_graph_fromGDF(nodes_dual, edges_dual)

The function generates a NetworkX.Graph from dual-nodes and -edges GeoDataFrames.

dual_id_dict(dict_values, G, node_attribute)

It can be used when one deals with a dual graph and wants to link analyses conducted on this representation to the primal graph.

nodes_degree(edges_gdf)

It returns a dictionary where keys are nodes identifier (e.g.

land_use#

classify_land_use(buildings_gdf, ...)

The function reclassifies land-use descriptors in a land-use field according to the categorisation presented below.

land_use_from_other_gdf(buildings_gdf, ...)

It assigns land-use attributes to buildings in a buildings GeoDataFrame, looking for possible matches in "other_gdf", a Polygon or Point GeoDataFrame Polygon: Possible matches here means the buildings in "other_gdf" whose area of interesection with the examined building (y), covers at least 60% of the building's (y) area.

landmarks#

get_buildings_fromFile(path, epsg[, ...])

The function take a building footprint .shp or .gpkg, returns two GDFs of buildings: the case-study area, plus a larger area containing other buildings, called "obstructions" (for analyses which include adjacent buildings).

get_buildings_fromOSM(place, download_method)

The function downloads and cleans building footprint geometries and create a buildings GeoDataFrames for the area of interest.

structural_score(buildings_gdf, ...[, ...])

The function computes the "Structural Landmark Component" sub-scores of each building.

number_neighbours(geometry, ...)

The function counts the number of neighbours, in a GeoDataFrame, around a given geometry, within a research radius.

visibility_score(buildings_gdf[, ...])

The function calculates the sub-scores of the "Visibility Landmark Component".

facade_area(building_geometry, building_height)

Compute the approximate facade area of a building given its geometry and height.

get_historical_buildings_fromOSM(place, ...)

The function downloads and cleans building footprint geometries and create a buildings GeoDataFrames for the area of interest.

cultural_score(buildings_gdf[, ...])

The function computes the "Cultural Landmark Component" based on the number of features listed in historical/cultural landmarks datasets.

pragmatic_score(buildings_gdf[, research_radius])

The function computes the "Pragmatic Landmark Component" based on the frequency, and therefore unexpectedness, of a land_use class in an area around a building.

compute_global_scores(buildings_gdf, ...)

Computes the component and global scores for a buildings GeoDataFrame, rescaling values when necessary and assigning weights to the different properties measured.

compute_local_scores(buildings_gdf, ...[, ...])

The function computes landmarkness at the local level.

load#

get_network_fromOSM(place, download_method)

The function downloads and creates a simplified OSMNx graph for a selected area's street network.

get_network_fromFile(path, epsg[, ...])

The function loads a vector lines from a specified directory, along with the epsg coordinate code.

get_network_fromGDF(edges_gdf, epsg[, ...])

The function loads a vector lines shapefile from a given LineString GeoDataFrame, along with the epsg coordinate code.

obtain_nodes_gdf(edges_gdf, crs)

It obtains the nodes GeoDataFrame from the unique coordinates pairs in the edges_gdf GeoDataFrame.

join_nodes_edges_by_coordinates(nodes_gdf, ...)

The function merge the u-v nodes information, from the nodes GeoDataFrame, with the edges_gdf GeoDataFrame.

reset_index_graph_gdfs(nodes_gdf, edges_gdf)

The function simply resets the indexes of the two dataframes.

plot#

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.

regions#

identify_regions(dual_graph, edges_gdf[, weight])

It identifies regions in the street network, using the dual graph representation.

identify_regions_primal(graph, nodes_gdf[, ...])

It identifies regions in the street network, using the primal graph representation.

polygonise_partitions(edges_gdf, column[, ...])

Given districts assign to street segments it create polygons representing districts, either by creating a convex_hull for each group of segments or simply polygonising them.

district_to_nodes_from_edges(nodes_gdf, ...)

It assigns districts' identifiers to the street junctions (nodes), when the districts are assigned to the street segments (edges), i.e. communities are identified on the dual graph.

districts_to_edges_from_nodes(nodes_gdf, ...)

It assigns districts' identifiers to the street segments (edges), when the districts are assigned to the junctions(nodes), i.e. communities are identified on the primal graph.

district_to_nodes_from_polygons(nodes_gdf, ...)

It assigns districts' identifiers to the street junctions (nodes), from polygons representing district areas.

amend_nodes_membership(nodes_gdf, edges_gdf, ...)

Amend the membership of nodes to districts based on connectivity and minimum district size.

find_gateways(nodes_gdf, edges_gdf, column)

This function identifies junctions lying on the boundary of a district, thus connected to other districts through "bridge" edges.

utilities#

downloader(place, download_method[, tags, ...])

The function downloads certain geometries from OSM, by means of OSMNX functions.

scaling_columnDF(series[, inverse])

Rescales the values in a dataframe's column from 0 to 1 or from 1 to 0.

dict_to_df(list_dict, list_col)

It takes a list of dictionaries and creates from them a pandas DataFrame.

center_line(line_geometryA, line_geometryB)

Given two LineStrings, it derives the corresponding center line

min_distance_geometry_gdf(geometry, gdf)

Given a geometry and a GeoDataFrame, it returns the minimum distance between the geometry and the GeoDataFrame.

split_line_at_MultiPoint(line_geometry, ...)

The function checks whether the coordinates of one or more Points in a Point Collections are part of the sequence of coordinates of a LineString.

merge_line_geometries(line_geometries)

Given a list of LineString geometries, this function reorders the geometries in the correct sequence based on their starting and ending points, and returns a merged LineString feature.

envelope_wgs(gdf)

Given a GeoDataFrame it derives its envelope in the WGS coordinate system.

convex_hull_wgs(gdf)

Given a GeoDataFrame it derives its convex hull in the WGS coordinate system.

rescale_ranges(n, range1, range2)

Given a value n and the range which it belongs to, the function rescale the value, between a different range.

gdf_from_geometries(geometries, crs)

The function creates a GeoDataFrame from a list of geometries.

line_at_centroid(line_geometry, offset)

Given a LineString, it creates a perpendicular LineString that intersects the given geometry at its centroid.

sum_at_centroid(line_geometry, lines_gdf, column)

Given a LineString geometry, it sums the column values of all the features in a LineString GeoDataFrame intersecting the line.

polygons_gdf_multiparts_to_singleparts(...)

The function extracts the individual parts of the multi-part geometries and creates a new GeoDataFrame with single part geometries.

fix_multiparts_LineString_gdf(gdf)

Fixes MultiLineString geometries in a GeoDataFrame by merging them into LineString geometries.

remove_lists_columns(df)

For each cell in the DataFrame, if the cell contains a list, update it to keep only the first element of the list.

polygon_2d_to_3d(building_polygon, base, height)

Convert a 2D polygon to a 3D polygon.

visibility#

visibility_polygon2d(building_geometry, ...)

It creates a 2d polygon of visibility around a polygon geometry (e.g.

compute_3d_sight_lines(nodes_gdf, buildings_gdf)

Computes the 3D sight lines between observer points in a Point GeoDataFrame and target buildings, based on a given distance along the buildings' exterior and a minimum distance between observer and target (e.g.

intervisibility(line2d, buildingID, start, ...)

Check if a 3d line of sight between two points is obstructed by any buildings.