iconoscope 0.1.1

CNN/ViT image embedding mosaic — extract features, reduce to 2D, render a visual atlas

iconoscope

iconoscope is a python package for exploring image collections using visual similarity based on image embeddings extracted from models like CLIP and DINOv2/3. Embeddings can be used to generate a mosaic where visually similar images appear near each other, or for interactive exploration in a preliminary HTML viewer.

The name iconoscope comes from the Greek words for image (εἰκών) and to see (σκοπεῖν). The iconoscope was the first practical video camera tube used in early television cameras.

This package was inspired by Andrej Karpathy's CNN embedding visualizer. Version 0.1 started as a python port of Karpathy's cnnembed Matlab code created with Claude Code.

Install

pip install iconoscope
pip install "iconoscope[umap]"   # include UMAP reducer

Or with uv:

uv add iconoscope
uv add "iconoscope[umap]"

CLIP backend

The CLIP embedding backend is not available on PyPI and must be installed separately:

pip install git+https://github.com/openai/CLIP.git

Usage

Two-stage pipeline: embed first (slow, GPU-accelerated), then mosaic (fast, iterate freely).

1. Embed

Extract features from a directory of images and save to an HDF5 file:

iconoscope embed ./images/ mycollection.h5

2. Mosaic

Reduce embeddings to 2D and render a mosaic image:

iconoscope mosaic mycollection.h5

Output defaults to mycollection.jpg. Coordinates are cached in the HDF5 file so subsequent runs skip the slow dimensionality reduction step.

3. Viewer

Generate an interactive HTML viewer:

iconoscope viewer mycollection.h5

Writes mycollection.html. Requires a pre-built Svelte app (cd viewer && npm install && npm run build).

Other commands

iconoscope info mycollection.h5          # inspect what's stored in an embeddings file
iconoscope cluster mycollection.h5 -k 12 # k-means clustering on embeddings

Embeddings file

The .h5 file is the hand-off between pipeline stages. It holds:

• features — L2-normalized float32 embeddings [N, D]
• paths — image paths [N]
• coords — cached 2D coordinates [N, 2] (written after the first mosaic run)
• cluster assignments (written by cluster)

Run iconoscope info to inspect the contents of any embeddings file.