1 /* 2 gg_core.h -- Gaia common support for geometries: core functions 3 4 version 5.0, 2020 August 1 5 6 Author: Sandro Furieri a.furieri@lqt.it 7 8 ------------------------------------------------------------------------------ 9 10 Version: MPL 1.1/GPL 2.0/LGPL 2.1 11 12 The contents of this file are subject to the Mozilla Public License Version 13 1.1 (the "License"); you may not use this file except in compliance with 14 the License. You may obtain a copy of the License at 15 http://www.mozilla.org/MPL/ 16 17 Software distributed under the License is distributed on an "AS IS" basis, 18 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 19 for the specific language governing rights and limitations under the 20 License. 21 22 The Original Code is the SpatiaLite library 23 24 The Initial Developer of the Original Code is Alessandro Furieri 25 26 Portions created by the Initial Developer are Copyright (C) 2008-2021 27 the Initial Developer. All Rights Reserved. 28 29 Contributor(s): 30 31 32 Alternatively, the contents of this file may be used under the terms of 33 either the GNU General Public License Version 2 or later (the "GPL"), or 34 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 35 in which case the provisions of the GPL or the LGPL are applicable instead 36 of those above. If you wish to allow use of your version of this file only 37 under the terms of either the GPL or the LGPL, and not to allow others to 38 use your version of this file under the terms of the MPL, indicate your 39 decision by deleting the provisions above and replace them with the notice 40 and other provisions required by the GPL or the LGPL. If you do not delete 41 the provisions above, a recipient may use your version of this file under 42 the terms of any one of the MPL, the GPL or the LGPL. 43 44 */ 45 46 47 /** 48 \file gg_core.h 49 50 Geometry handling functions: core 51 */ 52 53 #ifndef _GG_CORE_H 54 #ifndef DOXYGEN_SHOULD_SKIP_THIS 55 #define _GG_CORE_H 56 #endif 57 58 #ifdef __cplusplus 59 extern "C" 60 { 61 #endif 62 63 #if defined(_WIN32) && !defined(__MINGW32__) 64 #include <spatialite/gaiaconfig-msvc.h> 65 #else 66 #include <spatialite/gaiaconfig.h> 67 #endif 68 69 /* constant values for gaiaGeodesicArcLength return_type */ 70 71 /** Arc Length measured in Degrees */ 72 #define GAIA_GEODESIC_ARC_LENGTH_DEGREES 0 73 74 /** Arc Length measured in Meters */ 75 #define GAIA_GEODESIC_ARC_LENGTH_METERS 1 76 77 /** Chord Length measured in Degrees */ 78 #define GAIA_GEODESIC_CHORD_LENGTH_DEGREES 2 79 80 /** Chord Length measured in Meters */ 81 #define GAIA_GEODESIC_CHORD_LENGTH_METERS 3 82 83 /** Central Angle measured in Radians */ 84 #define GAIA_GEODESIC_CENTRAL_ANGLE_RADIANS 4 85 86 /** Central Angle measured in Degrees */ 87 #define GAIA_GEODESIC_CENTRAL_ANGLE_DEGREES 5 88 89 /** Area of segment/arc measured in Square Meters */ 90 #define GAIA_GEODESIC_ARC_AREA_METERS 6 91 92 /** Height of segment/arc in Meters */ 93 #define GAIA_GEODESIC_ARC_HEIGHT_METERS 7 94 95 96 /* function prototypes */ 97 98 /** 99 Safely frees any dynamic memory block allocated by the library itself 100 101 \param ptr pointer to dynamically allocated memory 102 103 \note on some platforms (most notably, Microsoft Windows) many different 104 runtime libraries may actually support the same process. 105 \n attempting to free() a memory block allocated by a different runtime 106 module may easily cause fatal memory corruption. 107 */ 108 GAIAGEO_DECLARE void gaiaFree (void *ptr); 109 110 /** 111 Allocates a 2D POINT [XY] 112 113 \param x the X coordinate. 114 \param y the Y coordinate. 115 116 \return the pointer to the newly created POINT object: NULL on failure 117 118 \sa gaiaFreePoint 119 120 \note you are responsible to destroy (before or after) any allocated 121 POINT, unless you've passed ownership of the POINT object to some 122 further object: in this case destroying the higher order object will 123 implicitly destroy any contained child object. 124 */ 125 GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPoint (double x, double y); 126 127 /** 128 Allocates a 3D POINT [XYZ] 129 130 \param x the X coordinate. 131 \param y the Y coordinate. 132 \param z the Z coordinate. 133 134 \return the pointer to the newly created POINT object: NULL on failure 135 136 \sa gaiaFreePoint 137 138 \note you are responsible to destroy (before or after) any allocated 139 POINT, unless you've passed ownership of the POINT object to some 140 further object: in this case destroying the higher order object will 141 implicitly destroy any contained child object. 142 */ 143 GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYZ (double x, double y, 144 double z); 145 146 /** 147 Allocates a 2D POINT [XYM] 148 149 \param x the X coordinate. 150 \param y the Y coordinate. 151 \param m the M measure. 152 153 \return the pointer to the newly created POINT object: NULL on failure 154 155 \sa gaiaFreePoint 156 157 \note you are responsible to destroy (before or after) any allocated 158 POINT, unless you've passed ownership of the POINT object to some 159 further object: in this case destroying the higher order object will 160 implicitly destroy any contained child object. 161 */ 162 GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYM (double x, double y, 163 double m); 164 165 /** 166 Allocates a 3D POINT [XYZM] 167 168 \param x the X coordinate. 169 \param y the Y coordinate. 170 \param z the Z coordinate. 171 \param m the M measure. 172 173 \return the pointer to the newly created POINT object: NULL on failure 174 175 \sa gaiaFreePoint 176 177 \note you are responsible to destroy (before or after) any allocated 178 POINT, unless you've passed ownership of the POINT object to some 179 further object: in this case destroying the higher order object will 180 implicitly destroy any contained child object. 181 */ 182 GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYZM (double x, double y, 183 double z, double m); 184 185 /** 186 Destroys a POINT object 187 188 \param ptr pointer to the POINT object to be destroyed 189 190 \sa gaiaAllocPoint, gaiaAllocPointXYZ, gaiaAllocPointXYM, gaiaAllocPointXYZM 191 192 \note attempting to destroy any POINT object whose ownership has already 193 been transferred to some other (higher order) object is a serious 194 error, and will easily cause severe memory corruption. 195 */ 196 GAIAGEO_DECLARE void gaiaFreePoint (gaiaPointPtr ptr); 197 198 /** 199 Allocates a 2D LINESTRING [XY] 200 201 \param vert number of points [aka vertices] into the Linestring 202 203 \return the pointer to newly created LINESTRING object: NULL on failure 204 205 \sa gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPoint, 206 gaiaGetPoint 207 208 \note you are responsible to destroy (before or after) any allocated LINESTRING, 209 unless you've passed ownership of the LINESTRING object to some further 210 object: in this case destroying the higher order object will implicitly 211 destroy any contained child object. 212 */ 213 GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestring (int vert); 214 215 /** 216 Allocates a 3D LINESTRING [XYZ] 217 218 \param vert number of points [aka vertices] into the Linestring 219 220 \return the pointer to newly created LINESTRING object: NULL on failure 221 222 \sa gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYZ, 223 gaiaGetPointXYZ 224 225 \note you are responsible to destroy (before or after) any allocated LINESTRING, 226 unless you've passed ownership of the LINESTRING object to some further 227 object: in this case destroying the higher order object will implicitly 228 destroy any contained child object. 229 */ 230 GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYZ (int vert); 231 232 /** 233 Allocates a 2D LINESTRING [XYM] 234 235 \param vert number of points [aka vertices] into the Linestring 236 237 \return the pointer to newly created LINESTRING object: NULL on failure 238 239 \sa gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYM, 240 gaiaGetPointXYM 241 242 \note you are responsible to destroy (before or after) any allocated LINESTRING, 243 unless you've passed ownership of the LINESTRING object to some further 244 object: in this case destroying the higher order object will implicitly 245 destroy any contained child object. 246 */ 247 GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYM (int vert); 248 249 /** 250 Allocates a 3D LINESTRING [XYZM] 251 252 \param vert number of points [aka vertices] into the Linestring 253 254 \return the pointer to newly created LINESTRING object: NULL on failure 255 256 \sa gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYZM, 257 gaiaGetPointXYZM 258 259 \note you are responsible to destroy (before or after) any allocated LINESTRING, 260 unless you've passed ownership of the LINESTRING object to some further 261 object: in this case destroying the higher order object will implicitly 262 destroy any contained child object. 263 */ 264 GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYZM (int vert); 265 266 /** 267 Destroys a LINESTRING object 268 269 \param ptr pointer to the LINESTRING object to be destroyed 270 271 \sa gaiaAllocLinestring, gaiaAllocLinestringXYZ, gaiaAllocLinestringXYM, 272 gaiaAllocLinestringXYZM 273 274 \note attempting to destroy any LINESTRING object whose ownnership has already 275 been transferred to some other (higher order) object is a serious 276 error, and will easily cause severe memory corruption. 277 */ 278 GAIAGEO_DECLARE void gaiaFreeLinestring (gaiaLinestringPtr ptr); 279 280 /** 281 Copies coordinates between two LINESTRING objects 282 283 \param dst destination LINESTRING [output] 284 \param src origin LINESTRING [input] 285 286 \sa gaiaCopyLinestringCoordsReverse, gaiaCopyLinestringCoordsEx 287 288 \note both LINESTRING objects must have exactly the same number of points: 289 if dimensions aren't the same for both objects, then the appropriate 290 conversion will be silently applied. 291 */ 292 GAIAGEO_DECLARE void gaiaCopyLinestringCoords (gaiaLinestringPtr dst, 293 gaiaLinestringPtr src); 294 295 /** 296 Copies coordinates between two LINESTRING objects 297 298 \param dst destination LINESTRING [output] 299 \param src origin LINESTRING [input] 300 \param z_no_data the default Z value 301 \parma m_no_data the default M value 302 303 \sa gaiaCopyLinestringCoords 304 305 \note both LINESTRING objects must have exactly the same number of points: 306 if dimensions aren't the same for both objects, then the appropriate 307 conversion will be silently applied. 308 */ 309 GAIAGEO_DECLARE void gaiaCopyLinestringCoordsEx (gaiaLinestringPtr dst, 310 gaiaLinestringPtr src, 311 double z_no_data, 312 double m_no_data); 313 314 /** 315 Copies coordinates between two LINESTRING objects in reverse order 316 317 \param dst destination LINESTRING [output] 318 \param src origin LINESTRING [input] 319 320 \sa gaiaCopyLinestringCoords 321 322 \note both LINESTRING objects must have exactly the same number of points: 323 if dimensions aren't the same for both objects, then the appropriate 324 conversion will be silently applied. 325 */ 326 GAIAGEO_DECLARE void gaiaCopyLinestringCoordsReverse (gaiaLinestringPtr 327 dst, 328 gaiaLinestringPtr 329 src); 330 331 /** 332 Allocates a 2D RING [XY] 333 334 \param vert number of points [aka vertices] into the Ring 335 336 \return the pointer to newly created RING object: NULL on failure 337 338 \sa gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPoint, 339 gaiaGetPoint 340 341 \note you are responsible to destroy (before or after) any allocated RING, 342 unless you've passed ownership of the RING object to some further 343 object: in this case destroying the higher order object will implicitly 344 destroy any contained child object. 345 */ 346 GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRing (int vert); 347 348 /** 349 Allocates a 3D RING [XYZ] 350 351 \param vert number of points [aka vertices] into the Ring 352 353 \return the pointer to newly created RING object: NULL on failure 354 355 \sa gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYZ, 356 gaiaGetPointXYZ 357 358 \note you are responsible to destroy (before or after) any allocated RING, 359 unless you've passed ownership of the RING object to some further 360 object: in this case destroying the higher order object will implicitly 361 destroy any contained child object. 362 */ 363 GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYZ (int vert); 364 365 /** 366 Allocates 2D RING [XYM] 367 368 \param vert number of points [aka vertices] into the Ring 369 370 \return the pointer to newly created RING object: NULL on failure 371 372 \sa gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYM, 373 gaiaGetPointXYM 374 375 \note you are responsible to destroy (before or after) any allocated RING, 376 unless you've passed ownership of the RING object to some further 377 object: in this case destroying the higher order object will implicitly 378 destroy any contained child object. 379 */ 380 GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYM (int vert); 381 382 /** 383 Allocates a 3D RING [XYZM] 384 385 \param vert number of points [aka vertices] into the Ring 386 387 \return the pointer to newly created RING object: NULL on failure 388 389 \sa gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYZM, 390 gaiaSetPointXYZM 391 392 \note you are responsible to destroy (before or after) any allocated RING, 393 unless you've passed ownership of the RING object to some further 394 object: in this case destroying the higher order object will implicitly 395 destroy any contained child object. 396 */ 397 GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYZM (int vert); 398 399 /** 400 Destroys a RING object 401 402 \param ptr pointer to the RING object to be destroyed 403 404 \sa gaiaAllocRing, gaiaAllocRingXYZ, gaiaAllocRingXYM, 405 gaiaAllocRingXYZM 406 407 \note attempting to destroy any RING object whose ownership has already 408 been transferred to some other (higher order) object is a serious 409 error, and will easily cause severe memory corruption. 410 */ 411 GAIAGEO_DECLARE void gaiaFreeRing (gaiaRingPtr ptr); 412 413 /** 414 Copies coordinates between two RING objects 415 416 \param dst destination RING [output] 417 \param src origin RING [input] 418 419 \sa gaiaCopyRingCoordsReverse, gaiaCopyRingCoordEx 420 421 \note both RING objects must have exactly the same number of points: 422 if dimensions aren't the same for both objects, then the appropriate 423 conversion will be silently applied. 424 */ 425 GAIAGEO_DECLARE void gaiaCopyRingCoords (gaiaRingPtr dst, gaiaRingPtr src); 426 427 /** 428 Copies coordinates between two RING objects 429 430 \param dst destination RING [output] 431 \param src origin RING [input] 432 \param z_no_data the default Z value 433 \param m_no_data the default M value 434 435 \sa gaiaCopyRingCoords 436 437 \note both RING objects must have exactly the same number of points: 438 if dimensions aren't the same for both objects, then the appropriate 439 conversion will be silently applied. 440 */ 441 GAIAGEO_DECLARE void gaiaCopyRingCoordsEx (gaiaRingPtr dst, gaiaRingPtr src, 442 double z_no_data, 443 double m_no_data); 444 445 /** 446 Copies coordinates between two RING objects in reverse order 447 448 \param dst destination RING [output] 449 \param src origin RING [input] 450 451 \sa gaiaCopyRingCoords 452 453 \note both RING objects must have exactly the same number of points: 454 if dimensions aren't the same for both objects, then the appropriate 455 conversion will be silently applied. 456 */ 457 GAIAGEO_DECLARE void gaiaCopyRingCoordsReverse (gaiaRingPtr dst, 458 gaiaRingPtr src); 459 460 /** 461 Allocates a 2D POLYGON [XY] 462 463 \param vert number of points [aka vertices] into the Exterior Ring. 464 \param holes number of Interior Rings [0, if no Interior Ring is required]. 465 466 \return the pointer to newly created POLYGON object: NULL on failure 467 468 \sa gaiaFreePolygon 469 470 \note you are responsible to destroy (before or after) any allocated POLYGON, 471 unless you've passed ownership of the POLYGON object to some further 472 object: in this case destroying the higher order object will implicitly 473 destroy any contained child object. 474 */ 475 GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygon (int vert, int holes); 476 477 /** 478 Allocates a 3D POLYGON [XYZ] 479 480 \param vert number of points [aka vertices] into the Exterior Ring. 481 \param holes number of Interior Rings [0, if no Interior Ring is required]. 482 483 \return the pointer to newly created POLYGON object: NULL on failure 484 485 \sa gaiaFreePolygon 486 487 \note you are responsible to destroy (before or after) any allocated POLYGON, 488 unless you've passed ownership of the POLYGON object to some further 489 object: in this case destroying the higher order object will implicitly 490 destroy any contained child object. 491 */ 492 GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYZ (int vert, int holes); 493 494 /** 495 Allocates a 2D POLYGON [XYM] 496 497 \param vert number of points [aka vertices] into the Exterior Ring. 498 \param holes number of Interior Rings [0, if no Interior Ring is required]. 499 500 \return the pointer to newly created POLYGON object: NULL on failure 501 502 \sa gaiaFreePolygon 503 504 \note you are responsible to destroy (before or after) any allocated POLYGON, 505 unless you've passed ownership of the POLYGON object to some further 506 object: in this case destroying the higher order object will implicitly 507 destroy any contained child object. 508 */ 509 GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYM (int vert, int holes); 510 511 /** 512 Allocates a 3D POLYGON [XYZM] 513 514 \param vert number of points [aka vertices] into the Exterior Ring. 515 \param holes number of Interior Rings [may by 0, if no Interior Ring is required]. 516 517 \return the pointer to newly created POLYGON object: NULL on failure 518 519 \sa gaiaFreePolygon 520 521 \note you are responsible to destroy (before or after) any allocated POLYGON, 522 unless you've passed ownership of the POLYGON object to some further 523 object: in this case destroying the higher order object will implicitly 524 destroy any contained child object. 525 */ 526 GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYZM (int vert, int holes); 527 528 /** 529 Allocates a POLYGON 530 531 \param ring pointer to a valid RING object: assumed to be the Polygon's 532 Exterior Ring. 533 534 \return the pointer to newly created POLYGON object: NULL on failure 535 536 \sa gaiaAllocRing, gaiaAllocRingXYZ, gaiaAllocRingXYM, gaiaAllocRingXYZM, 537 gaiaFreePolygon 538 539 \note you are responsible to destroy (before or after) any allocated POLYGON, 540 unless you've passed ownership of the POLYGON object to some further 541 object: in this case destroying the higher order object will implicitly 542 destroy any contained child object. 543 \n Ownership of passed Ring object will be transferred to the 544 Polygon object being created. 545 */ 546 GAIAGEO_DECLARE gaiaPolygonPtr gaiaCreatePolygon (gaiaRingPtr ring); 547 548 /** 549 Destroys a POLYGON object 550 551 \param polyg pointer to the POLYGON object to be destroyed 552 553 \sa gaiaAllocPolygon, gaiaAllocPolygonXYZ, gaiaAllocPolygonXYM, 554 gaiaAllocPolygonXYZM, gaiaCreatePolygon 555 556 \note attempting to destroy any POLYGON object whose ownership has already 557 been transferred to some other (higher order) object is a serious 558 error, and will easily cause severe memory corruption. 559 \n Ownership of each RING object referenced by a POLYGON object always belongs 560 to the POLYGON itself, so destroying the POLYGON will surely destroy 561 any related RING as well. 562 */ 563 GAIAGEO_DECLARE void gaiaFreePolygon (gaiaPolygonPtr polyg); 564 565 /** 566 Allocates a 2D Geometry [XY] 567 568 \return the pointer to newly created Geometry object: NULL on failure 569 570 \sa gaiaFreeGeomColl 571 572 \note you are responsible to destroy (before or after) any allocated Geometry, 573 unless you've passed ownership of the Geometry object to some further 574 object: in this case destroying the higher order object will implicitly 575 destroy any contained child object. 576 */ 577 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomColl (void); 578 579 /** 580 Allocates a 3D Geometry [XYZ] 581 582 \return the pointer to newly created Geometry object: NULL on failure 583 584 \sa gaiaFreeGeomColl 585 586 \note you are responsible to destroy (before or after) any allocated Geometry, 587 unless you've passed ownership of the Geometry object to some further 588 object: in this case destroying the higher order object will implicitly 589 destroy any contained child object. 590 */ 591 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYZ (void); 592 593 /** 594 Allocates a 2D Geometry [XYM] 595 596 \return the pointer to newly created Geometry object: NULL on failure 597 598 \sa gaiaFreeGeomColl 599 600 \note you are responsible to destroy (before or after) any allocated Geometry, 601 unless you've passed ownership of the Geometry object to some further 602 object: in this case destroying the higher order object will implicitly 603 destroy any contained child object. 604 */ 605 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYM (void); 606 607 /** 608 Allocates a 3D Geometry [XYZM] 609 610 \return the pointer to newly created Geometry object: NULL on failure 611 612 \sa gaiaFreeGeomColl 613 614 \note you are responsible to destroy (before or after) any allocated Geometry, 615 unless you've passed ownership of the Geometry object to some further 616 object: in this case destroying the higher order object will implicitly 617 destroy any contained child object. 618 */ 619 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYZM (void); 620 621 /** 622 Destroys a Geometry object 623 624 \param geom pointer to the Geometry object to be destroyed 625 626 \sa gaiaAllocGeomColl, gaiaAllocGeomCollXYZ, gaiaAllocGeomCollXYM, 627 gaiaAllocGeomCollXYZM 628 629 \note attempting to destroy any Geometry object whose ownership has already 630 been transferred to some other (higher order) object is a serious 631 error, and will easily cause severe memory corruption. 632 \n Ownership of each POINT, LINESTRING or POLYGON object referenced by a 633 Geometry object always belongs to the Geometry itself, so destroying the 634 Geometry will surely destroy any related elementary geometry item as well. 635 */ 636 GAIAGEO_DECLARE void gaiaFreeGeomColl (gaiaGeomCollPtr geom); 637 638 /** 639 Creates a new 2D Point [XY] object into a Geometry object 640 641 \param p pointer to the Geometry object 642 \param x X coordinate of the Point to be created 643 \param y X coordinate of the Point to be created 644 645 \note ownership of the newly created POINT object belongs to the Geometry 646 object. 647 */ 648 GAIAGEO_DECLARE void gaiaAddPointToGeomColl (gaiaGeomCollPtr p, double x, 649 double y); 650 651 /** 652 Creates a new 3D Point [XYZ] object into a Geometry object 653 654 \param p pointer to the Geometry object 655 \param x X coordinate of the Point to be created 656 \param y X coordinate of the Point to be created 657 \param z Z coordinate of the Point to be created 658 659 \note ownership of the newly created POINT object belongs to the Geometry 660 object. 661 */ 662 GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYZ (gaiaGeomCollPtr p, 663 double x, double y, 664 double z); 665 666 /** 667 Creates a new 2D Point [XYM] object into a Geometry object 668 669 \param p pointer to the Geometry object 670 \param x X coordinate of the Point to be created 671 \param y X coordinate of the Point to be created 672 \param m M measure of the Point to be created 673 674 \note ownership of the newly created POINT object belongs to the Geometry 675 object. 676 */ 677 GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYM (gaiaGeomCollPtr p, 678 double x, double y, 679 double m); 680 681 /** 682 Creates a new 3D Point [XYZM] object into a Geometry object 683 684 \param p pointer to the Geometry object 685 \param x X coordinate of the Point to be created 686 \param y X coordinate of the Point to be created 687 \param z Z coordinate of the Point to be created 688 \param m M measure of the Point to be created 689 690 \note ownership of the newly created POINT object belongs to the Geometry 691 object. 692 */ 693 GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYZM (gaiaGeomCollPtr p, 694 double x, double y, 695 double z, double m); 696 697 /** 698 Creates a new Linestring object into a Geometry object 699 700 \param p pointer to the Geometry object. 701 \param vert number of points [aka vertices] into the Linestring. 702 703 \return the pointer to newly created Linestring: NULL on failure. 704 705 \note ownership of the newly created Linestring object belongs to the Geometry object. 706 \n the newly created Linestring will have the same dimensions as the Geometry has. 707 */ 708 GAIAGEO_DECLARE gaiaLinestringPtr 709 gaiaAddLinestringToGeomColl (gaiaGeomCollPtr p, int vert); 710 711 /** 712 Inserts an already existing Linestring object into a Geometry object 713 714 \param p pointer to the Geometry object. 715 \param line pointer to the Linestring object. 716 717 \note ownership of the Linestring object will be transferred to the 718 Geometry object. 719 */ 720 GAIAGEO_DECLARE void gaiaInsertLinestringInGeomColl (gaiaGeomCollPtr p, 721 gaiaLinestringPtr 722 line); 723 724 /** 725 Creates a new Polygon object into a Geometry object 726 727 \param p pointer to the Geometry object. 728 \param vert number of points [aka vertices] into the Polygon's Exterior Ring. 729 \param interiors number of Interiors Rings [0, if no Interior Ring is required] 730 731 \return the pointer to newly created Polygon: NULL on failure. 732 733 \note ownership of the newly created Polygon object belongs to the Geometry object. 734 \n the newly created Polygon will have the same dimensions as the Geometry has. 735 */ 736 GAIAGEO_DECLARE gaiaPolygonPtr gaiaAddPolygonToGeomColl (gaiaGeomCollPtr 737 p, int vert, 738 int interiors); 739 740 /** 741 Creates a new Polygon object into a Geometry object starting from an 742 already existing Ring object 743 744 \param p pointer to the Geometry object. 745 \param ring pointer to the Ring object [assumed to represent to Polygon's 746 Exterior Ring]. 747 748 \return the pointer to the newly created Polygon object: NULL on failure. 749 750 \note ownership of the Ring object will be transferred to the 751 Polygon object, and the Polygon object ownerships belongs to the Geometry object. 752 \n the Polygon object will have the same dimensions as the Ring object has. 753 */ 754 GAIAGEO_DECLARE gaiaPolygonPtr 755 gaiaInsertPolygonInGeomColl (gaiaGeomCollPtr p, gaiaRingPtr ring); 756 757 /** 758 Creates a new Interior Ring object into a Polygon object 759 760 \param p pointer to the Polygon object. 761 \param pos relative position index [first Interior Ring has index 0]. 762 \param vert number of points (aka vertices) into the Ring. 763 764 \return the pointer to the newly created Ring object: NULL on failure. 765 766 \sa gaiaAllocPolygon, gaiaAllocPolygonXYZ, gaiaAllocPolygonXYM, 767 gaiaAllocPolygonXYZM 768 769 \note ownership of the Ring object belongs to the Polygon object. 770 \n the newly created Ring will have the same dimensions the Polygon has. 771 */ 772 GAIAGEO_DECLARE gaiaRingPtr gaiaAddInteriorRing (gaiaPolygonPtr p, 773 int pos, int vert); 774 775 /** 776 Inserts an already existing Ring object into a Polygon object 777 778 \param p pointer to the Polygon object 779 \param ring pointer to the Ring object 780 781 \sa gaiaAddRingToPolygon 782 783 \note ownership of the Ring object still remains to the calling procedure 784 (a duplicated copy of the original Ring will be inserted into the Polygon). 785 \n the newly created Polygon will have the same dimensions as the Ring has. 786 \n if required the Polygon's Interior Rings count could be increased. 787 */ 788 GAIAGEO_DECLARE void gaiaInsertInteriorRing (gaiaPolygonPtr p, 789 gaiaRingPtr ring); 790 791 /** 792 Inserts an already existing Ring object into a Polygon object 793 794 \param polyg pointer to the Polygon object 795 \param ring pointer to the Ring object 796 797 \sa gaiaInsertInteriorRing 798 799 \note ownership of the Ring object will be transferred to the Polygon object. 800 \n the newly created Polygon will have the same dimensions as the Ring has. 801 \n if required the Polygon's Interior Rings count could be increased. 802 */ 803 GAIAGEO_DECLARE void gaiaAddRingToPolyg (gaiaPolygonPtr polyg, 804 gaiaRingPtr ring); 805 806 /** 807 Duplicates a Linestring object 808 809 \param line pointer to Linestring object [origin]. 810 811 \return the pointer to newly created Linestring object: NULL on failure. 812 813 \sa gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, 814 gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, 815 gaiaCloneGeomCollPolygons, gaiaCloneLinestringSpecial 816 817 \note the newly created object is an exact copy of the original one. 818 */ 819 GAIAGEO_DECLARE gaiaLinestringPtr gaiaCloneLinestring (gaiaLinestringPtr 820 line); 821 /** 822 Duplicates a Linestring object (special) 823 824 \param line pointer to Linestring object [origin]. 825 \param mode one of GAIA_SAME_ORDER or GAIA_REVERSE_ORDER. 826 827 \return the pointer to newly created Linestring object: NULL on failure. 828 829 \sa gaiaCloneLinestring, gaiaCloneGeomCollSpecial 830 831 \note if GAIA_REVERSE_ORDER is specified, then any vertex into the newly created 832 object will be in reverse order [first vertex will be last one, and last vertex 833 will be the first one]. In any other case this function will simply default to 834 gaiaCloneLinestring. 835 */ 836 GAIAGEO_DECLARE gaiaLinestringPtr 837 gaiaCloneLinestringSpecial (gaiaLinestringPtr line, int mode); 838 839 /** 840 Duplicates a Ring object 841 842 \param ring pointer to Ring object [origin]. 843 844 \return the pointer to newly created Ring object: NULL on failure. 845 846 \sa gaiaCloneLinestring, gaiaClonePolygon, gaiaCloneGeomColl, 847 gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, 848 gaiaCloneGeomCollPolygons, gaiaCloneRingSpecial 849 850 \note the newly created object is an exact copy of the original one. 851 */ 852 GAIAGEO_DECLARE gaiaRingPtr gaiaCloneRing (gaiaRingPtr ring); 853 854 /** 855 Duplicates a Ring object (special) 856 857 \param ring pointer to Ring object [origin]. 858 \param mode one of GAIA_SAME_ORDER or GAIA_REVERSE_ORDER. 859 860 \return the pointer to newly created Ring object: NULL on failure. 861 862 \sa gaiaCloneRing, gaiaClonePolygonSpecial 863 864 \note if GAIA_REVERSE_ORDER is specified, then any vertex into the newly created 865 object will be in reverse order [first vertex will be last one, and last vertex 866 will be the first one]. In any other case this function will simply default to 867 gaiaCloneRing. 868 */ 869 GAIAGEO_DECLARE gaiaRingPtr gaiaCloneRingSpecial (gaiaRingPtr ring, 870 int mode); 871 872 /** 873 Duplicates a Polygon object 874 875 \param polyg pointer to Polygon object [origin]. 876 877 \return the pointer to newly created Polygon object: NULL on failure. 878 879 \sa gaiaCloneLinestring, gaiaCloneRing, gaiaCloneGeomColl, 880 gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, 881 gaiaCloneGeomCollPolygons, gaiaClonePolygonSpecial 882 883 \note the newly created object is an exact copy of the original one. 884 */ 885 GAIAGEO_DECLARE gaiaPolygonPtr gaiaClonePolygon (gaiaPolygonPtr polyg); 886 887 /** 888 Duplicates a Polygon object (special) 889 890 \param polyg pointer to Polygon object [origin]. 891 \param mode one of GAIA_SAME_ORDER, GAIA_REVERSE_ORDER, or GAIA_LHR_ORDER. 892 893 \return the pointer to newly created Polygon object: NULL on failure. 894 895 \sa gaiaClonePolygon, gaiaCloneGeomCollSpecial 896 897 \note if GAIA_REVERSE_ORDER is specified, then any Ring into the newly created 898 object will be in reverse order. If GAIA_CW_ORDER is specified, any 899 Exterior Ring will have clockwise orientation, and any Interior Ring will have 900 counter-clockwise orientation. If GAIA_CCW_ORDER is specified, any 901 Exterior Ring will have counter-clockwise orientation, and any Interior Ring 902 will have clockwise orientation. In any other case this function will simply 903 default to gaiaClonePolygon. 904 */ 905 GAIAGEO_DECLARE gaiaPolygonPtr gaiaClonePolygonSpecial (gaiaPolygonPtr 906 polyg, int mode); 907 908 /** 909 Duplicates a Geometry object 910 911 \param geom pointer to Geometry object [origin]. 912 913 \return the pointer to newly created Geometry object: NULL on failure. 914 915 \sa gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, 916 gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, 917 gaiaCloneGeomCollPolygons, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, 918 gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM, gaiaExtractPointsFromGeomColl, 919 gaiaExtractLinestringsFromGeomColl, gaiaExtractPolygonsFromGeomColl, 920 gaiaMergeGeometries, gaiaCloneGeomCollSpecial 921 922 \note the newly created object is an exact copy of the original one. 923 */ 924 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomColl (gaiaGeomCollPtr geom); 925 926 /** 927 Duplicates a Geometry object (special) 928 929 \param geom pointer to Geometry object [origin]. 930 \param mode one of GAIA_SAME_ORDER, GAIA_REVERSE_ORDER or GAIA_LHR_ORDER. 931 932 \return the pointer to newly created Geometry object: NULL on failure. 933 934 \sa gaiaCloneLinestringSpecial, gaiaCloneRingSpecial, gaiaClonePolygonSpecial, 935 gaiaCloneGeomColl 936 937 \note if GAIA_REVERSE_ORDER is specified, then any Linestring and/or Ring into 938 the newly created object will be in reverse order. If GAIA_LHR_ORDER is specified 939 instead, any Polygong will have the Exterior Ring in clockwise orientation, and any 940 Interior Ring int counter-clockwise orientation. In any other case this function will 941 simply default to gaiaCloneGeomColl. 942 */ 943 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollSpecial (gaiaGeomCollPtr 944 geom, int mode); 945 946 /** 947 Duplicates a Geometry object [Points only] 948 949 \param geom pointer to Geometry object [origin]. 950 951 \return the pointer to newly created Geometry object: NULL on failure. 952 953 \sa gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, 954 gaiaCloneGeomCollLinestrings, 955 gaiaCloneGeomCollPolygons 956 957 \note the newly created object is an exact copy of the original one; except 958 in that only Point objects will be copied. 959 \n Caveat: an empty Geometry could be returned. 960 */ 961 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollPoints (gaiaGeomCollPtr 962 geom); 963 964 /** 965 Duplicates a Geometry object [Linestrings only] 966 967 \param geom pointer to Geometry object [origin]. 968 969 \return the pointer to newly created Geometry object: NULL on failure. 970 971 \sa gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, 972 gaiaCloneGeomCollPoints, gaiaCloneGeomCollPolygons 973 974 \note the newly created object is an exact copy of the original one; except 975 in that only Linestrings objects will be copied. 976 \n Caveat: an empty Geometry could be returned. 977 */ 978 GAIAGEO_DECLARE gaiaGeomCollPtr 979 gaiaCloneGeomCollLinestrings (gaiaGeomCollPtr geom); 980 981 /** 982 Duplicates a Geometry object [Polygons only] 983 984 \param geom pointer to Geometry object [origin]. 985 986 \return the pointer to newly created Geometry object: NULL on failure. 987 988 \sa gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, 989 gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings 990 991 \note the newly created object is an exact copy of the original one; except 992 in that only Polygons objects will be copied. 993 \n Caveat: an empty Geometry could be returned. 994 */ 995 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollPolygons (gaiaGeomCollPtr 996 geom); 997 998 /** 999 Duplicates a Geometry object [casting dimensions to 2D XY] 1000 1001 \param geom pointer to Geometry object [origin]. 1002 1003 \return the pointer to newly created Geometry object: NULL on failure. 1004 1005 \sa gaiaCloneGeomColl, gaiaCastGeomCollToXYZ, 1006 gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM 1007 1008 \note the newly created object is an exact copy of the original one; except 1009 in that any elementary item will be casted to 2D [XY] dimensions. 1010 */ 1011 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXY (gaiaGeomCollPtr geom); 1012 1013 /** 1014 Duplicates a Geometry object [casting dimensions to 3D XYZ] 1015 1016 \param geom pointer to Geometry object [origin]. 1017 1018 \return the pointer to newly created Geometry object: NULL on failure. 1019 1020 \sa gaiaCloneGeomColl, gaiaCastGeomCollToXY, 1021 gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM, 1022 gaiaCostGeomCollToXYZnoData 1023 1024 \note the newly created object is an exact copy of the original one; except 1025 in that any elementary item will be cast to 3D [XYZ] dimensions. 1026 */ 1027 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYZ (gaiaGeomCollPtr 1028 geom); 1029 1030 /** 1031 Duplicates a Geometry object [casting dimensions to 2D XYM] 1032 1033 \param geom pointer to Geometry object [origin]. 1034 1035 \return the pointer to newly created Geometry object: NULL on failure. 1036 1037 \sa gaiaCloneGeomColl, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, 1038 gaiaCastGeomCollToXYZM, gaiaCastGeomCollToXYMnoData 1039 1040 \note the newly created object is an exact copy of the original one; except 1041 in that any elementary item will be cast to 2D [XYM] dimensions. 1042 */ 1043 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYM (gaiaGeomCollPtr 1044 geom); 1045 1046 /** 1047 Duplicates a Geometry object [casting dimensions to 3D XYZM] 1048 1049 \param geom pointer to Geometry object [origin]. 1050 1051 \return the pointer to newly created Geometry object: NULL on failure. 1052 1053 \sa gaiaCloneGeomColl, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, 1054 gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZMnoData 1055 1056 \note the newly created object is an exact copy of the original one; except 1057 in that any elementary item will be cast to 3D [XYZM] dimensions. 1058 */ 1059 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYZM (gaiaGeomCollPtr 1060 geom); 1061 1062 /** 1063 Duplicates a Geometry object [casting dimensions to 3D XYZ - noData] 1064 1065 \param geom pointer to Geometry object [origin]. 1066 \param no_data the default Z value 1067 1068 \return the pointer to newly created Geometry object: NULL on failure. 1069 1070 \sa gaiaCostGeomCollToXYZ 1071 1072 \note the newly created object is an exact copy of the original one; except 1073 in that any elementary item will be cast to 3D [XYZ] dimensions. 1074 */ 1075 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYZnoData (gaiaGeomCollPtr 1076 geom, 1077 double 1078 no_data); 1079 1080 /** 1081 Duplicates a Geometry object [casting dimensions to 2D XYM - noData] 1082 1083 \param geom pointer to Geometry object [origin]. 1084 \param no_data the default M value 1085 1086 \return the pointer to newly created Geometry object: NULL on failure. 1087 1088 \sa gaiaCastGeomCollToXYM 1089 1090 \note the newly created object is an exact copy of the original one; except 1091 in that any elementary item will be cast to 2D [XYM] dimensions. 1092 */ 1093 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYMnoData (gaiaGeomCollPtr 1094 geom, 1095 double 1096 no_data); 1097 1098 /** 1099 Duplicates a Geometry object [casting dimensions to 3D XYZM - noData] 1100 1101 \param geom pointer to Geometry object [origin]. 1102 \param z_no_data the default Z value 1103 \param m_no_data the default M value 1104 1105 \return the pointer to newly created Geometry object: NULL on failure. 1106 1107 \sa gaiaCastGeomCollToXYZM 1108 1109 \note the newly created object is an exact copy of the original one; except 1110 in that any elementary item will be cast to 3D [XYZM] dimensions. 1111 */ 1112 GAIAGEO_DECLARE gaiaGeomCollPtr 1113 gaiaCastGeomCollToXYZMnoData (gaiaGeomCollPtr geom, double z_no_data, 1114 double m_no_data); 1115 1116 /** 1117 Gets coodinates from a Linestring's Point 1118 1119 \param ln pointer to Linestring object. 1120 \param v relative position of Point: first Point has index 0 1121 \param x on completion this variable will contain the Point X coordinate. 1122 \param y on completion this variable will contain the Point Y coordinate. 1123 \param z on completion this variable will contain the Point Z coordinate. 1124 \param m on completion this variable will contain the Point M measure. 1125 1126 \return 0 on failure: any other different value on success. 1127 1128 \sa gaiaLineSetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaGetPointXYM, 1129 gaiaGetPointXYZM 1130 1131 \note this function perform the same identical task performed by 1132 gaiaGetPoint(), gaiaGetPointXYZ(), gaiaGetPointXYM() and gaiaGetPointXYZM() 1133 macros. 1134 \n using the gaiaLineGetPoint() function is a little bit slower but is 1135 intrinsically safest, because misused macros can easily cause severe 1136 memory corruption. 1137 \n gaiaLineGetPoint() instead will always ensure that the appropriate 1138 dimensions (as declared by the Linestring object) will be correctly used. 1139 */ 1140 GAIAGEO_DECLARE int gaiaLineGetPoint (gaiaLinestringPtr ln, int v, 1141 double *x, double *y, double *z, 1142 double *m); 1143 1144 /** 1145 Sets coordinates for a Linestring's Point 1146 1147 \param ln pointer to Linestring object. 1148 \param v relative position of Point: first Point has index 0 1149 \param x the Point's X coordinate. 1150 \param y the Point's Y coordinate. 1151 \param z the Point's Z coordinate. 1152 \param m the Point's M measure. 1153 1154 \return 0 on failure: any other different value on success. 1155 1156 \sa gaiaLineGetPoint, gaiaSetPoint, gaiaSetPointXYZ, gaiaSetPointXYM, 1157 gaiaSetPointXYZM 1158 1159 \note this function perform the same identical task performed by 1160 gaiaSetPoint(), gaiaSetPointXYZ(), gaiaSetPointXYM() and gaiaSetPointXYZM() 1161 macros. 1162 \n using the gaiaLineSetPoint() function is a little bit slower but is 1163 intrinsically safest, because misused macros can easily cause severe 1164 memory corruption. 1165 \n gaiaLineSetPoint() instead will always ensure that the appropriate 1166 dimensions (as declared by the Linestring object) will be correctly used. 1167 */ 1168 GAIAGEO_DECLARE int gaiaLineSetPoint (gaiaLinestringPtr ln, int v, 1169 double x, double y, double z, 1170 double m); 1171 1172 /** 1173 Gets coordinates from a Ring's Point 1174 1175 \param rng pointer to Ring object. 1176 \param v relative position of Point: first Point has index 0 1177 \param x on completion this variable will contain the Point X coordinate. 1178 \param y on completion this variable will contain the Point Y coordinate. 1179 \param z on completion this variable will contain the Point Z coordinate. 1180 \param m on completion this variable will contain the Point M measure. 1181 1182 \return 0 on failure: any other different value on success. 1183 1184 \sa gaiaRingSetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaGetPointXYM, 1185 gaiaGetPointXYZM 1186 1187 \note this function perform the same identical task performed by 1188 gaiaGetPoint(), gaiaGetPointXYZ(), gaiaGetPointXYM() and gaiaGetPointXYZM() 1189 macros. 1190 \n using the gaiaRingGetPoint() function is a little bit slower but is 1191 intrinsically safest, because misused macros can easily cause severe 1192 memory corruption. 1193 \n gaiaRingGetPoint() instead will always ensure that the appropriate 1194 dimensions (as declared by the Ring object) will be correctly used. 1195 */ 1196 GAIAGEO_DECLARE int gaiaRingGetPoint (gaiaRingPtr rng, int v, double *x, 1197 double *y, double *z, double *m); 1198 1199 /** 1200 Sets coodinates for a Ring's Point 1201 1202 \param rng pointer to Ring object. 1203 \param v relative position of Point: first Point has index 0 1204 \param x the Point's X coordinate. 1205 \param y the Point's Y coordinate. 1206 \param z the Point's Z coordinate. 1207 \param m the Point's M measure. 1208 1209 \return 0 on failure: any other different value on success. 1210 1211 \sa gaiaRingGetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaSetPointXYM, 1212 gaiaSetPointXYZM 1213 1214 \note this function perform the same identical task performed by 1215 gaiaSetPoint(), gaiaSetPointXYZ(), gaiaSetPointXYM() and gaiaSetPointXYZM() 1216 macros. 1217 \n using the gaiaRingSetPoint() function is a little bit slower but is 1218 intrinsically safest, because misused macros can easily cause severe 1219 memory corruption. 1220 \n gaiaRingSetPoint() instead will always ensure that the appropriate 1221 dimensions (as declared by the Ring object) will be correctly used. 1222 */ 1223 GAIAGEO_DECLARE int gaiaRingSetPoint (gaiaRingPtr rng, int v, double x, 1224 double y, double z, double m); 1225 1226 /** 1227 Determines OGC dimensions for a Geometry object 1228 1229 \param geom pointer to Geometry object 1230 1231 \return OGC dimensions 1232 1233 \note OGC dimensions are defined as follows: 1234 \li if the Geometry doesn't contain any elementary item: \b -1 1235 \li if the Geometry only contains Point items: \b 0 1236 \li if the Geometry only contains Point / Linestring items: \b 1 1237 \li if the Geometry contains some Polygon item: \b 2 1238 */ 1239 GAIAGEO_DECLARE int gaiaDimension (gaiaGeomCollPtr geom); 1240 1241 /** 1242 Determines the corresponding Type for a Geometry object 1243 1244 \param geom pointer to Geometry object 1245 1246 \return the corresponding Geometry Type 1247 1248 \note Type is one of: GAIA_POINT, GAIA_LINESTRING, GAIA_POLYGON, 1249 GAIA_MULTIPOINT, GAIA_MULTILINESTRING, GAIA_MULTIPOLYGON, 1250 GAIA_GEOMETRYCOLLECTION, GAIA_POINTZ, GAIA_LINESTRINGZ, GAIA_POLYGONZ, 1251 GAIA_MULTIPOINTZ, GAIA_MULTILINESTRINGZ, GAIA_MULTIPOLYGONZ, 1252 GAIA_GEOMETRYCOLLECTIONZ, GAIA_POINTM, GAIA_LINESTRINGM, GAIA_POLYGONM, 1253 GAIA_MULTIPOINTM, GAIA_MULTILINESTRINGM, GAIA_MULTIPOLYGONM, 1254 GAIA_GEOMETRYCOLLECTIONM, GAIA_POINTZM, GAIA_LINESTRINGZM, GAIA_POLYGONZM, 1255 GAIA_MULTIPOINTZM, GAIA_MULTILINESTRINGZM, GAIA_MULTIPOLYGONZM, 1256 GAIA_GEOMETRYCOLLECTIONZM 1257 \n on failure GAIA_NONE will be returned. 1258 */ 1259 GAIAGEO_DECLARE int gaiaGeometryType (gaiaGeomCollPtr geom); 1260 1261 /** 1262 Determines the corresponding Type for a Geometry object 1263 1264 \param geom pointer to Geometry object 1265 1266 \return the corresponding Geometry Type 1267 1268 \sa gaiaGeometryType 1269 1270 \note Type is one of: GAIA_POINT, GAIA_LINESTRING, GAIA_POLYGON, 1271 GAIA_MULTIPOINT, GAIA_MULTILINESTRING, GAIA_MULTIPOLYGON, 1272 GAIA_GEOMETRYCOLLECTION 1273 \n on failure GAIA_NONE will be returned. 1274 1275 \remark deprecated function (used in earlier SpatiaLite versions). 1276 */ 1277 GAIAGEO_DECLARE int gaiaGeometryAliasType (gaiaGeomCollPtr geom); 1278 1279 /** 1280 Checks for empty Geometry object 1281 1282 \param geom pointer to Geometry object 1283 1284 \return 0 if the Geometry is empty: otherwise any other different value. 1285 1286 \note an empty Geometry is a Geometry not containing any elementary 1287 item: i.e. no Points, no Linestrings and no Polygons at all. 1288 */ 1289 GAIAGEO_DECLARE int gaiaIsEmpty (gaiaGeomCollPtr geom); 1290 1291 /** 1292 Checks for Clockwise Geometry object 1293 1294 \param geom pointer to Geometry object 1295 1296 \return 0 if the Geometry is not clockwise: otherwise any other different value. 1297 1298 \note a Clockwise Geometry contains no Polygons, or alternatively 1299 contains only Clockwise Polygons. 1300 A Clockwise Polygon has a Clockwise exterior ring and all interior rings 1301 are Counter-Clockwise. 1302 */ 1303 GAIAGEO_DECLARE int gaiaCheckClockwise (gaiaGeomCollPtr geom); 1304 1305 /** 1306 Checks for CounterClockwise Geometry object 1307 1308 \param geom pointer to Geometry object 1309 1310 \return 0 if the Geometry is not counter-clockwise: otherwise any other different value. 1311 1312 \note a CounterClockwise Geometry contains no Polygons, or alternatively 1313 contains only CounterClockwise Polygons. 1314 A CounterClockwise Polygon has a CounterClockwise exterior ring and all 1315 interior rings are Clockwise. 1316 */ 1317 GAIAGEO_DECLARE int gaiaCheckCounterClockwise (gaiaGeomCollPtr geom); 1318 1319 /** 1320 Checks for toxic Geometry object 1321 1322 \param geom pointer to Geometry object 1323 1324 \return 0 if the Geometry is not toxic: otherwise any other different value. 1325 1326 \sa gaiaIsToxic_r, gaiaSanitize 1327 1328 \note a \b toxic Geometry is a Geometry containing severely malformed 1329 Polygons: i.e. containing less than 4 Points. 1330 \n Or containing severely malformed Linestrings: i.e. containing less 1331 than 2 Points. 1332 \n Attempting to pass any toxic Geometry to GEOS supported functions 1333 will easily cause a crash.\n 1334 not reentrant and thread unsafe. 1335 */ 1336 GAIAGEO_DECLARE int gaiaIsToxic (gaiaGeomCollPtr geom); 1337 1338 /** 1339 Checks for toxic Geometry object 1340 1341 \param p_cache a memory pointer returned by spatialite_alloc_connection() 1342 \param geom pointer to Geometry object 1343 1344 \return 0 if the Geometry is not toxic: otherwise any other different value. 1345 1346 \sa gaiaIsToxic, gaiaSanitize 1347 1348 \note a \b toxic Geometry is a Geometry containing severely malformed 1349 Polygons: i.e. containing less than 4 Points. 1350 \n Or containing severely malformed Linestrings: i.e. containing less 1351 than 2 Points. 1352 \n Attempting to pass any toxic Geometry to GEOS supported functions 1353 will easily cause a crash.\n 1354 reentrant and thread-safe. 1355 */ 1356 GAIAGEO_DECLARE int gaiaIsToxic_r (const void *p_cache, 1357 gaiaGeomCollPtr geom); 1358 1359 /** 1360 Checks for not-closed Rings 1361 1362 \param ring pointer to Ring object 1363 1364 \return 0 if the Ring in unclosed: otherwise any other different value. 1365 1366 \sa gaiaIsNotClosedRing_r, gaiaIsToxic, gaiaIsNotClosedGeomColl 1367 1368 \note unclosed Rings cause GEOS supported functions to crash. 1369 \n SpatiaLite will always carefully check any Ring before passing it 1370 to GEOS, eventually silently inserting a further point required so 1371 to properly close the figure. 1372 \n This function allows to explicitly identify any unclosed Ring.\n 1373 not reentrant and thread unsafe. 1374 */ 1375 GAIAGEO_DECLARE int gaiaIsNotClosedRing (gaiaRingPtr ring); 1376 1377 /** 1378 Checks for not-closed Rings 1379 1380 \param p_cache a memory pointer returned by spatialite_alloc_connection() 1381 \param ring pointer to Ring object 1382 1383 \return 0 if the Ring in unclosed: otherwise any other different value. 1384 1385 \sa gaiaIsNotClosedRing, gaiaIsToxic, gaiaIsNotClosedGeomColl 1386 1387 \note unclosed Rings cause GEOS supported functions to crash. 1388 \n SpatiaLite will always carefully check any Ring before passing it 1389 to GEOS, eventually silently inserting a further point required so 1390 to properly close the figure. 1391 \n This function allows to explicitly identify any unclosed Ring.\n 1392 reentrant and thread-safe. 1393 */ 1394 GAIAGEO_DECLARE int gaiaIsNotClosedRing_r (const void *p_data, 1395 gaiaRingPtr ring); 1396 1397 /** 1398 Checks for not-closed Rings in a Geometry object 1399 1400 \param geom pointer to Geometry object 1401 1402 \return 0 if the Geometry has no unclosed Rings: otherwise any other different value. 1403 1404 \sa gaiaIsNotClosedGeomColl_r, gaiaIsToxic, gaiaIsNotClosedRing 1405 1406 \note This function allows to explicitly identify any Geometry containing 1407 at least one unclosed Ring.\n 1408 not reentrant and thread unsafe. 1409 */ 1410 GAIAGEO_DECLARE int gaiaIsNotClosedGeomColl (gaiaGeomCollPtr geom); 1411 1412 /** 1413 Checks for not-closed Rings in a Geometry object 1414 1415 \param p_cache a memory pointer returned by spatialite_alloc_connection() 1416 \param geom pointer to Geometry object 1417 1418 \return 0 if the Geometry has no unclosed Rings: otherwise any other different value. 1419 1420 \sa gaiaIsNotClosedGeomColl, gaiaIsToxic, gaiaIsNotClosedRing 1421 1422 \note This function allows to explicitly identify any Geometry containing 1423 at least one unclosed Ring.\n 1424 reentrant and thread-safe. 1425 */ 1426 GAIAGEO_DECLARE int gaiaIsNotClosedGeomColl_r (const void *p_data, 1427 gaiaGeomCollPtr geom); 1428 1429 /** 1430 Attempts to sanitize a possibly malformed Geometry object 1431 1432 \param org pointer to Geometry object. 1433 1434 \return the pointer to newly created Geometry: NULL on failure. 1435 1436 \sa gaiaIsToxic, gaiaEnsureClosedRings, gaiaRemoveRepeatedPoints 1437 1438 \note you are responsible to destroy (before or after) any allocated Geometry, 1439 this including any Geometry created by gaiaSanitize() 1440 \n the output Geometry will surely have: 1441 \li no repeated Points on Linestrings or Rings (i.e. consecutive Points 1442 sharing exactly the same coordinates): any repeated Point will be suppressed, 1443 simply leaving only the first occurrence. 1444 \li proper Ring closure: for sure any Ring will have exactly coinciding 1445 first and last Points. 1446 */ 1447 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaSanitize (gaiaGeomCollPtr org); 1448 1449 /** 1450 Attempts to sanitize a possibly malformed Geometry object 1451 1452 \param org pointer to Geometry object. 1453 1454 \return the pointer to newly created Geometry: NULL on failure. 1455 1456 \sa gaiaIsToxic, gaiaSanitize, gaiaRemoveRepeatedPoint 1457 1458 \note you are responsible to destroy (before or after) any allocated Geometry, 1459 this including any Geometry created by gaiaSanitize() 1460 \n the output Geometry will surely have proper Ring closure: for sure any 1461 Ring will have exactly coinciding first and last Points. 1462 */ 1463 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaEnsureClosedRings (gaiaGeomCollPtr org); 1464 1465 /** 1466 Attempts to sanitize a possibly malformed Geometry object 1467 1468 \param org pointer to Geometry object. 1469 \param tolerance 1470 1471 \return the pointer to newly created Geometry: NULL on failure. 1472 1473 \sa gaiaIsToxic, gaiaSanitizeGeometry, gaiaEnsureClosedRings 1474 1475 \note you are responsible to destroy (before or after) any allocated Geometry, 1476 this including any Geometry created by gaiaSanitize() 1477 \n the output Geometry will surely have no repeated Points on Linestrings or Rings 1478 or MultiPoints (i.e. consecutive Points sharing exactly the same coordinates or 1479 falling within the given tolerace): any repeated Point will be suppressed, 1480 simply leaving only the first occurrence. 1481 */ 1482 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaRemoveRepeatedPoints (gaiaGeomCollPtr 1483 org, 1484 double tolerance); 1485 1486 /** 1487 Attempts to resolve a (Multi)Linestring from a Geometry object 1488 1489 \param geom pointer to Geometry object. 1490 \param force_multi: 0 if the returned Geometry could represent a Linestring: 1491 any other value if casting to MultiLinestring is required unconditionally. 1492 1493 \return the pointer to newly created Geometry: NULL on failure. 1494 1495 \sa gaiaDissolveSegments, gaiaDissolvePoints 1496 1497 \note you are responsible to destroy (before or after) any allocated Geometry, 1498 this including any Geometry created by gaiaLinearize() 1499 \n the input Geometry is expected to contain Polygons only: then any Ring 1500 will be transformed into the corresponding Linestring. 1501 */ 1502 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaLinearize (gaiaGeomCollPtr geom, 1503 int force_multi); 1504 1505 /** 1506 Attempts to resolve a collection of Segments from a Geometry object 1507 1508 \param geom pointer to Geometry object. 1509 1510 \return the pointer to newly created Geometry: NULL on failure. 1511 1512 \sa gaiaLinearize, gaiaDissolvePoints 1513 1514 \note you are responsible to destroy (before or after) any allocated Geometry, 1515 this including any Geometry created by gaiaDissolveSegments() 1516 \n the input Geometry can be of any arbitrary type: 1517 \li any Point will be copied untouched. 1518 \li any Linestring will be dissolved into Segments. 1519 \li any Ring will be dissolved into Segments. 1520 */ 1521 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaDissolveSegments (gaiaGeomCollPtr geom); 1522 1523 /** 1524 Attempts to resolve a collection of Points from a Geometry object 1525 1526 \param geom pointer to Geometry object. 1527 1528 \return the pointer to newly created Geometry: NULL on failure. 1529 1530 \sa gaiaLinearize, gaiaDissolveSegments 1531 1532 \note you are responsible to destroy (before or after) any allocated Geometry, 1533 this including any Geometry created by gaiaDissolvePoints() 1534 \n the input Geometry can be of any arbitrary type: 1535 \li any Point will be copied untouched. 1536 \li any Linestring will be dissolved into sparse Points. 1537 \li any Ring will be dissolved into sparse Points. 1538 */ 1539 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaDissolvePoints (gaiaGeomCollPtr geom); 1540 1541 /** 1542 Extracts any Point from a Geometry object 1543 1544 \param geom pointer to Geometry object 1545 1546 \return the pointer to newly created Geometry: NULL on failure. 1547 1548 \sa gaiaExtractLinestringsFromGeomColl, 1549 gaiaExtractPolygonsFromGeomColl, gaiaCloneGeomColl 1550 1551 \note you are responsible to destroy (before or after) any allocated Geometry, 1552 this including any Geometry created by gaiaExtractPointsFromGeomColl() 1553 \n the newly created Geometry will contain any Point contained into the 1554 input Geometry. 1555 \n if the input Geometry doesn't contains any Point, then NULL will be returned. 1556 */ 1557 GAIAGEO_DECLARE gaiaGeomCollPtr 1558 gaiaExtractPointsFromGeomColl (gaiaGeomCollPtr geom); 1559 1560 /** 1561 Extracts any Linestring from a Geometry object 1562 1563 \param geom pointer to Geometry object 1564 1565 \return the pointer to newly created Geometry: NULL on failure. 1566 1567 \sa gaiaExtractPointsFromGeomColl, gaiaExtractPolygonsFromGeomColl, 1568 gaiaCloneGeomColl 1569 1570 \note you are responsible to destroy (before or after) any allocated Geometry, 1571 this including any Geometry created by gaiaExtractLinestringsFromGeomColl() 1572 \n the newly created Geometry will contain any Linestring contained into the 1573 input Geometry. 1574 \n if the input Geometry doesn't contains any Linestring, then NULL will be returned. 1575 */ 1576 GAIAGEO_DECLARE gaiaGeomCollPtr 1577 gaiaExtractLinestringsFromGeomColl (gaiaGeomCollPtr geom); 1578 1579 /** 1580 Extracts any Polygon from a Geometry object 1581 1582 \param geom pointer to Geometry object 1583 1584 \return the pointer to newly created Geometry: NULL on failure. 1585 1586 \sa gaiaExtractPointsFromGeomColl, gaiaExtractLinestringsFromGeomColl, 1587 gaiaCloneGeomColl 1588 1589 \note you are responsible to destroy (before or after) any allocated Geometry, 1590 this including any Geometry created by gaiaExtractPolygonsFromGeomColl() 1591 \n the newly created Geometry will contain any Polygon contained into the 1592 input Geometry. 1593 \n if the input Geometry doesn't contains any Polygon, then NULL will be returned. 1594 */ 1595 GAIAGEO_DECLARE gaiaGeomCollPtr 1596 gaiaExtractPolygonsFromGeomColl (gaiaGeomCollPtr geom); 1597 1598 /** 1599 Merges two Geometry objects into a single one 1600 1601 \param geom1 pointer to first Geometry object. 1602 \param geom2 pointer to second Geometry object. 1603 1604 \return the pointer to newly created Geometry: NULL on failure. 1605 1606 \sa gaiaMergeGeometries_r, gaiaCloneGeomColl 1607 1608 \note you are responsible to destroy (before or after) any allocated Geometry, 1609 this including any Geometry created by gaiaMergeGeometries() 1610 \n the newly created Geometry will contain any Point, Linestring and/or 1611 Polygon contained in both input Geometries.\n 1612 not reentrant and thread unsafe. 1613 */ 1614 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMergeGeometries (gaiaGeomCollPtr 1615 geom1, 1616 gaiaGeomCollPtr geom2); 1617 1618 /** 1619 Merges two Geometry objects into a single one 1620 1621 \param p_cache a memory pointer returned by spatialite_alloc_connection() 1622 \param geom1 pointer to first Geometry object. 1623 \param geom2 pointer to second Geometry object. 1624 1625 \return the pointer to newly created Geometry: NULL on failure. 1626 1627 \sa gaiaMergeGeometries, gaiaCloneGeomColl 1628 1629 \note you are responsible to destroy (before or after) any allocated Geometry, 1630 this including any Geometry created by gaiaMergeGeometries() 1631 \n the newly created Geometry will contain any Point, Linestring and/or 1632 Polygon contained in both input Geometries.\n 1633 reentrant and thread-safe. 1634 */ 1635 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMergeGeometries_r (const void 1636 *p_cache, 1637 gaiaGeomCollPtr 1638 geom1, 1639 gaiaGeomCollPtr 1640 geom2); 1641 1642 /** 1643 Will return a new GEOMETRY (supporting M) with measures linearly 1644 interpolated between the start and end points. 1645 1646 \param geom pointer to Geometry object of the Linestring or MultiLinestring type. 1647 \param m_start M start value 1648 \param m_end M end value 1649 1650 \return the pointer to newly created Geometry: NULL on failure. 1651 1652 \note you are responsible to destroy (before or after) any allocated Geometry, 1653 this including any Geometry created by gaiaAddMeasure() 1654 \n the newly created Geometry will contain Linestrings. 1655 \n if the input Geometry has no M dimension it will be added, otherwise 1656 it will overwritten. 1657 \n an eventual Z will be preserved unaffected. 1658 */ 1659 GAIAGEO_DECLARE gaiaGeomCollPtr 1660 gaiaAddMeasure (gaiaGeomCollPtr geom, double m_start, double m_end); 1661 1662 #ifndef OMIT_GEOS /* including GEOS */ 1663 /** 1664 Will interpolate the M-value for a LinestringM at the point closest to the 1665 given Point. 1666 1667 \param p_cache a memory pointer returned by spatialite_alloc_connection() 1668 \param line pointer to Geometry object of the Linestring type and supporting 1669 the M dimension. 1670 \param point pointer to Geometry object of the Point type. 1671 \param m_value on succesfull completion this variable will contain the 1672 interpolated M value 1673 1674 \return 0 on failure: any other value on success. 1675 */ 1676 GAIAGEO_DECLARE int 1677 gaiaInterpolatePoint (const void *p_cache, gaiaGeomCollPtr line, 1678 gaiaGeomCollPtr point, double *m_value); 1679 #endif /* end including GEOS */ 1680 1681 /** 1682 Return a GeometryCollection containing elements matching the specified range of measures 1683 1684 \param geom pointer to Geometry object 1685 \param m_start range of measures: start value 1686 \param m_end range of measures: end value 1687 1688 \return the pointer to newly created Geometry: NULL on failure. 1689 1690 \note you are responsible to destroy (before or after) any allocated Geometry, 1691 this including any Geometry created by gaiaLocateBetweenMeasures() 1692 \n the newly created Geometry will contain Points and/or Linestrings. 1693 \n if the input Geometry has no M dimension then NULL will be returned. 1694 \n if the input Geometry doesn't contains any point/vertex corresponding to the 1695 required range of measures then NULL will be returned. 1696 \n if the input Geometry contains any Polygon (or is a GeometryCollection) then 1697 NULL will be returned. 1698 */ 1699 GAIAGEO_DECLARE gaiaGeomCollPtr 1700 gaiaLocateBetweenMeasures (gaiaGeomCollPtr geom, double m_start, 1701 double m_end); 1702 1703 /** 1704 Checks if a Geometry object is valid Trajectory 1705 1706 \param geom pointer to Geometry object 1707 1708 \return 0 if false; any other value if true 1709 1710 \sa gaiaTrajectoryInterpolatePoint 1711 1712 \note a Geometry is considered to be a valid Trajectory if it contains 1713 a simple LINESTRING supporting M-values growing from each vertex to the next. 1714 */ 1715 GAIAGEO_DECLARE int gaiaIsValidTrajectory (gaiaGeomCollPtr geom); 1716 1717 /** 1718 Attempts to interpolate a Point along a Trajectory accordingly to given M-Value 1719 1720 \param geom pointer to Geometry object (expected to be a valid Trajectory) 1721 \param m the M-Value to be interpolated 1722 1723 \return the pointer to newly created Geometry object representing a Point 1724 laying on the input Geometry and positioned at the given M-Value 1725 NULL on failure. 1726 1727 \sa gaiaIsValidTrajectory, gaiaFreeGeomColl 1728 1729 \note you are responsible to destroy (before or after) any allocated Geometry, 1730 this including any Geometry returned by gaiaTrajectoryInterpolatePoint()\n 1731 not reentrant and thread unsafe. 1732 1733 \note a Geometry is considered to be a valid Trajectory if it contains 1734 a simple LINESTRING supporting M-values growing from each vertex to the next. 1735 */ 1736 GAIAGEO_DECLARE gaiaGeomCollPtr 1737 gaiaTrajectoryInterpolatePoint (gaiaGeomCollPtr geom, double m); 1738 1739 /** 1740 Measures the geometric length for a Linestring or Ring 1741 1742 \param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM 1743 \param coords pointed to COORD mem-array 1744 \param vert number of Points (aka Vertices) within the COORD mem-array 1745 1746 \return the calculated geometric length 1747 1748 \sa gaiaGeomCollLength 1749 1750 \note \b dims, \b coords and \b vert are usually expected to correspond to 1751 \b DimensionModel, \b Coords and \b Points members from a gaiaLinestringStruct 1752 or gaiaRingStruct 1753 1754 \remark internal method: doesn't require any GEOS support. 1755 */ 1756 GAIAGEO_DECLARE double gaiaMeasureLength (int dims, double *coords, 1757 int vert); 1758 1759 /** 1760 Measures the geometric area for a Ring object 1761 1762 \param ring pointer to Ring object 1763 1764 \return the calculated geometric area 1765 1766 \sa gaiaGeomCollArea 1767 1768 \remark internal method: doesn't require any GEOS support. 1769 */ 1770 GAIAGEO_DECLARE double gaiaMeasureArea (gaiaRingPtr ring); 1771 1772 /** 1773 Determines the Centroid for a Ring object 1774 1775 \param ring pointer to Ring object. 1776 \param rx on completion this variable will contain the centroid X coordinate. 1777 \param ry on completion this variable will contain the centroid Y coordinate. 1778 1779 \sa gaiaGeomCollCentroid 1780 1781 \remark internal method: doesn't require any GEOS support. 1782 */ 1783 GAIAGEO_DECLARE void gaiaRingCentroid (gaiaRingPtr ring, double *rx, 1784 double *ry); 1785 1786 /** 1787 Determines the direction for a Ring object 1788 1789 \param p pointer to Ring object 1790 1791 \return 0 if the ring has counter-clockwise direction; any other different 1792 value for clockwise direction. 1793 */ 1794 GAIAGEO_DECLARE void gaiaClockwise (gaiaRingPtr p); 1795 1796 /** 1797 Check if a Point lays on a Ring surface 1798 1799 \param ring pointer to Ring object 1800 \param pt_x Point X coordinate 1801 \param pt_y Point Y coordinate 1802 1803 \return 0 if false: any other value if true 1804 */ 1805 GAIAGEO_DECLARE int gaiaIsPointOnRingSurface (gaiaRingPtr ring, 1806 double pt_x, double pt_y); 1807 1808 /** 1809 Checks if a Point lays on a Polygon surface 1810 1811 \param polyg pointer to Polygon object 1812 \param x Point X coordinate 1813 \param y Point Y coordinate 1814 1815 \return 0 if false: any other value if true 1816 */ 1817 GAIAGEO_DECLARE int gaiaIsPointOnPolygonSurface (gaiaPolygonPtr polyg, 1818 double x, double y); 1819 1820 /** 1821 Computes the minimum distance between a Point and a Linestring or Ring 1822 1823 \param x0 Point X coordinate 1824 \param y0 Point Y coordinate 1825 \param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM 1826 \param coords pointed to COORD mem-array 1827 \param vert number of Points (aka Vertices) within the COORD mem-array 1828 1829 \return the calculated minumum distance. 1830 1831 \note \b dims, \b coords and \b vert are usually expected to correspond to 1832 \b DimensionModel, \b Coords and \b Points members from a gaiaLinestringStruct 1833 or gaiaRingStruct 1834 */ 1835 GAIAGEO_DECLARE double gaiaMinDistance (double x0, double y0, 1836 int dims, double *coords, int vert); 1837 1838 /** 1839 Determines the intesection Point between two Segments 1840 1841 \param x0 on completion this variable will contain the Intersection X coord 1842 \param y0 on completion this variable will contain the Intersection Y coord 1843 \param x1 start Point X of first Segment 1844 \param y1 start Point Y of first Segment 1845 \param x2 end Point X of first Segment 1846 \param y2 end Point Y of first Segment 1847 \param x3 start Point X of second Segment 1848 \param y3 start Point Y of second Segment 1849 \param x4 end Point X of second Segment 1850 \param y4 end Point Y of second Segment 1851 1852 \return 0 if the Segments doesn't intersect at all: any other value on 1853 success. 1854 */ 1855 GAIAGEO_DECLARE int gaiaIntersect (double *x0, double *y0, double x1, 1856 double y1, double x2, double y2, 1857 double x3, double y3, double x4, 1858 double y4); 1859 1860 /** 1861 Shifts any coordinate within a Geometry object 1862 1863 \param geom pointer to Geometry object. 1864 \param shift_x X axis shift factor. 1865 \param shift_y Y axis shift factor. 1866 1867 \sa gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords, 1868 gaiaShiftCoords3D, gaiaShiftLongitude 1869 */ 1870 GAIAGEO_DECLARE void gaiaShiftCoords (gaiaGeomCollPtr geom, 1871 double shift_x, double shift_y); 1872 1873 /** 1874 Shifts any coordinate within a 3D Geometry object 1875 1876 \param geom pointer to Geometry object. 1877 \param shift_x X axis shift factor. 1878 \param shift_y Y axis shift factor. 1879 \param shift_z Z axis shift factor. 1880 1881 \sa gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords, 1882 gaiaShiftCoords, gaiaShiftLongitude, gaiaNormalizeLonLat 1883 */ 1884 GAIAGEO_DECLARE void gaiaShiftCoords3D (gaiaGeomCollPtr geom, 1885 double shift_x, double shift_y, 1886 double shift_z); 1887 1888 /** 1889 Shifts negative longitudes 1890 1891 \param geom pointer to Geometry object. 1892 1893 \sa gaiaShiftCoords, gaiaShiftCoords3D, gaiaNormalizeLonLat 1894 1895 \note only intended for geographic (longitude/latitude) coordinates. 1896 Negative longitudes (-180/0) will be shifted by 360, thus allowing 1897 to represent longitudes in the 0/360 range and effectively crossing 1898 the International Date Line. 1899 1900 */ 1901 GAIAGEO_DECLARE void gaiaShiftLongitude (gaiaGeomCollPtr geom); 1902 1903 /** 1904 Shifts any coordinate to within the "normal range" of longitude and 1905 latitude values (-180.0 to 180.0 longitude and -90.0 to 90.0 latitude). 1906 1907 \param geom pointer to Geometry object. 1908 1909 \sa gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords, 1910 gaiaShiftCoords3D, gaiaShiftLongitude 1911 */ 1912 GAIAGEO_DECLARE void gaiaNormalizeLonLat (gaiaGeomCollPtr geom); 1913 1914 1915 /** 1916 Scales any coordinate within a Geometry object 1917 1918 \param geom pointer to Geometry object. 1919 \param scale_x X axis scale factor. 1920 \param scale_y Y axis scale factor. 1921 1922 \sa gaiaShiftCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords 1923 */ 1924 GAIAGEO_DECLARE void gaiaScaleCoords (gaiaGeomCollPtr geom, 1925 double scale_x, double scale_y); 1926 1927 /** 1928 Rotates any coordinate within a Geometry object 1929 1930 \param geom pointer to Geometry object. 1931 \param angle rotation angle [expressed in Degrees]. 1932 1933 \sa gaiaShiftCoords, gaiaScaleCoords, gaiaReflectCoords, gaiaSwapCoords 1934 */ 1935 GAIAGEO_DECLARE void gaiaRotateCoords (gaiaGeomCollPtr geom, double angle); 1936 1937 /** 1938 Reflects any coordinate within a Geometry object 1939 1940 \param geom pointer to Geometry object. 1941 \param x_axis if set to 0, no X axis reflection will be applied: 1942 otherwise the X axis will be reflected. 1943 \param y_axis if set to 0, no Y axis reflection will be applied: 1944 otherwise the Y axis will be reflected. 1945 1946 \sa gaiaShiftCoords, gaiaScaleCoords, gaiaRotateCoords, gaiaSwapCoords 1947 */ 1948 GAIAGEO_DECLARE void gaiaReflectCoords (gaiaGeomCollPtr geom, int x_axis, 1949 int y_axis); 1950 1951 /** 1952 Swaps any coordinate within a Geometry object 1953 1954 \param geom pointer to Geometry object. 1955 1956 \sa gaiaShiftCoords, gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords 1957 1958 \note the X and Y axes will be swapped. 1959 */ 1960 GAIAGEO_DECLARE void gaiaSwapCoords (gaiaGeomCollPtr geom); 1961 1962 /** 1963 Checks if two Linestring objects are equivalent 1964 1965 \param line1 pointer to first Linestring object. 1966 \param line2 pointer to second Linestring object. 1967 1968 \return 0 if false: any other different value if true 1969 1970 \sa gaiaPolygonEquals 1971 1972 \note two Linestrings objects are assumed to be equivalent if exactly 1973 \remark deprecated function (used in earlier SpatiaLite versions). 1974 the same Points are found in both them. 1975 */ 1976 GAIAGEO_DECLARE int gaiaLinestringEquals (gaiaLinestringPtr line1, 1977 gaiaLinestringPtr line2); 1978 1979 /** 1980 Checks if two Polygons objects are equivalent 1981 1982 \param polyg1 pointer to first Polygon object. 1983 \param polyg2 pointer to second Polygon object. 1984 1985 \return 0 if false: any other different value if true 1986 1987 \sa gaiaLinestringEquals 1988 1989 \note two Polygon objects are assumed to be equivalent if exactly 1990 the same Points are found in both them. 1991 1992 \remark deprecated function (used in earlier SpatiaLite versions). 1993 */ 1994 GAIAGEO_DECLARE int gaiaPolygonEquals (gaiaPolygonPtr polyg1, 1995 gaiaPolygonPtr polyg2); 1996 1997 /** 1998 Retrieves Geodesic params for an Ellipsoid definition 1999 2000 \param name text string identifying an Ellipsoid definition. 2001 \param a on completion this variable will contain the first geodesic param. 2002 \param b on completion this variable will contain the second geodesic param. 2003 \param rf on completion this variable will contain the third geodesic param. 2004 2005 \return 0 on failure: any other value on success. 2006 2007 \sa gaiaGreatCircleDistance, gaiaGeodesicDistance, 2008 gaiaGreatCircleTotalLength, gaiaGeodesicTotalLength 2009 2010 \note supported Ellipsoid definitions are: \b MERIT, \b SGS85, \b GRS80, 2011 \b IAU76, \b airy, \b APL4.9, \b NWL9D, \b mod_airy, \b andrae, \b aust_SA, 2012 \b GRS67, \b bessel, \b bess_nam, \b clrk66, \b clrk80, \b CPM, \b delmbr, 2013 \b engelis, \b evrst30, \b evrst48, \b evrst56, \b evrst69, \b evrstSS, 2014 \b fschr60 2015 */ 2016 GAIAGEO_DECLARE int gaiaEllipseParams (const char *name, double *a, 2017 double *b, double *rf); 2018 2019 /** 2020 Calculates the Great Circle Distance between between two Points 2021 2022 \param a first geodesic parameter. 2023 \param b second geodesic parameter. 2024 \param lat1 Latitude of first Point. 2025 \param lon1 Longitude of first Point. 2026 \param lat2 Latitude of second Point. 2027 \param lon2 Longitude of second Point. 2028 2029 \return the calculated Great Circle Distance. 2030 2031 \sa gaiaEllipseParams, gaiaGeodesicDistance, 2032 gaiaGreatCircleTotalLength, gaiaGeodesicTotalLength 2033 2034 \note the returned distance is expressed in Kilometers. 2035 \n the Great Circle method is less accurate but fastest to be calculated. 2036 */ 2037 GAIAGEO_DECLARE double gaiaGreatCircleDistance (double a, double b, 2038 double lat1, double lon1, 2039 double lat2, double lon2); 2040 2041 /** 2042 Calculates the Geodesic Distance between two Points 2043 2044 \param a first geodesic parameter. 2045 \param b second geodesic parameter. 2046 \param rf third geodesic parameter. 2047 \param lat1 Latitude of first Point. 2048 \param lon1 Longitude of first Point. 2049 \param lat2 Latitude of second Point. 2050 \param lon2 Longitude of second Point. 2051 2052 \return the calculated Geodesic Distance. 2053 2054 \sa gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGreatCircleTotalLength, 2055 gaiaGeodesicTotalLength, gaiaGeodesicArcLength 2056 2057 \note the returned distance is expressed in Kilometers. 2058 \n the Geodesic method is much more accurate but slowest to be calculated. 2059 */ 2060 GAIAGEO_DECLARE double gaiaGeodesicDistance (double a, double b, 2061 double rf, double lat1, 2062 double lon1, double lat2, 2063 double lon2); 2064 2065 /** 2066 Calculates the Great Circle Total Length for a Linestring / Ring 2067 2068 \param a first geodesic parameter. 2069 \param b second geodesic parameter. 2070 \param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM 2071 \param coords pointed to COORD mem-array 2072 \param vert number of Points (aka Vertices) within the COORD mem-array 2073 2074 \return the calculated Great Circle Total Length. 2075 2076 \sa gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGeodesicDistance, 2077 gaiaGeodesicTotalLength 2078 2079 \note the returned length is expressed in Kilometers. 2080 \n the Great Circle method is less accurate but fastest to be calculated. 2081 \n \b dims, \b coords and \b vert are usually expected to correspond to 2082 \b DimensionModel, \b Coords and \b Points members from a gaiaLinestringStruct 2083 or gaiaRingStruct 2084 */ 2085 GAIAGEO_DECLARE double gaiaGreatCircleTotalLength (double a, double b, 2086 int dims, 2087 double *coords, 2088 int vert); 2089 2090 /** 2091 Calculates the Geodesic Total Length for a Linestring / Ring 2092 2093 \param a first geodesic parameter. 2094 \param b second geodesic parameter. 2095 \param rf third geodesic parameter. 2096 \param dims dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM 2097 \param coords pointed to COORD mem-array 2098 \param vert number of Points (aka Vertices) within the COORD mem-array 2099 2100 \return the calculated Geodesic Total Length. 2101 2102 \sa gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGeodesicDistance, 2103 gaiaGreatCircleTotalLength, gaiaGeodesicArcLength 2104 2105 \note the returned length is expressed in Kilometers. 2106 \n the Geodesic method is much more accurate but slowest to be calculated. 2107 \n \b dims, \b coords and \b vert are usually expected to correspond to 2108 \b DimensionModel, \b Coords and \b Points members from a gaiaLinestringStruct 2109 or gaiaRingStruct. 2110 */ 2111 GAIAGEO_DECLARE double gaiaGeodesicTotalLength (double a, double b, 2112 double rf, int dims, 2113 double *coords, int vert); 2114 2115 /** 2116 Convert a Length from a Measure Unit to another 2117 2118 \param value the length measure to be converted. 2119 \param unit_from original Measure Unit. 2120 \param unit_to converted Measure Unit. 2121 \param cvt on completion this variable will contain the converted length 2122 measure. 2123 2124 \note supported Measu Units are: GAIA_KM, GAIA_M, GAIA_DM, GAIA_CM, GAIA_MM, 2125 GAIA_KMI, GAIA_IN, GAIA_FT, GAIA_YD, GAIA_MI, GAIA_FATH, GAIC_CH, GAIA_LINK, 2126 GAIA_US_IN, GAIA_US_FT, GAIA_US_YD, GAIA_US_CH, GAIA_US_MI, GAIA_IND_YD, 2127 GAIA_IND_FT, GAIA_IND_CH 2128 */ 2129 GAIAGEO_DECLARE int gaiaConvertLength (double value, int unit_from, 2130 int unit_to, double *cvt); 2131 2132 /** 2133 Computes several Geodesic values based on the Distance between two Geometries 2134 2135 \param db_handle handle to the current DB connection. 2136 \param cache the same memory pointer passed to the corresponding call to 2137 spatialite_init_ex() and returned by spatialite_alloc_connection() 2138 \param geom1 the first Geometry. 2139 \param geom2 the second Geometry. 2140 \param return_type selects wich value has be computed. 2141 Must be one between: GAIA_GEODESIC_ARC_LENGTH_METERS, 2142 GAIA_GEODESIC_ARC_LENGTH_DEGREES, GAIA_GEODESIC_CHORD_LENGTH_METERS, 2143 GAIA_GEODESIC_CHORD_LENGTH_DEGREES, GAIA_GEODESIC_CENTRAL_ANGLE_DEGREES, 2144 GAIA_GEODESIC_CENTRAL_ANGLE_RADIANS, GAIA_GEODESIC_ARC_AREA_METERS or 2145 GAIA_GEODESIC_ARC_HEIGHT_METERS. 2146 \param retval on completion this variable will contain the computed value. 2147 2148 \return 0 on failure: any other value on success. 2149 2150 \sa gaiaGeodesicDistance, gaiaGeodesicTotalLength 2151 2152 \note Both geom1 and geom2 must share the same SRID, that is expected 2153 to be of the Geographic type (longitudes and latitudes). 2154 \n Requires to be supported by a recent version of PROJ (>= 4.9.0). 2155 \n If not supported by GEOS only two POINT Geometries will be accepted. 2156 2157 */ 2158 GAIAGEO_DECLARE int gaiaGeodesicArcLength (sqlite3 * sqlite, 2159 const void *cache, 2160 gaiaGeomCollPtr geom1, 2161 gaiaGeomCollPtr geom2, 2162 int return_type, double *retval); 2163 2164 /** 2165 Creates a Circle (Linestring) Geometry 2166 2167 \param center_x center point X coordinate. 2168 \param center_y center point Y coordinate. 2169 \param radius the circle's radius. 2170 \param step angular distance (in degrees) between points on the circumference. 2171 2172 \sa gaiaMakeArc, gaiaMakeEllipse, gaiaMakeEllipticArc 2173 2174 \note simply a convenience method defaulting to gaiaMakeEllipse 2175 with both axes set to radius value 2176 */ 2177 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMakeCircle (double center_x, 2178 double center_y, 2179 double radius, double step); 2180 2181 /** 2182 Creates an Ellipse (Linestring) Geometry 2183 2184 \param center_x center point X coordinate. 2185 \param center_y center point Y coordinate. 2186 \param x_axis the ellipses's X axis. 2187 \param y_axis the ellipses's Y axis. 2188 \param step angular distance (in degrees) between points on the ellipse. 2189 2190 \sa gaiaMakeEllipticArc, gaiaMakeCircle, gaiaMakeArc 2191 */ 2192 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMakeEllipse (double center_x, 2193 double center_y, 2194 double x_axis, 2195 double y_axis, 2196 double step); 2197 2198 /** 2199 Creates a Circular Arc (Linestring) Geometry 2200 2201 \param center_x center point X coordinate. 2202 \param center_y center point Y coordinate. 2203 \param radius the circle's radius. 2204 \param start the start angle (in degrees). 2205 \param start the stop angle (in degrees). 2206 \param step angular distance (in degrees) between points on the circumference. 2207 2208 \sa gaiaMakeCircle, gaiaMakeEllipse, gaiaMakeEllipticArc 2209 2210 \note simply a convenience method defaulting to gaiaMakeEllipticArc 2211 with both axes set to radius value 2212 */ 2213 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMakeArc (double center_x, 2214 double center_y, 2215 double radius, double start, 2216 double stop, double step); 2217 2218 /** 2219 Creates an Elliptic Arc (Linestring) Geometry 2220 2221 \param center_x center point X coordinate. 2222 \param center_y center point Y coordinate. 2223 \param x_axis the ellipses's X axis. 2224 \param y_axis the ellipses's Y axis. 2225 \param start the start angle (in degrees). 2226 \param start the stop angle (in degrees). 2227 \param step angular distance (in degrees) between points on the ellipse. 2228 2229 \sa gaiaMakeCircle, gaiaMakeEllipse, gaiaMakeEllipticArc 2230 */ 2231 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMakeEllipticArc (double center_x, 2232 double center_y, 2233 double x_axis, 2234 double y_axis, 2235 double start, 2236 double stop, 2237 double step); 2238 2239 /** 2240 Creates a Polygon from closed Linestrings 2241 2242 \param exterior a closed Linestring assumed to represent the Exterior Ring. 2243 \param interiors one (or more than one) clsed Linestrings assumed to represent 2244 all Interior Rings (could be a Linstring or a MultiLinestring).\n 2245 NULL if there are no Interior Rings at all. 2246 2247 \sa gaiaPolygonize 2248 2249 \note this method will simply check if all the received Linestrings are 2250 closed, but it could possibly return an invalid Polygon if there is any 2251 topology inconsistency between the exterior and interior rings. 2252 You are responsible to destroy (before or after) any allocated Geometry, 2253 this including any Geometry returned by gaiaPolygonize()\n 2254 not reentrant and thread unsafe. 2255 */ 2256 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMakePolygon (gaiaGeomCollPtr exterior, 2257 gaiaGeomCollPtr interiors); 2258 2259 /** 2260 Computes the Curvosity Index for some Linestrings 2261 2262 \param p_cache a memory pointer returned by spatialite_alloc_connection() 2263 \param line a generic Linestring. 2264 \param extra_points number of points to be interpolated at regular 2265 distance into the reference line. 2266 2267 \return the calculated Curvosity Index (expected to be in the range between 0.0 and 1.0). 2268 */ 2269 GAIAGEO_DECLARE double gaiaCurvosityIndex (const void *p_cache, 2270 gaiaLinestringPtr line, 2271 int extra_points); 2272 2273 /** 2274 Computes the Uphill and Downhill total Height for some 3D Linestrings 2275 2276 \param line a generic Linestring. 2277 \param up on completion this variable will contain the total Uphill Height.\n 2278 Will always be ZERO for any 2D Linestring. 2279 \param down on completion this variable will contain the total Downhill Height.\n 2280 Will always be ZERO for any 2D Linestring. 2281 2282 */ 2283 GAIAGEO_DECLARE void gaiaUpDownHeight (gaiaLinestringPtr line, double *up, 2284 double *down); 2285 2286 #ifdef _WIN32 2287 GAIAGEO_DECLARE FILE * gaia_win_fopen(const char *path, const char *mode); 2288 #endif 2289 2290 #ifdef __cplusplus 2291 } 2292 #endif 2293 2294 #endif /* _GG_CORE_H */ 2295