# kwikerrr/point2wss architecture

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

- Interactive diagram: https://gitdiagram.com/kwikerrr/point2wss
- Repository: https://github.com/kwikerrr/point2wss

## Overview

Point2WSS trains and evaluates a cross-modal masked autoencoder that reconstructs WSS roof parameters from LiDAR point clouds. Its data path loads paired cloud/label samples, preprocesses them and tokenizes roof geometry; training feeds both modalities to mutually conditioned branches, with reconstruction and alignment objectives. The graph also includes the documented evaluation entry point and the model’s key internal stages. Relationship evidence is limited to the README and sampled/indexed source references; unsampled wiring is not inferred.

Main entry points: [`src/nets/branches/pointcloud_branch_mae.py`](https://github.com/kwikerrr/point2wss/blob/main/src/nets/branches/pointcloud_branch_mae.py) (Point-cloud branch), [`src/losses/point2wss_loss.py`](https://github.com/kwikerrr/point2wss/blob/main/src/losses/point2wss_loss.py) (Multimodal losses), [`src/train.py`](https://github.com/kwikerrr/point2wss/blob/main/src/train.py) (Training entry point), [`src/tokenization/numerical/tokenizer.py`](https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/tokenizer.py) (Multipitch tokenizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_split_loader["Split loader<br/>[txt_loader.py]"]
  node_data_module["Synthetic data module"]
  node_synthetic_dataset["Synthetic dataset"]
  node_grid_dataset["Grid dataset"]
  node_base_dataset["Dataset preprocessing<br/>[base_dataset.py]"]
end

subgraph group_representation["Roof representation"]
  node_tokenizer["Multipitch tokenizer<br/>[tokenizer.py]"]
  node_sequence_format["Sequence grammar<br/>[sequence_format.py]"]
  node_vocabulary["Token vocabulary<br/>[vocabulary.py]"]
  node_numerical_encoder["Numerical encoding<br/>[encoders.py]"]
end

subgraph group_model["Cross-modal model"]
  node_point2wss["Point2WSS network<br/>[point2wss.py]"]
  node_parameter_branch["Parameter branch<br/>[params_branch.py]"]
  node_parameter_encoder["Parameter encoder<br/>[params_encoder.py]"]
  node_parameter_masker["Parameter masker<br/>[params_masker.py]"]
  node_parameter_cross["Parameter cross-encoder"]
  node_point_branch["Point-cloud branch"]
  node_point_encoder["Point-cloud encoder"]
  node_patch_divider["Patch divider<br/>[patch_divider.py]"]
  node_geometry["Point-cloud geometry<br/>[geometry.py]"]
  node_point_masker["Point-cloud masker"]
  node_point_cross["Point-cloud cross-encoder"]
  node_transformer_attention["Attention layers<br/>[attention.py]"]
end

subgraph group_objectives["Training objectives"]
  node_loss["Multimodal losses<br/>[point2wss_loss.py]"]
  node_reconstruction_loss["Reconstruction loss<br/>[reconstruction.py]"]
  node_chamfer_loss["Chamfer loss<br/>[chamfer.py]"]
  node_contrastive_loss["Contrastive losses<br/>[contrastive.py]"]
  node_cross_contrastive_loss["Cross-modal alignment"]
end

subgraph group_execution["Train and evaluate"]
  node_training_module["Lightning training module<br/>[training_module.py]"]
  node_train_entry["Training entry point<br/>[train.py]"]
  node_eval_entry["Evaluation entry point<br/>[eval.py]"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_train_entry
node_train_entry -->|"instantiates"| node_tokenizer
node_train_entry -->|"instantiates"| node_data_module
node_train_entry -->|"instantiates"| node_training_module
node_train_entry -->|"fits model"| node_training_module
node_data_module -->|"loads splits"| node_split_loader
node_data_module -->|"creates datasets"| node_grid_dataset
node_data_module -->|"creates datasets"| node_synthetic_dataset
node_grid_dataset -->|"inherits preprocessing"| node_base_dataset
node_synthetic_dataset -->|"uses base class"| node_base_dataset
node_grid_dataset -->|"tokenizes labels"| node_tokenizer
node_synthetic_dataset -->|"tokenizes labels"| node_tokenizer
node_tokenizer -->|"uses grammar"| node_sequence_format
node_tokenizer -->|"uses token IDs"| node_vocabulary
node_sequence_format -.->|"uses numeric ranks"| node_numerical_encoder
node_training_module -.->|"runs network"| node_point2wss
node_point2wss -->|"dispatches parameters"| node_parameter_branch
node_point2wss -->|"dispatches point cloud"| node_point_branch
node_parameter_branch -.->|"encodes tokens"| node_parameter_encoder
node_parameter_branch -->|"masks tokens"| node_parameter_masker
node_parameter_branch -->|"cross-attends"| node_parameter_cross
node_point_branch -->|"forms patches"| node_patch_divider
node_patch_divider -->|"uses sampling"| node_geometry
node_point_branch -.->|"encodes patches"| node_point_encoder
node_point_branch -->|"masks patches"| node_point_masker
node_point_branch -->|"cross-attends"| node_point_cross
node_parameter_cross -.->|"uses attention"| node_transformer_attention
node_point_cross -.->|"uses attention"| node_transformer_attention
node_training_module -.->|"computes objectives"| node_loss
node_loss -.->|"uses reconstruction"| node_reconstruction_loss
node_loss -.->|"uses geometry loss"| node_chamfer_loss
node_loss -.->|"uses alignment"| node_contrastive_loss
node_loss -.->|"uses cross alignment"| node_cross_contrastive_loss
node_user -->|"starts evaluation"| node_eval_entry

click node_split_loader "https://github.com/kwikerrr/point2wss/blob/main/src/datamodules/loaders/txt_loader.py"
click node_data_module "https://github.com/kwikerrr/point2wss/blob/main/src/datamodules/synthetic_datamodule.py"
click node_synthetic_dataset "https://github.com/kwikerrr/point2wss/blob/main/src/datasets/synthetic_dataset.py"
click node_grid_dataset "https://github.com/kwikerrr/point2wss/blob/main/src/datasets/grid_synthetic_dataset.py"
click node_base_dataset "https://github.com/kwikerrr/point2wss/blob/main/src/datasets/base_dataset.py"
click node_tokenizer "https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/tokenizer.py"
click node_sequence_format "https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/sequence_format.py"
click node_vocabulary "https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/vocabulary.py"
click node_numerical_encoder "https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/encoders.py"
click node_point2wss "https://github.com/kwikerrr/point2wss/blob/main/src/nets/point2wss.py"
click node_parameter_branch "https://github.com/kwikerrr/point2wss/blob/main/src/nets/branches/params_branch.py"
click node_parameter_encoder "https://github.com/kwikerrr/point2wss/blob/main/src/nets/encoders/params_encoder.py"
click node_parameter_masker "https://github.com/kwikerrr/point2wss/blob/main/src/nets/maskers/params_masker.py"
click node_parameter_cross "https://github.com/kwikerrr/point2wss/blob/main/src/nets/cross_encoders/param_cross_encoder.py"
click node_point_branch "https://github.com/kwikerrr/point2wss/blob/main/src/nets/branches/pointcloud_branch_mae.py"
click node_point_encoder "https://github.com/kwikerrr/point2wss/blob/main/src/nets/encoders/pointcloud_encoder.py"
click node_patch_divider "https://github.com/kwikerrr/point2wss/blob/main/src/nets/pointcloud/patch_divider.py"
click node_geometry "https://github.com/kwikerrr/point2wss/blob/main/src/nets/pointcloud/geometry.py"
click node_point_masker "https://github.com/kwikerrr/point2wss/blob/main/src/nets/maskers/pointcloud_masker.py"
click node_point_cross "https://github.com/kwikerrr/point2wss/blob/main/src/nets/cross_encoders/pointcloud_cross_encoder.py"
click node_transformer_attention "https://github.com/kwikerrr/point2wss/blob/main/src/nets/transformers/attention.py"
click node_loss "https://github.com/kwikerrr/point2wss/blob/main/src/losses/point2wss_loss.py"
click node_reconstruction_loss "https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/reconstruction.py"
click node_chamfer_loss "https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/chamfer.py"
click node_contrastive_loss "https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/contrastive.py"
click node_cross_contrastive_loss "https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/cross_contrastive.py"
click node_training_module "https://github.com/kwikerrr/point2wss/blob/main/src/models/training_module.py"
click node_train_entry "https://github.com/kwikerrr/point2wss/blob/main/src/train.py"
click node_eval_entry "https://github.com/kwikerrr/point2wss/blob/main/src/eval.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_split_loader,node_data_module,node_synthetic_dataset,node_grid_dataset,node_base_dataset toneBlue
class node_tokenizer,node_sequence_format,node_vocabulary,node_numerical_encoder toneAmber
class node_point2wss,node_parameter_branch,node_parameter_encoder,node_parameter_masker,node_parameter_cross,node_point_branch,node_point_encoder,node_patch_divider,node_geometry,node_point_masker,node_point_cross,node_transformer_attention toneMint
class node_loss,node_reconstruction_loss,node_chamfer_loss,node_contrastive_loss,node_cross_contrastive_loss toneRose
class node_training_module,node_train_entry,node_eval_entry,node_user toneIndigo
```

## Components

### Data preparation

- [Split loader](https://github.com/kwikerrr/point2wss/blob/main/src/datamodules/loaders/txt_loader.py): `src/datamodules/loaders/txt_loader.py`
- [Synthetic data module](https://github.com/kwikerrr/point2wss/blob/main/src/datamodules/synthetic_datamodule.py): `src/datamodules/synthetic_datamodule.py`
- [Synthetic dataset](https://github.com/kwikerrr/point2wss/blob/main/src/datasets/synthetic_dataset.py): `src/datasets/synthetic_dataset.py`
- [Grid dataset](https://github.com/kwikerrr/point2wss/blob/main/src/datasets/grid_synthetic_dataset.py): `src/datasets/grid_synthetic_dataset.py`
- [Dataset preprocessing](https://github.com/kwikerrr/point2wss/blob/main/src/datasets/base_dataset.py): `src/datasets/base_dataset.py`

### Roof representation

- [Multipitch tokenizer](https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/tokenizer.py): `src/tokenization/numerical/tokenizer.py`
- [Sequence grammar](https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/sequence_format.py): `src/tokenization/numerical/sequence_format.py`
- [Token vocabulary](https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/vocabulary.py): `src/tokenization/numerical/vocabulary.py`
- [Numerical encoding](https://github.com/kwikerrr/point2wss/blob/main/src/tokenization/numerical/encoders.py): `src/tokenization/numerical/encoders.py`

### Cross-modal model

- [Point2WSS network](https://github.com/kwikerrr/point2wss/blob/main/src/nets/point2wss.py): `src/nets/point2wss.py`
- [Parameter branch](https://github.com/kwikerrr/point2wss/blob/main/src/nets/branches/params_branch.py): `src/nets/branches/params_branch.py`
- [Parameter encoder](https://github.com/kwikerrr/point2wss/blob/main/src/nets/encoders/params_encoder.py): `src/nets/encoders/params_encoder.py`
- [Parameter masker](https://github.com/kwikerrr/point2wss/blob/main/src/nets/maskers/params_masker.py): `src/nets/maskers/params_masker.py`
- [Parameter cross-encoder](https://github.com/kwikerrr/point2wss/blob/main/src/nets/cross_encoders/param_cross_encoder.py): `src/nets/cross_encoders/param_cross_encoder.py`
- [Point-cloud branch](https://github.com/kwikerrr/point2wss/blob/main/src/nets/branches/pointcloud_branch_mae.py): `src/nets/branches/pointcloud_branch_mae.py`
- [Point-cloud encoder](https://github.com/kwikerrr/point2wss/blob/main/src/nets/encoders/pointcloud_encoder.py): `src/nets/encoders/pointcloud_encoder.py`
- [Patch divider](https://github.com/kwikerrr/point2wss/blob/main/src/nets/pointcloud/patch_divider.py): `src/nets/pointcloud/patch_divider.py`
- [Point-cloud geometry](https://github.com/kwikerrr/point2wss/blob/main/src/nets/pointcloud/geometry.py): `src/nets/pointcloud/geometry.py`
- [Point-cloud masker](https://github.com/kwikerrr/point2wss/blob/main/src/nets/maskers/pointcloud_masker.py): `src/nets/maskers/pointcloud_masker.py`
- [Point-cloud cross-encoder](https://github.com/kwikerrr/point2wss/blob/main/src/nets/cross_encoders/pointcloud_cross_encoder.py): `src/nets/cross_encoders/pointcloud_cross_encoder.py`
- [Attention layers](https://github.com/kwikerrr/point2wss/blob/main/src/nets/transformers/attention.py): `src/nets/transformers/attention.py`

### Training objectives

- [Multimodal losses](https://github.com/kwikerrr/point2wss/blob/main/src/losses/point2wss_loss.py): `src/losses/point2wss_loss.py`
- [Reconstruction loss](https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/reconstruction.py): `src/losses/components/reconstruction.py`
- [Chamfer loss](https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/chamfer.py): `src/losses/components/chamfer.py`
- [Contrastive losses](https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/contrastive.py): `src/losses/components/contrastive.py`
- [Cross-modal alignment](https://github.com/kwikerrr/point2wss/blob/main/src/losses/components/cross_contrastive.py): `src/losses/components/cross_contrastive.py`

### Train and evaluate

- [Lightning training module](https://github.com/kwikerrr/point2wss/blob/main/src/models/training_module.py): `src/models/training_module.py`
- [Training entry point](https://github.com/kwikerrr/point2wss/blob/main/src/train.py): `src/train.py`
- [Evaluation entry point](https://github.com/kwikerrr/point2wss/blob/main/src/eval.py): `src/eval.py`

### Other components

- **Researcher**

## Connections

- Researcher → Training entry point: starts training (evidence: `src/train.py`)
- Training entry point → Multipitch tokenizer: instantiates (evidence: `src/train.py`)
- Training entry point → Synthetic data module: instantiates (evidence: `src/train.py`)
- Training entry point → Lightning training module: instantiates (evidence: `src/train.py`)
- Training entry point → Lightning training module: fits model (evidence: `src/train.py`)
- Synthetic data module → Split loader: loads splits (evidence: `src/datamodules/synthetic_datamodule.py`)
- Synthetic data module → Grid dataset: creates datasets
- Synthetic data module → Synthetic dataset: creates datasets (evidence: `src/datamodules/synthetic_datamodule.py`)
- Grid dataset → Dataset preprocessing: inherits preprocessing (evidence: `src/datasets/grid_synthetic_dataset.py`)
- Synthetic dataset → Dataset preprocessing: uses base class (evidence: `src/datasets/synthetic_dataset.py`)
- Grid dataset → Multipitch tokenizer: tokenizes labels (evidence: `src/datasets/grid_synthetic_dataset.py`)
- Synthetic dataset → Multipitch tokenizer: tokenizes labels (evidence: `src/datasets/synthetic_dataset.py`)
- Multipitch tokenizer → Sequence grammar: uses grammar (evidence: `src/tokenization/numerical/tokenizer.py`)
- Multipitch tokenizer → Token vocabulary: uses token IDs (evidence: `src/tokenization/numerical/tokenizer.py`)
- Sequence grammar → Numerical encoding: uses numeric ranks
- Lightning training module → Point2WSS network: runs network
- Point2WSS network → Parameter branch: dispatches parameters
- Point2WSS network → Point-cloud branch: dispatches point cloud
- Parameter branch → Parameter encoder: encodes tokens
- Parameter branch → Parameter masker: masks tokens
- Parameter branch → Parameter cross-encoder: cross-attends
- Point-cloud branch → Patch divider: forms patches
- Patch divider → Point-cloud geometry: uses sampling (evidence: `src/nets/pointcloud/patch_divider.py`)
- Point-cloud branch → Point-cloud encoder: encodes patches
- Point-cloud branch → Point-cloud masker: masks patches
- Point-cloud branch → Point-cloud cross-encoder: cross-attends
- Parameter cross-encoder → Attention layers: uses attention
- Point-cloud cross-encoder → Attention layers: uses attention
- Lightning training module → Multimodal losses: computes objectives
- Multimodal losses → Reconstruction loss: uses reconstruction
- Multimodal losses → Chamfer loss: uses geometry loss
- Multimodal losses → Contrastive losses: uses alignment
- Multimodal losses → Cross-modal alignment: uses cross alignment
- Researcher → Evaluation entry point: starts evaluation