gocesiumtiler

In V2, vertical datum conversion is delegated to the Proj library. To convert elevations (e.g., from EGM to WGS84), you must provide a CRS definition that includes the vertical datum.

For example, to use EPSG:32633 with elevations referred to EGM2008 (EPSG:3855), use the composite CRS string:

--crs EPSG:32633+3855

Important: This may require downloading specific grid files from the Proj CDN and placing them in the share folder.

gocesiumtiler folder -o C:\out -e EPSG:32633+3855 -r 10 -m 1000 -d 12 C:\las

The library uses a hybrid, lazy octree data structure for sampling:

1. Storage: Points are stored in a linked tree backed by an array for cache efficiency and fast manipulations. Coordinates are converted to EPSG 4978 and then to a local CRS.
2. Cell Creation: Octree cells are created based on a provided resolution (grid spacing).
3. Traversal: Points are assigned to cells. The point closest to the cell center is kept; others are parked in the node's octant.
4. Roll-up: If an octant has fewer points than min-points-per-node or reaches max-depth, points are rolled up to the parent node.
5. Lazy Creation: Child nodes are created on demand using parked points.
6. Output: Final artifacts use local CRS coordinates, with a global transform applied at the tileset root to return to EPSG 4978 for Cesium compatibility.

Mutators allow you to manipulate or discard input points during the tiling process. They implement the mutator.Mutator interface and are passed to the tiler via tiler.WithMutators().

Built-in Mutators:

• mutator.NewZOffset(offset): Performs vertical translation of point clouds.
• mutator.NewSubsampler(ratio): Thins down the points in the output.

Important: Mutators must be goroutine safe.

mut := []mutator.Mutator{
   mutator.NewZOffset(10),
   mutator.NewSubsampler(0.5),
}

err = t.ProcessFiles([]string{"myinput.las"}, "/tmp/myoutput", "EPSG:32632", tiler.NewTilerOptions(
   tiler.WithEightBitColors(true),
   tiler.WithWorkerNumber(2),
   tiler.WithMaxDepth(5),
   tiler.WithMutators(mut),
), ctx)

To integrate the tiler into your own Go applications, install the v2 module using go get. You can then instantiate a tiler using tiler.NewGoCesiumTiler() and process data using either ProcessFiles or ProcessFolder.

Note: Compilation requires cgo. Refer to DEVELOPMENT.md for build environment setup requirements.

package main

import (
	"context"
	"log"

	"github.com/mfbonfigli/gocesiumtiler/v2/tiler"
)

func main() {
	t, err := tiler.NewGoCesiumTiler()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.TODO()
	// ProcessFiles(inputFiles, outputDir, epsgCode, options, context)
	err = t.ProcessFiles([]string{"myinput.las"}, "/tmp/myoutput", "EPSG:32632", tiler.NewTilerOptions(
		tiler.WithEightBitColors(true),
		tiler.WithWorkerNumber(2),
		tiler.WithMaxDepth(5),
	), ctx)
	if err != nil {
		log.Fatal(err)
	}
}

To install the tool, follow these steps:

1. Download the latest executable for your platform (Windows x64 or Linux x64) from the GitHub Releases page and unzip it.
2. Ensure the executable is placed in the same directory as the share folder.
3. Optional: If you require specific coordinate transformations (e.g., EGM to WGS84 elevation conversion), download the required Proj Data grids from the Proj CDN and unpack them into the share folder.

Note: The tool stores data completely in memory for speed. If processing very large LAS files, you may need to split them into smaller chunks to avoid running out of RAM.

For reproducible builds, use the provided Docker-based workflow. This method handles the complex cgo compilation and static linking of the Proj library automatically for both Linux and Windows targets.

• Linux/macOS: Run ./build.sh.
• Windows: Run ./build.ps1 in a PowerShell console.

It is recommended to use this method before creating any Pull Requests to ensure the build is reproducible.

# For Windows (PowerShell)
./build.ps1

# For Linux/macOS
./build.sh

To convert a single file using default settings and letting the tool detect the CRS from the LAS metadata:

gocesiumtiler file -out C:\out C:\las\file.las

To convert all LAS files in a folder into one single 3D Tileset with specific sampling parameters:

gocesiumtiler folder -out C:\out -crs EPSG:32633+3855 -resolution 10 -min-points-per-tile 1000 -depth 12 -join C:\las

To create a custom mutator, implement the Mutate method from the mutator.Mutator interface.

Signature: Mutate(p model.Point, t model.Transform) (model.Point, bool)

• Input: The original model.Point and a model.Transform object (useful for converting between local CRS and global EPSG 4978 CRS).
• Output: The (potentially modified) model.Point and a bool. Return true to keep the point in the final output, or false to discard it.

type ClassBasedColorMutator struct {}

func (m *ClassBasedColorMutator) Mutate(pt model.Point, localToGlobal model.Transform) (model.Point, bool) {
	switch pt.Classification {
	case 2: // ground
		pt.R, pt.G, pt.B = 128, 0, 0
	case 3: // low vegetation
		pt.R, pt.G, pt.B = 0, 60, 0
	// ... other cases
	default:
		pt.R, pt.G, pt.B = 30, 30, 30
	}
	return pt, true
}