v0.2

Complete rewrite of the package; uses transformers python library to use a consistent interface for loading and running models. HDF5 files from 0.1 are not compatible with v0.2.

Provides a command-line tool to work with image embeddings in a persistent, flexible image dataset stored in a custom HDF5 file. Includes the following functionality:

• Create an image dataset based on a directory of images; saves as an HDF5 file with image paths
  • Uses PIL to verify images before adding to dataset; stores base directory and relative paths for portability.
• Embed images with one or more vision models with optional pre-processing and save features in the image dataset file
  • Supports DINOv2, DINOv3, ResNet-50, CLIP, SigLIP
  • Supports center-cropping by % of image and grayscale
  • HDF5 support saving features from multiple models and configurations in parallel.
• Mosaic : generate a static mosaic from dataset images (or a subset); runs PCA and UMAP embeddings and then slots images into a grid
  • Uses UMAP coordinates for specified model and preprocessing options; generates and saves UMAP if not already present.
  • Uses most frequent aspect ratio of the images in the dataset and uses that to determine best fit grid size.
• UMAP: programmatically generate and save UMAP coordinates for any or all model features present in an image dataset file
• Cluster: Run k-means with a specified K on a set of embeddings and save the results to the HDF5 file
• Info: Report the contents of an iconoscope image dataset (number of image paths, extracted features, and any related UMAP coordinates or clustering)

An image dataset created by iconoscope v0.2 includes a schema and version number, with light validation of required fields.

Notebooks

The repository includes experimental Marimo notebooks for exploring image datasets:

• UMAP → grid animation, to explain how the image mosaic layout works
• Nearest Neighbor search with comparison across models
• Princeton Geniza Project image embedding explorer; autoloads a prepared image dataset, and makes available for both UMAP → grid and nearest neighbor search

---

What's Changed (auto-generated)

• Switch to hdf5 for dataset storage by @rlskoeser in #2
• Support saving features to existing image dataset by @rlskoeser in #23
• Add explicit dependencies and declare minimum required versions by @rlskoeser in #24
• improve cli speed; minimal imports, only when needed by @rlskoeser in #25
• Support more image formats by @rlskoeser in #26
• Fix rectangular mosaic grid assignment by @rlskoeser in #27
• Separate dataset creation from embed by @rlskoeser in #28
• Image dimensions & aspect ratio by @rlskoeser in #29
• Support multiple models when generating embeddings by @rlskoeser in #30
• Add support for preprocessing options + saved variant embeddings by @rlskoeser in #31
• PGP marimo notebook for image exploration by @rlskoeser in #33
• Improve umap save by @rlskoeser in #34
• Add basic validation when loading dataset hdf5 file by @rlskoeser in #35

Full Changelog: https://github.com/Princeton-CDH/iconoscope/commits/0.2