DynAIkonTrap.filtering.motion_queue#

This module provides access to a “motion queue”, which is simply a queue for sequences of consecutive motion. The intended usage is to place frames of motion, as determined by a motion filter, into the queue. When a frame of no motion arrives, this is not added to the queue and the motion sequence is ended.

The sequence is then analysed by the animal filter, loaded into the MotionQueue, and a callback called with only the animal frames from the motion sequence. Within a MotionSequence there is some simplistic “smoothing” of animal detections. This means even animal detectors that provide sporadic outputs in time, are transformed to a smooth system output.

Below is a simple outline example of how this can be used to print all animal frames:

camera = Camera()

mf = MotionFilter(...)

mq = MotionQueue(
    AnimalFilter(...),
    print,
    MotionQueueSettings(),
    camera.framerate,
    )

while True:

    frame = camera.get() # Can raise Empty exception

    motion_score = mf.run_raw(frame.motion)
    motion_detected = motion_score >= motion_threshold

    if motion_detected:
        mq.put(frame, motion_score)
    else:
        # Safe to call repeatedly; will only end non-empty motion    sequence
        mq.end_motion_sequence()

The modularity here means Different implementations for animal filtering and motion filtering stages can be used.

Classes

`Label`(value)	Categories into which a frame can fall
`LabelledFrame`(frame, index, priority[, label])	A frame of motion and image data accompanied by some additional labels for the motion queue
`MotionQueue`(settings, animal_detector, framerate)	A queue for sequences of motion to be analysed by the animal filter
`MotionSequence`(smoothing_len)	Sequence of consecutive frames with motion deemed sufficient by a previous motion filtering stage.

class Label(value)#

Categories into which a frame can fall

ANIMAL = 1#

EMPTY = 0#

UNKNOWN = 2#

class LabelledFrame(frame: Frame, index: int, priority: float, label: Label = Label.UNKNOWN)#

A frame of motion and image data accompanied by some additional labels for the motion queue

frame: Frame#

index: int#

label: Label = 2#

priority: float#

class MotionQueue(settings: MotionQueueSettings, animal_detector: AnimalFilter, framerate: int)#

A queue for sequences of motion to be analysed by the animal filter

Parameters

settings (MotionQueueSettings) – Settings for the queue
animal_detector (AnimalFilter) – An initialised animal filter to apply to frames in the motion sequences
output_callback (Callable[[List[Frame]], Any]) – Function to call with filtered frames
framerate (int) – Framerate at which the frames were recorded

close()#

end_motion_sequence()#: End the current motion sequence and prepare the next one. To be called when there is a gap in motion. It is safe to call this repeatedly for consecutive empty frames. Calling this releases the motion sequence to be processed by the animal filter.

get() → Frame#

Retrieve the next animal Frame from the motion queue’s output

Returns: An animal frame
Return type: Frame

is_idle() → bool#: Allows checking if the motion queue is currently waiting for new frames to arrive. May be removed in future.

put(frame: Frame, motion_score: float)#

Append the given frame to the current motion sequence. If the sequence exceeds the length limit, a new one is automatically started. This prevents excessively long motion sequences.

Parameters

frame (Frame) – A frame of motion and image data to be analysed
motion_score (float) – Output value for this frame from the motion filtering stage

class MotionSequence(smoothing_len: int)#

Sequence of consecutive frames with motion deemed sufficient by a previous motion filtering stage. Smoothing is built in to smooth any animal detections over multiple frames. This can be done as the minimum number of frames in which an animal is likely to be present, can be reasoned about.

Parameters: smoothing_len (int) – Number of frames by which to smooth animal detections in either direction

close_gaps()#: Remove small gaps of missing animal predictions in the current motion sequence. This should only be called just before the motion sequence is passed out of the motion queue. This function removes unlikely gaps in animal detections using the smoothing_len.

get_animal_frames() → List[LabelledFrame]#

Retrieve only the animal frames from the motion sequence

Returns: List of animal frames from this motion sequence
Return type: List[LabelledFrame]

get_highest_priority() → LabelledFrame#

Finds the frame with the highest priority in the motion sequence. This should be the next frame to be passed to the animal filtering stage.

Returns: Frame to be analysed by the animal filtering stage
Return type: LabelledFrame

label_as_animal(frame: LabelledFrame)#

Label a given frame as containing an animal. Intended to be called based on the output of the animal filter. Frames either side of this one in the current motion sequence will also be labelled as animal according to the smoothing_len

Parameters: frame (LabelledFrame) – The frame to be labelled as containing an animal

label_as_empty(frame: LabelledFrame)#

Label the given frame as empty. Intended to be called based on the output of the animal filter. Only this frame is labelled as empty; no smoothing is applied.

Parameters: frame (LabelledFrame) – The frame to be labelled as being empty

put(frame: Frame, motion_score: float)#

Append the frame to this motion sequence

Parameters

frame (Frame) – Frame to be put in this motion sequence
motion_score (float) – Output value for this frame from the motion filtering stage