# brz1409/bathyfacto architecture

> Architecture diagram of the GitHub repository brz1409/bathyfacto, 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/brz1409/bathyfacto
- Repository: https://github.com/brz1409/bathyfacto

## Overview

BathyFacto is a Nerfstudio plugin for training refraction-aware neural radiance fields from underwater imagery and exporting bathymetric point clouds. The user workflow is to obtain or build a mask- and metadata-rich dataset, train/evaluate the two-media model, then export points in the dataset’s global frame. The graph preserves the documented dataset-building, baseline, and download capabilities. Edges reflect explicit README claims or shown references and calls; unsampled implementation details are not inferred.

Main entry points: [`bathyfacto/bathyfacto_model.py`](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_model.py) (BathyFacto model), [`bathyfacto/bathyfacto_config.py`](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_config.py) (Training methods), [`bathyfacto/export.py`](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/export.py) (Point-cloud exporter), [`bathyfacto/build_dataset.py`](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/build_dataset.py) (Dataset builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dataset["Dataset preparation"]
  node_dataset_download["Dataset downloader"]
  node_xml_reader["Metashape XML reader<br/>[metashape_xml.py]"]
  node_normalization["Frame normalization<br/>[normalization.py]"]
  node_dataset_builder["Dataset builder<br/>[build_dataset.py]"]
  node_npz_dataset["BathyFacto dataset"]
end

subgraph group_training["Training and parsing"]
  node_parser_registration["Parser registration"]
  node_data_parser["Dataset parser"]
  node_data_manager["Masked ray data"]
  node_method_config["Training methods"]
  node_pipeline["Train and evaluate"]
end

subgraph group_geometry["Model and geometry"]
  node_model["BathyFacto model"]
  node_field["Radiance field"]
  node_two_media["Two-media geometry"]
end

subgraph group_export["Point-cloud export"]
  node_exporter["Point-cloud exporter<br/>[export.py]"]
  node_point_cloud["Bathymetric point cloud"]
end

node_user(("Researcher"))
node_metashape["Metashape project"]
node_source_data["Source dataset"]
node_nerfstudio["Nerfstudio runtime"]

node_user -->|"downloads"| node_dataset_download
node_source_data -->|"retrieves from"| node_dataset_download
node_user -->|"builds dataset"| node_dataset_builder
node_metashape -->|"provides project"| node_dataset_builder
node_dataset_builder -->|"parses XML"| node_xml_reader
node_dataset_builder -->|"uses transforms"| node_normalization
node_dataset_builder -->|"writes dataset"| node_npz_dataset
node_dataset_download -->|"provides dataset"| node_npz_dataset
node_npz_dataset -->|"loads dataset"| node_data_parser
node_parser_registration -->|"registers parser"| node_data_parser
node_data_parser -.->|"supplies parsed data"| node_data_manager
node_method_config -->|"configures parser"| node_parser_registration
node_method_config -->|"configures parser"| node_data_parser
node_method_config -->|"configures manager"| node_data_manager
node_method_config -->|"configures model"| node_model
node_method_config -->|"configures pipeline"| node_pipeline
node_user -->|"starts training"| node_nerfstudio
node_nerfstudio -.->|"runs pipeline"| node_pipeline
node_pipeline -->|"passes eval batch"| node_model
node_data_manager -.->|"provides masked rays"| node_model
node_model -->|"uses field"| node_field
node_model -->|"uses refraction geometry"| node_two_media
node_user -->|"exports points"| node_exporter
node_exporter -->|"renders camera rays"| node_model
node_exporter -->|"attaches medium mask"| node_data_manager
node_exporter -->|"uses frame transforms"| node_normalization
node_exporter -->|"writes PLY"| node_point_cloud

click node_dataset_download "https://github.com/brz1409/bathyfacto/blob/main/scripts/download_dataset.py"
click node_xml_reader "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/metashape_xml.py"
click node_normalization "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/normalization.py"
click node_dataset_builder "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/build_dataset.py"
click node_parser_registration "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_dataparser_plugin.py"
click node_data_parser "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_dataparser.py"
click node_data_manager "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_datamanager.py"
click node_method_config "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_config.py"
click node_pipeline "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_pipeline.py"
click node_model "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_model.py"
click node_field "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_field.py"
click node_two_media "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/two_media_geometry.py"
click node_exporter "https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/export.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_dataset_download,node_xml_reader,node_normalization,node_dataset_builder,node_npz_dataset toneBlue
class node_parser_registration,node_data_parser,node_data_manager,node_method_config,node_pipeline toneAmber
class node_model,node_field,node_two_media toneMint
class node_exporter,node_point_cloud toneRose
class node_user,node_metashape,node_source_data,node_nerfstudio toneIndigo
```

## Components

### Dataset preparation

- [Dataset downloader](https://github.com/brz1409/bathyfacto/blob/main/scripts/download_dataset.py): `scripts/download_dataset.py`
- [Metashape XML reader](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/metashape_xml.py): `bathyfacto/metashape_xml.py`
- [Frame normalization](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/normalization.py): `bathyfacto/normalization.py`
- [Dataset builder](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/build_dataset.py): `bathyfacto/build_dataset.py`
- **BathyFacto dataset**

### Training and parsing

- [Parser registration](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_dataparser_plugin.py): `bathyfacto/bathyfacto_dataparser_plugin.py`
- [Dataset parser](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_dataparser.py): `bathyfacto/bathyfacto_dataparser.py`
- [Masked ray data](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_datamanager.py): `bathyfacto/bathyfacto_datamanager.py`
- [Training methods](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_config.py): `bathyfacto/bathyfacto_config.py`
- [Train and evaluate](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_pipeline.py): `bathyfacto/bathyfacto_pipeline.py`

### Model and geometry

- [BathyFacto model](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_model.py): `bathyfacto/bathyfacto_model.py`
- [Radiance field](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/bathyfacto_field.py): `bathyfacto/bathyfacto_field.py`
- [Two-media geometry](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/two_media_geometry.py): `bathyfacto/two_media_geometry.py`

### Point-cloud export

- [Point-cloud exporter](https://github.com/brz1409/bathyfacto/blob/main/bathyfacto/export.py): `bathyfacto/export.py`
- **Bathymetric point cloud**

### Other components

- **Researcher**
- **Metashape project**
- **Source dataset**
- **Nerfstudio runtime**

## Connections

- Researcher → Dataset downloader: downloads (evidence: `README.md`)
- Source dataset → Dataset downloader: retrieves from (evidence: `README.md`)
- Researcher → Dataset builder: builds dataset (evidence: `README.md`)
- Metashape project → Dataset builder: provides project (evidence: `README.md`)
- Dataset builder → Metashape XML reader: parses XML (evidence: `bathyfacto/build_dataset.py`)
- Dataset builder → Frame normalization: uses transforms (evidence: `bathyfacto/build_dataset.py`)
- Dataset builder → BathyFacto dataset: writes dataset (evidence: `README.md`)
- Dataset downloader → BathyFacto dataset: provides dataset (evidence: `README.md`)
- BathyFacto dataset → Dataset parser: loads dataset (evidence: `README.md`)
- Parser registration → Dataset parser: registers parser (evidence: `bathyfacto/bathyfacto_dataparser_plugin.py`)
- Dataset parser → Masked ray data: supplies parsed data
- Training methods → Parser registration: configures parser (evidence: `bathyfacto/bathyfacto_config.py`)
- Training methods → Dataset parser: configures parser (evidence: `bathyfacto/bathyfacto_config.py`)
- Training methods → Masked ray data: configures manager (evidence: `bathyfacto/bathyfacto_config.py`)
- Training methods → BathyFacto model: configures model (evidence: `bathyfacto/bathyfacto_config.py`)
- Training methods → Train and evaluate: configures pipeline (evidence: `bathyfacto/bathyfacto_config.py`)
- Researcher → Nerfstudio runtime: starts training (evidence: `README.md`)
- Nerfstudio runtime → Train and evaluate: runs pipeline
- Train and evaluate → BathyFacto model: passes eval batch (evidence: `bathyfacto/bathyfacto_pipeline.py`)
- Masked ray data → BathyFacto model: provides masked rays (evidence: `bathyfacto/bathyfacto_model.py`)
- BathyFacto model → Radiance field: uses field (evidence: `bathyfacto/bathyfacto_model.py`)
- BathyFacto model → Two-media geometry: uses refraction geometry (evidence: `bathyfacto/bathyfacto_model.py`)
- Researcher → Point-cloud exporter: exports points (evidence: `README.md`)
- Point-cloud exporter → BathyFacto model: renders camera rays (evidence: `bathyfacto/export.py`)
- Point-cloud exporter → Masked ray data: attaches medium mask (evidence: `bathyfacto/export.py`)
- Point-cloud exporter → Frame normalization: uses frame transforms (evidence: `bathyfacto/export.py`)
- Point-cloud exporter → Bathymetric point cloud: writes PLY (evidence: `bathyfacto/export.py`)
