rtp4jc/immich-animals sidecar-v0.1.1

animal-ml sidecar v0.1.1 (beta)

on GitHub

Detection fix for the animal-ml sidecar. Same models as 0.1.0: this release only changes how photos are fed to the dog detector.

What's new

The detector was trained on photos that keep their shape, padded to a square. The sidecar was squashing every photo to a square instead, so a portrait phone photo reached the detector at about half its real width. 0.1.1 feeds photos the way the detector was trained on them.

• Owner phone photos with the dog found: 75% → 83% (3,755 frames from DogReID-1553)
• Named in-the-wild dog photos with a detection: 80% → 81%
• Tight whole-body dog photos with a detection: 99% → 100%
• Wolves and foxes detected as a dog: 40% → 56%. Cat photos detected as a dog: 14% → 11%.

Upgrading from 0.1.0

Change the image tag to ghcr.io/rtp4jc/animal-ml:0.1.1, then docker compose up -d animal-ml. Then run Administration → Job Queues → Face Detection → Refresh to find dogs 0.1.0 missed. Names and merges are kept.

The animal-ml sidecar adds your dogs to Immich's People tab.

Immich already detects human faces and groups them into people. This runs alongside it and does the same for individual dogs.

This beta is about dogs. Cats and other animals are not supported yet. A cat is occasionally detected, but that is not a goal of this release.

Before you start

Use Refresh on the Face Detection queue, not Reset. Refresh keeps every face already in your library, so names, merges and hidden people survive both adding the sidecar and removing it. Reset deletes all named faces and manual merges.

Setup

Next to your Immich docker-compose.yml, create docker-compose.override.yml:

services:
  animal-ml:
    container_name: animal_ml
    image: ghcr.io/rtp4jc/animal-ml:0.1.1
    environment:
      UPSTREAM_ML_URL: http://immich-machine-learning:3003
    restart: always

docker compose up -d animal-ml

Then Administration → Settings → Machine Learning → set the URL to http://animal-ml:3003. Leave Min Detection Score and Max Distance alone as the sidecar uses its own values for dogs.

Finally Administration → Job Queues → Face Detection → Refresh (this will take a long time if you have a large library)

Full instructions: sidecar/README.md

What to expect

Dogs you photograph a lot cluster well; a dog with 673 photos put 491 of them in one person. A dog with 11 photos scattered across five.

• Dogs with under ~15 photos may not group at all
• Similar-looking dogs get mixed together
• About one cat photo in nine is detected as a person
• Photos of people, landscapes, horses and buildings produce no false positives

Measured on 61 named dogs from Wikimedia Commons (952 photos), 27 MPDD dogs (244 photos) and 450 dog-free photos: 81% of in-the-wild dog photos produce a detection. Verified end-to-end against a stock Immich v3.2.2 stack.

How

This runs as a docker container next to the other Immich docker containers. It intercepts requests to detect people, detects dogs and produces an identity embedding, calls the actual Immich ML docker container and merges the results containing people and dog detections for each image.

Assets

The model files are attached here and baked into the published image. Verify them with sha256sum -c SHA256SUMS.

Licence

AGPL-3.0, because the detector is fine-tuned from Ultralytics YOLO11. The models are trained on data whose terms permit non-commercial research and personal use only — see NOTICE.