Overview

mago 3DTerrainer is an open source based quantized-mesh terrain generator developed in Java.
It is compatible with quantized-mesh, the native terrain data of Cesium Terrain Tiles.
It can easily convert GeoTIFF files, the standard format of OCG, into quantized-mesh data.
See: https://github.com/CesiumGS/quantized-mesh

Key features

• Convenient conversion: convert GeoTIFF files without complicated commands.
• High accuracy: Generate quantized-mesh data with high accuracy.
• Multiple data conversion: Convert multiple GeoTIFF data at once.
• Customizable options: Provides various customization options such as min/max tile depth, tile raster max size, tile mosaic size, tile generation strength, interpolation method, etc.
• RTIN Based Terrain Simplification: utilizes the RTIN(Right-Triangulated Irregular Network) algorithm for efficient terrain simplification.
• Planetary body support: Generate terrain tiles for the Moon and other bodies beyond Earth using the --body option.

Usage

You can download the released jar file or build the jar yourself via the mago-3d-terrainer project gradle script.
The built jar is created in the /dist directory.

gradlew jar

The Java version used in the release is OpenJDK 21.

Example help command

java -jar mago-3d-terrainer.jar -help

Output:

----------------------------------------
mago-3d-terrainer(dev-version) by Gaia3D, Inc.
----------------------------------------
Usage: command options
 -h, --help                          Print help
 -q, --quiet                         Suppress all output except errors
 -lt, --leaveTemp                    Leave temporary files for debugging
 -j, --json                          Generate layer.json for terrain data
 -c, --continue                      Continue terrain generation from the previous run. Use this option when terrain generation is interrupted or fails.
 -m, --modify                        Modify existing terrain. Use this option when updating part of a terrain region.
 -ssr, --skipStandardizationResize   Skip standardization and resizing process. This option can be used when the input data is already standardized and resized.
 -i, --input <arg>                   [Required] Input file or directory path. Repeatable.
 -o, --output <arg>                  [Required] Output directory path
 -l, --log <arg>                     Log file path
 -t, --temp <arg>                    Temporary directory path (default: {OUTPUT}/temp)
 -g, --geoid <arg>                   Set the height reference for terrain data.
                                     Geoid file path for height correction.
                                     (default: Ellipsoid)(options: Ellipsoid, EGM96, EGM2008, EGM84, or GeoTIFF file path)
 -min, --minDepth <arg>              Set the minimum terrain tile depth. This is effectively fixed at 0.
                                     (default: 0)(options: 0 - 22)
 -max, --maxDepth <arg>              Set the maximum terrain tile depth. If omitted, it is calculated automatically from the input raster resolution.
                                     (options: 0 - 22)
 -is, --intensity <arg>              Set the mesh refinement intensity.
                                     (default: 4.0)
 -it, --interpolationType <arg>      Set the interpolation type.
                                     (default: bilinear)(options: nearest, bilinear)
 -pt, --priorityType <arg>           Set the height priority for overlapping terrain data.
                                     (default: resolution)(options: resolution, higher)
 -nv, --nodataValue <arg>            Set the NODATA value for terrain generation.
                                     (default: -9999)
 -cn, --calculateNormals             [Deprecated] Terrain octVertexNormals are generated by default.
 -ncn, --noCalculateNormals          Disable generation of terrain octVertexNormals.
 -ms, --mosaicSize <arg>             Set the tiling mosaic buffer size per tile.
                                     (default: 8)
 -mr, --rasterMaxSize <arg>          Set the maximum raster size for splitting.
                                     (default: 4096)
 -md, --metadata                     [Experimental] Generate metadata for terrain data.
 -wm, --waterMask                    [Experimental] Generate a water mask for terrain data.
 -b, --body <arg>                    Set the celestial body for terrain generation.
                                     (default: earth)(options: earth, moon)
 -vb, --verbose                      Print verbose logs.
 -d, --debug                         [DEBUG] Print more detailed logs.

This is a simple Quantized-mesh conversion code with the required argument values.

java -jar mago-3d-terrainer-x.x.x.jar -input C:\data\geotiff-sample -output C:\data\geotiff-terrain-output -maxDepth 14

Multiple input files or directories can be provided by repeating the input option:

java -jar mago-3d-terrainer-x.x.x.jar --input C:\data\dem-a.tif --input C:\data\dem-b.tif --output C:\data\terrain-output -maxDepth 14

or

java -jar mago-3d-terrainer-x.x.x.x.jar -i C:\data\geotiff-sample -o C:\data\geotiff-terrain-output -max 14

Using the Docker version

The mago 3DTerrainer is also available as a docker image.

Installation command:

docker pull gaia3d/mago-3d-terrainer

Running command:

docker run --rm -v "/workspace:/workspace" gaia3d/mago-3d-terrainer -input /workspace/geotiff-sample -output /workspace/geotiff-terrain-output -maxDepth 14

Planetary Body Support (Moon and beyond)

mago-3d-terrainer supports terrain generation for planetary bodies other than Earth. Use the --body option to specify the target body:

java -jar mago-3d-terrainer.jar --input /input/lunar_dem --output /output/lunar_terrain --body moon --max 8

The Moon's DEM data (e.g. NASA LOLA) is typically distributed in a projected CRS and must be reprojected to geographic coordinates before use. Use GDAL to preprocess:

gdalwarp -t_srs "+proj=longlat +a=1737400 +b=1737400 +no_defs" -r bilinear input.tif output.tif

Alternatively, if your PROJ installation includes the IAU 2015 database:

gdalwarp -t_srs "IAU_2015:30100" input.tif output.tif

The output tile structure uses the same geographic tiling scheme (-180 to 180 longitude) as Earth tiles. To render in CesiumJS, configure the terrain provider with the correct ellipsoid:

const viewer = new Cesium.Viewer("cesiumContainer", {
    terrainProvider: await Cesium.CesiumTerrainProvider.fromUrl("/path/to/lunar_terrain", {
        ellipsoid: Cesium.Ellipsoid.MOON
    })
});

See the MANUAL.md for the full planetary terrain workflow.

Documentation

For detailed documentation, including installation and usage instructions, please refer to the official documentation:

• JavaDocs : gaia3d.github.io/mago-3d-terrainer
• Manual : github.com/Gaia3D/mago-3d-terrainer

Supported Java versions

Requires JDK 21 or later. The release artifacts are built and tested with OpenJDK 21.

License

• mago 3DTerrainer is licensed under the MPL2.0 license (https://www.mozilla.org/en-US/MPL/2.0/).
• If you do not want to release your modified code under the MPL2.0 license, you can follow a commercial license. In that case, please contact sales@gaia3d.com.

Library dependencies

• JOML (Java OpenGL Math Library): https://github.com/JOML-CI/JOML
• geotools (Geospatial data tools library): https://github.com/geotools/geotools
• proj4j (Converting coordinate reference systems): https://github.com/locationtech/proj4j