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
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
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  */
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
GeomType
Each enumerated type is compatible with a Well-known Binary (WKB) type code.
Definition: Enums.h:41
static const std::string sm_typeName
Definition: LineString.h:500
Coord2D * getCoordinates() const
It returns a pointer to the internal array of coordinates.
Definition: LineString.h:456
Base exception class for plugin module.
Definition: Exception.h:42
Curve is an abstract class that represents 1-dimensional geometric objects stored as a sequence of co...
Definition: Curve.h:58
An utility struct for representing 2D coordinates.
Definition: Coord2D.h:40
double * m_zA
A pointer to z values.
Definition: LineString.h:494
std::size_t m_nPts
The number of coordinates of the LineString.
Definition: LineString.h:496
#define TEGEOMEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:76
LineString is a curve with linear interpolation between points.
Definition: LineString.h:62
double * getM() const
It returns a pointer to the internal array of m-values.
Definition: LineString.h:484
A point with x and y coordinate values.
Definition: Point.h:50
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
URI C++ Library.
std::size_t getNPoints() const
It returns the number of points (vertexes) in the linestring.
Definition: LineString.h:193
A base class for values that can be retrieved from the data access module.
Definition: AbstractData.h:57
Coord2D * m_coords
A pointer to x, y values.
Definition: LineString.h:493
#define TE_DEFINE_VISITABLE
Definition: BaseVisitable.h:75
This class is designed to declare objects to be thrown as exceptions by TerraLib. ...
Definition: Exception.h:58
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:73
Curve is an abstract class that represents 1-dimensional geometric objects stored as a sequence of co...
An utility struct for representing 2D coordinates.
double * getZ() const
It returns a pointer to the internal array of z-values.
Definition: LineString.h:470
double * m_mA
A pointer to m values.
Definition: LineString.h:495
std::size_t size() const
It returns the number of points (vertexes) in the geometry.
Definition: LineString.h:262