Filters

Retrieve the estimated kinematic state and extent of the object, all flattened into a single vector.

Returns: - A vector representing both the estimated kinematic state and extent.

Retrieve the estimated kinematic state of the object.

Returns: - A vector representing the estimated kinematic state.

Retrieve the estimated extent of the object.

Parameters: - flatten_matrix: whether to flatten the extent matrix or not

Returns: - A matrix or vector representing the estimated extent.

Get a point estimate

Append a value to a named history and return the updated history.

Clear a named history or all registered histories.

Store a deep-copied snapshot of the current filter state.

Store the current point estimate as a padded numeric history.

Plot the filter state.

Update the grid state using a reusable likelihood model.

Parameters

measurement_model : object Model object exposing either likelihood_values(z, grid) or a callable likelihood(z, grid) attribute. The method must return one likelihood value per point of self.filter_state.get_grid(). z : array-like Measurement passed to the model.

Notes

This adapter preserves the existing :meth:update_nonlinear API and simply delegates to it after extracting the likelihood capability from the model object.

Predict using a reusable grid transition-density model.

Parameters

transition_model : object Model object exposing either transition_density_for_filter(self) or a transition_density attribute compatible with this filter's density-based prediction method.

Notes

This generic adapter is intentionally conservative: concrete grid filters still define the actual density-based prediction method. If a filter does not expose predict_nonlinear_via_transition_density, a clear NotImplementedError is raised.

Propagate the multi-object posterior one time step.

Update from one complete scan of measurements.

measurement_partitions may contain precomputed cells or alternative partitions for trackers that separate partitioning from association.

Run a complete predict/update step and record enabled histories.

Return extracted extended-object estimates.

Return the number of currently extracted objects.

Return labels of extracted objects.

Return vectorized extracted-object estimates.

With flatten_vector=False, each column represents one object. With flatten_vector=True, the matrix is flattened for compatibility with existing multi-target logging helpers.

Return kinematic estimates only.

Return extent estimates only.

Return measurement-rate estimates where available.

Return drawable contour points for extracted objects.

Return the cardinality distribution if represented explicitly.

Return expected cardinality when it can be inferred from estimates.

Optional complexity-reduction hook.

Optional component-merging hook.

Optional component-capping hook.

Run optional pruning, merging, and capping hooks.

Record prior extent estimates.

Record posterior extent estimates.

Record prior measurement-rate estimates.

Record posterior measurement-rate estimates.

Clear histories and keep MEOT-specific mirrors synchronized.

This method must be implemented in subclass

Set the post-update resampling criterion and return the filter.

Return whether the current weighted particle set should resample.

The default criterion, None, always returns True to retain the previous update behavior.

Manually resample particles according to their current weights.

The particle locations are sampled with replacement from the current weighted particle set, and the resulting weights are reset to uniform.

Resample if the configured criterion requests it.

Returns

bool True if resampling was performed, otherwise False.

Predict using a reusable particle transition model.

Update using a reusable particle measurement model.

Append a value to a named history and return the updated history.

Clear a named history or all registered histories.

Return a copy with updated gate acceptance metadata.

Return whether hypothesis is accepted by the NIS threshold.

Return hypotheses accepted by the top-k rule.

Predict assuming identity system model with noise gauss_w.

Computes x(k+1) = x(k) ⊕ w(k), where ⊕ is complex or quaternion multiplication.

Parameters: gauss_w (GaussianDistribution): system noise with unit vector mean

Update assuming identity measurement model with noise gauss_v.

Computes z(k) = x(k) ⊕ v(k), where ⊕ is complex or quaternion multiplication.

Parameters: gauss_v (GaussianDistribution): measurement noise with unit vector mean z (array): measurement as a unit vector of shape (2,) or (4,)

Return the mean of the current filter state.

Predict assuming identity system model with Bingham noise.

Computes x(k+1) = x(k) () w(k) where () is complex or quaternion multiplication and w(k) ~ bw.

Parameters: bw (BinghamDistribution): noise distribution

Predict assuming nonlinear system model with Bingham noise.

Computes x(k+1) = a(x(k)) (*) w(k) using a sigma-point approximation.

Parameters: a (callable): nonlinear system function mapping R^n -> R^n bw (BinghamDistribution): noise distribution

Update assuming identity measurement model with Bingham noise.

Applies the measurement z using likelihood based on Bingham noise bv.

Parameters: bv (BinghamDistribution): measurement noise distribution z (numpy.ndarray): measurement as a unit vector of shape (dim+1,)

Return the mode of the current distribution as a point estimate.

Initialize the CircularParticleFilter.

Parameters:

Compute the likelihood of association based on the PDF of the likelihood and the filter state.

Parameters:

Returns:

Initialise with a standard Gaussian at 0 with unit variance.

Parameters

alpha: UKF sigma-point spread parameter (default 1e-3). beta: UKF prior distribution parameter (default 2.0, optimal for Gaussian). kappa: UKF secondary scaling parameter (default 0.0).

Predict assuming identity system model: x(k+1) = x(k) + w(k) mod 2pi where w(k) is additive noise described by gauss_sys*.

Parameters

gauss_sys: Distribution of additive system noise (converted to :class:GaussianDistribution if necessary).

Predict assuming a nonlinear system model: x(k+1) = f(x(k)) + w(k) mod 2pi where w(k) is additive noise described by gauss_sys*.

Parameters

f: Function from [0, 2pi) to [0, 2pi). gauss_sys: Distribution of additive system noise.

Update assuming identity measurement model: z(k) = x(k) + v(k) mod 2pi where v(k) is additive noise described by gauss_meas*.

Parameters

gauss_meas: Distribution of additive measurement noise. z: Scalar measurement in [0, 2*pi).

Update assuming a nonlinear measurement model: z(k) = f(x(k)) + v(k) (if measurement_periodic is False) z(k) = f(x(k)) + v(k) mod 2pi (if measurement_periodic is True) where v(k) is additive noise described by gauss_meas*.

Parameters

f: Measurement function from [0, 2*pi) to R^d. gauss_meas: Distribution of additive measurement noise. z: Measurement vector of shape (d,). measurement_periodic: Whether the measurement is a periodic quantity.

Return the mean of the current state estimate.

Return a rounded-rectangle control polygon used by the toolbox demo.

Predict with identity dynamics and bounded additive process noise.

Predict boxes using an interval inclusion function.

inclusion_function must return (lower, upper) for the image of the input boxes. In vectorized mode it receives arrays with shape (n_boxes, dim); otherwise it is called once per box with vectors of shape (dim,).

Predict through nonlinear dynamics.

For guaranteed interval propagation, pass inclusion_function. If no inclusion function is supplied, the method encloses the images of the box corners. Corner enclosure is exact for affine maps and often useful for monotone maps, but it is not a mathematically guaranteed inclusion for an arbitrary nonlinear function.

Update by intersecting state boxes with an identity measurement box.

If the measurement model is z = x + v and measurement_noise_bounds is supplied as (v_lower, v_upper), the state constraint is x in [z_lower - v_upper, z_upper - v_lower].

Update by contracting predicted boxes.

contractor receives (lower, upper) or (lower, upper, measurement) and returns contracted (lower, upper) arrays. The Box PF likelihood is the contracted volume divided by the predicted volume. An optional additional likelihood can be multiplied in, evaluated at the contracted box centers.

Fallback update using a point likelihood at box centers.

Return the usual particle-filter effective sample size.

Multinomially resample boxes and split duplicates along their widest side.

Predict for nonlinear system model.

Return the Fourier basis vector or basis matrix for angle phi.

Evaluate the star-convex radial function at one or more angles.

Update from one or more 2-D measurements.

measurements may be a single vector, a (2, n) matrix, or a (n, 2) matrix. Each column/row is processed as one RHM contour or interior-source observation.

Return the posterior mean of the Poisson measurement rate.

Predict with a linear kinematic model and optional information decay.

Alias for :meth:predict_linear to match existing EOT tracker APIs.

Update from all detections generated by the target in one scan.

Find the minimum-cost measurement-to-track assignment.

Parameters

measurements : array-like, shape (dim_meas, n_meas) Measurements for the current update step. measurement_matrix : array-like Linear measurement model. cov_mats_meas : array-like Measurement covariance matrix or per-measurement covariance tensor. warn_on_no_meas_for_track : bool, optional Whether to emit a warning when a track remains unassigned. pairwise_cost_matrix : array-like, optional Additional target/measurement association costs of shape (n_targets, n_meas). These costs are added to the geometric cost matrix before running the Hungarian algorithm.

Update the tracker with an optional additional association cost matrix.

Construct the filter from separate position/velocity priors.

position_distribution and velocity_distribution may be Gaussian distributions, tuples (mean, covariance), or any objects exposing compatible first and second moments through mean() and either covariance() or C.

Reset the filter from separate position / velocity priors.

This is a convenience instance-level analogue of :meth:from_factorized_priors.

Reweight only the discrete hypotheses.

This is useful when an external spike / replay likelihood is already available and only the discrete goal/mode posterior should be updated.

Predict with the built-in goal-conditioned replay dynamics.

Predict with a shared nonlinear dynamics model for all components.

Update with a nonlinear measurement function via EKF linearization.

Reweight discrete goal hypotheses from a measurement in goal space.

This does not alter the continuous component states. It only updates the posterior weights over discrete goal/mode hypotheses.

Initialize the particle cloud from factorized component priors.

Backward-compatible alias for factorized initialization.

Each prior may be given either as a distribution, a single state vector to broadcast to all particles, or an explicit particle matrix.

Directly set particle states from component samples or distributions.

Replace the current goal particles by samples from a goal bank.

Approximate posterior mass over a candidate-goal bank.

Predict one replay step under the goal-conditioned sparse-jump model.

Rejuvenate position particles from a measurement-guided proposal.

position_proposal may be a linear distribution, a (mean, covariance) tuple, or a matrix of candidate positions. Candidate matrices are sampled with proposal_weights when provided. Velocity and goal particles, particle weights, and IMM mode indices in subclasses are left unchanged.

Update by position likelihood, then refresh positions from a proposal.

This is useful when the observation likelihood is available on a grid or candidate bank: the usual likelihood update preserves Bayesian reweighting/resampling of the augmented particles, while the proposal step moves a configurable subset of position particles onto measurement-supported states for subsequent replay predictions.

Set one discrete mode index per particle.

Sample particle mode indices from a prior probability vector.

Predict one replay step after Markov switching the particle modes.

Update the tracker with optional per-measurement reliabilities.

measurement_weights scales each measurement covariance block as R_i / weight_i. Zero-weight or masked measurements are skipped. active_measurement_mask can be used to explicitly disable cluttered, occluded, or otherwise unsupported measurements.

Constructor

Parameters: n_particles (int > 0): Number of particles to use dim (int > 0): Dimension

Sets the current system state

Parameters: dist_ (HyperhemisphericalDiracDistribution): New state

Predicts the next state for each hyperhemisphere

Parameters

no_of_grid_points : int Number of grid points on the hemisphere. dim : int Manifold dimension of the hyperhemisphere (e.g. 2 for S2-half). grid_type : str Grid type, defaults to 'leopardi_symm'.

Predict assuming an identity system model with noise d_sys.

Supported: :class:HyperhemisphericalWatsonDistribution, :class:WatsonDistribution, symmetric two-component :class:HypersphericalMixture of VMF distributions.

Parameters

d_sys : AbstractDistribution System noise distribution with the same dim as the filter.

Perform prediction using a precomputed transition density.

Parameters

f_trans : SdHalfCondSdHalfGridDistribution Must use the same grid as the current filter state.

Perform a measurement update assuming an identity measurement model.

Supported noise: :class:HyperhemisphericalWatsonDistribution, :class:WatsonDistribution, :class:VonMisesFisherDistribution (with mu[-1] == 0), symmetric :class:HypersphericalMixture.

Parameters

meas_noise : AbstractDistribution Measurement noise centred at [0, …, 0, 1]. z : array, shape (dim,) Measurement on the hemisphere.

Compute a point estimate from the dominant scatter-matrix eigenvector.

Returns

p : array, shape (dim,) Point estimate on the upper hemisphere.

Build a :class:SdHalfCondSdHalfGridDistribution from a noise distribution.

Parameters

d_sys : AbstractDistribution Supported: :class:HyperhemisphericalWatsonDistribution, :class:WatsonDistribution, symmetric :class:HypersphericalMixture. no_grid_points : int Number of grid points on the hemisphere.

Returns

SdHalfCondSdHalfGridDistribution

Constructor

Parameters: n_particles (int > 0): Number of particles to use dim (int > 0): Dimension

Sets the current system state

Parameters: dist_ (HyperhemisphericalDiracDistribution): New state

Initialize HypersphericalDummyFilter.

Parameters: dim (int >= 2): Manifold dimension of the hypersphere (e.g. 2 for S^2).

Predict assuming a nonlinear system model: x(k+1) = normalize(f(normalize(x(k)))) + w(k)

Parameters

f: Function from S^(d-1) to S^(d-1). gauss_sys: Distribution of additive system noise (mean is ignored).

Predict assuming nonlinear system model with arbitrary noise: x(k+1) = f(x(k), v_k)

Parameters

f: Function f(x, v) -> x_new where x is a unit vector in R^d. noise_samples: Array of shape (noise_dim, n_noise) with noise samples (columns). noise_weights: Array of length n_noise with positive weights.

Predict with identity system model: x(k+1) = x(k) + w(k)

Parameters

gauss_sys: Distribution of additive system noise (mean is ignored).

Update assuming a nonlinear measurement model: z(k) = f(normalize(x(k))) + v_k

Parameters

f: Measurement function from S^(d-1) to R^m. gauss_meas: Distribution of additive measurement noise (mean is ignored). z: Measurement vector of shape (m,) or scalar.

Update with identity measurement model: z(k) = x(k) + v_k

Parameters

gauss_meas: Distribution of additive measurement noise (mean is ignored). z: Measurement vector on S^(d-1).

Return the mean of the current state estimate (unit vector).

Initialize HypertoroidalDummyFilter.

Parameters: dim (int >= 1): Manifold dimension of the hypertorus (e.g. 1 for T^1).

Constructor.

Parameters

n_coefficients : int or tuple of int Number of Fourier coefficients per dimension. The length of the tuple determines the dimensionality of the distribution. transformation : str, optional Transformation to use ('sqrt' or 'identity'). Default is 'sqrt'.

Predicts assuming identity system model, i.e., x(k+1) = x(k) + w(k) mod 2*pi, where w(k) is additive noise given by d_sys.

Parameters

d_sys : AbstractHypertoroidalDistribution Distribution of additive noise.

Updates assuming identity measurement model, i.e., z(k) = x(k) + v(k) mod 2*pi, where v(k) is additive noise given by d_meas.

Parameters

d_meas : AbstractHypertoroidalDistribution Distribution of additive noise. z : array_like, shape (dim,) Measurement in [0, 2*pi)^dim.

Build a HypertoroidalFourierDistribution representing the transition density f(x_{k+1} | x_k) from a deterministic system function f and an additive noise distribution.

Parameters

f : callable Deterministic system function. Takes dim arrays (x_k values) and returns either a tuple of dim arrays or a single array (for dim == 1). Must support vectorized evaluation on N-D grids. noise_distribution : AbstractHypertoroidalDistribution Additive noise distribution.

Returns

HypertoroidalFourierDistribution 2*dim-dimensional transition density.

Predicts assuming a nonlinear system model, i.e., x(k+1) = f(x(k)) + w(k) mod 2*pi.

Parameters

f : callable System function. See get_f_trans_as_hfd for calling convention. noise_distribution : AbstractHypertoroidalDistribution Additive process noise distribution. truncate_joint_sqrt : bool, optional Whether to truncate the intermediate joint sqrt representation (only relevant for sqrt transformation). Default is True.

Predicts using a probabilistic transition density.

Parameters

f_trans : HypertoroidalFourierDistribution or callable Transition density f(x_{k+1} | x_k).

* If a ``HypertoroidalFourierDistribution``: the first ``dim``
  dimensions must be for x_{k+1} and the remaining ``dim``
  dimensions for x_k.  Its transformation must match that of
  the current filter state.
* If a callable: a function of 2*dim arguments (first dim for
  x_{k+1}, last dim for x_k); it is converted internally.

truncate_joint_sqrt : bool, optional Whether to truncate the intermediate joint sqrt coefficient tensor. Default is True.

Updates using an arbitrary likelihood function and measurement.

Parameters

likelihood : HypertoroidalFourierDistribution or callable * If a HypertoroidalFourierDistribution: used directly for the Bayes update (multiplication). z must be None. * If a callable likelihood(z, x): the likelihood function f(z | x), where both z and x are dim x n_pts arrays. z must be provided. z : array_like, shape (dim,), optional Measurement. Must be provided when likelihood is a callable.

Perform the IMM interaction (mixing) step.

The current model probabilities are propagated through the transition matrix, and a mixed Gaussian prior is computed for each destination model.

Predict each model with an identity system model.

sys_noise_covs and sys_inputs can either be shared across all models or be provided as lists/tuples with one entry per model.

Predict each model with a linear system model.

system_matrices, sys_noise_covs, and sys_inputs can either be shared across all models or be provided as lists/tuples with one entry per model.

Predict each model with a nonlinear transition function.

Parameters can be shared across all models or supplied per model. fx_args may be None, a single dictionary shared across all models, or a list/tuple of dictionaries.

Update each model with an identity measurement model.

meas_noises can either be shared across all models or be provided as a list/tuple with one entry per model.

Update each model with a linear measurement model.

measurement_matrices and meas_noises can either be shared across all models or be provided as lists/tuples with one entry per model.

Update each model with a nonlinear measurement function.

Because current nonlinear filters in PyRecEst do not expose a uniform predictive-likelihood interface, nonlinear IMM updates require externally supplied model likelihoods (or log-likelihoods).

Update model probabilities from external per-model likelihoods.

Return the IMM mean estimate.

Compute marginal association probabilities.

Returns: tuple[numpy.ndarray, numpy.ndarray] The first entry contains the marginal probabilities of shape (n_targets, n_meas + 1), where column 0 corresponds to a missed detection. The second entry is the most likely joint event, encoded as measurement indices and -1 for missed detections.

Create a Kalman filter from a Gaussian state.

Parameters

initial_state : GaussianDistribution or tuple Initial state distribution. Tuples must contain (mean, covariance) with mean shape (n,) or scalar shape for a one-dimensional state, and covariance shape (n, n).

Predict one step with an identity transition matrix.

Parameters

sys_noise_cov : array-like, shape (n, n) Additive process-noise covariance. sys_input : array-like, shape (n,), optional Additive deterministic input applied after the identity transition.

Predict one step with a linear Gaussian system model.

Parameters

system_matrix : array-like, shape (n, n) State-transition matrix F. sys_noise_cov : array-like, shape (n, n) Additive process-noise covariance Q. sys_input : array-like, shape (n,), optional Additive deterministic input u.

Predict one step with a linear Gaussian transition model object.

The model object is consumed structurally. It must expose a system_matrix attribute and either system_noise_cov or sys_noise_cov. If present, sys_input or system_input is forwarded as the deterministic transition input.

Parameters

transition_model : object Linear Gaussian transition model object compatible with :meth:predict_linear.

Update with a measurement matrix equal to the identity.

Parameters

meas_noise : array-like, shape (n, n) Measurement-noise covariance. measurement : array-like, shape (n,) Measurement vector. return_diagnostics : bool, optional If true, return update diagnostics after updating the filter state. scale : float, optional Multiplicative measurement-noise scale used for the update. action : str, optional Caller-defined diagnostic label for the update action.

Return innovation and innovation covariance for a linear measurement.

Return the normalized innovation squared for a linear measurement.

Update the state with a linear Gaussian measurement model.

Parameters

measurement : array-like, shape (m,) Measurement vector z. measurement_matrix : array-like, shape (m, n) Measurement matrix H mapping state vectors to measurement vectors. meas_noise : array-like, shape (m, m) Measurement-noise covariance R. return_diagnostics : bool, optional If true, return a diagnostics dictionary after updating the filter state. The dictionary contains nis, residual, scale, and action. scale : float, optional Multiplicative measurement-noise scale used for the update. action : str, optional Caller-defined diagnostic label for the update action.

Robustly update the state with a linear measurement model.

The Gaussian measurement covariance is adaptively inflated according to the normalized innovation squared. Supported modes are "student-t", "huber", "nis-inflate", and None/ "none". With robust_update=None and gate_threshold set, measurements above the gate are rejected and the prior state is kept.

Robustly update with a structural linear Gaussian model object.

Update the state with a linear Gaussian measurement model object.

The model object is consumed structurally. It must expose a measurement_matrix attribute and either meas_noise or measurement_noise_cov.

Parameters

measurement_model : object Linear Gaussian measurement model object compatible with :meth:update_linear. measurement : array-like, shape (m,) Measurement vector z. return_diagnostics : bool, optional If true, return update diagnostics after updating the filter state. scale : float, optional Multiplicative measurement-noise scale used for the update. action : str, optional Caller-defined diagnostic label for the update action.

Return the posterior mean vector with shape (n,).

Update the filter with new measurements using the linear measurement model.

Args: measurements (numpy.ndarray): Array of shape (dim_meas, n_meas) containing the measurements. measurementMatrix (numpy.ndarray): Array of shape (dim_meas, dim_state) containing the measurement matrix. covMatMeas (numpy.ndarray): Array of shape (dim_meas, dim_meas) containing the measurement noise covariance matrix. falseAlarmRate (float): Scalar representing the false alarm rate. Default is 0, which means that clutter is disabled. clutterCov (numpy.ndarray): Array of shape (dim_meas, dim_meas) containing the clutter covariance matrix. Default is None, which means that clutter is disabled. lambdaMultimeas (float): Scalar representing the scaling factor for multimeasurements. Default is 1, which means that multimeasurements are not used. enableGating (bool): If True, gating will be used to remove unlikely measurements before the update. Default is False. gatingThreshold (float): Scalar representing the gating threshold. Default is None, which means that the threshold is set to chi2inv(0.99, dim_meas).

Raises: AssertionError: If enableGating=True and gatingThreshold is None.

Compute mu_s, Sigma_s, Sigma_xs according to the Kernel SME multi-detection + clutter equations in the paper.

x_prior is stacked [x_1; ...; x_N], C_prior full covariance. lambdaMultimeas = lambda^l (Poisson mean number of detections per target). falseAlarmRate = lambda^c (Poisson mean number of clutter points per scan).

Update the moving average with a new manifold-valued sample.

Return the current manifold estimate.

Get the point estimate.

This method is responsible for getting the point estimate.

Returns:

Alias for :meth:predict_linear to match existing EOT tracker APIs.

Sequentially update from one or more 2-D target-originated measurements.

Return the single-target point estimate.

Create a multi-Bernoulli tracker.

Parameters

initial_prior : iterable, optional Initial Bernoulli components. Each item can be a :class:BernoulliComponent, (existence_probability, state), (existence_probability, state, label), or a single-target state accepted by :class:KalmanFilter. tracker_param : dict, optional Tracker parameters. Supported keys include survival and detection probabilities, clutter intensity, gating settings, pruning and capping limits, and optional birth settings. birth_components : iterable, optional Bernoulli components appended during prediction. log_prior_estimates : bool, optional If true, store prior estimates after prediction. log_posterior_estimates : bool, optional If true, store posterior estimates after update.

Return the number of Bernoulli components.

Return the existence probabilities of all Bernoulli components.

Return the cardinality PMF implied by the Bernoulli components.

Return the expected cardinality of the multi-Bernoulli posterior.

Return the MAP cardinality estimate.

Return the labels of all active Bernoulli components.

Return active Bernoulli components keyed by track label.

Parameters

copy_components : bool, optional If true, return deep copies. If false, return references to the tracker-owned components.

Return a Bernoulli component by track label.

Parameters

label : hashable Track label to retrieve. copy_component : bool, optional If true, return a deep copy. If false, return the tracker-owned component.

Return the labels of the extracted target states.

Parameters

number_of_targets : int, optional Number of most likely target states to extract. If omitted, use the MAP cardinality estimate.

Return extracted target states.

The state extraction follows a common multi-Bernoulli convention: the MAP cardinality is used, and the states of the Bernoulli components with the highest existence probabilities are returned.

Parameters

flatten_vector : bool, optional If true, flatten the output into a one-dimensional vector. number_of_targets : int, optional Number of most likely target states to extract. If omitted, use the MAP cardinality estimate.

Returns

array-like, shape (n, number_of_targets) Extracted point estimates. If flatten_vector is true, the result is flattened.

Return extracted target states together with persistent labels.

Returns

tuple (labels, point_estimates) where labels is a list of persistent track labels and point estimates has shape (n, number_of_targets) unless flatten_vector is true.

Remove Bernoulli components with low existence probability.

Keep only the Bernoulli components with the highest existence probability.

Predict all Bernoulli components with a linear/Gaussian model.

Parameters

system_matrices : array-like, shape (n, n) or (n, n, num_components) Shared or per-component state-transition matrices. sys_noises : array-like or GaussianDistribution Shared process-noise covariance with shape (n, n), per-component covariances with shape (n, n, num_components), or a zero-mean :class:GaussianDistribution. inputs : array-like, optional Shared input with shape (n,) or per-component inputs with shape (n, num_components). birth_components : iterable, optional Components appended after prediction instead of the tracker's stored birth components.

Find the best measurement-to-Bernoulli association.

Parameters

measurements : array-like, shape (m,) or (m, num_measurements) Measurement vector or measurement matrix. measurement_matrix : array-like, shape (m, n) Linear map from state vectors to measurement vectors. cov_mats_meas : array-like, shape (m, m) or (m, m, num_measurements) Shared or per-measurement covariance matrices.

Update the tracker with linear/Gaussian measurements.

Parameters

measurements : array-like, shape (m,) or (m, num_measurements) Measurement vector or matrix whose columns are individual measurements. measurement_matrix : array-like, shape (m, n) Linear map from state vectors to measurement vectors. cov_mats_meas : array-like, shape (m, m) or (m, m, num_measurements) Shared measurement-noise covariance or per-measurement covariance matrices.

Append value at time and return its timestamped record.

Remove all buffered entries.

Return true if time precedes the current latest timestamp.

Return true if time is acceptable under the fixed-lag window.

Return the latest record with timestamp at or before time.

Return all records with timestamp strictly greater than time.

Return all records with timestamp greater than or equal to time.

Store a measurement and return the resulting record.

Record/apply a timestamped linear-Gaussian prediction.

Record/apply a timestamped structural transition-model prediction.

Record/apply a timestamped linear-Gaussian measurement update.

Record/apply a timestamped robust linear-Gaussian update.

Record/apply a timestamped structural measurement-model update.

Record/apply a timestamped robust structural measurement-model update.

Record/apply a timestamped particle transition-model prediction.

Record/apply a timestamped nonlinear particle prediction.

Record/apply a timestamped particle measurement-model update.

Record/apply a timestamped likelihood-based particle update.

Replace the block weights and refresh the compatibility weights.

Replace particles and optionally global or block weights.

Return the weight vector used for one SO(3) component.

Return one effective sample size per partition block.

Return the mean block effective sample size.

Return the component-wise chordal mean using block-specific weights.

Return a block-wise modal product particle.

Since the posterior is represented as a product over blocks, the returned point may be a hybrid assembled from different source particles.

Return the component-wise SO(3) mean.

Systematically resample one partition block and reset its weights.

Systematically resample selected blocks and reset their weights.

Update block weights from nonnegative block likelihoods.

The likelihood must evaluate to an array shaped (n_blocks, n_particles). Each row updates the corresponding block's weights independently.

Update block weights from block log-likelihoods.

The log-likelihood must evaluate to an array shaped (n_blocks, n_particles). Each row updates the corresponding block's weights independently using log-sum-exp normalization.

Update from per-component likelihoods shaped (n_particles, K).

Update from per-component log-likelihoods shaped (n_particles, K).

Update partition weights with masked component geodesic log-likelihoods.

Update with masked geodesic likelihoods per partition block.

This preserves the existing likelihood-space API while delegating to the log-likelihood implementation for numerical stability.

Initialize the filter with a uniform distribution over n intervals.

Parameters

n : int Number of discretization intervals.

Perform prediction step based on a transition matrix.

Parameters

sys_matrix : array_like, shape (L, L) System/transition matrix. Entry (j, i) gives the probability of transitioning from interval i to interval j.

Perform measurement update based on a measurement matrix.

Parameters

meas_matrix : array_like, shape (Lw, L) Measurement matrix. Row z_row gives the likelihoods for each state interval when the measurement falls in measurement interval z_row. z : scalar Measurement in [0, 2*pi).

Perform measurement update using a likelihood function.

Parameters

likelihood : callable Function likelihood(z, x) returning f(z | x), where z is the measurement and x is the state value. Maps Z x [0, 2*pi) -> [0, infinity). z : arbitrary Measurement.

Return the mean direction of the filter state.

Obtain the system matrix by 2-D numerical integration from a system function.

Parameters

L : int Number of discretization intervals. a : callable System function x_{k+1} = a(x_k, w_k). Must accept scalar arguments and return a scalar. noise_distribution : AbstractCircularDistribution Distribution of the process noise, defined on [0, 2*pi).

Returns

A : ndarray, shape (L, L) System transition matrix. Entry (j, i) is the probability of transitioning from state interval i to state interval j.

Obtain the measurement matrix by 2-D numerical integration from a measurement function.

Parameters

L : int Number of discretization intervals for the state. l_meas : int Number of discretization intervals for the measurement. h : callable Measurement function z_k = h(x_k, v_k). Must accept scalar arguments and return a scalar. noise_distribution : AbstractCircularDistribution Distribution of the measurement noise, defined on [0, 2*pi).

Returns

H : ndarray, shape (l_meas, L) Measurement matrix. Entry (i, j) is the probability that the measurement falls in measurement interval i given that the state is in state interval j.

Predict with a left-multiplicative noise model on SE(2).

The motion model is::

x_{t+1} = v [⊕] x_t

where v is the system noise. The mean of gauss_sys encodes the (dual-quaternion) noise mean; the noise is assumed zero-mean in the manifold sense.

Parameters

gauss_sys : GaussianDistribution System noise distribution. Must have a 4-D mean (first two entries normalised) and a 4×4 covariance.

Incorporate a dual-quaternion measurement.

The measurement model is::

z = x [⊕] v

where v is the measurement noise.

Parameters

gauss_meas : GaussianDistribution Measurement noise distribution. Must have a 4-D mean (first two entries normalised) and a 4×4 covariance. z : array_like, shape (4,) Measurement in dual-quaternion representation.

Return the mean of the current state estimate.

Map detector confidence values in [0, 1] to SO(3) noise scales.

The mapping is sigma(c)^2 = noise_std^2 + (1 - c)^confidence_exponent * (max_noise_std^2 - noise_std^2).

Replace particles and optionally weights.

Return the component-wise chordal mean product rotation.

Return the highest-weight product particle.

Return the component-wise SO(3) mean.

Return the particle effective sample size.

Systematically resample particles and reset weights to uniform.

Apply tangent-space deltas and optional tangent Gaussian noise.

Predict with identity dynamics and optional tangent Gaussian noise.

Apply a nonlinear transition on product particles.

Update weights from a likelihood evaluated on product particles.

Update weights from log-likelihoods evaluated on product particles.

Return per-component masked geodesic log-likelihoods.

The returned array has shape (n_particles, num_rotations). Masks deactivate components, confidence values in [0, 1] scale each component's log-likelihood contribution, component_noise_std supplies heteroskedastic per-component noise, and outlier_prob adds an unnormalized constant likelihood floor for robustness.

Return one masked geodesic log-likelihood per product particle.

Update with a masked, confidence-aware geodesic log-likelihood.

Update with a masked geodesic likelihood on SO(3)^K.

This method preserves the existing likelihood-space API and delegates to the log-likelihood implementation for numerical stability.

Create a filter by sampling tangent noise around mean.

Convert packed real SH coefficients to PyRecEst's coefficient matrix.

Pack PyRecEst's real SH coefficient matrix degree by degree.

Rotate packed real SH coefficients by ZYZ Euler angles in radians.

Evaluate the raw radial SH extent for Cartesian unit directions.

Evaluate the current radial extent for Cartesian directions.

Return object surface points for Cartesian rays from center.

MATLAB-equivalent stacked point measurement equation.

Update from one or more 3-D point measurements.

The measurement equation is the one used in the MATLAB SphericalHarmonicsAdditiveMeasmodel: each observed point defines a bearing from the hypothesized center, and the predicted measurement is the surface point at the current SH radius along that bearing.

Perform the prediction step.

Parameters

transition_density : AbstractConditionalDistribution or None Conditional grid distribution f(next | current) for the periodic/bounded part, where grid_values[i, j] = f(next=i | current=j). If None, the periodic transition is assumed to be a Dirac (identity), and only the linear part is updated. covariance_matrices : array or None Process-noise covariance(s) for the linear part. Shape (lin_dim, lin_dim) for a single matrix applied to all areas, or (lin_dim, lin_dim, n_areas) for per-area matrices (indexed by the prior area in Case 3, or the current area in Case 2). None means no additive noise. system_matrices : array or None System matrix/matrices for the linear part. Shape (lin_dim, lin_dim) for a single matrix, or (lin_dim, lin_dim, n_areas) for per-area matrices (indexed by the prior area). None means the identity matrix. linear_input_vectors : array or None Deterministic input vector(s) for the linear part. Shape (lin_dim,) for a single vector or (lin_dim, n_areas) for per-area vectors (indexed by the prior area). None means zero input.

Perform the measurement update step.

Parameters

likelihood_periodic_grid : array or AbstractDistribution or None Likelihood values on the periodic grid. If an AbstractDistribution is given, it is evaluated at the grid points. Must have the same shape as filter_state.gd.grid_values or be None (uniform likelihood over the bounded domain). likelihoods_linear : list of GaussianDistribution or None Gaussian likelihood(s) for the linear part. Either a list with one element (applied to all areas) or a list with as many elements as there are grid points. None means uniform likelihood.

Return the current filter state.

Return the hybrid mean (periodic mean + linear mean).

Return the current point estimate of the track.

Return managed tracks matching the requested visibility flags.

Return the number of extracted tracks.

Return stacked point estimates of the extracted tracks.

Create tracks directly from filters or filter states.

Create tracks from measurements using self.initiator.

Add a new track and return its track id.

Physically remove deleted tracks and return the number removed.

Run one complete lifecycle step.

Propagate the filter state.

Parameters

omega: Control / input passed to f. Set to None if f does not use it (the filter passes it through). dt: Integration step (seconds).

Update the filter with a new measurement.

Parameters

y: 1-D measurement vector, shape (l,).

Return the current state estimate (manifold element).

Parameters:

Run a prediction step using an additive-noise transition model.

This is an adapter around :meth:predict_nonlinear; it does not change the UKF algorithm or deprecate the existing function/covariance API.

Parameters

model: Reusable transition model containing the deterministic transition function and additive process-noise covariance. dt: Optional time step overriding model.dt. fx_args: Optional transition-function keyword arguments overriding the model's default function_args for this prediction.

Run an update step using an additive-noise measurement model.

This is an adapter around :meth:update_nonlinear; it preserves the existing direct nonlinear update API while allowing model-object reuse.

Constructor

Predicts assuming identity system model, i.e., x(k+1) = x(k) + w(k) mod 2*pi, where w(k) is additive noise given by vmSys.

Parameters: vmSys (VMDistribution) : distribution of additive noise

Updates assuming identity measurement model, i.e., z(k) = x(k) + v(k) mod 2*pi, where v(k) is additive noise given by vmMeas.

Parameters: vmMeas (VMDistribution) : distribution of additive noise z : measurement in [0, 2pi)

Set the filter state.

Return the mean direction of the current filter state.

State prediction via mulitiplication. Provide zonal density for update Could add support for a rotation Q

State update via mulitiplication. Provide zonal density for update Could add support for a rotation Q

Initialize the filter.

Predicts using an identity system model.