Namespaces
namespace	raingage

Classes
struct	AquiferPreview

struct	AquiferProcessPreview

struct	AquiferRequest

struct	AquiferRow

struct	AquiferSnapshot

struct	AquiferTarget

struct	GroundwaterQualityRow

struct	GroundwaterSourceRow

struct	GroundwaterSpeciesTerm

struct	GroundwaterTransportPreview

struct	GroundwaterTransportRequest

struct	GroundwaterTransportResult

struct	GroundwaterTransportSnapshot

struct	InfiltrationOwnershipCell

struct	InfiltrationOwnershipPreview

struct	InfiltrationOwnershipSnapshot

struct	MeshAssignmentSampling

struct	RasterFluxRequest

struct	RasterFluxResult

struct	SurfaceOwnershipReview

struct	TransportSpecies

Enumerations
enum class	GroundwaterTransportTarget { InitialQuality , Source }

enum class	GroundwaterSourceDistribution { PerCell , RegionTotal }

enum class	RasterFluxCoverage { Complete , ValidAreaOnly }

Functions
InfiltrationOwnershipPreview	previewInfiltrationOwnership (SWMM_Engine engine, const QStringList &tags, bool removeExplicit)
	Review surface infiltration conflicts with aquifer-owned cells without changing inputs.

bool	applyInfiltrationOwnership (SWMM_Engine engine, const InfiltrationOwnershipSnapshot &expected, const InfiltrationOwnershipSnapshot &desired, QString *error)
	Replace reviewed infiltration inputs after checking for intervening changes.

QString	groundwaterEtForcingStatus (SWMM_Engine engine, const QString &meshMode={})
	Describe the authored atmospheric demand that can drive groundwater ET.

AquiferProcessPreview	previewAquiferProcesses (SWMM_Engine engine, const QString &et, const QString &link, const QString &wilting)
	Validate and review groundwater ET, seepage, and wilting choices without writing.

bool	applyAquiferProcesses (SWMM_Engine engine, const AquiferSnapshot &expected, const AquiferSnapshot &desired, const QString &groundwater, QString *error)
	Apply reviewed groundwater process options after stale-input checks.

QVector< AquiferTarget >	aquiferTargets ()
	Describe assignable aquifer properties and their permitted value ranges.

bool	readAquiferSnapshot (SWMM_Engine engine, AquiferSnapshot snapshot, QString error)
	Capture authored aquifer rows, inheritance flags, options and forcing context.

AquiferPreview	previewAquiferAssignment (const AquiferRequest &request, std::function< bool()> cancelled={})
	Resolve inherited aquifer properties into appended per-cell overrides.

bool	applyAquiferPreview (SWMM_Engine engine, const AquiferPreview &preview, QString *error, std::function< bool(int)> beforeWrite={})
	Append validated overrides while preserving all original authored records.

bool	undoAquiferPreview (SWMM_Engine engine, const AquiferPreview &preview, QString *error)
	Remove only the unchanged suffix produced by an aquifer assignment.

QVector< TransportSpecies >	groundwaterTransportSpecies (SWMM_Engine engine, QString *error=nullptr)
	Read enabled groundwater species and native concentration/mass-rate metadata.

bool	readGroundwaterTransportSnapshot (SWMM_Engine engine, GroundwaterTransportSnapshot snapshot, QString error=nullptr)
	Capture inputs needed for transport validation and stale-preview detection.

GroundwaterTransportPreview	previewGroundwaterTransport (const GroundwaterTransportRequest &request, std::function< bool()> cancelled={})
	Build a validated initial-quality or groundwater-source edit using snapshot data only.

GroundwaterTransportResult	applyGroundwaterTransport (SWMM_Engine engine, const GroundwaterTransportPreview &preview, std::function< bool(int)> beforeWrite={})
	Commit reviewed transport rows with preflight, readback and bounded restoration.

GroundwaterTransportResult	undoGroundwaterTransport (SWMM_Engine engine, const GroundwaterTransportPreview &preview)
	Restore the before state only when the engine still matches the reviewed after state.

MeshAssignmentSampling::SampleResult	sampleMeshAssignment (const MeshAssignmentSampling::Job &job, std::function< bool()> cancelled={}, std::function< void(int, int)> progress={})
	Run a self-contained raster/vector sampling job on the calling thread.

void	runMeshAssignmentSampling (QPromise< MeshAssignmentSampling::SampleResult > &promise, MeshAssignmentSampling::Job job)
	Adapt synchronous sampling to a Qt concurrent promise.

RasterFluxResult	integrateRasterFlux (const RasterFluxRequest &request, std::function< bool()> cancelled={})
	Integrate signed raster flux density over exact cell/pixel intersections.

bool	readSurfaceOwners (SWMM_Engine engine, QVector< int > rows, QString error)
	Read authored surface-owner records while the engine permits editing.

SurfaceOwnershipReview	previewSurfaceOwners (SWMM_Engine engine, const QVector< int > &rows, const std::function< bool(int, int)> &progress={})
	Ask the engine to validate proposed ownership and compute object-area shares.

bool	replaceSurfaceOwners (SWMM_Engine engine, const QVector< int > &rows, const QString &token, QString *error)
	Replace ownership records using the engine-issued preview token.

bool	surfaceOwnershipMeshMatches (SWMM_Engine engine, const SWMM2DMeshLayer layer, QString error)
	Check that the GUI mesh and engine mesh describe the same cells before ownership review.

Enumeration Type Documentation

◆ GroundwaterSourceDistribution

enum class openswmmvis::assignment::GroundwaterSourceDistribution

strong

Enumerator
PerCell
RegionTotal

◆ GroundwaterTransportTarget

enum class openswmmvis::assignment::GroundwaterTransportTarget

strong

Enumerator
InitialQuality
Source

◆ RasterFluxCoverage

enum class openswmmvis::assignment::RasterFluxCoverage

strong

Enumerator
Complete
ValidAreaOnly

Function Documentation

◆ applyAquiferPreview()

bool openswmmvis::assignment::applyAquiferPreview	(	SWMM_Engine	engine,
		const AquiferPreview &	preview,
		QString *	error,
		std::function< bool(int)>	beforeWrite = `{}`
	)

Append validated overrides while preserving all original authored records.

Parameters

[in]	engine	Borrowed engine in BUILDING or OPENED state.
[in]	preview	Error-free preview whose before snapshot must still match the engine.
[out]	error	Optional message, cleared at entry; a rollback failure explicitly requires reloading.
[in]	beforeWrite	Optional synchronous hook receiving a one-based write ordinal; false injects failure before that write.

Returns: True on success, including an empty append. Failure attempts to remove the appended suffix; inspect error if restoration fails.

Here is the call graph for this function:

◆ applyAquiferProcesses()

bool openswmmvis::assignment::applyAquiferProcesses	(	SWMM_Engine	engine,
		const AquiferSnapshot &	expected,
		const AquiferSnapshot &	desired,
		const QString &	groundwater,
		QString *	error
	)

Apply reviewed groundwater process options after stale-input checks.

Parameters

[in]	engine	Borrowed editing engine.
[in]	expected	Snapshot that must still match current rows, options and forcing review.
[in]	desired	Snapshot supplying GW_ET, LINK_SEEPAGE, WILTING_SUCTION and OPTIONS_AUTHORED.
[in]	groundwater	Expected GROUNDWATER enable token captured by the preview.
[out]	error	Optional failure description.

Returns: True when the atomic engine process-options update succeeds; false on stale inputs or engine refusal.

Here is the call graph for this function:

◆ applyGroundwaterTransport()

GroundwaterTransportResult openswmmvis::assignment::applyGroundwaterTransport	(	SWMM_Engine	engine,
		const GroundwaterTransportPreview &	preview,
		std::function< bool(int)>	beforeWrite = `{}`
	)

Commit reviewed transport rows with preflight, readback and bounded restoration.

Parameters

[in]	engine	Borrowed engine in BUILDING or OPENED state; its full snapshot must match the preview before state.
[in]	preview	Error-free validated edit produced by previewGroundwaterTransport().
[in]	beforeWrite	Optional synchronous hook receiving a one-based write ordinal; false prevents that write.

Returns: Success, mutation and restoration flags plus diagnostics. A true changed flag requires marking the project dirty, even after successful restoration, because authoring metadata may have changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ applyInfiltrationOwnership()

bool openswmmvis::assignment::applyInfiltrationOwnership	(	SWMM_Engine	engine,
		const InfiltrationOwnershipSnapshot &	expected,
		const InfiltrationOwnershipSnapshot &	desired,
		QString *	error
	)

Replace reviewed infiltration inputs after checking for intervening changes.

Parameters

[in]	engine	Borrowed engine in BUILDING or OPENED state.
[in]	expected	Exact authored rows and destination that must still exist.
[in]	desired	Reviewed replacement rows and destination; may be a prior snapshot for undo.
[out]	error	Optional failure message; unchanged on success.

Returns: True after both writes succeed. A failed row replacement attempts to restore the old destination.

◆ aquiferTargets()

QVector< AquiferTarget > openswmmvis::assignment::aquiferTargets ( )

Describe assignable aquifer properties and their permitted value ranges.

Returns: Ordered target metadata including unit kinds, exclusive lower bounds and an explicit unsupported FLOW target with its refusal reason.

Here is the caller graph for this function:

◆ groundwaterEtForcingStatus()

QString openswmmvis::assignment::groundwaterEtForcingStatus	(	SWMM_Engine	engine,
		const QString &	meshMode = `{}`
	)

Describe the authored atmospheric demand that can drive groundwater ET.

Parameters

[in]	engine	Borrowed engine whose mesh/climate evaporation settings are inspected.
[in]	meshMode	Optional mesh evaporation mode override; empty reads the current engine option.

Returns: Human-readable forcing review, including missing climate configuration; this is a configuration check rather than simulation-period validation.

Here is the caller graph for this function:

◆ groundwaterTransportSpecies()

QVector< TransportSpecies > openswmmvis::assignment::groundwaterTransportSpecies	(	SWMM_Engine	engine,
		QString *	error = `nullptr`
	)

Read enabled groundwater species and native concentration/mass-rate metadata.

Parameters

[in]	engine	Borrowed engine supplying transport enable flags and species definitions.
[out]	error	Optional diagnostic, cleared at entry.

Returns: Species available for assignment; empty may mean no enabled species or a read failure, distinguished by error.

Here is the caller graph for this function:

◆ integrateRasterFlux()

RasterFluxResult openswmmvis::assignment::integrateRasterFlux	(	const RasterFluxRequest &	request,
		std::function< bool()>	cancelled = `{}`
	)

Integrate signed raster flux density over exact cell/pixel intersections.

Parameters

[in]	request	Read-only raster path, one-based band, distinct nonnegative cell IDs and parallel convex triangular/quadrilateral footprints in mesh CRS. densityUnit must be m/s, mm/h, m/day or in/h.
[in]	cancelled	Optional synchronous cancellation callback; true aborts the entire integration.

Returns: Flows in signed m³/s and coverage areas in m², aligned with requested cells; NaN flow preserves a cell under the selected coverage policy. Error/cancellation clears actionable values.

Requires equivalent projected mesh and source CRSs with valid linear units. Uses original raster resolution, applies scale/offset, honors NoData/masks, and opens its own read-only dataset, so it can run on a worker thread.

◆ previewAquiferAssignment()

AquiferPreview openswmmvis::assignment::previewAquiferAssignment	(	const AquiferRequest &	request,
		std::function< bool()>	cancelled = `{}`
	)

Resolve inherited aquifer properties into appended per-cell overrides.

Parameters

[in]	request	Immutable snapshot, distinct nonnegative engine cell IDs, parallel tags and sampled values. Values use the target property units; NaN may be skipped only with skipNoData.
[in]	cancelled	Optional callback polled in the calling thread; true cancels the preview.

Returns: Validated changed rows and old/new values. Missing base properties, invalid ranges or cancellation set error and clear actionable rows. The engine is never accessed.

Here is the call graph for this function:

◆ previewAquiferProcesses()

AquiferProcessPreview openswmmvis::assignment::previewAquiferProcesses	(	SWMM_Engine	engine,
		const QString &	et,
		const QString &	link,
		const QString &	wilting
	)

Validate and review groundwater ET, seepage, and wilting choices without writing.

Parameters

[in]	engine	Borrowed engine supplying the current aquifer snapshot and enable flag.
[in]	et	AUTO, NONE, BOUNDARY_ET, CAPILLARY_RISE or BOTH.
[in]	link	DEFAULT, ONE_WAY, NONE or TWO_WAY.
[in]	wilting	AUTO or a finite positive suction expressed as text in project length units.

Returns: Before/after options, effective behavior descriptions and forcing review; nonempty error rejects the proposed edit.

Here is the call graph for this function:

◆ previewGroundwaterTransport()

GroundwaterTransportPreview openswmmvis::assignment::previewGroundwaterTransport	(	const GroundwaterTransportRequest &	request,
		std::function< bool()>	cancelled = `{}`
	)

Build a validated initial-quality or groundwater-source edit using snapshot data only.

Parameters

[in]	request	Distinct in-range cell IDs and parallel finite values; initial values use species native concentration units, source flows use signed m³/s. NaN is skipped only when requested.
[in]	cancelled	Optional callback evaluated in the calling thread; true discards actionable changes.

Returns: Before/after snapshots and affected/skipped IDs. On validation failure or cancellation, error is set and after equals before.

Source RegionTotal distribution normalizes positive cell-area weights; soil-layer quality requires enabled layered transport and a valid one-based SIGMA layer in every target cell.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ previewInfiltrationOwnership()

InfiltrationOwnershipPreview openswmmvis::assignment::previewInfiltrationOwnership	(	SWMM_Engine	engine,
		const QStringList &	tags,
		bool	removeExplicit
	)

Review surface infiltration conflicts with aquifer-owned cells without changing inputs.

Parameters

[in]	engine	Borrowed editing engine containing the current mesh and authored infiltration rows.
[in]	tags	One exact engine region tag per cell, in engine cell-index order; unsaved mesh-tag changes are rejected.
[in]	removeExplicit	Whether the proposed rows remove explicit surface methods from aquifer-owned cells.

Returns: Before/after authored rows, per-cell ownership explanations, and migration summaries; nonempty error prevents applying the preview. Obsolete AQUIFER_2D destinations are proposed as LOST.

◆ previewSurfaceOwners()

SurfaceOwnershipReview openswmmvis::assignment::previewSurfaceOwners	(	SWMM_Engine	engine,
		const QVector< int > &	rows,
		const std::function< bool(int, int)> &	progress = `{}`
	)

Ask the engine to validate proposed ownership and compute object-area shares.

Parameters

[in]	engine	Borrowed engine supplying current owners and mesh geometry.
[in]	rows	Proposed encoded ownership records passed to the engine unchanged.
[in]	progress	Optional synchronous (done,total) callback; true continues and false requests cancellation.

Returns: Prior/proposed records, computed shares and a token for stale-preview protection. Apply only when valid is true and the review diagnostics are acceptable.

Performs count and fill preview calls; engine changes between calls produce an error. Does not replace ownership records.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readAquiferSnapshot()

bool openswmmvis::assignment::readAquiferSnapshot	(	SWMM_Engine	engine,
		AquiferSnapshot *	snapshot,
		QString *	error
	)

Capture authored aquifer rows, inheritance flags, options and forcing context.

Parameters

[in]	engine	Borrowed engine; nullptr is rejected.
[out]	snapshot	Non-null destination, replaced only after every read succeeds.
[out]	error	Optional message, cleared at entry and populated on failure.

Returns: True on a complete capture; false leaves the destination unchanged.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readGroundwaterTransportSnapshot()

bool openswmmvis::assignment::readGroundwaterTransportSnapshot	(	SWMM_Engine	engine,
		GroundwaterTransportSnapshot *	snapshot,
		QString *	error = `nullptr`
	)

Capture inputs needed for transport validation and stale-preview detection.

Parameters

[in]	engine	Borrowed engine whose aquifers, active cells, quality, sources, species and time series are read.
[out]	snapshot	Non-null destination, replaced only after a complete successful read.
[out]	error	Optional failure description, cleared at entry.

Returns: True on a complete snapshot; false preserves the previous destination.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readSurfaceOwners()

bool openswmmvis::assignment::readSurfaceOwners	(	SWMM_Engine	engine,
		QVector< int > *	rows,
		QString *	error
	)

Read authored surface-owner records while the engine permits editing.

Parameters

[in]	engine	Borrowed editing engine.
[out]	rows	Non-null destination for encoded owner records; may be resized before a failed fill read.
[out]	error	Non-null failure-message destination; unchanged on success.

Returns: True on a complete count/fill read; false on engine refusal.

Here is the caller graph for this function:

◆ replaceSurfaceOwners()

bool openswmmvis::assignment::replaceSurfaceOwners	(	SWMM_Engine	engine,
		const QVector< int > &	rows,
		const QString &	token,
		QString *	error
	)

Replace ownership records using the engine-issued preview token.

Parameters

[in]	engine	Borrowed editing engine.
[in]	rows	Reviewed encoded ownership records.
[in]	token	Token captured by previewSurfaceOwners(); stale model state is rejected by the engine.
[out]	error	Non-null failure-message destination; unchanged on success.

Returns: True when the engine accepts the replacement; false with a diagnostic otherwise.

◆ runMeshAssignmentSampling()

void openswmmvis::assignment::runMeshAssignmentSampling	(	QPromise< MeshAssignmentSampling::SampleResult > &	promise,
		MeshAssignmentSampling::Job	job
	)

Adapt synchronous sampling to a Qt concurrent promise.

Parameters

[in,out]	promise	Receives one SampleResult plus progress updates; cancellation is polled through isCanceled(). Caller owns promise lifetime.
[in]	job	Copied job whose paths and geometry are independent of GUI objects.

Intended for a worker thread; publishes a result even when sampling reports cancellation or an error.

Here is the call graph for this function:

◆ sampleMeshAssignment()

MeshAssignmentSampling::SampleResult openswmmvis::assignment::sampleMeshAssignment	(	const MeshAssignmentSampling::Job &	job,
		std::function< bool()>	cancelled = `{}`,
		std::function< void(int, int)>	progress = `{}`
	)

Run a self-contained raster/vector sampling job on the calling thread.

Parameters

[in]	job	Value-only job captured from GUI state; source paths are reopened locally and no QObject or engine handle is used. Bands are one-based; cell IDs and geometry arrays must stay index-aligned.
[in]	cancelled	Optional synchronous callback; true requests cancellation.
[in]	progress	Optional synchronous callback receiving processed and total cell counts; GUI callers must marshal UI updates to the GUI thread.

Returns: Sampled values in source units after scale/offset and target range checks, classification rows, skip counts and diagnostics. Nonempty error or cancelled prevents applying results.

May run on a worker thread. Each invocation owns its GDAL datasets and coordinate transforms; source files must remain accessible during the call.

Here is the caller graph for this function:

◆ surfaceOwnershipMeshMatches()

bool openswmmvis::assignment::surfaceOwnershipMeshMatches	(	SWMM_Engine	engine,
		const SWMM2DMeshLayer *	layer,
		QString *	error
	)

Check that the GUI mesh and engine mesh describe the same cells before ownership review.

Parameters

[in]	engine	Borrowed engine; nullptr is rejected.
[in]	layer	Borrowed active GUI mesh; nullptr is rejected.
[out]	error	Non-null failure-message destination; an empty matching mesh returns false without a new message.

Returns: True only for a nonempty mesh with matching vertex/cell counts, finite coordinates/elevations within tolerance, and identical ordered connectivity.

Reads GUI layer state; call on the GUI thread. No geometry or ownership is changed.

Here is the caller graph for this function:

◆ undoAquiferPreview()

bool openswmmvis::assignment::undoAquiferPreview	(	SWMM_Engine	engine,
		const AquiferPreview &	preview,
		QString *	error
	)

Remove only the unchanged suffix produced by an aquifer assignment.

Parameters

[in]	engine	Borrowed engine in BUILDING or OPENED state.
[in]	preview	Original preview; current rows/options must equal before plus appended rows.
[out]	error	Optional message, cleared at entry.

Returns: True after suffix removal; false for stale edits, unavailable state, read failures or failed deletion.

Here is the call graph for this function:

◆ undoGroundwaterTransport()

GroundwaterTransportResult openswmmvis::assignment::undoGroundwaterTransport	(	SWMM_Engine	engine,
		const GroundwaterTransportPreview &	preview
	)

Restore the before state only when the engine still matches the reviewed after state.

Parameters

[in]	engine	Borrowed editing engine.
[in]	preview	Original applied edit.

Returns: Transaction status using the same changed/rollbackComplete contract as applyGroundwaterTransport(); newer edits cause refusal.

Here is the call graph for this function:

Here is the caller graph for this function:

Namespaces

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ GroundwaterSourceDistribution

◆ GroundwaterTransportTarget

◆ RasterFluxCoverage

Function Documentation

◆ applyAquiferPreview()

◆ applyAquiferProcesses()

◆ applyGroundwaterTransport()

◆ applyInfiltrationOwnership()

◆ aquiferTargets()

◆ groundwaterEtForcingStatus()

◆ groundwaterTransportSpecies()

◆ integrateRasterFlux()

◆ previewAquiferAssignment()

◆ previewAquiferProcesses()

◆ previewGroundwaterTransport()

◆ previewInfiltrationOwnership()

◆ previewSurfaceOwners()

◆ readAquiferSnapshot()

◆ readGroundwaterTransportSnapshot()

◆ readSurfaceOwners()

◆ replaceSurfaceOwners()

◆ runMeshAssignmentSampling()

◆ sampleMeshAssignment()

◆ surfaceOwnershipMeshMatches()

◆ undoAquiferPreview()

◆ undoGroundwaterTransport()