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