Readers
Reader classes are used for getting data into the framework.
Base classes for different Readers.
- class stonesoup.reader.base.Reader[source]
Bases:
stonesoup.base.Base
,stonesoup.buffered_generator.BufferedGenerator
Reader base class
- class stonesoup.reader.base.DetectionReader[source]
Bases:
stonesoup.reader.base.Reader
Detection Reader base class
- abstract 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.reader.base.GroundTruthReader[source]
Bases:
stonesoup.reader.base.Reader
Ground Truth Reader base class
- abstract 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
- class stonesoup.reader.base.SensorDataReader[source]
Bases:
stonesoup.reader.base.Reader
Sensor Data Reader base class
- abstract sensor_data_gen()[source]
Returns a generator of sensor data for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
SensorData
– Sensor data generated in the time step
- class stonesoup.reader.base.FrameReader[source]
Bases:
stonesoup.reader.base.SensorDataReader
FrameReader base class
A FrameReader produces
SensorData
in the form ofImageFrame
objects.- abstract frames_gen()[source]
Returns a generator of frames for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
ImageFrame
– Generated frame in the time step
- sensor_data_gen()[source]
Returns a generator of frames for each time step.
Note
This is just a wrapper around (and therefore performs identically to)
frames_gen()
.- Yields
datetime.datetime
– Datetime of current time stepset of
ImageFrame
– Generated frame in the time step
Base classes for use with File based readers.
- class stonesoup.reader.file.FileReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.base.Reader
Base class for file based readers.
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.
- path: pathlib.Path
Path to file to be opened. Str will be converted to path.
- class stonesoup.reader.file.BinaryFileReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.file.FileReader
Base class for binary file readers.
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.
- class stonesoup.reader.file.TextFileReader(path: pathlib.Path, encoding: str = 'utf-8')[source]
Bases:
stonesoup.reader.file.FileReader
Base class for text file readers.
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.encoding (
str
, optional) – File encoding. Must be valid coding. Default ‘utf-8’.
Generic
Generic readers for Stone Soup.
This is a collection of generic readers for Stone Soup, allowing quick reading of data that is in common formats.
- class stonesoup.reader.generic.CSVGroundTruthReader(path: pathlib.Path, state_vector_fields: Sequence[str], time_field: str, path_id_field: str, encoding: str = 'utf-8', time_field_format: str = None, timestamp: bool = False, metadata_fields: Collection[str] = None, csv_options: Mapping = {})[source]
Bases:
stonesoup.reader.base.GroundTruthReader
,stonesoup.reader.generic._CSVReader
A simple reader for csv files of truth data.
CSV file must have headers, as these are used to determine which fields to use to generate the ground truth state. Those states with the same ID will be put into a
GroundTruthPath
in sequence, and all paths that are updated at the same time are yielded together, and such assumes file is in time order.- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.state_vector_fields (
Sequence[str]
) – List of columns names to be used in state vectortime_field (
str
) – Name of column to be used as time fieldpath_id_field (
str
) – Name of column to be used as path IDencoding (
str
, optional) – File encoding. Must be valid coding. Default ‘utf-8’.time_field_format (
str
, optional) – Optional datetime formattimestamp (
bool
, optional) – Treat time field as a timestamp from epochmetadata_fields (
Collection[str]
, optional) – List of columns to be saved as metadata, default allcsv_options (
Mapping
, optional) – Keyword arguments for the underlying csv reader
- 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
- class stonesoup.reader.generic.CSVDetectionReader(path: pathlib.Path, state_vector_fields: Sequence[str], time_field: str, encoding: str = 'utf-8', time_field_format: str = None, timestamp: bool = False, metadata_fields: Collection[str] = None, csv_options: Mapping = {})[source]
Bases:
stonesoup.reader.base.DetectionReader
,stonesoup.reader.generic._CSVReader
A simple detection reader for csv files of detections.
CSV file must have headers, as these are used to determine which fields to use to generate the detection. Detections at the same time are yielded together, and such assume file is in time order.
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.state_vector_fields (
Sequence[str]
) – List of columns names to be used in state vectortime_field (
str
) – Name of column to be used as time fieldencoding (
str
, optional) – File encoding. Must be valid coding. Default ‘utf-8’.time_field_format (
str
, optional) – Optional datetime formattimestamp (
bool
, optional) – Treat time field as a timestamp from epochmetadata_fields (
Collection[str]
, optional) – List of columns to be saved as metadata, default allcsv_options (
Mapping
, optional) – Keyword arguments for the underlying csv reader
- 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
YAML
- class stonesoup.reader.yaml.YAMLReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.file.FileReader
,stonesoup.buffered_generator.BufferedGenerator
YAML Reader
- Parameters
path (
pathlib.Path
) – File to read data from
- path: pathlib.Path
File to read data from
- class stonesoup.reader.yaml.YAMLDetectionReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.yaml.YAMLReader
,stonesoup.reader.base.DetectionReader
YAML Detection Reader
- Parameters
path (
pathlib.Path
) – File to read data from
- 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.reader.yaml.YAMLGroundTruthReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.yaml.YAMLReader
,stonesoup.reader.base.GroundTruthReader
YAML Ground Truth Reader
- Parameters
path (
pathlib.Path
) – File to read data from
- 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
- class stonesoup.reader.yaml.YAMLSensorDataReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.yaml.YAMLReader
,stonesoup.reader.base.SensorDataReader
YAML Sensor Data Reader
- Parameters
path (
pathlib.Path
) – File to read data from
- sensor_data_gen()[source]
Returns a generator of sensor data for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
SensorData
– Sensor data generated in the time step
- class stonesoup.reader.yaml.YAMLTrackReader(path: pathlib.Path)[source]
Bases:
stonesoup.reader.yaml.YAMLReader
,stonesoup.tracker.base.Tracker
YAML Track Reader
- Parameters
path (
pathlib.Path
) – File to read data from
- tracks_gen()[source]
Returns a generator of tracks for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
Track
– Tracks existing in the time step
AISHub
- class stonesoup.reader.aishub.JSON_AISDetectionReader(path: pathlib.Path, encoding: str = 'utf-8')[source]
Bases:
stonesoup.reader.base.DetectionReader
,stonesoup.reader.file.TextFileReader
A simple detection reader for JSON files of AIS (maritime transponder) detections.
This particular JSON AIS reader is written to read the JSON format used by files downloaded from ‘www.aishub.net’ (must be a contributor to their AIS database to download their files).
JSON format:
[{"ERROR": "false"}, [{"NAME": "MARTCILINO", "MMSI": 205466990, "LONGITUDE": 3078401, "TIME": "1516233686", "LATITUDE": 31215032, ...}, {"NAME": "MARTCILINO", "MMSI": 205466990, "LONGITUDE": 3064592, "TIME": "1516234275", "LATITUDE": 31227463, ...}]]
Notes
TIME is in Linux Epoch format
LONGITUDE and LATITUDE are (long/lat degrees)*(600,000)
MMSI is unique ship identifier
The AIS detection attributes for lattitude, longitude, and timestamp are saved as the attributes of a ‘Detection’; the other attributes are saved as the dictionary ‘metadata’ attribute of a ‘Detection’.
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.encoding (
str
, optional) – File encoding. Must be valid coding. Default ‘utf-8’.
- 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
Video
Video readers for Stone Soup.
This is a collection of video readers for Stone Soup, allowing quick reading of video data/streams.
- class stonesoup.reader.video.VideoClipReader(path: pathlib.Path, start_time: datetime.timedelta = datetime.timedelta(0), end_time: datetime.timedelta = None, timestamp: datetime.datetime = None)[source]
Bases:
stonesoup.reader.file.FileReader
,stonesoup.reader.base.FrameReader
A simple reader that uses MoviePy to read video frames from a file.
Usage of MoviePy allows for the application of clip transformations and effects, as per the MoviePy documentation. Upon instantiation, the underlying MoviePy VideoFileClip instance can be accessed through the
clip
class property. This can then be used as expected, e.g.:# Rearrange RGB to BGR def arrange_bgr(image): return image[:, :, [2, 1, 0]] reader = VideoClipReader("path_to_file") reader.clip = reader.clip.fl_image(arrange_bgr) for timestamp, frame in reader: # The generated frame.pixels will now # be arranged in BGR format. ...
- Parameters
path (
pathlib.Path
) – Path to file to be opened. Str will be converted to path.start_time (
datetime.timedelta
, optional) – Start time expressed as duration from the start of the clipend_time (
datetime.timedelta
, optional) – End time expressed as duration from the start of the cliptimestamp (
datetime.datetime
, optional) – Timestamp given to the first frame
- start_time: datetime.timedelta
Start time expressed as duration from the start of the clip
- end_time: datetime.timedelta
End time expressed as duration from the start of the clip
- timestamp: datetime.datetime
Timestamp given to the first frame
- frames_gen()[source]
Returns a generator of frames for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
ImageFrame
– Generated frame in the time step
- class stonesoup.reader.video.FFmpegVideoStreamReader(url: urllib.parse.ParseResult, buffer_size: int = 1, input_opts: Mapping[str, str] = None, output_opts: Mapping[str, str] = None, filters: Sequence[Tuple[str, Sequence[Any], Mapping[Any, Any]]] = None, frame_size: Tuple[int, int] = None)[source]
Bases:
stonesoup.reader.url.UrlReader
,stonesoup.reader.base.FrameReader
A threaded reader that uses ffmpeg-python to read frames from video streams (e.g. RTSP) in real-time.
Notes
Use of this class requires that FFmpeg is installed on the host machine.
By default, FFmpeg performs internal buffering of frames leading to a slight delay in the incoming frames (0.5-1 sec). To remove the delay it is recommended to set
input_opts={'threads': 1, 'fflags': 'nobuffer'}
when instantiating a reader, e.g: .
video_reader = FFmpegVideoStreamReader('rtsp://192.168.0.10:554/1/h264minor', input_opts={'threads': 1, 'fflags': 'nobuffer'}) for timestamp, frame in video_reader: ....
- Parameters
url (
urllib.parse.ParseResult
) – Input source to read video stream from, passed as input url argument. This can include any valid FFmpeg input e.g. rtsp URL, device name when using ‘dshow’/’v4l2’buffer_size (
int
, optional) – Size of the frame buffer. The frame buffer is used to cache frames in cases where the stream generates frames faster than they are ingested by the reader. If buffer_size is less than or equal to zero, the buffer size is infinite.input_opts (
Mapping[str, str]
, optional) – FFmpeg input options, provided in the form of a dictionary, whose keys correspond to option names. (e.g.{'fflags': 'nobuffer'}
). The default is{}
.output_opts (
Mapping[str, str]
, optional) – FFmpeg output options, provided in the form of a dictionary, whose keys correspond to option names. The default is{'f': 'rawvideo', 'pix_fmt': 'rgb24'}
.filters (
Sequence[Tuple[str, Sequence[Any], Mapping[Any, Any]]]
, optional) – FFmpeg filters, provided in the form of a list of filter name, sequence of arguments, mapping of key/value pairs (e.g.[('scale', ('320', '240'), {})]
). Default None where no filter will be applied. Note thatframe_size
may need to be set in when video size changed by filter.frame_size (
Tuple[int, int]
, optional) – Tuple of frame width and height. Default None where it will be detected using ffprobe against the input, but this may yield wrong width/height (e.g. when filters are applied), and such this option can be used to override.
- url: urllib.parse.ParseResult
Input source to read video stream from, passed as input url argument. This can include any valid FFmpeg input e.g. rtsp URL, device name when using ‘dshow’/’v4l2’
- buffer_size: int
Size of the frame buffer. The frame buffer is used to cache frames in cases where the stream generates frames faster than they are ingested by the reader. If buffer_size is less than or equal to zero, the buffer size is infinite.
- frame_size: Tuple[int, int]
Tuple of frame width and height. Default None where it will be detected using ffprobe against the input, but this may yield wrong width/height (e.g. when filters are applied), and such this option can be used to override.
- input_opts: Mapping[str, str]
FFmpeg input options, provided in the form of a dictionary, whose keys correspond to option names. (e.g.
{'fflags': 'nobuffer'}
). The default is{}
.
- output_opts: Mapping[str, str]
FFmpeg output options, provided in the form of a dictionary, whose keys correspond to option names. The default is
{'f': 'rawvideo', 'pix_fmt': 'rgb24'}
.
- filters: Sequence[Tuple[str, Sequence[Any], Mapping[Any, Any]]]
FFmpeg filters, provided in the form of a list of filter name, sequence of arguments, mapping of key/value pairs (e.g.
[('scale', ('320', '240'), {})]
). Default None where no filter will be applied. Note thatframe_size
may need to be set in when video size changed by filter.
- frames_gen()[source]
Returns a generator of frames for each time step.
- Yields
datetime.datetime
– Datetime of current time stepset of
ImageFrame
– Generated frame in the time step
OpenSky Network
- class stonesoup.reader.opensky.OpenSkyNetworkDetectionReader(bbox: Tuple[float, float, float, float] = None, timestep: datetime.timedelta = datetime.timedelta(seconds=15))[source]
Bases:
stonesoup.reader.opensky._OpenSkyNetworkReader
,stonesoup.reader.base.DetectionReader
OpenSky Network detection reader
This reader uses the OpenSky Network REST API to fetch air traffic control data.
The detection state vector consists of longitude, latitude (in decimal degrees) and altitude (in meters).
Note
By using this reader, you are agreeing to OpenSky Network’s terms of use.
- Parameters
bbox (
Tuple[float, float, float, float]
, optional) – Bounding box to filter data to (left, bottom, right, top). Default None which will include global data.timestep (
datetime.timedelta
, optional) – Time of each poll after reported time from OpenSky. Must be greater than 10 seconds. Default 15 seconds.
- 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.reader.opensky.OpenSkyNetworkGroundTruthReader(bbox: Tuple[float, float, float, float] = None, timestep: datetime.timedelta = datetime.timedelta(seconds=15))[source]
Bases:
stonesoup.reader.opensky._OpenSkyNetworkReader
,stonesoup.reader.base.GroundTruthReader
OpenSky Network groundtruth reader
This reader uses the OpenSky Network REST API to fetch air traffic control data.
The groundtruth state vector consists of longitude, latitude (in decimal degrees) and altitude (in meters).
Paths that are yielded are grouped based on the International Civil Aviation Organisation (ICAO) 24-bit address.
Note
By using this reader, you are agreeing to OpenSky Network’s terms of use.
- Parameters
bbox (
Tuple[float, float, float, float]
, optional) – Bounding box to filter data to (left, bottom, right, top). Default None which will include global data.timestep (
datetime.timedelta
, optional) – Time of each poll after reported time from OpenSky. Must be greater than 10 seconds. Default 15 seconds.
- 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