Fingerprint-based position estimators
| This documentation was generated with the assistance of AI. Please report any inaccuracies. |
The com.irurueta.navigation.indoor.fingerprint package estimates a device’s position by comparing its RSSI
readings against a database of fingerprints — readings previously collected at known locations — rather than
requiring the radio sources' own positions to be known in advance the way
direct RSSI/ranging positioning does. Only the k nearest
known fingerprints (by RSSI-space distance) are used for any single estimate.
Overview
Fingerprinting takes a completely different approach from RSSI/ranging positioning: instead of converting a signal into a distance and solving a geometry problem, it treats the whole combination of signal strengths a device observes as a signature, and looks it up. This is the classic Wi-Fi fingerprinting technique, built in two phases:
- Offline — building the radio map
-
at many known locations, someone (or some automated process) records which access points are visible and how strong each one’s signal is there. Each location ends up with its own signature: a vector of RSSI values, one per access point, stored alongside that location’s known position.
- Online — matching a new reading
-
the device’s own signature (a vector of RSSI readings from the access points it currently sees) is compared against every signature in the database, and the k closest matches — by k-nearest-neighbors in signal space, not physical space — are found. The device’s position is then estimated as a weighted average of those matches' known locations: closer signal-space matches count for more.
Because it never needs to know where the access points physically are, or how their signal decays with distance, fingerprinting sidesteps the path-loss model entirely — at the cost of needing a survey of the space first. The linear and non-linear estimators below differ in exactly how they turn a set of nearby matches into a single estimated position.
Class hierarchy
3D non-linear classes have matching FirstOrder/SecondOrder/ThirdOrder subclasses, omitted above for
brevity. There is no linear or order-variant form of the joint position-and-radio-source estimator — it always
uses a single (first-order, gradient-based) model, described in
its own section below.
Selecting the nearest fingerprints
Both LinearFingerprintPositionEstimator and NonLinearFingerprintPositionEstimator first narrow the known
fingerprint database down to the k nearest ones (by Euclidean distance in RSSI space) via either
RadioSourceKNearestFinder (raw RSSI distance) or RadioSourceNoMeanKNearestFinder (mean-removed, bias-corrected
distance — the default, useNoMeanNearestFingerprintFinder = true). If solving fails numerically with k
neighbors, k is increased (up to maxNearestFingerprints, unlimited by default) and the solve is retried.
Linear estimation
LinearFingerprintPositionEstimator linearizes the log-distance path-loss model with a first-order Taylor
expansion of received power around each known fingerprint location, then solves the resulting system directly
— no iterative fitting involved. Given received power as a function of squared distance to a source at position
:
expanding around a known fingerprint position (2D case shown):
with the derivatives evaluated at the known, fixed distance between fingerprint and source:
Rearranged, each (known fingerprint, matched source reading) pair contributes one row to a linear system in the
unknown position , solved directly (not by least-squares fitting). The 3D case simply adds
the analogous terms. At least dims independent rows are required (2 for 2D, 3 for 3D).
Class documentation calls this "a first-order Taylor approximation… solves the problem in a linear way" — it is
mathematically the same first-order model as
the FirstOrderNonLinearFingerprintPositionEstimator below, just solved directly instead of
through Levenberg-Marquardt.
Non-linear estimation
NonLinearFingerprintPositionEstimator fits the same Taylor-expansion model with
LevenbergMarquardtMultiDimensionFitter instead of a direct solve, which lets it exploit second- and third-order
terms — and report a position covariance/chi-squared — at the cost of iterative refinement. Each (nearest
fingerprint, matched reading) pair becomes one non-linear sample; evaluate() returns the predicted RSSI at a
trial position and its Jacobian, differing precisely by order (below). Measurement variance (fingerprint RSSI
std, path-loss exponent std, position covariances) is propagated into a per-sample weight, falling back to
FALLBACK_RSSI_STANDARD_DEVIATION = 1.0 if it cannot be derived. As with the linear estimator, k grows on
numerical failure.
The full Taylor expansion being approximated at each order is:
all derivatives evaluated at the known fingerprint position (fixed, known distance
to the source). NonLinearFingerprintPositionEstimatorType selects how many of these terms are
used (default THIRD_ORDER); the 3D case has the same structure with one extra axis.
First order — FirstOrderNonLinearFingerprintPositionEstimator{2D,3D}
Uses only the gradient term — mathematically identical to the linear estimator’s model, just fit with Levenberg-Marquardt instead of solved directly:
The Jacobian returned to the fitter is constant (independent of the trial point) — a genuinely linear-in-parameters model.
Second order — SecondOrderNonLinearFingerprintPositionEstimator{2D,3D}
Adds the Hessian (quadratic and cross) terms:
( is the same expression with and swapped). The Jacobian now depends on the trial point — e.g. gains a term — making this genuinely non-linear, unlike first order.
Third order — ThirdOrderNonLinearFingerprintPositionEstimator{2D,3D} (library default)
Adds all third partial derivatives — pure cubic terms , , and mixed terms , — each a quotient-rule expansion over . The 3D case additionally has a fully-mixed triple term with no 2D analogue:
This is the most accurate approximation of the three but also the most numerically sensitive, since it depends on higher powers of .
Order |
What’s added |
First |
Gradient only — a linear model in the unknown position, just fit via Levenberg-Marquardt instead of solved directly. |
Second |
+ Hessian (quadratic + cross terms) — the model becomes genuinely non-linear in the unknown position. |
Third (default) |
+ all third partial derivatives (cubic + mixed cubic terms) — most accurate, most expensive, least numerically stable. |
Joint position and radio source refinement
NonLinearFingerprintPositionAndRadioSourceEstimator solves a related but distinct problem: it treats both the
unknown position and each radio source’s own position as
unknowns to refine jointly, rather than assuming source positions are already known and fixed. It eliminates the
unknown transmitted-power constant by differencing the received power of a known fingerprint and
the unknown-location reading for the same source:
with partial derivatives (2D shown):
fit jointly via Levenberg-Marquardt over an unknown vector packing the fingerprint position and every observed
source’s position. Unlike the position-only estimators, this is inherently a first-order (gradient-only) model —
there are no order variants — but applied to a larger joint unknown vector. It requires at least
nearest fingerprints, optionally accepts initialLocatedSources
as a warm start, and returns refined source positions via getEstimatedLocatedSources() alongside the estimated
device position.
Usage parameters
-
locatedFingerprints,fingerprint(unknown-location readings) — required for all estimators;sources(known radio source positions) required for the position-only estimators, replaced by optionalinitialLocatedSourcesfor the joint estimator. -
minNearestFingerprints/maxNearestFingerprints— k-NN search range (position-only defaultmin=1, unlimited max; joint estimator’s minimum is auto-computed fromdims*(1+numSources)). -
pathLossExponent(default2.0) anduseSourcesPathLossExponentWhenAvailable(defaulttrue) — use each source’s own path-loss exponent if available, else the estimator’s configured value. -
useNoMeanNearestFingerprintFinder(defaulttrue) — bias-corrected vs. raw RSSI-distance neighbor search. -
removeMeansFromFingerprintReadings(position-only, defaultfalse) — corrects hardware/device RSSI bias by differencing against each fingerprint’s own mean. -
Non-linear only:
initialPosition(else centroid of selected neighbors),fallbackRssiStandardDeviation(default1.0,1e-3for the joint estimator), fourpropagate*flags (RSSI std, path-loss exponent std, fingerprint/source position covariance — all defaulttrue). -
NonLinearFingerprintPositionEstimator{2D,3D}.create(…)— static factory selecting First/Second/Third order viaNonLinearFingerprintPositionEstimatorType(defaultTHIRD_ORDER). -
Outputs:
getEstimatedPosition(),getNearestFingerprints(), and for non-linear estimatorsgetCovariance()/getChiSq(); the joint estimator additionally exposesgetEstimatedLocatedSources().
API reference
Main classes used on this page, linked to their source code and Javadoc:
| Class | Source | Javadoc |
|---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Related
-
RSSI-based position estimators / Ranging-based position estimators / Combined RSSI and ranging position estimators — direct positioning when source locations are already known.
-
Radio source estimators — estimating a radio source’s position and transmission parameters from readings taken at known locations (the inverse problem this package’s joint estimator also touches on).