# 360-geo/copc-converter architecture

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

- Interactive diagram: https://gitdiagram.com/360-geo/copc-converter
- Repository: https://github.com/360-geo/copc-converter

## Overview

copc_converter converts one or more LAS/LAZ files into COPC point-cloud files, with a typestate pipeline also exposed as a library. The documented workflow scans inputs, validates shared metadata, counts and partitions points, distributes scratch data, builds the octree, and writes the output. The map also includes documented memory budgeting, Extra Bytes/CRS handling, optional temporal indexing, and analysis tools. Stage ordering and tool capabilities come from the README; some internal calls are unsampled, so only indexed or documented relationships are shown.

Main entry points: [`src/lib.rs`](https://github.com/360-geo/copc-converter/blob/master/src/lib.rs) (Typestate pipeline), [`src/writer.rs`](https://github.com/360-geo/copc-converter/blob/master/src/writer.rs) (COPC writer), [`src/main.rs`](https://github.com/360-geo/copc-converter/blob/master/src/main.rs) (CLI entry point), [`src/octree.rs`](https://github.com/360-geo/copc-converter/blob/master/src/octree.rs) (Octree build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversion["Conversion pipeline"]
  node_cli["CLI entry point<br/>[main.rs]"]
  node_pipeline["Typestate pipeline<br/>[lib.rs]"]
  node_scan["Input scan<br/>[octree.rs]"]
  node_validation["Metadata validation<br/>[validate.rs]"]
  node_extras["Extra Bytes handling<br/>[extra_bytes.rs]"]
end

subgraph group_processing["Point processing"]
  node_counting["Chunk planning<br/>[chunking.rs]"]
  node_octree["Octree build<br/>[octree.rs]"]
  node_storage[("Node scratch storage<br/>[node_store.rs]")]
end

subgraph group_format["COPC output"]
  node_copctypes["COPC structures<br/>[copc_types.rs]"]
  node_writer["COPC writer<br/>[writer.rs]"]
end

subgraph group_operations["Runtime controls"]
  node_memory["Memory budgeting<br/>[memory_limit.rs]"]
end

subgraph group_tools["Analysis tools"]
  node_inspect["COPC inspection<br/>[inspect_copc.rs]"]
  node_source["Local/HTTP source<br/>[source.rs]"]
  node_http["HTTP range reader<br/>[http_source.rs]"]
  node_preview["Chunking preview"]
end

node_user(("Converter user"))
node_input["LAS/LAZ inputs"]
node_output["COPC file"]

node_user -->|"runs"| node_cli
node_user -->|"calls"| node_pipeline
node_input -->|"scanned from"| node_scan
node_cli -->|"configures and runs"| node_pipeline
node_pipeline -->|"scans"| node_scan
node_pipeline -->|"validates"| node_validation
node_validation -->|"uses"| node_extras
node_pipeline -->|"counts and plans"| node_counting
node_pipeline -->|"distributes and builds"| node_octree
node_octree -->|"stores node data"| node_storage
node_pipeline -->|"writes"| node_writer
node_writer -->|"uses node hierarchy"| node_octree
node_writer -->|"serializes structures"| node_copctypes
node_writer -->|"produces"| node_output
node_cli -->|"detects limits"| node_memory
node_inspect -->|"reads local or remote"| node_source
node_source -->|"delegates HTTP reads"| node_http
node_preview -->|"analyzes chunks"| node_counting

click node_cli "https://github.com/360-geo/copc-converter/blob/master/src/main.rs"
click node_pipeline "https://github.com/360-geo/copc-converter/blob/master/src/lib.rs"
click node_scan "https://github.com/360-geo/copc-converter/blob/master/src/octree.rs"
click node_validation "https://github.com/360-geo/copc-converter/blob/master/src/validate.rs"
click node_extras "https://github.com/360-geo/copc-converter/blob/master/src/extra_bytes.rs"
click node_counting "https://github.com/360-geo/copc-converter/blob/master/src/chunking.rs"
click node_octree "https://github.com/360-geo/copc-converter/blob/master/src/octree.rs"
click node_storage "https://github.com/360-geo/copc-converter/blob/master/src/node_store.rs"
click node_copctypes "https://github.com/360-geo/copc-converter/blob/master/src/copc_types.rs"
click node_writer "https://github.com/360-geo/copc-converter/blob/master/src/writer.rs"
click node_memory "https://github.com/360-geo/copc-converter/blob/master/src/memory_limit.rs"
click node_inspect "https://github.com/360-geo/copc-converter/blob/master/src/bin/inspect_copc.rs"
click node_source "https://github.com/360-geo/copc-converter/blob/master/src/tools/source.rs"
click node_http "https://github.com/360-geo/copc-converter/blob/master/src/tools/http_source.rs"
click node_preview "https://github.com/360-geo/copc-converter/blob/master/src/bin/preview_chunking.rs"

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_cli,node_pipeline,node_scan,node_validation,node_extras,node_user toneBlue
class node_counting,node_octree,node_storage toneAmber
class node_copctypes,node_writer toneMint
class node_memory toneRose
class node_inspect,node_source,node_http,node_preview,node_input,node_output toneIndigo
```

## Components

### Conversion pipeline

- [CLI entry point](https://github.com/360-geo/copc-converter/blob/master/src/main.rs): `src/main.rs`
- [Typestate pipeline](https://github.com/360-geo/copc-converter/blob/master/src/lib.rs): `src/lib.rs`
- [Input scan](https://github.com/360-geo/copc-converter/blob/master/src/octree.rs): `src/octree.rs`
- [Metadata validation](https://github.com/360-geo/copc-converter/blob/master/src/validate.rs): `src/validate.rs`
- [Extra Bytes handling](https://github.com/360-geo/copc-converter/blob/master/src/extra_bytes.rs): `src/extra_bytes.rs`

### Point processing

- [Chunk planning](https://github.com/360-geo/copc-converter/blob/master/src/chunking.rs): `src/chunking.rs`
- [Octree build](https://github.com/360-geo/copc-converter/blob/master/src/octree.rs): `src/octree.rs`
- [Node scratch storage](https://github.com/360-geo/copc-converter/blob/master/src/node_store.rs): `src/node_store.rs`

### COPC output

- [COPC structures](https://github.com/360-geo/copc-converter/blob/master/src/copc_types.rs): `src/copc_types.rs`
- [COPC writer](https://github.com/360-geo/copc-converter/blob/master/src/writer.rs): `src/writer.rs`

### Runtime controls

- [Memory budgeting](https://github.com/360-geo/copc-converter/blob/master/src/memory_limit.rs): `src/memory_limit.rs`

### Analysis tools

- [COPC inspection](https://github.com/360-geo/copc-converter/blob/master/src/bin/inspect_copc.rs): `src/bin/inspect_copc.rs`
- [Local/HTTP source](https://github.com/360-geo/copc-converter/blob/master/src/tools/source.rs): `src/tools/source.rs`
- [HTTP range reader](https://github.com/360-geo/copc-converter/blob/master/src/tools/http_source.rs): `src/tools/http_source.rs`
- [Chunking preview](https://github.com/360-geo/copc-converter/blob/master/src/bin/preview_chunking.rs): `src/bin/preview_chunking.rs`

### Other components

- **Converter user**
- **LAS/LAZ inputs**
- **COPC file**

## Connections

- Converter user → CLI entry point: runs (evidence: `README.md`)
- Converter user → Typestate pipeline: calls (evidence: `README.md`)
- LAS/LAZ inputs → Input scan: scanned from (evidence: `README.md`)
- CLI entry point → Typestate pipeline: configures and runs (evidence: `src/main.rs`)
- Typestate pipeline → Input scan: scans (evidence: `README.md`)
- Typestate pipeline → Metadata validation: validates (evidence: `README.md`)
- Metadata validation → Extra Bytes handling: uses (evidence: `src/validate.rs`)
- Typestate pipeline → Chunk planning: counts and plans (evidence: `README.md`)
- Typestate pipeline → Octree build: distributes and builds (evidence: `README.md`)
- Octree build → Node scratch storage: stores node data (evidence: `src/octree.rs`)
- Typestate pipeline → COPC writer: writes (evidence: `README.md`)
- COPC writer → Octree build: uses node hierarchy (evidence: `src/writer.rs`)
- COPC writer → COPC structures: serializes structures (evidence: `src/writer.rs`)
- COPC writer → COPC file: produces (evidence: `README.md`)
- CLI entry point → Memory budgeting: detects limits (evidence: `README.md`)
- COPC inspection → Local/HTTP source: reads local or remote (evidence: `README.md`)
- Local/HTTP source → HTTP range reader: delegates HTTP reads (evidence: `src/tools/source.rs`)
- Chunking preview → Chunk planning: analyzes chunks (evidence: `README.md`)