tracktable.core.geomath module¶
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.
almost_equal
(a, b, relative_tolerance=1e-06)[source]¶ Check two numbers for equality within a tolerance
-
tracktable.core.geomath.
altitude
(thing)[source]¶ 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
point – TrajectoryPoint or (lon, lat, altitude) tuple
- Returns
Altitude as float
- Raises
AttributeError – if attempt at access fails
-
tracktable.core.geomath.
bearing
(origin, destination)[source]¶ Compute angular bearing between two points
Source: http://gagravarr.livejournal.com/109998.html with modifications.
- Parameters
origin (BasePoint or TrajectoryPoint) – start point
destination (BasePoint or TrajectoryPoint) – end point
- Returns
Bearing from origin to destination.
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.
-
tracktable.core.geomath.
compute_bounding_box
(point_sequence, buffer=())[source]¶ 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.
- Parameters
point_sequence – Iterable of points
buffer – tuple of ratios to extend the bounding box. This defaults to an empty tuple which means no padding is added.
- Returns
Bounding box with min_corner, max_corner attributes
- Domain:
Each domain returns a separate bounding box type.
-
tracktable.core.geomath.
convex_hull_area
(trajectory)[source]¶ 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 whose hull you want to measure
- Returns
Area of the trajectory’s convex hull
-
tracktable.core.geomath.
convex_hull_aspect_ratio
(trajectory)[source]¶ 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 whose shape you want to measure
- Returns
Aspect ratio of the trajectory’s convex hull
-
tracktable.core.geomath.
convex_hull_centroid
(trajectory)[source]¶ 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.
-
tracktable.core.geomath.
convex_hull_perimeter
(trajectory)[source]¶ 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 whose hull you want to measure
- Returns
Perimeter of the trajectory’s convex hull
-
tracktable.core.geomath.
current_length
(point)[source]¶ Return the current length of a path in domain-dependent units
This is the length up to the given point in a trajectory.
- Parameters
Point (TrajectoryPoint) – Point to which we want the length
- Returns
Length in domain-dependent units
- Domain:
Terrestrial: distance in km Cartesian2D: distance in units Cartesian3D: distance in units
-
tracktable.core.geomath.
distance
(hither, yon)[source]¶ 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.
- Parameters
hither (BasePoint) – point 1
yon (BasePoint) – point 2
- Returns
Distance between hither and yon
- Domain:
Terrestrial domain returns distance in km. Cartesian domains return distance in native units.
-
tracktable.core.geomath.
end_to_end_distance
(trajectory)[source]¶ 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.
- Parameters
trajectory (Trajectory) – Path whose length we want
- Returns
Length in domain-dependent units
- Domain:
Terrestrial: distance in km Cartesian2D: distance in units Cartesian3D: distance in units
-
tracktable.core.geomath.
extrapolate
(start, end, t)[source]¶ 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)[source]¶ 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 – Sequence of points for which you want a mean
- Returns
Single point of the same type that came in
-
tracktable.core.geomath.
geometric_median
(points)[source]¶ Compute L1 multivariate median of points
The multivariate median generalizes the standard 1D median to two or more dimensions.
- Parameters
points – Iterable of points for which you want a median
- Returns
Single point of the same type that came in
-
tracktable.core.geomath.
interpolate
(start, end, t)[source]¶ 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)[source]¶ 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 – Geometry object
thing2 – Geometry object
- Returns
True or False
-
tracktable.core.geomath.
kms_to_lat
(kms: float, latitude: float between -90 and 90) -> float (in latitude)[source]¶ Compute the 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)[source]¶ 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
-
tracktable.core.geomath.
latitude
(thing)[source]¶ 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
point – TrajectoryPoint or (lon, lat) tuple
- 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)[source]¶ 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.
-
tracktable.core.geomath.
latitude_or_y
(thing)[source]¶ Return the latitude or Y-coordinate from a point or tuple
- Parameters
point – TrajectoryPoint or (lon, lat) tuple or (x, y) point
- Returns
Latitude/Y as float
- Raises
AttributeError – if attempt at access fails
-
tracktable.core.geomath.
length
(trajectory)[source]¶ Return the length of a path in domain-dependent units
This is the total length of all segments in the trajectory.
- Parameters
trajectory (Trajectory) – Path whose length we want
- Returns
Length in domain-dependent units
- Domain:
Terrestrial: distance in km Cartesian2D: distance in units Cartesian3D: distance in units
-
tracktable.core.geomath.
longitude
(thing)[source]¶ 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
point – TrajectoryPoint or (lon, lat) tuple
- 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)[source]¶ 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.
-
tracktable.core.geomath.
longitude_or_x
(thing)[source]¶ Return the longitude or X-coordinate from a point or tuple
- Parameters
point – TrajectoryPoint or (lon, lat) tuple or (x, y) point
- Returns
Longitude/X as float
- Raises
AttributeError – if attempt at access fails
-
tracktable.core.geomath.
point_at_fraction
(trajectory, time_fraction)[source]¶ 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.
WARNING: This function is deprecated. Use point_at_time_fraction instead.
- 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 whose shape you want to measure
- Returns
Radius of gyration of the trajectory
-
tracktable.core.geomath.
recompute_speed
(trajectory, target_attribute_name='speed')[source]¶ 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 – Any Tracktable trajectory
target_attribute_name – Speed will be stored in this property at each point. Defaults to ‘speed’.
The trajectory will be modified in place instead of returning a new copy.
-
tracktable.core.geomath.
signed_turn_angle
(a, b, c)[source]¶ 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.
- Parameters
a (BasePoint) – first point
b (BasePoint) – second point
c (BasePoint) – third point
- Returns
Signed angle in domain-dependent units
- Domain:
Terrestrial: angle in degrees, positive angles are clockwise Cartesian2D: angle in radians, positive angles are counterclockwise Cartesian3D: not defined
-
tracktable.core.geomath.
simplify
(trajectory, tolerance)[source]¶ 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 to simplify
tolerance – Error tolerance measured in the trajectory’s native distance
- Returns
Simplified version of trajectory
-
tracktable.core.geomath.
speed_between
(point1, point2)[source]¶ Return speed in km/hr between two timestamped points.
- Parameters
point1 (TrajectoryPoint) – Start point
point2 (TrajectoryPoint) – End point
- Returns
Speed (as a float) measured in domain-specific units
- Domain Info:
Terrestrial: Speed is in km/hr Cartesian2D: Speed is in units/sec Cartesian3D: Speed is in units/sec
-
tracktable.core.geomath.
subset_during_interval
(trajectory, start_time, end_time)[source]¶ 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)[source]¶ 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)[source]¶ 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.
- Parameters
a (BasePoint) – first point
b (BasePoint) – second point
c (BasePoint) – third point
- Returns
Angle in domain-dependent units
- Domain:
Terrestrial: angle in degrees between 0 and 180 Cartesian2D: angle in radians between 0 and pi Cartesian3D: angle in radians between 0 and pi
-
tracktable.core.geomath.
xcoord
(thing)[source]¶ 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
point – 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)[source]¶ 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
point – Object with an ‘y’ property or tuple of numbers
- Returns
Number corresponding to y coordinate
- Raises
AttributeError if attempt at access fails –