tracktable.core.geomath module

Module contents

This file contains useful math functions. Some of them will be related to geography such as ‘find the distance between these two points on the globe’.

tracktable.core.geomath.ECEF(point, ratio=1.0, altitudeString='')

Convert point to ECEF. Altitude is in km.

Converts Terrestrial points to cartesian coordinates.

Parameters

• points – A point to convert

• ratio – conversion ratio from km to result

• altitudeString – String label of altitude property

Returns

Single Cartesian 3D point

tracktable.core.geomath.ECEF_from_feet(point, altitudeString='altitude')

Convert point to ECEF using altitude in feet

Converts Terrestrial points to cartesian coordinates.

Parameters

• points – A point to convert

• altitudeString – String label of altitude property

Returns

Single Cartesian 3D point

tracktable.core.geomath.ECEF_from_meters(point, altitudeString='altitude')

Convert point to ECEF using altitude in meters

Converts Terrestrial points to cartesian coordinates.

Parameters

• points – A point to convert

• altitudeString – String label of altitude property

Returns

Single Cartesian 3D point

tracktable.core.geomath.almost_equal(a, b, relative_tolerance=1e-06)

Check two numbers for equality within a tolerance

Parameters

• a (float) – First number

• b (float) – Second number

Keyword Arguments

relative_tolerance (float) – Numbers must be close to within this fraction of their average to be considered equal (Default: 1e-6)

Returns

True/false depending on whether or not they’re equal-ish

tracktable.core.geomath.altitude(thing)

Return the altitude from a point or tuple

It is often convenient to specify a point as a (lon, lat, altitude) tuple instead of a full-fledged TrajectoryPoint. By using this function to look up altitude we can cope gracefully with both.

Parameters

thing (TrajectoryPoint or (lon, lat, altitude) tuple) – Object with an ‘altitude’ property or tuple of numbers

Returns

Altitude as float

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.bearing(origin, destination)

Compute angular bearing between two points

Source: http://gagravarr.livejournal.com/109998.html with modifications.

Domain Information:

Terrestrial: Returned in degrees. 0 is due north, 90 is due east.

Cartesian2D: Returned in radians. 0 is positive X, pi/2 is positive Y.

Cartesian3D: Not defined.

Parameters

• origin (BasePoint or TrajectoryPoint) – start point

• destination (BasePoint or TrajectoryPoint) – end point

Returns

Bearing from origin to destination.

tracktable.core.geomath.compute_bounding_box(point_sequence, buffer=())

Compute a bounding box for a sequence of points.

This function will construct a domain-specific bounding box over an arbitrary sequence of points. Those points must all have the same type. It can also produce a buffer of space that extends the bounding box some percentage beyond the min and max points. The implementation is fairly naive and can cause issues if the values extend past max values for the point/map type.

Domain Information:

Each domain returns a separate bounding box type.

Parameters

point_sequence (BasePoint or TrajectoryPoint iterable) – Iterable of points

Keyword Arguments

buffer (tuple) – Ratios to extend the bounding box. This defaults to an empty tuple which means no padding is added. (Default: ())

Returns

Bounding box with min_corner, max_corner attributes

tracktable.core.geomath.convex_hull_area(trajectory)

Compute the area of the convex hull of a trajectory

Area will be returned in the native area units of the domain. This is square kilometers for the terrestrial domain and untyped squared units for Cartesian.

Parameters

trajectory (Trajectory) – Trajectory whose hull you want to measure

Returns

Area of the trajectory’s convex hull

tracktable.core.geomath.convex_hull_aspect_ratio(trajectory)

Compute the aspect ratio of the convex hull of a trajectory

Aspect ratio is a dimensionless number. It refers to the ratio of the shortest axis of the polygon over the longest.

Note that we compute an approximation using the vertices of the convex hull. This will get better in a future release.

Parameters

trajectory (Trajectory) – Trajectory whose shape you want to measure

Returns

Aspect ratio of the trajectory’s convex hull

tracktable.core.geomath.convex_hull_centroid(trajectory)

Compute the centroid of the convex hull of a trajectory

Centroid will be returned in the native units of the domain. This is: latitude, longitude (altitude) for the terrestrial domain; and x, y (z) for Cartesian.

Parameters

trajectory (Trajectory) – Trajectory whose shape you want to measure

Returns

Centroid ratio of the trajectory’s convex hull

tracktable.core.geomath.convex_hull_perimeter(trajectory)

Compute the perimeter of the convex hull of a trajectory

Perimeter length will be returned in the native distance units of the domain. This is kilometers for the terrestrial domain and untyped units for Cartesian.

Parameters

trajectory (Trajectory) – Trajectory whose hull you want to measure

Returns

Perimeter of the trajectory’s convex hull

tracktable.core.geomath.current_length(point)

Return the current length of a path in domain-dependent units

This is the length up to the given point in a trajectory.

Domain Information:

Terrestrial: distance in km

Cartesian2D: distance in units

Cartesian3D: distance in units

Parameters

Point (TrajectoryPoint) – Point to which we want the length

Returns

Length in domain-dependent units

tracktable.core.geomath.current_length_fraction(point)

Return the fraction length of a point in a trajectory

This is the fraction length of all segments in the trajectory up to the given point.

Parameters

point (Point) – Point whose current length fraction we want

Returns

Fraction of total length up to this point.

tracktable.core.geomath.current_time_fraction(point)

Return the fraction duration of a point in trajectory

This is the fraction duration of all segments in the trajectory up to the given point.

Parameters

point (Point) – Point whose current duration fraction we want

Returns

Fraction of total duration up to this point.

tracktable.core.geomath.distance(hither, yon)

Return the distance between two points

This function will compute the distance between two points in domain-specific units.

The points being measured must be from the same domain.

Domain Information:

Terrestrial domain returns distance in km.

Cartesian domains return distance in native units.

Parameters

• hither (BasePoint) – point 1

• yon (BasePoint) – point 2

Returns

Distance between hither and yon

tracktable.core.geomath.end_to_end_distance(trajectory)

Return the distance between a path’s endpoints

This is just the crow-flight distance between start and end points rather than the total distance traveled.

Domain Information:

Terrestrial: distance in km

Cartesian2D: distance in units

Cartesian3D: distance in units

Parameters

trajectory (Trajectory) – Path whose length we want

Returns

Length in domain-dependent units

tracktable.core.geomath.extrapolate(start, end, t)

Extrapolate between two points

This function will extrapolate linearly between two points. It is aware of the underlying coordinate system: interpolation on the globe will be done along great circles and interpolation in Cartesian space will be done along a straight line.

The points being measured must be from the same domain.

Parameters

• start (BasePoint or TrajectoryPoint) – point 1

• end (BasePoint or TrajectoryPoint) – point 2

• t (float) – interpolant

Returns

New point interpolated between start and end

tracktable.core.geomath.geometric_mean(points)

Compute mean of input points

This is the regular mean: just the component-wise average of the coordinates.

Note

This does not yet do the right thing with terrestrial points. It should normalize their coordinates to make sure they do not fall across the limb of the map before taking the average.

Parameters

points (BasePoint or TrajectoryPoint iterable) – Points for which you want a mean

Returns

Single point of the same type that came in

tracktable.core.geomath.geometric_median(points)

Compute L1 multivariate median of points

The multivariate median generalizes the standard 1D median to two or more dimensions.

Parameters

points (BasePoint or TrajectoryPoint iterable) – Points for which you want a median

Returns

Single point of the same type that came in

tracktable.core.geomath.interpolate(start, end, t)

Interpolate between two points

This function will interpolate linearly between two points. It is aware of the underlying coordinate system: interpolation on the globe will be done along great circles and interpolation in Cartesian space will be done along a straight line.

The points being measured must be from the same domain.

Parameters

• start (BasePoint or TrajectoryPoint) – point 1

• end (BasePoint or TrajectoryPoint) – point 2

• t (float in [0, 1]) – interpolant

Returns

New point interpolated between start and end

tracktable.core.geomath.intersects(thing1, thing2)

Check to see whether two geometries intersect

The geometries in question must be from the same domain. They can be points, trajectories, linestrings or bounding boxes.

Parameters

• thing1 (points, trajectories, linestrings or bounding boxes) – Geometry object used for intersection calculation

• thing2 (points, trajectories, linestrings or bounding boxes) – Geometry object used for intersection calculation

Returns

True or False

tracktable.core.geomath.km_to_radians(distance)

Convert distance from km to radians given that we are working on the surface of the earth

Parameters

distance – distance in km

Returns

distance in radians

tracktable.core.geomath.kms_to_lat(kms: float, latitude: float between -90 and 90) -> float (in latitude)

Compute the degrees-latitude conversion for a distance in km, at a given latitude.

Parameters

• kms (float) – Kilometers

• latitude (float) – Latitude

Returns

degrees-latitude conversion for a distance in km, at a given latitude

tracktable.core.geomath.kms_to_lon(kms: float, latitude: float between -90 and 90) -> float (in longitude)

Compute the degrees-longitude conversion for a distance in km, at a given latitude. This is because as you move towards the poles, the km/longitude ratio decreases

Parameters

• kms (float) – Kilometers

• latitude (float) – Latitude

Returns

degrees-longitude conversion for a distance in km, at a given latitude

tracktable.core.geomath.latitude(thing)

Return the latitude from a point or tuple

It is often convenient to specify a point as a (lon, lat) tuple instead of a fullfledged TrajectoryPoint. By using this function to look up latitude we can cope gracefully with both.

Parameters

thing (TrajectoryPoint or (lon, lat) tuple) – Object with an ‘latitude’ property or tuple of numbers

Returns

Latitude as float

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.latitude_degree_size(latitude: float between -90 and 90) -> float (in km)

Compute the distance between adjacent degrees of latitude centered on a given parallel. This measurement is 111.694km at the equator and 110.574km at the poles. This is a small enough variation that we’ll just use linear interpolation.

Parameters

latitude (float) – Latitude

Returns

The distance between adjacent degrees of latitude

tracktable.core.geomath.latitude_or_y(thing)

Return the latitude or Y-coordinate from a point or tuple

Parameters

thing (TrajectoryPoint, (lon, lat) tuple or (x, y) point) – Object with an ‘latitude’ or ‘y’ property or tuple of numbers

Returns

Latitude/Y as float

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.length(trajectory)

Return the length of a path in domain-dependent units

This is the total length of all segments in the trajectory.

Domain Information:

Terrestrial: distance in km

Cartesian2D: distance in units

Cartesian3D: distance in units

Parameters

trajectory (Trajectory) – Path whose length we want

Returns

Length in domain-dependent units

tracktable.core.geomath.longitude(thing)

Return the longitude from a point or tuple

It is often convenient to specify a point as a (lon, lat) tuple instead of a fullfledged TrajectoryPoint. By using this function to look up longitude we can cope gracefully with both.

Parameters

thing (TrajectoryPoint or (lon, lat) tuple) – Object with an ‘longitude’ property or tuple of numbers

Returns

Longitude as float

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.longitude_degree_size(latitude: float between -90 and 90) -> float (in km)

Compute the distance between adjacent degrees of longitude at a given latitude. This varies from 111.32km at the equator to 0 at the poles and decreases as the cosine of increasing latitude.

Parameters

latitude (float) – Latitude

Returns

The distance between adjacent degrees of longitude

tracktable.core.geomath.longitude_or_x(thing)

Return the longitude or X-coordinate from a point or tuple

Parameters

thing (TrajectoryPoint, (lon, lat) tuple or (x, y) point) – Object with an ‘longitude’ or ‘x’ property or tuple of numbers

Returns

Longitude/X as float

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.point_at_fraction(trajectory, time_fraction)

WARNING: This function is deprecated. Use point_at_time_fraction instead.

Return a point from a trajectory at a specific fraction of its duration

This function will estimate a point at a trajectory at some specific fraction of its total duration. If the supplied fraction does not fall exactly on a vertex of the trajectory we will interpolate between the nearest two points.

Fractions before the beginning or after the end of the trajectory will return the start and end points, respectively.

Parameters

• trajectory (Trajectory) – Path to sample

• time_fraction (float) – Value between 0 and 1. 0 is the beginning and 1 is the end.

Returns

TrajectoryPoint at specified fraction

tracktable.core.geomath.point_at_length_fraction(trajectory, length_fraction)

Return a point from a trajectory at a specific fraction of its distance

This function will estimate a point at a trajectory at some specific fraction of its total travel distance. If the supplied fraction does not fall exactly on a vertex of the trajectory we will interpolate between the nearest two points.

Fractions before the beginning or after the end of the trajectory will return the start and end points, respectively.

Parameters

• trajectory (Trajectory) – Path to sample

• length_fraction (float) – Value between 0 and 1. 0 is the beginning and 1 is the end.

Returns

TrajectoryPoint at specified fraction

tracktable.core.geomath.point_at_time(trajectory, when)

Return a point from a trajectory at a specific time

This function will estimate a point at a trajectory at some specific time. If the supplied timestamp does not fall exactly on a vertex of the trajectory we will interpolate between the nearest two points.

Times before the beginning or after the end of the trajectory will return the start and end points, respectively.

Parameters

• trajectory (Trajectory) – Path to sample

• when (datetime) – Timestamp for which we want the point

Returns

TrajectoryPoint at specified time

tracktable.core.geomath.point_at_time_fraction(trajectory, time_fraction)

Return a point from a trajectory at a specific fraction of its duration

This function will estimate a point at a trajectory at some specific fraction of its total duration. If the supplied fraction does not fall exactly on a vertex of the trajectory we will interpolate between the nearest two points.

Fractions before the beginning or after the end of the trajectory will return the start and end points, respectively.

Parameters

• trajectory (Trajectory) – Path to sample

• time_fraction (float) – Value between 0 and 1. 0 is the beginning and 1 is the end.

Returns

TrajectoryPoint at specified fraction

tracktable.core.geomath.radius_of_gyration(trajectory)

Compute the radius of gyration of a trajectory

Radius of gyration is an indication of the compactness of a trajectory. Technically the result is in radians from the center of mass of the trajectory. The units of the radius is dependent on the type of trajectory being measured. Terrestrial will return km, while Cartesian2D returns radians.

Parameters

trajectory (Trajectory) – Trajectory whose shape you want to measure

Returns

Radius of gyration of the trajectory

tracktable.core.geomath.recompute_speed(trajectory, target_attribute_name='speed')

Use points and timestamps to compute speed

The speed data in trajectories is often suspect. This method goes through and recomputes it based on the distance between neighboring points and the time elapsed between those points.

The speed at point N is computed using the distance and time since point N-1. The speed at point 0 is copied from point 1.

Parameters

trajectory (Trajectory) – Any Tracktable trajectory

Keyword Arguments

target_attribute_name (str) – Speed will be stored in this property at each point. Defaults to ‘speed’. (Default: “speed”)

The trajectory will be modified in place instead of returning a new copy.

tracktable.core.geomath.sanity_check_distance_less_than(max_distance)

Check and verify distance is less than max allowable distance

Parameters

max_distance (float) – Max allowable distance between points

Returns

True/False indicating if distance between two points is less than max distance

tracktable.core.geomath.signed_turn_angle(a, b, c)

Return signed turn angle between (a, b) and (b, c).

The magnitude of the angle tells you how far you turned. The sign of the angle tells you whether you turned right or left. Which one depends on the domain.

Domain Information:

Terrestrial: angle in degrees, positive angles are clockwise

Cartesian2D: angle in radians, positive angles are counterclockwise

Cartesian3D: not defined

Parameters

• a (BasePoint) – first point

• b (BasePoint) – second point

• c (BasePoint) – third point

Returns

Signed angle in domain-dependent units

tracktable.core.geomath.simplify(trajectory, tolerance)

Geometric simplification for trajectory

This function reduces the number of points in a trajectory without introducing positional error greater than the supplied tolerance. Under the hood it uses Douglas-Peucker simplification.

Note

The points in the output are copies of the points in the input. Changing the input after a call to simplify() will have no effect on previous results.

Note

This function only cares about geometric error in the trajectory. It does not account for error in the attributes attached to each point.

Parameters

• trajectory (Trajectory) – Trajectory to simplify

• tolerance (float) – Error tolerance measured in the trajectory’s native distance

Returns

Simplified version of trajectory

tracktable.core.geomath.speed_between(point1, point2)

Return speed in km/hr between two timestamped points.

Domain Information:

Terrestrial: Speed is in km/hr

Cartesian2D: Speed is in units/sec

Cartesian3D: Speed is in units/sec

Parameters

• point1 (TrajectoryPoint) – Start point

• point2 (TrajectoryPoint) – End point

Returns

Speed measured in domain-specific units as float

tracktable.core.geomath.subset_during_interval(trajectory, start_time, end_time)

Return a subset of a trajectory between two times

This function will extract some (possibly empty) subset of a trajectory between two timestamps.

If the time interval is entirely outside the trajectory, the result will be an empty trajectory. Otherwise we will use point_at_time to find the two endpoints and build a new trajectory from the endpoints and all trajectory points between them.

Parameters

• trajectory (Trajectory) – Path to sample

• start_time (datetime) – Timestamp for beginning of subset

• end_time (datetime) – Timestamp for end of subset

Returns

Trajectory for desired interval

tracktable.core.geomath.time_at_fraction(trajectory, fraction)

Return a time from a trajectory at a specific fraction of its duration

This function will estimate a time in a trajectory at some specific fraction of its total travel duration. If the supplied fraction does not fall exactly on a vertex of the trajectory we will interpolate between the nearest two points.

Fractions before the beginning or after the end of the trajectory will return the start and end times, respectively.

Parameters

• trajectory (Trajectory) – Path to sample

• fraction (float) – Value between 0 and 1. 0 is the beginning and 1 is the end.

Returns

Timestamp (datetime) at specified fraction

tracktable.core.geomath.unsigned_turn_angle(a, b, c)

Return unsigned turn angle between (a, b) and (b, c).

The magnitude of the angle tells you how far you turned. This function will not tell you whether you turned right or left - for that you need signed_turn_angle.

Domain Information:

Terrestrial: angle in degrees between 0 and 180

Cartesian2D: angle in radians between 0 and pi

Cartesian3D: angle in radians between 0 and pi

Parameters

• a (BasePoint) – first point

• b (BasePoint) – second point

• c (BasePoint) – third point

Returns

Angle in domain-dependent units

tracktable.core.geomath.xcoord(thing)

Return what we think is the X-coordinate for an object.

If the supplied thing has a property named ‘x’ then we return that. Otherwise we try to return its first element.

Parameters

thing (Tracktable object) – Object with an ‘x’ property or tuple of numbers

Returns

Number corresponding to x coordinate

Raises

AttributeError – if attempt at access fails

tracktable.core.geomath.ycoord(thing)

Return what we think is the Y-coordinate for an object.

If the supplied thing has a property named ‘y’ then we return that. Otherwise we try to return its second element.

Parameters

thing (Tracktable object) – Object with an ‘y’ property or tuple of numbers

Returns

Number corresponding to y coordinate

Raises

AttributeError – if attempt at access fails