ops Package#

graph Module#

surficial.ops.graph.address_to_point(graph, edge, m)#

Return a Point location given an edge address within an Alignment

Parameters:

  • graph (Alignment) – directed network graph

  • edge (tuple[int, int]) – tuple identifying the edge

  • m (float) – distance measure along the edge geometry

Returns:

point address location

Return type:

Point

surficial.ops.graph.extend_edge(graph, edge, window=10, statistic='min')#

Extend an edge using vertices from neighboring edges

Parameters:

  • graph (Alignment) – network graph

  • edge (tuple[int, int]) – edge to extend

  • window (int) – number of vertices to extend the edge

  • statistic (str) – function used to determine which edge to use among several

Returns:

vertices of the input edge with added vertices from preceeding and successor edges

Return type:

DataFrame

surficial.ops.graph.get_neighbor_edge(graph, edge, column='z', direction='up', window=None, statistic='min')#

Return the neighboring edge having the lowest minimum value

Parameters:

  • graph (Alignment) – directed network graph

  • edge (tuple[int, int]) – edge for which to determine a neighbor

  • column (str) – column to test in vertices

  • direction (str) – ‘up’ tests predecessor edges; ‘down’ tests successors

  • window (None | int) – number of neighbor vertices to test

  • statistic (str) – test statistic

Returns:

edge meeting the criteria

Return type:

None | tuple[int, int]

surficial.ops.graph.get_path_distances(point_addresses, edge_addresses)#

Calculate point distances from a node

Parameters:

  • point_addresses (DataFrame) – point address information

  • edge_addresses (DataFrame) – edge address information

Returns:

DataFrame of point address information relative to an outlet node in a network

m (float):

distance along the edge geometry

x (float):

projected point x coordinate

y (float):

projected point y coordinate

z (float):

projected point z coordinate

d (float):

offset distance, or distance from the point to its projection

edge (tuple[int, int]):

tuple of node identifiers identifying an edge

from_node_address (float):

cost path distance from the edge start node to the outlet node

to_node_address (float):

cost path distance from the edge end node to the outlet node

path_m (float):

path distance from the point to the outlet node

Return type:

DataFrame

surficial.ops.graph.get_pre_window(edges, vertices, window, column, statistic='min')#

Determine a ‘winning’ edge where a node has multiple edges

Parameters:

  • edges (list[tuple[int, int]]) – edges to evaluate

  • vertices (DataFrame) – vertices making up the edges

  • window (int) – size of the window around the edge endpoints

  • column (str) – column name for the elevation

  • statistic (str) – test statistic (not implemented, only minumum used)

Returns:

modified vertices

Return type:

DataFrame

surficial.ops.graph.points_to_addresses(graph, points, radius=100, edges=None, reverse=False)#

Locate points by address along the nearest graph edge

Returns a DataFrame describing the addresses (projections) of points, within some distance, onto a set of graph edges.

Parameters:

  • graph (Alignment) – directed network graph

  • points (list[Point]) – points to project

  • radius (int | float) – buffer radius

  • edges (None | list[tuple[int, int]]) – edge tuples onto which points will be projected, if None then all edges in graph are used

  • reverse (bool) – reverse vertex ordering

Returns:

DataFrame of point address information relative to individual edges

m (float):

distance along the edge geometry

x (float):

projected point x coordinate

y (float):

projected point y coordinate

z (float):

projected point z coordinate

d (float):

offset distance, or distance from the point to its projection

edge (tuple[int, int]):

tuple of node identifiers identifying an edge

Return type:

DataFrame

shape Module#

surficial.ops.shape.densify_linestring(line, start=0, step=10)#

Densify a LineString with regularly-spaced stations

Parameters:

  • line (LineString) – shapely LineString

  • start (int | float) – distance along the line from the first vertex; permits stationing to begin at some offset from the first vertex

  • step (int | float) – distance in-between stations along the line

Returns:

densified line with new vertices spaced by the step distance

Return type:

LineString

surficial.ops.shape.filter_contains(points, polygon)#

Return a set of Points contained within a Polygon

Parameters:

  • points (list[Point]) – an array of Point to test.

  • polygon (Polygon) – the polygon to filter on.

Returns:

Points contained within Polygon

Return type:

list[Point]

surficial.ops.shape.linestring_to_stations(line, position=0.0, step=1.0)#

Return a list of regularly spaced stations along a LineString

Parameters:

  • line (LineString) – shapely LineString

  • position (float) – distance along the line from the first vertex; permits stationing to begin at some offset from the first vertex

  • step (int | float) – distance in-between stations along the line

Returns:

stations as list of [m,x,y,z] values

Return type:

list[list[float]]

surficial.ops.shape.linestring_to_vertices(line)#

Return a list of [m,x,y,z] values for a LineString

Parameters:

line (LineString) – shapely LineString

Returns:

list of vertex [m,x,y,z] values

m (float):

measure of distance along the line from the first vertex

x (float):

vertex x coordinate

y (float):

vertex y coordinate

z (float):

vertex z coordinate

Return type:

list[list[float]]

surficial.ops.shape.measure(line, start=0.0)#

Return an array of vertex distances along a LineString

Parameters:

  • line (LineString) – the line on which to project.

  • start (float) – measure at first vertex, zero by default.

Returns:

measures as list of vertex distances along line

Return type:

list[float]

surficial.ops.shape.orient2d(point, projection, from_vert, to_vert)#

Calculate the orientation and offset distance of a point from a line

Parameters:

  • point (Point) – point for which we want to determine orientation left or right of a line

  • projection (Point) – point of projection onto the line

  • from_vert (Point) – from point defining the line

  • to_vert (Point) – to point defining the line

Returns:

point distance offset from the line; negative is left of the line, positive or zero is right of the line

Return type:

float

surficial.ops.shape.project2d(point, line, measure=None)#

Project a Point onto a line

Uses Shapely project(), which sets distance to zero for all negative distances.

Note

The measure parameter does nothing at this time. I had intended to allow interpolation between measures other than distance

Parameters:

  • point (Point) – point at zero distance on line between point and p2.

  • line (LineString) – the line on which to project.

  • measure (None | str) –

Returns:

the projected Point, distance along line, offset from line

Return type:

dict