Trajectory.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18 */
19 
20 /*!
21  \file Trajectory.h
22 
23  \brief This file contains a class to represent a trajectory.
24  */
25 
26 #ifndef __TERRALIB_ST_INTERNAL_TRAJECTORY_H
27 #define __TERRALIB_ST_INTERNAL_TRAJECTORY_H
28 
29 //TerraLib
30 #include "../../../sam/rtree/Index.h"
31 
32 //ST
33 #include "../../Config.h"
34 #include "../../Enums.h"
35 #include "TrajectoryObservation.h"
36 #include "TrajectoryIterator.h"
37 
38 //STL
39 #include <vector>
40 #include <map>
41 #include <memory>
42 
43 // Boost
44 #include <boost/shared_ptr.hpp>
45 
46 // Forward declarations
47 namespace te { namespace dt { class DateTime; class DateTimePeriod; } }
48 namespace te { namespace gm { class Geometry; class Envelope; } }
49 
50 namespace te
51 {
52  namespace st
53  {
54  // Forward declarations
55  class TimeSeries;
57 
58  // Typedef
59  typedef boost::shared_ptr<te::sam::rtree::Index<te::dt::DateTime*> > TjRTreeShrPtr;
60 
61  /*!
62  \class Trajectory
63 
64  \brief A class to represent trajectory.
65 
66  A trajectory represents the variation of spatial locations or boundaries of an
67  object over time. It is composed of an observation set and of an interpolator.
68  The observations have a fixed object identity and measured geometries at controlled
69  times. The interpolator is able to estimate spaces at non-observed times.
70 
71  \ingroup st
72 
73  \sa ObservationSet AbstractInterpolator
74  */
76  {
77  public:
78 
79  /*! \name Trajectory Constructors */
80  //@{
81 
82  /*!
83  \brief Empty constructor.
84 
85  It constructs an empty trajectory. The user does not indicate the interpolator
86  associated to it. Internally, it uses a default interpolator
87  that is NearestGeometryAtTimeInterp.
88  */
89  Trajectory();
90 
91  /*!
92  \brief Empty constructor.
93 
94  It constructs an empty trajectory. The user does not indicate the interpolator
95  associated to it. Internally, it uses a default interpolator
96  that is NearestGeometryAtTimeInterp.
97 
98  \param id The trajectory id
99  */
100  Trajectory(const std::string& id);
101 
102  /*!
103  \brief Empty constructor.
104 
105  It constructs an empty trajectory.
106 
107  \param interp The interpolator associated to the trajectory.
108  \param id The trajectory id.
109 
110  */
111  Trajectory(AbstractTrajectoryInterp* interp, const std::string& id);
112 
113  /*!
114  \brief Constructor.
115 
116  The user does not indicate the interpolator
117  associated to it. Internally, it uses a default interpolator
118  that is NearestGeometryAtTimeInterp.
119 
120  \param obs The trajectory observations.
121  \param id The trajectory id.
122 
123  \note This constructor does not build the internal RTree
124  */
125  Trajectory(const TrajectoryObservationSet& obs, const std::string& id);
126 
127  /*!
128  \brief Constructor.
129 
130  \param obs The trajectory observations.
131  \param interp The interpolator associated to the trajectory.
132  \param id The trajectory id.
133 
134  \note This constructor does not build the internal RTree
135  */
137  const std::string& id);
138 
139  /*!
140  \brief It constructs a trajectory from a patch
141 
142  \param patch The given patch.
143  \param interp The interpolator
144  \param id The trajectory id
145  */
146  Trajectory(const TrajectoryPatch& patch, AbstractTrajectoryInterp* interp,
147  const std::string& id);
148 
149  /*!
150  \brief Copy constructor.
151 
152  \note They will share the internal pointers.
153  \note The caller has to use the method "clone" to have a deep copy.
154  */
155  Trajectory(const Trajectory& tj);
156  //@}
157 
158  /*!
159  \brief Copy assignment operator
160 
161  \note They will share the internal pointers.
162  \note The caller has to use the method "clone" to have a deep copy.
163  */
164  Trajectory& operator=(const Trajectory& other);
165 
166  /*!
167  \brief It returns a clone of this trajectory.
168 
169  \return A new trajectory
170 
171  \note The caller will take the ownership of the returned pointer.
172  */
173  Trajectory* clone() const;
174 
175  /*!
176  \brief It returns the trajectory observations.
177 
178  \return A reference to the trajectory observations.
179  */
180  const TrajectoryObservationSet& getObservations() const;
181 
182  /*!
183  \brief It returns the interpolator associated to the trajectory.
184 
185  \return A pointer the interpolator associated to the trajectory.
186 
187  \note The caller will NOT take the ownership of the returned pointer.
188  \note The AbstractTrajectoryInterp points to a singleton.
189  */
190  AbstractTrajectoryInterp* getInterpolator() const;
191 
192  /*!
193  \brief It sets the interpolator associated to the path.
194 
195  \param interp A interpolator which is able to estimate geometries in non-observed times.
196 
197  \note It will NOT take the ownership of the input pointer.
198  \note The AbstractTrajectoryInterp points to a singleton.
199  */
200  void setInterpolator(AbstractTrajectoryInterp* interp);
201 
202  /*!
203  \brief It returns the trajectory id.
204 
205  \return The trajectory id.
206  */
207  std::string getId() const;
208 
209  /*!
210  \brief It sets the trajectory id.
211 
212  \param id The trajectory od.
213  */
214  void setId(const std::string& id);
215 
216  /*!
217  \brief It adds an observation (time and geometry) into the trajectory.
218 
219  \param time A pointer to the time.
220  \param data A pointer to the geometry.
221 
222  \note The caller will take the ownership of the given pointers.
223  */
224  void add(te::dt::DateTime* time, te::gm::Geometry* geom);
225 
226  /*!
227  \brief It adds an observation (time and geometry) into the trajectory.
228 
229  \param p A pair of date and time.
230 
231  \note The caller will take the ownership of the returned pointer.
232  */
233  void add(const TrajectoryObservation& p);
234 
235  /*!
236  \brief It returns the size of the trajectory observations.
237 
238  \return The observations size of the trajectory.
239  */
240  std::size_t size() const;
241 
242  /*! \name Trajectory Iterator
243 
244  An example of use:
245 
246  TrajectoryIterator it = tj.begin();
247  while(it!=tj.end())
248  {
249  Geometry* g = it.getGeometry();
250  DateTime* t = it.getTime();
251  ++it;
252  }
253  */
254  //@{
255  /*!
256  \brief It returns an iterator that points to the first observation of the trajectory.
257 
258  \return The trajectory iterator.
259  */
260  TrajectoryIterator begin() const;
261 
262  /*!
263  \brief It returns an iterator that points to the end of the trajectory.
264 
265  \return The trajectory iterator.
266  */
267  TrajectoryIterator end() const;
268 
269  /*!
270  \brief It returns an iterator that points to an observation at a given time.
271 
272  If there is no observation at this given time, the returned iterator
273  points to the end of the trajectory.
274 
275  \return The trajectory iterator.
276  \note This does not take the ownership of the given pointer.
277  */
279  //@}
280 
281  /*!
282  \brief It returns the geometry associated to a given date and time.
283 
284  If there is no geometry associated to the given date and time, it will
285  use internally its interpolation function.
286 
287  \param t A date and time.
288 
289  \return A pointer to the geometry associated to the given date and time.
290 
291  \note The caller WILL take the ownership of the returned pointer.
292  */
293  std::auto_ptr<te::gm::Geometry> getGeometry(te::dt::DateTime* t) const;
294 
295  /*!
296  \brief It returns the temporal extent of the trajectory observations.
297 
298  \return The temporal extent of trajectory observations.
299 
300  \note The caller will take the ownership of the output pointer.
301  */
302  std::auto_ptr<te::dt::DateTimePeriod> getTemporalExtent() const;
303 
304  /*!
305  \brief It returns the spatial extent of the trajectory observations.
306 
307  \return The spatial extent of the trajectory observations.
308 
309  \note The caller will take the ownership of the output pointer.
310  */
311  te::gm::Envelope getSpatialExtent() const;
312 
313  /*! \name Trajectory Patch
314 
315  These methods return patches of a trajectory, as TrajectoryPatch objects,
316  that satisfy given restrictions.
317  A TrajectoryPatch object contains only pointers to the initial and
318  final observations that delimit a patch of a Trajectory. The
319  end() method of a TrajectoryPatch object returns an iterator
320  that points to the position AFTER the last required observation.
321 
322  Example of use:
323 
324  TrajectoryPatch patch = tj->getTrajectory(period, "DURING");
325  TrajectoryIterator it = patch.begin();
326  while(it!=patch.end())
327  {
328  Geometry* g = it.getGeometry();
329  DateTime* t = it.getTime();
330  ++it;
331  }
332 
333  Other option is to create a new Trajectory from the returned patch:
334 
335  TrajectoryPatch patch = tj->getTrajectory(period, "DURING");
336  Trajectory tjnew(patch);
337  */
338  //@{
339  /*!
340  \brief It returns a trajectory subset that satisfies a given temporal relation.
341 
342  The possible temporal relations are: AFTER (2);
343  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
344  DURING (4); EQUALS (8)
345 
346  \param dt A given date and time.
347  \param r A given temporal relation.
348 
349  \return A patch of the trajectory.
350 
351  \note When the temporal relation is DURING, dt must be a time period.
352  */
354 
355  /*!
356  \brief It returns trajectory subsets that satisfy a given spatial relation.
357 
358  The possible spatial relation is: 1. INTERSECTS
359 
360  \param g A given envelope.
361  \param r A given spatial relation.
362  \param result The returned patches.
363  */
364  void getPatches(const te::gm::Envelope& g, te::gm::SpatialRelation r,
365  std::vector<TrajectoryPatch>& result) const;
366 
367  /*!
368  \brief It returns trajectory subsets that satisfy a given spatial relation.
369 
370  The possible spatial relation is: 1. INTERSECTS
371 
372  \param geom A given geometry.
373  \param r A given spatial relation.
374  \param result The returned patches.
375  */
376  void getPatches(const te::gm::Geometry& geom, te::gm::SpatialRelation r,
377  std::vector<TrajectoryPatch>& result) const;
378 
379  /*!
380  \brief It returns trajectory subsets that satisfy a given spatial
381  and temporal relation.
382 
383  The possible temporal relations are: AFTER (2);
384  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
385  DURING (4); EQUALS (8)
386 
387  The possible spatial relation is: 1. INTERSECTS
388 
389  \param e A given envelope.
390  \param r A given spatial relation.
391  \param dt A given date and time.
392  \param r A given temporal relation.
393  \param result The returned patches.
394  */
395  void getPatches(const te::gm::Envelope& e, te::gm::SpatialRelation sr,
397  std::vector<TrajectoryPatch>& result) const;
398 
399  /*!
400  \brief It returns trajectory subsets that satisfy a given spatial
401  and temporal relation.
402 
403  The possible temporal relations are: AFTER (2);
404  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
405  DURING (4); EQUALS (8)
406 
407  The possible spatial relation is: 1. INTERSECTS
408 
409  \param geom A given geometry.
410  \param r A given spatial relation.
411  \param dt A given date and time.
412  \param r A given temporal relation.
413  \param result The returned patches.
414  */
415  void getPatches(const te::gm::Geometry& geom, te::gm::SpatialRelation sr,
417  std::vector<TrajectoryPatch>& result) const;
418 
419  /*!
420  \brief It returns trajectory subsets that satisfy a given
421  spatiotemporal relation.
422 
423  The possible spatiotemporal relations are:
424  1. REACH; 2. EXITS; 3. REACHES; 4. LEAVES
425 
426  \param geom A given geometry.
427  \param srt A given spatiotemporal relation.
428  \param result The returned patches.
429  */
430  void getPatches(const te::gm::Geometry& geom, te::st::SpatioTemporalRelation str,
431  const std::vector<TrajectoryPatch>& result) const;
432  //@}
433 
434  /*!
435  \brief It returns the distance between two trajectories.
436 
437  \param other The other trajectory.
438  \return a time series that maps times to the distances.
439 
440  \note The caller will take the ownership of the returned pointer.
441  */
442  std::auto_ptr<TimeSeries> getDistance(const Trajectory& other) const;
443 
444  /*!
445  \brief It returns the distance between the trajectory and a given geometry.
446 
447  \param geom A given geometry.
448  \return a time series that maps times to the distances.
449 
450  \note The caller will take the ownership of the returned pointer.
451  */
452  std::auto_ptr<TimeSeries> getDistance(const te::gm::Geometry& geom);
453 
454  /*! \brief Virtual destructor. */
455  virtual ~Trajectory();
456 
457  private:
458 
459  TrajectoryObservationSet m_observations; //!< The trajectory observations
460  AbstractTrajectoryInterp* m_interpolator; //!< The interpolator used to estimate non-observed times.
461  std::string m_id; //!< The trajectory identification.
462  TjRTreeShrPtr m_rtree; //!< The RTree to index the trajectory geometries
463  };
464  } // end namespace st
465 } // end namespace te
466 
467 #endif // __TERRALIB_ST_INTERNAL_TRAJECTORY_H
468 
This file contains a typedef that defines observations of trajectory.
#define TESTEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:88
AbstractTrajectoryInterp * m_interpolator
The interpolator used to estimate non-observed times.
Definition: Trajectory.h:460
A struct to represent a patch or a continuous piece of a trajectory.
boost::shared_ptr< te::sam::rtree::Index< te::dt::DateTime * > > TjRTreeShrPtr
Definition: Trajectory.h:56
TemporalRelation
Temporal relations between date and time (Source: Allen, 1991).
Definition: Enums.h:140
SpatialRelation
Spatial relations between geometric objects.
Definition: Enums.h:127
std::map< te::dt::DateTimeShrPtr, te::gm::GeometryShrPtr, CompareShrDateTime > TrajectoryObservationSet
TrajectoryObservationSet m_observations
The trajectory observations.
Definition: Trajectory.h:459
This file contains a trajetory iterator.
An abstract class for an interpolation function or interpolator that estimates geometries at non-obse...
SpatioTemporalRelation
An enum for the types of spatiotemporal relation.
Definition: Enums.h:34
std::pair< te::dt::DateTimeShrPtr, te::gm::GeometryShrPtr > TrajectoryObservation
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
URI C++ Library.
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:74
A class to represent trajectory.
Definition: Trajectory.h:75
TjRTreeShrPtr m_rtree
The RTree to index the trajectory geometries.
Definition: Trajectory.h:462
std::string m_id
The trajectory identification.
Definition: Trajectory.h:461
A class to traverse the observations of a trajectory.