DynAIkonTrap.comms#

An interface for writing animal frames to disk or sending them to a server. The AbstractOutput combines a frame(s) with the most appropriate sensor log(s) and outputs these.

Functions

Output(settings, read_from)

Generator function to provide an implementation of the AbstractOutput based on the OutputMode of the settings argument.

Output(settings: OutputSettings, read_from: Tuple[Filter, SensorLogs]) → Union[Sender, Writer]#: Generator function to provide an implementation of the AbstractOutput based on the OutputMode of the settings argument. If the output mode is SEND, this function performs some error checking/handling before configuring a Sender instance

Classes

`AbstractOutput`(settings, read_from)	A base class to use for outputting captured images or videos.
`Sender`(settings, read_from)	The Sender is a simple interface for sending the desired data to a server.
`SenderLog`(settings)	A class to keep a log about detections sent to remote servers, useful to record observation IDs from FASTCAT-Cloud
`VideoCaption`(sensor_logs, framerate)	Class to aid in generating captions for video output.
`Writer`(settings, read_from)

class AbstractOutput(settings: OutputSettings, read_from: Tuple[Filter, SensorLogs])#

A base class to use for outputting captured images or videos. The output_still() and output_video() functions should be overridden with output method-specific implementations.

close()#

abstract output_group_of_stills(images: List[str], time: float, sensor_log: SensorLog)#

Output a group of still images all correlated with one-and-other, eg in an event. The sensor data can be provided via the keyword arguments.

Parameters:

images (List[bytes]) – A list of images saved on disk
time (float) – UNIX time stamp when the images were captured
sensor_log (SensorLog) – Log of sensor values at the time the frames were captured

abstract output_still(image: bytes, time: float, sensor_log: SensorLog)#

Output a still image with its sensor data. The sensor data can be provided via the keyword arguments.

Parameters:

image (bytes) – The image
time (float) – UNIX timestamp when the image was captured
sensor_log (SensorLog) – Log of sensor values at time frame was captured

abstract output_video(video: IO[bytes], time: float, caption: Optional[StringIO] = None, **kwargs)#

Output a video with its meta-data. The sensor data is provided via the video captions (caption).

Parameters:

video (IO[bytes]) – MP4 video
caption (StringIO) – Caption of sensor readings as produced by VideoCaption.generate_sensor_json()
time (float) – UNIX timestamp when the image was captured

class Sender(settings: SenderSettings, read_from: Tuple[Filter, SensorLogs])#

The Sender is a simple interface for sending the desired data to a server. Inherits from Writer, if server posts fail, Writer methods are called instead to save data on disk.

check_health() → bool#

Checks health of the server to send to

Returns:: returns True if connection deemed healthy, False otherwise
Return type:: bool

output_group_of_stills(images: List[str], time: float, sensor_log: Optional[SensorLog] = None)#

A function to output a group of correlated still images under one directory. E.G. Frames in a video. Takes a list of paths to correlated frames and a time. A directory is constructed from the time given, images within the directory are saved in list-order in the form dir_name/cap0.jpg, dir_name/cap1.jpg … If a sensor log is given, this is saved within the directory in json format with a filename constructed from the given timestamp. The directory name where everything is saved is returned in string format.

Parameters:

images (List[str]) – List of correlated images to save in common detection directory
time (float) – Time stamp to associate with this detection
sensor_log (SensorLog) – The sensor log associated with this detection, can be None

Returns:

Directory name containing sensor log and/or saved images, given as a string

Return type:

str

output_still(image: bytes, time: float, sensor_log: Optional[SensorLog] = None)#

Output a still image with its sensor data. The sensor data can be provided via the keyword arguments.

Parameters:

image (bytes) – The image
time (float) – UNIX timestamp when the image was captured
sensor_log (SensorLog) – Log of sensor values at time frame was captured

output_video(video: IO[bytes], time: float, caption: Optional[StringIO] = None, **kwargs) → Dict#

A function post a video clip to the sender’s url. The video caption and timestamp are included in the post data. If a problem arises with the connection, the video will be saved to disk instead using the inherited Writer

Parameters:

video (IO[bytes]) – The video file to post to server
time (float) – The time stamp associated with the video capture
caption (StringIO, optional) – The optional video caption. Defaults to None.

Returns:

If the post attempt was sucessful, returns an empty string. Otherwise, returns the string output of output_video()

Return type:

str

class SenderLog(settings: SenderSettings)#

A class to keep a log about detections sent to remote servers, useful to record observation IDs from FASTCAT-Cloud

log(result: Dict)#

Logs a sender result to the log file

Parameters:: result (str) – sender result from accessing server or saving to disk

class VideoCaption(sensor_logs: SensorLogs, framerate: float)#

Class to aid in generating captions for video output. The captions are based on the logged sensor readings.

Parameters:

sensor_logs (SensorLogs) – The object containing the log of sensor readings
framerate (float) – Camera framerate

generate_sensor_json(timestamps: List[float]) → StringIO#

Generate JSON captions containing the sensor readings at given moments in time.

The format is as follows:

[
    {
        "start": 0,
        "end": 1,
        "log": {
            "EXAMPLE_SENSOR_1": {
                "value": 0.0,
                "units": "x"
            },
            "EXAMPLE_SENSOR_2": {
                "value": 0.0,
                "units": "x"
            }
        }
    },
    {
        "start": 1,
        "end": 5,
        "logs": {}
    }
]

The "start" and "end" correspond to the frame numbers in which the sensor logs are valid. The frame numbers are inclusive. It is not guaranteed that all frames are covered by logs. There may also be also be overlaps between entries if the exact timestamp where a new set of sensor readings becomes valid occurs during a frame.

Parameters:: timestamps (List[float]) – Timestamps for every frame in the motion/animal sequence
Returns:: The JSON captions wrapped in a StringIO, ready for writing to file
Return type:: StringIO

generate_vtt_for(timestamps: List[float]) → StringIO#

Generate WebVTT captions containing the sensor readings at given moments in time.

Parameters:: timestamps (List[float]) – Timestamps for every frame in the motion/animal sequence
Returns:: The WebVTT captions ready to be sent to a server
Return type:: StringIO

class Writer(settings: OutputSettings, read_from: Tuple[Filter, SensorLogs])#

output_group_of_stills(images: List[str], time: float, sensor_log: Optional[SensorLog] = None) → str#

Parameters:

images (List[str]) – List of correlated images to save in common detection directory
time (float) – Time stamp to associate with this detection
sensor_log (SensorLog) – The sensor log associated with this detection, can be None

Returns:

Directory name containing sensor log and/or saved images, given as a string

Return type:

str

output_still(image: bytes, time: float, sensor_log: Optional[SensorLog] = None)#

Output a still image with its sensor data. The sensor data can be provided via the keyword arguments.

Parameters:

image (bytes) – The image
time (float) – UNIX timestamp when the image was captured
sensor_log (SensorLog) – Log of sensor values at time frame was captured

output_video(video: IO[bytes], time: float, caption: Optional[StringIO] = None, **kwargs) → str#

Takes a video file bytestream and saves to disk alongside an optional caption file with the same name with a .json extension. These names are set with a timestamp.

Parameters:

video (IO[bytes]) – The video file to be saved
time (float) – The time corresponding to this video
caption – The caption to be saved, can be None to save no caption file