DynAIkonTrap.filtering.motion#

This module provides a general interface to a motion filtering stage. The motion filter determines if a frame contains sufficient motion to be of interest for passing on to the AnimalFilter stage. This stage in the pipeline is what allows the system to operate at video framerates as it allows the removal of empty frames that do not need to be analysed by an animal detector. Any method employed in the MotionFilter must therefore be able to operate fast enough that it does not form a bottleneck in the system.

The implementation can be replaced with another one easily as the interface simply takes the motion vectors from a frame, performs a calculation, and returns a value corresponding to the motion. If using the MotionFilter.run() method (over MotionFilter.run_raw()), the threshold is defined internally and a simple Boolean is provided as an output.

This implementation makes use of the Sum of Thresholded Vectors (SoTV) approach. Under this approach initially a small threshold is applied to all motion vectors. This removes the smallest vectors that are more likely to be due to noise or unimportant movements. Secondly, the vectors are summed together giving a single average motion vector for the frame. This step implicitely checks for coherence in movement vectors, as well as the magnitude and size of the area of motion. Finally, the vector is smoothed in time using a Chebyshev type-2 filter to reduce frame-to-frame oscillations in movement and give an insight to the trend in motion. The magnitude of the single smoothed vector representing motion in the frame can then be thresholded to determine if sufficient movement is declared, or not.

Classes

MotionFilter(settings, framerate)

Motion filtering stage employing the Sum of Thresholded Vectors (SoTV) approach.
class MotionFilter(settings: MotionFilterSettings, framerate: int)#

Motion filtering stage employing the Sum of Thresholded Vectors (SoTV) approach. The output of this stage is filtered in time using an IIR filter, to provide a smoothed result.

This implementation of the motion-based filter makes use of a Chebyshev type-2 filter to smooth the output.

Parameters:

  • settings (MotionFilterSettings) – Settings for the motion filter

  • framerate (int) – Framerate at which the frames were recorded

reset()#

Reset the internal IIR filter’s memory to zero

run(motion_frame: ndarray) → bool#

Apply a threshold to the output of run_raw()

Parameters:

motion_frame (np.ndarray) – Motion vectors for a frame

Returns:

True if the SoTV is at least the threshold, otherwise False

Return type:

bool

run_raw(motion_frame: ndarray) → float#
Run the motion filter using SoTV:

  1. Apply a small threshold to the motion vectors

  2. For those that exceed this, sum the vectors

  3. Apply time filtering to smooth this output

Parameters:

motion_frame (np.ndarray) – Motion vectors for a frame

Returns:

SoTV for the given frame

Return type:

float