linref package

Subpackages

Submodules

linref.route module

Developed by Tariq Shihadah tariq.shihadah@gmail.com

Created: 10/22/2019

Modified: 4/6/2022

class linref.route.MLSRoute(mls, rte_breaks=None, rte_ranges=None, closed='both', **kwargs)[source]

Bases: object

An object class to manage route mile-post information for each vertex of a shapely MultiLineString (MLS). An MLSRoute object instance will be able to convert between the actual linear distance along an MLS (starting from the origin of the MLS and moving downstream along the line, ignoring spaces between individual LineStrings) to the route distance along the MLS based on provided route break information.

Parameters

mlsshapely MultiLineString

The linear geometry being represented by the route object.

rte_breakslist of lists of numerical values

Numerical information representing the route distance values at each vertice of the route MultiLineString. To include breaks in route values, input a separate list for each contiguous group of vertices. Each list should have a number of elements equal to the number of vertices in each LineString contained in the MultiLineString. If rte_breaks is used, rte_ranges should not be input.

rte_rangeslist of tuples of numerical values

Numerical information representing the start and end distance values for each LineString in the MultiLineString. If rte_ranges is used, rte_breaks will be automatically computed and should not be input.

closedstr {‘left’, ‘right’, ‘both’, ‘neither’}, default ‘both’

Whether intervals are closed on the left-side, right-side, both or neither.

bearing(positive=True, invert=False)[source]

Approximate the bearing angle of the route, based on the first and last points in the route’s MLS.

Parameters

positivebool, default True

Whether to enforce a positive range on the computed bearing angle. If True, the bearing angle will fall on the range [0,360). If False, the bearing angle will fall on the range (-180,180].

invertbool, default False

Whether to invert the computed bearing angle, effectively reversing the direction of the route.

property closed
classmethod concatenate(routes, **kwargs)[source]

Combine a list of MLSRoute objects into a single MLSRoute.

NOTE: - MLSRoute objects will be concatenated in the order they are

provided.

  • Behavior of this method under non-trivial conditions has not been tested.

convert(mls_loc=None, rte_loc=None, choose='first')[source]

Convert an mls location to a reference location or vice versa.

convert_to_mls(loc=None, normalized=False, choose='first', snap=None)[source]

Convert a route or normalized reference location to an MLS location.

Parameters

locnumerical

The location along the route in terms of route’s defined location values.

normalizedboolean, default False

Whether to interpret the provided location along the route in terms of proportional distance along the route. If False, the location along the route will be interpreted normally.

choose{‘first’, ‘last’, ‘all’}, default ‘first’

Which range to return information for if multiple ranges are found which intersect with the provided location.

snap{None, ‘near’, ‘left’, ‘right’}, default None

If the input location does not fall within any ranges, snap to the nearest match based on distance, choosing the closest range to the left, right, or either side (‘near’). If None, a value error will be raised when no intersecting ranges are found.

convert_to_rte(loc=None, normalized=False, choose='first', bounded=False)[source]

Convert an MLS or normalized reference location to a route location.

Parameters

locnumerical

The location along the route in terms of the absolute distance along the route’s MultiLineString.

normalizedboolean, default False

Whether to interpret the provided location along the route in terms of proportional distance along the route. If False, the location along the route will be interpreted normally.

choose{‘first’, ‘last’, ‘all’}, default ‘first’

Which range to return information for if multiple ranges are found which intersect with the provided location.

boundedboolean, default False

Whether to raise an error when the location information falls outside the minimum and maximum bounds of the MLS range. If False, negative loc values will be snapped to 0 and loc values greater than mls_length will be snapped to mls_length. If True, a ValueError will be raised for values which fall outside of this range.

copy(deep=False)[source]

Create an exact copy of the MLS route object instance.

cut(beg, end, by_mls=False, normalized=False)[source]

Cut the MLS route at the given begin and end points. This can be done in terms of the route measure information (by_mls=False), in terms of MultiLineString actual cumulative length (by_mls=True), or in terms of proportional distances along the route (normalized=True).

Parameters

begfloat

The location value at which the new route should begin.

endfloat

The location value at which the new route should end.

by_mlsboolean, default False

Whether to interpret the begin and end points in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route locations. If True, interpret as MLS locations. If the normalized parameter is True, this will be superseded and proportional distance will be used.

normalizedboolean, default False

Whether to interpret the begin and end points in terms of proportional distances along the route. If False, the begin and end points will be interpreted according to the by_mls parameter.

Returns

routeMLSRoute

A new MLSRoute object instance with route information and a MultiLineString which has been cut according to the given parameters.

property element_lengths
classmethod from_2d_paths(paths, **kwargs)[source]

Create MLSRoute instance from a list of paths, made up of a list of three-element tuples with X, Y, and range location (i.e., M-value).

classmethod from_lines(lines, begs, ends, **kwargs)[source]

Create an MLSRoute instance from a list of LineStrings or a single MultiLineString and lists of begin and end mile post values with lengths equal to the number of LineStrings within the provided geometry.

Parameters

linesMultiLineString, LineString, or list of either

A collection of shapely linear geometries (LineStrings or MultiLineStrings) to use as the basis for the MLSRoute.

begslist of numeric values or a single numeric value

A list of begin mile post values equal in length to the provided lines. This correlates to a single begin mile post value for each linear geometry in the provided collection. If a single mile post value is provided, begin mile post values for multiple lines will be linearly interpolated.

endslist of numeric values or a single numeric value

A list of end mile post values equal in length to the provided lines. This correlates to a single end mile post value for each line in the provided collection. If a single mile post value is provided, end mile post values for multiple lines will be linearly interpolated.

**kwargs

Keyword arguments to be input in the MLSRoute constructor.

classmethod from_wkt(wkt, **kwargs)[source]

Create an MLSRoute instance from a WKT string for a MULTILINESTRING or LINESTRING with three to four dimensions, with the last dimension being interpreted as M values.

Parameters

wktstr

WKT string representing a MULTILINESTRING or LINESTRING with three to four dimensions, with the last dimension representing the geometry’s M values.

**kwargs

Keyword arguments to be input in the MLSRoute constructor.

interpolate(loc, by_mls=False, normalized=False, snap=None, **kwargs)[source]

Return a point at the specified location along the route. This can be done using a normalized proportional distance along the route, or the distance along the route in terms of route location or MultiLineString absolute length.

Parameters

locnumerical

The distance along the route at which to create the point. Can be proportional distance, route location, or MultiLineString distance.

by_mlsboolean, default False

Whether to interpret the provided location along the route in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route locations. If True, interpret as MLS location. If the normalized parameter is True, this will be superseded and proportional distance will be used.

normalizedboolean, default False

Whether to interpret the provided location along the route in terms of proportional distance along the route. If False, the location along the route will be interpreted according to the by_mls parameter.

snap{None, ‘near’, ‘left’, ‘right’}, default None

If the input location does not fall within any ranges, snap to the nearest match based on distance, choosing the closest range to the left, right, or either side (‘near’). If None, a value error will be raised when no intersecting ranges are found.

locate_mls(loc, normalized=False, choose='first', bounded=False)[source]

Get the range index and the proportional distance along that range of the input MLS location.

Parameters

… bounded : boolean, default False

Whether to raise an error when the location information falls outside the minimum and maximum bounds of the MLS range. If False, negative loc values will be snapped to 0 and loc values greater than mls_length will be snapped to mls_length. If True, a ValueError will be raised for values which fall outside of this range.

locate_rte(loc, normalized=False, choose='first', snap=None)[source]

Get the range index and the proportional distance along that range of the input route location.

Parameters

snap{None, ‘near’, ‘left’, ‘right’}, default None

If the input location does not fall within any ranges, snap to the nearest match based on distance, choosing the closest range to the left, right, or either side (‘near’). If None, a value error will be raised when no intersecting ranges are found.

property mls
property mls_breaks
property mls_length
property mls_ranges
normalize(loc, by_mls=False, snap=None, **kwargs)[source]

Normalize a location as an actual route location or the absolute distance along the route’s MultiLineString.

Parameters

locnumerical

The distance along the route which will be normalized. Can be route location or MultiLineString distance.

by_mlsboolean, default False

Whether to interpret the provided location along the route in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route location. If True, interpret as MLS location.

snap{None, ‘near’, ‘left’, ‘right’}, default None

If the input location does not fall within any ranges, snap to the nearest match based on distance, choosing the closest range to the left, right, or either side (‘near’). If None, a value error will be raised when no intersecting ranges are found.

property num_lines
project(obj, by_mls=False, normalized=False)[source]

Find the location along the route to a point nearest the input object. This can be done using a normalized proportional distance along the route, or the distance along the route in terms of route location or MultiLineString absolute length.

Parameters

objshapely geometry object

A shapely geometry object to be projected along the route.

by_mlsboolean, default False

Whether to return the projected distance along the route in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route locations. If True, interpret as MLS location. If the normalized parameter is True, this will be superseded and proportional distance will be used.

normalizedboolean, default False

Whether to return the projected distance in terms of proportional distance along the route. If False, the distance along the route will be returned according to the by_mls parameter.

property rte_breaks
property rte_length
property rte_ranges
segment(cuts, by_mls=False, normalized=False, **kwargs)[source]

Cut the MLS Route into segments based on the given cut points.

Parameters

cutsarray-like

Array-like of numeric values representing the locations at which to cut the route, either in terms of MultiLineString distance or defined route locations.

by_mlsboolean, default False

Whether to interpret the provided location along the route in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route locations. If True, interpret as MLS location. If the normalized parameter is True, this will be superseded and proportional distance will be used.

normalizedboolean, default False

Whether to interpret the provided location along the route in terms of proportional distance along the route. If False, the location along the route will be interpreted according to the by_mls parameter.

Returns

segmentslist of MLSRoutes

A list of new MLSRoute object instances, each with route information and a MultiLineString which has been cut according to the given parameters.

snap(loc, by_mls=False, normalized=False)[source]

Snap a provided location value to the bounds of the route based on the provided parameters. If the location falls within the bounds of the route, the same value will be returned.

Parameters

locscalar

Location value to snap to the route bounds.

by_mlsboolean, default False

Whether to interpret the provided location along the route in terms of the actual cumulative length of the route’s MultiLineString. If False, interpret as route location. If True, interpret as MLS location.

normalizedboolean, default False

Whether to interpret the provided location along the route in terms of proportional distance along the route. If False, the location along the route will be interpreted according to the by_mls parameter.

to_wkt(decimals=None)[source]

Produce a WKT string representing the object with the underlying MultiLineString appended with M values represented in the rte_breaks property.

property vertices
property wkt
linref.route.combine_mpgs(objs, cls=None)[source]

Combine multiple multipart geometries into a single multipart geometry of geometry collection.

Module contents