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

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 step
set 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 step
set 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 detections
metadata_field (str) – Field used to reduce set of detections

metadata_field: str: Field used to reduce set of detections

class stonesoup.feeder.filter.MetadataValueFilter(reader: Reader, metadata_field: str, operator: LambdaType, 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 suitable operator function, the feeder will filter the incoming detections by evaluating the metadata_field field value using the desired operator function. Only detections that satisfy the operator condition (i.e. cause the operator to return True) 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 detections
metadata_field (str) – Field used to reduce set of detections
operator (function) – A unary operator/function of the form b = f(val), where val is the value of the selected metadata_field. The function MUST return a bool type that evaluates to True 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 return False 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 to True, any detections that do not have a metadata field matching the name metadata_field (meaning they also cannot be processed by the operator), will be allowed through the filter. The default is False.

operator: LambdaType: A unary operator/function of the form b = f(val), where val is the value of the selected metadata_field. The function MUST return a bool type that evaluates to True 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 return False 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: If set to True, any detections that do not have a metadata field matching the name metadata_field (meaning they also cannot be processed by the operator), will be allowed through the filter. The default is False.

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 detections
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], 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 in limits), 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) in limits 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 in limits), 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) in limits 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 defined reference_point.

Parameters:

reader (Reader) – Source of detections
reference_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 defined reference_point.

Parameters:

reader (Reader) – Source of detections
reference_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 detections
mapping (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.

mapping: Tuple[int, int]: Indexes of long, lat. Default (0, 1)

zone_number: int: UTM zone number to carry out conversion. Default None, where it will select the zone based on the first yielded data.

northern: bool: 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

reader: Reader = None

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 detections
buffer_size (int, optional) – Max size of buffer

buffer_size: int: 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. The TimeBufferedFeeder can be used in conjunction to ensure this is the case.

Parameters:

reader (Reader) – Source of detections
time_window (datetime.timedelta, optional) – Time window to group detections

time_window: timedelta: 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 grayscale ImageFrame objects. As such pixels for all frames must be 2-D arrays, containing grayscale intensity values.

Parameters:

reader (Reader) – Source of detections
train_size (int, optional) – The number of train pixels
guard_size (int, optional) – The number of guard pixels
alpha (float, optional) – The threshold value
squared (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.

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.

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:

numpy.ndarray

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 binary ImageFrame objects. As such pixels 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 of GaussianDetection objects. Each detection is given a LinearGaussian 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