imcluster 0.3.0

Installation

imcluster requires Python 3.10–3.13:

pip install imcluster

DINOv2 presets are public and require no authentication. DINOv3 model repositories are gated. Before using --dino-version 3:

1. Sign in to Hugging Face and open the DINOv3 ViT-B/16 model page.

2. Review and accept Meta’s DINOv3 license and agree to share the requested contact information. Approval is usually automatic, but access can take several minutes (often 5–15 minutes) to propagate.

3. Authenticate the machine that will run imcluster:

   hf auth login

   This opens Hugging Face’s browser login flow and stores the resulting token locally. Confirm the active account with:

   hf auth whoami

For a server or non-interactive environment, create a read token in Hugging Face token settings and expose it to the process instead:

export HF_TOKEN=hf_your_token_here

Never commit a Hugging Face token to the repository or place it directly in a script. Accepting access on the website and authenticating locally are both required; a valid token from an account without model access cannot download the weights.

DINOv2 weights use the Apache License 2.0. DINOv3 weights use the DINOv3 license; the imcluster source code uses the Apache License 2.0.

Quick start

Cluster the images directly inside a directory and open the gallery:

imcluster photos/

Include nested directories, request 12 groups, and preserve the outputs:

imcluster photos/ --recursive --n-clusters 12 \
    --cache results.parquet --gallery clusters.html

Inputs may be individual image files, directories, or UTF-8 text manifests with one image path per line. Relative manifest entries are resolved from the manifest’s directory. Supported formats are PNG, JPEG, TIFF, BMP, and GIF.

Models

The default selection is --dino-version auto --size base. Automatic mode uses DINOv3 when the selected model is cached or accessible with the active Hugging Face account. Otherwise it reports the fallback and uses DINOv2.

Explicit DINOv2 selection uses --dino-version 2. Its presets are small, base, large, and max; max selects DINOv2 Giant. For DINOv2, --arch is ignored. In automatic mode, tiny falls back to DINOv2 Small and huge falls back to DINOv2 Giant.

DINOv3 is selected with --dino-version 3. Its available presets are:

An arbitrary compatible Hugging Face model overrides the preset:

imcluster photos/ --model organization/model-id

Inference

--device auto selects CUDA, then Apple MPS, then CPU. A device can be selected explicitly with --device cpu|cuda|mps. --batch-size defaults to 8; reduce it if inference runs out of memory.

ViT-B is suitable for a quality-oriented default but can be slow on CPU. --dino-version 2 --size small or --dino-version 3 --size tiny provides a lighter run. The largest variants require substantial accelerator memory.

Clustering

Spectral, K-means, agglomerative, and hierarchical clustering use a cluster count:

imcluster photos/ --clustering spectral --n-clusters 10

DBSCAN discovers groups and marks outliers as the noise cluster:

imcluster photos/ --clustering dbscan \
    --dbscan-eps 0.35 --min-samples 3

HDBSCAN also discovers groups and noise while adapting to varying densities:

imcluster photos/ --clustering hdbscan --min-samples 5

Run imcluster --help for the complete command-line reference.

Limitations

Model downloads can be large, and the biggest presets are impractical without a high-memory GPU. Clustering quality depends on the visual domain and chosen parameters. The models’ training data also carries the biases documented by their authors.

Credits

imcluster is maintained by Robert Turnbull at the Melbourne Data Analytics Platform. Zaher Joukhadar was instrumental in the original idea, and James Quang helped implement DINO feature extraction.