Sensors
- class stonesoup.sensor.base.PlatformMountable(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]
-
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’svelocity_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 3movement_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: Optional[StateVector]
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: Optional[StateVector]
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: Optional[StateVector]
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(resolutions: dict = None, 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
resolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.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’svelocity_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 3movement_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
- abstract measure(ground_truths: Set[GroundTruthState], noise: Union[ndarray, bool] = True, **kwargs) Set[TrueDetection] [source]
Generate a measurement for a given state
- Parameters
ground_truths (Set[
GroundTruthState
]) – A set ofGroundTruthState
noise (
numpy.ndarray
or bool) – An externally generated random process noise sample (the default is True, in which caservs()
is used; if False, no noise will be added)
- 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(resolutions: dict = None, rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None, clutter_model: ClutterModel = None)[source]
-
- Parameters
resolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.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’svelocity_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 3movement_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 simulatedClutter
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: Union[ndarray, bool] = True, **kwargs) Set[TrueDetection] [source]
Generate a measurement for a given state
- Parameters
ground_truths (Set[
GroundTruthState
]) – A set ofGroundTruthState
noise (
numpy.ndarray
or bool) – An externally generated random process noise sample (the default is True, in which caservs()
is used; if False, no noise will be added)
- 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], resolutions: dict = None, 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 (
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.resolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.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’svelocity_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 3movement_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.
- measure(ground_truths: Set[GroundTruthState], noise: Union[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, resolutions: dict = None, 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 underlyingCartesianToElevationBearing
modelmapping (
numpy.ndarray
) – Mapping between the targets state space and the sensors measurement capabilitynoise_covar (
CovarianceMatrix
) – The sensor noise covariance matrix. This is utilised by (and follow in format) the underlyingCartesianToElevationBearing
modelresolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.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’svelocity_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 3movement_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 simulatedClutter
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
- 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, resolutions: dict = None, 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 fromresolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.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’svelocity_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 3movement_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 ofCategoricalGroundTruthState
.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
Actionable
- class stonesoup.sensor.actionable.ActionableProperty(generator_cls, cls=None, *, default, doc=None, readonly=False)[source]
Bases:
Property
Property that is modified via an
Action
with defined, non-equal start and end times.
- class stonesoup.sensor.actionable.Actionable(resolutions: dict = None)[source]
-
Base Actionable type.
Contains the core methods of an actionable sensor/platform type.
Notes
An Actionable is required to have a timestamp attribute, in order to validate actions and act. This is an abstract base class, and not intended for direct use. Attaining a timestamp is left to the inheriting type.
- Parameters
resolutions (
dict
, optional) – Mapping of eachActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.
- resolutions: dict
Mapping of each
ActionableProperty
of the sensor and corresponding resolutions at which the sensor is able to be tasked.
- actions(timestamp: datetime, start_timestamp: Optional[datetime] = None) Set[ActionGenerator] [source]
Method to return a set of action generators available up to a provided timestamp.
A generator is returned for each actionable property that the sensor has.
- Parameters
timestamp (datetime.datetime) – Time of action finish.
start_timestamp (datetime.datetime, optional) – Time of action start.
- Returns
Set of action generators, that describe the bounds of each action space.
- Return type
set of
ActionGenerator
- add_actions(actions: Sequence[Action]) bool [source]
Add actions to the sensor
- Parameters
actions (sequence of
Action
) – Sequence of actions that will be executed in order- Returns
Return True if actions accepted. False if rejected. Returns neither if timestamp is invalid.
- Return type
- Raises
NotImplementedError – If sensor cannot be tasked.
Notes
Base class returns True
- act(timestamp: datetime)[source]
Carry out actions up to a timestamp.
- Parameters
timestamp (datetime.datetime) – Carry out actions up to this timestamp.