# nampham13/bt-shutternet architecture

> Architecture diagram of the GitHub repository nampham13/bt-shutternet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nampham13/bt-shutternet
- Repository: https://github.com/nampham13/bt-shutternet

## Overview

BT-ShutterNet estimates exposure fraction (and shutter angle) from blurred video by comparing inter-frame motion with within-exposure blur. The principal workflow runs from a clip or supervised frame/flow data, through preprocessing and dataset selection, to model inference and reported estimates or evaluation metrics. The model’s useful internal layers are its temporal-motion branch, key-frame blur-physics branch, and weighted physics estimator. The graph also preserves documented training, benchmarking, and data-visualization capabilities. Relationships are limited to README statements, shown imports, or SOURCE INDEX references; unsampled internals are not treated as inspected.

Main entry points: [`datasets/factory.py`](https://github.com/nampham13/bt-shutternet/blob/main/datasets/factory.py) (Dataset selection), [`models/factory.py`](https://github.com/nampham13/bt-shutternet/blob/main/models/factory.py) (Model configuration), [`utils/preprocessing.py`](https://github.com/nampham13/bt-shutternet/blob/main/utils/preprocessing.py) (ROI preprocessing), [`models/bt_net.py`](https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py) (Key-frame blur)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_preprocess["ROI preprocessing<br/>[preprocessing.py]"]
  node_roi["ROI operations<br/>[roi.py]"]
  node_flow_dataset["Synthetic blur dataset"]
  node_video_dataset["Real video dataset"]
  node_dataset_factory["Dataset selection<br/>[factory.py]"]
end

subgraph group_model["Exposure model"]
  node_model_factory["Model configuration<br/>[factory.py]"]
  node_encoder_blocks["Encoder and blocks<br/>[blocks.py]"]
  node_blur_descriptor["Blur descriptor<br/>[blur_descriptor.py]"]
  node_temporal_branch["Temporal motion<br/>[bt_net.py]"]
  node_blur_branch["Key-frame blur<br/>[bt_net.py]"]
  node_physics_estimator["Physics estimator<br/>[bt_net.py]"]
end

subgraph group_runtime["Train and evaluate"]
  node_train["Training<br/>[train.py]"]
  node_evaluate["Evaluation<br/>[evaluate.py]"]
  node_inference["Video inference<br/>[infer_video.py]"]
  node_metrics["Exposure metrics<br/>[metrics.py]"]
end

subgraph group_analysis["Diagnostics"]
  node_benchmark["Model benchmark<br/>[benchmark.py]"]
  node_visualization["Data visualization<br/>[visualization.py]"]
  node_visualize_script["Visualization workflow<br/>[visualize_data.py]"]
end

node_video_user(("Video user"))
node_flow_data[("Frame and flow data")]
node_manifest_data["Video manifest"]

node_video_user -->|"submits clip"| node_inference
node_flow_data -->|"supplies frames and flow"| node_flow_dataset
node_manifest_data -->|"lists video samples"| node_video_dataset
node_flow_dataset -->|"preprocesses frames"| node_preprocess
node_video_dataset -->|"preprocesses frames"| node_preprocess
node_preprocess -->|"uses ROI operations"| node_roi
node_dataset_factory -->|"selects dataset"| node_flow_dataset
node_dataset_factory -->|"selects dataset"| node_video_dataset
node_train -->|"creates dataset"| node_dataset_factory
node_evaluate -->|"creates dataset"| node_dataset_factory
node_model_factory -->|"constructs model"| node_temporal_branch
node_temporal_branch -->|"uses blocks"| node_encoder_blocks
node_blur_branch -->|"uses descriptor"| node_blur_descriptor
node_blur_branch -->|"uses blocks"| node_encoder_blocks
node_temporal_branch -->|"provides motion cues"| node_physics_estimator
node_blur_branch -->|"provides blur cues"| node_physics_estimator
node_train -->|"builds model"| node_model_factory
node_evaluate -->|"builds model"| node_model_factory
node_inference -->|"builds model"| node_model_factory
node_train -->|"reports metrics"| node_metrics
node_evaluate -->|"computes metrics"| node_metrics
node_inference -->|"preprocesses clip"| node_preprocess
node_benchmark -.->|"benchmarks model"| node_model_factory
node_visualize_script -->|"creates dataset"| node_dataset_factory
node_visualize_script -->|"renders samples"| node_visualization

click node_preprocess "https://github.com/nampham13/bt-shutternet/blob/main/utils/preprocessing.py"
click node_roi "https://github.com/nampham13/bt-shutternet/blob/main/utils/roi.py"
click node_flow_dataset "https://github.com/nampham13/bt-shutternet/blob/main/datasets/exposure_flow_dataset.py"
click node_video_dataset "https://github.com/nampham13/bt-shutternet/blob/main/datasets/exposure_video_dataset.py"
click node_dataset_factory "https://github.com/nampham13/bt-shutternet/blob/main/datasets/factory.py"
click node_model_factory "https://github.com/nampham13/bt-shutternet/blob/main/models/factory.py"
click node_encoder_blocks "https://github.com/nampham13/bt-shutternet/blob/main/models/blocks.py"
click node_blur_descriptor "https://github.com/nampham13/bt-shutternet/blob/main/models/blur_descriptor.py"
click node_temporal_branch "https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py"
click node_blur_branch "https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py"
click node_physics_estimator "https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py"
click node_train "https://github.com/nampham13/bt-shutternet/blob/main/scripts/train.py"
click node_evaluate "https://github.com/nampham13/bt-shutternet/blob/main/scripts/evaluate.py"
click node_inference "https://github.com/nampham13/bt-shutternet/blob/main/scripts/infer_video.py"
click node_metrics "https://github.com/nampham13/bt-shutternet/blob/main/utils/metrics.py"
click node_benchmark "https://github.com/nampham13/bt-shutternet/blob/main/scripts/benchmark.py"
click node_visualization "https://github.com/nampham13/bt-shutternet/blob/main/utils/visualization.py"
click node_visualize_script "https://github.com/nampham13/bt-shutternet/blob/main/scripts/visualize_data.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preprocess,node_roi,node_flow_dataset,node_video_dataset,node_dataset_factory,node_video_user toneBlue
class node_model_factory,node_encoder_blocks,node_blur_descriptor,node_temporal_branch,node_blur_branch,node_physics_estimator,node_flow_data toneAmber
class node_train,node_evaluate,node_inference,node_metrics toneMint
class node_benchmark,node_visualization,node_visualize_script toneRose
class node_manifest_data toneIndigo
```

## Components

### Data preparation

- [ROI preprocessing](https://github.com/nampham13/bt-shutternet/blob/main/utils/preprocessing.py): `utils/preprocessing.py`
- [ROI operations](https://github.com/nampham13/bt-shutternet/blob/main/utils/roi.py): `utils/roi.py`
- [Synthetic blur dataset](https://github.com/nampham13/bt-shutternet/blob/main/datasets/exposure_flow_dataset.py): `datasets/exposure_flow_dataset.py`
- [Real video dataset](https://github.com/nampham13/bt-shutternet/blob/main/datasets/exposure_video_dataset.py): `datasets/exposure_video_dataset.py`
- [Dataset selection](https://github.com/nampham13/bt-shutternet/blob/main/datasets/factory.py): `datasets/factory.py`

### Exposure model

- [Model configuration](https://github.com/nampham13/bt-shutternet/blob/main/models/factory.py): `models/factory.py`
- [Encoder and blocks](https://github.com/nampham13/bt-shutternet/blob/main/models/blocks.py): `models/blocks.py`
- [Blur descriptor](https://github.com/nampham13/bt-shutternet/blob/main/models/blur_descriptor.py): `models/blur_descriptor.py`
- [Temporal motion](https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py): `models/bt_net.py`
- [Key-frame blur](https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py): `models/bt_net.py`
- [Physics estimator](https://github.com/nampham13/bt-shutternet/blob/main/models/bt_net.py): `models/bt_net.py`

### Train and evaluate

- [Training](https://github.com/nampham13/bt-shutternet/blob/main/scripts/train.py): `scripts/train.py`
- [Evaluation](https://github.com/nampham13/bt-shutternet/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Video inference](https://github.com/nampham13/bt-shutternet/blob/main/scripts/infer_video.py): `scripts/infer_video.py`
- [Exposure metrics](https://github.com/nampham13/bt-shutternet/blob/main/utils/metrics.py): `utils/metrics.py`

### Diagnostics

- [Model benchmark](https://github.com/nampham13/bt-shutternet/blob/main/scripts/benchmark.py): `scripts/benchmark.py`
- [Data visualization](https://github.com/nampham13/bt-shutternet/blob/main/utils/visualization.py): `utils/visualization.py`
- [Visualization workflow](https://github.com/nampham13/bt-shutternet/blob/main/scripts/visualize_data.py): `scripts/visualize_data.py`

### Other components

- **Video user**
- **Frame and flow data**
- **Video manifest**

## Connections

- Video user → Video inference: submits clip (evidence: `README.md`)
- Frame and flow data → Synthetic blur dataset: supplies frames and flow (evidence: `README.md`)
- Video manifest → Real video dataset: lists video samples (evidence: `datasets/exposure_video_dataset.py`)
- Synthetic blur dataset → ROI preprocessing: preprocesses frames (evidence: `datasets/exposure_flow_dataset.py`)
- Real video dataset → ROI preprocessing: preprocesses frames (evidence: `datasets/exposure_video_dataset.py`)
- ROI preprocessing → ROI operations: uses ROI operations (evidence: `utils/preprocessing.py`)
- Dataset selection → Synthetic blur dataset: selects dataset (evidence: `datasets/factory.py`)
- Dataset selection → Real video dataset: selects dataset (evidence: `datasets/factory.py`)
- Training → Dataset selection: creates dataset (evidence: `scripts/train.py`)
- Evaluation → Dataset selection: creates dataset (evidence: `scripts/evaluate.py`)
- Model configuration → Temporal motion: constructs model (evidence: `models/factory.py`)
- Temporal motion → Encoder and blocks: uses blocks (evidence: `models/bt_net.py`)
- Key-frame blur → Blur descriptor: uses descriptor (evidence: `models/bt_net.py`)
- Key-frame blur → Encoder and blocks: uses blocks (evidence: `models/bt_net.py`)
- Temporal motion → Physics estimator: provides motion cues (evidence: `README.md`)
- Key-frame blur → Physics estimator: provides blur cues (evidence: `README.md`)
- Training → Model configuration: builds model (evidence: `scripts/train.py`)
- Evaluation → Model configuration: builds model (evidence: `scripts/evaluate.py`)
- Video inference → Model configuration: builds model (evidence: `scripts/infer_video.py`)
- Training → Exposure metrics: reports metrics (evidence: `scripts/train.py`)
- Evaluation → Exposure metrics: computes metrics (evidence: `scripts/evaluate.py`)
- Video inference → ROI preprocessing: preprocesses clip (evidence: `scripts/infer_video.py`)
- Model benchmark → Model configuration: benchmarks model
- Visualization workflow → Dataset selection: creates dataset (evidence: `scripts/visualize_data.py`)
- Visualization workflow → Data visualization: renders samples (evidence: `scripts/visualize_data.py`)
