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