GEOS: geos_c.h Source File

00001 /************************************************************************
00002  *
00003  * $Id: geos_c.h.in 2144 2008-07-31 17:01:15Z mloskot $
00004  *
00005  * C-Wrapper for GEOS library
00006  *
00007  * Copyright (C) 2005 Refractions Research Inc.
00008  *
00009  * This is free software; you can redistribute and/or modify it under
00010  * the terms of the GNU Lesser General Public Licence as published
00011  * by the Free Software Foundation. 
00012  * See the COPYING file for more information.
00013  *
00014  * Author: Sandro Santilli <strk@refractions.net>
00015  *
00016  ***********************************************************************
00017  *
00018  * GENERAL NOTES:
00019  *
00020  *      - Remember to call initGEOS() before any use of this library's
00021  *        functions, and call finishGEOS() when done.
00022  *
00023  *      - Currently you have to explicitly GEOSGeom_destroy() all
00024  *        GEOSGeom objects to avoid memory leaks, and to free()
00025  *        all returned char * (unless const). This might change
00026  *        before first release to ensure greater API stability.
00027  *
00028  ***********************************************************************/
00029 
00030 #ifndef GEOS_C_H_INCLUDED
00031 #define GEOS_C_H_INCLUDED
00032 
00033 #ifndef __cplusplus
00034 # include <stddef.h> /* for size_t definition */
00035 #endif
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 /************************************************************************
00042  *
00043  * Version
00044  *
00045  ***********************************************************************/
00046 
00047 /*
00048  * Following 'ifdef' hack fixes problem with generating geos_c.h on Windows,
00049  * when building with Visual C++ compiler.
00050  */
00051 #if defined(_MSC_VER)
00052 #include <geos/version.h>
00053 #define GEOS_CAPI_VERSION_MAJOR 1
00054 #define GEOS_CAPI_VERSION_MINOR 5
00055 #define GEOS_CAPI_VERSION_PATCH 0
00056 #define GEOS_CAPI_VERSION "3.1.0-CAPI-1.5.0"
00057 #else
00058 #ifndef GEOS_VERSION_MAJOR
00059 #define GEOS_VERSION_MAJOR 3
00060 #endif
00061 #ifndef GEOS_VERSION_MINOR
00062 #define GEOS_VERSION_MINOR 1
00063 #endif
00064 #ifndef GEOS_VERSION_PATCH
00065 #define GEOS_VERSION_PATCH 0
00066 #endif
00067 #ifndef GEOS_VERSION
00068 #define GEOS_VERSION "3.1.0"
00069 #endif
00070 #ifndef GEOS_JTS_PORT
00071 #define GEOS_JTS_PORT "1.7.1"
00072 #endif
00073 
00074 #define GEOS_CAPI_VERSION_MAJOR 1
00075 #define GEOS_CAPI_VERSION_MINOR 5
00076 #define GEOS_CAPI_VERSION_PATCH 0
00077 #define GEOS_CAPI_VERSION "3.1.0-CAPI-1.5.0"
00078 #endif 
00079 
00080 #define GEOS_CAPI_FIRST_INTERFACE GEOS_CAPI_VERSION_MAJOR 
00081 #define GEOS_CAPI_LAST_INTERFACE (GEOS_CAPI_VERSION_MAJOR+GEOS_CAPI_VERSION_MINOR)
00082  
00083 /************************************************************************
00084  *
00085  * (Abstract) type definitions
00086  *
00087  ***********************************************************************/
00088 
00089 typedef void (*GEOSMessageHandler)(const char *fmt, ...);
00090 
00091 /* When we're included by geos_c.cpp, those are #defined to the original
00092  * JTS definitions via preprocessor. We don't touch them to allow the
00093  * compiler to cross-check the declarations. However, for all "normal" 
00094  * C-API users, we need to define them as "opaque" struct pointers, as 
00095  * those clients don't have access to the original C++ headers, by design.
00096  */
00097 #ifndef GEOSGeometry
00098 typedef struct GEOSGeom_t GEOSGeometry;
00099 typedef struct GEOSPrepGeom_t GEOSPreparedGeometry;
00100 typedef struct GEOSCoordSeq_t GEOSCoordSequence;
00101 #endif
00102 
00103 /* Those are compatibility definitions for source compatibility
00104  * with GEOS 2.X clients relying on that type.
00105  */
00106 typedef GEOSGeometry* GEOSGeom;
00107 typedef GEOSCoordSequence* GEOSCoordSeq;
00108 
00109 /* Supported geometry types
00110  * This was renamed from GEOSGeomTypeId in GEOS 2.2.X, which might
00111  * break compatibility, this issue is still under investigation.
00112  */
00113 
00114 enum GEOSGeomTypes {
00115         GEOS_POINT,
00116         GEOS_LINESTRING,
00117         GEOS_LINEARRING,
00118         GEOS_POLYGON,
00119         GEOS_MULTIPOINT,
00120         GEOS_MULTILINESTRING,
00121         GEOS_MULTIPOLYGON,
00122         GEOS_GEOMETRYCOLLECTION
00123 };
00124 
00125 /* Byte oders exposed via the c api */
00126 enum GEOSByteOrders {
00127         GEOS_WKB_XDR = 0, /* Big Endian */
00128         GEOS_WKB_NDR = 1 /* Little Endian */
00129 };
00130 
00131 
00132 /************************************************************************
00133  *
00134  * Initialization, cleanup, version
00135  *
00136  ***********************************************************************/
00137 
00138 #if defined(_MSC_VER)
00139 #  define GEOS_DLL     __declspec(dllexport)
00140 #else
00141 #  define GEOS_DLL
00142 #endif
00143 
00144 extern void GEOS_DLL initGEOS(GEOSMessageHandler notice_function,
00145         GEOSMessageHandler error_function);
00146 extern void GEOS_DLL finishGEOS(void);
00147 extern const char GEOS_DLL *GEOSversion();
00148 
00149 
00150 /************************************************************************
00151  *
00152  * NOTE - These functions are DEPRECATED.  Please use the new Reader and
00153  * writer APIS!
00154  *
00155  ***********************************************************************/
00156 
00157 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKT(const char *wkt);
00158 extern char GEOS_DLL *GEOSGeomToWKT(const GEOSGeometry* g);
00159 
00160 /*
00161  * Specify whether output WKB should be 2d or 3d.
00162  * Return previously set number of dimensions.
00163  */
00164 extern int GEOS_DLL GEOS_getWKBOutputDims();
00165 extern int GEOS_DLL GEOS_setWKBOutputDims(int newDims);
00166 
00167 /*
00168  * Specify whether the WKB byte order is big or little endian. 
00169  * The return value is the previous byte order.
00170  */
00171 extern int GEOS_DLL GEOS_getWKBByteOrder();
00172 extern int GEOS_DLL GEOS_setWKBByteOrder(int byteOrder);
00173 
00174 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKB_buf(const unsigned char *wkb, size_t size);
00175 extern unsigned char GEOS_DLL *GEOSGeomToWKB_buf(const GEOSGeometry* g, size_t *size);
00176 
00177 extern GEOSGeometry GEOS_DLL *GEOSGeomFromHEX_buf(const unsigned char *hex, size_t size);
00178 extern unsigned char GEOS_DLL *GEOSGeomToHEX_buf(const GEOSGeometry* g, size_t *size);
00179 
00180 /************************************************************************
00181  *
00182  * Coordinate Sequence functions
00183  *
00184  ***********************************************************************/
00185 
00186 /*
00187  * Create a Coordinate sequence with ``size'' coordinates
00188  * of ``dims'' dimensions.
00189  * Return NULL on exception.
00190  */
00191 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_create(unsigned int size, unsigned int dims);
00192 
00193 /*
00194  * Clone a Coordinate Sequence.
00195  * Return NULL on exception.
00196  */
00197 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_clone(const GEOSCoordSequence* s);
00198 
00199 /*
00200  * Destroy a Coordinate Sequence.
00201  */
00202 extern void GEOS_DLL GEOSCoordSeq_destroy(GEOSCoordSequence* s);
00203 
00204 /*
00205  * Set ordinate values in a Coordinate Sequence.
00206  * Return 0 on exception.
00207  */
00208 extern int GEOS_DLL GEOSCoordSeq_setX(GEOSCoordSequence* s,
00209         unsigned int idx, double val);
00210 extern int GEOS_DLL GEOSCoordSeq_setY(GEOSCoordSequence* s,
00211         unsigned int idx, double val);
00212 extern int GEOS_DLL GEOSCoordSeq_setZ(GEOSCoordSequence* s,
00213         unsigned int idx, double val);
00214 extern int GEOS_DLL GEOSCoordSeq_setOrdinate(GEOSCoordSequence* s,
00215         unsigned int idx, unsigned int dim, double val);
00216 
00217 /*
00218  * Get ordinate values from a Coordinate Sequence.
00219  * Return 0 on exception.
00220  */
00221 extern int GEOS_DLL GEOSCoordSeq_getX(const GEOSCoordSequence* s,
00222         unsigned int idx, double *val);
00223 extern int GEOS_DLL GEOSCoordSeq_getY(const GEOSCoordSequence* s,
00224         unsigned int idx, double *val);
00225 extern int GEOS_DLL GEOSCoordSeq_getZ(const GEOSCoordSequence* s,
00226         unsigned int idx, double *val);
00227 extern int GEOS_DLL GEOSCoordSeq_getOrdinate(const GEOSCoordSequence* s,
00228         unsigned int idx, unsigned int dim, double *val);
00229 
00230 /*
00231  * Get size and dimensions info from a Coordinate Sequence.
00232  * Return 0 on exception.
00233  */
00234 extern int GEOS_DLL GEOSCoordSeq_getSize(const GEOSCoordSequence* s,
00235         unsigned int *size);
00236 extern int GEOS_DLL GEOSCoordSeq_getDimensions(const GEOSCoordSequence* s,
00237         unsigned int *dims);
00238 
00239 
00240 /************************************************************************
00241  *
00242  * Geometry Constructors.
00243  * GEOSCoordSequence* arguments will become ownership of the returned object.
00244  * All functions return NULL on exception.
00245  *
00246  ***********************************************************************/
00247 
00248 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint(GEOSCoordSequence* s);
00249 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing(GEOSCoordSequence* s);
00250 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString(GEOSCoordSequence* s);
00251 
00252 /*
00253  * Second argument is an array of GEOSGeometry* objects.
00254  * The caller remains owner of the array, but pointed-to
00255  * objects become ownership of the returned GEOSGeometry.
00256  */
00257 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPolygon(GEOSGeometry* shell,
00258         GEOSGeometry** holes, unsigned int nholes);
00259 extern GEOSGeometry GEOS_DLL *GEOSGeom_createCollection(int type,
00260         GEOSGeometry* *geoms, unsigned int ngeoms);
00261 
00262 extern GEOSGeometry GEOS_DLL *GEOSGeom_clone(const GEOSGeometry* g);
00263 
00264 /************************************************************************
00265  *
00266  * Memory management
00267  *
00268  ***********************************************************************/
00269 
00270 extern void GEOS_DLL GEOSGeom_destroy(GEOSGeometry* g);
00271 
00272 
00273 /************************************************************************
00274  *
00275  * Topology operations - return NULL on exception.
00276  *
00277  ***********************************************************************/
00278 
00279 extern GEOSGeometry GEOS_DLL *GEOSEnvelope(const GEOSGeometry* g1);
00280 extern GEOSGeometry GEOS_DLL *GEOSIntersection(const GEOSGeometry* g1, const GEOSGeometry* g2);
00281 extern GEOSGeometry GEOS_DLL *GEOSBuffer(const GEOSGeometry* g1,
00282         double width, int quadsegs);
00283 extern GEOSGeometry GEOS_DLL *GEOSConvexHull(const GEOSGeometry* g1);
00284 extern GEOSGeometry GEOS_DLL *GEOSDifference(const GEOSGeometry* g1, const GEOSGeometry* g2);
00285 extern GEOSGeometry GEOS_DLL *GEOSSymDifference(const GEOSGeometry* g1,
00286         const GEOSGeometry* g2);
00287 extern GEOSGeometry GEOS_DLL *GEOSBoundary(const GEOSGeometry* g1);
00288 extern GEOSGeometry GEOS_DLL *GEOSUnion(const GEOSGeometry* g1, const GEOSGeometry* g2);
00289 extern GEOSGeometry GEOS_DLL *GEOSPointOnSurface(const GEOSGeometry* g1);
00290 extern GEOSGeometry GEOS_DLL *GEOSGetCentroid(const GEOSGeometry* g);
00291 extern char GEOS_DLL *GEOSRelate(const GEOSGeometry* g1, const GEOSGeometry* g2);
00292 
00293 /*
00294  * all arguments remain ownership of the caller
00295  * (both Geometries and pointers)
00296  */
00297 extern GEOSGeometry GEOS_DLL *GEOSPolygonize(const GEOSGeometry * const geoms[], unsigned int ngeoms);
00298 extern GEOSGeometry GEOS_DLL *GEOSPolygonizer_getCutEdges(const GEOSGeometry * const geoms[], unsigned int ngeoms);
00299 
00300 extern GEOSGeometry GEOS_DLL *GEOSLineMerge(const GEOSGeometry* g);
00301 extern GEOSGeometry GEOS_DLL *GEOSSimplify(const GEOSGeometry* g1, double tolerance);
00302 extern GEOSGeometry GEOS_DLL *GEOSTopologyPreserveSimplify(const GEOSGeometry* g1,
00303         double tolerance);
00304 
00305 /************************************************************************
00306  *
00307  *  Binary predicates - return 2 on exception, 1 on true, 0 on false
00308  *
00309  ***********************************************************************/
00310 
00311 extern char GEOS_DLL GEOSRelatePattern(const GEOSGeometry* g1, const GEOSGeometry* g2,
00312         const char *pat);
00313 extern char GEOS_DLL GEOSDisjoint(const GEOSGeometry* g1, const GEOSGeometry* g2);
00314 extern char GEOS_DLL GEOSTouches(const GEOSGeometry* g1, const GEOSGeometry* g2);
00315 extern char GEOS_DLL GEOSIntersects(const GEOSGeometry* g1, const GEOSGeometry* g2);
00316 extern char GEOS_DLL GEOSCrosses(const GEOSGeometry* g1, const GEOSGeometry* g2);
00317 extern char GEOS_DLL GEOSWithin(const GEOSGeometry* g1, const GEOSGeometry* g2);
00318 extern char GEOS_DLL GEOSContains(const GEOSGeometry* g1, const GEOSGeometry* g2);
00319 extern char GEOS_DLL GEOSOverlaps(const GEOSGeometry* g1, const GEOSGeometry* g2);
00320 extern char GEOS_DLL GEOSEquals(const GEOSGeometry* g1, const GEOSGeometry* g2);
00321 extern char GEOS_DLL GEOSEqualsExact(const GEOSGeometry* g1, const GEOSGeometry* g2, double tolerance);
00322 
00323 
00324 /************************************************************************
00325  *
00326  *  Prepared Geometry Binary predicates - return 2 on exception, 1 on true, 0 on false
00327  *
00328  ***********************************************************************/
00329 
00330 /* 
00331  * Argument ownership is taken by prepared geometry
00332  */
00333 extern const GEOSPreparedGeometry GEOS_DLL *GEOSPrepare(const GEOSGeometry* g);
00334 
00335 extern void GEOS_DLL GEOSPreparedGeom_destroy(GEOSPreparedGeometry* g);
00336 
00337 extern char GEOS_DLL GEOSPreparedContains(const GEOSPreparedGeometry* pg1, const GEOSGeometry* g2);
00338 extern char GEOS_DLL GEOSPreparedContainsProperly(const GEOSPreparedGeometry* pg1, const GEOSGeometry* g2);
00339 extern char GEOS_DLL GEOSPreparedCovers(const GEOSPreparedGeometry* pg1, const GEOSGeometry* g2);
00340 extern char GEOS_DLL GEOSPreparedIntersects(const GEOSPreparedGeometry* pg1, const GEOSGeometry* g2);
00341 
00342 
00343 /************************************************************************
00344  *
00345  *  Unary predicate - return 2 on exception, 1 on true, 0 on false
00346  *
00347  ***********************************************************************/
00348 
00349 extern char GEOS_DLL GEOSisEmpty(const GEOSGeometry* g1);
00350 extern char GEOS_DLL GEOSisValid(const GEOSGeometry* g1);
00351 extern char GEOS_DLL GEOSisSimple(const GEOSGeometry* g1);
00352 extern char GEOS_DLL GEOSisRing(const GEOSGeometry* g1);
00353 extern char GEOS_DLL GEOSHasZ(const GEOSGeometry* g1);
00354 
00355 
00356 /************************************************************************
00357  *
00358  *  Geometry info
00359  *
00360  ***********************************************************************/
00361 
00362 /* Return NULL on exception, result must be freed by caller. */
00363 extern char GEOS_DLL *GEOSGeomType(const GEOSGeometry* g1);
00364 
00365 /* Return -1 on exception */
00366 extern int GEOS_DLL GEOSGeomTypeId(const GEOSGeometry* g1);
00367 
00368 /* Return 0 on exception */
00369 extern int GEOS_DLL GEOSGetSRID(const GEOSGeometry* g1);
00370 
00371 extern void GEOS_DLL GEOSSetSRID(GEOSGeometry* g, int SRID);
00372 
00373 /* May be called on all geometries in GEOS 3.x, returns -1 on error and 1
00374  * for non-multi geometries. Older GEOS versions only accept 
00375  * GeometryCollections or Multi* geometries here, and are likely to crash
00376  * when feeded simple geometries, so beware if you need compatibility with
00377  * old GEOS versions.
00378  */
00379 extern int GEOS_DLL GEOSGetNumGeometries(const GEOSGeometry* g1);
00380 
00381 /*
00382  * Return NULL on exception, Geometry must be a Collection.
00383  * Returned object is a pointer to internal storage:
00384  * it must NOT be destroyed directly.
00385  */
00386 extern const GEOSGeometry GEOS_DLL *GEOSGetGeometryN(const GEOSGeometry* g, int n);
00387 
00388 /* Return -1 on exception */
00389 extern int GEOS_DLL GEOSNormalize(GEOSGeometry* g1);
00390 
00391 /* Return -1 on exception */
00392 extern int GEOS_DLL GEOSGetNumInteriorRings(const GEOSGeometry* g1);
00393 
00394 /*
00395  * Return NULL on exception, Geometry must be a Polygon.
00396  * Returned object is a pointer to internal storage:
00397  * it must NOT be destroyed directly.
00398  */
00399 extern const GEOSGeometry GEOS_DLL *GEOSGetInteriorRingN(const GEOSGeometry* g, int n);
00400 
00401 /*
00402  * Return NULL on exception, Geometry must be a Polygon.
00403  * Returned object is a pointer to internal storage:
00404  * it must NOT be destroyed directly.
00405  */
00406 extern const GEOSGeometry GEOS_DLL *GEOSGetExteriorRing(const GEOSGeometry* g);
00407 
00408 /* Return -1 on exception */
00409 extern int GEOS_DLL GEOSGetNumCoordinates(const GEOSGeometry* g1);
00410 
00411 /*
00412  * Return NULL on exception.
00413  * Geometry must be a LineString, LinearRing or Point.
00414  */
00415 extern const GEOSCoordSequence GEOS_DLL *GEOSGeom_getCoordSeq(const GEOSGeometry* g);
00416 
00417 /*
00418  * Return 0 on exception (or empty geometry)
00419  */
00420 extern int GEOS_DLL GEOSGeom_getDimensions(const GEOSGeometry* g);
00421 
00422 /************************************************************************
00423  *
00424  *  Misc functions 
00425  *
00426  ***********************************************************************/
00427 
00428 /* Return 0 on exception, 1 otherwise */
00429 extern int GEOS_DLL GEOSArea(const GEOSGeometry* g1, double *area);
00430 extern int GEOS_DLL GEOSLength(const GEOSGeometry* g1, double *length);
00431 extern int GEOS_DLL GEOSDistance(const GEOSGeometry* g1, const GEOSGeometry* g2,
00432         double *dist);
00433 
00434 
00435 
00436 /************************************************************************
00437  *
00438  * Reader and Writer APIs
00439  *
00440  ***********************************************************************/
00441 
00442 typedef struct GEOSWKTReader_t GEOSWKTReader;
00443 typedef struct GEOSWKTWriter_t GEOSWKTWriter;
00444 typedef struct GEOSWKBReader_t GEOSWKBReader;
00445 typedef struct GEOSWKBWriter_t GEOSWKBWriter;
00446 
00447 
00448 /* WKT Reader */
00449 extern GEOSWKTReader GEOS_DLL *GEOSWKTReader_create();
00450 extern void GEOS_DLL GEOSWKTReader_destroy(GEOSWKTReader* reader);
00451 extern GEOSGeometry GEOS_DLL *GEOSWKTReader_read(GEOSWKTReader* reader, const char *wkt);
00452 
00453 /* WKT Writer */
00454 extern GEOSWKTWriter GEOS_DLL *GEOSWKTWriter_create();
00455 extern void GEOS_DLL GEOSWKTWriter_destroy(GEOSWKTWriter* writer);
00456 extern char GEOS_DLL *GEOSWKTWriter_write(GEOSWKTWriter* reader, const GEOSGeometry* g);
00457 
00458 /* WKB Reader */
00459 extern GEOSWKBReader GEOS_DLL *GEOSWKBReader_create();
00460 extern void GEOS_DLL GEOSWKBReader_destroy(GEOSWKBReader* reader);
00461 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_read(GEOSWKBReader* reader, const unsigned char *wkb, size_t size);
00462 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_readHEX(GEOSWKBReader* reader, const unsigned char *hex, size_t size);
00463 
00464 /* WKB Writer */
00465 extern GEOSWKBWriter GEOS_DLL *GEOSWKBWriter_create();
00466 extern void GEOS_DLL GEOSWKBWriter_destroy(GEOSWKBWriter* writer);
00467 
00468 /* The owner owns the results for these two methods! */
00469 extern unsigned char GEOS_DLL *GEOSWKBWriter_write(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
00470 extern unsigned char GEOS_DLL *GEOSWKBWriter_writeHEX(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
00471 
00472 /* 
00473  * Specify whether output WKB should be 2d or 3d.
00474  * Return previously set number of dimensions.
00475  */
00476 extern int GEOS_DLL GEOSWKBWriter_getOutputDimension(const GEOSWKBWriter* writer);
00477 extern void GEOS_DLL GEOSWKBWriter_setOutputDimension(GEOSWKBWriter* writer, int newDimension);
00478 
00479 /*
00480  * Specify whether the WKB byte order is big or little endian. 
00481  * The return value is the previous byte order.
00482  */
00483 extern int GEOS_DLL GEOSWKBWriter_getByteOrder(const GEOSWKBWriter* writer);
00484 extern void GEOS_DLL GEOSWKBWriter_setByteOrder(GEOSWKBWriter* writer, int byteOrder);
00485 
00486 /*
00487  * Specify whether SRID values should be output. 
00488  */
00489 extern char GEOS_DLL GEOSWKBWriter_getIncludeSRID(const GEOSWKBWriter* writer);
00490 extern void GEOS_DLL GEOSWKBWriter_setIncludeSRID(GEOSWKBWriter* writer, const char writeSRID);
00491 
00492 
00493 
00494 
00495 #ifdef __cplusplus
00496 } // extern "C"
00497 #endif
00498 
00499 #endif /* #ifndef GEOS_C_H_INCLUDED */