Utils

Geograph utils

approx_map_unit_factor(point, tolerance=1e-07, method='geodesic')[source]

Compute a linear approximation of the map unit factor u for 1 meter:

\[d(p_1, p_2) pprox ||p1 - p2||_2 imes u\]

This can be useful to not change the CRS of geograph. The approximation can be very wrong for long distances.

Parameters
  • point – Point where the approximation is computed.

  • tolerance – Precision for the iterative method

  • method – Distance method (geodesic, great_circle)

Returns

Return type

The linear approximation unit factor.

Examples

>>> import geonetworkx as gnx
>>> p1 = gnx.Point(-73.614, 45.504)
>>> u = gnx.approx_map_unit_factor(p1)
>>> p2 = gnx.Point(-73.613, 45.502)
>>> "%.2f" % gnx.geodesic_distance(p1, p2)
'235.62'
>>> "%.2f" % (gnx.euclidian_distance(p1, p2) / u)
'214.83'
Return type

float

compose(G, H)[source]

Return a new graph of G composed with H. Makes sure the returned graph is consistent with respect to the spatial keys. (See nx.compose). According to the priority rule in networkX, attributes from H take precedent over attributes from G.

Return type

GeoGraph

crs_equals(crs1, crs2)[source]

Compare CRS using pyproj.Proj objects.

Return type

bool

euclidian_distance(p1, p2)[source]

Return the euclidian distance between the two points

Parameters
  • p1 (Point) – The first shapely Point

  • p2 (Point) – The second shapely Point

Returns

The euclidian distance

Return type

float

Return type

float

euclidian_distance_coordinates(c1, c2)[source]

Return the euclidian distance between the two sets of coordinates.

Return type

float

fill_edges_missing_geometry_attributes(graph)[source]

Add a geometry attribute to the edges that don’t have any. The created geometry is a straight line between the two nodes.

Parameters

graph (GeoGraph) – graph to fill

fill_elevation_attribute(graph, attribute_name='elevation[m]', only_missing=True)[source]

Fill the elevation[m] attribute on nodes of the given geograph. The elevation is found with the srtm package. Graph crs has to be WGS84 standard, otherwise elevation data won’t be consistent.

Parameters
  • graph (GeoGraph) – GeoGraph to modify

  • attribute_name (str) – Attribute to fill (Default value = “elevation[m]”)

  • only_missing (bool) – Get the elevation and set it only if the node attribute is missing. (Default value = True)

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph(crs=gnx.WGS84_CRS)
>>> g.add_edge(1, 2, geometry=gnx.LineString([(5.15, 45.504), (5.167, 45.506)]))
>>> gnx.fill_elevation_attribute(g)  
>>> print(g.nodes[1]["elevation[m]"])  
393
fill_length_attribute(graph, attribute_name='length', only_missing=True, method=None)[source]

Fill the 'length' attribute of the given networkX Graph.

Parameters
  • graph (GeoGraph) – graph to fill

  • attribute_name (str) – The length attribute name to set (Default value = “length”)

  • only_missing (bool) – Compute the length only if the attribute is missing (Default value = True)

  • method (str) – Method to compute the distance

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph(crs=gnx.WGS84_CRS)
>>> g.add_edge(1, 2, geometry=gnx.LineString([(-73.614, 45.504), (-73.632, 45.506)]))
>>> gnx.fill_length_attribute(g)  # using geodesic distance
>>> "%.2f" % g.edges[(1, 2)]["length"]
'1424.17'
>>> g.to_utm(inplace=True)
>>> gnx.fill_length_attribute(g, only_missing=False)
>>> "%.2f" % g.edges[(1, 2)]["length"]  # using euclidian distance in UTM
'1423.81'
geodesic_distance(p1, p2)[source]
Return geopy geodesic distance with two given point in the

long/lat format.

Parameters
  • p1 – First 2D point

  • p2 – Second 2D point

Returns

Return type

The geodesic distance in meters.

Examples

>>> import geonetworkx as gnx
>>> p1 = gnx.Point(-73.614, 45.504)  # long/lat format
>>> p2 = gnx.Point(-73.632, 45.506)
>>> "%.2f" % gnx.geodesic_distance(p1, p2)
'1424.17'
Return type

float

geographical_distance(graph, node1, node2, method='great_circle')[source]

Return the geographical distance between the two given nodes.

Parameters
  • graph (Geograph) – Geograph

  • node1 – First node label

  • node2 – Second node label

  • method (str) – “geodesic”, “euclidian”, “great_circle” (Default value = “great_circle”)

Returns

Distance between nodes, unit depends on the method.

Return type

float

Return type

float

get_closest_nodes(graph, point, k, **kwargs)[source]

Return the k closest nodes from the given point.

Euclidian distance is used here by default.

Parameters
  • graph – Geograph on which nodes are browsed

  • point – Query point on which the distances from nodes are computed.

  • k – Number of nodes to return.

  • kwargs – Additional parameters to send to scipy.spatial.cKDTree.query method.

Returns

A list containing closest nodes labels.

Return type

list

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_nodes_from([(1, gnx.Point(1, 1)),
...                   (2, gnx.Point(-1, 3)),
...                   (3, gnx.Point(-1, -4)),
...                   (4, gnx.Point(-1, -1)),
...                   (5, gnx.Point(-10, 10))])
>>> cns = gnx.get_closest_nodes(g, gnx.Point(0, 0), 3)
>>> print(cns)
[1, 4, 2]
Return type

list

get_crs_as_str(crs)[source]

Return the given CRS as string pyproj.Proj methods.

Return type

str

get_default_distance_method_from_crs(crs)[source]

Return the default method for computing distances for the given CRS.

Parameters

crs – Coordinate Reference System

Returns

Return type

String representing the distance calculation method.

Return type

str

get_distance(p1, p2, method)[source]

Return the distance between the two given points with the given method.

Return type

float

get_graph_bounding_box(graph)[source]

Return the bounding box coordinates of the given GeoGraph. It takes into account nodes and edges geometries.

get_line_ordered_edge(graph, e, line)[source]

Return the given edge with the first node of the edge representing the first line point and the second node the last edge point. The closest node rule is applied.

get_line_start(graph, e, line)[source]

For a given edge, return the node constituting the line start with a closest node rule.

get_new_node_unique_name(graph, name)[source]

Return a new unique node name from an initial node name. A counter suffix is added at the end if the node name is already used.

Parameters
  • graph (nx.Graph) – A given graph

  • name (str) – A initial node name

Returns

A unique name not in graph.nodes().

Return type

str

get_surrounding_nodes(graph, point, r, **kwargs)[source]

Return all nodes that are within distance r of given point.

Euclidian distance is used here by default.

Parameters
  • graph – Geograph on which nodes are browsed

  • point – Query point on which the distances from nodes are computed.

  • r – Maximum distance between point and nodes to return.

  • kwargs – Additional parameters to send to scipy.spatial.cKDTree.query_ball_point method.

Returns

A list containing nodes labels that are within the distance.

Return type

list

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_nodes_from([(1, gnx.Point(1, 1)),
...                   (2, gnx.Point(-1, 3)),
...                   (3, gnx.Point(-1, -4)),
...                   (4, gnx.Point(-1, -1)),
...                   (5, gnx.Point(-10, 10))])
>>> sns = gnx.get_surrounding_nodes(g, gnx.Point(0, 0), 1.5)
>>> print(sns)
[1, 4]
Return type

list

get_utm_crs(p)[source]

Return the Universal Transverse Mercator CRS with a given in point in long-lat format.

great_circle_distance(p1, p2)[source]
Return geopy great circle distance with two given point in the

long/lat format.

Parameters
  • p1 – First 2D point

  • p2 – Second 2D point

Returns

Return type

The great circle distance in meters.

Examples

>>> import geonetworkx as gnx
>>> p1 = gnx.Point(-73.614, 45.504)  # long/lat format
>>> p2 = gnx.Point(-73.632, 45.506)
>>> "%.2f" % gnx.great_circle_distance(p1, p2)
'1420.27'
Return type

float

hard_write_spatial_keys(graph)[source]

Write spatial keys in the graph attribute, so that if the default keys are used, they are propagated for special operations (e.g. composing graphs).

is_null_crs(crs)[source]

Test for null crs values.

Return type

bool

join_lines_extremity_to_nodes_coordinates(graph)[source]

Modify the edges geometry attribute so that lines extremities match with nodes coordinates.

Parameters

graph (GeoGraph) – A geograph to modify

measure_line_distance(line, method)[source]

Measure the length of a shapely LineString object using the given distance method.

Parameters
  • line – Linestring to measure. Coordinates have to be (in the WGS-84 ellipsoid model)

  • method – Method to compute the distance

Returns

distance in meters of the linestring.

Return type

float

Return type

float

measure_multi_line_distance(multiline, method)[source]

Measure the length of shapely MultiLineString object using the given distance method.

Parameters
  • multiline – MultiLineString to measure.

  • method – Method to compute the distance

Returns

Sum of distances of all linestrings composing the multilinestring in meters.

Return type

float

Return type

float

order_well_lines(graph)[source]

Try to order well each geometry attribute of edges so that the first coordinates of the line string are the coordinates of the first vertex of the edge. The closest node rule is applied. If the graph is not oriented, the modification will be inconsistent (nodes declaration in edges views are not ordered). Euclidian distance is used here.

Parameters

graph (GeoGraph) – Graph on which to apply the ordering step. Modification is inplace.

rename_edges_attribute(graph, old_name, new_name)[source]

Rename edges attribute defined by its old name to a new name.

rename_nodes_attribute(graph, old_name, new_name)[source]

Rename nodes attribute defined by its old name to a new name.

stringify_nodes(graph, copy=True)[source]

Modify the graph node names into strings.

Voronoi utils

class PyVoronoiHelper(points, segments, bounding_box_coords, scaling_factor=100000.0)[source]

Bases: object

Add-on for the pyvoronoi (boost voronoi) tool. It computes the voronoi cells within a bounding box.

static add_polygon_coordinates(coordinates, point)[source]

Add given point to given coordinates list if is not the equal to the last coordinates.

clip_infinite_edge(cell_coords, edge, eta)[source]

Fill infinite edge coordinate by placing the infinite vertex to a eta distance of the known vertex.

get_cells_as_gdf(with_more_attributes=False)[source]

Returns the voronoi cells in geodataframe with a column named id referencing the index of the associated input geometry.

Return type

GeoDataFrame

get_cells_as_polygons()[source]

Return the voronoi cells as polygons trimmed with the bounding box.

Return type

dict

get_cells_coordiates(eta=1.0, discretization_tolerance=0.05)[source]

“Parse the results of pyvoronoi to compute the voronoi cells coordinates. The infinite ridges are projected at a eta distance in the ridge direction.

Parameters
  • eta (float) – Distance for infinite ridges projection. (Default value = 1.0)

  • discretization_tolerance (float) – Discretization distance for curved edges. (Default value = 0.05)

Returns

A dictionary mapping the cells ids and their coordinates.

Return type

dict

Return type

dict

static repair_bowtie_polygon(polygon)[source]

Repair an invalid polygon for the ‘bowtie’ case.

Return type

MultiPolygon

static repair_polygon(polygon)[source]

Repair an invalid polygon. It works in most cases but it has no guarantee of success.

Return type

Union[Polygon, MultiPolygon]

compute_voronoi_cells_from_lines(lines, tolerance=1e-07)[source]

Compute the voronoi cells of given generic lines. Input linestrings can be not simple.

Parameters
  • lines (list) – List of LineString

  • tolerance (float) – Tolerance for the voronoi cells computation (Two points will be considered equal if their coordinates are equal when rounded at tolerance). (Default value = 1e-7)

Returns

A list of cells geometries.

Return type

list

Return type

list

split_as_simple_segments(lines, tol=1e-07)[source]

Split a list of lines to simple segments (linestring composed by two points). All returned segments do not cross themselves except at extremities.

Parameters
  • lines (list) – List of lines to split

  • tol (float) – Tolerance to test if a line is a sub line of another one. (Default value = 1e-7)

Returns

A dictionary mapping for each input line index, the list of simple segments.

Return type

defaultdict

Return type

defaultdict

split_linestring_as_simple_linestrings(line)[source]

Split a linestring if it is not simple (i.e. it crosses itself).

Return type

list

Generators utils

_get_ego_boundaries(graph, ego_graph, n, radius, distance=None)[source]

Retrieve all information to build an extended ego-graph. See gnx.extended_ego_graph for more info.

Return type

tuple

add_ego_boundary_nodes(graph, n, radius, distance, undirected=False)[source]

Modify the given graph to add boundary nodes at exact radius distance. An edge \((u, v)\) is a boundary edge if \((u, v)\) if \(d(n, u) < radius < d(n, v)\). A boundary node is added on the edge to represent the ego- graph limit. See gnx.extended_ego_graph for more info.

Parameters
  • graph (GeoGraph, GeoDiGraph, GeoMultiGraph or GeoMultiDiGraph) – Input graph to modify

  • n – A single source node

  • radius (float or int) – Include all neighbors of distance<=radius from n.

  • distance (str) – Use specified edge data key as distance. For example, setting distance=’weight’ will use the edge weight to measure the distance from the node n.

  • undirected (bool) – If True use both in- and out-neighbors of directed graphs. (Default value = False)

extended_ego_graph(graph, n, radius=1, center=True, undirected=False, distance=None)[source]

Returns induced subgraph of neighbors centered at node n within a given radius extended by interpolated nodes on boundary edges.

Note that the returned graph is not a subgraph of the input graph because it will have boundary nodes in addition. It means that a node is added on each edge leaving the ego-graph to represent the furthest reachable point on this edge. The boundary node is added at given node using a linear interpolation. A boundary node \(b\) will be added on the edge \((u, v)\) if \(d(n, u) < radius < d(n, v)\). The boundary will be placed along the edge geometry at the following distance:

\[d(u, b) = \frac{\text{radius} - d(n, u)}{d(u, v)}\]

Furthermore, the attribute distance is filled with the value \(d(u, b)\).

Parameters
  • graph (GeoGraph, GeoDiGraph, GeoMultiGraph or GeoMultiDiGraph) – A Geograph or subclass

  • n – A single source node

  • radius (float or int) – Include all neighbors of distance<=radius from n. (Default value = 1)

  • center (bool) – If False, do not include center node in graph (Default value = True)

  • undirected (bool) – If True use both in- and out-neighbors of directed graphs. (Default value = False)

  • distance (str) – Use specified edge data key as distance. For example, setting distance=’weight’ will use the edge weight to measure the distance from the node n. (Default value = None)

Returns

The resulting graph with node, edge, and graph attributes copied.

Return type

GeoGraph, GeoDiGraph, GeoMultiGraph or GeoMultiDiGraph

Return type

GeoGraph