# pavelsuma/ames architecture

> Architecture diagram of the GitHub repository pavelsuma/ames, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pavelsuma/ames
- Repository: https://github.com/pavelsuma/ames

## Overview

##### Project Overview and Main Components
- Identification: This is not a full-stack web application but a research and evaluation framework for image retrieval. Its primary goal is to extract features (descriptors) from images using backbones (CVNet and DINOv2) and then estimate similarity using a memory-efficient transformer-based model.
- Main components to include:
- Configuration Manager: Represent the conf folder that holds YAML definitions for datasets and model setups.
- Data Input / Preprocessing: Show components handling image reading and dataset preparation. Highlight extract/image_dataset.py and src/utils/dataset_loader.py.
- Model & Similarity Estimation Module: Illustrate the models within src/models (e.g., binarization_layer.py, resnet.py, transformer_dec.py, matcher.py). Indicate that these components implement the core transformer-based similarity estimation.
- Evaluation & Metrics Module: Include the evaluation script (src/evaluate.py) along with the metric utilities (src/utils/metrics.py) and other helper functions.
- Utilities: Indicate the utility scripts in src/utils that support dataset manipulation, tensor dataset handling, and miscellaneous functions.

##### Relationships and Data Flow
- The Extraction Module: to determine parameters such as dataset split, backbone choice, and descriptor type.
- Data Input flows into the Descriptor Extraction Module where images are preprocessed and descriptors are computed.
- The output descriptors are then used by the Model & Similarity Estimation Module. For example, the matcher in src/models/matcher.py and associated transformer decoder (transformer_dec.py) compute similarity scores.
- Finally, evaluation commands (in src/evaluate.py) take in extracted descriptors and the computed similarities, incorporating utility functions (e.g., metric calculation in src/utils/metrics.py) to output final performance metrics.

##### Architectural Patterns and Principles
- Modularity: Separate directories (conf, extract, src/models, src/utils) indicate a clean separation of concerns.
- Pipeline Architecture: Data flows sequentially from configuration to extraction to model inference and then evaluation.
- Extensibility: The extraction scripts for different backbones (CVNet vs. DINOv2) and configurable YAML files indicate that the design supports easy switching or extension to new dataset splits or network architectures.

##### Relevant Technologies and Frameworks
- Python 3.11.5 is the runtime.
- Key libraries include PyTorch (for modeling), hydra-core (for configuration management), numpy, and additional image processing dependencies (like opencv for descriptor extraction).
- Models: The use of ResNet, transformer modules, and binarization layers that are implemented inside the src/models directory.

##### Additional Detail Suggestions
- With hyperparameters where appropriate (λ value, temperature, etc.) that influence the similarity computation.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration"
        Config["Configuration Manager (YAML)"]
    end

    subgraph "Data Input / Preprocessing"
        DS1["Image Dataset Loader (extract/image_dataset.py)"]
        DS2["Dataset Loader (src/utils/dataset_loader.py)"]
    end

    subgraph "Descriptor Extraction Module"
        ED1["Extract Descriptors (extract/extract_descriptors.py)"]
        ED2["CVNet Extractor (extract/extract_cvnet.py)"]
        ED3["DINOv2 Extractor (extract/extract_dino.py)"]
        ED4["Image Transforms (extract/transforms.py)"]
    end

    subgraph "Model & Similarity Estimation Module"
        MOD1["Binarization Layer (src/models/binarization_layer.py)"]
        MOD2["ResNet (src/models/resnet.py)"]
        MOD3["Transformer Decoder (src/models/transformer_dec.py)"]
        MOD4["Matcher (src/models/matcher.py)"]
    end

    subgraph "Evaluation & Metrics Module"
        EVAL1["Evaluation Script (src/evaluate.py)"]
        EVAL2["Metrics Utility (src/utils/metrics.py)"]
    end

    subgraph "Utilities"
        UTIL1["Misc Utilities (src/utils/)"]
    end

    %% Connections and Data Flow
    Config -->|"loads"| DS1
    Config -->|"loads"| DS2
    Config -->|"configures"| ED1

    DS1 -->|"supplies_images"| ED1
    DS2 -->|"supplies_dataset"| ED1

    ED2 -->|"provides_features"| ED1
    ED3 -->|"provides_features"| ED1
    ED4 -->|"applies_transforms"| ED1

    ED1 -->|"outputs_descriptors"| MOD4

    MOD1 -->|"part_of_model"| MOD4
    MOD2 -->|"part_of_model"| MOD4
    MOD3 -->|"part_of_model"| MOD4

    MOD4 -->|"similarity_scores"| EVAL1
    EVAL1 -->|"evaluates_results"| EVAL2

    UTIL1 -->|"supports"| DS2
    UTIL1 -->|"supports"| EVAL1

    %% Click Events
    click Config "https://github.com/pavelsuma/ames/tree/main/conf/"
    click DS1 "https://github.com/pavelsuma/ames/blob/main/extract/image_dataset.py"
    click DS2 "https://github.com/pavelsuma/ames/blob/main/src/utils/dataset_loader.py"
    click ED1 "https://github.com/pavelsuma/ames/blob/main/extract/extract_descriptors.py"
    click ED2 "https://github.com/pavelsuma/ames/blob/main/extract/extract_cvnet.py"
    click ED3 "https://github.com/pavelsuma/ames/blob/main/extract/extract_dino.py"
    click ED4 "https://github.com/pavelsuma/ames/blob/main/extract/transforms.py"
    click MOD1 "https://github.com/pavelsuma/ames/blob/main/src/models/binarization_layer.py"
    click MOD2 "https://github.com/pavelsuma/ames/blob/main/src/models/resnet.py"
    click MOD3 "https://github.com/pavelsuma/ames/blob/main/src/models/transformer_dec.py"
    click MOD4 "https://github.com/pavelsuma/ames/blob/main/src/models/matcher.py"
    click EVAL1 "https://github.com/pavelsuma/ames/blob/main/src/evaluate.py"
    click EVAL2 "https://github.com/pavelsuma/ames/blob/main/src/utils/metrics.py"
    click UTIL1 "https://github.com/pavelsuma/ames/tree/main/src/utils/"

    %% Styling Classes for Color Coding
    class Config configuration;
    class DS1,DS2 data;
    class ED1,ED2,ED3,ED4 extraction;
    class MOD1,MOD2,MOD3,MOD4 model;
    class EVAL1,EVAL2 evaluation;
    class UTIL1 utility;

    classDef configuration fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef data fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef extraction fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef model fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef evaluation fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef utility fill:#F08080,stroke:#000,stroke-width:1px;
```
