Routely module reference

Routely

class routely.routely.Route(x, y, z=None)

Bases: object

Create a Route.

Parameters

  • x (array-like) – List or array of x-coordinates of the route.

  • y (array-like) – List or array of y-coordinates of the route.

  • z (dict, optional) – List or array of z data for the route. This does not need to be elevation, but any data corresponding to the route in the x-y plane. Defaults to None.

align_to_origin(origin=(0, 0), align_corner='bottomleft')

Align a corner of Route extents to the origin.

Parameters

  • origin (tuple, optional) – Route origin to align a chosen corner to. Defaults to (0, 0).

  • align_corner (str, optional) – Choose a corner to align. Options: ‘bottomleft’, ‘bottomright’, ‘topleft’, ‘topright’. Defaults to ‘bottomleft’.

Returns

Return a new Route object.

Return type

Route

bbox()

Get the bounding box coordinates of the route.

Returns

(lower-left corner coordinates, upper-right corner coordinates).

Return type

tuple

center()

Get the center point of the route as defined as the mid-point between the max and min extents on each axis.

Returns

(x, y) coordinates of the route center point

Return type

tuple

center_on_origin(new_origin=(0, 0))

Translate the Route to the origin, where the Route center point will be equal to the origin.

Parameters

new_origin (tuple, optional) – New Route origin, which will correspond to the Route’s center point. Defaults to (0, 0).

Returns

Return a new Route object.

Return type

Route

clean_coordinates(duplicates='consecutive')

Clean the coordinate lists by removing duplicate x and y tuples. This is done by finding the index list of unique x and y tuples, and returning the correspondong coordinates for x, y and z data. Two methods for finding duplicates are available: consecutive or any. See args for description.

Parameters

duplicates (str, optional) – Choose the method for dealing with duplicate coordinate tuples. If “consecutive” then remove consecutive duplicates keeping the first. If “any”, remove all duplicate coordinate tuples. Defaults to consecutive.

Returns

Return a new Route object.

Return type

Route

copy()
dataframe()

Returns route data in list form -> [(x, y, z, distance)]. z will be included if specified as an input arguement.

static distance_between_two_points(p1, p2)

Calulate the Euclidean distance between two (x, y) points.

Parameters

  • p1 (tuple) – (x, y) tuple of the first point

  • p2 (tuple) – (x, y) tuple of the second point

Returns

distance between point 1 and point 2

Return type

float

fit_to_box(box_width, box_height, keep_aspect=True)

Scale the Route to fit within a specified bounding box of given width and height. This modifies the x, y and d Route attributes.

Parameters

  • box_width (float) – Desired width.

  • box_height (float) – Desired height.

  • keep_aspect (bool, optional) – If True, the route will be scalled equal in both x and y directions ensuring the new route will fit within the smallest extent. If False, x and y coordinates will be scalled independently such that the modified route will fill the specified width and height. Note: this modifies the aspect ratio of the route. Defaults to True.

Returns

Return a new Route object.

Return type

Route

height()

Get the height of the route (from min y to max y).

Returns

route height.

Return type

float

interpolate(kind='equidistant_steps', num=1)

Interpolate Route x and y coordinate lists given various interpolation stategies.

Available strategies include (specify chosen strategy in ‘kind’ args):

–> ‘equidistant_Steps’: equally spaced steps along the route path from start to end, using np.arange(). Step spacing specified by ‘num’ arg. This is not equidistant steps along x or y axis but distance along the path ie between route waypoints. Note: some variation in steps may occur in order to coincide with existing x and y coordinates.

—> ‘absolute_steps’: the total number of points along the full route as specified by ‘num’ arg. The spacing of the points will be linear along the length of the route using np.linspace.

Note, in all cases, the total route distance may vary from the original but the start and end coordinates will remain the same.

Parameters

  • kind (str, optional) – See docs for options. Defaults to ‘equidistant_steps’.

  • num (int, optional) – step value corresponding to chosen ‘kind’ of interpolation. Defaults to 1.

Returns

Return a new Route object.

Return type

Route

mirror(about_x=False, about_y=False, about_axis=False)

Mirror Route x and y coordinates in the x and y planes as may be specified.

Parameters

  • about_x (bool, optional) – If True, mirror Route horizontally. Defaults to False.

  • about_y (bool, optional) – If True, mirror Route vertically. Defaults to False.

  • about_axis (bool, optional) – If True, mirror Route about the x or y axis. If False, mirror Route about the Route’s center point. Defaults to False.

Returns

Return a new Route object.

Return type

Route

nr_points()

Get the number of coordinate points that comprise the route.

Returns

number of coordinates.

Return type

float

optimise_bbox(box_width, box_height)

Rotate the route to the most efficient use of space given the width and height of a bounding box. This does not scale the route to fill the space but rather find the best aspect ratio of the route that best matches that of the specified box width and height.

The route is rotated 90 degrees clockwise in steps of one degree about the route’s center point.

Parameters

  • box_width (float) – box width.

  • box_height (float) – box height.

Returns

Return a new Route object.

Return type

Route

plot_z(markers=True)

Plot Route z-data (d vs z).

Parameters

markers (bool, optional) – Choose to display markers. Defaults to True.

plotroute(markers=True, equal_aspect=True, equal_lims=True, canvas_style=False)

Plot the route (x vs y).

Parameters

  • markers (bool, optional) – Choose to display markers. Defaults to True.

  • equal_aspect (bool, optional) – Choose to maintain an equal aspect ration in the plot. Defaults to True.

  • equal_lims (bool, optional) – Choose to display equal x and y limits. Defaults to True.

  • canvas_Style (bool, optional) – Create a canvas style plot by removing all chart axes. Defails to False.

rotate(angle_deg)

Rotate Route x and y coordinates clockwise for a given angle in degrees. This does not modify z-axis data.

Parameters

angle_deg (float) – angle of rotation in degrees.

Returns

Return a new Route object.

Return type

Route

size()

Returns the width and height (w, h) of the route along the x and y axes.

Returns

(width, height)

Return type

tuple

smooth(smoothing_factor=None)

Smooth the route using cubic interpolation by varying the smoothing factor from 0 to 1.

The smoothing factor dictates how much smoothing will be applied. The factor reduces the number of route coordinate points relative to the mean change in distance between coordinates. With a reduced number of points, the route is smoothed using Scipy’s cubic interpolation. Consquently, the higher the factor, the fewer coordinate points and the higher level of smoothing. The smoothing factor must be greater than or equal to 0 and less than 1.0.

Parameters

smoothing_factor (float) – level of smoothing to apply between 0 (no smoothing) and 1 (max smoothing). Must be less than 1.

Returns

Return a new Route object.

Return type

Route

width()

Get the width of the route (from min x to max x).

Returns

route width.

Return type

float