# nearthlab/siammaskcpp architecture

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

- Interactive diagram: https://gitdiagram.com/nearthlab/siammaskcpp
- Repository: https://github.com/nearthlab/siammaskcpp

## Overview

##### Project type and purpose
- This is a C++-based real-time video object tracking & segmentation tool (a port of SiamMask) that uses TorchScript models and OpenCV.
- Its primary function is to load a pre-converted SiamMask model, read video frames (e.g., from the “tennis” sample folder), run inference to produce segmentation masks, and display or save the results.

##### File structure
- Top level:
- CMakeLists.txt (build orchestration)
- demo.cpp (CLI application entry point)
- config_davis.json & config_vot.json (model & run configurations)
- “tennis” (sample data input)
- “SiamMask” folder (core headers implementing conversion, geometry, state, main algorithm)
- “third_party” folder containing argparse (CLI parsing) and json (configuration parsing) libraries
- Patterns: single executable, modular headers, C++ library and sample folder.

##### Relationships & Data Flow
- External libs (OpenCV, LibTorch) feed into Preprocessing & Inference Engine
- CMake builds all code modules and links to OpenCV/LibTorch

##### Architectural patterns & design principles
- Modular separation: I/O (demo.cpp + argparse/json) vs. core algorithms (SiamMask headers) vs. external libs
- Single-process pipeline: sequential data flow per frame
- Dependency inversion: core logic depends on abstracted tensor/matrix operations, not on direct Torch or OpenCV calls

##### Detail checklist
- Config JSON parsed by json library → mapped to internal Config struct
- TorchScript modules represented as external resources loaded by torch::jit API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        style InputLayer fill:none,stroke:none
        videoSource["Video Frame Source"]:::data
        configLoader["Configuration JSON Loader"]:::input
        cliParser["CLI Parser"]:::input
    end

    %% Preprocessing Module
    subgraph "Preprocessing Module"
        style Preprocessing fill:none,stroke:none
        convert["cv::Mat conversions"]:::core
        geometry["Geometry utilities"]:::core
    end

    %% Inference Engine
    subgraph "Inference Engine"
        style Inference fill:none,stroke:none
        modelLoader["TorchScript Model Loader"]:::core
        modelFiles["Model Files"]:::data
    end

    %% Postprocessing Module
    subgraph "Postprocessing Module"
        style Postprocessing fill:none,stroke:none
        decode["Mask decoding & refinement"]:::core
        state["State handling"]:::core
        tensorConv["Tensor⇄cv::Mat conversions"]:::core
    end

    %% Visualization / Output
    subgraph "Visualization / Output"
        style Visualization fill:none,stroke:none
        viz["Overlay masks & Display/Save"]:::input
    end

    %% Build & External Dependencies
    subgraph "Build & External Dependencies"
        style BuildExternal fill:none,stroke:none
        cmake["CMake Build"]:::build
        opencv["OpenCV"]:::external
        libtorch["LibTorch"]:::external
        jsonLib["JSON parsing library"]:::external
        argparseLib["Argument parsing library"]:::external
    end

    %% Data Flow
    cliParser -->|"flags & input path"| configLoader
    configLoader -->|"Config struct"| convert
    videoSource -->|JPEG frames| convert
    convert -->|"cv::Mat"| modelLoader
    geometry --> modelLoader
    opencv --> convert
    opencv --> viz
    libtorch --> modelLoader
    modelLoader -->|"torch::Tensor"| decode
    decode --> state
    state --> tensorConv
    tensorConv --> viz
    viz -->|"display/save"| videoSource

    %% Build connections
    cmake --> cliParser
    cmake --> convert
    cmake --> modelLoader
    cmake --> decode
    cmake --> viz
    cmake --> opencv
    cmake --> libtorch
    cmake --> jsonLib
    cmake --> argparseLib

    %% External libs to modules
    jsonLib --> configLoader
    argparseLib --> cliParser

    %% Click Events
    click videoSource "https://github.com/nearthlab/siammaskcpp/tree/master/tennis/"
    click configLoader "https://github.com/nearthlab/siammaskcpp/tree/master/third_party/json/"
    click cliParser "https://github.com/nearthlab/siammaskcpp/blob/master/demo.cpp"
    click convert "https://github.com/nearthlab/siammaskcpp/blob/master/SiamMask/convert.h"
    click geometry "https://github.com/nearthlab/siammaskcpp/blob/master/SiamMask/geometry.h"
    click modelLoader "https://github.com/nearthlab/siammaskcpp/blob/master/demo.cpp"
    click decode "https://github.com/nearthlab/siammaskcpp/blob/master/SiamMask/siammask.h"
    click state "https://github.com/nearthlab/siammaskcpp/blob/master/SiamMask/state.h"
    click tensorConv "https://github.com/nearthlab/siammaskcpp/blob/master/SiamMask/numpy.h"
    click viz "https://github.com/nearthlab/siammaskcpp/blob/master/demo.cpp"
    click cmake "https://github.com/nearthlab/siammaskcpp/blob/master/CMakeLists.txt"
    click jsonLib "https://github.com/nearthlab/siammaskcpp/tree/master/third_party/json/"
    click argparseLib "https://github.com/nearthlab/siammaskcpp/tree/master/third_party/argparse/"

    %% Styles
    classDef input fill:#a3cef1,stroke:#036,stroke-width:1px
    classDef data fill:#89CFF0,stroke:#036,stroke-width:1px
    classDef core fill:#98FB98,stroke:#060,stroke-width:1px
    classDef external fill:#FFA500,stroke:#a54,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#888,stroke-width:1px
```
