# googol23/cframe_metrology architecture

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

- Interactive diagram: https://gitdiagram.com/googol23/cframe_metrology
- Repository: https://github.com/googol23/cframe_metrology

## Overview

This package turns laser-tracker/scanner measurements into a detector reference-frame transform, then uses it for per-sensor ladder metrology; an optional branch registers ladders against optically corrected nominal ROOT geometry. The graph emphasizes the documented workflow and the principal runtime stages. Source-index references establish many pipeline dependencies, but excerpts do not expose every call detail, so uncertain subsystem links are omitted.

Main entry points: [`src/detector_alignment/pipeline.py`](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/pipeline.py) (Alignment pipeline), [`src/detector_alignment/registration_stage.py`](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/registration_stage.py) (Registration orchestration), [`src/detector_alignment/ladder.py`](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder.py) (Ladder processing), [`src/detector_alignment/io.py`](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/io.py) (Point-cloud loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Measurement inputs"]
  node_measurements["Survey point clouds"]
  node_config["Workflow configuration<br/>[config.yaml]"]
end

subgraph group_cframe["C-frame alignment"]
  node_fiducials["Fiducial processing<br/>[fiducials.py]"]
  node_plane_fit["Robust plane fit<br/>[plane.py]"]
  node_reference["Reference registration<br/>[reference.py]"]
  node_math["3D transforms<br/>[math3d.py]"]
  node_uncertainty["Uncertainty propagation<br/>[uncertainty.py]"]
end

subgraph group_ladder["Ladder metrology"]
  node_segmentation["Sensor segmentation<br/>[segmentation.py]"]
  node_ladder_process["Ladder processing<br/>[ladder.py]"]
  node_sensor_planes["Sensor plane analysis"]
  node_ladder_viz["Metrology visualization<br/>[ladder_viz.py]"]
end

subgraph group_registration["Nominal registration"]
  node_nominal["Nominal ladder geometry"]
  node_root_geometry["ROOT geometry preparation<br/>[root_geometry.py]"]
  node_optical["Optical metrology preparation"]
  node_registration_stage["Registration orchestration"]
  node_registration_fit["Rigid ladder fit"]
  node_registration_viz["Registration overlays"]
end

subgraph group_shared["Shared runtime"]
  node_cli["Command line<br/>[cli.py]"]
  node_pipeline["Alignment pipeline<br/>[pipeline.py]"]
  node_cloud_io["Point-cloud loading<br/>[io.py]"]
  node_models["Metrology data models<br/>[models.py]"]
end

node_operator(("Metrology operator"))
node_results["Transforms and diagnostics"]

node_operator -->|"runs"| node_cli
node_measurements -->|"provides inputs"| node_pipeline
node_config -->|"configures"| node_pipeline
node_cli -->|"invokes"| node_pipeline
node_pipeline -->|"loads clouds"| node_cloud_io
node_pipeline -->|"processes fiducials"| node_fiducials
node_pipeline -->|"fits C-frame"| node_plane_fit
node_pipeline -->|"registers references"| node_reference
node_plane_fit -->|"uses transforms"| node_math
node_reference -->|"uses registration"| node_math
node_pipeline -->|"propagates uncertainty"| node_uncertainty
node_pipeline -->|"processes ladders"| node_ladder_process
node_ladder_process -->|"loads clouds"| node_cloud_io
node_ladder_process -->|"segments clouds"| node_segmentation
node_pipeline -->|"fits sensor surfaces"| node_sensor_planes
node_pipeline -->|"renders residuals"| node_ladder_viz
node_pipeline -->|"runs optional stage"| node_registration_stage
node_registration_stage -->|"loads ladder clouds"| node_cloud_io
node_registration_stage -->|"prepares geometry"| node_root_geometry
node_root_geometry -->|"builds nominal model"| node_nominal
node_registration_stage -->|"uses geometry"| node_nominal
node_registration_stage -->|"fits rigid correction"| node_registration_fit
node_registration_stage -->|"renders overlays"| node_registration_viz
node_registration_stage -.->|"uses optical corrections"| node_optical
node_pipeline -->|"writes products"| node_results
node_registration_stage -->|"exports diagnostics"| node_results

click node_config "https://github.com/googol23/cframe_metrology/blob/master/examples/config.yaml"
click node_cli "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/cli.py"
click node_pipeline "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/pipeline.py"
click node_cloud_io "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/io.py"
click node_models "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/models.py"
click node_fiducials "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/fiducials.py"
click node_plane_fit "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/plane.py"
click node_reference "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/reference.py"
click node_math "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/math3d.py"
click node_uncertainty "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/uncertainty.py"
click node_segmentation "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/segmentation.py"
click node_ladder_process "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder.py"
click node_sensor_planes "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_metrology.py"
click node_ladder_viz "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_viz.py"
click node_nominal "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/nominal_geometry.py"
click node_root_geometry "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/root_geometry.py"
click node_optical "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_metrology.py"
click node_registration_stage "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/registration_stage.py"
click node_registration_fit "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/labeled_registration.py"
click node_registration_viz "https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/registration_viz.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_measurements,node_config toneBlue
class node_fiducials,node_plane_fit,node_reference,node_math,node_uncertainty toneAmber
class node_segmentation,node_ladder_process,node_sensor_planes,node_ladder_viz toneMint
class node_nominal,node_root_geometry,node_optical,node_registration_stage,node_registration_fit,node_registration_viz toneRose
class node_cli,node_pipeline,node_cloud_io,node_models,node_operator,node_results toneIndigo
```

## Components

### Measurement inputs

- **Survey point clouds**
- [Workflow configuration](https://github.com/googol23/cframe_metrology/blob/master/examples/config.yaml): `examples/config.yaml`

### C-frame alignment

- [Fiducial processing](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/fiducials.py): `src/detector_alignment/fiducials.py`
- [Robust plane fit](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/plane.py): `src/detector_alignment/plane.py`
- [Reference registration](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/reference.py): `src/detector_alignment/reference.py`
- [3D transforms](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/math3d.py): `src/detector_alignment/math3d.py`
- [Uncertainty propagation](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/uncertainty.py): `src/detector_alignment/uncertainty.py`

### Ladder metrology

- [Sensor segmentation](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/segmentation.py): `src/detector_alignment/segmentation.py`
- [Ladder processing](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder.py): `src/detector_alignment/ladder.py`
- [Sensor plane analysis](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_metrology.py): `src/detector_alignment/ladder_metrology.py`
- [Metrology visualization](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_viz.py): `src/detector_alignment/ladder_viz.py`

### Nominal registration

- [Nominal ladder geometry](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/nominal_geometry.py): `src/detector_alignment/nominal_geometry.py`
- [ROOT geometry preparation](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/root_geometry.py): `src/detector_alignment/root_geometry.py`
- [Optical metrology preparation](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/ladder_metrology.py): `src/detector_alignment/ladder_metrology.py`
- [Registration orchestration](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/registration_stage.py): `src/detector_alignment/registration_stage.py`
- [Rigid ladder fit](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/labeled_registration.py): `src/detector_alignment/labeled_registration.py`
- [Registration overlays](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/registration_viz.py): `src/detector_alignment/registration_viz.py`

### Shared runtime

- [Command line](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/cli.py): `src/detector_alignment/cli.py`
- [Alignment pipeline](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/pipeline.py): `src/detector_alignment/pipeline.py`
- [Point-cloud loading](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/io.py): `src/detector_alignment/io.py`
- [Metrology data models](https://github.com/googol23/cframe_metrology/blob/master/src/detector_alignment/models.py): `src/detector_alignment/models.py`

### Other components

- **Metrology operator**
- **Transforms and diagnostics**

## Connections

- Metrology operator → Command line: runs (evidence: `README.md`)
- Survey point clouds → Alignment pipeline: provides inputs (evidence: `README.md`)
- Workflow configuration → Alignment pipeline: configures (evidence: `README.md`)
- Command line → Alignment pipeline: invokes (evidence: `src/detector_alignment/cli.py`)
- Alignment pipeline → Point-cloud loading: loads clouds (evidence: `src/detector_alignment/pipeline.py`)
- Alignment pipeline → Fiducial processing: processes fiducials (evidence: `src/detector_alignment/pipeline.py`)
- Alignment pipeline → Robust plane fit: fits C-frame (evidence: `README.md`)
- Alignment pipeline → Reference registration: registers references (evidence: `README.md`)
- Robust plane fit → 3D transforms: uses transforms (evidence: `src/detector_alignment/plane.py`)
- Reference registration → 3D transforms: uses registration (evidence: `src/detector_alignment/reference.py`)
- Alignment pipeline → Uncertainty propagation: propagates uncertainty (evidence: `src/detector_alignment/pipeline.py`)
- Alignment pipeline → Ladder processing: processes ladders (evidence: `src/detector_alignment/pipeline.py`)
- Ladder processing → Point-cloud loading: loads clouds (evidence: `src/detector_alignment/ladder.py`)
- Ladder processing → Sensor segmentation: segments clouds (evidence: `src/detector_alignment/segmentation.py`)
- Alignment pipeline → Sensor plane analysis: fits sensor surfaces (evidence: `README.md`)
- Alignment pipeline → Metrology visualization: renders residuals (evidence: `src/detector_alignment/pipeline.py`)
- Alignment pipeline → Registration orchestration: runs optional stage (evidence: `src/detector_alignment/pipeline.py`)
- Registration orchestration → Point-cloud loading: loads ladder clouds (evidence: `src/detector_alignment/registration_stage.py`)
- Registration orchestration → ROOT geometry preparation: prepares geometry (evidence: `src/detector_alignment/pipeline.py`)
- ROOT geometry preparation → Nominal ladder geometry: builds nominal model (evidence: `src/detector_alignment/root_geometry.py`)
- Registration orchestration → Nominal ladder geometry: uses geometry (evidence: `src/detector_alignment/registration_stage.py`)
- Registration orchestration → Rigid ladder fit: fits rigid correction (evidence: `src/detector_alignment/registration_stage.py`)
- Registration orchestration → Registration overlays: renders overlays (evidence: `src/detector_alignment/registration_stage.py`)
- Registration orchestration → Optical metrology preparation: uses optical corrections (evidence: `README.md`)
- Alignment pipeline → Transforms and diagnostics: writes products (evidence: `README.md`)
- Registration orchestration → Transforms and diagnostics: exports diagnostics (evidence: `src/detector_alignment/registration_stage.py`)
