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_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 the polygon boundary vertices 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.

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 HydroCouple. All rights reserved.

License\n MIT License

Function Documentation

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

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

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
	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.

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

	engine	Engine handle.
	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.

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.

Parameters

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

Returns

SWMM_OK on success, or an error code.

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.

Parameters

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

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
	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.

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

	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).
	count	Number of nodes (should equal swmm_node_count()).

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
	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.

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 the polygon boundary vertices for a subcatchment.

Parameters

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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.

Parameters

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

Returns

SWMM_OK on success, or an error code.