LineString.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 terralib/geometry/LineString.h
22 
23  \brief LineString is a curve with linear interpolation between points.
24 */
25 
26 #ifndef __TERRALIB_GEOMETRY_INTERNAL_LINESTRING_H
27 #define __TERRALIB_GEOMETRY_INTERNAL_LINESTRING_H
28 
29 // TerraLib
30 #include "Coord2D.h"
31 #include "Curve.h"
32 
33 // STL
34 #include <vector>
35 
36 namespace te
37 {
38  namespace gm
39  {
40  /*!
41  \class LineString
42 
43  \brief LineString is a curve with linear interpolation between points.
44 
45  In a linestring each consecutive pair of points defines a line segment.
46  Internally, we store an array of coordinates and separate arrays for points with z and m.
47  All OGC interface is supported based on points through the method getPointN.
48  But the extended methods, for coordinates, will be faster than the same versions of OGC
49  methods because they work with less complex structures (coordinates) than points.
50 
51  \note A LineString must have at least two coordinates, otherwise, its methods must not be called.
52 
53  \ingroup geometry
54 
55  \sa Geometry,
56  AbstractPoint, Point, PointM, PointZ, PointZM, PointKd,
57  Curve, Line, LinearRing, CircularString, CompoundCurve,
58  Surface, Polygon, Triangle, CurvePolygon, PolyhedralSurface, TIN,
59  GeometryCollection, MultiSurface, MultiCurve,
60  MultiPoint, MultiLineString, MultiPolygon
61  */
62  class TEGEOMEXPORT LineString : public Curve
63  {
64  public:
65 
66  TE_DEFINE_VISITABLE
67 
68  /** @name Initializer methods on geometric objects
69  * Methods for initializing a geometric object.
70  */
71  //@{
72 
73  /*!
74  \brief It initializes the linestring with the specified spatial reference system id and envelope.
75 
76  \param t The internal type of the linestring.
77  \param srid The Spatial Reference System ID associated to the linestring.
78  \param mbr The minimum bounding rectangle of this geometry (i.e., its envelope).
79 
80  \note The linestring will take the ownership of the given mbr.
81  */
82  LineString(GeomType t, int srid = 0, Envelope* mbr = 0);
83 
84  /*!
85  \brief It initializes the linestring with the specified spatial reference system id and envelope.
86 
87  \param size The number of points in the LineString. It must be a value greater than 0.
88  \param t The internal type of the linestring.
89  \param srid The Spatial Reference System ID associated to the linestring.
90  \param mbr The minimum bounding rectangle of this geometry (i.e., its envelope).
91 
92  \note The linestring will take the ownership of the given mbr.
93  */
94  LineString(std::size_t size, GeomType t, int srid = 0, Envelope* mbr = 0);
95 
96  /*!
97  \brief Copy constructor.
98 
99  \param rhs The other geometry.
100  */
101  LineString(const LineString& rhs);
102 
103  /*! \brief Virtual destructor. */
104  virtual ~LineString();
105 
106  /*!
107  \brief Assignment operator.
108 
109  \param rhs The other geometry.
110 
111  \return A reference for this.
112  */
113  virtual LineString& operator=(const LineString& rhs);
114 
115  //@}
116 
117  /** @name Re-Implementation from AbstractData
118  * Methods re-Implementated from AbstractData.
119  */
120  //@{
121 
122  /*!
123  \brief It clones the linestring.
124 
125  \return A copy of the given linestring.
126 
127  \note The caller of this method will take the ownership of the returned linestring.
128 
129  \note The cloned linestring will not have the
130  MBR computed. This will save time when you
131  are just cloning a geometry and don't intend
132  to waste time computing the bounding box.
133  If you have another suggestion, please, let me know.
134  */
135  virtual te::dt::AbstractData* clone() const;
136 
137  //@}
138 
139  /** @name Re-Implmentation of methods from Geometry class
140  * Re-Implmentation of basic methods from Geometry class.
141  */
142  //@{
143 
144  /*!
145  \brief The name of instantiable subtype is: LineString.
146 
147  \return The name of instantiable subtype is: LineString.
148  */
149  const std::string& getGeometryType() const throw();
150 
151  /*!
152  \brief It sets the Spatial Reference System ID of the linestring.
153 
154  \param srid The Spatial Reference System ID to be associated to the linestring.
155 
156  \note TerraLib extended method.
157  */
158  void setSRID(int srid) throw();
159 
160  /*!
161  \brief It converts the coordinate values of the linestring to the new spatial reference system.
162 
163  After calling this method the linestring will be associated to the new SRID.
164 
165  \param srid The new Spatial Reference System ID used to transform the coordinates of the linestring.
166 
167  \exception Exception It will throw an exception if it can not do the transformation.
168 
169  \note The linestring must be associated to a valid SRID before calling this method.
170 
171  \note If the linestring already has an associated MBR, this method will automatically update it (i. e. automatically recompute it).
172  */
173  void transform(int srid) throw(te::common::Exception);
174 
175  /*!
176  \brief It computes the minimum bounding rectangle for the linestring.
177 
178  \param cascade For linestring this flag doesn't have effect.
179 
180  \note You can use this method in order to update the MBR of the linestring.
181 
182  \note TerraLib extended method.
183  */
184  void computeMBR(bool cascade) const throw();
185 
186  /*!
187  \brief It returns the number of points (vertexes) in the linestring.
188 
189  \return The number of points (vertexes) in the linestring.
190 
191  \note TerraLib extended method.
192  */
193  std::size_t getNPoints() const throw() { return m_nPts; }
194 
195  /*!
196  \brief It returns a derived geometry collection value according to the range of coordinate values inclusively.
197 
198  \param mStart The initial coordinate value.
199  \param mEnd The final coordinate value.
200 
201  \return A GeometryCollection value.
202 
203  \note The caller of this method will take the ownership of geometry.
204  */
205  Geometry* locateBetween(const double& mStart, const double& mEnd) const throw(Exception);
206 
207  //@}
208 
209  /** @name Re-Implementation from Curve
210  * Methods re-impleented from Curve.
211  */
212  //@{
213 
214  /*!
215  \brief The length of this Curve in its associated spatial reference.
216 
217  \return The length of this Curve in its associated spatial reference.
218  */
219  //double getLength() const;
220 
221  /*!
222  \brief It returns the curve start point.
223 
224  \return The curve start point.
225 
226  \note The caller of this method will take the ownership of the point geometry.
227  */
228  Point* getStartPoint() const;
229 
230  /*!
231  \brief It returns the curve end point.
232 
233  \return The curve end point.
234 
235  \note The caller of this method will take the ownership of the point geometry.
236  */
237  Point* getEndPoint() const;
238 
239  /*!
240  \brief It returns true if the curve is closed (startPoint = endPoint).
241 
242  \return True if the curve is closed (startPoint = endPoint).
243 
244  \warning The line must have at least 2 points.
245  */
246  bool isClosed() const;
247 
248  //@}
249 
250  /** @name LineString Specific Methods
251  * Specific methods for a LineString.
252  */
253  //@{
254 
255  /*!
256  \brief It returns the number of points (vertexes) in the geometry.
257 
258  \return The number of points (vertexes) in the geometry.
259 
260  \note TerraLib extended method.
261  */
262  std::size_t size() const { return m_nPts; }
263 
264  /*!
265  \brief It reserves room for the number of coordinates in this LineString.
266 
267  \param size The number of coordinates reserved for the LineString.
268 
269  \note TerraLib extended method.
270  */
271  void setNumCoordinates(std::size_t size);
272 
273  /*!
274  \brief It clears all the coordinates.
275 
276  After calling this method you can not use the set methods.
277  You will need to use the setNumCoordinates method in order
278  to use the set methods.
279 
280  \note TerraLib extended method.
281  */
282  void makeEmpty();
283 
284  /*!
285  \brief It returns the specified point in this LineString.
286 
287  \param i The index of the point you want to retrieve.
288 
289  \return The specified point in this LineString.
290 
291  \note The caller of this method will take the ownership of the point geometry.
292 
293  \note This method doesn't check the index range.
294  */
295  Point* getPointN(std::size_t i) const;
296 
297  /*!
298  \brief It sets the value of the specified point to this new one.
299 
300  \param i The index where the point will be set to the new value.
301  \param p The new point value.
302 
303  \note TerraLib extended method.
304  */
305  void setPointN(std::size_t i, const Point& p);
306 
307  /*!
308  \brief It sets the value of the specified point.
309 
310  \param i The index where the point will be set to the new value.
311  \param x The x coordinate value.
312  \param y The y coordinate value.
313 
314  \note TerraLib extended method.
315  */
316  void setPoint(std::size_t i, const double& x, const double& y);
317 
318  /*!
319  \brief It sets the value of the specified point.
320 
321  \param i The index where the point will be set to the new value.
322  \param x The x coordinate value.
323  \param y The y coordinate value.
324  \param z The z coordinate value.
325 
326  \note TerraLib extended method.
327  */
328  void setPointZ(std::size_t i, const double& x, const double& y, const double& z);
329 
330  /*!
331  \brief It sets the value of the specified point.
332 
333  \param i The index where the point will be set to the new value.
334  \param x The x coordinate value.
335  \param y The y coordinate value.
336  \param m The m coordinate value.
337 
338  \note TerraLib extended method.
339  */
340  void setPointM(std::size_t i, const double& x, const double& y, const double& m);
341 
342  /*!
343  \brief It sets the value of the specified point.
344 
345  \param i The index where the point will be set to the new value.
346  \param x The x coordinate value.
347  \param y The y coordinate value.
348  \param z The z coordinate value.
349  \param m The m coordinate value.
350 
351  \note TerraLib extended method.
352  */
353  void setPointZM(std::size_t i, const double& x, const double& y, const double& z, const double& m);
354 
355  /*!
356  \brief It returns the n-th x coordinate value.
357 
358  \param i The n-th coordinate.
359 
360  \return The n-th x coordinate value.
361 
362  \note TerraLib extended method.
363  */
364  const double& getX(std::size_t i) const;
365 
366  /*!
367  \brief It returns the n-th y coordinate value.
368 
369  \param i The n-th coordinate.
370 
371  \return The n-th y coordinate value.
372 
373  \note TerraLib extended method.
374  */
375  const double& getY(std::size_t i) const;
376 
377  /*!
378  \brief It returns the n-th z coordinate value.
379 
380  \param i The n-th coordinate.
381 
382  \return The n-th z coordinate value.
383 
384  \note Don't call this method if the LineString doesn't have Z coordinate values.
385 
386  \note TerraLib extended method.
387  */
388  const double& getZ(std::size_t i) const;
389 
390  /*!
391  \brief It returns the n-th m measure value.
392 
393  \param i The n-th coordinate.
394 
395  \return The n-th m measure value.
396 
397  \note Don't call this method if the LineString doesn't have M coordinate values.
398 
399  \note TerraLib extended method.
400  */
401  const double& getM(std::size_t i) const;
402 
403  /*!
404  \brief It sets the n-th x coordinate value.
405 
406  \param i The coordinate index.
407  \param x The x value.
408 
409  \note TerraLib extended method.
410  */
411  void setX(std::size_t i, const double& x);
412 
413  /*!
414  \brief It sets the n-th y coordinate value.
415 
416  \param i The coordinate index.
417  \param y The y value.
418 
419  \note TerraLib extended method.
420  */
421  void setY(std::size_t i, const double& y);
422 
423  /*!
424  \brief It sets the n-th z coordinate value.
425 
426  \param i The coordinate index.
427  \param z The z value.
428 
429  \note Don't call this method if the LineString doesn't have Z coordinate values.
430 
431  \note TerraLib extended method.
432  */
433  void setZ(std::size_t i, const double& z);
434 
435  /*!
436  \brief It sets the n-th m measure value.
437 
438  \param i The coordinate index.
439  \param m The m value.
440 
441  \note Don't call this method if the LineString doesn't have M coordinate values.
442 
443  \note TerraLib extended method.
444  */
445  void setM(std::size_t i, const double& m);
446 
447  /*!
448  \brief It returns a pointer to the internal array of coordinates.
449 
450  \return A pointer to the internal array of coordinates.
451 
452  \warning Don't use this method unless you know exactly what you're doing!
453 
454  \note TerraLib extended method.
455  */
456  Coord2D* getCoordinates() const
457  {
458  return m_coords;
459  }
460 
461  /*!
462  \brief It returns a pointer to the internal array of z-values.
463 
464  \return A pointer to the internal array of z-values.
465 
466  \warning Don't use this method unless you know exactly what you're doing!
467 
468  \note TerraLib extended method.
469  */
470  double* getZ() const
471  {
472  return m_zA;
473  }
474 
475  /*!
476  \brief It returns a pointer to the internal array of m-values.
477 
478  \return A pointer to the internal array of m-values.
479 
480  \warning Don't use this method unless you know exactly what you're doing!
481 
482  \note TerraLib extended method.
483  */
484  double* getM() const
485  {
486  return m_mA;
487  }
488 
489  //@}
490 
491  protected:
492 
493  Coord2D* m_coords; //!< A pointer to x, y values.
494  double* m_zA; //!< A pointer to z values.
495  double* m_mA; //!< A pointer to m values.
496  std::size_t m_nPts; //!< The number of coordinates of the LineString.
497 
498  private:
499 
500  static const std::string sm_typeName; //! Geometry type name for LineString.
501  };
502 
503  } // end namespace gm
504 } // end namespace te
505 
506 #endif // __TERRALIB_GEOMETRY_INTERNAL_LINESTRING_H
507 
te::gm::GeomType
GeomType
Each enumerated type is compatible with a Well-known Binary (WKB) type code.
Definition: Enums.h:41
te::gm::LineString::sm_typeName
static const std::string sm_typeName
Definition: LineString.h:500
te::gm::LineString::getCoordinates
Coord2D * getCoordinates() const
It returns a pointer to the internal array of coordinates.
Definition: LineString.h:456
te::Exception
Base exception class for plugin module.
Definition: Exception.h:42
te::gm::Curve
Curve is an abstract class that represents 1-dimensional geometric objects stored as a sequence of co...
Definition: Curve.h:58
te::gm::Coord2D
An utility struct for representing 2D coordinates.
Definition: Coord2D.h:40
te::gm::LineString::m_zA
double * m_zA
A pointer to z values.
Definition: LineString.h:494
te::gm::LineString::m_nPts
std::size_t m_nPts
The number of coordinates of the LineString.
Definition: LineString.h:496
TEGEOMEXPORT
#define TEGEOMEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:76
te::gm::LineString
LineString is a curve with linear interpolation between points.
Definition: LineString.h:62
te::gm::LineString::getM
double * getM() const
It returns a pointer to the internal array of m-values.
Definition: LineString.h:484
te::gm::Point
A point with x and y coordinate values.
Definition: Point.h:50
te::gm::Envelope
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
te
URI C++ Library.
Definition: AddressGeocodingOp.h:51
te::gm::LineString::getNPoints
std::size_t getNPoints() const
It returns the number of points (vertexes) in the linestring.
Definition: LineString.h:193
te::dt::AbstractData
A base class for values that can be retrieved from the data access module.
Definition: AbstractData.h:57
te::gm::LineString::m_coords
Coord2D * m_coords
A pointer to x, y values.
Definition: LineString.h:493
TE_DEFINE_VISITABLE
#define TE_DEFINE_VISITABLE
Definition: BaseVisitable.h:75
te::common::Exception
This class is designed to declare objects to be thrown as exceptions by TerraLib. ...
Definition: Exception.h:58
te::gm::Geometry
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:74
Curve.h
Curve is an abstract class that represents 1-dimensional geometric objects stored as a sequence of co...
Coord2D.h
An utility struct for representing 2D coordinates.
te::gm::LineString::getZ
double * getZ() const
It returns a pointer to the internal array of z-values.
Definition: LineString.h:470
te::gm::LineString::m_mA
double * m_mA
A pointer to m values.
Definition: LineString.h:495
te::gm::LineString::size
std::size_t size() const
It returns the number of points (vertexes) in the geometry.
Definition: LineString.h:262