Loading...
Searching...
No Matches
mesh::NaturalNeighbourInterpolator Class Reference

Natural-neighbour (Sibson or Laplace) interpolator over scattered (x, y, z) seeds. More...

#include <mesh/naturalnbinterpolator.h>

Collaboration diagram for mesh::NaturalNeighbourInterpolator:

Public Types

enum class  Variant {
  Sibson ,
  Laplace
}
 Natural-neighbour coordinate construction used by interpolate() and weightsAt(): Sibson (default) uses area-stealing coordinates, Laplace uses Voronoi facet length divided by the distance to the seed. More...
 

Public Member Functions

 NaturalNeighbourInterpolator ()=default
 Construct an invalid empty interpolator using the Sibson variant.
 
void setVariant (Variant v)
 Select which natural-neighbor weight construction later queries use.
 
Variant variant () const
 Read the currently stored interpolation variant.
 
bool build (const QVector< QPointF > &pts, const QVector< double > &z, QString *err)
 Replace interpolation geometry with a snap-deduplicated normalized Delaunay seed set.
 
bool build (const QVector< QPointF > &pts, QString *err)
 Build the same triangulation for weight-only queries using zero scalar values.
 
bool isValid () const
 Read whether the latest full build completed successfully.
 
double interpolate (double x, double y) const
 Interpolate one scalar through the chosen normalized natural-neighbor weight scheme.
 
bool weightsAt (double x, double y, QVector< QPair< int, double > > &out) const
 Return normalized natural-neighbor weights keyed by original retained input indices.
 
const std::vector< int > & keptSeedIndices () const
 Borrow the original input-index mapping in internal Delaunay-vertex order.
 

Detailed Description

Natural-neighbour (Sibson or Laplace) interpolator over scattered (x, y, z) seeds.

build() copies and triangulates the seeds; interpolate() and weightsAt() then answer queries inside the seeds' convex hull and return NaN / false elsewhere. The instance owns all its storage. Queries mutate internal caches, so one instance must not be queried from several threads at once (see the file comment).

Member Enumeration Documentation

◆ Variant

Natural-neighbour coordinate construction used by interpolate() and weightsAt(): Sibson (default) uses area-stealing coordinates, Laplace uses Voronoi facet length divided by the distance to the seed.

Enumerator
Sibson 

Area-stealing (Sibson) coordinates; the default.

Laplace 

Voronoi facet length divided by the distance to the seed.

Constructor & Destructor Documentation

◆ NaturalNeighbourInterpolator()

mesh::NaturalNeighbourInterpolator::NaturalNeighbourInterpolator ( )
default

Construct an invalid empty interpolator using the Sibson variant.

Note
A successful build() is required before queries. Owns copied geometry/value arrays and reusable scratch storage; no external input ownership is taken. Even const queries mutate caches, so each instance needs a single querying worker or external synchronization.

Member Function Documentation

◆ build() [1/2]

bool mesh::NaturalNeighbourInterpolator::build ( const QVector< QPointF > & pts,
const QVector< double > & z,
QString * err )

Replace interpolation geometry with a snap-deduplicated normalized Delaunay seed set.

Parameters
[in]ptsBorrowed planar seed coordinates in common CRS/units, unchanged; count must match z. Finite x/y times 1e7 must fit qint64 for unchecked qRound64 snap keys, and counts must fit int.
[in]zBorrowed scalar values in a consistent application-defined unit, unchanged; nonfinite coordinate/value seeds are skipped. First finite occurrence of each 1e-7 quantized xy key is retained.
[out]errOptional borrowed diagnostic, overwritten only on checked failure, not cleared on success.
Returns
True after at least three unique noncollinear seeds produce live triangles and owned arrays; false for count mismatch, insufficient/degenerate seeds, failed Delaunay or post-normalization merging. Invalidates and clears prior geometry at entry; failure may leave partial retained-index/array state, never restores the prior interpolant. Success does not guarantee every interior query has a usable natural-neighbor cavity. Copies seed coordinates/values, retains no inputs, allocates triangulation and arrays; variant remains unchanged. Requires exclusive instance access, callback/project/engine free.

Triangulate the seed set. Snap-dedupes coincident points, requires >= 3 unique non-collinear points. Returns false (and sets *err when non-null) when interpolation is unavailable — the caller should then fall back to IDW entirely.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ build() [2/2]

bool mesh::NaturalNeighbourInterpolator::build ( const QVector< QPointF > & pts,
QString * err )

Build the same triangulation for weight-only queries using zero scalar values.

Parameters
[in]ptsBorrowed seeds in common planar CRS/units, unchanged; all full-build coordinate/count preconditions apply, including representable 1e7 snap-key scaling.
[out]errOptional borrowed error string, overwritten on checked failure, unchanged on success.
Returns
Full build() result with an owned temporary zero-value vector. Replaces prior geometry and retained-index views, keeps chosen variant, and makes interpolate() yield zero wherever weights work. No input retention or source mutation; requires exclusive instance access.

Triangulate seeds for weight queries only (weightsAt), with no associated values. Equivalent to build() with a zero z vector.

Here is the call graph for this function:

◆ interpolate()

double mesh::NaturalNeighbourInterpolator::interpolate ( double x,
double y ) const

Interpolate one scalar through the chosen normalized natural-neighbor weight scheme.

Parameters
[in]xFinite query x in the original seed planar CRS/units, unchanged; normalized arithmetic and weighted sums must remain representable for meaningful results.
[in]yFinite query y in the same original coordinate system, unchanged.
Returns
Weighted scalar in the original z units, or NaN if invalid/unbuilt, hull walk fails, cavity reaches the hull/is degenerate, weights fail or total weight is below 1e-15. Even some hull/interior seed queries can be unavailable; caller supplies its own fallback. No extrapolation, error-text update, coordinate conversion or source mutation. Allocates local weights and reuses mutable walk/stamp/scratch caches, so const does not permit concurrent queries on this instance.

Interpolate z at (x, y). Returns NaN when the point is outside the seed convex hull or the local insertion is degenerate — the caller falls back to IDW for that vertex.

◆ isValid()

bool mesh::NaturalNeighbourInterpolator::isValid ( ) const
inline

Read whether the latest full build completed successfully.

Returns
True after successful build, false initially or after a checked build failure. Does not test query-specific hull/cavity degeneracy, finite arithmetic or current application data freshness. Constant unsynchronized state check, no allocation or geometry mutation.

◆ keptSeedIndices()

const std::vector< int > & mesh::NaturalNeighbourInterpolator::keptSeedIndices ( ) const
inline

Borrow the original input-index mapping in internal Delaunay-vertex order.

Returns
Const reference to instance-owned index storage, valid only until build(), assignment or destruction; never delete/mutate it. First finite snap-key occurrence survives, skipped/duplicate seeds do not appear. After failed build this may contain partial data, so require isValid() first. No copy/allocation or query-cache mutation; exclude concurrent rebuild.

Original indices of the seeds that survived snap-dedupe, in Delaunay-vertex order. Coincident inputs collapse to the first occurrence, so a caller can diff this against its input to learn which seeds were dropped and will never carry weight.

◆ setVariant()

void mesh::NaturalNeighbourInterpolator::setVariant ( Variant v)
inline

Select which natural-neighbor weight construction later queries use.

Parameters
[in]vVariant, normally Sibson or Laplace; implementation treats other enum values as Sibson.
Note
Does not rebuild triangulation, clear validity or perform a query. Exclude concurrent build/query operations; the variant applies to subsequent calls and no signal or project update is emitted.

◆ variant()

Variant mesh::NaturalNeighbourInterpolator::variant ( ) const
inline

Read the currently stored interpolation variant.

Returns
Stored enum, initially Sibson; no normalization or validation. Requires stable instance access, performs no geometry query and changes no state.

◆ weightsAt()

bool mesh::NaturalNeighbourInterpolator::weightsAt ( double x,
double y,
QVector< QPair< int, double > > & out ) const

Return normalized natural-neighbor weights keyed by original retained input indices.

Parameters
[in]xFinite original-seed-CRS x query coordinate, unchanged.
[in]yFinite original-seed-CRS y query coordinate, unchanged; normalized geometry/sums must be representable.
[out]outBorrowed destination, cleared at entry and empty on checked failure. Success fills owned (index,dimensionless weight) pairs sorted ascending by original seed index; dropped seeds are absent.
Returns
True for a usable cavity and weight sum >=1e-15, false when invalid/outside/hull-touching/ degenerate or weight construction fails. Finite well-conditioned sums normalize to one, not a promise of extrapolation. Allocates weight/output arrays and mutates reusable caches even though const; requires exclusive instance access, retains no output pointer and changes no source/project data.

Natural-neighbour weights at (x, y), keyed by ORIGINAL seed index.

Same scheme interpolate() uses; this exposes the coordinates themselves so a caller can blend something other than a scalar z (e.g. whole rainfall time series). Weights are normalised to sum 1 and returned SORTED ASCENDING BY INDEX — the order is contractual, because the underlying accumulation walks a QHash whose iteration order is randomised per process, and callers that hash these weights need reproducibility.

Note
Not thread-safe for concurrent queries: inherits interpolate()'s mutable walk-start cache. Use one instance per worker thread.

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