Trajectory Module¶

Module Contents¶

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.

PropertyMap const &__properties() const¶

PropertyMap &__non_const_properties()¶

void __set_properties(PropertyMap const &props)¶

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.

void insert(int index, point_type const &value)¶

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

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

Parameters

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

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

void compute_current_features(std::size_t start_index)¶

Public Types

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

typedef std::vector<PointT> point_vector_type¶

typedef point_vector_type::iterator iterator¶

typedef point_vector_type::const_iterator const_iterator¶

typedef point_vector_type::reverse_iterator reverse_iterator¶

typedef point_vector_type::const_reverse_iterator const_reverse_iterator¶

typedef point_vector_type::size_type size_type¶

typedef point_vector_type::value_type value_type¶

typedef point_vector_type::difference_type difference_type¶

typedef point_vector_type::reference reference¶

typedef point_vector_type::const_reference const_reference¶

Public Functions

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

~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
[in] generate_uuid: Flag to generate a UUID for the trajectory

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
[in] generate_uuid: Flag to generate a UUID for the trajectory

template<class InputIterator> Trajectory(InputIterator first, InputIterator last, const Trajectory &original)¶

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

Trajectory &clone() const¶: Make this trajectory a clone 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.

const_iterator cbegin() 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.