# drebain/deep_medial_fields architecture

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

- Interactive diagram: https://gitdiagram.com/drebain/deep_medial_fields
- Repository: https://github.com/drebain/deep_medial_fields

## Overview

##### Project Type and Purpose
- This is a research-oriented Python project implementing the “Deep Medial Fields” method described in the linked arXiv paper.
- It is neither a web app nor a compiler, but a computational pipeline for training and evaluating a neural network model on 3D mesh datasets (the `.obj` files in `datasets/`).

##### Analysis of File Structure
- Top-level modules:
- `data.py`, `datasets/` – data loading and preprocessing of 3D meshes
- `model.py`, `bilinear.py`, `loss.py`, `config.py` – network architecture, custom layers, loss definitions, and hyperparameters
- `training.py`, `run_train.py`, `summary.py` – training loop, experiment launcher, logging/summaries
- `rendering.py`, `run_ao.py` – inference/rendering of ambient occlusion or other outputs using the trained model
- Support files: `.pylintrc`, `requirements.txt`
- No frontend/backend split – it’s a single Python pipeline.

##### Key Components
a. Data Ingestion Component
- Source: `datasets/*.obj`
- Loader & Preprocessor: `data.py`
- Outputs: point clouds / sampled medial fields
b. Model Component
- Custom layers: `bilinear.py`
- Architecture: `model.py`
- Configuration: `config.py`
c. Training Component
- Loss computation: `loss.py`
- Optimizer & Loop: `training.py`
- Entry point: `run_train.py`
- Summaries/logs: `summary.py`
d. Inference/Rendering Component
- Inference script: `run_ao.py`
- Rendering pipeline: `rendering.py`
e. External Services & Frameworks
- JAX (autodiff, XLA, GPU/TPU backend)
- Standard Python libs (NumPy, etc.)

##### Relationships and Data Flow
- Data Ingestion → Model Input
- Model ↔ Loss Module (forward & backward passes)
- Training Loop writes to Summaries/Checkpoints
- Trained Model → Rendering/Inference
- All compute tasks executed by JAX on CPU/GPU

##### Architectural Patterns & Principles
- Modular separation of concerns: data, model, loss, training, rendering
- Pipeline model: clear unidirectional flow from raw data to final output
- Configuration-driven experiments via `config.py`
- Reusability of components (e.g., `bilinear.py` layer can be shared between training and inference)

##### Technologies & Frameworks to Annotate
- Python 3.x
- JAX (autodiff, jit, XLA)
- OBJ file format for 3D meshes
- Logging/summary (TensorBoard or custom)

##### Detail Level
- How `run_train.py` orchestrates imports from `data.py`, `model.py`, `loss.py`, and launches `training.py`.
- How `run_ao.py` loads the saved model and calls `rendering.py`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion
    DS["datasets/"]:::dataComp
    DP["data.py"]:::dataComp

    %% Model Components
    M["model.py"]:::modelComp
    BLP["bilinear.py"]:::modelComp
    CFG["config.py"]:::modelComp

    %% Training Components
    RUN_TRAIN["run_train.py"]:::trainComp
    LOSS["loss.py"]:::trainComp
    TRAIN["training.py"]:::trainComp
    SUMM["summary.py"]:::trainComp

    %% Inference/Rendering
    RUN_AO["run_ao.py"]:::renderComp
    REN["rendering.py"]:::renderComp
    OUT["Rendered Output"]:::renderComp

    %% External Framework
    JAX["JAX (autodiff, XLA)"]:::externalComp

    %% Data Flow
    DS -->|".obj meshes"| DP
    DP -->|"point cloud / medial field tensor"| M

    %% Model Details
    M -->|"uses layer"| BLP
    M -->|"reads params"| CFG
    CFG -->|"configures"| M

    %% Training Orchestration
    RUN_TRAIN -->|"loads data"| DP
    RUN_TRAIN -->|"builds model"| M
    RUN_TRAIN -->|"computes loss"| LOSS
    RUN_TRAIN -->|"starts loop"| TRAIN

    TRAIN -->|"computes gradients"| LOSS
    TRAIN -->|"writes logs/checkpoints"| SUMM

    %% Inference Flow
    RUN_AO -->|"loads trained model"| M
    RUN_AO -->|"calls pipeline"| REN
    REN -->|"renders images/fields"| OUT

    %% External Framework Usage
    DP -->|"uses"| JAX
    M -->|"jit/grad"| JAX
    LOSS -->|"auto-diff"| JAX
    TRAIN -->|"exec on GPU/TPU"| JAX
    REN -->|"jit render"| JAX

    %% Click Events
    click DP "https://github.com/drebain/deep_medial_fields/blob/main/data.py"
    click DS "https://github.com/drebain/deep_medial_fields/tree/main/datasets/"
    click M "https://github.com/drebain/deep_medial_fields/blob/main/model.py"
    click BLP "https://github.com/drebain/deep_medial_fields/blob/main/bilinear.py"
    click CFG "https://github.com/drebain/deep_medial_fields/blob/main/config.py"
    click LOSS "https://github.com/drebain/deep_medial_fields/blob/main/loss.py"
    click TRAIN "https://github.com/drebain/deep_medial_fields/blob/main/training.py"
    click RUN_TRAIN "https://github.com/drebain/deep_medial_fields/blob/main/run_train.py"
    click SUMM "https://github.com/drebain/deep_medial_fields/blob/main/summary.py"
    click REN "https://github.com/drebain/deep_medial_fields/blob/main/rendering.py"
    click RUN_AO "https://github.com/drebain/deep_medial_fields/blob/main/run_ao.py"

    %% Styles
    classDef dataComp fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modelComp fill:#90EE90,stroke:#333,stroke-width:1px
    classDef trainComp fill:#FFA500,stroke:#333,stroke-width:1px
    classDef renderComp fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef externalComp fill:#F0F0F0,stroke:#333,stroke-width:1px
```
