Platforms¶
-
class
stonesoup.platform.base.
Platform
(states, position_mapping, rotation_offsets=None, mounting_offsets=None, sensors=None, velocity_mapping=None)[source]¶ Bases:
stonesoup.types.state.StateMutableSequence
,abc.ABC
A platform that can carry a number of different sensors.
The location of platform mounted sensors will be maintained relative to the sensor position. Platforms move within a 2 or 3 dimensional rectangular cartesian space.
A simple platform is considered to always be aligned with its principle velocity. It does not take into account issues such as bank angle or body deformation (e.g. flex).
Note
This class abstract and not intended to be instantiated. To get the behaviour of this class use a subclass which gives movement behaviours. Currently these are
FixedPlatform
andMovingPlatform
- Parameters
states (
Sequence[State]
) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form[x, y, z]
. For a moving platform it would contain position and velocity interleaved:[x, vx, y, vy, z, vz]
position_mapping (
Sequence[int]
) – Mapping between platform position and state vector. For a position-only 3d platform this might be[0, 1, 2]
. For a position and velocity platform:[0, 2, 4]
rotation_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors 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’sposition_mapping
mounting_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’sposition_mapping
sensors (
MutableSequence[ForwardRef('BaseSensor')]
, optional) – A list of N mounted sensors. Defaults to an empty listvelocity_mapping (
Sequence[int]
, optional) – Mapping between platform velocity and state dims. If not set, it will default to[m+1 for m in position_mapping]
-
states
: Sequence[stonesoup.types.state.State]¶ A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form
[x, y, z]
. For a moving platform it would contain position and velocity interleaved:[x, vx, y, vy, z, vz]
-
position_mapping
: Sequence[int]¶ Mapping between platform position and state vector. For a position-only 3d platform this might be
[0, 1, 2]
. For a position and velocity platform:[0, 2, 4]
-
velocity_mapping
: Sequence[int]¶ Mapping between platform velocity and state dims. If not set, it will default to
[m+1 for m in position_mapping]
-
property
position
¶ Return the position of the platform.
Extracted from the state vector of the platform using the platform’s
position_mapping
. This property is settable for fixed platforms, but not for movable ones, where the position must be set by moving the model with a transition model.
-
sensors
: MutableSequence[BaseSensor]¶ A list of N mounted sensors. Defaults to an empty list
-
mounting_offsets
: MutableSequence[stonesoup.types.array.StateVector]¶ A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’s
position_mapping
-
rotation_offsets
: MutableSequence[stonesoup.types.array.StateVector]¶ A list of StateVectors 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
position_mapping
-
property
ndim
¶ Convenience property to return the number of dimensions in which the platform operates.
Given by the length of the
position_mapping
-
abstract property
orientation
¶ Return the orientation of the platform.
Implementation is case dependent and left to the Fixed/Moving subclasses
-
abstract property
velocity
¶ Return the velocity of the platform.
Implementation is case dependent and left to the Fixed/Moving subclasses
-
abstract
move
(timestamp: datetime.datetime, **kwargs) → None[source]¶ Update the platform position using the
transition_model
.- Parameters
timestamp (
datetime.datetime
, optional) – A timestamp signifying when the end of the maneuver (the default isNone
)
Notes
This methods updates the value of
position
.Any provided
kwargs
are forwarded to thetransition_model
.If
transition_model
ortimestamp
isNone
, the method has no effect, but will return successfully.
-
add_sensor
(sensor: BaseSensor, mounting_offset: Optional[stonesoup.types.array.StateVector] = None, rotation_offset: Optional[stonesoup.types.array.StateVector] = None) → None[source]¶ Add a sensor to the platform
- Parameters
sensor (
BaseSensor
) – The sensor object to addmounting_offset (
StateVector
, optional) – A StateVector with the mounting offset of the new sensor. If not supplied, defaults to a zero vectorrotation_offset (
StateVector
, optional) – A StateVector with the rotation offset of the new sensor. If not supplied, defaults to a zero vector.
-
remove_sensor
(sensor: BaseSensor) → None[source]¶ Remove a sensor from the platform
- Parameters
sensor (
BaseSensor
) – The sensor object to remove
-
pop_sensor
(index: int)[source]¶ Remove a sensor from the platform by index
- Parameters
index (int) – The index of the sensor to remove
-
get_sensor_position
(sensor: BaseSensor) → stonesoup.types.array.StateVector[source]¶ Return the position of the given sensor, which should be already attached to the platform. If the sensor is not attached to the platform, raises a
ValueError
.- Parameters
sensor (
BaseSensor
) – The sensor for which to return the position.- Returns
The position of the sensor, taking into account the platform position and orientation and the mounting offset of the sensor.
- Return type
StateVector
-
get_sensor_orientation
(sensor: BaseSensor) → stonesoup.types.array.StateVector[source]¶ Return the orientation of the given sensor, which should be already attached to the platform. If the sensor is not attached to the platform, raises a
ValueError
.- Parameters
sensor (
BaseSensor
) – The sensor for which to return the orientation.- Returns
The orientation of the sensor, taking into account the platform orientation and the rotation offset of the sensor.
- Return type
StateVector
-
class
stonesoup.platform.base.
FixedPlatform
(states, position_mapping, rotation_offsets=None, mounting_offsets=None, sensors=None, velocity_mapping=None, orientation=None)[source]¶ Bases:
stonesoup.platform.base.Platform
Fixed platform base class
A platform represents a random object defined as a
State
with fixed (but settable) position and orientation.Note
Position and orientation are a read/write properties in this class.
- Parameters
states (
Sequence[State]
) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form[x, y, z]
. For a moving platform it would contain position and velocity interleaved:[x, vx, y, vy, z, vz]
position_mapping (
Sequence[int]
) – Mapping between platform position and state vector. For a position-only 3d platform this might be[0, 1, 2]
. For a position and velocity platform:[0, 2, 4]
rotation_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors 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’sposition_mapping
mounting_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’sposition_mapping
sensors (
MutableSequence[ForwardRef('BaseSensor')]
, optional) – A list of N mounted sensors. Defaults to an empty listvelocity_mapping (
Sequence[int]
, optional) – Mapping between platform velocity and state dims. If not set, it will default to[m+1 for m in position_mapping]
orientation (
StateVector
, optional) – A fixed orientation of the static platform. Defaults to the zero vector
-
orientation
: stonesoup.types.array.StateVector¶ A fixed orientation of the static platform. Defaults to the zero vector
-
property
velocity
¶ Return the velocity of the platform.
For a fixed platform this is always a zero vector of length
ndim
.
-
property
is_moving
¶ Return the
True
if the platform is moving,False
otherwise.
-
move
(timestamp: datetime.datetime, **kwargs) → None[source]¶ For a fixed platform this method has no effect other than to update the timestamp.
-
class
stonesoup.platform.base.
MovingPlatform
(states, position_mapping, transition_model, rotation_offsets=None, mounting_offsets=None, sensors=None, velocity_mapping=None)[source]¶ Bases:
stonesoup.platform.base.Platform
Moving platform base class
A platform represents a random object defined as a
State
that moves according to a givenTransitionModel
.Note
Position and orientation are a read only properties in this class.
- Parameters
states (
Sequence[State]
) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form[x, y, z]
. For a moving platform it would contain position and velocity interleaved:[x, vx, y, vy, z, vz]
position_mapping (
Sequence[int]
) – Mapping between platform position and state vector. For a position-only 3d platform this might be[0, 1, 2]
. For a position and velocity platform:[0, 2, 4]
transition_model (
TransitionModel
) – Transition modelrotation_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors 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’sposition_mapping
mounting_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’sposition_mapping
sensors (
MutableSequence[ForwardRef('BaseSensor')]
, optional) – A list of N mounted sensors. Defaults to an empty listvelocity_mapping (
Sequence[int]
, optional) – Mapping between platform velocity and state dims. If not set, it will default to[m+1 for m in position_mapping]
-
transition_model
: stonesoup.models.transition.base.TransitionModel¶ Transition model
-
property
velocity
¶ Return the velocity of the platform.
Extracted from the state vector of the platform using the platform’s
velocity_mapping
. If the state vector is too short and does not contain the elements specified in thevelocity_mapping
this raises anAttributeError
-
property
orientation
¶ Return the orientation of the platform.
This is defined as 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.
The orientation of this platform is defined as along the direction of its velocity, with roll always set to zero (as this is the angle the platform is rotated about the velocity axis, which is not defined in this approximation).
Notes
A non-moving platform (
self.is_moving == False
) does not have a defined orientation in this approximations and so raises anAttributeError
-
property
is_moving
¶ Return the
True
if the platform is moving,False
otherwise.Equivalent (for this class) to
all(v == 0 for v in self.velocity)
-
move
(timestamp=None, **kwargs) → None[source]¶ Propagate the platform position using the
transition_model
.- Parameters
timestamp (
datetime.datetime
, optional) – A timestamp signifying when the end of the maneuver (the default isNone
)
Notes
This methods updates the value of
position
.Any provided
kwargs
are forwarded to thetransition_model
.If
transition_model
ortimestamp
isNone
, the method has no effect, but will return successfully.
-
class
stonesoup.platform.base.
MultiTransitionMovingPlatform
(states, position_mapping, transition_models, transition_times, rotation_offsets=None, mounting_offsets=None, sensors=None, velocity_mapping=None)[source]¶ Bases:
stonesoup.platform.base.MovingPlatform
Moving platform with multiple transition models
A list of transition models are given with corresponding transition times, dictating the movement behaviour of the platform for given durations.
- Parameters
states (
Sequence[State]
) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form[x, y, z]
. For a moving platform it would contain position and velocity interleaved:[x, vx, y, vy, z, vz]
position_mapping (
Sequence[int]
) – Mapping between platform position and state vector. For a position-only 3d platform this might be[0, 1, 2]
. For a position and velocity platform:[0, 2, 4]
transition_models (
Sequence[TransitionModel]
) – List of transition modelstransition_times (
Sequence[datetime.timedelta]
) – Durations for each listed transition modelrotation_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors 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’sposition_mapping
mounting_offsets (
MutableSequence[StateVector]
, optional) – A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’sposition_mapping
sensors (
MutableSequence[ForwardRef('BaseSensor')]
, optional) – A list of N mounted sensors. Defaults to an empty listvelocity_mapping (
Sequence[int]
, optional) – Mapping between platform velocity and state dims. If not set, it will default to[m+1 for m in position_mapping]
-
transition_models
: Sequence[stonesoup.models.transition.base.TransitionModel]¶ List of transition models
-
transition_times
: Sequence[datetime.timedelta]¶ Durations for each listed transition model
-
property
transition_model
¶ Transition model
-
move
(timestamp=None, **kwargs) → None[source]¶ Propagate the platform position using the
transition_model
.- Parameters
timestamp (
datetime.datetime
, optional) – A timestamp signifying the end of the maneuver (the default isNone
)
Notes
This methods updates the value of
position
.Any provided
kwargs
are forwarded to thetransition_model
.If
transition_model
ortimestamp
isNone
, the method has no effect, but will return successfully.This method updates
transition_model
,transition_index
andcurrent_interval
: If the timestamp provided gives a time delta greater thancurrent_interval
thetransition_model
is called for the rest of its corresponding duration, and the move method is called again on the next transition model (by incrementingtransition_index
) intransition_models
with the residue time delta. If the time delta is less thancurrent_interval
thetransition_model
is called for that duration andcurrent_interval
is reduced accordingly.