Skip to content

Latest commit

 

History

History
4746 lines (2687 loc) · 118 KB

API.md

File metadata and controls

4746 lines (2687 loc) · 118 KB
Raw

TG C API

C API for the TG geometry library.

This document provides a detailed description of the functions and types in the tg.h and tg.c source files for the TG library.

For a more general overview please see the project README.

Table of contents

Programing notes

Pure functions

TG library functions are thread-safe, reentrant, and (mostly) without side effects. The exception being with the use of malloc by some functions like geometry constructors. In those cases, it's the programmer's responsibiilty to check the return value before continuing.

struct tg_geom *geom = tg_geom_new_point(-112, 33);
if (!geom) {
    // System is out of memory.
}

Fast cloning

The cloning of geometries, as with tg_geom_clone(), are O(1) operations that use implicit sharing through an atomic reference counter. Geometry constructors like tg_geom_new_polygon() will use this method under the hood to maintain references of its inputs.

While this may only be an implementation detail, it's important for the programmer to understand how TG uses memory and object references.

For example:

struct tg_geom *geom = tg_geom_new_polygon(exterior, holes, nholes);

Above, a new geometry "geom" was created and includes a cloned reference to the tg_ring "exterior" and all of the holes.

Providing TG_NOATOMICS to the compiler will disable the use of atomics and instead use non-atomic reference counters.

cc -DTG_NOATOMICS tg.c ...

Alternatively, the tg_geom_copy() method is available to perform a deep copy of the geometry.

Avoid memory leaks

To avoid memory leaks, call tg_geom_free() on geometries created from geometry constructors, geometry parsers, tg_geom_clone(), and tg_geom_copy().

In other words, for every tg_geom_new_*(), tg_geom_parse_*(), tg_geom_clone(), and tg_geom_copy() there should be (eventually and exactly) one tg_geom_free().

Upcasting

The TG object types tg_line, tg_ring, and tg_poly can be safely upcasted to a tg_geom with no cost at runtime.

struct tg_geom *geom1 = (struct tg_geom*)line; // Cast tg_line to tg_geom
struct tg_geom *geom2 = (struct tg_geom*)ring; // Cast tg_ring to tg_geom
struct tg_geom *geom3 = (struct tg_geom*)poly; // Cast tg_poly to tg_geom

This allows for exposing all tg_geom functions to the other object types.

In addition, the tg_ring type can also cast to a tg_poly.

struct tg_poly *poly = (struct tg_poly*)ring; // Cast tg_ring to tg_poly

Do not downcast. It's not generally safe to cast from a tg_geom to other types.

Structs

Objects

Enums

Geometry constructors

Functions for creating and freeing geometries.

Geometry accessors

Functions for accessing various information about geometries, such as getting the geometry type or extracting underlying components or coordinates.

Geometry predicates

Functions for testing the spatial relations of two geometries.

Geometry parsing

Functions for parsing geometries from external data representations. It's recommended to use tg_geom_error() after parsing to check for errors.

Geometry writing

Functions for writing geometries as external data representations.

Geometry with alternative dimensions

Functions for working with geometries that have more than two dimensions or are empty. The extra dimensional coordinates contained within these geometries are only carried along and serve no other purpose than to be available for when it's desired to export to an output representation such as GeoJSON, WKT, or WKB.

Point functions

Functions for working directly with the tg_point type.

Segment functions

Functions for working directly with the tg_segment type.

Rectangle functions

Functions for working directly with the tg_rect type.

Ring functions

Functions for working directly with the tg_ring type.

There are no direct spatial predicates for tg_ring. If you want to perform operations like "intersects" or "covers" then you must upcast the ring to a tg_geom, like such:

tg_geom_intersects((struct tg_geom*)ring, geom);

Line functions

Functions for working directly with the tg_line type.

There are no direct spatial predicates for tg_line. If you want to perform operations like "intersects" or "covers" then you must upcast the line to a tg_geom, like such:

tg_geom_intersects((struct tg_geom*)line, geom);

Polygon functions

Functions for working directly with the tg_poly type.

There are no direct spatial predicates for tg_poly. If you want to perform operations like "intersects" or "covers" then you must upcast the poly to a tg_geom, like such:

tg_geom_intersects((struct tg_geom*)poly, geom);

Global environment

Functions for optionally setting the behavior of the TG environment. These, if desired, should be called only once at program start up and prior to calling any other tg_*() functions.

tg_point

struct tg_point {
    double x;
    double y;
};

The base point type used for all geometries.

See also

tg_segment

struct tg_segment {
    struct tg_point a;
    struct tg_point b;
};

The base segment type used in tg_line and tg_ring for joining two vertices.

See also

tg_rect

struct tg_rect {
    struct tg_point min;
    struct tg_point max;
};

A rectangle defined by a minimum and maximum coordinates. Returned by the tg_geom_rect(), tg_ring_rect(), and other *_rect() functions for getting a geometry's minumum bounding rectangle. Also used internally for geometry indexing.

See also

tg_ring

struct tg_ring;

A ring is series of tg_segment which creates a shape that does not self-intersect and is fully closed, where the start and end points are the exact same value.

Creating

To create a new ring use the tg_ring_new() function.

struct tg_ring *ring = tg_ring_new(points, npoints);

Upcasting

A tg_ring can always be safely upcasted to a tg_poly or tg_geom; allowing it to use any tg_poly_*() or tg_geom_*() function.

struct tg_poly *poly = (struct tg_poly*)ring; // Cast to a tg_poly
struct tg_geom *geom = (struct tg_geom*)ring; // Cast to a tg_geom

See also

tg_line

struct tg_line;

A line is a series of tg_segment that make up a linestring.

Creating

To create a new line use the tg_line_new() function.

struct tg_line *line = tg_line_new(points, npoints);

Upcasting

A tg_line can always be safely upcasted to a tg_geom; allowing it to use any tg_geom_*() function.

struct tg_geom *geom = (struct tg_geom*)line; // Cast to a tg_geom

See also

tg_poly

struct tg_poly;

A polygon consists of one exterior ring and zero or more holes.

Creating

To create a new polygon use the tg_poly_new() function.

struct tg_poly *poly = tg_poly_new(exterior, holes, nholes);

Upcasting

A tg_poly can always be safely upcasted to a tg_geom; allowing it to use any tg_geom_*() function.

struct tg_geom *geom = (struct tg_geom*)poly; // Cast to a tg_geom

See also

tg_geom

struct tg_geom;

A geometry is the common generic type that can represent a Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection.

For geometries that are derived from GeoJSON, they may have addtional attributes such as being a Feature or a FeatureCollection; or include extra json fields.

Creating

To create a new geometry use one of the Geometry constructors or Geometry parsing functions.

struct tg_geom *geom = tg_geom_new_point(point);
struct tg_geom *geom = tg_geom_new_polygon(poly);
struct tg_geom *geom = tg_parse_geojson(geojson);

Upcasting

Other types, specifically tg_line, tg_ring, and tg_poly, can be safely upcasted to a tg_geom; allowing them to use any tg_geom_*() function.

struct tg_geom *geom1 = (struct tg_geom*)line; // Cast to a LineString
struct tg_geom *geom2 = (struct tg_geom*)ring; // Cast to a Polygon
struct tg_geom *geom3 = (struct tg_geom*)poly; // Cast to a Polygon

See also

tg_geom_type

enum tg_geom_type {
    TG_POINT              = 1, // Point.
    TG_LINESTRING         = 2, // LineString.
    TG_POLYGON            = 3, // Polygon.
    TG_MULTIPOINT         = 4, // MultiPoint, collection of points.
    TG_MULTILINESTRING    = 5, // MultiLineString, collection of linestrings.
    TG_MULTIPOLYGON       = 6, // MultiPolygon, collection of polygons.
    TG_GEOMETRYCOLLECTION = 7, // GeometryCollection, collection of geometries.
};

Geometry types.

All tg_geom are one of the following underlying types.

See also

tg_index

enum tg_index {
    TG_DEFAULT,  // default is TG_NATURAL or tg_env_set_default_index().
    TG_NONE,     // no indexing available, or disabled.
    TG_NATURAL,  // indexing with natural ring order, for rings/lines
    TG_YSTRIPES, // indexing using segment striping, rings only
};

Geometry indexing options.

Used for polygons, rings, and lines to make the point-in-polygon and geometry intersection operations fast.

An index can also be used for efficiently traversing, searching, and performing nearest-neighbor (kNN) queries on the segment using tg_ring_index_*() and tg_ring_nearest() functions.

tg_geom_new_point()

struct tg_geom *tg_geom_new_point(struct tg_point point);

Creates a Point geometry.

Parameters

  • point: Input point

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_linestring()

struct tg_geom *tg_geom_new_linestring(const struct tg_line *line);

Creates a LineString geometry.

Parameters

  • line: Input line, caller retains ownership.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_polygon()

struct tg_geom *tg_geom_new_polygon(const struct tg_poly *poly);

Creates a Polygon geometry.

Parameters

  • poly: Input polygon, caller retains ownership.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipoint()

struct tg_geom *tg_geom_new_multipoint(const struct tg_point *points, int npoints);

Creates a MultiPoint geometry.

Parameters

  • points: An array of points, caller retains ownership.
  • npoints: The number of points in array

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multilinestring()

struct tg_geom *tg_geom_new_multilinestring(const struct tg_line *const lines[], int nlines);

Creates a MultiLineString geometry.

Parameters

  • lines: An array of lines, caller retains ownership.
  • nlines: The number of lines in array

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipolygon()

struct tg_geom *tg_geom_new_multipolygon(const struct tg_poly *const polys[], int npolys);

Creates a MultiPolygon geometry.

Parameters

  • polys: An array of polygons, caller retains ownership.
  • npolys: The number of polygons in array

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_geometrycollection()

struct tg_geom *tg_geom_new_geometrycollection(const struct tg_geom *const geoms[], int ngeoms);

Creates a GeometryCollection geometry.

Parameters

  • geoms: An array of geometries, caller retains ownership.
  • ngeoms: The number of geometries in array

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_error()

struct tg_geom *tg_geom_new_error(const char *errmsg);

Utility for returning an error message wrapped in a geometry. This operation does not return a real geometry, only an error message, which may be useful for generating custom errors from operations outside of the TG library.

tg_geom_clone()

struct tg_geom *tg_geom_clone(const struct tg_geom *geom);

Clones a geometry

Parameters

  • geom: Input geometry, caller retains ownership.

Return

  • A duplicate of the provided geometry.

Note

  • The caller is responsible for freeing with tg_geom_free().
  • This method of cloning uses implicit sharing through an atomic reference counter.

See also

tg_geom_copy()

struct tg_geom *tg_geom_copy(const struct tg_geom *geom);

Copies a geometry

Parameters

  • geom: Input geometry, caller retains ownership.

Return

  • A duplicate of the provided geometry.
  • NULL if out of memory

Note

  • The caller is responsible for freeing with tg_geom_free().
  • This method performs a deep copy of the entire geometry to new memory.

See also

tg_geom_free()

void tg_geom_free(struct tg_geom *geom);

Releases the memory associated with a geometry.

Parameters

  • geom: Input geometry

See also

tg_geom_typeof()

enum tg_geom_type tg_geom_typeof(const struct tg_geom *geom);

Returns the geometry type. e.g. TG_POINT, TG_POLYGON, TG_LINESTRING

Parameters

  • geom: Input geometry

Return

  • The geometry type

See also

tg_geom_type_string()

const char *tg_geom_type_string(enum tg_geom_type type);

Get the string representation of a geometry type. e.g. "Point", "Polygon", "LineString".

Parameters

  • type: Input geometry type

Return

  • A string representing the type

Note

  • The returned string does not need to be freed.

See also

tg_geom_rect()

struct tg_rect tg_geom_rect(const struct tg_geom *geom);

Returns the minimum bounding rectangle of a geometry.

Parameters

  • geom: Input geometry

Return

  • Minumum bounding rectangle

See also

tg_geom_is_feature()

bool tg_geom_is_feature(const struct tg_geom *geom);

Returns true if the geometry is a GeoJSON Feature.

Parameters

  • geom: Input geometry

Return

  • True or false

See also

tg_geom_is_featurecollection()

bool tg_geom_is_featurecollection(const struct tg_geom *geom);

Returns true if the geometry is a GeoJSON FeatureCollection.

Parameters

  • geom: Input geometry

Return

  • True or false

See also

tg_geom_point()

struct tg_point tg_geom_point(const struct tg_geom *geom);

Returns the underlying point for the provided geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_POINT geometry, returns the point.
  • For everything else returns the center of the geometry's bounding rectangle.

See also

tg_geom_line()

const struct tg_line *tg_geom_line(const struct tg_geom *geom);

Returns the underlying line for the provided geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_LINESTRING geometry, returns the line.
  • For everything else returns NULL.

See also

tg_geom_poly()

const struct tg_poly *tg_geom_poly(const struct tg_geom *geom);

Returns the underlying polygon for the provided geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_POLYGON geometry, returns the polygon.
  • For everything else returns NULL.

See also

tg_geom_num_points()

int tg_geom_num_points(const struct tg_geom *geom);

Returns the number of points in a MultiPoint geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_MULTIPOINT geometry, returns the number of points.
  • For everything else returns zero.

See also

tg_geom_point_at()

struct tg_point tg_geom_point_at(const struct tg_geom *geom, int index);

Returns the point at index for a MultiPoint geometry.

Parameters

  • geom: Input geometry
  • index: Index of point

Return

  • The point at index. Returns an empty point if the geometry type is not TG_MULTIPOINT or when the provided index is out of range.

See also

tg_geom_num_lines()

int tg_geom_num_lines(const struct tg_geom *geom);

Returns the number of lines in a MultiLineString geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_MULTILINESTRING geometry, returns the number of lines.
  • For everything else returns zero.

See also

tg_geom_line_at()

const struct tg_line *tg_geom_line_at(const struct tg_geom *geom, int index);

Returns the line at index for a MultiLineString geometry.

Parameters

  • geom: Input geometry
  • index: Index of line

Return

  • The line at index. Returns NULL if the geometry type is not TG_MULTILINE or when the provided index is out of range.

See also

tg_geom_num_polys()

int tg_geom_num_polys(const struct tg_geom *geom);

Returns the number of polygons in a MultiPolygon geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_MULTIPOLYGON geometry, returns the number of polygons.
  • For everything else returns zero.

See also

tg_geom_poly_at()

const struct tg_poly *tg_geom_poly_at(const struct tg_geom *geom, int index);

Returns the polygon at index for a MultiPolygon geometry.

Parameters

  • geom: Input geometry
  • index: Index of polygon

Return

  • The polygon at index. Returns NULL if the geometry type is not TG_MULTIPOLYGON or when the provided index is out of range.

See also

tg_geom_num_geometries()

int tg_geom_num_geometries(const struct tg_geom *geom);

Returns the number of geometries in a GeometryCollection geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_MULTIGEOMETRY geometry, returns the number of geometries.
  • For everything else returns zero.

Note

  • A geometry that is a GeoJSON FeatureCollection can use this function to get number features in its collection.

See also

tg_geom_geometry_at()

const struct tg_geom *tg_geom_geometry_at(const struct tg_geom *geom, int index);

Returns the geometry at index for a GeometryCollection geometry.

Parameters

  • geom: Input geometry
  • index: Index of geometry

Return

  • For a TG_MULTIGEOMETRY geometry, returns the number of geometries.
  • For everything else returns zero.

Note

  • A geometry that is a GeoJSON FeatureCollection can use this function to get number features in its collection.

See also

tg_geom_extra_json()

const char *tg_geom_extra_json(const struct tg_geom *geom);

Returns a string that represents any extra JSON from a parsed GeoJSON geometry. Such as the "id" or "properties" fields.

Parameters

  • geom: Input geometry

Return

  • Returns a valid JSON object as a string, or NULL if the geometry did not come from GeoJSON or there is no extra JSON.

Note

  • The returned string does not need to be freed.

See also

tg_geom_is_empty()

bool tg_geom_is_empty(const struct tg_geom *geom);

Tests whether a geometry is empty. An empty geometry is one that has no interior boundary.

Parameters

  • geom: Input geometry

Return

  • True or false

tg_geom_dims()

int tg_geom_dims(const struct tg_geom *geom);

Get the number of dimensions for a geometry.

Parameters

  • geom: Input geometry

Return

  • 2 for standard geometries
  • 3 when geometry has Z or M coordinates
  • 4 when geometry has Z and M coordinates
  • 0 when input is NULL

tg_geom_has_z()

bool tg_geom_has_z(const struct tg_geom *geom);

Tests whether a geometry has Z coordinates.

Parameters

  • geom: Input geometry

Return

  • True or false

tg_geom_has_m()

bool tg_geom_has_m(const struct tg_geom *geom);

Tests whether a geometry has M coordinates.

Parameters

  • geom: Input geometry

Return

  • True or false

tg_geom_z()

double tg_geom_z(const struct tg_geom *geom);

Get the Z coordinate of a Point geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_POINT geometry, returns the Z coodinate.
  • For everything else returns zero.

tg_geom_m()

double tg_geom_m(const struct tg_geom *geom);

Get the M coordinate of a Point geometry.

Parameters

  • geom: Input geometry

Return

  • For a TG_POINT geometry, returns the M coodinate.
  • For everything else returns zero.

tg_geom_extra_coords()

const double *tg_geom_extra_coords(const struct tg_geom *geom);

Get the extra coordinates for a geometry.

Parameters

  • geom: Input geometry

Return

  • Array of coordinates
  • NULL if there are no extra coordinates

Note

  • These are the raw coodinates provided by a constructor like tg_geom_new_polygon_z() or from a parsed source like WKT "POLYGON Z ...".

See also

tg_geom_num_extra_coords()

int tg_geom_num_extra_coords(const struct tg_geom *geom);

Get the number of extra coordinates for a geometry

Parameters

  • geom: Input geometry

Return

  • The number of extra coordinates, or zero if none.

See also

tg_geom_memsize()

size_t tg_geom_memsize(const struct tg_geom *geom);

Returns the allocation size of the geometry.

Parameters

  • geom: Input geometry

Return

  • Size of geometry in bytes

tg_geom_search()

void tg_geom_search(const struct tg_geom *geom, struct tg_rect rect, bool(*iter)(const struct tg_geom *geom, int index, void *udata), void *udata);

Iterates over all child geometries in geom that intersect rect

Note

  • Only iterates over collection types: TG_MULTIPOINT, TG_MULTILINESTRING, TG_MULTIPOLYGON, and TG_GEOMETRYCOLLECTION.
  • A GeoJSON FeatureCollection works as well.

See also

tg_geom_equals()

bool tg_geom_equals(const struct tg_geom *a, const struct tg_geom *b);

Tests whether two geometries are topologically equal.

See also

tg_geom_intersects()

bool tg_geom_intersects(const struct tg_geom *a, const struct tg_geom *b);

Tests whether two geometries intersect.

See also

tg_geom_disjoint()

bool tg_geom_disjoint(const struct tg_geom *a, const struct tg_geom *b);

Tests whether 'a' and 'b' have no point in common, and are fully disconnected geometries.

Note

  • Works the same as !tg_geom_intersects(a, b)

See also

tg_geom_contains()

bool tg_geom_contains(const struct tg_geom *a, const struct tg_geom *b);

Tests whether 'a' contains 'b', and 'b' is not touching the boundary of 'a'.

Note

  • Works the same as tg_geom_within(b, a)

Warning

  • This predicate returns false when geometry 'b' is on or touching the boundary of geometry 'a'. Such as when a point is on the edge of a polygon. For full coverage, consider using tg_geom_covers.

See also

tg_geom_within()

bool tg_geom_within(const struct tg_geom *a, const struct tg_geom *b);

Tests whether 'a' is contained inside of 'b' and not touching the boundary of 'b'.

Note

  • Works the same as tg_geom_contains(b, a)

Warning

  • This predicate returns false when geometry 'a' is on or touching the boundary of geometry 'b'. Such as when a point is on the edge of a polygon. For full coverage, consider using tg_geom_coveredby.

See also

tg_geom_covers()

bool tg_geom_covers(const struct tg_geom *a, const struct tg_geom *b);

Tests whether a geometry 'a' fully contains geometry 'b'.

See also

tg_geom_coveredby()

bool tg_geom_coveredby(const struct tg_geom *a, const struct tg_geom *b);

Tests whether 'a' is fully contained inside of 'b'.

Note

  • Works the same as tg_geom_covers(b, a)

See also

tg_geom_touches()

bool tg_geom_touches(const struct tg_geom *a, const struct tg_geom *b);

Tests whether a geometry 'a' touches 'b'. They have at least one point in common, but their interiors do not intersect.

See also

tg_geom_intersects_rect()

bool tg_geom_intersects_rect(const struct tg_geom *a, struct tg_rect b);

Tests whether a geometry intersects a rect.

See also

tg_geom_intersects_xy()

bool tg_geom_intersects_xy(const struct tg_geom *a, double x, double y);

Tests whether a geometry intersects a point using xy coordinates.

See also

tg_parse_geojson()

struct tg_geom *tg_parse_geojson(const char *geojson);

Parse geojson.

Supports GeoJSON standard, including Features, FeaturesCollection, ZM coordinates, properties, and arbritary JSON members.

Parameters

  • geojson: A geojson string. Must be UTF8 and null-terminated.

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_geojsonn()

struct tg_geom *tg_parse_geojsonn(const char *geojson, size_t len);

Parse geojson with an included data length.

Parameters

  • geojson: Geojson data. Must be UTF8.
  • len: Length of data

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_geojson_ix()

struct tg_geom *tg_parse_geojson_ix(const char *geojson, enum tg_index ix);

Parse geojson using provided indexing option.

Parameters

  • geojson: A geojson string. Must be UTF8 and null-terminated.
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_geojsonn_ix()

struct tg_geom *tg_parse_geojsonn_ix(const char *geojson, size_t len, enum tg_index ix);

Parse geojson using provided indexing option.

Parameters

  • geojson: Geojson data. Must be UTF8.
  • len: Length of data
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wkt()

struct tg_geom *tg_parse_wkt(const char *wkt);

Parse Well-known text (WKT).

Parameters

  • wkt: A WKT string. Must be null-terminated

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wktn()

struct tg_geom *tg_parse_wktn(const char *wkt, size_t len);

Parse Well-known text (WKT) with an included data length.

Parameters

  • wkt: WKT data
  • len: Length of data

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wkt_ix()

struct tg_geom *tg_parse_wkt_ix(const char *wkt, enum tg_index ix);

Parse Well-known text (WKT) using provided indexing option.

Parameters

  • wkt: A WKT string. Must be null-terminated
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wktn_ix()

struct tg_geom *tg_parse_wktn_ix(const char *wkt, size_t len, enum tg_index ix);

Parse Well-known text (WKT) using provided indexing option.

Parameters

  • wkt: WKT data
  • len: Length of data
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wkb()

struct tg_geom *tg_parse_wkb(const uint8_t *wkb, size_t len);

Parse Well-known binary (WKB).

Parameters

  • wkb: WKB data
  • len: Length of data

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_wkb_ix()

struct tg_geom *tg_parse_wkb_ix(const uint8_t *wkb, size_t len, enum tg_index ix);

Parse Well-known binary (WKB) using provided indexing option.

Parameters

  • wkb: WKB data
  • len: Length of data
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_hex()

struct tg_geom *tg_parse_hex(const char *hex);

Parse hex encoded Well-known binary (WKB).

Parameters

  • hex: A hex string. Must be null-terminated

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_hexn()

struct tg_geom *tg_parse_hexn(const char *hex, size_t len);

Parse hex encoded Well-known binary (WKB) with an included data length.

Parameters

  • hex: Hex data
  • len: Length of data

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_hex_ix()

struct tg_geom *tg_parse_hex_ix(const char *hex, enum tg_index ix);

Parse hex encoded Well-known binary (WKB) using provided indexing option.

Parameters

  • hex: Hex string. Must be null-terminated
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_hexn_ix()

struct tg_geom *tg_parse_hexn_ix(const char *hex, size_t len, enum tg_index ix);

Parse hex encoded Well-known binary (WKB) using provided indexing option.

Parameters

  • hex: Hex data
  • len: Length of data
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse()

struct tg_geom *tg_parse(const void *data, size_t len);

Parse data into a geometry by auto detecting the input type. The input data can be WKB, WKT, Hex, or GeoJSON.

Parameters

  • data: Data
  • len: Length of data

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_parse_ix()

struct tg_geom *tg_parse_ix(const void *data, size_t len, enum tg_index ix);

Parse data using provided indexing option.

Parameters

  • data: Data
  • len: Length of data
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A geometry or an error. Use tg_geom_error() after parsing to check for errors.

See also

tg_geom_error()

const char *tg_geom_error(const struct tg_geom *geom);

Return a parsing error.

Parsing functions, such as tg_parse_geojson(), may fail due to invalid input data.

It's important to always check for errors after parsing.

Example

struct tg_geom *geom = tg_parse_geojson(input);
if (tg_geom_error(geom)) {
    // The parsing failed due to invalid input or out of memory.

    // Get the error message.
    const char *err = tg_geom_error(geom);

    // Do something with the error, such as log it.
    printf("[err] %s\n", err);

    // Make sure to free the error geom and it's resources.
    tg_geom_free(geom);

    // !!
    // DO NOT use the return value of tg_geom_error() after calling 
    // tg_geom_free(). If you need to hang onto the error for a longer
    // period of time then you must copy it before freeing.
    // !!

    return;
} else {
    // ... Parsing succeeded 
}

Return

  • A string describing the error
  • NULL if there was no error

See also

tg_geom_geojson()

size_t tg_geom_geojson(const struct tg_geom *geom, char *dst, size_t n);

Writes a GeoJSON representation of a geometry.

The content is stored as a C string in the buffer pointed to by dst. A terminating null character is automatically appended after the content written.

Parameters

  • geom: Input geometry
  • dst: Buffer where the resulting content is stored.
  • n: Maximum number of bytes to be used in the buffer.

Return

  • The number of characters, not including the null-terminator, needed to store the content into the C string buffer. If the returned length is greater than n-1, then only a parital copy occurred, for example:
char str[64];
size_t len = tg_geom_geojson(geom, str, sizeof(str));
if (len > sizeof(str)-1) {
    // ... write did not complete ...
}

See also

tg_geom_wkt()

size_t tg_geom_wkt(const struct tg_geom *geom, char *dst, size_t n);

Writes a Well-known text (WKT) representation of a geometry.

The content is stored as a C string in the buffer pointed to by dst. A terminating null character is automatically appended after the content written.

Parameters

  • geom: Input geometry
  • dst: Buffer where the resulting content is stored.
  • n: Maximum number of bytes to be used in the buffer.

Return

  • The number of characters, not including the null-terminator, needed to store the content into the C string buffer. If the returned length is greater than n-1, then only a parital copy occurred, for example:
char str[64];
size_t len = tg_geom_wkt(geom, str, sizeof(str));
if (len > sizeof(str)-1) {
    // ... write did not complete ...
}

See also

tg_geom_wkb()

size_t tg_geom_wkb(const struct tg_geom *geom, uint8_t *dst, size_t n);

Writes a Well-known binary (WKB) representation of a geometry.

The content is stored in the buffer pointed by dst.

Parameters

  • geom: Input geometry
  • dst: Buffer where the resulting content is stored.
  • n: Maximum number of bytes to be used in the buffer.

Return

  • The number of characters needed to store the content into the buffer. If the returned length is greater than n, then only a parital copy occurred, for example:
uint8_t buf[64];
size_t len = tg_geom_wkb(geom, buf, sizeof(buf));
if (len > sizeof(buf)) {
    // ... write did not complete ...
}

See also

tg_geom_hex()

size_t tg_geom_hex(const struct tg_geom *geom, char *dst, size_t n);

Writes a hex encoded Well-known binary (WKB) representation of a geometry.

The content is stored as a C string in the buffer pointed to by dst. A terminating null character is automatically appended after the content written.

Parameters

  • geom: Input geometry
  • dst: Buffer where the resulting content is stored.
  • n: Maximum number of bytes to be used in the buffer.

Return

  • The number of characters, not including the null-terminator, needed to store the content into the C string buffer. If the returned length is greater than n-1, then only a parital copy occurred, for example:
char str[64];
size_t len = tg_geom_hex(geom, str, sizeof(str));
if (len > sizeof(str)-1) {
    // ... write did not complete ...
}

See also

tg_geom_new_point_z()

struct tg_geom *tg_geom_new_point_z(struct tg_point point, double z);

Creates a Point geometry that includes a Z coordinate.

Parameters

  • point: Input point
  • z: The Z coordinate

Return

  • A newly allocated geometry, or NULL if system is out of memory. The caller is responsible for freeing with tg_geom_free().

See also

tg_geom_new_point_m()

struct tg_geom *tg_geom_new_point_m(struct tg_point point, double m);

Creates a Point geometry that includes an M coordinate.

Parameters

  • point: Input point
  • m: The M coordinate

Return

  • A newly allocated geometry, or NULL if system is out of memory. The caller is responsible for freeing with tg_geom_free().

See also

tg_geom_new_point_zm()

struct tg_geom *tg_geom_new_point_zm(struct tg_point point, double z, double m);

Creates a Point geometry that includes a Z and M coordinates.

Parameters

  • point: Input point
  • z: The Z coordinate
  • m: The M coordinate

Return

  • A newly allocated geometry, or NULL if system is out of memory. The caller is responsible for freeing with tg_geom_free().

See also

tg_geom_new_point_empty()

struct tg_geom *tg_geom_new_point_empty();

Creates an empty Point geometry.

Return

  • A newly allocated geometry, or NULL if system is out of memory. The caller is responsible for freeing with tg_geom_free().

See also

tg_geom_new_linestring_z()

struct tg_geom *tg_geom_new_linestring_z(const struct tg_line *line, const double *extra_coords, int ncoords);

Creates a LineString geometry that includes Z coordinates.

Parameters

  • line: Input line, caller retains ownership.
  • coords: Array of doubles representing each Z coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_linestring_m()

struct tg_geom *tg_geom_new_linestring_m(const struct tg_line *line, const double *extra_coords, int ncoords);

Creates a LineString geometry that includes M coordinates.

Parameters

  • line: Input line, caller retains ownership.
  • coords: Array of doubles representing each M coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_linestring_zm()

struct tg_geom *tg_geom_new_linestring_zm(const struct tg_line *line, const double *extra_coords, int ncoords);

Creates a LineString geometry that includes ZM coordinates.

Parameters

  • line: Input line, caller retains ownership.
  • coords: Array of doubles representing each Z and M coordinate, interleaved. Caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_linestring_empty()

struct tg_geom *tg_geom_new_linestring_empty();

Creates an empty LineString geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_polygon_z()

struct tg_geom *tg_geom_new_polygon_z(const struct tg_poly *poly, const double *extra_coords, int ncoords);

Creates a Polygon geometry that includes Z coordinates.

Parameters

  • poly: Input polygon, caller retains ownership.
  • coords: Array of doubles representing each Z coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_polygon_m()

struct tg_geom *tg_geom_new_polygon_m(const struct tg_poly *poly, const double *extra_coords, int ncoords);

Creates a Polygon geometry that includes M coordinates.

Parameters

  • poly: Input polygon, caller retains ownership.
  • coords: Array of doubles representing each M coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_polygon_zm()

struct tg_geom *tg_geom_new_polygon_zm(const struct tg_poly *poly, const double *extra_coords, int ncoords);

Creates a Polygon geometry that includes ZM coordinates.

Parameters

  • poly: Input polygon, caller retains ownership.
  • coords: Array of doubles representing each Z and M coordinate, interleaved. Caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_polygon_empty()

struct tg_geom *tg_geom_new_polygon_empty();

Creates an empty Polygon geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipoint_z()

struct tg_geom *tg_geom_new_multipoint_z(const struct tg_point *points, int npoints, const double *extra_coords, int ncoords);

Creates a MultiPoint geometry that includes Z coordinates.

Parameters

  • points: An array of points, caller retains ownership.
  • npoints: The number of points in array
  • coords: Array of doubles representing each Z coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipoint_m()

struct tg_geom *tg_geom_new_multipoint_m(const struct tg_point *points, int npoints, const double *extra_coords, int ncoords);

Creates a MultiPoint geometry that includes M coordinates.

Parameters

  • points: An array of points, caller retains ownership.
  • npoints: The number of points in array
  • coords: Array of doubles representing each M coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipoint_zm()

struct tg_geom *tg_geom_new_multipoint_zm(const struct tg_point *points, int npoints, const double *extra_coords, int ncoords);

Creates a MultiPoint geometry that includes ZM coordinates.

Parameters

  • points: An array of points, caller retains ownership.
  • npoints: The number of points in array
  • coords: Array of doubles representing each Z and M coordinate, interleaved. Caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipoint_empty()

struct tg_geom *tg_geom_new_multipoint_empty();

Creates an empty MultiPoint geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multilinestring_z()

struct tg_geom *tg_geom_new_multilinestring_z(const struct tg_line *const lines[], int nlines, const double *extra_coords, int ncoords);

Creates a MultiLineString geometry that includes Z coordinates.

Parameters

  • lines: An array of lines, caller retains ownership.
  • nlines: The number of lines in array
  • coords: Array of doubles representing each Z coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multilinestring_m()

struct tg_geom *tg_geom_new_multilinestring_m(const struct tg_line *const lines[], int nlines, const double *extra_coords, int ncoords);

Creates a MultiLineString geometry that includes M coordinates.

Parameters

  • lines: An array of lines, caller retains ownership.
  • nlines: The number of lines in array
  • coords: Array of doubles representing each M coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multilinestring_zm()

struct tg_geom *tg_geom_new_multilinestring_zm(const struct tg_line *const lines[], int nlines, const double *extra_coords, int ncoords);

Creates a MultiLineString geometry that includes ZM coordinates.

Parameters

  • lines: An array of lines, caller retains ownership.
  • nlines: The number of lines in array
  • coords: Array of doubles representing each Z and M coordinate, interleaved. Caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multilinestring_empty()

struct tg_geom *tg_geom_new_multilinestring_empty();

Creates an empty MultiLineString geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipolygon_z()

struct tg_geom *tg_geom_new_multipolygon_z(const struct tg_poly *const polys[], int npolys, const double *extra_coords, int ncoords);

Creates a MultiPolygon geometry that includes Z coordinates.

Parameters

  • polys: An array of polygons, caller retains ownership.
  • npolys: The number of polygons in array
  • coords: Array of doubles representing each Z coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipolygon_m()

struct tg_geom *tg_geom_new_multipolygon_m(const struct tg_poly *const polys[], int npolys, const double *extra_coords, int ncoords);

Creates a MultiPolygon geometry that includes M coordinates.

Parameters

  • polys: An array of polygons, caller retains ownership.
  • npolys: The number of polygons in array
  • coords: Array of doubles representing each M coordinate, caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipolygon_zm()

struct tg_geom *tg_geom_new_multipolygon_zm(const struct tg_poly *const polys[], int npolys, const double *extra_coords, int ncoords);

Creates a MultiPolygon geometry that includes ZM coordinates.

Parameters

  • polys: An array of polygons, caller retains ownership.
  • npolys: The number of polygons in array
  • coords: Array of doubles representing each Z and M coordinate, interleaved. Caller retains ownership.
  • ncoords: Number of doubles in array.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_multipolygon_empty()

struct tg_geom *tg_geom_new_multipolygon_empty();

Creates an empty MultiPolygon geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_geom_new_geometrycollection_empty()

struct tg_geom *tg_geom_new_geometrycollection_empty();

Creates an empty GeometryCollection geometry.

Return

  • A newly allocated geometry.
  • NULL if system is out of memory.

Note

See also

tg_point_rect()

struct tg_rect tg_point_rect(struct tg_point point);

Returns the minimum bounding rectangle of a point.

See also

tg_point_intersects_rect()

bool tg_point_intersects_rect(struct tg_point a, struct tg_rect b);

Tests whether a point fully intersects a rectangle.

See also

tg_segment_rect()

struct tg_rect tg_segment_rect(struct tg_segment s);

Returns the minimum bounding rectangle of a segment.

See also

tg_segment_intersects_segment()

bool tg_segment_intersects_segment(struct tg_segment a, struct tg_segment b);

Tests whether a segment intersects another segment.

See also

tg_rect_expand()

struct tg_rect tg_rect_expand(struct tg_rect rect, struct tg_rect other);

Expands a rectangle to include an additional rectangle.

Parameters

  • rect: Input rectangle
  • other: Input rectangle

Return

  • Expanded rectangle

See also

tg_rect_expand_point()

struct tg_rect tg_rect_expand_point(struct tg_rect rect, struct tg_point point);

Expands a rectangle to include an additional point.

Parameters

  • rect: Input rectangle
  • point: Input Point

Return

  • Expanded rectangle

See also

tg_rect_center()

struct tg_point tg_rect_center(struct tg_rect rect);

Returns the center point of a rectangle

See also

tg_rect_intersects_rect()

bool tg_rect_intersects_rect(struct tg_rect a, struct tg_rect b);

Tests whether a rectangle intersects another rectangle.

See also

tg_rect_intersects_point()

bool tg_rect_intersects_point(struct tg_rect a, struct tg_point b);

Tests whether a rectangle and a point intersect.

See also

tg_ring_new()

struct tg_ring *tg_ring_new(const struct tg_point *points, int npoints);

Creates a ring from a series of points.

Parameters

  • points: Array of points
  • npoints: Number of points in array

Return

  • A newly allocated ring
  • NULL if out of memory

Note

  • A tg_ring can be safely upcasted to a tg_geom. (struct tg_geom*)ring
  • A tg_ring can be safely upcasted to a tg_poly. (struct tg_poly*)ring
  • All rings with 32 or more points are automatically indexed.

See also

tg_ring_new_ix()

struct tg_ring *tg_ring_new_ix(const struct tg_point *points, int npoints, enum tg_index ix);

Creates a ring from a series of points using provided index option.

Parameters

  • points: Array of points
  • npoints: Number of points in array
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A newly allocated ring
  • NULL if out of memory

Note

See also

tg_ring_free()

void tg_ring_free(struct tg_ring *ring);

Releases the memory associated with a ring.

Parameters

  • ring: Input ring

See also

tg_ring_clone()

struct tg_ring *tg_ring_clone(const struct tg_ring *ring);

Clones a ring

Parameters

  • ring: Input ring, caller retains ownership.

Return

  • A duplicate of the provided ring.

Note

  • The caller is responsible for freeing with tg_ring_free().
  • This method of cloning uses implicit sharing through an atomic reference counter.

See also

tg_ring_copy()

struct tg_ring *tg_ring_copy(const struct tg_ring *ring);

Copies a ring

Parameters

  • ring: Input ring, caller retains ownership.

Return

  • A duplicate of the provided ring.
  • NULL if out of memory

Note

  • The caller is responsible for freeing with tg_ring_free().
  • This method performs a deep copy of the entire geometry to new memory.

See also

tg_ring_memsize()

size_t tg_ring_memsize(const struct tg_ring *ring);

Returns the allocation size of the ring.

Parameters

  • ring: Input ring

Return

  • Size of ring in bytes

See also

tg_ring_rect()

struct tg_rect tg_ring_rect(const struct tg_ring *ring);

Returns the minimum bounding rectangle of a rect.

Parameters

  • ring: Input ring

Return

  • Minimum bounding retangle

See also

tg_ring_num_points()

int tg_ring_num_points(const struct tg_ring *ring);

Returns the number of points.

Parameters

  • ring: Input ring

Return

  • Number of points

See also

tg_ring_point_at()

struct tg_point tg_ring_point_at(const struct tg_ring *ring, int index);

Returns the point at index.

Parameters

  • ring: Input ring
  • index: Index of point

Return

  • The point at index

Note

  • This function performs bounds checking. Use tg_ring_points() for direct access to the points.

See also

tg_ring_points()

const struct tg_point *tg_ring_points(const struct tg_ring *ring);

Returns the underlying point array of a ring.

Parameters

  • ring: Input ring

Return

  • Array or points

See also

tg_ring_num_segments()

int tg_ring_num_segments(const struct tg_ring *ring);

Returns the number of segments.

Parameters

  • ring: Input ring

Return

  • Number of segments

See also

tg_ring_segment_at()

struct tg_segment tg_ring_segment_at(const struct tg_ring *ring, int index);

Returns the segment at index.

Parameters

  • ring: Input ring
  • index: Index of segment

Return

  • The segment at index

See also

tg_ring_convex()

bool tg_ring_convex(const struct tg_ring *ring);

Returns true if ring is convex.

Parameters

  • ring: Input ring

Return

  • True if ring is convex.
  • False if ring is concave.

See also

tg_ring_clockwise()

bool tg_ring_clockwise(const struct tg_ring *ring);

Returns true if winding order is clockwise.

Parameters

  • ring: Input ring

Return

  • True if clockwise
  • False if counter-clockwise

See also

tg_ring_index_spread()

int tg_ring_index_spread(const struct tg_ring *ring);

Returns the indexing spread for a ring.

The "spread" is the number of segments or rectangles that are grouped together to produce a unioned rectangle that is stored at a higher level.

For a tree based structure, this would be the number of items per node.

Parameters

  • ring: Input ring

Return

  • The spread, default is 16
  • Zero if ring has no indexing

See also

tg_ring_index_num_levels()

int tg_ring_index_num_levels(const struct tg_ring *ring);

Returns the number of levels.

Parameters

  • ring: Input ring

Return

  • The number of levels
  • Zero if ring has no indexing

See also

tg_ring_index_level_num_rects()

int tg_ring_index_level_num_rects(const struct tg_ring *ring, int levelidx);

Returns the number of rectangles at level.

Parameters

  • ring: Input ring
  • levelidx: The index of level

Return

  • The number of index levels
  • Zero if ring has no indexing or levelidx is out of bounds.

See also

tg_ring_index_level_rect()

struct tg_rect tg_ring_index_level_rect(const struct tg_ring *ring, int levelidx, int rectidx);

Returns a specific level rectangle.

Parameters

  • ring: Input ring
  • levelidx: The index of level
  • rectidx: The index of rectangle

Return

  • The rectangle
  • Empty rectangle if ring has no indexing, or levelidx or rectidx is out of bounds.

See also

tg_ring_nearest_segment()

bool tg_ring_nearest_segment(const struct tg_ring *ring, double(*rect_dist)(struct tg_rect rect, int *more, void *udata), double(*seg_dist)(struct tg_segment seg, int *more, void *udata), bool(*iter)(struct tg_segment seg, double dist, int index, void *udata), void *udata);

Iterates over segments from nearest to farthest.

This is a kNN operation. The caller must provide their own "rect_dist" and "seg_dist" callbacks to do the actual distance calculations.

Parameters

  • ring: Input ring
  • rect_dist: Callback that returns the distance to a tg_rect.
  • seg_dist: Callback that returns the distance to a tg_segment.
  • iter: Callback that returns each segment in the ring in order of nearest to farthest. Caller must return true to continue to the next segment, or return false to stop iterating.
  • udata: User-defined data

Return

  • True if operation succeeded, false if out of memory.

Note

  • Though not typical, this operation may need to allocate memory. It's recommended to check the return value for success.
  • The *more argument is an optional ref-value that is used for performing partial step-based or probability-based calculations. A detailed description of its use is outside the scope of this document. Ignoring it altogether is the preferred behavior.

See also

tg_ring_line_search()

void tg_ring_line_search(const struct tg_ring *a, const struct tg_line *b, bool(*iter)(struct tg_segment aseg, int aidx, struct tg_segment bseg, int bidx, void *udata), void *udata);

Iterates over all segments in ring A that intersect with segments in line B.

Note

  • This efficently uses the indexes of each geometry, if available.

See also

tg_ring_ring_search()

void tg_ring_ring_search(const struct tg_ring *a, const struct tg_ring *b, bool(*iter)(struct tg_segment aseg, int aidx, struct tg_segment bseg, int bidx, void *udata), void *udata);

Iterates over all segments in ring A that intersect with segments in ring B.

Note

  • This efficently uses the indexes of each geometry, if available.

See also

tg_ring_area()

double tg_ring_area(const struct tg_ring *ring);

Calculate the area of a ring.

tg_ring_perimeter()

double tg_ring_perimeter(const struct tg_ring *ring);

Calculate the perimeter length of a ring.

tg_line_new()

struct tg_line *tg_line_new(const struct tg_point *points, int npoints);

Creates a line from a series of points.

Parameters

  • points: Array of points
  • npoints: Number of points in array

Return

  • A newly allocated line
  • NULL if out of memory

Note

  • A tg_line can be safely upcasted to a tg_geom. (struct tg_geom*)line
  • All lines with 32 or more points are automatically indexed.

See also

tg_line_new_ix()

struct tg_line *tg_line_new_ix(const struct tg_point *points, int npoints, enum tg_index ix);

Creates a line from a series of points using provided index option.

Parameters

  • points: Array of points
  • npoints: Number of points in array
  • ix: Indexing option, e.g. TG_NONE, TG_NATURAL, TG_YSTRIPES

Return

  • A newly allocated line
  • NULL if out of memory

Note

  • A tg_line can be safely upcasted to a tg_geom. (struct tg_geom*)poly

See also

tg_line_free()

void tg_line_free(struct tg_line *line);

Releases the memory associated with a line.

Parameters

  • line: Input line

See also

tg_line_clone()

struct tg_line *tg_line_clone(const struct tg_line *line);

Clones a line

Parameters

  • line: Input line, caller retains ownership.

Return

  • A duplicate of the provided line.

Note

  • The caller is responsible for freeing with tg_line_free().
  • This method of cloning uses implicit sharing through an atomic reference counter.

See also

tg_line_copy()

struct tg_line *tg_line_copy(const struct tg_line *line);

Copies a line

Parameters

  • line: Input line, caller retains ownership.

Return

  • A duplicate of the provided line.
  • NULL if out of memory

Note

  • The caller is responsible for freeing with tg_line_free().
  • This method performs a deep copy of the entire geometry to new memory.

See also

tg_line_memsize()

size_t tg_line_memsize(const struct tg_line *line);

Returns the allocation size of the line.

Parameters

  • line: Input line

Return

  • Size of line in bytes

See also

tg_line_rect()

struct tg_rect tg_line_rect(const struct tg_line *line);

Returns the minimum bounding rectangle of a line.

See also

tg_line_num_points()

int tg_line_num_points(const struct tg_line *line);

Returns the number of points.

Parameters

  • line: Input line

Return

  • Number of points

See also

tg_line_points()

const struct tg_point *tg_line_points(const struct tg_line *line);

Returns the underlying point array of a line.

Parameters

  • line: Input line

Return

  • Array or points

See also

tg_line_point_at()

struct tg_point tg_line_point_at(const struct tg_line *line, int index);

Returns the point at index.

Parameters

  • line: Input line
  • index: Index of point

Return

  • The point at index

Note

  • This function performs bounds checking. Use tg_line_points() for direct access to the points.

See also

tg_line_num_segments()

int tg_line_num_segments(const struct tg_line *line);

Returns the number of segments.

Parameters

  • line: Input line

Return

  • Number of segments

See also

tg_line_segment_at()

struct tg_segment tg_line_segment_at(const struct tg_line *line, int index);

Returns the segment at index.

Parameters

  • line: Input line
  • index: Index of segment

Return

  • The segment at index

See also

tg_line_clockwise()

bool tg_line_clockwise(const struct tg_line *line);

Returns true if winding order is clockwise.

Parameters

  • line: Input line

Return

  • True if clockwise
  • False if counter-clockwise

See also

tg_line_index_spread()

int tg_line_index_spread(const struct tg_line *line);

Returns the indexing spread for a line.

The "spread" is the number of segments or rectangles that are grouped together to produce a unioned rectangle that is stored at a higher level.

For a tree based structure, this would be the number of items per node.

Parameters

  • line: Input line

Return

  • The spread, default is 16
  • Zero if line has no indexing

See also

tg_line_index_num_levels()

int tg_line_index_num_levels(const struct tg_line *line);

Returns the number of levels.

Parameters

  • line: Input line

Return

  • The number of levels
  • Zero if line has no indexing

See also

tg_line_index_level_num_rects()

int tg_line_index_level_num_rects(const struct tg_line *line, int levelidx);

Returns the number of rectangles at level.

Parameters

  • line: Input line
  • levelidx: The index of level

Return

  • The number of index levels
  • Zero if line has no indexing or levelidx is out of bounds.

See also

tg_line_index_level_rect()

struct tg_rect tg_line_index_level_rect(const struct tg_line *line, int levelidx, int rectidx);

Returns a specific level rectangle.

Parameters

  • line: Input line
  • levelidx: The index of level
  • rectidx: The index of rectangle

Return

  • The rectangle
  • Empty rectangle if line has no indexing, or levelidx or rectidx is out of bounds.

See also

tg_line_nearest_segment()

bool tg_line_nearest_segment(const struct tg_line *line, double(*rect_dist)(struct tg_rect rect, int *more, void *udata), double(*seg_dist)(struct tg_segment seg, int *more, void *udata), bool(*iter)(struct tg_segment seg, double dist, int index, void *udata), void *udata);

Iterates over segments from nearest to farthest.

See also

tg_line_line_search()

void tg_line_line_search(const struct tg_line *a, const struct tg_line *b, bool(*iter)(struct tg_segment aseg, int aidx, struct tg_segment bseg, int bidx, void *udata), void *udata);

Iterates over all segments in line A that intersect with segments in line B.

Note

  • This efficently uses the indexes of each geometry, if available.

See also

tg_line_length()

double tg_line_length(const struct tg_line *line);

Calculate the length of a line.

tg_poly_new()

struct tg_poly *tg_poly_new(const struct tg_ring *exterior, const struct tg_ring *const holes[], int nholes);

Creates a polygon.

Parameters

  • exterior: Exterior ring
  • holes: Array of interior rings that are holes
  • nholes: Number of holes in array

Return

  • A newly allocated polygon
  • NULL if out of memory
  • NULL if exterior or any holes are NULL

Note

  • A tg_poly can be safely upcasted to a tg_geom. (struct tg_geom*)poly

See also

tg_poly_free()

void tg_poly_free(struct tg_poly *poly);

Releases the memory associated with a polygon.

Parameters

  • poly: Input polygon

See also

tg_poly_clone()

struct tg_poly *tg_poly_clone(const struct tg_poly *poly);

Clones a polygon.

Parameters

  • poly: Input polygon, caller retains ownership.

Return

  • A duplicate of the provided polygon.

Note

  • The caller is responsible for freeing with tg_poly_free().
  • This method of cloning uses implicit sharing through an atomic reference counter.

See also

tg_poly_copy()

struct tg_poly *tg_poly_copy(const struct tg_poly *poly);

Copies a polygon.

Parameters

  • poly: Input polygon, caller retains ownership.

Return

  • A duplicate of the provided polygon.
  • NULL if out of memory

Note

  • The caller is responsible for freeing with tg_poly_free().
  • This method performs a deep copy of the entire geometry to new memory.

See also

tg_poly_memsize()

size_t tg_poly_memsize(const struct tg_poly *poly);

Returns the allocation size of the polygon.

Parameters

  • poly: Input polygon

Return

  • Size of polygon in bytes

See also

tg_poly_exterior()

const struct tg_ring *tg_poly_exterior(const struct tg_poly *poly);

Returns the exterior ring.

Parameters

  • poly: Input polygon

Return

  • Exterior ring

Note

  • The polygon maintains ownership of the exterior ring.

See also

tg_poly_num_holes()

int tg_poly_num_holes(const struct tg_poly *poly);

Returns the number of interior holes.

Parameters

  • poly: Input polygon

Return

  • Number of holes

See also

tg_poly_hole_at()

const struct tg_ring *tg_poly_hole_at(const struct tg_poly *poly, int index);

Returns an interior hole.

Parameters

  • poly: Input polygon
  • index: Index of hole

Return

  • Ring hole

See also

tg_poly_rect()

struct tg_rect tg_poly_rect(const struct tg_poly *poly);

Returns the minimum bounding rectangle of a polygon.

See also

tg_poly_clockwise()

bool tg_poly_clockwise(const struct tg_poly *poly);

Returns true if winding order is clockwise.

Parameters

  • poly: Input polygon

Return

  • True if clockwise
  • False if counter-clockwise

See also

tg_env_set_allocator()

void tg_env_set_allocator(void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *));

Allow for configuring a custom allocator.

This overrides the built-in malloc, realloc, and free functions for all TG operations.

Warning

  • This function, if needed, should be called only once at program start up and prior to calling any other tg_*() function.

See also

tg_env_set_index()

void tg_env_set_index(enum tg_index ix);

Set the geometry indexing default.

This is a global override to the indexing for all yet-to-be created geometries.

Warning

  • This function, if needed, should be called only once at program start up and prior to calling any other tg_*() function.

See also

tg_env_set_index_spread()

void tg_env_set_index_spread(int spread);

Set the default index spread.

The "spread" is how many rectangles are grouped together on an indexed level before propagating up to a higher level.

Default is 16.

This is a global override to the indexing spread for all yet-to-be created geometries.

Warning

  • This function, if needed, should be called only once at program start up and prior to calling any other tg_*() function.

See also

Generated with the help of doxygen