Basic Classes¶
Domains¶
Tracktable operates on points, timestamps and trajectories. Since points and trajectories are meaningless without a coordinate system, we instantiate points and trajectories from a domain. Each domain provides several different data types and a standard set of units. By design, it is difficult to mix points and trajectories from different domains. While we cannot prevent you entirely from mixing up (for example) kilometers and miles when computing distances, we can at least try to make it difficult.
Tracktable includes the following domains:
C++ Namespace |
Description |
---|---|
tracktable::domain::terrestrial |
Points in longitude/latitude space |
tracktable::domain::cartesian2d |
Points in flat 2D space |
tracktable::doamin::cartesian3d |
Points in flat 3D space |
tracktable::doamin::feature_vectors |
Collection of points in cartesian space with 2 to 30 dimensions |
Each domain defines several data types:
C++ Class |
Description |
---|---|
base_point_type |
Bare point - just coordinates. |
trajectory_point_type |
Point with coordinates, object ID, timestamp and user-defined properties. |
trajectory_type |
Vector of trajectory points. Trajectories have their own user-defined properties. |
linestring_type |
Vector of un-decorated points (base points). |
box_type |
Axis-aligned bounding box. |
base_point_reader_type |
Read base points from a delimited text file. |
trajectory_reader_type |
Read Trajectories from a delimited text file. |
trajectory_point_reader_type |
Read Trajectory points from a delimited text file. |
Note
In this guide we will assume you are working with
trajectory_point_type
data rather than base_point_type
data
and that the data is in the terrestrial domain.
Timestamp¶
There is a single timestamp class that is common across all point
domains. tracktable::Timestamp
is a thinly disguised
boost::posix_time::ptime
.
The tracktable
namespace contains several
convenience methods for manipulating timestamps. A full list is located in
the timestamp reference documentation.
We use the following ones most frequently.
tracktable::time_from_string()
: Convert a string into it’s timestamp representation. By default this will produce the timestamp March 5, 2014 at 13:44:06 from the string “2014-03-05 13:44:06”.tracktable::time_to_string()
: Convert a timestamp into its string representation. By default this will produce the string “2014-03-05 13:44:06” from the timestamp March 5, 2014 at 13:44:06.
Point Types¶
Base Points¶
Within a domain, Tracktable uses the base_point_type
to store a bare set of coordinates.
These behave like standard C++ objects with the appropriate getters and setters.
1#include <tracktable/Domain/Terrestrial.h>
2
3typedef tracktable::domain::terrestrial::TerrestrialPoint TerrestrialPoint;
4
5int lon = 40;
6int lat = 50;
7
8TerrestrialPoint point;
9point.set_longitude(lon);
10point.set_latitude(lat);
Trajectory Points¶
For assembling trajectories in a given domain, Tracktable uses
the trajectory_point_type
class to store the (lon, lat)
coordinates as well as additional point information such as the
timestamp
and object_id
.
These are the main differences between base_point_type
and trajectory_point_type
.
Its coordinates, reference BasePoint above.
An identifier for the moving object.
A timestamp recording when the object was observed.
To generate and initialize a trajectory point you would do something like the code below:
1#include <tracktable/Core/TrajectoryPoint.h>
2#include <tracktable/Core/Timestamp.h>
3
4typedef tracktable::domain::terrestrial::TerrestrialTrajectoryPoint TerrestrialTrajectoryPoint;
5
6std::string id = "FlightId";
7int lon = 40;
8int lat = 50;
9
10TerrestrialTrajectoryPoint point;
11point.set_object_id(id);
12point.set_longitude(lon);
13point.set_latitude(lat);
14point.set_timestamp(tracktable::time_from_string("2014-04-05 13:25:00"));
Note
The timestamp
and object_id
properties are specific to trajectory points.
You may want to associate other data with a point as well. For example:
1point.set_property("altitude", 13400);
2point.set_property("origin, "ORD");
3point.set_property("destination", "LAX");
4point.set_property("departure_time", tracktable::time_from_string("2015-02-01 18:00:00"));
The trajectory can only hold values that are of numeric
, string
or
Timestamp
type.
LineStrings¶
We include linestring_type
for the ability to create ordered sequences of
points. linestring_type
is analogous to base_point_type
in that it has no
decoration at all. linestring_type
just a vector of base_point_type
points.
1#include <tracktable/Domain/Terrestrial.h>
2
3typedef tracktable::domain::terrestrial::TerrestrialPoint TerrestrialPoint;
4typedef tracktable::domain::terrestrial::linestring_type LineStringTerrestrial;
5
6double corners[3][2] = {
7 { 44, 33 },
8 { 44.0769, 32.5862 },
9 { 44, 33 }
10};
11
12LineStringTerrestrial linestring;
13linestring.push_back(TerrestrialPoint(corners[0]));
14linestring.push_back(TerrestrialPoint(corners[1]));
15linestring.push_back(TerrestrialPoint(corners[2]));
Trajectories¶
We include Trajectory
for ordered sequences of points.
Trajectory
has its own ID (trajectory_id
) as well as its own properties
array.
As with the point types above, each domain in Tracktable defines a trajectory class. A trajectory is just a vector of points with a few extra properties attached. A trajectory is an iterable just like any other point sequence. Here is an example of creating a trajectory.
1#include <tracktable/Domain/Terrestrial.h>
2
3using tracktable::domain::terrestrial::base_point_type;
4using tracktable::domain::terrestrial::trajectory_point_type;
5using tracktable::domain::terrestrial::trajectory_type;
6
7trajectory_point_type albuquerque;
8trajectory_point_type santa_fe;
9trajectory_point_type roswell;
10trajectory_type trajectory;
11
12std::string obj_id("GreenChileExpress001");
13albuquerque.set_longitude(-106.6100);
14albuquerque.set_latitude(35.1107);
15albuquerque.set_object_id(obj_id);
16albuquerque.set_timestamp(tracktable::time_from_string("2014-05-01 12:00:00"));
17
18santa_fe.set_longitude(-105.9644);
19santa_fe.set_latitude(35.6672);
20santa_fe.set_object_id(obj_id);
21santa_fe.set_timestamp(tracktable::time_from_string("2014-05-01 13:00:00"));
22
23roswell.set_longitude(-104.5281);
24roswell.set_latitude(33.3872);
25roswell.set_object_id(obj_id);
26roswell.set_timestamp(tracktable::time_from_string("2014-05-01 14:00:00"));
27
28trajectory.push_back(albuquerque);
29trajectory.push_back(santa_fe);
30trajectory.push_back(roswell);
Note
Tracktable expects that all points in a given trajectory will have the same object ID. Timestamps must not decrease from one point to the next.
There are several free functions defined on trajectories that do useful things. We expect that the following will be used most often:
point_at_time(TrajectoryT const& path, Timestamp const& time)
: Given a timestamp, interpolate between points on the trajectory to find the point at exactly the specified time. Timestamps before the beginning or after the end of the trajectory will return the start and end points, respectively. Tracktable will try to interpolate all properties that are defined on the trajectory points.subset_during_interval(TrajectoryT const& path, Timestamp const& start, Timestamp const& finish)
: Given a start and end timestamp, extract the subset of the trajectory between those two times. The start and end points will be at exactly the start and end times you specify. These will be interpolated if there are no points in the trajectory at precisely the right time. Points in between the start and end times will be copied from the trajectory without modification.