# mfbonfigli/gocesiumtiler architecture

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

- Interactive diagram: https://gitdiagram.com/mfbonfigli/gocesiumtiler
- Repository: https://github.com/mfbonfigli/gocesiumtiler

## Overview

##### Main Components
- CLI Driver: Represented by the “cmd” folder (with main.go/main_test.go) that sets up the entry point and parses CLI flags like “file” and “folder” commands.
- Core Tiling Engine: The “tiler” package is the orchestrator that pulls together file processing, spatial segmentation, mutator applications, and output tiling.
- LAS File Handling: Under “internal/las” there are modules for LAS reading (including test data), geometry extraction (points, intensity, classification) and CRS metadata.
- Coordinate Conversion: Found in “internal/conv” (with submodules for coordinate conversion in “coor” and “proj”) that handle the transformation of input points into the local and global coordinate systems.
- Output Writer Layer: The “internal/writer” package handles conversion into output formats (consumers/producers for Cesium 3D Tiles such as .pnts and glTF assets). This layer also uses the “share” folder for projection and grid data.
- Utilities and Helpers: “internal/utils” provide binary and IO functionalities required across the project.
- Versioning & Build Infrastructure: The “version” directory with version/version.go and build scripts (build.sh, build.ps1, Dockerfile) indicate CI/CD and environment reproducibility.

##### Data Flow
- The tiling engine initiates LAS file reading via the LAS module. Once LAS files are read, points are converted using the coordinate conversion module.
- The conversion results feed into the spatial data structures – the octree/grid implemented in the “internal/tree” – responsible for spatial sampling and level-of-detail generation.
- During point processing, optional “mutators” (e.g., ZOffset and Subsampler, as well as any custom mutators) are applied to modify or filter points.
- Finally, the processed data is handed off to the writer module that emits the final output in Cesium 3D Tiles formats.
- Support files in the “share” folder (such as grid definitions, Proj configuration files, etc.) are referenced during CRS conversion and output construction.

##### Architectural Patterns & Design Principles
- Modular Design: Packages are clearly separated; for instance, file reading, conversion, tree-based spatial manipulation, and tile writing are isolated.
- Plugin/Mutator Pattern: The tiler accepts implementations of the mutator interface, providing extensibility and customization of point processing.
- In-memory Data Processing: The design emphasizes speed by processing data entirely in memory (as highlighted in the README) and using efficient data structures (like a linked tree backed by an array).
- Clear CLI and Library Separation: The project is usable as both a stand-alone command-line tool and as a Go library, making the architecture flexible.

##### Technologies and External Dependencies
- Go language core and modules (go.mod, go.sum).
- Proj 9.5.0 (for coordinate conversion) and its grid data (located in the “share” folder).
- Utilization of goroutines (to process data concurrently) based on README notes regarding multi-core usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        A["CLI Driver (cmd)"]:::cli
        B["LAS File Handling (internal/las)"]:::las
    end

    subgraph "Processing Layer"
        C["Core Tiling Engine (tiler)"]:::engine
        D["Coordinate Conversion (internal/conv)"]:::conv
        E["Spatial & Geometric Processing (internal/tree, internal/geom)"]:::spatial
        F["Custom Mutators"]:::mutators
    end

    subgraph "Output Layer"
        G["Tile Writer (internal/writer)"]:::writer
    end

    subgraph "Support & Utilities"
        H["Utilities & Helpers (internal/utils)"]:::utils
        I["Configuration & Grid Data (share)"]:::config
        J["Versioning & Build Infrastructure"]:::version
    end

    %% Data Flow
    A -->|"triggers"| C
    C -->|"reads from"| B
    C -->|"invokes"| D
    B -->|"raw data"| E
    D -->|"converted data"| E
    E -->|"outputs LOD data"| G
    E -->|"applies"| F
    F -->|"mutated data"| G
    I -.->|"provides config"| D
    I -.->|"supplies grid"| G
    H -.-> C
    H -.-> D
    J -.->|"build info"| C
    C -->|"concurrency via goroutines"| C

    %% Click Events
    click A "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/cmd/main.go"
    click A "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/cmd/main_test.go"
    click C "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/tiler/tiler.go"
    click C "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/tiler/tiler_test.go"
    click B "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/las/reader.go"
    click B "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/las/reader_test.go"
    click B "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/las/golas/reader.go"
    click E "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/geom/bbox.go"
    click E "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/geom/point.go"
    click E "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/tree/tree.go"
    click E "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/tree/grid/tree.go"
    click D "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/conv/coor/conv.go"
    click D "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/conv/coor/proj/proj.go"
    click G "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/writer/writer.go"
    click G "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/writer/pnts.go"
    click G "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/writer/gltf.go"
    click H "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/utils/binary.go"
    click H "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/internal/utils/io.go"
    click J "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/version/version.go"
    click J "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/build.sh"
    click J "https://github.com/mfbonfigli/gocesiumtiler/blob/v2/build.ps1"
    click J "https://github.com/mfbonfigli/gocesiumtiler/tree/v2/Dockerfile"
    click I "https://github.com/mfbonfigli/gocesiumtiler/tree/v2/share"

    %% Styles
    classDef cli fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
    classDef engine fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef las fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef conv fill:#81D4FA,stroke:#01579B,stroke-width:2px;
    classDef spatial fill:#DCEDC8,stroke:#33691E,stroke-width:2px;
    classDef mutators fill:#F0F4C3,stroke:#827717,stroke-width:2px;
    classDef writer fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef utils fill:#F5F5F5,stroke:#616161,stroke-width:2px;
    classDef version fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
    classDef config fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
```
