tracktable.core module¶
Module contents¶
TrailMix Trajectory Library - Core
Basic types (point, trajectory) live in this module. They are in turn imported from the small C extension libraries.
-
tracktable.core.
data_directory
()[source]¶ Return path to Tracktable example data files
We bundle a few example data files inside Tracktable. This function will give you the path to those. Use it as follows:
import os.path from tracktable.core import data_directory
- with open(os.path.join(data_directory(), “SampleASDI.csv”)) as asdi_file:
# Do your own stuff with the data
- Parameters
arguments. (No) –
- Returns
Path to Tracktable example data files.
-
class
tracktable.core.
TrajectoryPoint
(longitude=0, latitude=0, altitude=0)¶ Bases:
object
This is the core geographic point class for Tracktable. NOTE: The ‘Bases’ is not accurate but will do for now.
This is the core geographic point class for Tracktable. You will not instantiate this yourself: instead, use tracktable.domain.<domain>.TrajectoryPoint.
TrajectoryPoint specifies a point on the surface of a sphere that is annotated with an object ID, coordinates, timestamp, and possibly other attributes (commonly altitude, heading and speed). Any or all of these may be left uninitialized depending on the user’s actions although a point without coordinates is not especially useful.
We require that the coordinates be in degrees of longitude and latitude. The units on all numeric properties are user-defined, although altitude will usually be in either feet or meters (depending on your data source) and heading will usually be in degrees clockwise from due north.
Note
TrajectoryPoint is implemented in C++ and exposed to Python via the Boost.Python module. I will include a link to the C++ class definition as soon as I figure out how to do so within Sphinx, Breathe and Napoleon.
-
coordinates
¶ array of floats
(longitude, latitude), where longitude is between -180 and 180 and latitude is between -90 and 90
-
object_id
¶ string
Object ID of entity referred to by this point
-
timestamp
¶ datetime
Timestamp corresponding to this point
-
properties
¶ dict
User-defined properties. Names are strings, values are numbers, timestamps and strings. All properties other than object ID, coordinates, and timestamp will be stored here.
-
TrajectoryPoint.
has_property
(property_name)¶ Check to see whether an entry is present in the property map
- Parameters
property_name (string) – Name of property to look for
- Returns
True or false depending on whether property was found
-
-
class
tracktable.core.
Trajectory
¶ Bases:
object
Ordered sequence of timestamped points.
This class is the heart of most of what Tracktable does. It implements an ordered sequence of TrajectoryPoint objects, each of which has an ID, coordinates and a timestamp. Those compose a trajectory. All points in a single Trajectory should have the same object_id.
Note
The Trajectory class is implemented in C++ and exposed to Python via the Boost.Python module. We use the vector indexing suite from Boost to make a trajectory act like a list of points.
-
object_id
¶ string
ID of object described in this trajectory. This will be the string “(empty)” if the trajectory does not contain any points.
-
start_time
¶ datetime
Timestamp of the first point in the trajectory. This will be invalid if the trajectory contains no points.
-
end_time
¶ datetime
Timestamp of the last point in the trajectory. This will be invalid if the trajectory contains no points.
-
Trajectory.
subset_in_window
(start_time, end_time)¶ Compute the subset of a trajectory between two timestamps.
We often want to clip a trajectory to just the part that fits within a certain window of time. This method interpolates new start and end positions that fall exactly at start_time and end_time and includes between them all of the points in the trajectory that occur within the specified interval. If the trajectory does not intersect the interval at all then the return value will be an empty Trajectory.
- Parameters
start_time (datetime) – Beginning of time window
end_time (datetime) – End of time window
- Returns
New Trajectory with endpoints at start_time and end_time
-
Trajectory.
point_at_time
(when)¶ Find the position on a trajectory at a specified time.
If the specified time falls between points on the trajectory then we will interpolate as needed. If you ask for a point before the trajectory begins or after the trajectory ends you will get the first or last point of the trajectory respectively.
- Parameters
when (datetime) – Time at which to evaluate trajectory
- Returns
TrajectoryPoint at specified time
-
Trajectory.
recompute_speed
()¶ Compute speeds at each point of a trajectory.
Sometimes the speed measurements that come with a data set are noisy or outright wrong. Sometimes they’re missing. This method is for those situations. When you call it, it will use the position and timestamp data to compute a speed at each point in the trajectory. This value can be accessed with
my_speed = my_trajectory[i].properties['speed']
.
-
Trajectory.
recompute_heading
()¶ Compute headings at each point of a trajectory.
The heading at each point of a trajectory is the direction to the next point. The heading at the very last point is the same as the heading at the penultimate point. This value can be accessed with
my_heading = my_trajectory[i].properties['heading']
.
-
Trajectory.
intersects_box
(southwest_corner, northeast_corner)¶ Test to see whether a trajectory intersects a rectangle in longitude/latitude space.
A trajectory intersects a box if any of its coordinates falls within the box.
- Parameters
southwest_corner (TrajectoryPoint or (longitude, latitude) tuple) – Southwest corner of box of interest
northwest_corner (TrajectoryPoint or (longitude, latitude) tuple) – Northwest corner of box of interest
- Returns
True or False
-
-
class
tracktable.core.
Timestamp
¶ Convenience methods for working with timestamps.
Recall that a Timestamp is just a timezone-aware
datetime.datetime
object. That gives us all of the standard Python date/time functions to use for manipulating them. As a result we only need convenience functions to take care of the awkward parts: turning strings into timestamps, timestamps into strings, and imbuing a naivedatetime
object with a time zone.-
static
Timestamp.
beginning_of_time
()¶ Return a timestamp equal to January 1, 1400. No valid timestamp should ever be this old.
- Returns
Timestamp object set to the first day of 1400
-
static
Timestamp.
from_struct_time
(mytime)¶ Construct a datetime from a time.struct_time object.
- Parameters
mytime (
time.struct_time
) – Source time- Returns
An aware datetime object imbued with
tracktable.core.timestamp.DEFAULT_TIMEZONE
-
static
Timestamp.
from_dict
(mydict)¶ Construct a datetime from a dict with named elements.
- Parameters
mydict (
dict
) – Dict with zero or more of ‘hour’, ‘minute’, ‘second’, ‘year’, ‘month’, ‘day’, and ‘utc_offset’ entries. Missing entries will be set to their minimum legal values.- Returns
An aware datetime object imbued with
tracktable.core.DEFAULT_TIMEZONE
unless a ‘utc_offset’ value is specified, in which case the specified time zone will be used instead.
-
static
Timestamp.
from_datetime
(mytime)¶ Convert a
datetime
into an aware timestamp.- Parameters
mytime (
datetime.datetime
) –datetime
object to convert- Returns
datetime
that will definitely have a time zone attached. If the input already has a time zone then it will be returned without modification. If not, a new timestamp will be created with the supplied date/time and the default time zone.
-
static
Timestamp.
from_any
(thing)¶ Try to construct a timestamp from whatever we’re given.
The possible inputs can be:
a Python datetime (in which case we just return a copy of the input)
a string in the format
2013-04-05 11:23:45
, in which case we will assume that it resides intimestamp.DEFAULT_TIMEZONE
a string in the format
2013-04-05 11:23:45-05
, in which case we will assume that it’s UTC-5 (or other time zone, accordingly)a string in the format
2013-04-05T11:23:45
or2013-04-05T11:23:45-05
– just like above but with a T in the middle instead of a spacea string in the format
20130405112345
- these are assumed to reside in the default time zonea string in the format
MM-DD-YYYY HH:MM:SS
a string such as
08-Aug-2013 12:34:45
where ‘Aug’ is the abbreviated name for a month in your local environmenta dict containing at least
year
,month
,day
entries and optionallyhour
,minute
,second
andutc_offset
Internally this method dispatches to all of the other
Timestamp.from_xxx()
methods.- Parameters
thing – Thing to try to convert to a timestamp
- Returns
Timezone-aware
datetime
object
-
static
Timestamp.
to_string
(dt, format_string='%Y-%m-%d %H:%M:%S`, include_tz=False)¶ Create a string from a timestamp.
Format contents as a string, by default formatted as
2013-04-21 14:45:00
. You may supply an argumentformat_string
if you want it in a different form. See the documentation fordatetime.strftime()
for information on what this format string looks like.- Parameters
dt (
datetime.datetime
) – Timestamp object to stringifyformat_string (string) – String to pass to
datetime.strftime()
include_tz (Boolean) – Whether or not to append timezone as UTC offset
- Returns
String representation of timestamp
-
static