Building Flan a fancy feeder

This repository contains all ML pipeline to test and build the yolo model that will power Flan's new fancy feeder

Project Structure

.
├── data/
│   ├── raw/
│   │   ├── videos/      # Video source for dataset generation
│   │   └── rtsp/        # Captured RTSP frames
│   └── ready/           # Final YOLO train/val dataset
├── models/
│   ├── pretrained/      # Downloaded YOLO weights (e.g., yolo26n.pt)
│   └── runs/            # Fine-tuned YOLO weights
├── src/flan_feeder/     # CLI Application source code
└── pyproject.toml       # Python dependencies and CLI configuration

Quick Start

Assuming you have uv installed, initialize the environment and run the CLI:

uv sync
uv run flan-feeder --help

Main Pipeline

1. Gather Videos: Put videos in data/raw/videos/{source}/ and create a metadata.csv.
2. Generate Dataset:

   uv run flan-feeder dataset data/raw/videos/{source} --out data/ready/dataset

3. Merge RTSP (Optional): If you have manual captures in data/raw/rtsp/:

   uv run flan-feeder merge-rtsp data/raw/rtsp --out data/ready/dataset

4. Train:

   uv run flan-feeder train --data data/ready/dataset/dataset.yaml

Additional Commands

• collect: Stream from RTSP/video and save frames on animal detection.
• prototype: Run the feeder state machine logic on a video stream.
• detect: Test detection on a video (Multi-animal filter).
• organise: Split a labelled folder into train/val.
• convert: Transform Label Studio JSON to YOLO.

Linting and Formatting

This project uses ruff for linting and code formatting.

# Lint code
uv run ruff check

# Auto-fix linting issues
uv run ruff check --fix

# Format code
uv run ruff format

Automation

This project uses pre-commit to automate linting. To set it up locally:

uv run pre-commit install

Once installed, ruff will run automatically every time you commit.

Who is Flan?

Flan is a stray cat who lives in Spain. Flan is a shy cat who comes have lunch at my place every day. However, other cats caught wind of Flan's lunch spot and started showing up too - and either they leave him no food or they bully him. By building a fancy feeder that only dispenses food to him, we can make sure he gets his lunch without any competition.