# 27aran/objecttwin architecture

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

- Interactive diagram: https://gitdiagram.com/27aran/objecttwin
- Repository: https://github.com/27aran/objecttwin

## Overview

ObjectTwin is an image-similarity search tool: the current implemented workflow is a user invoking the CLI with a reference image and folder, then receiving ranked matches. Search recursively discovers images, loads and normalizes them, and compares DINOv2 embeddings. TIFF handling and automatic CPU/GPU selection are supported capabilities. The README describes a GUI, but marks it planned; the packaged entry point currently only prints the version. The graph follows the sampled runtime sources and does not assume the future GUI workflow.

Main entry points: [`src/objecttwin/search.py`](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/search.py) (Search and ranking), [`src/objecttwin/cli.py`](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/cli.py) (Search CLI), [`src/objecttwin/embedder.py`](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/embedder.py) (DINOv2 embeddings), [`src/objecttwin/imageio.py`](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/imageio.py) (Image discovery and loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["Search CLI<br/>[cli.py]"]
  node_entrypoint["Package entry point<br/>[__main__.py]"]
end

subgraph group_images["Image intake"]
  node_imageio["Image discovery and loading<br/>[imageio.py]"]
  node_tiff["TIFF decoding and normalization<br/>[imageio.py]"]
end

subgraph group_similarity["Similarity engine"]
  node_search["Search and ranking<br/>[search.py]"]
  node_embedder["DINOv2 embeddings<br/>[embedder.py]"]
end

node_user(("CLI user"))
node_model["Pretrained DINOv2 model"]

node_user -->|"provides paths"| node_cli
node_cli -->|"loads model"| node_embedder
node_cli -->|"starts search"| node_search
node_search -->|"discovers and loads"| node_imageio
node_search -->|"embeds batches"| node_embedder
node_imageio -->|"decodes TIFF"| node_tiff
node_embedder -->|"loads pretrained weights"| node_model
node_search -->|"returns ranked matches"| node_cli

click node_cli "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/cli.py"
click node_entrypoint "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/__main__.py"
click node_search "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/search.py"
click node_imageio "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/imageio.py"
click node_tiff "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/imageio.py"
click node_embedder "https://github.com/27aran/objecttwin/blob/main/src/objecttwin/embedder.py"

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_cli,node_entrypoint,node_user toneBlue
class node_imageio,node_tiff toneAmber
class node_search,node_embedder toneMint
class node_model toneIndigo
```

## Components

### User interface

- [Search CLI](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/cli.py): `src/objecttwin/cli.py`
- [Package entry point](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/__main__.py): `src/objecttwin/__main__.py`

### Image intake

- [Image discovery and loading](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/imageio.py): `src/objecttwin/imageio.py`
- [TIFF decoding and normalization](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/imageio.py): `src/objecttwin/imageio.py`

### Similarity engine

- [Search and ranking](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/search.py): `src/objecttwin/search.py`
- [DINOv2 embeddings](https://github.com/27aran/objecttwin/blob/main/src/objecttwin/embedder.py): `src/objecttwin/embedder.py`

### Other components

- **CLI user**
- **Pretrained DINOv2 model**

## Connections

- CLI user → Search CLI: provides paths (evidence: `src/objecttwin/cli.py`)
- Search CLI → DINOv2 embeddings: loads model (evidence: `src/objecttwin/cli.py`)
- Search CLI → Search and ranking: starts search (evidence: `src/objecttwin/cli.py`)
- Search and ranking → Image discovery and loading: discovers and loads (evidence: `src/objecttwin/search.py`)
- Search and ranking → DINOv2 embeddings: embeds batches (evidence: `src/objecttwin/search.py`)
- Image discovery and loading → TIFF decoding and normalization: decodes TIFF (evidence: `src/objecttwin/imageio.py`)
- DINOv2 embeddings → Pretrained DINOv2 model: loads pretrained weights (evidence: `src/objecttwin/embedder.py`)
- Search and ranking → Search CLI: returns ranked matches (evidence: `src/objecttwin/cli.py`)
