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 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.
-
point_vector_type Points
Internal storage for the points in the trajectory.
-
PropertyMap Properties
-
inline 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
-
inline bool empty() const
Return whether or not the trajectory is empty.
-
inline void reserve(size_type n)
Preallocate enough space in the array for the specified number of entries.
- Parameters:
n – [in] Allocate space for this many points.
-
template<typename iter_type>
inline void assign(iter_type iter_begin, iter_type iter_end) Populate a trajectory from a sequence ot points.
- Parameters:
iter_begin – [in] Iterator pointing to first point
iter_end – [in] Iterator pointing after last point
-
inline 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
-
inline bool operator!=(const Trajectory &other) const
Check whether two trajectories are unequal.
- Parameters:
other – Trajectory for comparison
-
inline 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
-
inline 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
-
inline 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
-
inline 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).
- Parameters:
i – [in] Which point to retrieve
- Returns:
Mutable reference to the requested point
-
inline 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);
- Parameters:
i – [in] Which point to retrieve
- Returns:
Immutable reference to the requested point
-
inline 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:
position – [in] Iterator pointing at the location to erase.
-
inline 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:
first – [in] Iterator pointing at the first point to erase
last – [in] Iterator pointing to the location after the last point to erase
-
inline void clear()
Reset the trajectory to an empty state.
This clears out the vector of points.
-
inline point_type &front()
Return the first point in the trajectory.
Note
If you call this on an empty trajectory the behavior is undefined.
- Returns:
First point in trajectory (mutable reference)
-
inline point_type const &front() const
Return the (immutable) first point in the trajectory.
Note
If you call this on an empty trajectory the behavior is undefined.
- Returns:
First point in trajectory (immutable reference)
-
inline point_type &back()
Return the last point in the trajectory.
Note
If you call this on an empty trajectory the behavior is undefined. Dereferencing back() on an empty trajectory will probably crash your program.
- Returns:
Last point in trajectory (mutable reference)
-
inline point_type const &back() const
Return the (immutable) last point in the trajectory.
Note
If you call this on an empty trajectory the behavior is undefined. Dereferencing back() on an empty trajectory will probably crash your program.
- Returns:
Last point in trajectory (immutable reference)
-
inline 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:
index – [in] Location to insert the point
value – [in] Point to insert
-
inline 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:
position – [in] Location to insert the point
value – [in] Point to insert
-
inline 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:
position – [in] Where to insert the points
n – [in] How many points to insert
value – [in] What point to insert
-
template<class InputIterator>
inline 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:
position – [in] Where to start inserting the points
first – [in] The first point to insert
last – [in] The location after the last point to insert
-
inline void compute_current_features(std::size_t start_index)
-
inline iterator begin()
Return an iterator pointing to the beginning of the trajectory
The point underneath this iterator can be changed.
-
inline const_iterator begin() const
Return an iterator pointing to the beginning of the trajectory
The point underneath this iterator cannot be changed.
-
inline const_iterator cbegin() const noexcept
Return an iterator pointing to the beginning of the trajectory
The point underneath this iterator cannot be changed.
-
inline 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.
-
inline 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.
-
inline const_iterator cend() const noexcept
Return an iterator pointing beyond the last point in the trajectory
The point underneath this iterator, if there is one, cannot be changed.
-
inline reverse_iterator rbegin()
Return a reverse_iterator pointing to the end of the trajectory
The point underneath this iterator can be changed.
-
inline const_reverse_iterator rbegin() const
Return a reverse_iterator pointing to the end of the trajectory
The point underneath this iterator cannot be changed.
-
inline const_reverse_iterator crbegin() const noexcept
Return a reverse_iterator pointing to the end of the trajectory
The point underneath this iterator cannot be changed.
-
inline reverse_iterator rend()
Return an iterator pointing beyond the first point in the trajectory
The point underneath this iterator, if there is one, can be changed.
-
inline const_reverse_iterator rend() const
Return an iterator pointing beyond the last point in the trajectory
The point underneath this iterator, if there is one, cannot be changed.
-
inline const_reverse_iterator crend() const noexcept
Return an iterator pointing beyond the last point in the trajectory
The point underneath this iterator, if there is one, cannot be changed.
-
inline void set_property(std::string const &name, PropertyValueT const &value)
Set a named property with a variant value (let the caller handle the type)
-
inline PropertyValueT property(std::string const &name, bool *ok = 0) const
Retrieve a named property with checking.
-
inline PropertyValueT property_without_checking(std::string const &name) const
Retrieve a named property without safety checking.
-
inline std::string string_property(std::string const &name, bool *ok = 0) const
Safely retrieve a named property with a string value.
-
inline double real_property(std::string const &name, bool *ok = 0) const
Safely retrieve a named property with a floating-point value.
-
inline Timestamp timestamp_property(std::string const &name, bool *ok = 0) const
Safely retrieve a named property with a timestamp value.
-
inline bool has_property(std::string const &name) const
Check whether a property is present.
-
inline PropertyMap const &__properties() const
-
inline PropertyMap &__non_const_properties()
-
inline void __set_properties(PropertyMap const &props)
Public Types
-
typedef PointT point_type
Convenient aliases for template parameters and types from internal storage.
-
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
-
inline Trajectory(bool generate_uuid = true)
Instantiate an empty trajectory
-
inline ~Trajectory()
-
inline Trajectory(const Trajectory &other)
Create a trajectory a copy of another.
-
inline 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:
n – [in] Length of the trajectory
initial_value – [in] Point to be used to fill the new vector
generate_uuid – [in] Flag to generate a UUID for the trajectory
-
template<class InputIterator>
inline 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:
first – [in] Iterator pointing to the first point for the new trajectory
last – [in] Iterator pointing past the last point for the new trajectory
generate_uuid – [in] Flag to generate a UUID for the trajectory
-
template<class InputIterator>
inline Trajectory(InputIterator first, InputIterator last, const Trajectory &original)
-
inline Trajectory &operator=(const Trajectory &other)
Make this trajectory a copy of another.
-
inline Trajectory &clone() const
Make this trajectory a clone of another.
-
inline 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.
-
inline 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.
-
inline 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.
- Returns:
the difference of end_time and start_time or 0 if no points.
-
inline void set_uuid()
Set the UUID of the trajectory to a random UUID using the systemwide generator
-
inline 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)”.
-
inline 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.
Friends
- friend class boost::serialization::access
-
point_vector_type Points