Bird Watcher

Turn your PiPiece into an automatic wildlife camera. The Bird Watcher uses on-device AI to detect birds and photograph them the moment they land at your feeder — no manual triggering required.

Real-World Captures

Getting Started

1. Install dependencies

The Bird Watcher requires a small one-time setup on the Pi. Run this in a terminal:

source ~/litert_venv/bin/activate
pip install opencv-python-headless numpy

The AI model (~4 MB) downloads automatically the first time you start the watcher.

2. Take a preview photo

Click Take Preview Photo to capture a still image of your feeder setup. This image appears in the main area and is used for drawing the seed level region.

3. Mark the seed tube (optional)

If you have a transparent tube feeder, you can enable automatic seed level monitoring:

1. Click Draw ROI in the sidebar
2. Click and drag on the image to draw a rectangle over the visible seed column
3. The saved region appears as a blue overlay — toggle it with Show ROI
4. Click Clear ROI or Redraw ROI to adjust

4. Configure detection settings

Setting	Default	What it does
Confidence	0.35	How certain the AI must be before triggering a capture. Lower values catch more birds but may produce false triggers on leaves or shadows.
Cooldown (s)	30	Minimum gap between captures. Prevents hundreds of frames of the same bird.
New Bird Window (days)	30	How many days must pass before a species is considered "new" again. Set to 0 to alert only on all-time first sightings.
Rare Bird Threshold	5	Species with fewer total sightings than this trigger a "rare bird" alert.

5. Start watching

Click Start Bird Watcher. The sidebar switches to the active state and shows ● WATCHING.

While It's Running

The sidebar shows:

• ● WATCHING — green pulsing indicator alongside the Stop button
• Running — total elapsed time since starting
• Detections — count of birds photographed this session
• Seed Level — estimated fill percentage for your tube feeder (requires a drawn ROI)

The main area updates in real time — each new capture replaces the previous image automatically.

Bird Rarity Alerts

When a bird is detected, PiPiece checks whether it's a new or rare visitor. A full-screen outline flashes to get your attention without interrupting anything.

New bird — gold outline

A gold outline with NEW BIRD badge appears when a species hasn't visited within your configured window (default: 30 days).

Rare bird — silver outline

A silver outline with RARE BIRD badge appears when a species has fewer total sightings than your threshold (default: 5).

The alert flashes 3 times then pulses slowly. It clears automatically after 30 seconds, or resets if a new detection arrives.

Seed Level Monitoring

When a ROI is drawn, the seed estimator scans it from bottom to top looking for seed-colored pixels. The level updates with each capture.

Level	Color	Meaning
20%+	White	Seed level OK
5–20%	Yellow	Getting low
< 5%	Red	Nearly empty

Your Captures

Bird detection photos are saved to ~/photos/bird_captures/ on the Pi — both a JPEG and a RAW DNG file for each detection:

bird_20260322_170445.jpg
bird_20260322_170445.dng

Sighting history is stored in ~/pipiece/config/:

• bird-species-summary.json — per-species totals with first and last seen dates
• bird-watcher-sightings.json — individual detection log

Troubleshooting

No detections despite birds present: Try lowering confidence to 0.25. Check the PM2 logs:

pm2 logs expressjs | grep bird-watcher

Seed level looks wrong: Redraw the ROI tightly around just the seed column, not the feeder tube walls. Lighting changes affect accuracy.