# yaubernice/image-similarity architecture

> Architecture diagram of the GitHub repository yaubernice/image-similarity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaubernice/image-similarity
- Repository: https://github.com/yaubernice/image-similarity

## Overview

Image Similarity is a visual-search studio and CLI for comparing deep image descriptors with per-model nearest-neighbour indexes. The main workflow is to manage a photo library, build an index for a selected model, submit an image or CLIP text query, and inspect ranked results; optional processing adds whitening, query expansion, and geometric reranking. Separate branches support Caltech-101 evaluation and DINOv2 fine-tuning. Some connections are documented capabilities rather than fully visible call paths in the excerpts, so those edges cite the README.

Main entry points: [`evaluate.py`](https://github.com/yaubernice/image-similarity/blob/main/evaluate.py) (Retrieval evaluation), [`app.py`](https://github.com/yaubernice/image-similarity/blob/main/app.py) (Studio API), [`extractors.py`](https://github.com/yaubernice/image-similarity/blob/main/extractors.py) (Feature extractors), [`image_similarity.py`](https://github.com/yaubernice/image-similarity/blob/main/image_similarity.py) (CLI build and query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Search studio"]
  node_browser["Studio interface<br/>[app.js]"]
  node_api["Studio API<br/>[app.py]"]
end

subgraph group_retrieval["Retrieval runtime"]
  node_extractors["Feature extractors<br/>[extractors.py]"]
  node_retrieval_ops["Retrieval processing<br/>[retrieval.py]"]
  node_cli["CLI build and query"]
end

subgraph group_evaluation["Evaluation and training"]
  node_evaluation["Retrieval evaluation<br/>[evaluate.py]"]
  node_metrics["Ranking metrics<br/>[metrics.py]"]
  node_finetune["DINOv2 fine-tuning<br/>[finetune.py]"]
end

subgraph group_data["Image data"]
  node_library["Photo library"]
  node_index_store[("Model indexes")]
  node_caltech_prep["Caltech subset preparation"]
  node_caltech_data["Caltech queries and labels"]
  node_checkpoint["Fine-tuned checkpoint"]
  node_results["Evaluation outputs"]
end

node_user(("Studio user"))

node_user -->|"uses"| node_browser
node_browser -->|"calls API"| node_api
node_api -->|"manages photos"| node_library
node_api -->|"embeds queries"| node_extractors
node_api -->|"applies whitening"| node_retrieval_ops
node_api -->|"builds and searches"| node_index_store
node_cli -->|"embeds images"| node_extractors
node_cli -->|"uses processing"| node_retrieval_ops
node_cli -->|"stores indexes"| node_index_store
node_caltech_prep -->|"prepares subset"| node_caltech_data
node_evaluation -->|"reads queries"| node_caltech_data
node_evaluation -->|"embeds images"| node_extractors
node_evaluation -->|"processes rankings"| node_retrieval_ops
node_evaluation -->|"summarizes scores"| node_metrics
node_evaluation -->|"writes reports"| node_results
node_finetune -->|"trains on database"| node_caltech_data
node_finetune -->|"writes weights"| node_checkpoint
node_extractors -->|"loads fine-tuned weights"| node_checkpoint

click node_browser "https://github.com/yaubernice/image-similarity/blob/main/static/app.js"
click node_api "https://github.com/yaubernice/image-similarity/blob/main/app.py"
click node_library "https://github.com/yaubernice/image-similarity/tree/main/images/database"
click node_index_store "https://github.com/yaubernice/image-similarity/tree/main/index"
click node_extractors "https://github.com/yaubernice/image-similarity/blob/main/extractors.py"
click node_retrieval_ops "https://github.com/yaubernice/image-similarity/blob/main/retrieval.py"
click node_cli "https://github.com/yaubernice/image-similarity/blob/main/image_similarity.py"
click node_caltech_prep "https://github.com/yaubernice/image-similarity/blob/main/scripts/prepare_caltech101.py"
click node_evaluation "https://github.com/yaubernice/image-similarity/blob/main/evaluate.py"
click node_metrics "https://github.com/yaubernice/image-similarity/blob/main/metrics.py"
click node_finetune "https://github.com/yaubernice/image-similarity/blob/main/finetune.py"
click node_results "https://github.com/yaubernice/image-similarity/tree/main/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_api,node_user toneBlue
class node_extractors,node_retrieval_ops,node_cli toneAmber
class node_evaluation,node_metrics,node_finetune toneMint
class node_library,node_index_store,node_caltech_prep,node_caltech_data,node_checkpoint,node_results toneRose
```

## Components

### Search studio

- [Studio interface](https://github.com/yaubernice/image-similarity/blob/main/static/app.js): `static/app.js`
- [Studio API](https://github.com/yaubernice/image-similarity/blob/main/app.py): `app.py`

### Retrieval runtime

- [Feature extractors](https://github.com/yaubernice/image-similarity/blob/main/extractors.py): `extractors.py`
- [Retrieval processing](https://github.com/yaubernice/image-similarity/blob/main/retrieval.py): `retrieval.py`
- [CLI build and query](https://github.com/yaubernice/image-similarity/blob/main/image_similarity.py): `image_similarity.py`

### Evaluation and training

- [Retrieval evaluation](https://github.com/yaubernice/image-similarity/blob/main/evaluate.py): `evaluate.py`
- [Ranking metrics](https://github.com/yaubernice/image-similarity/blob/main/metrics.py): `metrics.py`
- [DINOv2 fine-tuning](https://github.com/yaubernice/image-similarity/blob/main/finetune.py): `finetune.py`

### Image data

- [Photo library](https://github.com/yaubernice/image-similarity/tree/main/images/database): `images/database`
- [Model indexes](https://github.com/yaubernice/image-similarity/tree/main/index): `index`
- [Caltech subset preparation](https://github.com/yaubernice/image-similarity/blob/main/scripts/prepare_caltech101.py): `scripts/prepare_caltech101.py`
- **Caltech queries and labels**
- **Fine-tuned checkpoint**
- [Evaluation outputs](https://github.com/yaubernice/image-similarity/tree/main/results): `results`

### Other components

- **Studio user**

## Connections

- Studio user → Studio interface: uses (evidence: `README.md`)
- Studio interface → Studio API: calls API (evidence: `static/app.js`)
- Studio API → Photo library: manages photos (evidence: `README.md`)
- Studio API → Feature extractors: embeds queries (evidence: `app.py`)
- Studio API → Retrieval processing: applies whitening (evidence: `app.py`)
- Studio API → Model indexes: builds and searches (evidence: `README.md`)
- CLI build and query → Feature extractors: embeds images (evidence: `image_similarity.py`)
- CLI build and query → Retrieval processing: uses processing (evidence: `image_similarity.py`)
- CLI build and query → Model indexes: stores indexes (evidence: `README.md`)
- Caltech subset preparation → Caltech queries and labels: prepares subset (evidence: `scripts/prepare_caltech101.py`)
- Retrieval evaluation → Caltech queries and labels: reads queries (evidence: `evaluate.py`)
- Retrieval evaluation → Feature extractors: embeds images (evidence: `evaluate.py`)
- Retrieval evaluation → Retrieval processing: processes rankings (evidence: `evaluate.py`)
- Retrieval evaluation → Ranking metrics: summarizes scores (evidence: `evaluate.py`)
- Retrieval evaluation → Evaluation outputs: writes reports (evidence: `README.md`)
- DINOv2 fine-tuning → Caltech queries and labels: trains on database (evidence: `finetune.py`)
- DINOv2 fine-tuning → Fine-tuned checkpoint: writes weights (evidence: `finetune.py`)
- Feature extractors → Fine-tuned checkpoint: loads fine-tuned weights (evidence: `extractors.py`)
