GitHub - juleshenry/zooplankton-image-tool: Premier zooplankton image tool (ZIT)

ZIT is a tool designed to enhance and composite plankton photos from video frames. It uses computer vision techniques (OpenCV MOG2 background subtraction and contour filtering) to create clean, high-quality composites showing the locomotion of zooplankton.

Features

Frame Capture: Extract frames from videos at specified intervals.
Motion-Based Composition: Create composites by overlaying moving entities on a stable background.
Entity Recognition: Uses MOG2 background subtraction to isolate animals from noise and artifacts.
Parameter Sweeping: Find optimal threshold values for different video conditions.

Installation

Ensure you have Poetry installed.

Usage

CLI

Capture frames and create a composite in one command:

# Using poetry
poetry run zit --input samples/limo.mp4 --composite --entities

# If installed
zit --input samples/limo.mp4 --composite --entities

Parameters

--input, -i: Path to the input video.
--interval: Interval in seconds for frame capture (default: 1).
--composite: Enable composition after frame capture.
--entities: Use entity recognition for cleaner composites (recommended).
--epsilon: Difference threshold for entity detection (default: 20.0). Also referred to as Thresh in sweep grids.
--noise: Minimum pixel area for a detected entity (default: 50.0). Also referred to as MinArea in sweep grids.
--skip START END: Process only a specific frame range.
--out-file: Name of the output composite image (default: composited.png).

Parameter Sweep

To find the optimal threshold values for your video, use the parameter sweep script. It generates a 5x5 grid of composites sweeping across MinArea (noise) and Thresh (epsilon).