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
-
abstract
-
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
-
abstract
-
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
-
abstract
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.
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
-
abstract
-
class
stonesoup.reader.video.
VideoClipReader
(path: pathlib.Path, start_time: datetime.timedelta = datetime.timedelta(0), end_time: datetime.timedelta = None)[source]¶ Bases:
stonesoup.reader.file.FileReader
,stonesoup.reader.video.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 clip
-
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
-
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.video.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