Feeders¶
Feeder classes are for manipulating data going into the tracker.
A feeder’s primary role is to take detection data from inputs into the framework, and feed them into the tracking algorithms. These can then optionally be used to drop detections, deliver detections out of sequence, synchronise out of sequence detections, etc.
Base classes for Stone Soup feeder
- class stonesoup.feeder.base.Feeder(reader: Reader)[source]¶
Bases:
Reader
Feeder base class
Feeder consumes and outputs
State
data and can be used to modify the sequence, duplicate or drop data.- Parameters:
reader (
Reader
) – Source of detections
- class stonesoup.feeder.base.DetectionFeeder(reader: Reader)[source]¶
Bases:
Feeder
,DetectionReader
Detection feeder base class
Feeder consumes and outputs
Detection
data and can be used to modify the sequence, duplicate or drop data.- Parameters:
reader (
Reader
) – Source of detections
- detections_gen()[source]¶
Returns a generator of detections for each time step.
- Yields:
datetime.datetime
– Datetime of current time stepset of
Detection
– Detections generate in the time step
- class stonesoup.feeder.base.GroundTruthFeeder(reader: Reader)[source]¶
Bases:
Feeder
,GroundTruthReader
Ground truth feeder base class
Feeder consumes and outputs
GroundTruthPath
data and can be used to modify the sequence, duplicate or drop data.- Parameters:
reader (
Reader
) – Source of detections
- groundtruth_paths_gen()[source]¶
Returns a generator of ground truth paths for each time step.
- Yields:
datetime.datetime
– Datetime of current time stepset of
GroundTruthPath
– Ground truth paths existing in the time step
Filter¶
- class stonesoup.feeder.filter.MetadataReducer(reader: Reader, metadata_field: str)[source]¶
Bases:
DetectionFeeder
Reduce detections so unique metadata value present at each time step.
This allows to reduce detections so a single detection is returned, based on a particular metadata value, for example a unique identity. The most recent detection will be yielded for each unique metadata value at each time step.
Note
If
GroundTruthPath
type is extended to have a metadata attribute, this class will be applicable to this type.
- Parameters:
reader (
Reader
) – Source of detectionsmetadata_field (
str
) – Field used to reduce set of detections
- class stonesoup.feeder.filter.MetadataValueFilter(reader: Reader, metadata_field: str, operator: function, keep_unmatched: bool = False)[source]¶
Bases:
MetadataReducer
Reduce detections by filtering out objects based on whether the value of a particular metadata field conforms to a given condition.
The MetadataValueFilter provides an easy way of reducing detections in cases where an informative metadata field exists (e.g. MMSI, SNR, etc.) , that can be used to identify and filter out unwanted detections.
Once provided with a
metadata_field
name and a suitableoperator
function, the feeder will filter the incoming detections by evaluating themetadata_field
field value using the desiredoperator
function. Only detections that satisfy the operator condition (i.e. cause theoperator
to returnTrue
) are allowed through the filter.Note
If
GroundTruthPath
type is extended to have a metadata attribute, this class will be applicable to this type.
- Parameters:
reader (
Reader
) – Source of detectionsmetadata_field (
str
) – Field used to reduce set of detectionsoperator (
function
) – A unary operator/function of the formb = f(val)
, whereval
is the value of the selectedmetadata_field
. The function MUST return abool
type that evaluates toTrue
when a particular object satisfies the condition(s) set by the operator, and thus should be allowed through the filter. Detections that cause the operator to returnFalse
will be filtered out. Any custom function that conforms to the above specifications can be used as an operator, e.g.operator=lambda x: x < 0.1
keep_unmatched (
bool
, optional) – If set toTrue
, any detections that do not have a metadata field matching the namemetadata_field
(meaning they also cannot be processed by theoperator
), will be allowed through the filter. The default isFalse
.
- operator: function¶
A unary operator/function of the form
b = f(val)
, whereval
is the value of the selectedmetadata_field
. The function MUST return abool
type that evaluates toTrue
when a particular object satisfies the condition(s) set by the operator, and thus should be allowed through the filter. Detections that cause the operator to returnFalse
will be filtered out. Any custom function that conforms to the above specifications can be used as an operator, e.g.operator=lambda x: x < 0.1
- class stonesoup.feeder.filter.BoundingBoxReducer(reader: Reader, limits: Sequence[Tuple[float, float]], mapping: Sequence[int] = None)[source]¶
Bases:
DetectionFeeder
,GroundTruthFeeder
Reduce data by selecting only data placed within the limits of a n-dimensional bounding box, defined on the data coordinate space.
When provided with the limit coordinates of a given n-dimensional bounding box (expressed in the form of min/max bounds on each dimension), the feeder will apply a filter to the incoming data, allowing to pass through only data that falls within the desired limits, and discarding the rest.
Assuming a 2D Cartesian data space, the feeder operation is equivalent to drawing an imaginary bounding box tangential to the plane defined by the XY axes, and only feeding data whose state vector falls within the bounds of the box.
Note
For the time being, the bounding box limits must be defined on the same coordinate axes as the received data, which is in turn assumed to all share a common coordinate frame.
For example, assume we are tracking some targets in Lat/Lon, but receive detections in the form of polar coordinates (e.g. relative to a single Radar sensor), then the bounding box MUST be defined on (a subset of) the polar coordinate system, and NOT the geo-spatial.
Thus, it is worth noting that in its current version the feeder is not recommended for use in filtering data coming from multiple sources/sensors, unless a common coordinate frame is guaranteed.
Finally, for simplicity purposes, the bounding box is not allowed to rotate around any axis.
- Parameters:
reader (
Reader
) – Source of detectionslimits (
Sequence[Tuple[float, float]]
) – Array of points that define the bounds of the desired bounding box. Expressed as a 2D array of min/max coordinate pairs (e.g.limits = [[x_min, x_max], [y_min, y_max], ...]
), where the n-th row corresponds to the n-th bounding box dimension limits. Points that fall ON or WITHIN the box’s bounds are considered as valid and are thus forwarded through the feeder, whereas points that fall OUTSIDE the box will be filtered out.mapping (
Sequence[int]
, optional) – Mapping between the state and bounding box coordinates. Should be specified as a vector of length equal to the number of bounding box dimensions, whose elements correspond to row indices in the state vector. E.g.mapping = [2, 0]
dictates that the first bounding box dimension (i.e. row 0 inlimits
), defines the limits that correspond to the element with (row) index 2 in the data state vector, while the second row (i.e. row 1) inlimits
relates to the element with index 0. Default is None, where the dimensions of the state vector will be used in order, up to length to limits.
- limits: Sequence[Tuple[float, float]]¶
Array of points that define the bounds of the desired bounding box. Expressed as a 2D array of min/max coordinate pairs (e.g.
limits = [[x_min, x_max], [y_min, y_max], ...]
), where the n-th row corresponds to the n-th bounding box dimension limits. Points that fall ON or WITHIN the box’s bounds are considered as valid and are thus forwarded through the feeder, whereas points that fall OUTSIDE the box will be filtered out.
- mapping: Sequence[int]¶
Mapping between the state and bounding box coordinates. Should be specified as a vector of length equal to the number of bounding box dimensions, whose elements correspond to row indices in the state vector. E.g.
mapping = [2, 0]
dictates that the first bounding box dimension (i.e. row 0 inlimits
), defines the limits that correspond to the element with (row) index 2 in the data state vector, while the second row (i.e. row 1) inlimits
relates to the element with index 0. Default is None, where the dimensions of the state vector will be used in order, up to length to limits.
Geo¶
- class stonesoup.feeder.geo.LLAtoENUConverter(reader: Reader, reference_point: Tuple[float, float, float], mapping: Tuple[int, int, int] = (0, 1, 2))[source]¶
Bases:
_LLARefConverter
Converts Long., Lat., Alt. to East, North, Up coordinate space.
This replaces Longitude (°), Latitude (°) and Altitude (m) of a
State
with East (m), North (m) and Up (m) coordinate space from a definedreference_point
.- Parameters:
reader (
Reader
) – Source of detectionsreference_point (
Tuple[float, float, float]
) – (Long, Lat, Altitude)mapping (
Tuple[int, int, int]
, optional) – Indexes of long, lat, altitude. Default (0, 1, 2)
- class stonesoup.feeder.geo.LLAtoNEDConverter(reader: Reader, reference_point: Tuple[float, float, float], mapping: Tuple[int, int, int] = (0, 1, 2))[source]¶
Bases:
_LLARefConverter
Converts Long., Lat., Alt. to North, East, Down coordinate space.
This replaces Longitude (°), Latitude (°) and Altitude (m) of a
State
with North (m), East (m) and Down (m) coordinate space from a definedreference_point
.- Parameters:
reader (
Reader
) – Source of detectionsreference_point (
Tuple[float, float, float]
) – (Long, Lat, Altitude)mapping (
Tuple[int, int, int]
, optional) – Indexes of long, lat, altitude. Default (0, 1, 2)
- class stonesoup.feeder.geo.LongLatToUTMConverter(reader: Reader, mapping: Tuple[int, int] = (0, 1), zone_number: int = None, northern: bool = None)[source]¶
Bases:
DetectionFeeder
,GroundTruthFeeder
Converts long. and lat. to UTM easting and northing.
This replaces Longitude (°), Latitude (°) of a
State
with East (m), North (m) coordinate space in a Universal Transverse Mercator zone.Note
Whilst this allows for data to be converted even if it is outside of the set zone, the errors will increase the further the position is from the zone being used.
- Parameters:
reader (
Reader
) – Source of detectionsmapping (
Tuple[int, int]
, optional) – Indexes of long, lat. Default (0, 1)zone_number (
int
, optional) – UTM zone number to carry out conversion. Default None, where it will select the zone based on the first yielded data.northern (
bool
, optional) – UTM northern for northern or southern grid. Default None, where it will be based on the first yielded data.
Multi¶
- class stonesoup.feeder.multi.MultiDataFeeder(readers: Collection[Reader])[source]¶
Bases:
DetectionFeeder
,GroundTruthFeeder
Multi-data Feeder
This returns states from multiple data readers as a single stream, yielding from the reader yielding the lowest timestamp first.
- Parameters:
readers (
Collection[Reader]
) – Readers to yield from
- readers: Collection[Reader]¶
Readers to yield from
Time Based¶
- class stonesoup.feeder.time.TimeBufferedFeeder(reader: Reader, buffer_size: int = 1000)[source]¶
Bases:
DetectionFeeder
,GroundTruthFeeder
Buffer data so it can be yielded in time order.
Any “old” data (where the time is earlier than the head of the buffer) shall be dropped, producing a
UserWarning
.- Parameters:
reader (
Reader
) – Source of detectionsbuffer_size (
int
, optional) – Max size of buffer
- class stonesoup.feeder.time.TimeSyncFeeder(reader: Reader, time_window: timedelta = datetime.timedelta(seconds=1))[source]¶
Bases:
DetectionFeeder
,GroundTruthFeeder
Synchronise the data into selected time window.
Assumes that states from
Reader
are in time order. TheTimeBufferedFeeder
can be used in conjunction to ensure this is the case.- Parameters:
reader (
Reader
) – Source of detectionstime_window (
datetime.timedelta
, optional) – Time window to group detections
Image¶
- class stonesoup.feeder.image.CFAR(reader: Reader, train_size: int = 10, guard_size: int = 4, alpha: float = 1.0, squared: bool = False)[source]¶
Bases:
Feeder
Cell-averaging (CA) Constant False Alarm Rate (CFAR) image data feeder
The CFAR feeder reads grayscale frames from an appropriate
Feeder
and outputs binary frames whose pixel values are either 0 or 255, indicating the lack or presence of a detection, respectively.See here for more information on CA-CFAR.
Note
The frames forwarded by the
reader
must be grayscaleImageFrame
objects. As suchpixels
for all frames must be 2-D arrays, containing grayscale intensity values.- Parameters:
reader (
Reader
) – Source of detectionstrain_size (
int
, optional) – The number of train pixelsguard_size (
int
, optional) – The number of guard pixelsalpha (
float
, optional) – The threshold valuesquared (
bool
, optional) – If set to True, the threshold will be computed as a function of the sum of squares. The default is False, in which case a simple sum will be evaluated.
- squared: bool¶
If set to True, the threshold will be computed as a function of the sum of squares. The default is False, in which case a simple sum will be evaluated.
- static cfar(input_img, train_size=10, guard_size=4, alpha=1.0, squared=False)[source]¶
Perform Constant False Alarm Rate (CFAR) detection on an input image
- Parameters:
input_img (numpy.ndarray) – The input grayscale image.
train_size (int) – The number of train pixels.
guard_size (int) – The number of guard pixels.
alpha (float) – The threshold value.
squared (bool) – If set to True, the threshold will be computed as a function of the sum of squares. The default is False, in which case a simple sum will be evaluated.
- Returns:
Output image containing 255 for pixels where a target is detected and 0 otherwise.
- Return type:
- class stonesoup.feeder.image.CCL(reader: Reader)[source]¶
Bases:
Feeder
Connected Component Labelling (CCL) image data feeder
The CCL feeder reads binary frames from an appropriate
Feeder
and outputs labelled frames whose pixel values contain the label of the connected component to which each pixel is has been assigned.See here for more information on and example applications of CCL.
Note
The frames forwarded by the
reader
must be binaryImageFrame
objects. As suchpixels
for all frames must be 2-D arrays, where each element can take only 1 of 2 possible values (e.g. [0 or 1], [0 or 255], etc.).- Parameters:
reader (
Reader
) – Source of detections
Track¶
- class stonesoup.feeder.track.Tracks2GaussianDetectionFeeder(reader: Reader)[source]¶
Bases:
DetectionFeeder
Feeder consumes Track objects and outputs GaussianDetection objects.
At each time step, the
Reader
feeds in a set of live tracks. The feeder takes the most recent state from each of those tracks, and turn them into a set ofGaussianDetection
objects. Each detection is given aLinearGaussian
measurement model whose covariance is equal to the state covariance. The feeder assumes that the tracks are all live, that is each track has a state at the most recent time step.- Parameters:
reader (
Reader
) – Source of detections