# mobarakol/dares architecture

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

- Interactive diagram: https://gitdiagram.com/mobarakol/dares
- Repository: https://github.com/mobarakol/dares

## Overview

##### Project Type and Purpose
- This is an open-source PyTorch research framework for **training** and **evaluating** self-supervised depth estimation and pose estimation models in robotic endoscopic surgery.
- Key indicators:
- README title (“DARES”) and paper reference
- Scripts named `train_end_to_end.py`, `evaluate_depth.py`, etc.
- Directory structure: `datasets/`, `networks/`, evaluation scripts.

##### File Structure
- Top-level scripts:
- `train_end_to_end.py` → entrypoint for training
- `test_simple.py`, `evaluate_*.py`, `export_gt_depth.py` → inference & evaluation
- Core modules:
- `datasets/` → data loaders for Endovis, SCARED
- `networks/` → model architectures (encoder + decoders: depth, pose, flow, appearance flow)
- `layers.py`, `options.py`, `utils.py` → custom layers, argument parsing, common utilities
- Resource files:
- `splits/endovis/` → text files defining train/val/test splits
- Supporting code:
- `trainer_end_to_end.py` → training loop orchestration
- `visualize_pose.py` → post-processing visualization

##### Extract Architecture Insights from the README
- Dependencies: PyTorch 1.2.0, torchvision, CUDA; data preprocessing via ffmpeg.
- Core workflow:
Load frames → DataLoader → Model (ResNet encoder + multi-decoders) → Loss computation → Backprop & optimization → Checkpointing → Inference/Evaluation.

##### Main Components & Interactions
a. Components:
- Data sources: Endovis & SCARED datasets (video → extracted frames)
- Data preprocessing & splits: ffmpeg, `splits/endovis/`
- DataLoader & Dataset classes (`datasets/mono_dataset.py`, `scared_dataset.py`)
- Model definitions (`networks/resnet_encoder.py`, `depth_decoder.py`, `pose_cnn.py`, etc.)
- Training orchestrator (`trainer_end_to_end.py`, `train_end_to_end.py`)
- Evaluation modules (`evaluate_depth.py`, `evaluate_pose.py`, `evaluate_3d_reconstruction.py`)
- Utilities & configurations (`options.py`, `utils.py`)
- Outputs: model checkpoints, depth maps, pose trajectories, 3D point clouds
- External services: GPU (CUDA), file system (for datasets & logs)

b. Relationships & Data Flow:
1. Raw video/images → **preprocessing** → stored on disk
2. **Splits** define which files go to train/val/test
3. Training script reads split files → instantiates **Dataset** → passed to PyTorch **DataLoader**
4. **DataLoader** feeds batches to **Model** (ResNet encoder + decoders)
5. **Trainer** computes losses (self-supervised photometric, smoothness, flow consistency) → backprop → updates model → saves checkpoints
7. **Utilities** support logging, checkpoint I/O, plotting

c. Architectural Patterns & Principles:
- Modular code organization: clear separation of datasets, models, training logic, and evaluation
- Plug-and-play decoders: easy to swap depth/flow/pose heads
- Configuration via `options.py`: centralized hyperparameters
- Use of PyTorch’s DataLoader and nn.Module abstractions

d. Key Technologies & Libraries:
- PyTorch (models, training loop)
- torchvision (image transforms)
- ffmpeg (preprocessing)
- NumPy (splits, metrics)
- Matplotlib or similar (visualizations)

##### Final Checklist
- Break the system into the seven logical components listed above.
- Separate uplines for preprocessing, training, and evaluation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Preparation"
        fs["Raw Videos/Images"]:::data
        ffmpeg["ffmpeg"]:::process
        frames["Extracted Frames"]:::data
        splits["Splits (train/val/test)"]:::data
        fs -->|"preprocess"| ffmpeg
        ffmpeg -->|"images"| frames
        frames -->|"define_splits"| splits
    end

    subgraph "Training Pipeline"
        trainScript["train_end_to_end.py"]:::process
        options["options.py"]:::code
        utils["utils.py"]:::code
        layers["layers.py"]:::code
        monoDS["mono_dataset.py"]:::code
        scaredDS["scared_dataset.py"]:::code
        dataLoader["PyTorch DataLoader"]:::process
        trainer["trainer_end_to_end.py"]:::process
        checkpoints["Checkpoints"]:::data

        trainScript --> options
        trainScript --> utils
        trainScript --> layers
        splits --> trainScript
        trainScript --> monoDS
        trainScript --> scaredDS
        monoDS --> dataLoader
        scaredDS --> dataLoader
        dataLoader --> modelContainer
        trainer --> checkpoints
        trainer -->|"updates"| modelContainer
        trainer -->|"compute"| GPU
        trainScript --> trainer
    end

    subgraph "Model"
        encoder["ResNet Encoder"]:::code
        depthDec["Depth Decoders"]:::code
        poseCNN["Pose CNN"]:::code
        poseDec["Pose Decoder"]:::code
        flowDec["Optical Flow Decoder"]:::code
        appFlowDec["Appearance Flow Decoder"]:::code

        encoder --> depthDec
        encoder --> poseCNN
        poseCNN --> poseDec
        encoder --> flowDec
        encoder --> appFlowDec
    end

    modelContainer["Model Wrapper (dares.py)"]:::code
    modelContainer --> encoder
    modelContainer --> depthDec
    modelContainer --> poseCNN
    modelContainer --> poseDec
    modelContainer --> flowDec
    modelContainer --> appFlowDec

    subgraph "Evaluation & Inference"
        evalDepth["evaluate_depth.py"]:::process
        evalPose["evaluate_pose.py"]:::process
        eval3D["evaluate_3d_reconstruction.py"]:::process
        exportGT["export_gt_depth.py"]:::process
        testSimple["test_simple.py"]:::process
        visualize["visualize_pose.py"]:::process
        metrics["Metrics & Visualizations"]:::process

        evalDepth -->|"load_checkpoint"| modelContainer
        evalPose -->|"load_checkpoint"| modelContainer
        eval3D -->|"load_checkpoint"| modelContainer
        testSimple -->|"load_checkpoint"| modelContainer
        exportGT -->|"load_checkpoint"| modelContainer
        modelContainer --> metrics
        metrics --> visualize
        evalDepth -->|"compute"| GPU
        evalPose -->|"compute"| GPU
        eval3D -->|"compute"| GPU
        testSimple -->|"compute"| GPU
    end

    GPU["GPU (CUDA)"]:::ext

    click splits "https://github.com/mobarakol/dares/tree/main/splits/endovis/"
    click monoDS "https://github.com/mobarakol/dares/blob/main/datasets/mono_dataset.py"
    click scaredDS "https://github.com/mobarakol/dares/blob/main/datasets/scared_dataset.py"
    click encoder "https://github.com/mobarakol/dares/blob/main/networks/resnet_encoder.py"
    click depthDec "https://github.com/mobarakol/dares/blob/main/networks/depth_decoder.py"
    click poseCNN "https://github.com/mobarakol/dares/blob/main/networks/pose_cnn.py"
    click poseDec "https://github.com/mobarakol/dares/blob/main/networks/pose_decoder.py"
    click flowDec "https://github.com/mobarakol/dares/blob/main/networks/optical_flow_decoder.py"
    click appFlowDec "https://github.com/mobarakol/dares/blob/main/networks/appearance_flow_decoder.py"
    click trainScript "https://github.com/mobarakol/dares/blob/main/train_end_to_end.py"
    click trainer "https://github.com/mobarakol/dares/blob/main/trainer_end_to_end.py"
    click evalDepth "https://github.com/mobarakol/dares/blob/main/evaluate_depth.py"
    click evalPose "https://github.com/mobarakol/dares/blob/main/evaluate_pose.py"
    click eval3D "https://github.com/mobarakol/dares/blob/main/evaluate_3d_reconstruction.py"
    click exportGT "https://github.com/mobarakol/dares/blob/main/export_gt_depth.py"
    click testSimple "https://github.com/mobarakol/dares/blob/main/test_simple.py"
    click visualize "https://github.com/mobarakol/dares/blob/main/visualize_pose.py"
    click options "https://github.com/mobarakol/dares/blob/main/options.py"
    click utils "https://github.com/mobarakol/dares/blob/main/utils.py"
    click layers "https://github.com/mobarakol/dares/blob/main/layers.py"

    classDef code fill:#6cf,stroke:#333,stroke-width:1px
    classDef data fill:#9f6,stroke:#333,stroke-width:1px
    classDef process fill:#fc9,stroke:#333,stroke-width:1px
    classDef ext fill:#ccc,stroke:#333,stroke-width:1px
```
