Geometry handling functions: core. More...

This graph shows which files directly or indirectly include this file:

Functions
GAIAGEO_DECLARE void	gaiaFree (void *ptr)
	Safely frees any dynamic memory block allocated by the library itself.
GAIAGEO_DECLARE gaiaPointPtr	gaiaAllocPoint (double x, double y)
	Allocates a 2D POINT [XY].
GAIAGEO_DECLARE gaiaPointPtr	gaiaAllocPointXYZ (double x, double y, double z)
	Allocates a 3D POINT [XYZ].
GAIAGEO_DECLARE gaiaPointPtr	gaiaAllocPointXYM (double x, double y, double m)
	Allocates a 2D POINT [XYM].
GAIAGEO_DECLARE gaiaPointPtr	gaiaAllocPointXYZM (double x, double y, double z, double m)
	Allocates a 3D POINT [XYZM].
GAIAGEO_DECLARE void	gaiaFreePoint (gaiaPointPtr ptr)
	Destroys a POINT object.
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaAllocLinestring (int vert)
	Allocates a 2D LINESTRING [XY].
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaAllocLinestringXYZ (int vert)
	Allocates a 3D LINESTRING [XYZ].
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaAllocLinestringXYM (int vert)
	Allocates a 2D LINESTRING [XYM].
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaAllocLinestringXYZM (int vert)
	Allocates a 3D LINESTRING [XYZM].
GAIAGEO_DECLARE void	gaiaFreeLinestring (gaiaLinestringPtr ptr)
	Destroys a LINESTRING object.
GAIAGEO_DECLARE void	gaiaCopyLinestringCoords (gaiaLinestringPtr dst, gaiaLinestringPtr src)
	Copies coordinates between two LINESTRING objects.
GAIAGEO_DECLARE gaiaRingPtr	gaiaAllocRing (int vert)
	Allocates a 2D RING [XY].
GAIAGEO_DECLARE gaiaRingPtr	gaiaAllocRingXYZ (int vert)
	Allocates a 3D RING [XYZ].
GAIAGEO_DECLARE gaiaRingPtr	gaiaAllocRingXYM (int vert)
	Allocates 2D RING [XYM].
GAIAGEO_DECLARE gaiaRingPtr	gaiaAllocRingXYZM (int vert)
	Allocates a 3D RING [XYZM].
GAIAGEO_DECLARE void	gaiaFreeRing (gaiaRingPtr ptr)
	Destroys a RING object.
GAIAGEO_DECLARE void	gaiaCopyRingCoords (gaiaRingPtr dst, gaiaRingPtr src)
	Copies coordinates betwee two RING objects.
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaAllocPolygon (int vert, int holes)
	Allocates a 2D POLYGON [XY].
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaAllocPolygonXYZ (int vert, int holes)
	Allocates a 3D POLYGON [XYZ].
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaAllocPolygonXYM (int vert, int holes)
	Allocates a 2D POLYGON [XYM].
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaAllocPolygonXYZM (int vert, int holes)
	Allocates a 3D POLYGON [XYZM].
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaCreatePolygon (gaiaRingPtr ring)
	Allocates a POLYGON.
GAIAGEO_DECLARE void	gaiaFreePolygon (gaiaPolygonPtr polyg)
	Destroys a POLYGON object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaAllocGeomColl (void)
	Allocates a 2D Geometry [XY].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaAllocGeomCollXYZ (void)
	Allocates a 3D Geometry [XYZ].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaAllocGeomCollXYM (void)
	Allocates a 2D Geometry [XYM].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaAllocGeomCollXYZM (void)
	Allocates a 3D Geometry [XYZM].
GAIAGEO_DECLARE void	gaiaFreeGeomColl (gaiaGeomCollPtr geom)
	Destroys a Geometry object.
GAIAGEO_DECLARE void	gaiaAddPointToGeomColl (gaiaGeomCollPtr p, double x, double y)
	Creates a new 2D Point [XY] object into a Geometry object.
GAIAGEO_DECLARE void	gaiaAddPointToGeomCollXYZ (gaiaGeomCollPtr p, double x, double y, double z)
	Creates a new 3D Point [XYZ] object into a Geometry object.
GAIAGEO_DECLARE void	gaiaAddPointToGeomCollXYM (gaiaGeomCollPtr p, double x, double y, double m)
	Creates a new 2D Point [XYM] object into a Geometry object.
GAIAGEO_DECLARE void	gaiaAddPointToGeomCollXYZM (gaiaGeomCollPtr p, double x, double y, double z, double m)
	Creates a new 3D Point [XYZM] object into a Geometry object.
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaAddLinestringToGeomColl (gaiaGeomCollPtr p, int vert)
	Creates a new Linestring object into a Geometry object.
GAIAGEO_DECLARE void	gaiaInsertLinestringInGeomColl (gaiaGeomCollPtr p, gaiaLinestringPtr line)
	Inserts an already existing Linestring object into a Geometry object.
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaAddPolygonToGeomColl (gaiaGeomCollPtr p, int vert, int interiors)
	Creates a new Polygon object into a Geometry object.
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaInsertPolygonInGeomColl (gaiaGeomCollPtr p, gaiaRingPtr ring)
	Creates a new Polygon object into a Geometry object starting from an already existing Ring object.
GAIAGEO_DECLARE gaiaRingPtr	gaiaAddInteriorRing (gaiaPolygonPtr p, int pos, int vert)
	Creates a new Interior Ring object into a Polygon object.
GAIAGEO_DECLARE void	gaiaInsertInteriorRing (gaiaPolygonPtr p, gaiaRingPtr ring)
	Inserts an already existing Ring object into a Polygon object.
GAIAGEO_DECLARE void	gaiaAddRingToPolyg (gaiaPolygonPtr polyg, gaiaRingPtr ring)
	Inserts an already existing Ring object into a Polygon object.
GAIAGEO_DECLARE gaiaLinestringPtr	gaiaCloneLinestring (gaiaLinestringPtr line)
	Duplicates a Linestring object.
GAIAGEO_DECLARE gaiaRingPtr	gaiaCloneRing (gaiaRingPtr ring)
	Duplicates a Ring object.
GAIAGEO_DECLARE gaiaPolygonPtr	gaiaClonePolygon (gaiaPolygonPtr polyg)
	Duplicates a Polygon object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCloneGeomColl (gaiaGeomCollPtr geom)
	Duplicates a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCloneGeomCollPoints (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [Points only].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCloneGeomCollLinestrings (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [Linestrings only].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCloneGeomCollPolygons (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [Polygons only].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCastGeomCollToXY (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [casting dimensions to 2D XY].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCastGeomCollToXYZ (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [casting dimensions to 3D XYZ].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCastGeomCollToXYM (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [casting dimensions to 2D XYM].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaCastGeomCollToXYZM (gaiaGeomCollPtr geom)
	Duplicates a Geometry object [casting dimensions to 3D XYZM].
GAIAGEO_DECLARE int	gaiaLineGetPoint (gaiaLinestringPtr ln, int v, double x, double y, double z, double m)
	Gets coodinates from a Linestring's Point.
GAIAGEO_DECLARE int	gaiaLineSetPoint (gaiaLinestringPtr ln, int v, double x, double y, double z, double m)
	Sets coodinates for a Linestring's Point.
GAIAGEO_DECLARE int	gaiaRingGetPoint (gaiaRingPtr rng, int v, double x, double y, double z, double m)
	Gets coodinates from a Ring's Point.
GAIAGEO_DECLARE int	gaiaRingSetPoint (gaiaRingPtr rng, int v, double x, double y, double z, double m)
	Sets coodinates for a Ring's Point.
GAIAGEO_DECLARE int	gaiaDimension (gaiaGeomCollPtr geom)
	Determines OGC dimensions for a Geometry object.
GAIAGEO_DECLARE int	gaiaGeometryType (gaiaGeomCollPtr geom)
	Determines the corresponding Type for a Geometry object.
GAIAGEO_DECLARE int	gaiaGeometryAliasType (gaiaGeomCollPtr geom)
	Determines the corresponding Type for a Geometry object.
GAIAGEO_DECLARE int	gaiaIsEmpty (gaiaGeomCollPtr geom)
	Checks for empty Geometry object.
GAIAGEO_DECLARE int	gaiaIsToxic (gaiaGeomCollPtr geom)
	Checks for toxic Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaSanitize (gaiaGeomCollPtr org)
	Attempts to sanitize a possibly malformed Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaLinearize (gaiaGeomCollPtr geom, int force_multi)
	Attempts to resolve a (Multi)Linestring from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaDissolveSegments (gaiaGeomCollPtr geom)
	Attempts to resolve a collection of Segments from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaDissolvePoints (gaiaGeomCollPtr geom)
	Attempts to resolve a collection of Points from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaExtractPointsFromGeomColl (gaiaGeomCollPtr geom)
	Extracts any Point from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaExtractLinestringsFromGeomColl (gaiaGeomCollPtr geom)
	Extracts any Linestring from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaExtractPolygonsFromGeomColl (gaiaGeomCollPtr geom)
	Extracts any Polygon from a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaMergeGeometries (gaiaGeomCollPtr geom1, gaiaGeomCollPtr geom2)
	Merges two Geometry objects into a single one.
GAIAGEO_DECLARE double	gaiaMeasureLength (int dims, double *coords, int vert)
	Measures the geometric length for a Linestring or Ring.
GAIAGEO_DECLARE double	gaiaMeasureArea (gaiaRingPtr ring)
	Measures the geometric area for a Ring object.
GAIAGEO_DECLARE void	gaiaRingCentroid (gaiaRingPtr ring, double rx, double ry)
	Determines the Centroid for a Ring object.
GAIAGEO_DECLARE void	gaiaClockwise (gaiaRingPtr p)
	Determines the direction for a Ring object.
GAIAGEO_DECLARE int	gaiaIsPointOnRingSurface (gaiaRingPtr ring, double pt_x, double pt_y)
	Check if a Point lays on a Ring surface.
GAIAGEO_DECLARE int	gaiaIsPointOnPolygonSurface (gaiaPolygonPtr polyg, double x, double y)
	Checks if a Point lays on a Polygon surface.
GAIAGEO_DECLARE double	gaiaMinDistance (double x0, double y0, int dims, double *coords, int vert)
	Computes the minimum distance intercurring from a Point and a Linestring or Ring.
GAIAGEO_DECLARE int	gaiaIntersect (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3, double x4, double y4)
	Determines the intesection Point between two Segments.
GAIAGEO_DECLARE void	gaiaShiftCoords (gaiaGeomCollPtr geom, double shift_x, double shift_y)
	Shifts any coordinate within a Geometry object.
GAIAGEO_DECLARE void	gaiaScaleCoords (gaiaGeomCollPtr geom, double scale_x, double scale_y)
	Scales any coordinate within a Geometry object.
GAIAGEO_DECLARE void	gaiaRotateCoords (gaiaGeomCollPtr geom, double angle)
	Rotates any coordinate within a Geometry object.
GAIAGEO_DECLARE void	gaiaReflectCoords (gaiaGeomCollPtr geom, int x_axis, int y_axis)
	Reflects any coordinate within a Geometry object.
GAIAGEO_DECLARE void	gaiaSwapCoords (gaiaGeomCollPtr geom)
	Swaps any coordinate within a Geometry object.
GAIAGEO_DECLARE int	gaiaLinestringEquals (gaiaLinestringPtr line1, gaiaLinestringPtr line2)
	Checks if two Linestring objects are equivalent.
GAIAGEO_DECLARE int	gaiaPolygonEquals (gaiaPolygonPtr polyg1, gaiaPolygonPtr polyg2)
	Checks if two Polygons objects are equivalent.
GAIAGEO_DECLARE int	gaiaEllipseParams (const char name, double a, double b, double rf)
	Retrieves Geodesic params for an Ellipsoid definition.
GAIAGEO_DECLARE double	gaiaGreatCircleDistance (double a, double b, double lat1, double lon1, double lat2, double lon2)
	Calculates the Great Circle Distance intercurring between two Points.
GAIAGEO_DECLARE double	gaiaGeodesicDistance (double a, double b, double rf, double lat1, double lon1, double lat2, double lon2)
	Calculates the Geodesic Distance intercurring between two Points.
GAIAGEO_DECLARE double	gaiaGreatCircleTotalLength (double a, double b, int dims, double *coords, int vert)
	Calculates the Great Circle Total Length for a Linestring / Ring.
GAIAGEO_DECLARE double	gaiaGeodesicTotalLength (double a, double b, double rf, int dims, double *coords, int vert)
	Calculates the Geodesic Total Length for a Linestring / Ring.
GAIAGEO_DECLARE int	gaiaConvertLength (double value, int unit_from, int unit_to, double *cvt)
	Convert a Length from a Measure Unit to another.

Detailed Description

Geometry handling functions: core.

Function Documentation

GAIAGEO_DECLARE gaiaRingPtr gaiaAddInteriorRing	(	gaiaPolygonPtr	p,
		int	pos,
		int	vert
	)

Creates a new Interior Ring object into a Polygon object.

Parameters:

p	pointer to the Polygon object.
pos	relative position index [first Interior Ring has index 0].
vert	number of points (aka vertices) into the Ring.

Returns:: the pointer to the newly created Ring object: NULL on failure.

See also:: gaiaAllocPolygon, gaiaAllocPolygonXYZ, gaiaAllocPolygonXYM, gaiaAllocPolygonXYZM

Note:: ownership of the Ring object belongs to the Polygon object.
the newly created Ring will have the same dimensions the Polygon has.

Examples:: demo2.c.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaAddLinestringToGeomColl	(	gaiaGeomCollPtr	p,
		int	vert
	)

Creates a new Linestring object into a Geometry object.

Parameters:

p	pointer to the Geometry object.
vert	number of points [aka vertices] into the Linestring.

Returns:: the pointer to newly created Linestring: NULL on failure.

Note:: ownership of the newly created Linestring object belongs to the Geometry object.
the newly created Linestring will have the same dimensions as the Geometry has.

Examples:: demo2.c.

GAIAGEO_DECLARE void gaiaAddPointToGeomColl	(	gaiaGeomCollPtr	p,
		double	x,
		double	y
	)

Creates a new 2D Point [XY] object into a Geometry object.

Parameters:

p	pointer to the Geometry object
x	X coordinate of the Point to be created
y	X coordinate of the Point to be created

Note:: ownership of the newly created POINT object belongs to the Geometry object.

Examples:: demo2.c, demo3.c, and demo4.c.

GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYM	(	gaiaGeomCollPtr	p,
		double	x,
		double	y,
		double	m
	)

Creates a new 2D Point [XYM] object into a Geometry object.

Parameters:

p	pointer to the Geometry object
x	X coordinate of the Point to be created
y	X coordinate of the Point to be created
m	M measure of the Point to be created

Note:: ownership of the newly created POINT object belongs to the Geometry object.

GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYZ	(	gaiaGeomCollPtr	p,
		double	x,
		double	y,
		double	z
	)

Creates a new 3D Point [XYZ] object into a Geometry object.

Parameters:

p	pointer to the Geometry object
x	X coordinate of the Point to be created
y	X coordinate of the Point to be created
z	Z coordinate of the Point to be created

Note:: ownership of the newly created POINT object belongs to the Geometry object.

GAIAGEO_DECLARE void gaiaAddPointToGeomCollXYZM	(	gaiaGeomCollPtr	p,
		double	x,
		double	y,
		double	z,
		double	m
	)

Creates a new 3D Point [XYZM] object into a Geometry object.

Parameters:

p	pointer to the Geometry object
x	X coordinate of the Point to be created
y	X coordinate of the Point to be created
z	Z coordinate of the Point to be created
m	M measure of the Point to be created

Note:: ownership of the newly created POINT object belongs to the Geometry object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaAddPolygonToGeomColl	(	gaiaGeomCollPtr	p,
		int	vert,
		int	interiors
	)

Creates a new Polygon object into a Geometry object.

Parameters:

p	pointer to the Geometry object.
vert	number of points [aka vertices] into the Polygon's Exterior Ring.
interiors	number of Interiors Rings [0, if no Interior Ring is required]

Returns:: the pointer to newly created Polygon: NULL on failure.

Note:: ownership of the newly created Polygon object belongs to the Geometry object.
the newly created Polygon will have the same dimensions as the Geometry has.

Examples:: demo2.c.

GAIAGEO_DECLARE void gaiaAddRingToPolyg	(	gaiaPolygonPtr	polyg,
		gaiaRingPtr	ring
	)

Inserts an already existing Ring object into a Polygon object.

Parameters:

polyg	pointer to the Polygon object
ring	pointer to the Ring object

See also:: gaiaInsertInteriorRing

Note:: ownership of the Ring object will be tranferred to the Polygon object.
the newly created Polygon will have the same dimensions as the Ring has.
if required the Polygon's Interior Rings count could be increased.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomColl ( void )

Allocates a 2D Geometry [XY].

Returns:: the pointer to newly created Geometry object: NULL on failure

See also:: gaiaFreeGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

Examples:: demo2.c, demo3.c, and demo4.c.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYM ( void )

Allocates a 2D Geometry [XYM].

Returns:: the pointer to newly created Geometry object: NULL on failure

See also:: gaiaFreeGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYZ ( void )

Allocates a 3D Geometry [XYZ].

Returns:: the pointer to newly created Geometry object: NULL on failure

See also:: gaiaFreeGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaAllocGeomCollXYZM ( void )

Allocates a 3D Geometry [XYZM].

Returns:: the pointer to newly created Geometry object: NULL on failure

See also:: gaiaFreeGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestring ( int vert )

Allocates a 2D LINESTRING [XY].

Parameters:

vert	number of points [aka vertices] into the Linestring

Returns:: the pointer to newly created LINESTRING object: NULL on failure

See also:: gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPoint, gaiaGetPoint

Note:: you are responsible to destroy (before or after) any allocated LINESTRING, unless you've passed ownership of the LINESTRING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYM ( int vert )

Allocates a 2D LINESTRING [XYM].

Parameters:

vert	number of points [aka vertices] into the Linestring

Returns:: the pointer to newly created LINESTRING object: NULL on failure

See also:: gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYM, gaiaGetPointXYM

Note:: you are responsible to destroy (before or after) any allocated LINESTRING, unless you've passed ownership of the LINESTRING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYZ ( int vert )

Allocates a 3D LINESTRING [XYZ].

Parameters:

vert	number of points [aka vertices] into the Linestring

Returns:: the pointer to newly created LINESTRING object: NULL on failure

See also:: gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYZ, gaiaGetPointXYZ

Note:: you are responsible to destroy (before or after) any allocated LINESTRING, unless you've passed ownership of the LINESTRING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaAllocLinestringXYZM ( int vert )

Allocates a 3D LINESTRING [XYZM].

Parameters:

vert	number of points [aka vertices] into the Linestring

Returns:: the pointer to newly created LINESTRING object: NULL on failure

See also:: gaiaFreeLinestring, gaiaLineSetPoint, gaiaLineGetPoint, gaiaSetPointXYZM, gaiaGetPointXYZM

Note:: you are responsible to destroy (before or after) any allocated LINESTRING, unless you've passed ownership of the LINESTRING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPoint	(	double	x,
		double	y
	)

Allocates a 2D POINT [XY].

Parameters:

x	the X coordinate.
y	the Y coordinate.

Returns:: the pointer to the newly created POINT object: NULL on failure

See also:: gaiaFreePoint

Note:: you are responsible to destroy (before or after) any allocated POINT, unless you've passed ownership of the POINT object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYM	(	double	x,
		double	y,
		double	m
	)

Allocates a 2D POINT [XYM].

Parameters:

x	the X coordinate.
y	the Y coordinate.
m	the M measure.

Returns:: the pointer to the newly created POINT object: NULL on failure

See also:: gaiaFreePoint

Note:: you are responsible to destroy (before or after) any allocated POINT, unless you've passed ownership of the POINT object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYZ	(	double	x,
		double	y,
		double	z
	)

Allocates a 3D POINT [XYZ].

Parameters:

x	the X coordinate.
y	the Y coordinate.
z	the Z coordinate.

Returns:: the pointer to the newly created POINT object: NULL on failure

See also:: gaiaFreePoint

Note:: you are responsible to destroy (before or after) any allocated POINT, unless you've passed ownership of the POINT object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPointPtr gaiaAllocPointXYZM	(	double	x,
		double	y,
		double	z,
		double	m
	)

Allocates a 3D POINT [XYZM].

Parameters:

x	the X coordinate.
y	the Y coordinate.
z	the Z coordinate.
m	the M measure.

Returns:: the pointer to the newly created POINT object: NULL on failure

See also:: gaiaFreePoint

Note:: you are responsible to destroy (before or after) any allocated POINT, unless you've passed ownership of the POINT object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygon	(	int	vert,
		int	holes
	)

Allocates a 2D POLYGON [XY].

Parameters:

vert	number of points [aka vertices] into the Exterior Ring.
holes	number of Interior Rings [0, if no Interior Ring is required].

Returns:: the pointer to newly created POLYGON object: NULL on failure

See also:: gaiaFreePolygon

Note:: you are responsible to destroy (before or after) any allocated POLYGON, unless you've passed ownership of the POLYGON object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYM	(	int	vert,
		int	holes
	)

Allocates a 2D POLYGON [XYM].

Parameters:

vert	number of points [aka vertices] into the Exterior Ring.
holes	number of Interior Rings [0, if no Interior Ring is required].

Returns:: the pointer to newly created POLYGON object: NULL on failure

See also:: gaiaFreePolygon

Note:: you are responsible to destroy (before or after) any allocated POLYGON, unless you've passed ownership of the POLYGON object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYZ	(	int	vert,
		int	holes
	)

Allocates a 3D POLYGON [XYZ].

Parameters:

vert	number of points [aka vertices] into the Exterior Ring.
holes	number of Interior Rings [0, if no Interior Ring is required].

Returns:: the pointer to newly created POLYGON object: NULL on failure

See also:: gaiaFreePolygon

Note:: you are responsible to destroy (before or after) any allocated POLYGON, unless you've passed ownership of the POLYGON object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaAllocPolygonXYZM	(	int	vert,
		int	holes
	)

Allocates a 3D POLYGON [XYZM].

Parameters:

vert	number of points [aka vertices] into the Exterior Ring.
holes	number of Interior Rings [may by 0, if no Interior Ring is required].

Returns:: the pointer to newly created POLYGON object: NULL on failure

See also:: gaiaFreePolygon

Note:: you are responsible to destroy (before or after) any allocated POLYGON, unless you've passed ownership of the POLYGON object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRing ( int vert )

Allocates a 2D RING [XY].

Parameters:

vert	number of points [aka vertices] into the Ring

Returns:: the pointer to newly created RING object: NULL on failure

See also:: gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPoint, gaiaGetPoint

Note:: you are responsible to destroy (before or after) any allocated RING, unless you've passed ownership of the RING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYM ( int vert )

Allocates 2D RING [XYM].

Parameters:

vert	number of points [aka vertices] into the Ring

Returns:: the pointer to newly created RING object: NULL on failure

See also:: gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYM, gaiaGetPointXYM

Note:: you are responsible to destroy (before or after) any allocated RING, unless you've passed ownership of the RING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYZ ( int vert )

Allocates a 3D RING [XYZ].

Parameters:

vert	number of points [aka vertices] into the Ring

Returns:: the pointer to newly created RING object: NULL on failure

See also:: gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYZ, gaiaGetPointXYZ

Note:: you are responsible to destroy (before or after) any allocated RING, unless you've passed ownership of the RING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaRingPtr gaiaAllocRingXYZM ( int vert )

Allocates a 3D RING [XYZM].

Parameters:

vert	number of points [aka vertices] into the Ring

Returns:: the pointer to newly created RING object: NULL on failure

See also:: gaiaFreeRing, gaiaRingSetPoint, gaiaRingGetPoint, gaiaSetPointXYZM, gaiaSetPointXYZM

Note:: you are responsible to destroy (before or after) any allocated RING, unless you've passed ownership of the RING object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXY ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [casting dimensions to 2D XY].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneGeomColl, gaiaCastGeomCollToXYZ, gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM

Note:: the newly created object is an exact copy of the original one; except in that any elementary item will be casted to 2D [XY] dimensions.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYM ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [casting dimensions to 2D XYM].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneGeomColl, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, gaiaCastGeomCollToXYZM

Note:: the newly created object is an exact copy of the original one; except in that any elementary item will be casted to 2D [XYM] dimensions.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYZ ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [casting dimensions to 3D XYZ].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneGeomColl, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM

Note:: the newly created object is an exact copy of the original one; except in that any elementary item will be casted to 3D [XYZ] dimensions.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCastGeomCollToXYZM ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [casting dimensions to 3D XYZM].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneGeomColl, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, gaiaCastGeomCollToXYM

Note:: the newly created object is an exact copy of the original one; except in that any elementary item will be casted to 3D [XYZM] dimensions.

GAIAGEO_DECLARE void gaiaClockwise ( gaiaRingPtr p )

Determines the direction for a Ring object.

Parameters:

p	pointer to Ring object

Returns:: 0 if the ring has counter-clockwise direction; any other different value for clockwise direction.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomColl ( gaiaGeomCollPtr geom )

Duplicates a Geometry object.

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, gaiaCloneGeomCollPolygons, gaiaCastGeomCollToXY, gaiaCastGeomCollToXYZ, gaiaCastGeomCollToXYM, gaiaCastGeomCollToXYZM, gaiaExtractPointsFromGeomColl, gaiaExtractLinestringsFromGeomColl, gaiaExtractPolygonsFromGeomColl, gaiaMergeGeometries

Note:: the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollLinestrings ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [Linestrings only].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, gaiaCloneGeomCollPoints, gaiaCloneGeomCollPolygons

Note:: the newly created object is an exact copy of the original one; except in that only Linestrings objects will be copied.
Caveat: an empty Geometry could be returned.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollPoints ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [Points only].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, gaiaCloneGeomCollLinestrings, gaiaCloneGeomCollPolygons

Note:: the newly created object is an exact copy of the original one; except in that only Point objects will be copied.
Caveat: an empty Geometry could be returned.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaCloneGeomCollPolygons ( gaiaGeomCollPtr geom )

Duplicates a Geometry object [Polygons only].

Parameters:

geom	pointer to Geometry object [origin].

Returns:: the pointer to newly created Geometry object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings

Note:: the newly created object is an exact copy of the original one; except in that only Polygons objects will be copied.
Caveat: an empty Geometry could be returned.

GAIAGEO_DECLARE gaiaLinestringPtr gaiaCloneLinestring ( gaiaLinestringPtr line )

Duplicates a Linestring object.

Parameters:

line	pointer to Linestring object [origin].

Returns:: the pointer to newly created Linestring object: NULL on failure.

See also:: gaiaCloneRing, gaiaClonePolygon, gaiaCloneGeomColl, gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, gaiaCloneGeomCollPolygons

Note:: the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaClonePolygon ( gaiaPolygonPtr polyg )

Duplicates a Polygon object.

Parameters:

polyg pointer to Polygon object [origin].

Returns:: the pointer to newly created Polygon object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaCloneRing, gaiaCloneGeomColl, gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, gaiaCloneGeomCollPolygons

Note:: the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE gaiaRingPtr gaiaCloneRing ( gaiaRingPtr ring )

Duplicates a Ring object.

Parameters:

ring	pointer to Ring object [origin].

Returns:: the pointer to newly created Ring object: NULL on failure.

See also:: gaiaCloneLinestring, gaiaClonePolygon, gaiaCloneGeomColl, gaiaCloneGeomCollPoints, gaiaCloneGeomCollLinestrings, gaiaCloneGeomCollPolygons

Note:: the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE int gaiaConvertLength	(	double	value,
		int	unit_from,
		int	unit_to,
		double *	cvt
	)

Convert a Length from a Measure Unit to another.

Parameters:

value	the length measure to be converted.
unit_from	original Measure Unit.
unit_to	converted Measure Unit.
cvt	on completion this variable will contain the converted length measure.

Note:: supported Measu Units are: GAIA_KM, GAIA_M, GAIA_DM, GAIA_CM, GAIA_MM, GAIA_KMI, GAIA_IN, GAIA_FT, GAIA_YD, GAIA_MI, GAIA_FATH, GAIC_CH, GAIA_LINK, GAIA_US_IN, GAIA_US_FT, GAIA_US_YD, GAIA_US_CH, GAIA_US_MI, GAIA_IND_YD, GAIA_IND_FT, GAIA_IND_CH

GAIAGEO_DECLARE void gaiaCopyLinestringCoords	(	gaiaLinestringPtr	dst,
		gaiaLinestringPtr	src
	)

Copies coordinates between two LINESTRING objects.

Parameters:

dst	destination LINESTRING [output]
src	origin LINESTRING [input]

Note:: both LINESTRING objects must have exactly the same number of points: if dimensions aren't the same for both objects, then the appropriate conversion will be silently applied.

GAIAGEO_DECLARE void gaiaCopyRingCoords	(	gaiaRingPtr	dst,
		gaiaRingPtr	src
	)

Copies coordinates betwee two RING objects.

Parameters:

dst	destination RING [output]
src	origin RING [input]

Note:: both RING objects must have exactly the same number of points: if dimensions aren't the same for both objects, then the appropriate conversion will be silently applied.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaCreatePolygon ( gaiaRingPtr ring )

Allocates a POLYGON.

Parameters:

ring	pointer to a valid RING object: assumed to be the Polygon's Exterior Ring.

Returns:: the pointer to newly created POLYGON object: NULL on failure

See also:: gaiaAllocRing, gaiaAllocRingXYZ, gaiaAllocRingXYM, gaiaAllocRingXYZM, gaiaFreePolygon

Note:: you are responsible to destroy (before or after) any allocated POLYGON, unless you've passed ownership of the POLYGON object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.
Ownership of passed Ring object will be transferred to the Polygon object being created.

GAIAGEO_DECLARE int gaiaDimension ( gaiaGeomCollPtr geom )

Determines OGC dimensions for a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: OGC dimensions

Note:

OGC dimensions are defined as follows:

if the Geometry doesn't contain any elementary item: -1
if the Geometry only contains Point items: 0
if the Geometry only contains Point / Linestring items: 1
if the Geometry contains some Polygon item: 2

Examples:: demo2.c.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaDissolvePoints ( gaiaGeomCollPtr geom )

Attempts to resolve a collection of Points from a Geometry object.

Parameters:

geom	pointer to Geometry object.

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaLinearize, gaiaDissolveSegments

Note:

you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaDissolvePoints()
the input Geometry can be of any arbitrary type:

any Point will be copied untouched.
any Linestring will be dissolved into sparse Points.
any Ring will be dissolved into sparse Points.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaDissolveSegments ( gaiaGeomCollPtr geom )

Attempts to resolve a collection of Segments from a Geometry object.

Parameters:

geom	pointer to Geometry object.

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaLinearize, gaiaDissolvePoints

Note:

you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaDissolveSegments()
the input Geometry can be of any arbitrary type:

any Point will be copied untouched.
any Linestring will be dissolved into Segments.
any Ring will be dissolved into Segments.

GAIAGEO_DECLARE int gaiaEllipseParams	(	const char *	name,
		double *	a,
		double *	b,
		double *	rf
	)

Retrieves Geodesic params for an Ellipsoid definition.

Parameters:

name	text string identifying an Ellipsoid definition.
a	on completion this variable will contain the first geodesic param.
b	on completion this variable will contain the second geodesic param.
rf	on completion this variable will contain the third geodesic param.

Returns:: 0 on failure: any other value on success.

See also:: gaiaGreatCircleDistance, gaiaGeodesicDistance, gaiaGreatCircleTotalLength, gaiaGeodesicTotalLength

Note:: supported Ellipsoid definitions are: MERIT, SGS85, GRS80, IAU76, airy, APL4.9, NWL9D, mod_airy, andrae, aust_SA, GRS67, bessel, bess_nam, clrk66, clrk80, CPM, delmbr, engelis, evrst30, evrst48, evrst56, evrst69, evrstSS, fschr60

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaExtractLinestringsFromGeomColl ( gaiaGeomCollPtr geom )

Extracts any Linestring from a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaExtractPointsFromGeomColl, gaiaExtractPolygonsFromGeomColl, gaiaCloneGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaExtractLinestringsFromGeomColl()
the newly created Geometry will contain any Linestring contained into the input Geometry.
if the input Geometry doesn't contains any Linestring, then NULL will be returned.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaExtractPointsFromGeomColl ( gaiaGeomCollPtr geom )

Extracts any Point from a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaExtractLinestringsFromGeomColl, gaiaExtractPolygonsFromGeomColl, gaiaCloneGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaExtractPointsFromGeomColl()
the newly created Geometry will contain any Point contained into the input Geometry.
if the input Geometry doesn't contains any Point, then NULL will be returned.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaExtractPolygonsFromGeomColl ( gaiaGeomCollPtr geom )

Extracts any Polygon from a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaExtractPointsFromGeomColl, gaiaExtractLinestringsFromGeomColl, gaiaCloneGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaExtractPolygonsFromGeomColl()
the newly created Geometry will contain any Polygon contained into the input Geometry.
if the input Geometry doesn't contains any Polygon, then NULL will be returned.

GAIAGEO_DECLARE void gaiaFree ( void * ptr )

Safely frees any dynamic memory block allocated by the library itself.

Parameters:

ptr	pointer to dynamicly allocated memory

Note:: on some platforms (most notably, Microsoft Windows) many different runtime libraries may actually support the same process.
attempting to free() a memory block allocated by a different runtime module may easily cause fatal memory corruption.

GAIAGEO_DECLARE void gaiaFreeGeomColl ( gaiaGeomCollPtr geom )

Destroys a Geometry object.

Parameters:

geom	pointer to the Geometry object to be destroyed

See also:: gaiaAllocGeomColl, gaiaAllocGeomCollXYZ, gaiaAllocGeomCollXYM, gaiaAllocGeomCollXYZM

Note:: attempting to destroy any Geometry object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.
Ownerhip of each POINT, LINESTRING or POLYGON object referenced by a Geometry object alway belongs to the Geometry itself, so destroying the Geometry will surely destroy any related elementary geometry item as well.

Examples:: demo1.c, demo2.c, demo3.c, and demo4.c.

GAIAGEO_DECLARE void gaiaFreeLinestring ( gaiaLinestringPtr ptr )

Destroys a LINESTRING object.

Parameters:

ptr	pointer to the LINESTRING object to be destroyed

See also:: gaiaAllocLinestring, gaiaAllocLinestringXYZ, gaiaAllocLinestringXYM, gaiaAllocLinestringXYZM

Note:: attempting to destroy any LINESTRING object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.

GAIAGEO_DECLARE void gaiaFreePoint ( gaiaPointPtr ptr )

Destroys a POINT object.

Parameters:

ptr	pointer to the POINT object to be destroyed

See also:: gaiaAllocPoint, gaiaAllocPointXYZ, gaiaAllocPointXYM, gaiaAllocPointXYZM

Note:: attempting to destroy any POINT object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.

GAIAGEO_DECLARE void gaiaFreePolygon ( gaiaPolygonPtr polyg )

Destroys a POLYGON object.

Parameters:

polyg pointer to the POLYGON object to be destroyed

See also:: gaiaAllocPolygon, gaiaAllocPolygonXYZ, gaiaAllocPolygonXYM, gaiaAllocPolygonXYZM, gaiaCreatePolygon

Note:: attempting to destroy any POLYGON object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.
Ownerhip of each RING object referenced by a POLYGON object alway belongs to the POLYGON itself, so destroying the POLYGON will surely destroy any related RING as well.

GAIAGEO_DECLARE void gaiaFreeRing ( gaiaRingPtr ptr )

Destroys a RING object.

Parameters:

ptr	pointer to the RING object to be destroyed

See also:: gaiaAllocRing, gaiaAllocRingXYZ, gaiaAllocRingXYM, gaiaAllocRingXYZM

Note:: attempting to destroy any RING object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.

GAIAGEO_DECLARE double gaiaGeodesicDistance	(	double	a,
		double	b,
		double	rf,
		double	lat1,
		double	lon1,
		double	lat2,
		double	lon2
	)

Calculates the Geodesic Distance intercurring between two Points.

Parameters:

a	first geodesic parameter.
b	second geodesic parameter.
rf	third geodesic parameter.
lat1	Latitude of first Point.
lon1	Longitude of first Point.
lat2	Latitude of second Point.
lon2	Longitude of second Point.

Returns:: the calculated Geodesic Distance.

See also:: gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGreatCircleTotalLength, gaiaGeodesicTotalLength

Note:: the returned distance is expressed in Kilometers.
the Geodesic method is much more accurate but slowest to be calculated.

GAIAGEO_DECLARE double gaiaGeodesicTotalLength	(	double	a,
		double	b,
		double	rf,
		int	dims,
		double *	coords,
		int	vert
	)

Calculates the Geodesic Total Length for a Linestring / Ring.

Parameters:

a	first geodesic parameter.
b	second geodesic parameter.
rf	third geodesic parameter.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM
coords	pointed to COORD mem-array
vert	number of Points (aka Vertices) within the COORD mem-array

Returns:: the calculated Geodesic Total Length.

See also:: gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGeodesicDistance, gaiaGreatCircleTotalLength

Note:: the returned length is expressed in Kilometers.
the Geodesic method is much more accurate but slowest to be calculated.
dims, coords and vert are usually expected to correspond to DimensionModel, Coords and Points members from a gaiaLinestringStruct or gaiaRingStruct

GAIAGEO_DECLARE int gaiaGeometryAliasType ( gaiaGeomCollPtr geom )

Determines the corresponding Type for a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: the corresponding Geometry Type

See also:: gaiaGeometryType

Note:: Type is one of: GAIA_POINT, GAIA_LINESTRING, GAIA_POLYGON, GAIA_MULTIPOINT, GAIA_MULTILINESTRING, GAIA_MULTIPOLYGON, GAIA_GEOMETRYCOLLECTION
on failure GAIA_NONE will be returned.

Remarks:: deprecated function (used in earlier SpatiaLite versions).

GAIAGEO_DECLARE int gaiaGeometryType ( gaiaGeomCollPtr geom )

Determines the corresponding Type for a Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: the corresponding Geometry Type

Note:: Type is one of: GAIA_POINT, GAIA_LINESTRING, GAIA_POLYGON, GAIA_MULTIPOINT, GAIA_MULTILINESTRING, GAIA_MULTIPOLYGON, GAIA_GEOMETRYCOLLECTION, GAIA_POINTZ, GAIA_LINESTRINGZ, GAIA_POLYGONZ, GAIA_MULTIPOINTZ, GAIA_MULTILINESTRINGZ, GAIA_MULTIPOLYGONZ, GAIA_GEOMETRYCOLLECTIONZ, GAIA_POINTM, GAIA_LINESTRINGM, GAIA_POLYGONM, GAIA_MULTIPOINTM, GAIA_MULTILINESTRINGM, GAIA_MULTIPOLYGONM, GAIA_GEOMETRYCOLLECTIONM, GAIA_POINTZM, GAIA_LINESTRINGZM, GAIA_POLYGONZM, GAIA_MULTIPOINTZM, GAIA_MULTILINESTRINGZM, GAIA_MULTIPOLYGONZM, GAIA_GEOMETRYCOLLECTIONZM
on failure GAIA_NONE will be returned.

Examples:: demo1.c, and demo2.c.

GAIAGEO_DECLARE double gaiaGreatCircleDistance	(	double	a,
		double	b,
		double	lat1,
		double	lon1,
		double	lat2,
		double	lon2
	)

Calculates the Great Circle Distance intercurring between two Points.

Parameters:

a	first geodesic parameter.
b	second geodesic parameter.
lat1	Latitude of first Point.
lon1	Longitude of first Point.
lat2	Latitude of second Point.
lon2	Longitude of second Point.

Returns:: the calculated Great Circle Distance.

See also:: gaiaEllipseParams, gaiaGeodesicDistance, gaiaGreatCircleTotalLength, gaiaGeodesicTotalLength

Note:: the returned distance is expressed in Kilometers.
the Great Circle method is less accurate but fastest to be calculated.

GAIAGEO_DECLARE double gaiaGreatCircleTotalLength	(	double	a,
		double	b,
		int	dims,
		double *	coords,
		int	vert
	)

Calculates the Great Circle Total Length for a Linestring / Ring.

Parameters:

a	first geodesic parameter.
b	second geodesic parameter.
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM
coords	pointed to COORD mem-array
vert	number of Points (aka Vertices) within the COORD mem-array

Returns:: the calculated Great Circle Total Length.

See also:: gaiaEllipseParams, gaiaGreatCircleDistance, gaiaGeodesicDistance, gaiaGeodesicTotalLength

Note:: the returned length is expressed in Kilometers.
the Great Circle method is less accurate but fastest to be calculated.
dims, coords and vert are usually expected to correspond to DimensionModel, Coords and Points members from a gaiaLinestringStruct or gaiaRingStruct

GAIAGEO_DECLARE void gaiaInsertInteriorRing	(	gaiaPolygonPtr	p,
		gaiaRingPtr	ring
	)

Inserts an already existing Ring object into a Polygon object.

Parameters:

p	pointer to the Polygon object
ring	pointer to the Ring object

See also:: gaiaAddRingToPolygon

Note:: ownership of the Ring object still remains to the calling procedure (a duplicated copy of the original Ring will be inserted into the Polygon).
the newly created Polygon will have the same dimensions as the Ring has.
if required the Polygon's Interior Rings count could be increased.

GAIAGEO_DECLARE void gaiaInsertLinestringInGeomColl	(	gaiaGeomCollPtr	p,
		gaiaLinestringPtr	line
	)

Inserts an already existing Linestring object into a Geometry object.

Parameters:

p	pointer to the Geometry object.
line	pointer to the Linestring object.

Note:: ownership of the Linestring object will be transferred to the Geometry object.

GAIAGEO_DECLARE gaiaPolygonPtr gaiaInsertPolygonInGeomColl	(	gaiaGeomCollPtr	p,
		gaiaRingPtr	ring
	)

Creates a new Polygon object into a Geometry object starting from an already existing Ring object.

Parameters:

p	pointer to the Geometry object.
ring	pointer to the Ring object [assumed to represent to Polygon's Exterior Ring].

Returns:: the pointer to the newly created Polygon object: NULL on failure.

Note:: ownership of the Ring object will be transferred to the Polygon object, and the Polygon object ownerships belongs to the Geometry object.
the Polygon object will have the same dimensions as the Ring object has.

GAIAGEO_DECLARE int gaiaIntersect	(	double *	x0,
		double *	y0,
		double	x1,
		double	y1,
		double	x2,
		double	y2,
		double	x3,
		double	y3,
		double	x4,
		double	y4
	)

Determines the intesection Point between two Segments.

Parameters:

x0	on completion this variable will contain the Intersection X coord
y0	on completion this variable will contain the Intersection Y coord
x1	start Point X of first Segment
y1	start Point Y of first Segment
x2	end Point X of first Segment
y2	end Point Y of first Segment
x3	start Point X of second Segment
y3	start Point Y of second Segment
x4	end Point X of second Segment
y4	end Point Y of second Segment

Returns:: 0 if the Segments doesn't intersect at all: any other value on success.

GAIAGEO_DECLARE int gaiaIsEmpty ( gaiaGeomCollPtr geom )

Checks for empty Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: 0 if the Geometry is empty: otherwise any other different value.

Note:: an empty Geometry is a Geometry not containing any elementary item: i.e. no Points, no Linestrings and no Polygons at all.

GAIAGEO_DECLARE int gaiaIsPointOnPolygonSurface	(	gaiaPolygonPtr	polyg,
		double	x,
		double	y
	)

Checks if a Point lays on a Polygon surface.

Parameters:

polyg	pointer to Polygon object
x	Point X coordinate
y	Point Y coordinate

Returns:: 0 if false: any other value if true

GAIAGEO_DECLARE int gaiaIsPointOnRingSurface	(	gaiaRingPtr	ring,
		double	pt_x,
		double	pt_y
	)

Check if a Point lays on a Ring surface.

Parameters:

ring	pointer to Ring object
pt_x	Point X coordinate
pt_y	Point Y coordinate

Returns:: 0 if false: any other value if true

GAIAGEO_DECLARE int gaiaIsToxic ( gaiaGeomCollPtr geom )

Checks for toxic Geometry object.

Parameters:

geom	pointer to Geometry object

Returns:: 0 if the Geometry is not toxic: otherwise any other different value.

See also:: gaiaSanitize

Note:: a toxic Geometry is a Geometry containing severely malformed Polygons: i.e. containing less than 4 Points, unclosed Rings and so on.
Attempting to pass any toxic Geometry to GEOS supported functions will easily cause a crash.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaLinearize	(	gaiaGeomCollPtr	geom,
		int	force_multi
	)

Attempts to resolve a (Multi)Linestring from a Geometry object.

Parameters:

geom	pointer to Geometry object.
force_multi,:	0 if the returned Geometry could represent a Linestring: any other value if casting to MultiLinestring is required unconditionally.

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaDissolveSegments, gaiaDissolvePoints

Note:: you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaLinearize()
the input Geometry is expected to contain Polygons only: then any Ring will be transformed into the corresponding Linestring.

GAIAGEO_DECLARE int gaiaLineGetPoint	(	gaiaLinestringPtr	ln,
		int	v,
		double *	x,
		double *	y,
		double *	z,
		double *	m
	)

Gets coodinates from a Linestring's Point.

Parameters:

ln	pointer to Linestring object.
v	relative position of Point: first Point has index 0
x	on completion this variable will contain the Point X coordinate.
y	on completion this variable will contain the Point Y coordinate.
z	on completion this variable will contain the Point Z coordinate.
m	on completion this variable will contain the Point M measure.

Returns:: 0 on failure: any other different value on success.

See also:: gaiaLineSetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaGetPointXYM, gaiaGetPointXYZM

Note:: this function perform the same identical task performed by gaiaGetPoint(), gaiaGetPointXYZ(), gaiaGetPointXYM() and gaiaGetPointXYZM() macros.
using the gaiaLineGetPoint() function is a little bit slower but is intrinsically safest, because misused macros can easily cause severe memory corruption.
gaiaLineGetPoint() instead will always ensure that the appropriate dimensions (as declared by the Linestring object) will be correctly used.

GAIAGEO_DECLARE int gaiaLineSetPoint	(	gaiaLinestringPtr	ln,
		int	v,
		double	x,
		double	y,
		double	z,
		double	m
	)

Sets coodinates for a Linestring's Point.

Parameters:

ln	pointer to Linestring object.
v	relative position of Point: first Point has index 0
x	the Point's X coordinate.
y	the Point's Y coordinate.
z	the Point's Z coordinate.
m	the Point's M measure.

Returns:: 0 on failure: any other different value on success.

See also:: gaiaLineGetPoint, gaiaSetPoint, gaiaSetPointXYZ, gaiaSetPointXYM, gaiaSetPointXYZM

Note:: this function perform the same identical task performed by gaiaSetPoint(), gaiaSetPointXYZ(), gaiaSetPointXYM() and gaiaSetPointXYZM() macros.
using the gaiaLineSetPoint() function is a little bit slower but is intrinsically safest, because misused macros can easily cause severe memory corruption.
gaiaLineSetPoint() instead will always ensure that the appropriate dimensions (as declared by the Linestring object) will be correctly used.

GAIAGEO_DECLARE int gaiaLinestringEquals	(	gaiaLinestringPtr	line1,
		gaiaLinestringPtr	line2
	)

Checks if two Linestring objects are equivalent.

Parameters:

line1	pointer to first Linestring object.
line2	pointer to second Linestring object.

Returns:: 0 if false: any other different value if true

See also:: gaiaPolygonEquals

Note:: two Linestrings objects are assumed to be equivalent if exactly

Remarks:: deprecated function (used in earlier SpatiaLite versions). the same Points are found in both them.

GAIAGEO_DECLARE double gaiaMeasureArea ( gaiaRingPtr ring )

Measures the geometric area for a Ring object.

Parameters:

ring	pointer to Ring object

Returns:: the calculated geometric area

See also:: gaiaGeomCollArea

Remarks:: internal method: doesn't require any GEOS support.

GAIAGEO_DECLARE double gaiaMeasureLength	(	int	dims,
		double *	coords,
		int	vert
	)

Measures the geometric length for a Linestring or Ring.

Parameters:

dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM
coords	pointed to COORD mem-array
vert	number of Points (aka Vertices) within the COORD mem-array

Returns:: the calculated geometric length

See also:: gaiaGeomCollLength

Note:: dims, coords and vert are usually expected to correspond to DimensionModel, Coords and Points members from a gaiaLinestringStruct or gaiaRingStruct

Remarks:: internal method: doesn't require any GEOS support.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaMergeGeometries	(	gaiaGeomCollPtr	geom1,
		gaiaGeomCollPtr	geom2
	)

Merges two Geometry objects into a single one.

Parameters:

geom1	pointer to first Geometry object.
geom2	pointer to second Geometry object.

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaCloneGeomColl

Note:: you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaMergeGeometries()
the newly created Geometry will contain any Point, Linestring and/or Polygon contained in both input Geometries.

GAIAGEO_DECLARE double gaiaMinDistance	(	double	x0,
		double	y0,
		int	dims,
		double *	coords,
		int	vert
	)

Computes the minimum distance intercurring from a Point and a Linestring or Ring.

Parameters:

x0	Point X coordinate
y0	Point Y coordinate
dims	dimensions: one of GAIA_XY, GAIA_XY_Z, GAIA_XY_M or GAIA_XY_ZM
coords	pointed to COORD mem-array
vert	number of Points (aka Vertices) within the COORD mem-array

Returns:: the calculated minumum distance.

Note:: dims, coords and vert are usually expected to correspond to DimensionModel, Coords and Points members from a gaiaLinestringStruct or gaiaRingStruct

GAIAGEO_DECLARE int gaiaPolygonEquals	(	gaiaPolygonPtr	polyg1,
		gaiaPolygonPtr	polyg2
	)

Checks if two Polygons objects are equivalent.

Parameters:

polyg1	pointer to first Polygon object.
polyg2	pointer to second Polygon object.

Returns:: 0 if false: any other different value if true

See also:: gaiaLinestringEquals

Note:: two Polygon objects are assumed to be equivalent if exactly the same Points are found in both them.

Remarks:: deprecated function (used in earlier SpatiaLite versions).

GAIAGEO_DECLARE void gaiaReflectCoords	(	gaiaGeomCollPtr	geom,
		int	x_axis,
		int	y_axis
	)

Reflects any coordinate within a Geometry object.

Parameters:

geom	pointer to Geometry object.
x_axis	if set to 0, no X axis reflection will be applied: otherwise the X axis will be reflected.
y_axis	if set to 0, no Y axis reflection will be applied: otherwise the Y axis will be reflected.

See also:: gaiaShiftCoords, gaiaScaleCoords, gaiaRotateCoords, gaiaSwapCoords

GAIAGEO_DECLARE void gaiaRingCentroid	(	gaiaRingPtr	ring,
		double *	rx,
		double *	ry
	)

Determines the Centroid for a Ring object.

Parameters:

ring	pointer to Ring object.
rx	on completion this variable will contain the centroid X coordinate.
ry	on completion this variable will contain the centroid Y coordinate.

See also:: gaiaGeomCollCentroid

Remarks:: internal method: doesn't require any GEOS support.

GAIAGEO_DECLARE int gaiaRingGetPoint	(	gaiaRingPtr	rng,
		int	v,
		double *	x,
		double *	y,
		double *	z,
		double *	m
	)

Gets coodinates from a Ring's Point.

Parameters:

rng	pointer to Ring object.
v	relative position of Point: first Point has index 0
x	on completion this variable will contain the Point X coordinate.
y	on completion this variable will contain the Point Y coordinate.
z	on completion this variable will contain the Point Z coordinate.
m	on completion this variable will contain the Point M measure.

Returns:: 0 on failure: any other different value on success.

See also:: gaiaRingSetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaGetPointXYM, gaiaGetPointXYZM

Note:: this function perform the same identical task performed by gaiaGetPoint(), gaiaGetPointXYZ(), gaiaGetPointXYM() and gaiaGetPointXYZM() macros.
using the gaiaRingGetPoint() function is a little bit slower but is intrinsically safest, because misused macros can easily cause severe memory corruption.
gaiaRingGetPoint() instead will always ensure that the appropriate dimensions (as declared by the Ring object) will be correctly used.

GAIAGEO_DECLARE int gaiaRingSetPoint	(	gaiaRingPtr	rng,
		int	v,
		double	x,
		double	y,
		double	z,
		double	m
	)

Sets coodinates for a Ring's Point.

Parameters:

rng	pointer to Ring object.
v	relative position of Point: first Point has index 0
x	the Point's X coordinate.
y	the Point's Y coordinate.
z	the Point's Z coordinate.
m	the Point's M measure.

Returns:: 0 on failure: any other different value on success.

See also:: gaiaRingGetPoint, gaiaGetPoint, gaiaGetPointXYZ, gaiaSetPointXYM, gaiaSetPointXYZM

Note:: this function perform the same identical task performed by gaiaSetPoint(), gaiaSetPointXYZ(), gaiaSetPointXYM() and gaiaSetPointXYZM() macros.
using the gaiaRingSetPoint() function is a little bit slower but is intrinsically safest, because misused macros can easily cause severe memory corruption.
gaiaRingSetPoint() instead will always ensure that the appropriate dimensions (as declared by the Ring object) will be correctly used.

GAIAGEO_DECLARE void gaiaRotateCoords	(	gaiaGeomCollPtr	geom,
		double	angle
	)

Rotates any coordinate within a Geometry object.

Parameters:

geom	pointer to Geometry object.
angle	rotation angle [expressed in Degrees].

See also:: gaiaShiftCoords, gaiaScaleCoords, gaiaReflectCoords, gaiaSwapCoords

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaSanitize ( gaiaGeomCollPtr org )

Attempts to sanitize a possibly malformed Geometry object.

Parameters:

org	pointer to Geometry object.

Returns:: the pointer to newly created Geometry: NULL on failure.

See also:: gaiaIsToxic

Note:

you are responsible to destroy (before or after) any allocated Geometry, this including any Geometry created by gaiaSanitize()
the output Geometry will surely have:

no repeated Points on Linestrings or Rings (i.e. consecutive Points sharing exactly the same coordinates): any repeated Point will be suppressed, simply leaving only the first occurrence.
proper Ring closure: for sure any Ring will have exactly coinciding first and last Points.

GAIAGEO_DECLARE void gaiaScaleCoords	(	gaiaGeomCollPtr	geom,
		double	scale_x,
		double	scale_y
	)

Scales any coordinate within a Geometry object.

Parameters:

geom	pointer to Geometry object.
scale_x	X axis scale factor.
scale_y	Y axis scale factor.

See also:: gaiaShiftCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords

GAIAGEO_DECLARE void gaiaShiftCoords	(	gaiaGeomCollPtr	geom,
		double	shift_x,
		double	shift_y
	)

Shifts any coordinate within a Geometry object.

Parameters:

geom	pointer to Geometry object.
shift_x	X axis shift factor.
shift_y	Y axis shift factor.

See also:: gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords, gaiaSwapCoords

GAIAGEO_DECLARE void gaiaSwapCoords ( gaiaGeomCollPtr geom )

Swaps any coordinate within a Geometry object.

Parameters:

geom	pointer to Geometry object.

See also:: gaiaShiftCoords, gaiaScaleCoords, gaiaRotateCoords, gaiaReflectCoords

Note:: the X and Y axes will be swapped.

Functions

Detailed Description

Function Documentation