imcluster 0.4.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.

imcluster --cache results.parquet

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

The available methods use scikit-learn’s clustering algorithms.

By default, UMAP reduces the DINO vectors and K-means clusters the result. Use --reduce tsne or --reduce pca to select another reduction method, or --reduce none to cluster the original vectors. --reduction-dims sets the PCA or UMAP target and defaults to 50. Reduced vectors are cached.

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

To evaluate clusters against known classes, provide a CSV with filename and class columns:

imcluster photos/ --evaluate expected_classes.csv

The class names only need to be consistent. The CLI reports Normalized Mutual Information (NMI), Adjusted Rand Index (ARI), and clustering accuracy (ACC) using an optimal mapping between cluster IDs and expected classes.

Add --metric metrics.csv to save the three scores as a CSV file.

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

Explore similar images

The gallery can compare every image with its nearest visual neighbours. Click an image card to open the comparison modal: the selected image stays on the left while the 30 most similar images, ranked using cosine similarity between the original model feature vectors, are available on the right. Use the thumbnail strip or arrow buttons to move through the matches.

Click the image on the right to promote it to the selected image. The modal then updates with that image’s nearest neighbours, making it easy to explore related groups without closing the comparison view.

The modal loads full-resolution originals from their file paths when they are available and otherwise falls back to the embedded thumbnails. Each thumbnail is embedded only once in the standalone report and reused by JavaScript.

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.