#include <terrainsizefield.h>

Collaboration diagram for mesh::TerrainSizeField:

Public Member Functions
bool	build (GDALDataset *ds, int band, int col0, int row0, int cols, int rows, const TerrainSizeOptions &opt, const std::function< bool(double)> &progress={})
	Replace this terrain-size grid by streaming a borrowed raster window, or stream rows only.

bool	buildFromFile (const QString &path, int band, double gx0, double gy0, double gx1, double gy1, const TerrainSizeOptions &opt, const std::function< bool(double)> &progress={})
	Open a read-only raster and build over the clipped pixel envelope of a native-CRS box.

double	sizeAtGeo (double x, double y) const
	Read resolved pixel size multiplied by mean native raster pixel spacing.

double	pixelSize () const
	Read mean absolute diagonal geotransform pixel spacing stored by buildFromFile().

QPointF	windowPixelToGeo (double px, double py) const
	Transform a fractional window-stream pixel coordinate to the retained native raster frame.

bool	buildFromGrid (const float *z, int cols, int rows, const TerrainSizeOptions &opt)
	Build from a borrowed in-memory row-major float elevation grid using aligned dyadic bands.

double	sizePixelsAt (double px, double py) const
	Read the nearest output-cell resolved size using absolute source-raster pixel coordinates.

bool	isValid () const
	Check whether stored output dimensions are positive.

int	outCols () const
	Read allocated terrain-size output column count.

int	outRows () const
	Read allocated terrain-size output row count.

int	outLevel () const
	Read the retained output-grid dyadic exponent.

int	levelsUsed () const
	Read the retained maximum dyadic level available to the computation.

const QVector< float > &	cells () const
	Borrow the row-major resolved-size grid owned by this field.

QString	errorMsg () const
	Copy the latest checked build diagnostic.

Member Function Documentation

◆ build()

bool mesh::TerrainSizeField::build	(	GDALDataset *	ds,
		int	band,
		int	col0,
		int	row0,
		int	cols,
		int	rows,
		const TerrainSizeOptions &	opt,
		const std::function< bool(double)> &	progress = `{}`
	)

Replace this terrain-size grid by streaming a borrowed raster window, or stream rows only.

Parameters

[in]	ds	Required borrowed open GDAL dataset, not closed or retained. Caller ensures GDAL registration and exclusive access during reads; no dataset writes occur.
[in]	band	Positive one-based band index; a missing GDAL band returns false.
[in]	col0	Nonnegative source-window first column; window must lie within the raster.
[in]	row0	Nonnegative source-window first row, same bounds contract.
[in]	cols	Positive source-window width, all size/index products and additions must be representable.
[in]	rows	Positive source-window height, same arithmetic requirement.
[in]	opt	Borrowed policy. Normal mode requires finite positive tolerance in raw DEM z units; outLevel/maxLevel must permit signed-int shifts/additions (normally 1..30, with count headroom). Band budget lowers maxLevel only to outLevel, so it is not an absolute memory ceiling. rowsOnly skips size storage/tolerance tests, streams an averaged grid with max(1,decimation), at least one row/band. rowSink is called synchronously with temporary read-only float rows, index/cols/rows of the actual stream; never retain its pointers. Declared finite NoData is converted to NaN before delivery.
[in]	progress	Optional synchronous fraction callback, called after each completed band in (0,1]; false cancels. Neither callback may mutate/reenter this instance or dataset; exceptions propagate.

Returns: True after streaming/computation, including rowsOnly mode where isValid() remains false; false for checked input/band/read failure or cancellation, with errorMsg() and cleared size dimensions. Prior grid is discarded at entry. Callback side effects/rows already delivered are not rolled back; exceptions may leave partial arrays/dimensions. Raw build does not initialize georeferencing for sizeAtGeo()/windowPixelToGeo(); use buildFromFile() for those. Allocates temporary bands/grids, retains no dataset/options/callback references and requires exclusive field access.

Build over the pixel window [col0, col0+cols) × [row0, row0+rows) of band band. progress receives a fraction in [0,1]; returning false cancels (build returns false, errorMsg set).

Here is the caller graph for this function:

◆ buildFromFile()

bool mesh::TerrainSizeField::buildFromFile	(	const QString &	path,
		int	band,
		double	gx0,
		double	gy0,
		double	gx1,
		double	gy1,
		const TerrainSizeOptions &	opt,
		const std::function< bool(double)> &	progress = `{}`
	)

Open a read-only raster and build over the clipped pixel envelope of a native-CRS box.

Parameters

[in]	path	Borrowed GDAL-readable UTF-8 pathname, unchanged; GDAL registration is caller managed.
[in]	band	Positive one-based band passed to build().
[in]	gx0	First box x coordinate in native raster CRS units, finite and transformable to int-range pixels.
[in]	gy0	First box y coordinate under the same representability requirement.
[in]	gx1	Opposite box x; all four box corners are inverse-transformed before taking the pixel envelope.
[in]	gy1	Opposite box y in the same CRS, unchanged; no CRS reprojection occurs.
[in]	opt	Borrowed streaming/size policy, same bounds/callback/units contract as build().
[in]	progress	Optional synchronous progress callback; false cancels after a band. Must not retain row pointers through opt.rowSink or reenter this instance; exceptions propagate.

Returns: True for completed build, including rowsOnly without a size grid; false with errorMsg() for open/geotransform/inversion/build failures, leaving no prior usable grid. Owns/closes the temporary GDAL dataset on normal return; exceptional callback/allocation unwinding has no added cleanup guarantee. Stores affine transforms, mean diagonal pixel size and window offsets for later coordinate queries. No source raster mutation, retained callbacks or transactional rollback of callback side effects.

Open path with GDAL and build over the pixel window that covers the georeferenced box [gx0, gx1] × [gy0, gy1] (raster CRS), clipped to the raster. Keeps the geotransform for sizeAtGeo().

Here is the call graph for this function:

◆ buildFromGrid()

bool mesh::TerrainSizeField::buildFromGrid	(	const float *	z,
		int	cols,
		int	rows,
		const TerrainSizeOptions &	opt
	)

Build from a borrowed in-memory row-major float elevation grid using aligned dyadic bands.

Parameters

[in]	z	Required readable cols*rows float values, NaN for NoData; unchanged and not retained. Infinity is not specially rejected and should be excluded by caller.
[in]	cols	Positive width, all products/additions/index arithmetic must fit the used int/qint64 ranges.
[in]	rows	Positive height, same arithmetic contract.
[in]	opt	Borrowed policy with finite positive tolerance in z units and representable shift levels. This overload ignores rowsOnly/decimation/maxBandBytes, always builds a size grid and processes bands of 2^maxLevel rows. rowSink receives borrowed original input rows synchronously; pointers must not be retained or used to mutate input, and callback exceptions propagate.

Returns: False for null/nonpositive grid or invalid tolerance, with prior grid discarded and empty error text; true after computation and 3x3 minimum dilation. Does not reset stored georeference/decimation, perform GDAL IO or offer cancellation. Allocates level/output scratch arrays, requires exclusive access; exceptions can leave partial state and delivered-row side effects are not rolled back.

Same computation on an in-memory row-major float grid (NaN = nodata), the whole grid as one band. For tests and small rasters.

◆ cells()

const QVector< float > & mesh::TerrainSizeField::cells ( ) const

inline

Borrow the row-major resolved-size grid owned by this field.

Returns: Const reference to outCols*outRows float sizes in pixels after a successful normal build; empty for rowsOnly/checked failure. Reference/content views are invalidated by rebuild/assignment or destruction, so do not retain across mutation or delete storage. No copy or allocation; exclusive rebuild access is required, stable concurrent reads are safe.

◆ errorMsg()

QString mesh::TerrainSizeField::errorMsg ( ) const

inline

Copy the latest checked build diagnostic.

Returns: Owned message, empty initially or after successful build and also after some in-memory validation refusals. Cleared at build entry, so use the boolean result for success rather than text alone. No dataset IO, allocation beyond QString semantics or state mutation.

◆ isValid()

bool mesh::TerrainSizeField::isValid ( ) const

inline

Check whether stored output dimensions are positive.

Returns: True after successful size construction, false initially, on checked failure or after rowsOnly streaming. Does not verify array completeness after exceptions or current georeference consistency. Constant read-only state query, no allocation or dataset access.

Here is the caller graph for this function:

◆ levelsUsed()

int mesh::TerrainSizeField::levelsUsed ( ) const

inline

Read the retained maximum dyadic level available to the computation.

Returns: Configured effective maximum exponent, initially 10; streaming may lower it to fit the band budget, never below outLevel. It is a limit, not a count of levels every block actually passed/tested. May be stale after failure, read-only query.

◆ outCols()

int mesh::TerrainSizeField::outCols ( ) const

inline

Read allocated terrain-size output column count.

Returns: Output columns, zero for rowsOnly/invalid/checked failure; successful grid rounds width up to 2^outLevel pixel cells. No state mutation or IO.

◆ outLevel()

int mesh::TerrainSizeField::outLevel ( ) const

inline

Read the retained output-grid dyadic exponent.

Returns: Exponent whose power of two is source pixels per output cell, initially 2 and clamped to at least 1 by builders. It may retain a prior/partial value after failure; use only with a completed build. No IO, allocation or mutation.

◆ outRows()

int mesh::TerrainSizeField::outRows ( ) const

inline

Read allocated terrain-size output row count.

Returns: Output rows, zero for rowsOnly/invalid/checked failure; successful grid rounds height up to 2^outLevel pixel cells. No state mutation or IO.

◆ pixelSize()

double mesh::TerrainSizeField::pixelSize ( ) const

inline

Read mean absolute diagonal geotransform pixel spacing stored by buildFromFile().

Returns: Native raster-CRS units per pixel, initially zero; rotation/shear terms are not full vector lengths. Raw build()/buildFromGrid() do not refresh this value, so it can be stale after those calls. No IO, coordinate conversion or field mutation.

Mean absolute pixel size in raster-CRS units (buildFromFile).

◆ sizeAtGeo()

double mesh::TerrainSizeField::sizeAtGeo	(	double	x,
		double	y
	)		const

Read resolved pixel size multiplied by mean native raster pixel spacing.

Parameters

[in]	x	Finite native raster-CRS x, unchanged; require a successful corresponding buildFromFile().
[in]	y	Finite native raster-CRS y, unchanged.

Returns: Resolved size in native raster-CRS length units, zero for invalid field/nonpositive stored pixel size or outside the output-grid envelope. Last output cells can cover padded pixels beyond the original clipped window. Uses nearest output-cell lookup, not interpolation, metric CRS conversion or a final triangle-error certificate. Reads owned arrays only, safe concurrent queries without mutation.

Resolved size in raster-CRS linear units at a raster-CRS coordinate (pixels × mean pixel size). Only after buildFromFile(); 0 outside the output-grid envelope.

Here is the call graph for this function:

◆ sizePixelsAt()

double mesh::TerrainSizeField::sizePixelsAt	(	double	px,
		double	py
	)		const

Read the nearest output-cell resolved size using absolute source-raster pixel coordinates.

Parameters

[in]	px	Finite absolute pixel column, relative to raster origin rather than window origin.
[in]	py	Finite absolute pixel row, same convention; invalid/nonfinite coordinates return zero.

Returns: Resolved edge size in pixels, zero when invalid or outside the allocated output-grid envelope. The rounded last output cell can extend past the original window, and is not clipped to m_cols/m_rows. No bilinear interpolation, allocation, georeference lookup or mutation; require completed valid grid.

Resolved size in PIXELS at fractional pixel coordinates (relative to the raster, not the window). 0 outside the output-grid envelope or when the field is empty. Nearest output cell — sizes are min-combined and gradation-limited downstream, so no interpolation is wanted here.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ windowPixelToGeo()

QPointF mesh::TerrainSizeField::windowPixelToGeo	(	double	px,
		double	py
	)		const

Transform a fractional window-stream pixel coordinate to the retained native raster frame.

Parameters

[in]	px	Fractional window-relative column, center at i+0.5; multiplied by the last stream decimation.
[in]	py	Fractional window-relative row, center at j+0.5, same convention; outside values extrapolate.

Returns: Owned native-CRS point from window offsets plus retained affine transform, without validity, finite-input or bounds checks. Requires matching buildFromFile() setup; raw/in-memory builds can leave georeference/decimation values stale. Pure read-only arithmetic, no allocation beyond value storage.

Raster-CRS coordinate of a fractional WINDOW pixel position (pixel (0, 0) spans [0, 1)², its centre is (0.5, 0.5)). Only after buildFromFile().

The documentation for this class was generated from the following files:

/home/runner/work/openswmm.gui/openswmm.gui/include/mesh/terrainsizefield.h
/home/runner/work/openswmm.gui/openswmm.gui/src/mesh/terrainsizefield.cpp

Public Member Functions

Member Function Documentation

◆ build()

◆ buildFromFile()

◆ buildFromGrid()

◆ cells()

◆ errorMsg()

◆ isValid()

◆ levelsUsed()

◆ outCols()

◆ outLevel()

◆ outRows()

◆ pixelSize()

◆ sizeAtGeo()

◆ sizePixelsAt()

◆ windowPixelToGeo()