Sensors

class stonesoup.sensor.base.PlatformMountable(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]

Bases: Base, ABC

Base class for any object that can be mounted on a platform.

All PlatformMountables must be mounted on a platform to calculate their position and orientation. To make this easier, if the sensor has a position and/or orientation specified in the constructor, and no platform_system, then the default is to create an internally held “private” platform for the Sensor. This allows the Sensor to control (and set) its own position and orientation.

Parameters:

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

rotation_offset: StateVector

A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

mounting_offset: StateVector

A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

movement_controller: Movable

The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

property position: StateVector | None

The sensor position on a 3D Cartesian plane, expressed as a 3x1 StateVector of Cartesian coordinates in the order \(x,y,z\).

Note

This property delegates the actual calculation of position to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller.

property orientation: StateVector | None

A 3x1 StateVector of angles (rad), specifying the sensor orientation in terms of the counter-clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

Note

This property delegates the actual calculation of orientation to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller.

property velocity: StateVector | None

The sensor velocity on a 3D Cartesian plane, expressed as a 3x1 StateVector of Cartesian coordinates in the order \(x,y,z\).

Note

This property delegates the actual calculation of velocity to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller which is a MovingMovable.

class stonesoup.sensor.sensor.Sensor(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]

Bases: PlatformMountable, Actionable

Sensor Base class for general use.

Most properties and methods are inherited from PlatformMountable.

Notes

  • Sensors must have a measure function.

  • Attributes that are modifiable via actioning the sensor should be ActionableProperty types.

  • The sensor has a timestamp property that should be updated via its act() method.

Parameters:

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

validate_timestamp()[source]

Method to validate the timestamp of the actionable.

Returns:

True if timestamp is valid, False otherwise.

Return type:

bool

abstractmethod measure(ground_truths: set[GroundTruthState], noise: ndarray | bool = True, **kwargs) → set[TrueDetection][source]

Generate a measurement for a given state

Parameters:
Returns:

A set of measurements generated from the given states. The timestamps of the measurements are set equal to that of the corresponding states that they were calculated from. Each measurement stores the ground truth path that it was produced from.

Return type:

Set[TrueDetection]

abstract property measurement_model

Measurement model of the sensor, describing general sensor model properties

class stonesoup.sensor.sensor.SimpleSensor(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None, clutter_model: ClutterModel = None)[source]

Bases: Sensor, ABC

Parameters:

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

  • clutter_model (ClutterModel, optional) – An optional clutter generator that adds a set of simulated Clutter objects to the measurements at each time step. The clutter is simulated according to the provided distribution.

clutter_model: ClutterModel

An optional clutter generator that adds a set of simulated Clutter objects to the measurements at each time step. The clutter is simulated according to the provided distribution.

measure(ground_truths: set[GroundTruthState], noise: ndarray | bool = True, **kwargs) → set[TrueDetection][source]

Generate a measurement for a given state

Parameters:
Returns:

A set of measurements generated from the given states. The timestamps of the measurements are set equal to that of the corresponding states that they were calculated from. Each measurement stores the ground truth path that it was produced from.

Return type:

Set[TrueDetection]

class stonesoup.sensor.sensor.SensorSuite(sensors: Sequence[Sensor], attributes_inform: set[str], rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]

Bases: Sensor

Sensor composition type

Models a suite of sensors all returning detections at the same ‘time’. Returns all detections in one go. Can append information of the sensors to the metadata of their corresponding detections.

Parameters:

  • sensors (collections.abc.Sequence) – Suite of sensors to get detections from.

  • attributes_inform (set) – Names of attributes to store the value of at time of detection.

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

sensors: Sequence[Sensor]

Suite of sensors to get detections from.

attributes_inform: set[str]

Names of attributes to store the value of at time of detection.

measure(ground_truths: set[GroundTruthState], noise: bool | ndarray = True, **kwargs) → set[TrueDetection][source]

Call each sub-sensor’s measure method in turn. Key word arguments are passed to the measure method of each sensor.

Append additional metadata to each sensor’s set of detections. Which keys are appended is dictated by attributes_inform.

property measurement_model

Measurement model of the sensor, describing general sensor model properties

Passive

class stonesoup.sensor.passive.PassiveElevationBearing(ndim_state: int, mapping: ndarray, noise_covar: CovarianceMatrix, rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None, clutter_model: ClutterModel = None)[source]

Bases: SimpleSensor

A simple passive sensor that generates measurements of targets, using a CartesianToElevationBearing model, relative to its position.

Note

The current implementation of this class assumes a 3D Cartesian plane.

Parameters:

  • ndim_state (int) – Number of state dimensions. This is utilised by (and follows in format) the underlying CartesianToElevationBearing model

  • mapping (numpy.ndarray) – Mapping between the targets state space and the sensors measurement capability

  • noise_covar (CovarianceMatrix) – The sensor noise covariance matrix. This is utilised by (and follow in format) the underlying CartesianToElevationBearing model

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

  • clutter_model (ClutterModel, optional) – An optional clutter generator that adds a set of simulated Clutter objects to the measurements at each time step. The clutter is simulated according to the provided distribution.

ndim_state: int

Number of state dimensions. This is utilised by (and follows in format) the underlying CartesianToElevationBearing model

mapping: ndarray

Mapping between the targets state space and the sensors measurement capability

noise_covar: CovarianceMatrix

The sensor noise covariance matrix. This is utilised by (and follow in format) the underlying CartesianToElevationBearing model

property measurement_model

Measurement model of the sensor, describing general sensor model properties

Categorical

class stonesoup.sensor.categorical.HMMSensor(measurement_model: MarkovianMeasurementModel, rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]

Bases: Sensor

Sensor model that observes a categorical state space and returns categorical measurements.

Measurements are categorical distributions over a finite set of categories \(Z = \{\zeta^n|n\in \mathbf{N}, n\le N\}\) (for some finite \(N\)).

Parameters:

  • measurement_model (MarkovianMeasurementModel) – Measurement model to generate detection vectors from

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

measurement_model: MarkovianMeasurementModel

Measurement model to generate detection vectors from

measure(ground_truths, noise: bool = True, **kwargs)[source]

Generate a categorical measurement for a given set of true categorical state.

Parameters:

  • ground_truths (Set[CategoricalGroundTruthState]) – A set of CategoricalGroundTruthState.

  • noise (bool) – Indicates whether measurement vectors are sampled from and the resultant measurement categories returned instead. These are discrete categories instead of a distribution over the measurement space. They are represented by N-tuples, with all components equal to 0, except at an index corresponding to the relevant category. For example \(e^k\) indicates that the measurement category is \(\zeta^k\). If False, the resultant distribution is returned.

Returns:

A set of measurements generated from the given states. The timestamps of the measurements are set equal to that of the corresponding states that they were calculated from. Each measurement stores the ground truth path that it was produced from.

Return type:

Set[TrueCategoricalDetection]

Gas

class stonesoup.sensor.gas.GasIntensitySensor(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None, min_noise: float = 0.0001, standard_deviation_percentage: float = 0.5, missed_detection_probability: Probability = 0.1, sensing_threshold: float = 0.0001)[source]

Bases: Sensor

A simple gas sensor that measures the concentration of gas at the location of the sensor. It implements the IsotropicPlume model for calculating concentration.

Parameters:

  • rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

  • mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

  • movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

  • min_noise (float, optional) – The minimum noise added to sensor measurements

  • standard_deviation_percentage (float, optional) – Standard deviation as a percentage of the concentration level

  • missed_detection_probability (Probability, optional) – The probability that the detection has detection has been affected by turbulence and therefore not sensed the gas.

  • sensing_threshold (float, optional) – Measurement threshold. Should be set high enough to minimise false detections.

min_noise: float

The minimum noise added to sensor measurements

standard_deviation_percentage: float

Standard deviation as a percentage of the concentration level

missed_detection_probability: Probability

The probability that the detection has detection has been affected by turbulence and therefore not sensed the gas.

sensing_threshold: float

Measurement threshold. Should be set high enough to minimise false detections.

measure(ground_truths: set[GroundTruthState], noise: ndarray | bool = True, **kwargs) → set[TrueDetection][source]

Generate a measurement for a given state

Parameters:
Returns:

A set of measurements generated from the given states. The timestamps of the measurements are set equal to that of the corresponding states that they were calculated from. Each measurement stores the ground truth path that it was produced from.

Return type:

Set[TrueDetection]

property measurement_model

Measurement model of the sensor, describing general sensor model properties