TracktableCore module¶

template<std::size_t Dimension> class PointBase¶

Base class for all points in Tracktable

This class defines a point independent of the number of coordinates or the data type.

You will not use this directly. Instead, you’ll use one of the coordinate-specific versions like PointBaseCartesian or PointBaseLonLat.

PointBase and all of its subclasses will be registered with boost::geometry so that you can use all of the generic geometry algorithms.

Subclassed by tracktable::PointCartesian< 2 >, tracktable::PointCartesian< 3 >, tracktable::PointCartesian< dim >, tracktable::PointCartesian< Dimension >

Public Functions

PointBase()¶: Initialize an empty point.

PointBase(PointBase const &other)¶: Initialize a copy of another point.

virtual ~PointBase()¶

Destructor for our descendants.

Although PointBase itself only needs a trivial destructor, we know that subclasses are going to extend it one way or another.

template<std::size_t d> coordinate_type const &get() const¶

Get the value of a particular coordinate.

Since this is Boost, you set and get coordinates by specifying the coordinate at compile time:

double x = point.get<0>();

template<std::size_t d> void set(coordinate_type const &new_value)¶

Set the value of a particular coordinate.

Since this is Boost, you set and get coordinates by specifying the coordinate at compile time:

point.set<0>(new_value);

coordinate_type const &operator[](std::size_t d) const¶

Get/set the value of a coordinate.

You can use operator[] whether or not you know the coordinate you want ahead of time.

double x = point[0]; point[0] = x;

coordinate_type &operator[](std::size_t d)¶

Get/set the value of a coordinate.

You can use operator[] whether or not you know the coordinate you want ahead of time.

double x = point[0]; point[0] = x;

bool operator==(PointBase const &other) const¶

Check two points for equality.

This requires that the two points have the same dimension.

bool operator!=(PointBase const &other) const¶: Check two points for inequality.

PointBase &operator=(PointBase const &other)¶: Make this point a copy of a different one.

std::size_t size() const¶: Get the number of dimensions in this point.

template<std::size_t Dimension> class PointCartesian : public tracktable::PointBase<Dimension>¶

N-dimensional point in Cartesian space.

This specializes PointBase to exist in a Cartesian coordinate system and be usable with boost::geometry. You must still instantiate it explicitly with the number of dimensions.

Public Types

typedef PointBase<Dimension> Superclass¶: Convenient alias for the parent class.

Public Functions

PointCartesian()¶: Create an uninitialized point.

PointCartesian(Superclass const &other)¶: Make this point into a copy of another.

PointCartesian(const double *coordinates)¶: Create a point with user-supplied coordinates.

class PointLonLat : public tracktable::PointBase<2>¶

2D point on a sphere

This class specializes PointBase to use boost::geometry in a spherical-equatorial coordinate system the familiar longitude/latitude mapping onto a sphere.

Subclassed by tracktable::domain::terrestrial::TerrestrialPoint

Public Types

typedef PointBase<2> Superclass¶: Convenient alias for superclass.

Public Functions

PointLonLat()¶: Create an uninitialized point.

PointLonLat(coord_type const &a, coord_type const &b)¶: Create a 2D point on a sphere (convenience constructor)

PointLonLat(const double *coordinates)¶: Create a 2D point on a sphere (convenience constructor)

PointLonLat(Superclass const &other)¶: Make this point a copy of a generic 2D point.

PointLonLat(PointLonLat const &other)¶: Make this point a copy of another.

coord_type longitude() const¶

Return this point’s longitude.

Return: Longitude in degrees

void set_longitude(coord_type const &new_longitude)¶

Set this point’s longitude.

Parameters

[in] new_longitude: New value for longitude

coord_type latitude() const¶

Return this point’s latitude.

Return: Latitude in degrees

void set_latitude(coord_type const &new_latitude)¶

Set this point’s latitude.

Parameters

[in] new_latitude: New value for latitude

template<class PointT> class Trajectory¶

Ordered sequence of 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.

We provide accessors so that you can treat a Trajectory as if it were a std::vector.

Methods related to properties

void set_property(std::string const &name, PropertyValueT const &value)¶: Set a named property with a variant value (let the caller handle the type)

PropertyValueT property(std::string const &name, bool *ok = 0) const¶: Retrieve a named property with checking.

PropertyValueT property_without_checking(std::string const &name) const¶: Retrieve a named property without safety checking.

std::string string_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a string value.

double real_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a floating-point value.

Timestamp timestamp_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a timestamp value.

bool has_property(std::string const &name) const¶: Check whether a property is present.

Methods that allow a Trajectory to be used like std::vector

Here are all the methods that make this container usable just like a std::vector.

There’s no magic here all we do is forward to the Points vector.

size_type size() const¶: Return the length of the trajectory in points.

size_type max_size() const¶: Return the maximum number of entries the points array can hold.

size_type capacity() const¶: Return the current allocated capacity of the points array.

void resize(size_type new_size, point_type default_value = point_type())¶

Resize the points array to contain exactly the number of entries requested.

Parameters

new_size: Desired length of the vector
default_value: Value for newly allocated entries

bool empty() const¶: Return whether or not the trajectory is empty.

void reserve(size_type n)¶

Preallocate enough space in the array for the specified number of entries.

Parameters

[in] n: Allocate space for this many points.

bool operator==(const Trajectory &other) const¶

Check whether one trajectory is equal to another by comparing all the points.

Two trajectories are equal if all of their points are equal.

This method does not check whether the UUID’s of the trajectories are equal. It only checks the points of the trajectories.

Parameters

other: Trajectory for comparison

bool operator!=(const Trajectory &other) const¶

Check whether two trajectories are unequal.

Parameters

other: Trajectory for comparison

point_type const &operator[](size_type i) const¶

Return a given point from the trajectory.

Return the requested point from the trajectory. It is the caller’s responsibility to ensure that a valid index has been requested.

Parameters

i: Index of desired point

point_type &operator[](size_type i)¶

Return a mutable reference to a given point in the trajectory.

As with the const version of operator[], it is the caller’s responsibility to ensure that a valid index has been requested.

Note

If you change the point’s coordinates you are responsible for calling trajectory->compute_current_length(i) to update the points’ current_length parameter.

Parameters

i: Index of desired point

void push_back(point_type const &pt)¶

Append a point to the trajectory.

Note that this uses copy semantics rather than move semantics. Since move semantics are part of C++11 we will not use them until we can be reasonable sure that suitable compilers are available in all environments that we care about.

Note

Why do we have this alias?

Parameters

pt: Point to append

point_type &at(size_type i)¶

Retrieve the point at a given index with bounds checking.

Retrieve a point. Unlike operator[], at() does bounds checking and will throw an exception if you ask for a point outside the range [0, num_points).

This version of the function will be called if you try to modify the point. For example:

my_trajectory.at(3).set_latitude(15);

Note

If you modify the point’s coordinates, you are responsible for calling trajectory->update_current_length(i).

Return

Mutable reference to the requested point

Parameters

[in] i: Which point to retrieve

point_type const &at(size_type i) const¶

Retrieve the point at a given index with bounds checking.

Retrieve a point. Unlike operator[], at() does bounds checking and will throw an exception if you ask for a point outside the range [0, num_points).

This version of the function will be called if the compiler can tell that you’re not trying to modify the point. For example:

TrajectoryPoint my_point = my_trajectory.at(3);

Return

Immutable reference to the requested point

Parameters

[in] i: Which point to retrieve

iterator erase(iterator position)¶

Remove a point from the trajectory.

Delete the point at the specified position (specified by an iterator). The points after the one deleted will be moved up one spot to fill the gap.

Note

This operation takes linear time in the number of points in the trajectory.

Parameters

[in] position: Iterator pointing at the location to erase.

iterator erase(iterator first, iterator last)¶

Remove a range of points from the trajectory.

Delete points from trajectories starting at ‘first’ and ending at the point just before ‘last’. Points after the deleted range will be moved up to fill the gap.

Note

This operation takes linear time in the number of points in the trajectory.

Parameters

[in] first: Iterator pointing at the first point to erase
[in] last: Iterator pointing to the location after the last point to erase

void clear()¶

Reset the trajectory to an empty state.

This clears out the vector of points.

point_type &front()¶

Return the first point in the trajectory.

Return: First point in trajectory (mutable reference)
Note: If you call this on an empty trajectory the behavior is undefined.

point_type const &front() const¶

Return the (immutable) first point in the trajectory.

Return: First point in trajectory (immutable reference)
Note: If you call this on an empty trajectory the behavior is undefined.

point_type &back()¶

Return the last point in the trajectory.

Return: Last point in trajectory (mutable reference)
Note: If you call this on an empty trajectory the behavior is undefined. Dereferencing back() on an empty trajectory will probably crash your program.

point_type const &back() const¶

Return the (immutable) last point in the trajectory.

Return: Last point in trajectory (immutable reference)
Note: If you call this on an empty trajectory the behavior is undefined. Dereferencing back() on an empty trajectory will probably crash your program.

iterator insert(iterator position, point_type const &value)¶

Insert a single element into the trajectory at an arbitrary position.

Insert a point into any position in the trajectory. All points after this location will be moved farther down.

Parameters

[in] position: Location to insert the point
[in] value: Point to insert

void insert(iterator position, size_type n, point_type const &value)¶

Fill a range in the trajectory.

Insert n copes of the point specified as ‘value’ starting at the specified ‘position’. All points after this location will be moved farther down in the trajectory.

Parameters

[in] position: Where to insert the points
[in] n: How many points to insert
[in] value: What point to insert

template<class InputIterator> void insert(iterator position, InputIterator first, InputIterator last)¶

Insert a range of points into the trajectory.

Insert all points in the range [first, last) into the trajectory. All points after this location will be moved farther down in the trajectory.

Parameters

[in] position: Where to start inserting the points
[in] first: The first point to insert
[in] last: The location after the last point to insert

Public Types

typedef PointT point_type¶: Convenient aliases for template parameters and types from internal storage.

Public Functions

Trajectory(bool generate_uuid = true)¶: Instantiate an empty trajectory.

Trajectory(const Trajectory &other)¶: Create a trajectory a copy of another.

Trajectory(size_type n, point_type initial_value = point_type(), bool generate_uuid = true)¶

Create a new trajectory with pre-specified length.

Create a new trajectory with n elements. You may also supply a point that will be copied into each element.

Parameters

[in] n: Length of the trajectory
[in] initial_value: Point to be used to fill the new vector

template<class InputIterator> Trajectory(InputIterator first, InputIterator last, bool generate_uuid = true)¶

Create a new trajectory from a range of points.

Create a new trajectory by copying points from [first, last).

Parameters

[in] first: Iterator pointing to the first point for the new trajectory
[in] last: Iterator pointing past the last point for the new trajectory

Trajectory &operator=(const Trajectory &other)¶: Make this trajectory a copy of another.

Timestamp start_time() const¶

Return the start time if available.

If there are any points in the trajectory this method will return the timestamp on the first point. If not, it will return an invalid Timestamp.

Timestamp end_time() const¶

Return the end time if available.

If there are any points in the trajectory this method will return the timestamp on the last point. If not, it will return an invalid Timestamp.

Duration duration() const¶

Return the duration, if available.

If there are any points in the trajectory, this method will return the duration of the trajectory. If not it will return a duration of 0.

Return: the difference of end_time and start_time or 0 if no points.

const uuid_type &uuid() const¶: Return the UUID (RFC 4122 or variant) of the trajectory.

void set_uuid(const uuid_type &new_uuid)¶: Set the UUID of the trajectory.

void set_uuid()¶: Set the UUID of the trajectory to a random UUID using the systemwide generator.

std::string object_id() const¶

Return the ID of the moving object.

If there are any points in the trajectory, return the object ID of the first one. Otherwise return the string “(empty)”.

std::string trajectory_id() const¶

Return a human-readable ID for the trajectory.

Return a mostly-unique ID for the trajectory incorporating its object ID, start time and end time. If the trajectory is empty then we return the string “(empty)”.

Note that if you have multiple trajectories with the same object ID, start time and end time, this identifier will not be unique.

iterator begin()¶

Return an iterator pointing to the beginning of the trajectory.

The point underneath this iterator can be changed.

const_iterator begin() const¶

Return an iterator pointing to the beginning of the trajectory.

The point underneath this iterator cannot be changed.

iterator end()¶

Return an iterator pointing beyond the last point in the trajectory.

The point underneath this iterator, if there is one, can be changed.

const_iterator end() const¶

Return an iterator pointing beyond the last point in the trajectory.

The point underneath this iterator, if there is one, cannot be changed.

Protected Attributes

uuid_type UUID¶: Internal storage for the trajectory UUID.

point_vector_type Points¶: Internal storage for the points in the trajectory.

template<class BasePointT> class TrajectoryPoint : public BasePointT ¶

Add object ID, timestamp, property map.

This class will add trajectory properties (a timestamp, an object ID and storage for named properties) to any point class.

Timestamp is a tracktable::Timestamp which (under the hood) is a boost::posix_time::ptime. Object ID is stored as a string.

We also include an interface to set, get and enumerate arbitrary named properties. The only restriction is that the types of these properties are limited to timestamps, floating-point numbers and strings. If you need something more flexible than that please consider creating your own alternative point class either by subclassing TrajectoryPoint or by composition.

Note: Named property support is implemented using boost::variant. You can either use boost::get<> to cast it to your desired data type or call one of the (type)_property_value functions to retrieve it with no casting necessary. Take a look at C++/Core/Tests/test_trajectory_point.cpp (XXX CHECK THIS) for a demonstration.

Public Functions

TrajectoryPoint()¶: Instantiate an uninitialized point.

TrajectoryPoint(TrajectoryPoint const &other)¶: Initialize a TrajectoryPoint as a copy of an existing point.

TrajectoryPoint(Superclass const &other)¶: Initialize with coordinates from a base point.

TrajectoryPoint operator=(TrajectoryPoint const &other)¶: Make this TrajectoryPoint a copy of an existing point.

bool operator==(TrajectoryPoint const &other) const¶: Check two points for equality.

bool operator!=(TrajectoryPoint const &other) const¶: Check two points for inequality.

std::string object_id() const¶: Return this point’s object ID.

Timestamp timestamp() const¶: Return this point’s timestamp.

void set_object_id(std::string const &new_id)¶: Set this point’s object ID.

void set_timestamp(Timestamp const &ts)¶: Set this point’s timestamp.

void set_property(std::string const &name, PropertyValueT const &value)¶: Set a named property with a variant value (let the caller handle the type)

PropertyValueT property(std::string const &name, bool *ok = 0) const¶: Retrieve a named property with checking.

PropertyValueT property(std::string const &name, PropertyValueT const &default_value) const¶: Retrieve a named property or a default value.

PropertyValueT property_without_checking(std::string const &name) const¶: Retrieve a named property without safety checking.

std::string string_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a string value.

double real_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a floating-point value.

Timestamp timestamp_property(std::string const &name, bool *ok = 0) const¶: Safely retrieve a named property with a timestamp value.

std::string string_property_with_default(std::string const &name, std::string const &default_value) const¶: Safely retrieve a named property with a string value.

double real_property_with_default(std::string const &name, double default_value) const¶: Safely retrieve a named property with a floating-point value.

Timestamp timestamp_property_with_default(std::string const &name, Timestamp const &default_value) const¶: Safely retrieve a named property with a timestamp value.

bool has_property(std::string const &name) const¶: Check whether a property is present.

std::string to_string() const¶: Convert point to a human-readable string form.

double current_length() const¶: Get length of trajectory up to this point.

void set_current_length(double length)¶: Set length of trajectory up to this point.

PropertyMap &__non_const_properties()¶: INTERNAL METHOD.

void __set_properties(PropertyMap const &props)¶: INTERNAL METHOD.

Protected Attributes

double CurrentLength¶: Length of trajectory up to this point.

std::string ObjectId¶: Storage for a point’s object ID.

PropertyMap Properties¶: Storage for a point’s named properties.

Timestamp UpdateTime¶: Storage for a point’s timestamp.