Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
aipp Namespace Reference

Namespaces

namespace  math

Classes

struct  Grid
 Rectangular, evenly spaced local map grid. More...
struct  PlannerOptions
 Search, utility, and optimizer controls for the reference planner. More...

Typedefs

using Matrix = math::Matrix
 Dense row-major covariance layout chosen for contiguous row updates.
using Vector = math::Vector
 Dynamic GP mean, measurement, or per-cell variance vector.
using Point = math::Point
 Three-dimensional local east/north/altitude point, in metres.
using Sensor = dipla::aigenlib::Sensor
 Sparse block-averaging observation operator.

Functions

std::vector< Point > refine (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const std::vector< Point > &initial, const PlannerOptions &options)
 Refine a greedy route with bounded CMA-ES while retaining its best candidate.
std::vector< Point > plan (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const PlannerOptions &options)
 Run greedy route selection followed by optional CMA-ES refinement.
double fov_radius (double altitude, double angle=60.0)
 Compute the ground-plane footprint radius from altitude and full FOV angle.
int resolution_block_size (double altitude)
 Select the research sensor's altitude-dependent aggregation block size.
double noise_model (double altitude, double minimum_altitude=10.0)
 Compute modeled observation variance at an altitude.
Matrix initialize_covariance (const Grid &grid, double sigma2, double lengthscale)
 Initialize a dense Matérn-3/2 GP covariance matrix.
Sensor build_sensor (const Grid &grid, const Point &pose, double angle=60.0, double observation_variance=-1.0)
 Build one block-averaged sensor footprint at a pose.
Sensor future_sensor (const Grid &grid, const std::vector< Point > &path, double angle=60.0, int stride=lookahead_stride, int max_measurements=lookahead_measurement_budget, double observation_variance=-1.0)
 Approximate future measurements along a path under a bounded budget.
Vector observe (const Sensor &sensor, const Vector &field)
 Apply the sensor's block averages to a full-grid field.
Vector sample_sensor_noise (const Sensor &sensor, std::mt19937_64 &generator)
 Draw independent zero-mean noise using each sensor row's variance.
std::vector< bool > importance_mask (const Vector &mean, const Matrix &covariance, const PlannerOptions &options)
 Select cells whose confidence bounds satisfy the utility threshold.
double expected_reduction (const Matrix &covariance, const std::vector< bool > &mask, const Sensor &sensor)
 Sum expected marginal-variance reduction over important cells.
void condition (Matrix &covariance, Vector *mean, const Sensor &sensor, const Vector *measurement)
 Apply a Gaussian linear-observation update in place.
Point clip_point (const Grid &grid, const Point &point, const PlannerOptions &options)
 Clamp a candidate to the map safety inset and altitude interval.
std::vector< Point > lattice (const Grid &grid, const PlannerOptions &options)
 Generate the deduplicated coarse-to-fine candidate lattice.
std::vector< Point > spline (const Point &start, const std::vector< Point > &waypoints, int samples_per_segment=spline_samples_per_segment)
 Interpolate controls with a natural cubic spline parameterized by distance.
double trajectory_objective (const Grid &grid, const Matrix &covariance, const std::vector< bool > &mask, const Point &start, const std::vector< Point > &raw_waypoints, const PlannerOptions &options)
 Score a trajectory by safety violation and distance-normalized information gain.
std::vector< Point > grid_search (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const PlannerOptions &options)
 Greedily select a bounded route by information gain per travel cost.

Variables

constexpr int lookahead_stride = 4
 Default route-pose sampling interval for look-ahead scoring.
constexpr int lookahead_measurement_budget = 64
 Innovation-system row budget, independent of worker FIFO capacity.
constexpr int spline_samples_per_segment = 5
 Default emitted spline samples per control segment.

Typedef Documentation

◆ Matrix

Dense row-major covariance layout chosen for contiguous row updates.

◆ Point

Three-dimensional local east/north/altitude point, in metres.

◆ Sensor

Sparse block-averaging observation operator.

Each row lists grid-cell indices averaged into one measurement; variances stores the independent observation variance for each row.

◆ Vector

Dynamic GP mean, measurement, or per-cell variance vector.

Function Documentation

◆ build_sensor()

Sensor aipp::build_sensor ( const Grid & grid,
const Point & pose,
double angle,
double observation_variance )

Build one block-averaged sensor footprint at a pose.

Use the square bounding the FOV, then group included cells by globally anchored resolution blocks. Blocks stay anchored to grid row/column zero, not to the moving footprint edge; otherwise tiny pose changes would redefine the measurement operator even over the same physical cells.

Note
Edge blocks average only their included cells. Do not normalize them by the nominal block area or add a circular-distance rejection: either would describe a different observation model from this reference implementation.
Precondition
Geometry and pose are finite, altitude/FOV are valid, and the chosen fixed or altitude-derived observation variance is finite and nonnegative.
See also
observe The same row-average weights must be used when generating measurements.

Grid cells inside the square bounding the circular FOV are grouped by altitude-dependent resolution blocks, matching the reference sensor's coarse measurement behavior.

Parameters
gridMap grid.
poseSensor east/north/altitude in metres.
angleFull field-of-view angle in degrees.
observation_varianceFixed variance, or negative to use the altitude model.
Returns
Sparse sensor rows and their independent variances.

◆ clip_point()

Point aipp::clip_point ( const Grid & grid,
const Point & point,
const PlannerOptions & options )

Clamp a candidate to the map safety inset and altitude interval.

Apply the comparison planner's two-grid-step XY inset and declared Z interval. This constrains a control point, not every point of a cubic spline between controls; trajectory_objective() separately scores spline overshoot.

Precondition
Coordinates and altitude bounds are finite, with options.zmin <= options.zmax.
Warning
A geometric target inset is not an aircraft geofence or an arrival test.

Horizontal margins are two grid steps, independent of optimizer penalty settings, so downstream routes retain a geometric boundary buffer.

Parameters
gridMap geometry and horizontal inset.
pointCandidate east/north/altitude point.
optionsPermitted altitude interval.
Returns
Bounded point.

◆ condition()

void aipp::condition ( Matrix & covariance,
Vector * mean,
const Sensor & sensor,
const Vector * measurement )

Apply a Gaussian linear-observation update in place.

Compute P and solve S * B = P once, then reuse B for both posterior mean and covariance. Never form a general explicit inverse merely to multiply it away again; the measurement-space solve is the smaller numerical problem.

Precondition
Supply mean and measurement together with compatible finite dimensions, or pass both as nullptr for hypothetical covariance-only conditioning.
Covariance and sensor describe the same valid finite grid domain.
Warning
The update mutates storage in place; it is not a transactional operation with rollback after an arithmetic or allocation failure. Symmetry restoration fixes triangle disagreement, not arbitrary loss of definiteness.
See also
expected_reduction Same covariance algebra without materializing its update.

Solves the innovation system rather than forming an inverse, updates the posterior mean only when both optional pointers are supplied, then updates covariance in row blocks to limit temporary allocations and restores symmetry.

Parameters
covariancePrior covariance, replaced by the posterior covariance.
meanOptional prior mean; used only when measurement is non-null.
sensorObservation operator.
measurementOptional observed vector paired with mean.

◆ expected_reduction()

double aipp::expected_reduction ( const Matrix & covariance,
const std::vector< bool > & mask,
const Sensor & sensor )

Sum expected marginal-variance reduction over important cells.

For each selected cell, the corresponding column of P and B yields the diagonal reduction in Sigma - P^T * B. Sum only those diagonals rather than allocating a full posterior just to obtain one candidate's utility. Future measurement values are unnecessary: linear-Gaussian covariance updates depend on the observation operator and noise, not the unknown observed value.

Note
Clamp each computed reduction to [0, prior marginal variance] to contain round-off. This is a trace-reduction utility, not entropy or a field-value reward.
Precondition
Covariance is finite and symmetric; mask has N entries and sensor rows and variances are valid for the same N-cell domain.

Uses the sensor innovation covariance and clamps numerical roundoff to each cell's prior marginal variance.

Parameters
covariancePrior covariance.
maskCells contributing to utility.
sensorCandidate observation operator.
Returns
Sum of marginal-variance reduction over selected cells.

◆ fov_radius()

double aipp::fov_radius ( double altitude,
double angle )

Compute the ground-plane footprint radius from altitude and full FOV angle.

The angle is the full FOV in degrees. Dividing by 360 both halves it and converts to radians; using 180 here would double the angular footprint.

Precondition
altitude is finite and nonnegative; angle is finite and between 0 and 180 degrees.
Note
This ground-plane geometry assumes a level footprint. build_sensor() selects its square bounds, not a ray-traced or circular visibility mask.

Uses the tangent of the half-angle because the input is the full FOV.

Parameters
altitudeSensor altitude above ground in metres.
angleFull field-of-view angle in degrees.
Returns
Ground-plane footprint radius in metres.

◆ future_sensor()

Sensor aipp::future_sensor ( const Grid & grid,
const std::vector< Point > & path,
double angle,
int stride,
int max_measurements,
double observation_variance )

Approximate future measurements along a path under a bounded budget.

Approximate a route's future observations without querying truth. Snap each sampled XY pose to the research grid before constructing its H; the supplied altitude still controls footprint, resolution, and default noise.

Note
Endpoint inclusion happens before row limiting. The final bounded operator evenly retains rows, not entire footprints, so a small budget may omit some cells or rows from any particular pose, including the endpoint.
Warning
max_measurements bounds the returned innovation dimension, not peak construction storage: the combined operator is built before subsampling.
Precondition
Path values, sensor geometry, and selected variances satisfy build_sensor()'s preconditions.

Samples path poses by stride, always includes the final waypoint, and evenly subsamples sensor rows if their total exceeds max_measurements. This trades a compact innovation matrix for some spatial detail.

Parameters
gridMap grid.
pathOrdered trajectory in metres.
angleFull field-of-view angle in degrees.
stridePath-pose interval used for sampling.
max_measurementsMaximum number of returned measurement rows.
observation_varianceFixed variance, or negative to use the altitude model.
Returns
Combined sensor operator within the requested measurement budget.
Exceptions
std::invalid_argumentIf stride or the measurement budget is nonpositive.

◆ grid_search()

std::vector< Point > aipp::grid_search ( const Grid & grid,
const Vector & mean,
const Matrix & covariance,
const Point & start,
const PlannerOptions & options )

Greedily select a bounded route by information gain per travel cost.

Choose a gain-per-distance winner, condition a private hypothetical covariance, then score the next choice against reduced uncertainty. Reusing the original covariance every round would repeatedly reward already-covered regions instead of planning complementary observations.

Note
The mean remains the observed mean throughout look-ahead: future sensor values are unknown. Importance masks can still change as simulated uncertainty shrinks. One extra dense covariance is the principal storage cost of this search.
Warning
Cancellation returns an empty vector, not the partial prefix already selected. A short nonempty route can still result from exhausted candidates; the application must enforce its required eight-point publication contract.
Precondition
Geometry, posterior, utility, and sensor settings satisfy the called helpers.
See also
PlannerOptions::keep_planning Cooperative polling, not preemptive interruption.

Each chosen sensor conditions a private covariance copy before the next selection, giving cheap sequential look-ahead without mutating observed belief state. Cancellation returns an empty/incomplete route.

Parameters
gridCandidate world grid.
meanCurrent posterior mean.
covarianceCurrent posterior covariance.
startInitial position.
optionsHorizon, utility, sensor, and cancellation settings.
Returns
Ordered greedy controls, possibly empty when interrupted.

◆ importance_mask()

std::vector< bool > aipp::importance_mask ( const Vector & mean,
const Matrix & covariance,
const PlannerOptions & options )

Select cells whose confidence bounds satisfy the utility threshold.

Select utility using mean plus/minus beta times marginal standard deviation. The lower-bound mode asks whether a cell could lie below threshold; the upper-bound mode asks whether it could lie above. Preserve the inequality directions when adapting a task: swapping them changes what exploration values.

Note
If every cell fails, score the whole field instead of handing search a flat zero-gain objective. This is an explicit exploration policy, not a claim that every cell now meets the requested confidence-bound test.
Precondition
Mean, covariance, and utility settings are finite and dimensionally compatible.

If no cell meets the requested bound, all cells are selected so the optimizer does not receive a degenerate zero-utility objective.

Parameters
meanPosterior mean.
covariancePosterior covariance.
optionsConfidence-bound direction, beta, and threshold.
Returns
Boolean importance mask in grid order.

◆ initialize_covariance()

Matrix aipp::initialize_covariance ( const Grid & grid,
double sigma2,
double lengthscale )

Initialize a dense Matérn-3/2 GP covariance matrix.

The Matern-3/2 kernel is sigma2 * (1 + q) * exp(-q), with q = sqrt(3) * distance / lengthscale. sigma2 is already the marginal variance; squaring it again would change both uncertainty scale and inferred utility. At zero distance the diagonal is sigma2; nearby cells share information according to lengthscale measured in the same metres as the grid.

Note
This initializes covariance only. The application owns the prior mean; do not infer its value from a bare GP initializer in another caller.

Kernel values are cached by displacement on the uniform grid; the dense matrix then supports the block updates used by conditioning.

Parameters
gridGrid defining the covariance coordinates.
sigma2Kernel marginal variance.
lengthscaleMatérn spatial length scale in metres.
Returns
Symmetric dense prior covariance.
Exceptions
std::invalid_argumentIf kernel amplitude or length scale is invalid.

◆ lattice()

std::vector< Point > aipp::lattice ( const Grid & grid,
const PlannerOptions & options )

Generate the deduplicated coarse-to-fine candidate lattice.

Combine three nested XY layers at progressively higher requested altitudes. Snap XY and Z to their respective grid-step lattices, then remove exact duplicate points so a shared location cannot consume two greedy slots. Fixed-height settings collapse Z layers naturally without inventing a Z search.

Note
Enumeration order breaks equal-score ties in grid_search(). Changing it can change a deterministic route even when the candidate set is unchanged.
Precondition
Altitude bounds are finite, ordered, and their step count fits int.

Nested layers trade uniform resolution for broad coverage and progressively finer central choices.

Parameters
gridMap geometry and spacing.
optionsAltitude range for lattice layers.
Returns
Unique candidate positions.

◆ noise_model()

double aipp::noise_model ( double altitude,
double minimum_altitude )

Compute modeled observation variance at an altitude.

Return variance, not standard deviation: 0.01 at minimum_altitude, approaching 0.04 from below at increasing height. The exponential preserves that saturation rather than making high-altitude noise grow without limit.

Warning
This formula is not clamped below its reference altitude and can become negative there. The 2 m application explicitly supplies variance 0.01; do not extrapolate this law to low flight or take sqrt of a negative result.
See also
build_sensor Fixed-variance override for a separately declared sensor experiment.

Exponentially approaches the reference high-altitude variance rather than increasing without bound.

Parameters
altitudeSensor altitude in metres.
minimum_altitudeReference altitude for the minimum variance.
Returns
Modeled measurement variance.

◆ observe()

Vector aipp::observe ( const Sensor & sensor,
const Vector & field )

Apply the sensor's block averages to a full-grid field.

Apply H identically to hidden truth and predicted mean; the latter gives the expected measurement used by the GP residual. Noise is deliberately separate so scoring can use the operator without drawing synthetic evidence.

Precondition
Rows are nonempty and indices address finite entries in field.
See also
sample_sensor_noise Independent noise is added by the observation owner.

Each sparse row is treated as a uniform averaging operator.

Parameters
sensorSparse sensor operator.
fieldOne value per grid cell.
Returns
One averaged value per sensor row.

◆ plan()

std::vector< Point > aipp::plan ( const Grid & grid,
const Vector & mean,
const Matrix & covariance,
const Point & start,
const PlannerOptions & options )

Run greedy route selection followed by optional CMA-ES refinement.

Greedy search provides a feasible incumbent; refinement is skipped when options.refine is false.

Parameters
gridMap geometry.
meanCurrent posterior mean.
covarianceCurrent posterior covariance.
startInitial position.
optionsSearch and optimizer settings.
Returns
Ordered control points, or an empty route if cancelled during greedy search.

◆ refine()

std::vector< Point > aipp::refine ( const Grid & grid,
const Vector & mean,
const Matrix & covariance,
const Point & start,
const std::vector< Point > & initial,
const PlannerOptions & options )

Refine a greedy route with bounded CMA-ES while retaining its best candidate.

Fixed-altitude problems omit Z from the search dimension; boundary transforms keep the optimizer's latent Gaussian unconstrained while all evaluated waypoints remain inside flight bounds.

Parameters
gridMap geometry and safety bounds.
meanCurrent posterior mean.
covarianceCurrent posterior covariance.
startInitial position.
initialGreedy route used as the warm start and incumbent.
optionsOptimizer budget, seed, bounds, and cancellation predicate.
Returns
Best route found, or the unchanged initial route if refinement cannot start.

◆ resolution_block_size()

int aipp::resolution_block_size ( double altitude)

Select the research sensor's altitude-dependent aggregation block size.

Higher altitude coarsens one measurement into averages of wider grid blocks. These thresholds belong to the research observation model, not the ONNX tensor resolution; changing them changes the experiment's H.

Piecewise aggregation preserves the reference sensor's coarser effective resolution at higher altitude.

Parameters
altitudeSensor altitude in metres.
Returns
Aggregation block width in cells.

◆ sample_sensor_noise()

Vector aipp::sample_sensor_noise ( const Sensor & sensor,
std::mt19937_64 & generator )

Draw independent zero-mean noise using each sensor row's variance.

Scale a standard normal by sqrt(variance), not variance itself. Using the same per-row variance in innovation() makes sampled measurements and GP likelihood describe one experiment rather than two incompatible sensors.

Precondition
Each sensor row has one finite, nonnegative variance.
Note
The caller owns random-stream lifetime. Even a zero-variance row draws a normal here; changing row order or draw count changes later noise samples. Equal seeds alone do not promise NumPy or cross-library bitwise equivalence.

Uses one standard-normal draw per row and scales by that row's standard deviation; the caller owns the generator to control reproducibility.

Parameters
sensorPer-row variances define Gaussian scales.
generatorCaller-owned random engine for reproducibility.
Returns
One independent noise value per sensor row.

◆ spline()

std::vector< Point > aipp::spline ( const Point & start,
const std::vector< Point > & waypoints,
int samples_per_segment )

Interpolate controls with a natural cubic spline parameterized by distance.

Parameterize by 3-D chord length rather than control index so unequal waypoint spacing affects interpolation geometrically. Natural endpoint conditions set endpoint second derivatives to zero; an in-place tridiagonal solve obtains the interior derivatives for all three coordinates together.

Note
Consecutive chords no longer than 1e-9 m are omitted. This avoids a singular system but intentionally differs from retaining coincident controls with an artificial minimum chord length in another reference implementation.
Warning
This is a sampled scoring path, not the flight controller's path implementation, a constant-speed parameterization, or a bound on continuous spline overshoot between emitted samples.
Precondition
Input coordinates are finite and the requested sample storage is practical.

Coincident consecutive knots are removed because their zero chord lengths make the spline system singular; an all-coincident path is returned as its single unique point.

Parameters
startInitial path point.
waypointsOrdered spline controls.
samples_per_segmentNumber of emitted samples per chord.
Returns
Interpolated path including the final knot.
Exceptions
std::invalid_argumentIf samples per segment is not positive.

◆ trajectory_objective()

double aipp::trajectory_objective ( const Grid & grid,
const Matrix & covariance,
const std::vector< bool > & mask,
const Point & start,
const std::vector< Point > & raw_waypoints,
const PlannerOptions & options )

Score a trajectory by safety violation and distance-normalized information gain.

Minimize boundary violation minus information gain per travel cost. Raw controls contribute a penalty even though scoring uses clipped controls; otherwise many out-of-bounds proposals would become the same cheap clipped path. Sampled spline overshoot adds a penalty of its own.

Note
Travel cost is the clipped control polyline's length, not spline arc length. Its grid-step floor prevents division by zero and infinite reward for hovering on coincident controls. Sensor stride and the 64-row budget bound the scoring solve at the cost of an approximate future-observation operator.
Warning
Soft penalties do not certify continuous-path containment. Changing samples_per_segment, stride, or row budget changes the objective, not just speed.
Precondition
Inputs satisfy spline(), clip_point(), and expected_reduction() contracts.

Controls are clipped for geometric evaluation, while raw-control and spline overshoot is retained as a penalty so the optimizer cannot hide an unsafe proposal by clipping it before scoring.

Parameters
gridMap geometry and safety bounds.
covarianceCurrent covariance.
maskCells included in information gain.
startCurrent position.
raw_waypointsCandidate controls before clipping.
optionsSensor geometry and distance-cost settings.
Returns
Scalar objective; lower values are preferred.

Variable Documentation

◆ lookahead_measurement_budget

int aipp::lookahead_measurement_budget = 64
inlineconstexpr

Innovation-system row budget, independent of worker FIFO capacity.

◆ lookahead_stride

int aipp::lookahead_stride = 4
inlineconstexpr

Default route-pose sampling interval for look-ahead scoring.

◆ spline_samples_per_segment

int aipp::spline_samples_per_segment = 5
inlineconstexpr

Default emitted spline samples per control segment.