# dali92002/htrbymatching architecture

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

- Interactive diagram: https://gitdiagram.com/dali92002/htrbymatching
- Repository: https://github.com/dali92002/htrbymatching

## Overview

##### Project Type and Purpose
- This is a research‐oriented machine‐learning project implementing a few‐shot handwriting recognition system in PyTorch. It combines object‐detection (Faster R-CNN style) with a metric‐learning / matching module for recognizing ciphered manuscript characters in low‐resource scenarios.

##### File Structure Analysis
Top-Level:
- alphabet/​…: support‐set character images grouped by cipher (borg, copiale, vatican).
- lines/​…: query‐set line images arranged per cipher.
- configs.py, htrmatching.yml: environment and hyperparameter settings.
- generate_data.py, load_data.py, utils.py, htr_utils.py, transforms.py: data preparation, augmentation, helper routines.
- train.py, train_progressive.py: entry points for standard vs. progressive few‐shot training.
- test.py: inference script that processes query lines against a trained model.
- src/: core model modules (Faster R-CNN backbone, RPN, ROI heads, matching layers, training/engine loop, COCO evaluation utilities).

##### Architecture Insights from README
- The system consists of two main stages:
a) Few‐Shot Matching Model (based on Faster R-CNN backbone + metric head)
b) Progressive Fine‐Tuning Pipeline (multi‐stage few‐shot adaptation)
- Input: small support set (“shots”) from alphabet/​… + query lines (lines/​…).
- Output: detection + classification of cipher characters in query lines.

##### Main Components & Their Relationships
A. Data Layer
- Support Dataset Loader
– Reads alphabet/<cipher>/<char>/sample.png
– Applies transforms (transforms.py)
- Query Dataset Loader
– Reads lines/<cipher>/line_*.png
– Applies line‐level transforms
- Configuration Parser (configs.py, htrmatching.yml)
B. Model Layer (src/)
- Backbone CNN (e.g., ResNet from generalized_rcnn.py)
- RPN (src/rpn.py) → region proposals for character candidates
- ROI Heads (src/roi_heads.py) → pool features per proposal
- Metric Matching Head (src/util_fc.py) → computes similarity between support features and query ROI features
- Loss & Training Engine (src/engine.py) → handles forward/backward, integrates coco_utils.py, coco_eval.py for metrics
C. Training & Fine‐Tuning
- train.py → standard few‐shot training from scratch or fine‐tuning with omniglot‐pretrained weights
- train_progressive.py → multi‐stage curriculum learning
D. Inference

##### Architectural Patterns & Design Principles
- Modular MVC‐style separation:
- Models and heads under src/
- Data preparation in separate scripts
- Configuration isolated from code
- Reuse of standard object‐detection pipelines (Faster R‐CNN) combined with custom matching layers
- Few‐shot training orchestrated by passing support and query batches through shared feature extractor

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SupportLoader["Support Dataset Loader"]:::data
        QueryLoader["Query Dataset Loader"]:::data
        AlphabetDir["Support Image Dir\n(alphabet/)"]:::data
        LinesDir["Query Image Dir\n(lines/)"]:::data
        TransformsData["Transforms & Augmentations\n(transforms.py)"]:::data
        TransformsModel["Transforms for Model\n(src/transforms.py)"]:::data
        ConfigParser["Configuration Parser\n(configs.py & htrmatching.yml)"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        Backbone["Backbone CNN\n(src/generalized_rcnn.py)"]:::model
        FasterRCNN["Faster R-CNN Integration\n(src/faster_rcnn.py)"]:::model
        RPN["Region Proposal Network\n(src/rpn.py)"]:::model
        ROIHeads["ROI Heads\n(src/roi_heads.py)"]:::model
        MatchingHead["Metric Matching Head\n(src/util_fc.py)"]:::model
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        direction TB
        TrainStd["Standard Few-Shot Training\n(train.py)"]:::script
        TrainProg["Progressive Fine-Tuning\n(train_progressive.py)"]:::script
        Engine["Loss & Training Engine\n(src/engine.py)"]:::script
        COCOUtils["COCO Utilities\n(src/coco_utils.py)"]:::script
        COCOEval["COCO Evaluation\n(src/coco_eval.py)"]:::script
        GeneralUtils["General Utility Functions\n(src/utils.py,\nutils.py, htr_utils.py)"]:::script
    end

    %% Inference
    subgraph "Inference"
        direction TB
        TestScript["Inference Script\n(test.py)"]:::script
    end

    %% Data Flow
    AlphabetDir --> SupportLoader
    LinesDir --> QueryLoader
    SupportLoader --> TransformsData
    QueryLoader --> TransformsData
    TransformsData --> Backbone
    TransformsModel --> Backbone
    Backbone --> FasterRCNN
    FasterRCNN --> RPN
    RPN --> ROIHeads
    ROIHeads --> MatchingHead
    MatchingHead --> Engine
    Engine --> COCOUtils
    COCOUtils --> COCOEval
    ConfigParser --> TrainStd
    ConfigParser --> TrainProg
    TrainStd --> Engine
    TrainProg --> Engine
    Engine --> TestScript

    %% Click Events
    click SupportLoader "https://github.com/dali92002/htrbymatching/blob/main/load_data.py"
    click QueryLoader "https://github.com/dali92002/htrbymatching/blob/main/load_data.py"
    click TransformsData "https://github.com/dali92002/htrbymatching/blob/main/transforms.py"
    click TransformsModel "https://github.com/dali92002/htrbymatching/blob/main/src/transforms.py"
    click AlphabetDir "https://github.com/dali92002/htrbymatching/tree/main/alphabet/"
    click LinesDir "https://github.com/dali92002/htrbymatching/tree/main/lines/"
    click ConfigParser "https://github.com/dali92002/htrbymatching/blob/main/configs.py"
    click ConfigParser "https://github.com/dali92002/htrbymatching/blob/main/htrmatching.yml"
    click Backbone "https://github.com/dali92002/htrbymatching/blob/main/src/generalized_rcnn.py"
    click FasterRCNN "https://github.com/dali92002/htrbymatching/blob/main/src/faster_rcnn.py"
    click RPN "https://github.com/dali92002/htrbymatching/blob/main/src/rpn.py"
    click ROIHeads "https://github.com/dali92002/htrbymatching/blob/main/src/roi_heads.py"
    click MatchingHead "https://github.com/dali92002/htrbymatching/blob/main/src/util_fc.py"
    click Engine "https://github.com/dali92002/htrbymatching/blob/main/src/engine.py"
    click COCOUtils "https://github.com/dali92002/htrbymatching/blob/main/src/coco_utils.py"
    click COCOEval "https://github.com/dali92002/htrbymatching/blob/main/src/coco_eval.py"
    click GeneralUtils "https://github.com/dali92002/htrbymatching/blob/main/src/utils.py"
    click GeneralUtils "https://github.com/dali92002/htrbymatching/blob/main/utils.py"
    click GeneralUtils "https://github.com/dali92002/htrbymatching/blob/main/htr_utils.py"
    click TrainStd "https://github.com/dali92002/htrbymatching/blob/main/train.py"
    click TrainProg "https://github.com/dali92002/htrbymatching/blob/main/train_progressive.py"
    click TestScript "https://github.com/dali92002/htrbymatching/blob/main/test.py"
    click imgs "https://github.com/dali92002/htrbymatching/tree/main/imgs/"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#2874A6,font-weight:bold
    classDef model fill:#D5F5E3,stroke:#1D8348,font-weight:bold
    classDef script fill:#FCF3CF,stroke:#B7950B,font-weight:bold
```
