openswmm_spatial.h File Reference

OpenSWMM Engine — Spatial Frame C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_spatial.h:

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

Go to the source code of this file.

Functions
SWMM_ENGINE_API int	swmm_spatial_set_crs (SWMM_Engine engine, const char *crs)
	Set the coordinate reference system string for the model.
SWMM_ENGINE_API int	swmm_spatial_get_crs (SWMM_Engine engine, char *buf, int buflen)
	Get the coordinate reference system string.
SWMM_ENGINE_API int	swmm_spatial_set_node_coord (SWMM_Engine engine, int idx, double x, double y)
	Set the X/Y coordinates for a node.
SWMM_ENGINE_API int	swmm_spatial_node_has_coord (SWMM_Engine engine, int idx, int *present)
	Read coordinate provenance without confusing an authored origin with missing data.
SWMM_ENGINE_API int	swmm_spatial_get_node_coord (SWMM_Engine engine, int idx, double *x, double *y)
	Get the X/Y coordinates for a node.
SWMM_ENGINE_API int	swmm_spatial_get_node_coords_bulk (SWMM_Engine engine, double *x_buf, double *y_buf, int count)
	Get X/Y coordinates for all nodes in a single call.
SWMM_ENGINE_API int	swmm_spatial_set_node_coords_bulk (SWMM_Engine engine, const double *x_buf, const double *y_buf, int count)
	Set X/Y coordinates for all nodes in a single call.
SWMM_ENGINE_API int	swmm_spatial_set_link_coord (SWMM_Engine engine, int idx, double x, double y)
	Set the centroid/midpoint X/Y coordinate for a link.
SWMM_ENGINE_API int	swmm_spatial_get_link_coord (SWMM_Engine engine, int idx, double *x, double *y)
	Get the centroid/midpoint X/Y coordinate for a link.
SWMM_ENGINE_API int	swmm_spatial_set_link_vertices (SWMM_Engine engine, int idx, const double *x, const double *y, int count)
	Set the polyline vertices for a link.
SWMM_ENGINE_API int	swmm_spatial_get_link_vertex_count (SWMM_Engine engine, int idx, int *count)
	Get the number of polyline vertices for a link.
SWMM_ENGINE_API int	swmm_spatial_get_link_vertices (SWMM_Engine engine, int idx, double *x, double *y, int max_count)
	Get the polyline vertices for a link.
SWMM_ENGINE_API int	swmm_spatial_set_subcatch_coord (SWMM_Engine engine, int idx, double x, double y)
	Set the centroid X/Y coordinate for a subcatchment.
SWMM_ENGINE_API int	swmm_spatial_get_subcatch_coord (SWMM_Engine engine, int idx, double *x, double *y)
	Get the centroid X/Y coordinate for a subcatchment.
SWMM_ENGINE_API int	swmm_spatial_set_subcatch_polygon (SWMM_Engine engine, int idx, const double *x, const double *y, int count)
	Set the polygon boundary vertices for a subcatchment.
SWMM_ENGINE_API int	swmm_spatial_get_subcatch_polygon_count (SWMM_Engine engine, int idx, int *count)
	Get the number of polygon vertices for a subcatchment.
SWMM_ENGINE_API int	swmm_spatial_get_subcatch_polygon (SWMM_Engine engine, int idx, double *x, double *y, int max_count)
	Get all polygon boundary rings for a subcatchment.
SWMM_ENGINE_API int	swmm_spatial_set_gage_coord (SWMM_Engine engine, int idx, double x, double y)
	Set the X/Y coordinate for a rain gage.
SWMM_ENGINE_API int	swmm_spatial_get_gage_coord (SWMM_Engine engine, int idx, double *x, double *y)
	Get the X/Y coordinate for a rain gage.
SWMM_ENGINE_API int	swmm_spatial_get_map_dimensions (SWMM_Engine engine, double *x1, double *y1, double *x2, double *y2)
	Read the stored map display extent.
SWMM_ENGINE_API int	swmm_spatial_set_map_dimensions (SWMM_Engine engine, double x1, double y1, double x2, double y2)
	Replace the stored map display extent.
SWMM_ENGINE_API int	swmm_spatial_get_map_units (SWMM_Engine engine, char *buf, int buflen)
	Copy the stored map-unit label.
SWMM_ENGINE_API int	swmm_spatial_set_map_units (SWMM_Engine engine, const char *units)
	Copy and uppercase the map-unit label.
SWMM_ENGINE_API int	swmm_spatial_get_annotation (SWMM_Engine engine, const char *section, char *buf, int buflen, int *required)
	Join stored annotation-section lines into text without a section header.
SWMM_ENGINE_API int	swmm_spatial_set_annotation (SWMM_Engine engine, const char *section, const char *text)
	Replace the passthrough lines of a supported annotation section.

Detailed Description

OpenSWMM Engine — Spatial Frame C API.

CRS management, node/link/subcatchment/gage coordinates, link polyline vertices, and subcatchment polygon vertices.

See also

openswmm_engine.h

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License

Apache-2.0

Function Documentation

swmm_spatial_get_annotation()

SWMM_ENGINE_API int swmm_spatial_get_annotation	(	SWMM_Engine	engine,
		const char *	section,
		char *	buf,
		int	buflen,
		int *	required )

Join stored annotation-section lines into text without a section header.

Does not interpret annotation content; stored lines are joined with LF. Both buf and required may be NULL for a valid section.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[in]	section	Non-null case-insensitive LABELS, BACKDROP, PROFILE or PROFILES token.
[out]	buf	Optional caller-owned text destination. NULL queries required size regardless of buflen; non-null output is NUL-terminated and silently truncated.
[in]	buflen	Destination capacity in bytes including NUL; must be positive when buf is non-null.
[out]	required	Optional full byte count INCLUDING NUL, written before short/nonpositive buffer handling. Empty/absent section requires 1 byte.

Returns

SWMM_OK including truncation/size query; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for unknown/null section or a non-null buffer with buflen<=0.

swmm_spatial_get_crs()

SWMM_ENGINE_API int swmm_spatial_get_crs	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen )

Get the coordinate reference system string.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer to receive the CRS string.
[in]	buflen	Size of buf in bytes.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. buf must be non-null and buflen positive or BADPARAM is returned. Copies the spatial-frame CRS (empty allowed), NUL-terminated and silently truncated to buflen-1 bytes.

swmm_spatial_get_gage_coord()

SWMM_ENGINE_API int swmm_spatial_get_gage_coord	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y )

Get the X/Y coordinate for a rain gage.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based gage index.
[out]	x	Receives the X coordinate.
[out]	y	Receives the Y coordinate.

Returns

SWMM_OK on success, or an error code.

Note

x may be NULL to suppress that output. y may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_spatial_get_link_coord()

SWMM_ENGINE_API int swmm_spatial_get_link_coord	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y )

Get the centroid/midpoint X/Y coordinate for a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	x	Receives the X coordinate.
[out]	y	Receives the Y coordinate.

Returns

SWMM_OK on success, or an error code.

Note

x may be NULL to suppress that output. y may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_spatial_get_link_vertex_count()

SWMM_ENGINE_API int swmm_spatial_get_link_vertex_count	(	SWMM_Engine	engine,
		int	idx,
		int *	count )

Get the number of polyline vertices for a link.

Count includes the upstream node coordinate at index 0, followed by stored interior vertices (if any), and the downstream node coordinate as the final index.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	count	Receives the vertex count.

Returns

SWMM_OK on success, or an error code.

Note

count may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Only valid endpoint indices are included, so an unconnected link can have fewer than two endpoint vertices.

swmm_spatial_get_link_vertices()

SWMM_ENGINE_API int swmm_spatial_get_link_vertices	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y,
		int	max_count )

Get the polyline vertices for a link.

Returned vertices are ordered as: 1) upstream node coordinate at index 0, 2) interior vertices in stored order, 3) downstream node coordinate as the final vertex.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	x	Caller-allocated buffer for X coordinates.
[out]	y	Caller-allocated buffer for Y coordinates.
[in]	max_count	Maximum number of vertices to write to the buffers.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Both output arrays must be non-null and max_count positive or BADPARAM is returned. Returns a silently truncated prefix when capacity is short; query the corresponding count first to allocate complete arrays. No written-count output is provided.

swmm_spatial_get_map_dimensions()

SWMM_ENGINE_API int swmm_spatial_get_map_dimensions	(	SWMM_Engine	engine,
		double *	x1,
		double *	y1,
		double *	x2,
		double *	y2 )

Read the stored map display extent.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[out]	x1	Optional destination for the first X coordinate in map/CRS units.
[out]	y1	Optional destination for the first Y coordinate in map/CRS units.
[out]	x2	Optional destination for the second X coordinate in map/CRS units.
[out]	y2	Optional destination for the second Y coordinate in map/CRS units.

Returns

SWMM_OK, including suppressed outputs; SWMM_ERR_BADHANDLE for null engine.

swmm_spatial_get_map_units()

SWMM_ENGINE_API int swmm_spatial_get_map_units	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen )

Copy the stored map-unit label.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[out]	buf	Non-null caller-owned text destination, empty when unspecified; NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive capacity including NUL, in bytes.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for invalid buffer.

swmm_spatial_get_node_coord()

SWMM_ENGINE_API int swmm_spatial_get_node_coord	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y )

Get the X/Y coordinates for a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	x	Receives the X coordinate.
[out]	y	Receives the Y coordinate.

Returns

SWMM_OK on success, or an error code.

Note

x may be NULL to suppress that output. y may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_spatial_get_node_coords_bulk()

SWMM_ENGINE_API int swmm_spatial_get_node_coords_bulk	(	SWMM_Engine	engine,
		double *	x_buf,
		double *	y_buf,
		int	count )

Get X/Y coordinates for all nodes in a single call.

Parameters

[in]	engine	Engine handle.
[out]	x_buf	Caller-allocated buffer for X coordinates (count elements).
[out]	y_buf	Caller-allocated buffer for Y coordinates (count elements).
[in]	count	Number of nodes (should equal swmm_node_count()).

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. Both coordinate arrays must be non-null and count positive or BADPARAM is returned. Copies min(count,node count) elements in CRS units; any tail remains unchanged.

swmm_spatial_get_subcatch_coord()

SWMM_ENGINE_API int swmm_spatial_get_subcatch_coord	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y )

Get the centroid X/Y coordinate for a subcatchment.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based subcatchment index.
[out]	x	Receives the X coordinate.
[out]	y	Receives the Y coordinate.

Returns

SWMM_OK on success, or an error code.

Note

x may be NULL to suppress that output. y may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_spatial_get_subcatch_polygon()

SWMM_ENGINE_API int swmm_spatial_get_subcatch_polygon	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y,
		int	max_count )

Get all polygon boundary rings for a subcatchment.

Multiple rings are concatenated with explicit closing XY vertices; the last ring may be open. Counts include repeated closing vertices.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based subcatchment index.
[out]	x	Caller-allocated buffer for X coordinates.
[out]	y	Caller-allocated buffer for Y coordinates.
[in]	max_count	Maximum number of vertices to write to the buffers.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Both output arrays must be non-null and max_count positive or BADPARAM is returned. Returns a silently truncated prefix when capacity is short; query the corresponding count first to allocate complete arrays. No written-count output is provided.

swmm_spatial_get_subcatch_polygon_count()

SWMM_ENGINE_API int swmm_spatial_get_subcatch_polygon_count	(	SWMM_Engine	engine,
		int	idx,
		int *	count )

Get the number of polygon vertices for a subcatchment.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based subcatchment index.
[out]	count	Receives the polygon vertex count.

Returns

SWMM_OK on success, or an error code.

Note

count may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_spatial_node_has_coord()

SWMM_ENGINE_API int swmm_spatial_node_has_coord	(	SWMM_Engine	engine,
		int	idx,
		int *	present )

Read coordinate provenance without confusing an authored origin with missing data.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[in]	idx	Zero-based existing node index.
[out]	present	Non-null destination: 1 when coordinate provenance is present, otherwise 0. An authored (0,0) may be present.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid node, or SWMM_ERR_BADPARAM for null present.

swmm_spatial_set_annotation()

SWMM_ENGINE_API int swmm_spatial_set_annotation	(	SWMM_Engine	engine,
		const char *	section,
		const char *	text )

Replace the passthrough lines of a supported annotation section.

Internal blank lines are retained; a trailing LF does not create a final additional empty line. Stores text for later serialization without interpreting drawing/profile syntax.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[in]	section	Non-null case-insensitive LABELS, BACKDROP, PROFILE or PROFILES token.
[in]	text	Borrowed NUL-terminated content to copy; NULL/empty removes the section. LF separates lines; CR bytes are discarded.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null/unsupported section.

swmm_spatial_set_crs()

SWMM_ENGINE_API int swmm_spatial_set_crs	(	SWMM_Engine	engine,
		const char *	crs )

Set the coordinate reference system string for the model.

The CRS string is stored as metadata (e.g., an EPSG code or WKT string). It is not used for coordinate transformations but is preserved in hot start files for consistency checking.

Parameters

[in]	engine	Engine handle.
[in]	crs	Null-terminated CRS string (e.g., "EPSG:4326").

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. crs must be non-null; empty clears it. Copies the string to both spatial and OPTIONS CRS metadata without validating it or transforming coordinates.

swmm_spatial_set_gage_coord()

SWMM_ENGINE_API int swmm_spatial_set_gage_coord	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double	y )

Set the X/Y coordinate for a rain gage.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based gage index.
[in]	x	X coordinate in CRS units.
[in]	y	Y coordinate in CRS units.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Coordinates are copied without finite/range validation and do not reproject or recompute other geometry.

swmm_spatial_set_link_coord()

SWMM_ENGINE_API int swmm_spatial_set_link_coord	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double	y )

Set the centroid/midpoint X/Y coordinate for a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	x	X coordinate in CRS units.
[in]	y	Y coordinate in CRS units.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Coordinates are copied without finite/range validation and do not reproject or recompute other geometry.

swmm_spatial_set_link_vertices()

SWMM_ENGINE_API int swmm_spatial_set_link_vertices	(	SWMM_Engine	engine,
		int	idx,
		const double *	x,
		const double *	y,
		int	count )

Set the polyline vertices for a link.

Vertices define the intermediate points of a link's path between its upstream and downstream nodes.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	x	Array of vertex X coordinates.
[in]	y	Array of vertex Y coordinates.
[in]	count	Number of vertices.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Arrays are copied; caller retains ownership. count must be nonnegative and define valid pointer ranges; positive counts require both arrays or BADPARAM is returned. No polygon validity, closure, orientation or finite-coordinate validation is performed. Stores interior vertices only; getters add each valid endpoint-node coordinate. Passing getter output back unchanged would duplicate endpoints as interiors.

swmm_spatial_set_map_dimensions()

SWMM_ENGINE_API int swmm_spatial_set_map_dimensions	(	SWMM_Engine	engine,
		double	x1,
		double	y1,
		double	x2,
		double	y2 )

Replace the stored map display extent.

Does not require minimum/maximum ordering, change object coordinates or compute a new bounding box.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[in]	x1	Finite first X coordinate in map/CRS units.
[in]	y1	Finite first Y coordinate in map/CRS units.
[in]	x2	Finite second X coordinate in map/CRS units.
[in]	y2	Finite second Y coordinate in map/CRS units.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for any nonfinite coordinate.

swmm_spatial_set_map_units()

SWMM_ENGINE_API int swmm_spatial_set_map_units	(	SWMM_Engine	engine,
		const char *	units )

Copy and uppercase the map-unit label.

Does not restrict the label vocabulary, rescale geometry or reproject coordinates.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. No spatial-edit lifecycle guard is imposed.
[in]	units	Non-null NUL-terminated label (such as FEET, METERS, DEGREES or NONE); empty is allowed.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null units.

swmm_spatial_set_node_coord()

SWMM_ENGINE_API int swmm_spatial_set_node_coord	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double	y )

Set the X/Y coordinates for a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	x	X coordinate in CRS units.
[in]	y	Y coordinate in CRS units.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Coordinates are copied without finite/range validation and do not reproject or recompute other geometry. Marks this node coordinate as explicitly present, including when x=y=0.

swmm_spatial_set_node_coords_bulk()

SWMM_ENGINE_API int swmm_spatial_set_node_coords_bulk	(	SWMM_Engine	engine,
		const double *	x_buf,
		const double *	y_buf,
		int	count )

Set X/Y coordinates for all nodes in a single call.

Parameters

[in]	engine	Engine handle.
[in]	x_buf	Array of X coordinates (count elements).
[in]	y_buf	Array of Y coordinates (count elements).
[in]	count	Number of nodes.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. Both coordinate arrays must be non-null and count positive or BADPARAM is returned. Copies min(count,node count) elements in CRS units; any tail remains unchanged. Unlike the scalar node-coordinate setter, this wrapper does not set node_has_xy provenance flags.

swmm_spatial_set_subcatch_coord()

SWMM_ENGINE_API int swmm_spatial_set_subcatch_coord	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double	y )

Set the centroid X/Y coordinate for a subcatchment.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based subcatchment index.
[in]	x	X coordinate in CRS units.
[in]	y	Y coordinate in CRS units.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Coordinates are copied without finite/range validation and do not reproject or recompute other geometry.

swmm_spatial_set_subcatch_polygon()

SWMM_ENGINE_API int swmm_spatial_set_subcatch_polygon	(	SWMM_Engine	engine,
		int	idx,
		const double *	x,
		const double *	y,
		int	count )

Set the polygon boundary vertices for a subcatchment.

Multiple rings are concatenated, each closed by repeating its first XY vertex. The final ring may be open. Even/odd containment defines holes.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based subcatchment index.
[in]	x	Array of polygon vertex X coordinates.
[in]	y	Array of polygon vertex Y coordinates.
[in]	count	Number of polygon vertices.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed node/link/subcatchment/gage/pollutant index check returns SWMM_ERR_BADINDEX. Arrays are copied; caller retains ownership. count must be nonnegative and define valid pointer ranges; positive counts require both arrays or BADPARAM is returned. No polygon validity, closure, orientation or finite-coordinate validation is performed.