### Point Tiler CLI Example Usage

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

An example demonstrating how to use the Point Tiler CLI with various compression and configuration options.

```bash
ptiler --input data/*.las \
       --output output/ \
       --input-epsg 6677 \
       --output-epsg 4979 \
       --min 15 --max 18 \
       --max-memory-mb 8192 \
       --threads 8 \
       --quantize --meshopt
```

--------------------------------

### Example Point Tiler Usage

Source: https://github.com/mierune/point-tiler/blob/main/README.md

This example demonstrates how to use the point-tiler CLI with various options for input and output files, coordinate systems, zoom levels, memory, threads, and compression settings.

```sh
ptiler --input app/examples/data/sample.las \
    --output app/examples/data/output \
    --input-epsg 6677 \
    --output-epsg 4979 \
    --min 15 \
    --max 18 \
    --max-memory-mb 8192 \
    --threads 8 \
    --quantize \
    --meshopt \
    --gzip-compress
```

--------------------------------

### Install Point Tiler CLI

Source: https://github.com/mierune/point-tiler/blob/main/README.md

Use this command to install the point-tiler CLI tool. Ensure you have curl installed. This installation is not supported on Windows.

```sh
curl -sSf https://raw.githubusercontent.com/MIERUNE/point-tiler/main/install.sh | bash
```

--------------------------------

### Creating a LasPointReader Instance

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Example of how to instantiate a `LasPointReader` with a vector of file paths.

```rust
let files = vec![PathBuf::from("data.las")];
let reader = LasPointReader::new(files)?;
```

--------------------------------

### Example Usage of Point::set

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-core.md

Demonstrates how to initialize a Point struct and update its properties using the `set` method.

```rust
let mut point = Point { x: 0.0, y: 0.0, z: 0.0, color: Color::default(), attributes: PointAttributes::default() };
point.set(10.5, 20.3, 15.7, 65535, 32768, 0);
```

--------------------------------

### ProjError Recovery Example

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/errors.md

Demonstrates how to handle ProjError during the setup of a coordinate transformer. It shows matching on the Result type and printing detailed error information.

```rust
match PointTransformer::new(input_epsg, output_epsg, None) {
    Ok(transformer) => {
        // Use transformer
    }
    Err(proj_error) => {
        eprintln!("Transformation setup failed: {}", proj_error);
        eprintln!("Error code: {}", proj_error.code);
        eprintln!("Context: {}", proj_error.context);
        // Handle error (abort, fallback CRS, etc.)
    }
}
```

--------------------------------

### CSV Data Example

Source: https://github.com/mierune/point-tiler/blob/main/README.md

This is an example of a valid CSV input file. Only XYZ and RGB columns are used; other attributes are ignored. Column names are case-insensitive.

```csv
"X","Y","Z","Intensity","ReturnNumber","NumberOfReturns","ScanDirectionFlag","EdgeOfFlightLine","Classification","Synthetic","KeyPoint","Withheld","Overlap","ScanAngleRank","UserData","PointSourceId","GpsTime","Red","Green","Blue"
-5599.971,-35106.097,3.602,680.000,1.000,1.000,1.000,0.000,1.000,0.000,0.00 0,0.000,0.000,-4.000,0.000,95.000,188552.207,19532.000,20046.000,20560.000
-5599.976,-35111.458,3.440,715.000,1.000,1.000,1.000,0.000,1.000,0.000,0.00 0,0.000,0.000,-4.000,0.000,95.000,188552.287,20560.000,21074.000,21588.000
-5599.978,-35115.695,3.543,311.000,1.000,1.000,1.000,0.000,1.000,0.000,0.00 0,0.000,0.000,-4.000,0.000,95.000,188552.347,19018.000,19275.000,20303.000
-5599.992,-35119.757,3.603,722.000,1.000,1.000,1.000,0.000,1.000,0.000,0.00 0,0.000,0.000,-4.000,0.000,95.000,188552.407,18504.000,20046.000,20817.000
-5599.992,-35129.327,3.431,505.000,1.000,1.000,1.000,0.000,1.000,0.000,0.00 0,0.000,0.000,-4.000,0.000,95.000,188552.547,18504.000,19789.000,21074.000
```

--------------------------------

### Example: Accessing Tile Content Information (Rust)

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Demonstrates how to use `make_tile_content` to obtain tile metadata and print its content path and longitude bounds.

```rust
let content = make_tile_content(&(18, 1234, 5678), &tile_cloud);
println!("Content at: {}", content.content_path);
println!("Bounds: ({}, {})", content.min_lng, content.max_lng);
```

--------------------------------

### Example Usage of PointIterator

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Demonstrates how to create and use a PointIterator to process points in chunks. Ensure a valid PointReader is provided.

```rust
let reader = LasPointReader::new(vec![PathBuf::from("data.las")])?;
let iter = PointIterator::new(reader, 10000);
for chunk in iter {
    println!("Processing {} points", chunk.len());
}
```

--------------------------------

### Example Usage of CsvPointReader

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Demonstrates creating a CsvPointReader with a list of file paths. The reader will automatically handle header detection and mapping.

```rust
let files = vec![PathBuf::from("data.csv")];
let reader = CsvPointReader::new(files)?;
```

--------------------------------

### Example: Processing Tiled Point Clouds (Rust)

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Iterates through tiles generated by `pointcloud_to_tiles`, printing the tile coordinates and the number of points within each tile.

```rust
let tiles = pointcloud_to_tiles(&cloud, 15, 18);
for ((z, x, y), tile_cloud) in tiles {
    println!("Tile {}/ப்புகளை/{}/{} has {} points", z, x, y, tile_cloud.points.len());
}
```

--------------------------------

### Example Usage of Point::to_rgb8_normalized

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-core.md

Demonstrates calling the `to_rgb8_normalized` method and printing the gamma-corrected 8-bit RGB values.

```rust
let rgb_normalized = point.to_rgb8_normalized();
println!("Normalized RGB: {}, {}, {}", rgb_normalized[0], rgb_normalized[1], rgb_normalized[2]);
```

--------------------------------

### Example Usage of Point::to_rgb8

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-core.md

Shows how to call the `to_rgb8` method on a Point object and print the resulting 8-bit RGB values.

```rust
let rgb = point.to_rgb8();
println!("RGB: {}, {}, {}", rgb[0], rgb[1], rgb[2]);
```

--------------------------------

### Load 3D Tileset in Cesium.js

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Example of how to load a 3D Tileset into a Cesium.js viewer. Ensure Cesium.js is included and the tileset JSON is accessible.

```html
<script src="https://cesium.com/downloads/cesiumjs/releases/1.104/Cesium.js"></script>
<div id="cesiumContainer"></div>
<script>
    const viewer = new Cesium.Viewer('cesiumContainer');
    Cesium.Cesium3DTileset.fromUrl('/output/tileset.json')
        .then(tileset => viewer.scene.primitives.add(tileset));
</script>
```

--------------------------------

### Use EPSG_WGS84_GEOGRAPHIC_3D constant

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Example of initializing a PointTransformer with WGS84 Geographic 3D as the output CRS.

```rust
let transformer = PointTransformer::new(6677, EPSG_WGS84_GEOGRAPHIC_3D, None)?;
```

--------------------------------

### Build Point Tiler from Source

Source: https://github.com/mierune/point-tiler/blob/main/README.md

For developers, after installing Rust and Cargo, clone the repository and build the project. This method allows for local development and testing.

```sh
git clone https://github.com/MIERUNE/point-tiler.git
cd point-tiler
cargo build --release
```

--------------------------------

### Reading a GLB File

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Provides an example of how to read a GLB file in Rust, parse its JSON content, and access the binary data.

```APIDOC
### Reading a GLB

```rust
use std::fs::File;

let file = File::open("input.glb")?;
let glb = Glb::from_reader(file)?;

// Parse JSON
let json: serde_json::Value = serde_json::from_slice(&glb.json)?;
println!("Asset: {:?}", json["asset"]);

// Access binary
if let Some(bin) = &glb.bin {
    println!("Binary size: {} bytes", bin.len());
}
```
```

--------------------------------

### Basic PointTransformer Usage Example

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

A common usage pattern for the PointTransformer, showing initialization, reading points from a file, and transforming them in-place. Ensure you have the necessary input file and PROJ data configured.

```rust
// Create transformer
let mut transformer = PointTransformer::new(
    6677,  // Japan Plane Rectangular CS Zone 1
    4979,  // WGS84 Geographic 3D
    None,  // Use default PROJ data
)?;

// Read points from input file
let mut points = read_las_file("input.las")?;

// Transform all points in-place
transformer.transform_points_in_place(&mut points)?;

// Points are now in WGS84 geographic coordinates
println!("First point: {:?}", points[0]);
```

--------------------------------

### Example CSV Data for Point Tiler

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

This example demonstrates the required 'x', 'y', 'z' columns and optional 'red', 'green', 'blue' color columns in a CSV file. The color values can range from 0-65535 or 0-255.

```csv
x,y,z,red,green,blue
10.5,20.3,15.7,255,128,64
10.6,20.4,15.8,200,100,50
```

--------------------------------

### Example Calculation: In-Memory Eligible

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Illustrates a scenario where the estimated processing size with headroom exceeds the specified max_memory_mb, leading to the use of the external sort workflow.

```pseudocode
Input: 1 GB file with 100M points
Estimated size: 100M × 80 bytes ≈ 8 GB
Total with headroom: 8 GB × 5 = 40 GB
max_memory_mb: 8192 (8 GB) — INSUFFICIENT, uses external sort
```

--------------------------------

### GLB File Structure

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Explains the binary layout of a GLB file, including the GLB header and the structure of JSON and BIN chunks, along with their respective padding rules and example sizes.

```APIDOC
## GLB File Structure

### Binary Layout

```
[12 bytes] GLB Header
    [4] Magic ("glTF")
    [4] Version (2)
    [4] Total file size

[8 bytes] JSON Chunk Header
    [4] JSON chunk size (with padding)
    [4] Chunk type ("JSON")
[N bytes] JSON content (UTF-8 text)
[M bytes] JSON padding (0x20 spaces)

[8 bytes] BIN Chunk Header (optional)
    [4] BIN chunk size (with padding)
    [4] Chunk type ("BIN\0")
[K bytes] Binary data
[P bytes] BIN padding (0x00 nulls)
```

### Padding Rules

- JSON chunk: Padded with space (0x20) to alignment boundary
- BIN chunk: Padded with null (0x00) to alignment boundary
- Alignment is specified at write time (default 4 bytes)

### Example Sizes

**JSON-only GLB:**
```
Header: 12 bytes
JSON header: 8 bytes
JSON content: 256 bytes
JSON padding: 0 bytes (already aligned)
Total: 276 bytes
```

**GLB with binary data:**
```
Header: 12 bytes
JSON header: 8 bytes + 1024 bytes content + 0 padding = 1032 bytes
BIN header: 8 bytes
BIN data: 1024 bytes
BIN padding: 0 bytes (already aligned)
Total: 1044 + 1032 = 2076 bytes
```
```

--------------------------------

### Example Calculation: External Sort Required

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Illustrates a scenario where the estimated processing size with headroom is borderline or within the specified max_memory_mb, potentially allowing the use of the in-memory workflow.

```pseudocode
Input: 100 MB file with 10M points
Estimated size: 10M × 80 bytes ≈ 800 MB
Total with headroom: 800 MB × 5 = 4 GB
max_memory_mb: 4096 (4 GB) — BORDERLINE, uses in-memory
```

--------------------------------

### Handle ProjError in Rust

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Example of matching a Result for potential ProjError during PointTransformer initialization.

```rust
match PointTransformer::new(9999, 4979, None) {
    Err(e) => eprintln!("Error: {}", e),
    Ok(transformer) => { /* use transformer */ }
}
```

--------------------------------

### Example CSV Data Format

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Illustrates the expected format for CSV files read by CsvPointReader, including required 'x', 'y', 'z' columns and optional color columns.

```csv
x,y,z,red,green,blue
10.5,20.3,15.7,255,128,64
```

--------------------------------

### Voxel Size Example at Zoom 15

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Demonstrates the calculation of voxel size at zoom level 15, where geometric error is 64.0 m.

```pseudocode
At zoom 15: voxel_size = 64.0 × 0.1 = 6.4 m
```

--------------------------------

### Example usage of EpsgCode type alias

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Demonstrates assigning values to variables of type EpsgCode for input and output coordinate reference systems.

```rust
let input_epsg: EpsgCode = 6677;  // Japan Plane Rectangular CS
let output_epsg: EpsgCode = 4979; // WGS84 Geographic 3D
```

--------------------------------

### Voxel Size Example at Zoom 18

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Demonstrates the calculation of voxel size at zoom level 18, where geometric error is 1.0 m.

```pseudocode
At zoom 18: voxel_size = 1.0 × 0.1 = 0.1 m
```

--------------------------------

### Validate GLB Chunk from Reader

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

This example demonstrates how to read a GLB file using `Glb::from_reader` and validate its JSON and BIN chunk sizes. It includes error handling for invalid data and general read errors. Use this to verify the integrity of generated or existing GLB files.

```rust
match Glb::from_reader(file) {
    Ok(glb) => {
        println!("JSON: {} bytes", glb.json.len());
        if let Some(bin) = &glb.bin {
            println!("BIN: {} bytes", bin.len());
        }
    }
    Err(e) if e.kind() == io::ErrorKind::InvalidData => {
        eprintln!("Invalid GLB format: {}", e);
    }
    Err(e) => eprintln!("Read error: {}", e),
}
```

--------------------------------

### Estimating LAS File Processing Size

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Demonstrates how to use `estimate_processing_size` to get an estimate of the memory needed for a given LAS file.

```rust
let size = LasPointReader::estimate_processing_size(&PathBuf::from("data.las"));
println!("Estimated size: {} bytes", size);
```

--------------------------------

### CLI Arguments to GLB Options Propagation

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/architecture.md

Illustrates the flow of configuration options from command-line interface arguments through internal structures to the final GLB generation process. This demonstrates how options like quantization and meshopt are passed down.

```text
ptiler --quantize --meshopt
    ↓
Cli { quantize: true, meshopt: true, ... }
    ↓
GlbOptions { quantize: true, meshopt: true, ... }
    ↓
generate_glb_with_options() uses options
    ↓
Output GLB with both extensions
```

--------------------------------

### Writing a GLB File

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Demonstrates how to create and write a GLB file using Rust, including preparing JSON and binary data and utilizing the `Glb` struct.

```APIDOC
## Usage Patterns

### Writing a GLB

```rust
use std::fs::File;
use std::io::BufWriter;
use serde_json::json;

// Create JSON and binary data
let json_doc = json!({
    "asset": { "version": "2.0" },
    "scenes": [{ "nodes": [0] }],
    "nodes": [{}],
    "meshes": [],
});
let json_bytes = serde_json::to_vec(&json_doc)?;
let bin_data = vec![1u8, 2, 3, 4];

// Create and write GLB
let glb = Glb {
    json: json_bytes.into(),
    bin: Some(bin_data.into()),
};
let mut file = BufWriter::new(File::create("output.glb")?);
gl.to_writer(&mut file)?;
```
```

--------------------------------

### PointTransformer Initialization with Custom PROJ Data Directory

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Demonstrates how to initialize the PointTransformer with a custom directory for PROJ data files, ensuring network access is managed and grid files are cached appropriately.

```APIDOC
## PointTransformer::new(custom_proj_dir)

### Description
Initializes a new PointTransformer instance, optionally specifying a custom directory for PROJ data. This allows for network-independent operations and custom data configurations.

### Method
`PointTransformer::new(source_epsg, target_epsg, custom_proj_dir)`

### Parameters
- **source_epsg** (integer) - Required - The EPSG code for the source coordinate system.
- **target_epsg** (integer) - Required - The EPSG code for the target coordinate system.
- **custom_proj_dir** (Option<&Path>) - Optional - A path to a custom directory containing PROJ data files. If `None`, the default PROJ data location is used.

### Request Example
```rust
use std::path::Path;

let proj_dir = Path::new("/custom/proj/data");
let transformer = PointTransformer::new(6677, 4979, Some(proj_dir))?;
```
```

--------------------------------

### Writing a GLB File

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Demonstrates how to create and write a GLB file with JSON and optional binary data using the `Glb` struct. Ensure `serde_json` is in scope for JSON serialization.

```rust
use std::fs::File;
use std::io::BufWriter;
use serde_json::json;

// Create JSON and binary data
let json_doc = json!({
    "asset": { "version": "2.0" },
    "scenes": [{ "nodes": [0] }],
    "nodes": [{}],
    "meshes": [],
});
let json_bytes = serde_json::to_vec(&json_doc)?;
let bin_data = vec![1u8, 2, 3, 4];

// Create and write GLB
let glb = Glb {
    json: json_bytes.into(),
    bin: Some(bin_data.into()),
};
let mut file = BufWriter::new(File::create("output.glb")?);
glb.to_writer(&mut file)?;
```

--------------------------------

### Main Application Entry Point

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/app-cli.md

The main function orchestrates the Point Tiler application flow. It parses arguments, initializes logging, expands glob patterns, validates file extensions, estimates memory requirements, and selects the appropriate processing workflow (in-memory or external sort).

```rust
fn main() {
    // 1. Parse arguments
    let cli = Cli::parse();
    
    // 2. Initialize logging
    Builder::new()
        .filter_level(LevelFilter::Info)
        .init();
    
    // 3. Expand glob patterns
    let input_paths = expand_globs(cli.input);
    
    // 4. Validate file extensions
    let extension = check_and_get_extension(&input_paths)?;
    
    // 5. Estimate memory
    let processing_size = estimate_processing_size(&input_paths);
    
    // 6. Select workflow
    if should_use_in_memory(processing_size, cli.max_memory_mb) {
        run_in_memory_workflow(/*...*/)?
    } else {
        run_external_sort_workflow(/*...*/)?
    }
}
```

--------------------------------

### Get Extension Function

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Converts a string representation of a file extension into the corresponding Extension enum variant. Panics if the extension is not supported.

```rust
pub fn get_extension(extension: &str) -> Extension
```

```rust
let ext = get_extension("las");
// Returns Extension::Las
```

--------------------------------

### Maximum compression for web

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Command to achieve maximum compression for web deployment using quantization, mesh optimization, and gzip compression. Suitable for reducing file sizes for online use.

```bash
ptiler --input data.las \
       --output output/ \
       --input-epsg 6677 \
       --output-epsg 4979 \
       --quantize --meshopt --gzip-compress
```

--------------------------------

### GlbOptions

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Configuration options for GLB generation, including quantization, meshopt compression, and gzip compression.

```APIDOC
## GlbOptions

Configuration options for GLB generation.

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `quantize` | `bool` | `false` | Enable KHR_mesh_quantization extension (16-bit positions) |
| `meshopt` | `bool` | `false` | Enable EXT_meshopt_compression for vertex data |
| `gzip_compress` | `bool` | `false` | Enable GZIP compression on output files |

**Example:**
```rust
let options = GlbOptions {
    quantize: true,
    meshopt: true,
    gzip_compress: false,
};
```
```

--------------------------------

### GLB I/O Methods

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Provides methods for reading from and writing to GLB files, with options for custom alignment.

```APIDOC
## Glb Structure

```rust
pub struct Glb<'a> {
    pub json: Cow<'a, [u8]>,
    pub bin: Option<Cow<'a, [u8]>>,
}
```

## Methods

### `to_writer`

Writes GLB with default 4-byte alignment.

#### Signature

```rust
pub fn to_writer<W: std::io::Write>(&self, writer: W) -> std::io::Result<()>
```

#### Example

```rust
let mut file = File::create("output.glb")?;
gl.to_writer(&mut file)?;
```

### `to_writer_with_alignment`

Writes GLB with specified chunk alignment.

#### Signature

```rust
pub fn to_writer_with_alignment<W: std::io::Write>(
    &self,
    writer: W,
    alignment: usize,
) -> std::io::Result<()>
```

#### Parameters

- **writer** (`W`): Output writer
- **alignment** (`usize`): Byte alignment (typically 4 or 8)

### `from_reader`

Reads and parses a GLB file.

#### Signature

```rust
pub fn from_reader<R: std::io::Read>(reader: R) -> std::io::Result<Self>
```

#### Returns

`io::Result<Glb>` - Parsed GLB

#### Example

```rust
let file = File::open("input.glb")?;
let glb = Glb::from_reader(file)?;
```
```

--------------------------------

### High-Performance Point Tiler Settings

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Optimizes point tiling for high performance by allocating more memory and threads. Enables quantization and mesh optimization for efficient output.

```bash
ptiler --input *.las \
    --output output/ \
    --input-epsg 6677 \
    --output-epsg 4979 \
    --min 15 --max 18 \
    --max-memory-mb 8192 \
    --threads 8 \
    --quantize \
    --meshopt
```

--------------------------------

### Check and Get File Extension

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/app-cli.md

Validates that all provided file paths share a consistent and recognized extension (las, laz, csv, txt). Rejects files with mixed or unsupported extensions.

```rust
fn check_and_get_extension(paths: &[PathBuf]) -> Result<Extension, String>
```

```rust
let ext = check_and_get_extension(&paths)?;
// Ok(Extension::Las) if all files are .las
// Err("Multiple extensions are not supported") if mixed
```

--------------------------------

### Point Tiler Project Structure

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/architecture.md

Illustrates the modular crate-based structure of the Point Tiler application, highlighting the role of each component.

```text
point-tiler/
├── app/                       # CLI binary - orchestration
├── pcd-core/                  # Core data structures
├── pcd-parser/                # File format readers
├── pcd-exporter/              # Tiling and 3D Tiles export
├── coordinate-transformer/    # PROJ-based coordinate conversion
└── cesiumtiles-gltf/
    └── cesiumtiles-gltf-json/ # glTF JSON type definitions
```

--------------------------------

### Create New PointCloud

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-core.md

Creates a new PointCloud instance. Automatically calculates bounding volume and metadata.

```rust
let points = vec![
    Point { x: 0.0, y: 0.0, z: 0.0, color: Color::default(), attributes: PointAttributes::default() },
    Point { x: 10.0, y: 10.0, z: 10.0, color: Color::default(), attributes: PointAttributes::default() },
];
let cloud = PointCloud::new(points, 4979);
```

--------------------------------

### Initialize Transformer with Custom PROJ Data Directory

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Demonstrates how to initialize the PointTransformer with a custom directory for PROJ data files. This is useful for managing PROJ resources outside the default location.

```rust
let proj_dir = Path::new("/custom/proj/data");
let transformer = PointTransformer::new(6677, 4979, Some(proj_dir))?;
```

--------------------------------

### TileZXY Type Alias

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Defines the TileZXY type alias for tile coordinates as a tuple of (zoom, x, y). This is re-exported from the tinymvt crate. Example: (18, 1234, 5678) represents zoom 18 tile at column 1234, row 5678.

```rust
type TileZXY = (u8, u32, u32);
```

--------------------------------

### Handling Transformation Errors in Rust

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/errors.md

Example of how to handle potential errors during point transformation using Rust's Result type. This snippet shows how to match on Ok and Err variants to process successful transformations or report detailed error information.

```rust
// Example: Handle transformation error
match transformer.transform_points_in_place(&mut points) {
    Ok(_) => println!("Transformation complete"),
    Err(e) => {
        eprintln!("Transformation failed: {} (code {})", e.message, e.code);
        eprintln!("Context: {}", e.context);
        // Fallback or abort
    }
}
```

--------------------------------

### Zero-Copy Writing (Borrowed Data)

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Illustrates how to perform zero-copy writing of GLB files in Rust by referencing existing data buffers, avoiding unnecessary allocations and copies.

```APIDOC
### Zero-Copy Writing (Borrowed Data)

```rust
let glb = Glb {
    json: &json_bytes[..].into(),
    bin: Some(&bin_data[..].into()),
};
gl.to_writer(&mut file)?;
// No allocation or copy; references borrowed from existing buffers
```
```

--------------------------------

### Zero-Copy GLB Writing

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Demonstrates writing a GLB file using borrowed data slices for JSON and binary content, avoiding allocations and copies. This is useful when data already exists in memory.

```rust
let glb = Glb {
    json: &json_bytes[..].into(),
    bin: Some(&bin_data[..].into()),
};
gl.to_writer(&mut file)?;
// No allocation or copy; references borrowed from existing buffers
```

--------------------------------

### PointCloud::new

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-core.md

Creates a new PointCloud instance. It automatically computes bounding volumes and metadata based on the provided points and EPSG code.

```APIDOC
## PointCloud::new

### Description
Creates a new PointCloud and calculates bounding volume and metadata automatically.

### Signature
```rust
pub fn new(points: Vec<Point>, epsg: EpsgCode) -> Self
```

### Parameters
#### Path Parameters
- **points** (Vec<Point>) - Required - Vector of points
- **epsg** (EpsgCode) - Required - EPSG code for coordinate system

### Returns
- **PointCloud** - New point cloud with computed metadata

### Example
```rust
let points = vec![
    Point { x: 0.0, y: 0.0, z: 0.0, color: Color::default(), attributes: PointAttributes::default() },
    Point { x: 10.0, y: 10.0, z: 10.0, color: Color::default(), attributes: PointAttributes::default() },
];
let cloud = PointCloud::new(points, 4979);
```
```

--------------------------------

### Convert CLI Args to GlbOptions

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/app-cli.md

CLI arguments are transformed into a GlbOptions struct for use in the GLB generation process. This struct is then passed to the `generate_glb_with_options` function.

```rust
let glb_options = GlbOptions {
    quantize: cli.quantize,
    meshopt: cli.meshopt,
    gzip_compress: cli.gzip_compress,
};
```

--------------------------------

### Point Tiler CLI Optional Arguments

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Lists optional arguments for configuring Point Tiler, such as zoom levels, memory limits, threads, and compression settings.

```bash
       --min <ZOOM>              # Default: 15
       --max <ZOOM>              # Default: 18
       --max-memory-mb <N>       # Default: 4096
       --threads <N>             # Default: auto-detect
       --quantize                # Enable quantization
       --meshopt                 # Enable meshopt compression
       --gzip-compress           # Enable GZIP
       --disable-decimation      # Keep all points
```

--------------------------------

### Generate GLB with Options

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Generate a GLB file from point cloud data using specified options. This function handles the conversion and allows for custom compression and encoding settings.

```rust
pub fn generate_glb_with_options(
    points: PointCloud,
    options: &GlbOptions,
) -> Result<cesiumtiles_gltf::glb::Glb<'a>, Box<dyn Error>>
```

```rust
let glb = generate_glb_with_options(point_cloud, &GlbOptions::default())?;
let mut file = File::create("output.glb")?;
gl.to_writer(&mut file)?;
```

--------------------------------

### Generate Tile Content Metadata (Rust)

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Creates metadata for a specific tile, including its content path and bounding box, from a given point cloud. The path follows the format {zoom}/{x}/{y}.glb.

```rust
pub fn make_tile_content(tile_coord: &TileZXY, point_cloud: &PointCloud) -> TileContent
```

--------------------------------

### GLB Export Options

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/types.md

Configuration struct for generating GLB files, controlling quantization, meshopt compression, and gzip compression. Used by GLB generation functions.

```rust
pub struct GlbOptions {
    pub quantize: bool,
    pub meshopt: bool,
    pub gzip_compress: bool,
}
```

--------------------------------

### Set Memory Budget via CLI

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/app-cli.md

Specify the maximum memory in megabytes to be used by the tool. This influences workflow selection, particularly for in-memory versus external sorting.

```bash
ptiler --max-memory-mb 8192 ...
```

--------------------------------

### into_tileset_root Method

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Converts the entire TileTree into the Cesium 3D Tileset format.

```APIDOC
## into_tileset_root

### Description
Converts the tile tree into a Cesium 3D Tileset format.

### Returns
`tileset::Tile` - Root tile in 3D Tileset JSON format

### Conversion Details:
- Recursively updates bounding volumes up the tree
- Converts child relationships to 3D Tileset hierarchy
- Adds geometric error based on zoom level and latitude
- Applies region bounding volumes (WGS84 longitude/latitude/height)
```

--------------------------------

### Reading a GLB File

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/cesiumtiles-gltf.md

Shows how to read a GLB file from a reader and access its JSON and binary data. The JSON content can be parsed into a `serde_json::Value`.

```rust
use std::fs::File;

let file = File::open("input.glb")?;
let glb = Glb::from_reader(file)?;

// Parse JSON
let json: serde_json::Value = serde_json::from_slice(&glb.json)?;
println!("Asset: {:?}", json["asset"]);

// Access binary
if let Some(bin) = &glb.bin {
    println!("Binary size: {} bytes", bin.len());
}
```

--------------------------------

### Maximum Compression Point Tiler Settings

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/configuration.md

Applies maximum compression to the output tiles. Uses quantization, mesh optimization, and gzip compression for smaller file sizes.

```bash
ptiler --input data.las \
    --output output/ \
    --input-epsg 6677 \
    --output-epsg 4979 \
    --quantize \
    --meshopt \
    --gzip-compress
```

--------------------------------

### generate_glb_with_options

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Generates a GLB file from point cloud data with specified options for compression and encoding.

```APIDOC
## generate_glb_with_options

Generates a GLB file from point cloud data with specified options.

### Method

`generate_glb_with_options(points: PointCloud, options: &GlbOptions) -> Result<cesiumtiles_gltf::glb::Glb<'a>, Box<dyn Error>>`

### Parameters

#### Path Parameters

* None

#### Query Parameters

* None

#### Request Body

* None

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `points` | `PointCloud` | Point cloud to convert |
| `options` | `&GlbOptions` | Compression and encoding options |

**Returns:** `Result<Glb, Box<dyn Error>>` - Binary glTF data

**Encoding Details:**
- **Unquantized:** F32 positions (12 bytes per vertex) + RGB8 color (3 bytes) + padding (1 byte) = 16 bytes/vertex
- **Quantized:** U16 positions (6 bytes) + padding (2 bytes) + RGB8 color (3 bytes) + padding (1 byte) = 12 bytes/vertex
- **Meshopt:** Uses 2-buffer layout with compressed data in Buffer 0 and fallback in Buffer 1

**Example:**
```rust
let glb = generate_glb_with_options(point_cloud, &GlbOptions::default())?;
let mut file = File::create("output.glb")?;
gl.to_writer(&mut file)?;
```
```

--------------------------------

### PointTransformer Transformation Usage

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Illustrates the typical usage pattern for the PointTransformer, including initialization, reading input data, and performing in-place transformation of points.

```APIDOC
## PointTransformer::transform_points_in_place

### Description
Transforms a mutable slice of points in-place from the source coordinate system to the target coordinate system defined during the transformer's initialization. This method is efficient as it avoids creating new data structures.

### Method
`transformer.transform_points_in_place(&mut points)`

### Parameters
- **points** (&mut [Point]) - Required - A mutable slice of points to be transformed. The points will be modified directly.

### Usage Example
```rust
// Create transformer
let mut transformer = PointTransformer::new(
    6677,  // Japan Plane Rectangular CS Zone 1
    4979,  // WGS84 Geographic 3D
    None,  // Use default PROJ data
)?;

// Read points from input file (assuming read_las_file is defined elsewhere)
let mut points = read_las_file("input.las")?;

// Transform all points in-place
transformer.transform_points_in_place(&mut points)?;

// Points are now in WGS84 geographic coordinates
println!("First point: {:?}", points[0]);
```
```

--------------------------------

### Run Point Tiler CLI

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/endpoints.md

Invoke the Point Tiler application from the command line with input and output parameters, including EPSG codes for coordinate system transformation.

```bash
ptiler --input data.las --output output/ --input-epsg 6677 --output-epsg 4979
```

--------------------------------

### LasPointReader::new Constructor

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Creates a new LAS reader instance, initializing it with a list of file paths.

```rust
pub fn new(files: Vec<PathBuf>) -> io::Result<Self>
```

--------------------------------

### High-detail output for local viewing

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Command to generate high-detail output suitable for local viewing by setting minimum and maximum LOD levels. Adjust --min and --max to control the level of detail.

```bash
ptiler --input data.las \
       --output output/ \
       --input-epsg 6677 \
       --output-epsg 4979 \
       --min 18 --max 21
```

--------------------------------

### PointTransformer::new

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/coordinate-transformer.md

Creates a new PointTransformer for EPSG-to-EPSG conversion. It initializes the PROJ context, enables network downloads and caching for grid files, and sets up the transformation, including normalization of axis order.

```APIDOC
## PointTransformer::new

### Description
Creates a new transformer for EPSG-to-EPSG conversion.

### Method
`pub fn new(
    input_epsg: EpsgCode,
    output_epsg: EpsgCode,
    proj_data_dir: Option<&Path>,
) -> Result<Self, ProjError>`

### Parameters
#### Path Parameters
- `input_epsg` (EpsgCode) - Required - Source EPSG code
- `output_epsg` (EpsgCode) - Required - Target EPSG code
- `proj_data_dir` (Option<&Path>) - Optional - Optional PROJ data directory

### Returns
- `Result<Self, ProjError>` - A new PointTransformer instance or a ProjError if initialization fails.

### Initialization Details
1. Creates PROJ context
2. Enables network for automatic grid file downloads
3. Enables grid caching
4. Creates CRS-to-CRS transformation
5. Normalizes axis order for visualization (handles EPSG:4326 lat/lon vs lon/lat)

### Errors
Returns `ProjError` if:
- PROJ context creation fails
- CRS codes are invalid
- Grid files cannot be loaded

### Example
```rust
let transformer = PointTransformer::new(6677, 4979, None)?;
```
```

--------------------------------

### Iterating Through Points with PointReader

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Demonstrates how to read points sequentially from a source using the `next_point` method until the end of the stream is reached or an error occurs.

```rust
let mut reader = /* LasPointReader or CsvPointReader */;
while let Ok(Some(point)) = reader.next_point() {
    println!("Point: ({}, {}, {})", point.x, point.y, point.z);
}
```

--------------------------------

### GZIP Compression Error Handling

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/errors.md

GZIP compression is applied at the filesystem I/O level. Any errors encountered during this process are standard `io::Error` types.

--------------------------------

### make_tile_content

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Creates tile metadata, including bounds and content path, from a given point cloud and its tile coordinates.

```APIDOC
## make_tile_content

### Description
Creates tile metadata from a point cloud.

### Signature
```rust
pub fn make_tile_content(tile_coord: &TileZXY, point_cloud: &PointCloud) -> TileContent
```

### Parameters
#### Path Parameters
- `tile_coord` (*&TileZXY*) - Required - Tile coordinates (z, x, y)
- `point_cloud` (*&PointCloud*) - Required - Point cloud for the tile

### Returns
- `TileContent` - Metadata including bounds and path

### Path Format
`{zoom}/{x}/{y}.glb`

### Bounds
Extracted from point cloud bounding volume (longitude, latitude, height in WGS84).

### Example
```rust
let content = make_tile_content(&(18, 1234, 5678), &tile_cloud);
println!("Content at: {}", content.content_path);
println!("Bounds: ({}, {})", content.min_lng, content.max_lng);
```
```

--------------------------------

### LasPointReader::open_next_file Method

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-parser.md

Opens the next file in the queue for reading. This is typically called internally by `next_point()`.

```rust
pub fn open_next_file(&mut self) -> io::Result<()>
```

--------------------------------

### Point Tiler CLI Required Arguments

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Specifies the essential arguments for running the Point Tiler CLI, including input/output paths and EPSG codes.

```bash
ptiler --input <FILE>...
       --output <DIR>
       --input-epsg <CODE>
       --output-epsg <CODE>
```

--------------------------------

### Point Tiler Data Processing Pipeline

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/architecture.md

Visualizes the step-by-step data flow from input files through parsing, transformation, processing, and final export to GLB files and tileset.json.

```text
Input Files (LAS/LAZ/CSV)
    ↓
[pcd-parser] → Read Points
    ↓
[coordinate-transformer] → Transform Coordinates
    ↓
[app] → Sort & Group by Zoom
    ↓
[pcd-core/decimation] → Voxel Decimation (optional)
    ↓
[pcd-exporter/tiling] → Create Tile Hierarchy
    ↓
[pcd-exporter/gltf] → Generate GLB files
    ↓
[cesiumtiles-gltf] → Write Binary Format
    ↓
Output: tileset.json + GLB files
```

--------------------------------

### into_tileset_root Method Signature

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/pcd-exporter.md

Converts the internal TileTree structure into the Cesium 3D Tileset format. This involves recursively updating bounding volumes, converting the hierarchy, and calculating geometric errors.

```rust
pub fn into_tileset_root(self) -> tileset::Tile
```

--------------------------------

### Integrate 3D Tiles with Cesium.js

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/endpoints.md

Load a generated 3D Tileset into a Cesium.js viewer by serving the output directory from a web server and referencing the tileset.json file.

```html
<script src="https://cesium.com/downloads/cesiumjs/releases/1.104/Cesium.js"></script>
<div id="cesiumContainer"></div>
<script>
    const viewer = new Cesium.Viewer('cesiumContainer');
    viewer.dataSources.add(Cesium.Cesium3DTileset.fromUrl('/output/tileset.json'));
</script>
```

--------------------------------

### Project Directory Structure

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/README.md

This snippet shows the directory structure of the Point Tiler project, indicating the location of main reference documents and API reference modules.

```text
output/
├── INDEX.md                    # Start here
├── README.md                   # This file
├── architecture.md
├── configuration.md
├── errors.md
├── types.md
├── endpoints.md
└── api-reference/
    ├── pcd-core.md
    ├── pcd-parser.md
    ├── pcd-exporter.md
    ├── coordinate-transformer.md
    ├── cesiumtiles-gltf.md
    └── app-cli.md
```

--------------------------------

### Convert LAZ with default settings

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/INDEX.md

Basic command to convert LAZ files to a specified EPSG code using default settings. Ensure input and output EPSG codes are correct for your data.

```bash
ptiler --input data.laz \
       --output output/ \
       --input-epsg 6677 \
       --output-epsg 4979
```

--------------------------------

### Benchmark Point Tiler Usage

Source: https://github.com/mierune/point-tiler/blob/main/README.md

This command is used for benchmarking the point-tiler tool. It processes multiple LAS files and outputs tiles, with options for compression and quantization.

```sh
ptiler --input /path/to/data/*.las \
    --output /path/to/output \
    --input-epsg 6677 \
    --output-epsg 4979 \
    --min 15 \
    --max 18 \
    --max-memory-mb 8192 \
    --threads 8 \
    --quantize \
    --meshopt \
    --gzip-compress
```

--------------------------------

### CLI Argument Structure with Clap Derive

Source: https://github.com/mierune/point-tiler/blob/main/_autodocs/api-reference/app-cli.md

Defines the command-line arguments for the Point Tiler application using `clap` derive macros. This structure includes input/output file paths, EPSG codes, tiling parameters, memory limits, and various processing options.

```rust
#[derive(Parser, Debug, Clone)]
#[command(
    name = "Point Tiler",
    about = "A tool for converting point cloud data into 3D Tiles",
    author = "MIERUNE Inc.",
    version = "0.0.1"
)]
struct Cli {
    #[arg(short, long, required = true, num_args = 1.., value_name = "FILE")]
    input: Vec<String>,
    
    #[arg(short, long, required = true, value_name = "DIR")]
    output: String,
    
    #[arg(long, required = true)]
    input_epsg: u16,
    
    #[arg(long, required = true)]
    output_epsg: u16,
    
    #[arg(long, default_value_t = 15)]
    min: u8,
    
    #[arg(long, default_value_t = 18)]
    max: u8,
    
    #[arg(long, default_value_t = 4 * 1024)]
    max_memory_mb: usize,
    
    #[arg(long, value_name = "N")]
    threads: Option<usize>,
    
    #[arg(long)]
    quantize: bool,
    
    #[arg(long)]
    gzip_compress: bool,
    
    #[arg(long)]
    meshopt: bool,
    
    #[arg(long)]
    disable_decimation: bool,
}
```