# jan1na/proki-hackathon-24 architecture

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

- Interactive diagram: https://gitdiagram.com/jan1na/proki-hackathon-24
- Repository: https://github.com/jan1na/proki-hackathon-24

## Overview

##### Project type and purpose
- This is not a web app or microservice mesh but a command-line ML pipeline for image-based robotic gripper placement.
- It takes CSV task files, runs a deep-learning segmentation model, post-processes the masks, then runs a simulated-annealing optimizer and writes out solutions.

##### File structure
- Top level:
- Dockerfile, setup.py, requirements.txt → packaging & deployment
- data/ → placeholder input images & masks
- readme_images/ → static assets for documentation
- solution/ → main pipeline code + model checkpoint
- evaluate/ & my_evaluate/ → evaluation scripts & ground-truth/task CSVs
- solution/ substructure:
- main.py → CLI entrypoint
- deeplabv3_resnet101_preprocessing.py & preprocessing_utils.py → image prep
- DeepLabV3Plus_finetuning.ipynb → model fine-tuning notebook (Colab)
- simulated_annealing.py → optimizer
- visualizer.py → result rendering
- Configuration/build: setup.py for pip install; optional Dockerfile for containerization

##### README insights
- Three-stage pipeline:
1. Image segmentation via a fine-tuned DeepLabV3-Plus (ResNet101)
2. Post-processing (threshold + erosion) to get binary masks
3. Simulated annealing for gripper (x,y,θ) placement
- CLI usage: python solution/main.py <input tasks.csv> <output solutions.csv>
- External dependency: large model checkpoint stored on Google Drive

##### Main components
a. CLI Orchestrator (main.py) – reads input CSV, coordinates services, writes output CSV
b. Segmentation Service – loads fine-tuned DeepLabV3Plus model, performs inference on images
c. Preprocessing Module – resizes, normalizes, thresholds & erodes masks
d. Optimization Engine – runs simulated annealing to choose best gripper pose
e. Visualization & Evaluation – optional, via visualizer.py and evaluate/*.py for ground-truth comparisons
f. Data Stores & Artifacts – image assets, model checkpoint, input task CSVs, output CSVs
g. External Services – Google Drive for model storage (or S3); GPU resource for training/inference

##### Relationships & data flow
- The CLI Orchestrator triggers Segmentation → outputs raw mask
- Preprocessing Module consumes raw mask → produces binary mask
- Optimization Engine consumes binary mask + gripper geometry → produces (x,y,θ)
- Visualization can tap into binary mask + pose → render overlay
- Evaluation scripts consume output CSV + ground_truth.csv → compute metrics

##### Architectural patterns & design principles
- Pipeline Pattern: clear linear stages (segmentation → post-processing → optimization)
- Modularity: each stage separated into its own Python module
- Separation of concerns: CLI logic separate from model code and optimization logic

##### Detail level
- Technology/tool names inside or next to modules (e.g., “DeepLabV3-Plus (PyTorch)”, “SciPy SimAnneal”)
- Essential edges only—don’t recreate every util function, but do show major modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Data Store
    DATA_DIR[(data/)]:::data
    click DATA_DIR "https://github.com/jan1na/proki-hackathon-24/tree/main/data/"

    %% CLI Orchestrator
    CLI["CLI Orchestrator\n(main.py)"]:::compute
    click CLI "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/main.py"

    %% Segmentation Service
    SEG_SCRIPT["Segmentation Service\nDeepLabV3-Plus (PyTorch)\n(deeplabv3_resnet101_preprocessing.py)"]:::compute
    click SEG_SCRIPT "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/deeplabv3_resnet101_preprocessing.py"
    MODEL[(Model Checkpoint\n.pth)]:::data
    click MODEL "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/deeplabv3_binary_segmentation_42_i_correct.pth"

    %% Preprocessing Module
    PRE["Preprocessing Module\n(preprocessing_utils.py)"]:::orange
    click PRE "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/preprocessing_utils.py"

    %% Optimization Engine
    OPT["Optimization Engine\n(SciPy SimAnneal)\n(simulated_annealing.py)"]:::compute
    click OPT "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/simulated_annealing.py"

    %% Visualization Module
    VIS["Visualization Module\n(visualizer.py)"]:::orange
    click VIS "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/visualizer.py"

    %% Output Data Store
    OUT[(solutions.csv)]:::data

    %% Evaluation Subgraph
    subgraph "Evaluation"
        EV1["evaluate/eval.py"]:::compute
        click EV1 "https://github.com/jan1na/proki-hackathon-24/blob/main/evaluate/eval.py"
        EV2["my_evaluate/eval.py"]:::compute
        click EV2 "https://github.com/jan1na/proki-hackathon-24/blob/main/my_evaluate/eval.py"
        GT1[(ground_truth.csv)]:::data
        click GT1 "https://github.com/jan1na/proki-hackathon-24/blob/main/evaluate/ground_truth.csv"
        GT2[(ground_truth.csv)]:::data
        click GT2 "https://github.com/jan1na/proki-hackathon-24/blob/main/my_evaluate/ground_truth.csv"
        TASK1[(task.csv)]:::data
        click TASK1 "https://github.com/jan1na/proki-hackathon-24/blob/main/evaluate/task.csv"
        TASK2[(task.csv)]:::data
        click TASK2 "https://github.com/jan1na/proki-hackathon-24/blob/main/my_evaluate/task.csv"
    end

    %% Fine-Tuning Notebook
    NOTE["Fine-Tuning Notebook\n(DeepLabV3Plus_finetuning.ipynb)"]:::artifact
    click NOTE "https://github.com/jan1na/proki-hackathon-24/blob/main/solution/DeepLabV3Plus_finetuning.ipynb"

    %% External Model Storage
    CLOUD["Google Drive/S3"]:::external

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        DOCKER["Dockerfile"]:::artifact
        click DOCKER "https://github.com/jan1na/proki-hackathon-24/tree/main/Dockerfile"
        SETUP["setup.py"]:::artifact
        click SETUP "https://github.com/jan1na/proki-hackathon-24/blob/main/setup.py"
        REQ["requirements.txt"]:::artifact
        click REQ "https://github.com/jan1na/proki-hackathon-24/blob/main/requirements.txt"
    end

    %% Data Flow
    DATA_DIR -->|images & masks| CLI
    CLI -->|"tasks.csv"| SEG_SCRIPT
    CLOUD -->|provides checkpoint| MODEL
    MODEL --> SEG_SCRIPT
    SEG_SCRIPT -->|raw_mask.png| PRE
    PRE -->|binary_mask.npy| OPT
    OPT -->|solutions.csv| OUT
    PRE -.->|optional| VIS
    OPT -.->|optional| VIS
    CLI -->|invokes visualization| VIS

    %% Evaluation Flow
    OUT -->|solutions.csv| EV1
    TASK1 --> EV1
    GT1 --> EV1
    OUT -->|solutions.csv| EV2
    TASK2 --> EV2
    GT2 --> EV2

    %% Offline Training Flow
    NOTE -.->|fine-tuning| SEG_SCRIPT

    %% Styles
    classDef data fill:#8dd3c7,stroke:#333,stroke-width:1px;
    classDef compute fill:#b3e2cd,stroke:#333,stroke-width:1px;
    classDef orange fill:#fdb462,stroke:#333,stroke-width:1px;
    classDef artifact fill:#d9d9d9,stroke:#333,stroke-width:1px;
    classDef external fill:#80b1d3,stroke:#333,stroke-width:1px;
```
