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:

Available Point 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:

Domain 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.

  1. Its coordinates, reference BasePoint above.

  2. An identifier for the moving object.

  3. 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.