### Install and Run Node.js Server

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/encoding-server/README.md

Navigate to the server directory, install dependencies, and start the development server.

```bash
cd encoding-server
npm install
npm start
```

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

### Install cargo-fuzz

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-core/fuzz/README.md

Install the cargo-fuzz tool. This requires a nightly Rust toolchain.

```bash
cargo install cargo-fuzz
```

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

### Verify MLT Module Installation

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/qgis/README.md

Verifies the successful installation of the maplibre_tiles module by listing layers from a sample MLT file.

```python
/usr/bin/python3 -c "import maplibre_tiles; print(maplibre_tiles.list_layers(open('../../test/synthetic/0x01/polygon.mlt','rb').read()))"
```

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

### Gradle Installation (Groovy)

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Add the MapLibre Tile library to your project's dependencies using Gradle with Groovy syntax. Ensure you include the necessary repositories.

```gradle
repositories {
  mavenCentral()
  maven {
    url 'https://maven.ecc.no/releases'
  }
}

dependencies {
  implementation 'org.maplibre:mlt:0.0.10'
}
```

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

### Gradle Installation (Kotlin)

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Add the MapLibre Tile library to your project's dependencies using Gradle with Kotlin syntax. Ensure you include the necessary repositories.

```kotlin
repositories {
  mavenCentral()
  maven {
    url = uri("https://maven.ecc.no/releases")
  }
}

dependencies {
  implementation("org.maplibre:mlt:0.0.10")
}
```

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

### Build and Install MLT Native Module

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/qgis/README.md

Builds the Rust MLT native module using maturin and installs it for QGIS. Supports building a wheel or developing directly.

```bash
cd rust/mlt-py

# Option A: build a wheel, then install it
pip install maturin            # in any environment
maturin build --release --interpreter /usr/bin/python3

# Install into user site-packages (visible to QGIS)
/usr/bin/python3 -m pip install --user --break-system-packages \
    ../../rust/target/wheels/mlt-*.whl

# Option B: if QGIS uses a virtualenv / conda, activate it first
#   conda activate qgis-env   # or: source /path/to/venv/bin/activate
#   maturin develop --release
```

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

### Decode MLT Files using CLI

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Command-line example for decoding MLT files using the generated 'decode.jar'.

```console
java -jar mlt-cli/build/libs/decode.jar --mlt /tmp/point-boolean.mlt
```

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

### Convert MVT to MLT using CLI

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Command-line examples for converting MVT files to MLT format using the generated 'encode.jar'. Supports various input formats like .pbf, .mbtiles, and .pmtiles.

```console
java -jar mlt-cli/build/libs/encode.jar --mvt ../test/fixtures/simple/point-boolean.pbf --mlt /tmp/point-boolean.mlt --tessellate --outlines ALL --verbose
```

```console
java -jar mlt-cli/build/libs/encode.jar --mbtiles /path/to/input.mbtiles --mlt /tmp/output.mbtiles --tessellate --outlines ALL --compress=deflate --verbose
```

```console
java -jar mlt-cli/build/libs/encode.jar --pmtiles /path/to/input.pmtiles --mlt /tmp/output.pmtiles --tessellate --outlines ALL --parallel
```

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

### Maven Installation

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Configure your Maven project to include the MapLibre Tile library by adding the necessary repositories and dependency information in your pom.xml.

```xml
<repositories>
  <repository>
    <id>maven-central</id>
    <url>https://repo1.maven.org/maven2</url>
  </repository>
  <repository>
    <id>ecc-releases</id>
    <url>https://maven.ecc.no/releases</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>org.maplibre</groupId>
    <artifactId>mlt</artifactId>
    <version>0.0.10</version>
  </dependency>
</dependencies>
```

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

### Build WASM and TypeScript Packages

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-wasm/README.md

Run this command to build both the WebAssembly and TypeScript components of the mlt-wasm package. Ensure wasm-pack and Node.js are installed.

```sh
npm run build
```

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

### Symlink QGIS MLT Plugin

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/qgis/README.md

Creates a symbolic link for the QGIS MLT plugin to make it available in QGIS. Examples for Linux, macOS, and Windows.

```bash
# Linux
ln -sfn "$(pwd)/../../qgis/mlt_plugin" \
    ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/mlt_plugin

# macOS
ln -sfn "$(pwd)/../../qgis/mlt_plugin" \
    ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins/mlt_plugin

# Windows (PowerShell, run as Admin)
# New-Item -ItemType SymbolicLink `
#   -Path "$env:APPDATA\QGIS\QGIS3\profiles\default\python\plugins\mlt_plugin" `
#   -Target (Resolve-Path "..\..\qgis\mlt_plugin")
```

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

### Basic MLT Encoding from MVT

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Converts a Mapbox Vector Tile (MVT) to MapLibre Tile (MLT) format. This example demonstrates basic configuration, including column mapping for nested properties.

```java
import org.maplibre.mlt.converter.MltConverter;
import org.maplibre.mlt.converter.mvt.MvtUtils;
import org.maplibre.mlt.converter.ColumnMapping;
import org.maplibre.mlt.converter.ConversionConfig;
import org.maplibre.mlt.converter.FeatureTableOptimizations;
import org.maplibre.mlt.metadata.tileset.MltMetadata;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;

byte[] mvtData = Files.readAllBytes(Path.of("tile.mvt"));
var mvtTile = MvtUtils.decodeMvt(mvtData);

// Configure column mappings for nested properties (e.g., name:en, name:de)
var columnMappingConfig = List.of(new ColumnMapping("name", ":", true));

var tilesetMetadata = MltConverter.createTilesetMetadata(mvtTile, columnMappingConfig, true);

var optimization = new FeatureTableOptimizations(false, false, columnMappingConfig);
var optimizations = Map.of("layer_name", optimization);
var config = new ConversionConfig(true, true, optimizations);

byte[] mltData = MltConverter.convertMvt(mvtTile, tilesetMetadata, config, null);

Files.write(Path.of("tile.mlt"), mltData);
```

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

### Build Project with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Run this command to build the entire project using Gradle.

```bash
./gradlew build
```

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

### Format Code with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Execute this command to format the project's code according to the defined style guidelines.

```bash
./gradlew spotlessApply
```

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

### Run All Tests with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Execute this command to run all the unit and integration tests for the project.

```bash
./gradlew test
```

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

### List Tile Files with Statistics using `mlt ls`

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Lists tile files in a directory with per-file statistics, including layer count, feature count, and compressed size.

```bash
mlt ls ./output/omt
```

```bash
mlt ls ./fixtures/omt
```

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

### Manual Tile Encoding with Encoder

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Demonstrates direct usage of the `Encoder` for manual tile generation and benchmarking alternative stream encodings. The `try_alternatives` method allows competing encoding strategies to find the shortest candidate.

```rust
use mlt_core::encoder::{Encoder, EncoderConfig, SortStrategy};
use mlt_core::MltResult;

fn manual_encode_example() -> MltResult<()> {
    let mut enc = Encoder::default();

    // Compete between encoding strategies for a single stream
    {
        let mut alt = enc.try_alternatives();
        alt.with(|e| {
            e.data.extend_from_slice(b"varint-encoded-stream-longer");
            Ok(())
        })?;
        alt.with(|e| {
            e.data.extend_from_slice(b"fpf-short");
            Ok(())
        })?;
        // alt drops here → "fpf-short" (9 bytes) wins over "varint..." (28 bytes)
    }

    // Inspect sizes before finalizing
    println!(
        "hdr={} meta={} data={} total={}",
        enc.hdr.len(), enc.meta.len(), enc.data.len(), enc.total_len()
    );

    // Finalize into a framed Tag-01 wire record
    let wire_bytes = enc.into_layer_bytes()?;
    println!("Wire record: {} bytes", wire_bytes.len());

    // Or get raw bytes without the size/tag prefix
    let raw = Encoder::default().into_raw_bytes();
    println!("Raw (no frame): {} bytes", raw.len());
    Ok(())
}
```

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

### Convert MLT to GeoJSON String

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-py/README.md

Convert MLT data directly into a GeoJSON formatted string using tile-local coordinates. This is a fast way to get GeoJSON output without full feature decoding.

```python
# GeoJSON string output (tile-local coords)
geojson_str = maplibre_tiles.decode_mlt_to_geojson(data)
```

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

### Execute Benchmarks with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Run this command to execute the project's benchmarks using the JMH (Java Microbenchmark Harness) tool.

```bash
./gradlew jmh
```

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

### Visualize MLT Files in Directory with CLI

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt/README.md

Use the `cargo run -- ui` command with a directory path to recursively browse and visualize all MLT files within that directory.

```bash
cargo run -- ui path/to/directory
```

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

### Build CLI Tools with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Use this command to build only the Command Line Interface (CLI) tools for the project.

```bash
./gradlew cli
```

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

### Run Specific Tests with Gradle

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/CONTRIBUTING.md

Run this command to execute a specific test class, such as `MltDecoderTest`.

```bash
./gradlew test --tests com.mlt.decoder.MltDecoderTest
```

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

### Visualize MLT File with CLI

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt/README.md

Use the `cargo run -- ui` command to visualize a single MLT file in the terminal.

```bash
cargo run -- ui path/to/file.mlt
```

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

### Download and Configure External fsst Project

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/resources/CMakeLists.txt

Uses ExternalProject_Add to download and configure the fsst library from a Git repository.

```cmake
include(ExternalProject)
ExternalProject_Add(FsstDownload
    GIT_REPOSITORY https://github.com/springmeyer/fsst
    GIT_TAG bd766bc # https://github.com/springmeyer/fsst/tree/dane/cross-platform-build-fixes
    INSTALL_COMMAND ""
    PREFIX ${CMAKE_CURRENT_BINARY_DIR}/libfsst-prefix
    CMAKE_ARGS "-DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS}"
)
```

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

### Interactive TUI Tile Viewer with `mlt ui`

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Launches an interactive terminal UI for browsing tile files, inspecting layers, and visualizing feature data.

```bash
mlt ui tile.mlt
```

```bash
mlt ui tileset.mbtiles
```

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

### Run Java Tests

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Commands to execute the test suites for the Java MapLibre tile library and its CLI tools.

```console
just java::test
```

```console
just java::test-cli
```

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

### Create FsstWrapper Module Library

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/resources/CMakeLists.txt

Defines a MODULE library 'FsstWrapper' from FsstWrapper.cpp, linking it with libfsst and setting output properties.

```cmake
add_library(FsstWrapper MODULE ${CMAKE_CURRENT_SOURCE_DIR}/FsstWrapper.cpp)
add_dependencies(FsstWrapper FsstDownload)
set_target_properties(FsstWrapper PROPERTIES
    OUTPUT_NAME "${output_name}"
    POSITION_INDEPENDENT_CODE ON
    SUFFIX ".so"
    PREFIX ""
)
target_include_directories(FsstWrapper PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${JNI_INCLUDE_DIRS} ${LIBFSST_INC_DIRECTORY})
target_link_libraries(FsstWrapper libfsst)
```

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

### Inspect Tile Layers with `mlt decode` and `mlt dump`

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Parses tile files (.mlt, .mvt, .pbf) and prints layer contents. `decode` fully decodes all column data, while `dump` shows raw stream metadata without decoding.

```bash
mlt decode tile.mlt
```

```bash
mlt decode --format geojson tile.mlt
```

```bash
mlt decode tile.mvt
```

```bash
mlt dump tile.mlt
```

```bash
mlt decode tile.pbf
```

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

### Build MLT C++ Library

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/README.md

Builds the MLT C++ library and tests using CMake and Ninja. Ensure submodules are updated before building.

```bash
git submodule update --init --recursive
cmake -GNinja -Bbuild -S.
cmake --build build --target mlt-cpp-test mlt-cpp-json
```

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

### Configure Build Options

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/CMakeLists.txt

Sets boolean options to enable or disable specific features like JSON support, FastPFor, SIMD, tests, and tools.

```cmake
option(MLT_WITH_JSON "Include JSON support" ON)
option(MLT_WITH_FASTPFOR "Include FastPFor support" ON)
option(MLT_WITH_FASTPFOR_SIMD "Include SIMD/NEON support in FastPFor decoding" ON)
option(MLT_WITH_TESTS "Include Tests" ON)
option(MLT_WITH_TOOLS "Include CLI tools" ON)
```

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

### Create Test Executable CMake

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/test/CMakeLists.txt

Creates the `mlt-cpp-test` executable using the defined test sources and sets the C++ standard to 20.

```cmake
add_executable(mlt-cpp-test ${TEST_SOURCES})
set_property(TARGET mlt-cpp-test PROPERTY CXX_STANDARD 20)
```

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

### Configure Google Test CMake

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/test/CMakeLists.txt

Configures Google Test for the project, including setting `gtest_force_shared_crt` for Windows compatibility and adding the googletest subdirectory.

```cmake
set(BUILD_GMOCK OFF CACHE BOOL "" FORCE)
set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)

# For Windows: Prevent overriding the parent project's compiler/linker settings
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)

add_subdirectory("${PROJECT_SOURCE_DIR}/vendor/googletest" "${CMAKE_CURRENT_BINARY_DIR}/googletest" EXCLUDE_FROM_ALL SYSTEM)
```

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

### Configure Include Directories

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/CMakeLists.txt

Specifies the include directories for the 'mlt-cpp' target, distinguishing between public and private headers.

```cmake
target_include_directories(mlt-cpp
    PUBLIC ${PROJECT_SOURCE_DIR}/include
    PRIVATE ${PROJECT_SOURCE_DIR}/src
)
```

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

### Batch Convert MVT to MLT in Java

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/README.MD

Process multiple MVT files from a directory, convert them to MLT format, and save the results. Handles file I/O and conversion errors.

```java
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.stream.Stream;
import org.maplibre.mlt.converter.MltConverter;
import org.maplibre.mlt.converter.mvt.MvtUtils;
import org.maplibre.mlt.converter.ConversionConfig;
import org.maplibre.mlt.metadata.tileset.MltMetadata;
import java.io.IOException;
import java.util.List;
import java.util.Map;

try (Stream<Path> paths = Files.list(Paths.get("input_tiles"))) {
  paths.filter(path -> path.toString().endsWith(".mvt"))
       .forEach(mvtPath -> {
         try {
           byte[] mvtData = Files.readAllBytes(mvtPath);
           var mvtTile = MvtUtils.decodeMvt(mvtData);
           var tilesetMetadata = MltConverter.createTilesetMetadata(mvtTile, List.of(), true);
           var config = new ConversionConfig(true, true, Map.of());
           byte[] mltData = MltConverter.convertMvt(mvtTile, tilesetMetadata, config, null);

           String mltPath = mvtPath.toString().replace(".mvt", ".mlt");
           Files.write(Paths.get(mltPath), mltData);

           System.out.println("Converted: " + mvtPath + " -> " + mltPath);
         } catch (IOException e) {
           System.err.println("Error processing " + mvtPath + ": " + e.getMessage());
         }
       });
}
```

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

### Build WASM Package Only

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-wasm/README.md

Execute this command to specifically build the WebAssembly component using wasm-pack. This is useful for targeted WASM compilation.

```sh
npm run build:wasm
```

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

### Find and Configure JNI

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/resources/CMakeLists.txt

Locates the Java Native Interface (JNI) and prints its include directories and libraries if found.

```cmake
find_package(JNI)
if (JNI_FOUND)
    message (STATUS "JNI_INCLUDE_DIRS=${JNI_INCLUDE_DIRS}")
    message (STATUS "JNI_LIBRARIES=${JNI_LIBRARIES}")
endif()
```

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

### Run the mlt Fuzzer

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-core/fuzz/README.md

Execute the fuzzing process for the 'layer' target from the fuzz directory. Options for run count and timeout are available.

```bash
cargo +nightly fuzz run layer
```

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

### Build TypeScript Package Only

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-wasm/README.md

Run this command to compile the TypeScript wrapper for the WASM module. This step is necessary after the WASM component has been built.

```sh
npm run build:ts
```

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

### Configure Test Include Directories CMake

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/test/CMakeLists.txt

Configures include directories for the test executable. Includes private headers for the library and conditionally includes JSON and FastPFOR headers based on build options.

```cmake
# Tests have access to private headers
target_include_directories(mlt-cpp-test PUBLIC "${PROJECT_SOURCE_DIR}/src")

option(MLT_WITH_JSON "Include JSON support" ON)

if(MLT_WITH_JSON)
    target_include_directories(mlt-cpp-test PUBLIC "${json_SOURCE_DIR}/include")
    target_compile_definitions(mlt-cpp-test PUBLIC MLT_WITH_JSON=1)
endif(MLT_WITH_JSON)
if(MLT_WITH_FASTPFOR)
    target_include_directories(mlt-cpp-test PRIVATE SYSTEM "${PROJECT_SOURCE_DIR}/vendor/fastpfor/headers")
endif(MLT_WITH_FASTPFOR)
```

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

### Request MVT Style Endpoint

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/encoding-server/README.md

Use curl to request the style endpoint, providing the URL of the Mapbox style JSON. This initiates the conversion process.

```bash
curl http://0.0.0.0/style?url=https://demotiles.maplibre.org/style.json ## default
```

```bash
curl http://localhost/style?url=https://demotiles.maplibre.org/style.json
```

```bash
curl http://10.0.2.2/style?url=https://demotiles.maplibre.org/style.json ## Android emulator bridge to 0.0.0.0
```

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

### Bulk MVT to MLT Conversion

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Converts directory trees of MVT tiles or .mbtiles databases to re-encoded MLT files using the `mlt convert` command. Supports configurable sort strategies, optional tessellation, and shared-dictionary optimization.

```bash
mlt convert ./fixtures/omt ./output/omt
```

```bash
mlt convert input.mbtiles output.mbtiles
```

```bash
mlt convert --tessellate ./mvt-tiles ./mlt-tiles
```

```bash
mlt convert --sort hilbert ./in ./out
```

```bash
mlt convert --no-shared-dict ./in ./out
```

```bash
mlt convert --mbtiles-format normalized in.mbtiles out.mbtiles
```

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

### Build Executable with JSON Support

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/tool/CMakeLists.txt

Configures a C++ executable target named 'mlt-cpp-json' using specified source files. It enforces C++20 standard, enables JSON support, and links against the 'mlt-cpp' library.

```cmake
add_executable(mlt-cpp-json mlt-json.cpp synthetic-geojson.cpp)
set_property(TARGET mlt-cpp-json PROPERTY CXX_STANDARD 20)
set(MLT_WITH_JSON ON CACHE BOOL "Include JSON Support" FORCE)
target_link_libraries(mlt-cpp-json PRIVATE mlt-cpp)
```

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

### Enable Compile Commands Export

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/CMakeLists.txt

Enables the generation of compile_commands.json for better IDE integration and tooling support.

```cmake
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
```

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

### Link Libraries and Discover Tests CMake

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/test/CMakeLists.txt

Links the test executable with the main library and Google Test, then discovers and enables the tests.

```cmake
target_link_libraries(mlt-cpp-test mlt-cpp gtest_main)

include(GoogleTest)

gtest_discover_tests(
    mlt-cpp-test
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
)
```

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

### Run MLT C++ Tests

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/README.md

Executes the compiled MLT C++ tests. The test executable is located in the build directory.

```bash
build/test/mlt-cpp-test
```

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

### Set Target Properties

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/CMakeLists.txt

Configures properties for the 'mlt-cpp' target, including metadata like name, URL, author, and license.

```cmake
set_target_properties(
    mlt-cpp
    PROPERTIES
    INTERFACE_MAPLIBRE_NAME "MapLibre Tile Format"
    INTERFACE_MAPLIBRE_URL "https://github.com/maplibre/maplibre-tile-spec"
    INTERFACE_MAPLIBRE_AUTHOR "MapLibre"
    INTERFACE_MAPLIBRE_LICENSE "${PROJECT_SOURCE_DIR}/../LICENSE-APACHE"
)
```

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

### Request MVT Source Endpoint

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/encoding-server/README.md

Use curl to request the source endpoint, providing the URL of the tiles JSON file. This is used to fetch tile source information.

```bash
curl http://0.0.0.0/source?url=https://demotiles.maplibre.org/tiles/tiles.json
```

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

### Set C++ Standard and Extensions

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/resources/CMakeLists.txt

Configures the C++ standard to C++17 and disables C++ extensions for broader compatibility.

```cmake
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
```

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

### String Encoding Schema

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/docs/specification.md

Illustrates the schema for encoding strings within the tile specification. Strings are represented with a length header followed by UTF-8 encoded bytes.

```mermaid
--- 
config:
  class:
    hideEmptyMembersBox: true
title: StringsSchema
---
classDiagram
direction TB
    class String {
      +VarInt length
      +u8 bytes[length] %% encoding is always UTF-8
    }

```

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

### Data Pipeline Flowchart

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/rust/mlt-core/README.md

Visual representation of the tile data lifecycle, from raw bytes to encoded bytes, including decoding, parsing, iteration, and encoding stages.

```mermaid
flowchart TB
A(["&[u8]  —  raw tile bytes"])

subgraph DEC ["Decoding"]
    B["<b>Parser::parse_layers(&[u8])</b>
    <i>Create zero-copy views into input bytes
    for each layer with almost no memory allocations</i>"]

    C["Layer&lt;Lazy>
       Tag01(Layer01&lt;Lazy>) | Unknown
       columns = LazyParsed::Raw(RawStream)
       zero allocations for column data"]

    D["decode_all()  —  or per-column:
       decode_id() / decode_geometry() / decode_property()

       RawStream
       → physical codec: FastPFor · varint · byte-RLE
       → logical  codec: delta · zigzag · Morton · Hilbert
       → typed column buffers Vec&lt;T>"]

    E["ParsedLayer  =  Layer&lt;Parsed>
       all columns decoded into typed buffers"]
end

subgraph ACCESS ["Iterate  (zero-copy borrow)"]
    F["iter_features()  →  Layer01FeatureIter"]
    G["FeatureRef
       id: Option&lt;u64>
       geometry reference
       property iterator"]
end

H(["Layer01::into_tile()"])

subgraph BRIDGE ["TileLayer  (row-oriented, fully owned)"]
    I["Vec&lt;TileFeature>
       id:       Option&lt;u64>
       geometry: geo_types::Geometry&lt;i32>
       props:    Vec&lt;PropValue>"]
end

subgraph ENC ["Encoding"]
    J["StagedLayer::from(TileLayer)
       owned columnar form
       IdValues · GeometryValues · Vec&lt;StagedProperty>"]

    K["StagedLayer::encode()
       / encode_auto() / encode_with_profile()
       per-column compression applied"]

    L["EncodedLayer01  (wire-ready)
       EncodedId · EncodedGeometry
       Vec&lt;EncodedProperty>  each = Vec&lt;EncodedStream>"]

    M["EncodedLayer::write_to()
       serialises: varint(size) + tag byte + column payloads"]
end

N(["Vec&lt;u8>  —  encoded tile bytes"])

A --> B --> C --> D --> E
E -->|"borrow"| F --> G
E -->|"own all data"| H --> I
I -->|"From&lt;TileLayer>"| J --> K --> L --> M --> N

classDef io fill:#1e5c3a,color:#e8f5e9,stroke:#0a3d22
classDef bridge fill:#4a1c6b,color:#f3e5f5,stroke:#2d0b45
classDef dec fill:#1a3a5c,color:#e3f2fd,stroke:#0d1f35
classDef enc fill:#5c2a1a,color:#fbe9e7,stroke:#3d1510
class A,N io
class H,I bridge
class B,C,D,E,F,G dec
class J,K,L,M enc
```

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

### Define Test Sources CMake

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/test/CMakeLists.txt

Defines the source files for the test executable. Conditionally adds `test_fastpfor.cpp` if `MLT_WITH_FASTPFOR` is enabled.

```cmake
set(TEST_SOURCES
    test_decode.cpp
    test_fsst.cpp
    test_packed_bitset.cpp
    test_util.cpp
    test_varint.cpp
)

if (MLT_WITH_FASTPFOR)
    list(APPEND TEST_SOURCES test_fastpfor.cpp)
endif()
```

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

### Platform-Specific CXX Flags

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/resources/CMakeLists.txt

Applies architecture-specific flags for macOS and native optimization flags for Linux.

```cmake
if(APPLE)
  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -arch x86_64 -arch arm64")
endif(APPLE)

if (LINUX)
  include(CheckCXXCompilerFlag)
  check_cxx_compiler_flag("-march=native" COMPILER_SUPPORTS_MARCH_NATIVE)
  if(COMPILER_SUPPORTS_MARCH_NATIVE)
      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
  endif()
endif(LINUX)
```

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

### Column Options Schema

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/docs/specification.md

Defines the enumeration of options applicable to fields and columns, such as NULLABLE, COMPLEX_TYPE, LOGICAL_TYPE, CHILD_TYPES, and VERTEX_SCOPE.

```mermaid
--- 
config:
  class:
    hideEmptyMembersBox: true
title: ColumnsSchema
---
classDiagram
direction TB
    class FieldOptions {
      NULLABLE = 1, %% Property is nullable
      COMPLEX_TYPE = 2, %% A complexType follows if set, else a scalarType [EXPERIMENTAL]
      LOGICAL_TYPE = 4, %% A logical type follows if set, else a physical type [EXPERIMENTAL]
      CHILD_TYPES = 8, %% 1: Child types are present [EXPERIMENTAL]
    }

    class ColumnOptions {
      VERTEX_SCOPE = 16, %% Property is vertex-scope if set, else feature-scope
    }

    <<enumeration>> FieldOptions
    <<enumeration>> ColumnOptions

    FieldOptions <|-- ColumnOptions

```

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

### Convert MVT bytes to TileLayer list and encode to MLT

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Parses raw MVT binary data into a list of TileLayer objects, infers column types, and then encodes them into MLT bytes. This is useful for converting existing MVT data into the MapLibre Tile format.

```rust
use mlt_core::mvt::mvt_to_tile_layers;
use mlt_core::encoder::EncoderConfig;
use mlt_core::MltResult;
use std::fs;

fn mvt_to_mlt(mvt_path: &str, mlt_path: &str) -> MltResult<()> {
    let mvt_bytes = fs::read(mvt_path).expect("read mvt");
    let tile_layers = mvt_to_tile_layers(mvt_bytes)?;

    let cfg = EncoderConfig {
        tessellate: true,
        ..Default::default()
    };

    let mut all_encoded: Vec<u8> = Vec::new();
    for layer in tile_layers {
        println!("Converting layer '{}' ({} features)", layer.name, layer.features.len());
        let encoded = layer.encode(cfg)?;
        all_encoded.extend_from_slice(&encoded);
    }

    fs::write(mlt_path, &all_encoded).expect("write mlt");
    println!("Written {} bytes to {mlt_path}", all_encoded.len());
    Ok(())
}
```

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

### Dump MLT Tile to JSON

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/README.md

Converts an MLT tile and its metadata file pair into JSON format using the provided tool. Specify the path to the MLT file as an argument.

```bash
build/tool/mlt-cpp-json ../test/expected/tag0x01/bing/4-12-6.mlt
```

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

### List Source Files

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/cpp/CMakeLists.txt

Appends a list of source files to the MLT_SRC_FILES variable, including implementation and internal header files.

```cmake
list(APPEND MLT_SRC_FILES
    ${PROJECT_SOURCE_DIR}/src/mlt/decoder.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/decode/geometry.hpp
    ${PROJECT_SOURCE_DIR}/src/mlt/decode/int.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/decode/int.hpp
    ${PROJECT_SOURCE_DIR}/src/mlt/decode/property.hpp
    ${PROJECT_SOURCE_DIR}/src/mlt/decode/string.hpp
    ${PROJECT_SOURCE_DIR}/src/mlt/feature.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/geometry_vector.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/layer.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/metadata/stream.cpp
    ${PROJECT_SOURCE_DIR}/src/mlt/metadata/tileset.cpp
)
```

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

### Request MVT Tile Endpoint

Source: https://github.com/maplibre/maplibre-tile-spec/blob/main/java/encoding-server/README.md

Use curl to request a specific tile, providing the URL to the MVT tile. The server will convert it to MLT on demand.

```bash
curl http://0.0.0.0/tile?url=https://demotiles.maplibre.org/tiles/{z}/{x}/{y}.pbf
```

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

### Sort TileLayer Features for Compression

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Employ `TileLayer::sort` with strategies like `SpatialHilbert`, `SpatialMorton`, or `Id` before encoding to improve compression ratios and decoding performance. `Unsorted` preserves the original order.

```rust
use mlt_core::{TileLayer, MltResult};
use mlt_core::encoder::SortStrategy;

fn sort_and_encode(mut layer: TileLayer) -> MltResult<Vec<u8>> {
    use mlt_core::encoder::EncoderConfig;

    // --- Hilbert sort: best spatial locality, slightly slower to compute ---
    layer.sort(SortStrategy::SpatialHilbert);
    let encoded = layer.encode(EncoderConfig::default())?;
    println!("Hilbert-sorted: {} bytes", encoded.len());

    // --- Morton sort: fast, nearly as good as Hilbert ---
    layer.sort(SortStrategy::SpatialMorton);
    let morton_encoded = layer.encode(EncoderConfig::default())?;
    println!("Morton-sorted: {} bytes", morton_encoded.len());

    // --- ID sort: useful when features are accessed by ID ---
    layer.sort(SortStrategy::Id);

    // --- No-op (preserve original order) ---
    layer.sort(SortStrategy::Unsorted);

    Ok(encoded)
}

```

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

### mvt::mvt_to_tile_layers

Source: https://context7.com/maplibre/maplibre-tile-spec/llms.txt

Converts raw Mapbox Vector Tile (MVT) binary data into a list of `TileLayer` objects. During parsing, column types are inferred based on the first non-null value encountered. Type conflicts are resolved by falling back to `Str`. The resulting `TileLayer` objects can be directly used with the `.encode()` method.

```APIDOC
## `mvt::mvt_to_tile_layers` — Convert MVT bytes to `TileLayer` list

Parses raw MVT binary data and converts each MVT layer into a `TileLayer` with inferred column types. The first non-null value per column determines its type; `I64`/`U64` values are widened to `I64`, `F32`/`F64` to `F64`, and all type conflicts fall back to `Str`. Pass the result directly to `.encode()`.

### Usage Example:

```rust
use mlt_core::mvt::mvt_to_tile_layers;
use mlt_core::encoder::EncoderConfig;
use mlt_core::MltResult;
use std::fs;

fn mvt_to_mlt(mvt_path: &str, mlt_path: &str) -> MltResult<()> {
    let mvt_bytes = fs::read(mvt_path).expect("read mvt");
    let tile_layers = mvt_to_tile_layers(mvt_bytes)?;

    let cfg = EncoderConfig {
        tessellate: true,
        ..Default::default()
    };

    let mut all_encoded: Vec<u8> = Vec::new();
    for layer in tile_layers {
        println!("Converting layer '{}' ({} features)", layer.name, layer.features.len());
        let encoded = layer.encode(cfg)?;
        all_encoded.extend_from_slice(&encoded);
    }

    fs::write(mlt_path, &all_encoded).expect("write mlt");
    println!("Written {} bytes to {mlt_path}", all_encoded.len());
    Ok(())
}
```
```