Skip to content

Commit 49e3e7a

Browse files
znkimznkim
authored
Merge pull request #27 from Gaia3D/raster
Resolving minor bottlenecks to improve the speed of applying and converting internal raster formats
2 parents 7c08354 + 8c2a51c commit 49e3e7a

270 files changed

Lines changed: 30970 additions & 9015 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,4 @@ bin/
5151
Cigolle2014Vector.pdf
5252
terrainer/gradle.properties
5353
/.gradle-home/
54+
tools/

‎MANUAL.ko.md‎

Lines changed: 73 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
updated at 2026-03-24 by znkim
2-
31
# 기본 변환 옵션
42

53
## 가장 간단한 데이터 변환 예시 (최소 옵션)
@@ -8,21 +6,74 @@ updated at 2026-03-24 by znkim
86
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output"
97
```
108

9+
여러 입력 파일 또는 디렉터리는 `--input` 옵션을 반복해서 지정할 수 있습니다.
10+
```bash
11+
java -jar mago-3d-terrainer.jar --input "/input_path/dem-a.tif" --input "/input_path/dem-b.tif" --output "/output_path/terrain_tiles_output"
12+
```
13+
1114
## 최소 / 최대 타일 깊이 설정
1215
`--minDepth <value>`와 `--maxDepth <value>` 옵션을 사용하여 타일의 최소 및 최대 깊이를 설정할 수 있습니다.
1316
짧은 옵션으로는 `-min <value>`와 `-max <value>`를 사용할 수 있습니다.
1417

1518
타일 깊이는 **0부터 시작**하며, 0은 최상위(루트) 타일을 의미합니다.
1619
설정 가능한 깊이 범위는 **0 ~ 22**입니다.
1720

18-
기본값:
19-
- 최소 깊이: **0**
20-
- 최대 깊이: **14**
21+
기본 동작:
22+
- 최소 깊이는 사실상 **0**으로 고정됩니다.
23+
- 최대 깊이를 생략하면 입력 래스터 해상도를 기준으로 자동 계산됩니다.
2124

2225
최소 깊이는 최대 깊이보다 클 수 없습니다.
2326
```
24-
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" -max 18
25-
```
27+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --min 0 --max 18
28+
```
29+
30+
## 타일 깊이와 원본 래스터 해상도 가이드
31+
각 지형 타일은 남북 방향으로 `180 / 2^depth` 도를 차지합니다. 아래 표는 기본값인 지구 기준에서 타일 하나의 대략적인 남북 길이를 보여줍니다. 변환기에서 사용하는 지구 적도 반지름과 같은 값을 기준으로 계산했으므로, 정밀 측지 거리표라기보다 `maxDepth` 선택을 위한 실무 가이드로 보면 됩니다.
32+
33+
달 지형의 경우 아래 길이에 약 **0.2724**(`1,737,400 / 6,378,137`)를 곱해 참고하면 됩니다.
34+
35+
| Depth | 타일 하나의 남북 길이 (km) | 타일 하나의 남북 길이 (m) |
36+
| ---: | ---: | ---: |
37+
| 0 | 20,037.508 | 20,037,508 |
38+
| 1 | 10,018.754 | 10,018,754 |
39+
| 2 | 5,009.377 | 5,009,377 |
40+
| 3 | 2,504.689 | 2,504,689 |
41+
| 4 | 1,252.344 | 1,252,344 |
42+
| 5 | 626.172 | 626,172 |
43+
| 6 | 313.086 | 313,086 |
44+
| 7 | 156.543 | 156,543.034 |
45+
| 8 | 78.272 | 78,271.517 |
46+
| 9 | 39.136 | 39,135.758 |
47+
| 10 | 19.568 | 19,567.879 |
48+
| 11 | 9.784 | 9,783.940 |
49+
| 12 | 4.892 | 4,891.970 |
50+
| 13 | 2.445985 | 2,445.985 |
51+
| 14 | 1.222992 | 1,222.992 |
52+
| 15 | 0.611496 | 611.496 |
53+
| 16 | 0.305748 | 305.748 |
54+
| 17 | 0.152874 | 152.874 |
55+
| 18 | 0.076437 | 76.437 |
56+
| 19 | 0.038219 | 38.219 |
57+
| 20 | 0.019109 | 19.109 |
58+
| 21 | 0.009555 | 9.555 |
59+
| 22 | 0.004777 | 4.777 |
60+
61+
GeoTIFF에 적절한 `maxDepth`를 가늠하는 방법은 다음과 같습니다.
62+
- `gdalinfo` 또는 GIS 도구로 원본 래스터의 픽셀 크기를 확인합니다.
63+
- 픽셀 크기에 **256**을 곱해 256 샘플 타일 하나가 표현하는 지상 길이를 추정합니다.
64+
- 위 표에서 그 길이에 가까운 depth를 선택합니다. 자동 `maxDepth` 계산도 이 기준을 따르며, 타일 길이가 `픽셀 크기 * 256`보다 작아지는 지점에서 보통 한 단계 더 세밀한 depth를 선택합니다.
65+
66+
실무 예시는 다음과 같습니다.
67+
68+
| GeoTIFF 픽셀 크기 | 256 픽셀의 지상 길이 | 일반적인 `maxDepth` |
69+
| ---: | ---: | ---: |
70+
| 90 m | 23,040 m | 11 |
71+
| 30 m | 7,680 m | 13 |
72+
| 10 m | 2,560 m | 14 |
73+
| 5 m | 1,280 m | 15 |
74+
| 1 m | 256 m | 18 |
75+
76+
원본 래스터가 지원하는 해상도보다 훨씬 큰 `maxDepth`를 지정하면 실제 지형 디테일은 늘지 않고 타일 수, 처리 시간, 저장 용량만 증가합니다. 변환 속도나 결과물 크기를 줄여야 할 때는 더 작은 `maxDepth`를 사용합니다.
2677

2778
## 타일링 상세 표현 (Intensity)
2879
`-intensity` 또는 `-is` 옵션을 통해 타일링의 세부 표현 정도를 조절할 수 있습니다.
@@ -44,13 +95,12 @@ java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/
4495
```
4596

4697
## Terrain Normal 계산 (조명 처리)
47-
`-calculateNormals` 또는 `-cn` 옵션을 사용하여 Terrain Tiles의 normal 벡터를 계산할 수 있습니다.
48-
기본값은 `false`입니다.
98+
Terrain normal 계산은 기본적으로 활성화되며, 조명을 위한 `octvertexnormals` 확장을 생성합니다.
4999

50-
이 옵션을 활성화하면 변환 시간이 증가할 수 있으나,
51-
렌더링 시 광원(Lighting) 효과를 적용할 수 있습니다.
100+
normal 생성을 원하지 않는 경우 `--noCalculateNormals` / `-ncn` 옵션을 사용합니다.
101+
기존 호환성을 위해 `--calculateNormals` / `-cn` 옵션은 계속 허용되지만, 더 이상 지정할 필요는 없습니다.
52102
```
53-
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --calculateNormals
103+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --noCalculateNormals
54104
```
55105

56106
## Geoid 보정 파일 사용
@@ -65,7 +115,7 @@ DEM (Orthometric Height) + Geoid Height = Ellipsoid Height
65115
```
66116

67117
지원 파일 형식: **GeoTIFF**
68-
기본 내장 Geoid 모델: **EGM96**
118+
기본 내장 Geoid 모델: **EGM96**, **EGM2008**, **EGM84**
69119
```
70120
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "/input_path/geoid_file.tif"
71121
```
@@ -75,6 +125,16 @@ java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/
75125
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM96"
76126
```
77127

128+
기본 제공되는 EGM2008 2.5' Geoid 모델을 사용하려면 다음과 같이 입력합니다.
129+
```
130+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM2008"
131+
```
132+
133+
기본 제공되는 EGM84 30' Geoid 모델을 사용하려면 다음과 같이 입력합니다.
134+
```
135+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM84"
136+
```
137+
78138
---
79139

80140
# 변환 최적화 옵션

‎MANUAL.md‎

Lines changed: 71 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
updated at 2026-03-24 by znkim
2-
31
# Basic Conversion Options
42

53
## Simple conversion example (minimum options)
@@ -8,22 +6,75 @@ The following example shows a basic conversion of GeoTIFF data using the minimum
86
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output"
97
```
108

9+
Multiple input files or directories can be provided by repeating the input option:
10+
```bash
11+
java -jar mago-3d-terrainer.jar --input "/input_path/dem-a.tif" --input "/input_path/dem-b.tif" --output "/output_path/terrain_tiles_output"
12+
```
13+
1114
## Setting minimum / maximum tile depth
1215
You can define the minimum and maximum tile depth using the `-minDepth <value>` and `-maxDepth <value>` options.
1316
Short options are `-min <value>` and `-max <value>`.
1417

1518
Tile depth starts from 0, where 0 represents the root (top-level) tile.
1619
Valid depth values range from **0 to 22**.
1720

18-
Default values:
19-
- Minimum depth: **0**
20-
- Maximum depth: **14**
21+
Default behavior:
22+
- Minimum depth is effectively fixed at **0**.
23+
- If maximum depth is omitted, it is calculated automatically from the input raster resolution.
2124

2225
The minimum depth must not be greater than the maximum depth.
2326
```
2427
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --min 0 --max 18
2528
```
2629

30+
## Tile depth and source raster resolution guide
31+
Each terrain tile covers `180 / 2^depth` degrees in the north-south direction. The table below shows the approximate north-south length of one tile for the default Earth body. The values use the same Earth equatorial radius as the converter, so they are intended as a practical guide rather than a geodetic distance survey.
32+
33+
For lunar terrain, multiply these lengths by about **0.2724** (`1,737,400 / 6,378,137`).
34+
35+
| Depth | One tile north-south length (km) | One tile north-south length (m) |
36+
| ---: | ---: | ---: |
37+
| 0 | 20,037.508 | 20,037,508 |
38+
| 1 | 10,018.754 | 10,018,754 |
39+
| 2 | 5,009.377 | 5,009,377 |
40+
| 3 | 2,504.689 | 2,504,689 |
41+
| 4 | 1,252.344 | 1,252,344 |
42+
| 5 | 626.172 | 626,172 |
43+
| 6 | 313.086 | 313,086 |
44+
| 7 | 156.543 | 156,543.034 |
45+
| 8 | 78.272 | 78,271.517 |
46+
| 9 | 39.136 | 39,135.758 |
47+
| 10 | 19.568 | 19,567.879 |
48+
| 11 | 9.784 | 9,783.940 |
49+
| 12 | 4.892 | 4,891.970 |
50+
| 13 | 2.445985 | 2,445.985 |
51+
| 14 | 1.222992 | 1,222.992 |
52+
| 15 | 0.611496 | 611.496 |
53+
| 16 | 0.305748 | 305.748 |
54+
| 17 | 0.152874 | 152.874 |
55+
| 18 | 0.076437 | 76.437 |
56+
| 19 | 0.038219 | 38.219 |
57+
| 20 | 0.019109 | 19.109 |
58+
| 21 | 0.009555 | 9.555 |
59+
| 22 | 0.004777 | 4.777 |
60+
61+
To estimate a suitable `maxDepth` for a GeoTIFF:
62+
- Check the raster pixel size with `gdalinfo` or another GIS tool.
63+
- Multiply the pixel size by **256** to estimate the ground size represented by one 256-sample terrain tile.
64+
- Choose a depth whose tile length is near that size. The automatic `maxDepth` selection follows this idea and generally chooses the next finer depth once the tile length becomes smaller than `pixel size * 256`.
65+
66+
Practical examples:
67+
68+
| GeoTIFF pixel size | 256 pixels on the ground | Typical `maxDepth` |
69+
| ---: | ---: | ---: |
70+
| 90 m | 23,040 m | 11 |
71+
| 30 m | 7,680 m | 13 |
72+
| 10 m | 2,560 m | 14 |
73+
| 5 m | 1,280 m | 15 |
74+
| 1 m | 256 m | 18 |
75+
76+
Using a much larger `maxDepth` than the source raster supports increases tile count, processing time, and storage size without adding real terrain detail. Use a smaller `maxDepth` when you need faster conversion or lighter output.
77+
2778
## Tiling detail level (Intensity)
2879
You can control the level of tiling detail using the `-intensity` or `-is` option.
2980
The intensity value ranges from **1 to 16**, with a default value of **4**.
@@ -43,12 +94,12 @@ java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/
4394
```
4495

4596
## Terrain normal calculation (Lighting)
46-
Enable terrain normal calculation using the `-calculateNormals` or `-cn` option.
47-
Default value is `false`.
97+
Terrain normal calculation is enabled by default and adds the `octvertexnormals` extension for lighting.
4898

49-
This increases conversion time but allows lighting effects during rendering.
99+
Use `--noCalculateNormals` / `-ncn` to disable normal generation when smaller output or faster conversion is preferred.
100+
The legacy `--calculateNormals` / `-cn` option is still accepted for compatibility, but it is no longer required.
50101
```
51-
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --calculateNormals
102+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --noCalculateNormals
52103
```
53104

54105
## Using a geoid correction file
@@ -57,7 +108,7 @@ For terrain data stored in **orthometric height**, the geoid height is added to
57108
Formula:```DEM (Orthometric Height) + Geoid Height = Ellipsoid Height```
58109

59110
Supported format: **GeoTIFF**
60-
Built-in model: **EGM96**
111+
Built-in models: **EGM96**, **EGM2008**, **EGM84**
61112
```
62113
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "/input_path/geoid_file.tif"
63114
```
@@ -67,6 +118,16 @@ Using the built-in EGM96 model:
67118
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM96"
68119
```
69120

121+
Using the built-in EGM2008 2.5' model:
122+
```
123+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM2008"
124+
```
125+
126+
Using the built-in EGM84 30' model:
127+
```
128+
java -jar mago-3d-terrainer.jar --input "/input_path/geotiff_folder" --output "/output_path/terrain_tiles_output" --geoid "EGM84"
129+
```
130+
70131
---
71132

72133
# Conversion Optimization Options

‎README.md‎

Lines changed: 47 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ See: https://github.com/CesiumGS/quantized-mesh
99

1010
![Static Badge](https://img.shields.io/badge/Gaia3D%2C%20Inc-blue?style=flat-square)
1111
![Static Badge](https://img.shields.io/badge/QuantizedMesh-green?style=flat-square&logo=Cesium)
12-
![Static Badge](https://img.shields.io/badge/Jdk17-red?style=flat-square&logo=openjdk)
12+
![Static Badge](https://img.shields.io/badge/JDK21-red?style=flat-square&logo=openjdk)
1313
![Static Badge](https://img.shields.io/badge/Gradle-darkorange?style=flat-square&logo=gradle)
1414
![Static Badge](https://img.shields.io/badge/Docker%20Image-blue?style=flat-square&logo=docker)
1515

@@ -30,7 +30,7 @@ The built jar is created in the ```/dist``` directory.
3030
```
3131
gradlew jar
3232
```
33-
###### The java version used in the release is openjdk 17.
33+
###### The Java version used in the release is OpenJDK 21.
3434

3535
## Example help command
3636
```
@@ -42,44 +42,55 @@ Output:
4242
mago-3d-terrainer(dev-version) by Gaia3D, Inc.
4343
----------------------------------------
4444
Usage: command options
45-
-h, --help Print Help
46-
-lt, --leaveTemp Leave temporary files for debugging
47-
-j, --json Generate layer.json from terrain data
48-
-c, --continue Continue from last terrain generation. This option can be used when terrain creation is interrupted or fails.
49-
-i, --input <arg> [Required] Input directory path
50-
-o, --output <arg> [Required] Output directory path
51-
-l, --log <arg> Log file path
52-
-t, --temp <arg> Temporary directory path (default: {OUTPUT}/temp)
53-
-g, --geoid <arg> Set reference height option for terrain data.
54-
Geoid file path for height correction,
55-
(default: Ellipsoid)(options: Ellipsoid, EGM96 or GeoTIFF File Path)
56-
-min, --minDepth <arg> Set minimum terrain tile depth
57-
(default : 0)(options: 0 - 22)
58-
-max, --maxDepth <arg> Set maximum terrain tile depth
59-
(default : 14)(options: 0 - 22)
60-
-is, --intensity <arg> Set Mesh refinement intensity.
61-
(default: 4.0)
62-
-it, --interpolationType <arg> Set Interpolation type
63-
(default : bilinear)(options: nearest, bilinear)
64-
-pt, --priorityType <arg> Nesting height priority type options
65-
(default : resolution)(options: resolution, higher)
66-
-nv, --nodataValue <arg> Set NODATA value for terrain generating
67-
(default : -9999)
68-
-cn, --calculateNormals Add terrain octVertexNormals for lighting effect
69-
-ms, --mosaicSize <arg> Tiling mosaic buffer size per tile.
70-
(default : 16)
71-
-mr, --rasterMaxSize <arg> Maximum raster size for split function.
72-
(default : 8192)
73-
-b, --body <arg> Target celestial body for terrain generation
74-
(default : earth)(options: earth, moon)
75-
-md, --metadata [Experimental] Generate metadata for the terrain data.
76-
-wm, --waterMask [Experimental] Generate water mask for the terrain data.
77-
-d, --debug [DEBUG] Print more detailed logs.
45+
-h, --help Print help
46+
-q, --quiet Suppress all output except errors
47+
-lt, --leaveTemp Leave temporary files for debugging
48+
-j, --json Generate layer.json for terrain data
49+
-c, --continue Continue terrain generation from the previous run. Use this option when terrain generation is interrupted or fails.
50+
-m, --modify Modify existing terrain. Use this option when updating part of a terrain region.
51+
-ssr, --skipStandardizationResize Skip standardization and resizing process. This option can be used when the input data is already standardized and resized.
52+
-i, --input <arg> [Required] Input file or directory path. Repeatable.
53+
-o, --output <arg> [Required] Output directory path
54+
-l, --log <arg> Log file path
55+
-t, --temp <arg> Temporary directory path (default: {OUTPUT}/temp)
56+
-g, --geoid <arg> Set the height reference for terrain data.
57+
Geoid file path for height correction.
58+
(default: Ellipsoid)(options: Ellipsoid, EGM96, EGM2008, EGM84, or GeoTIFF file path)
59+
-min, --minDepth <arg> Set the minimum terrain tile depth. This is effectively fixed at 0.
60+
(default: 0)(options: 0 - 22)
61+
-max, --maxDepth <arg> Set the maximum terrain tile depth. If omitted, it is calculated automatically from the input raster resolution.
62+
(options: 0 - 22)
63+
-is, --intensity <arg> Set the mesh refinement intensity.
64+
(default: 4.0)
65+
-it, --interpolationType <arg> Set the interpolation type.
66+
(default: bilinear)(options: nearest, bilinear)
67+
-pt, --priorityType <arg> Set the height priority for overlapping terrain data.
68+
(default: resolution)(options: resolution, higher)
69+
-nv, --nodataValue <arg> Set the NODATA value for terrain generation.
70+
(default: -9999)
71+
-cn, --calculateNormals [Deprecated] Terrain octVertexNormals are generated by default.
72+
-ncn, --noCalculateNormals Disable generation of terrain octVertexNormals.
73+
-ms, --mosaicSize <arg> Set the tiling mosaic buffer size per tile.
74+
(default: 8)
75+
-mr, --rasterMaxSize <arg> Set the maximum raster size for splitting.
76+
(default: 4096)
77+
-md, --metadata [Experimental] Generate metadata for terrain data.
78+
-wm, --waterMask [Experimental] Generate a water mask for terrain data.
79+
-b, --body <arg> Set the celestial body for terrain generation.
80+
(default: earth)(options: earth, moon)
81+
-vb, --verbose Print verbose logs.
82+
-d, --debug [DEBUG] Print more detailed logs.
7883
```
7984
This is a simple Quantized-mesh conversion code with the required argument values.
8085
```
8186
java -jar mago-3d-terrainer-x.x.x.jar -input C:\data\geotiff-sample -output C:\data\geotiff-terrain-output -maxDepth 14
8287
```
88+
89+
Multiple input files or directories can be provided by repeating the input option:
90+
91+
```bash
92+
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
93+
```
8394
or
8495
```
8596
java -jar mago-3d-terrainer-x.x.x.x.jar -i C:\data\geotiff-sample -o C:\data\geotiff-terrain-output -max 14
@@ -134,7 +145,7 @@ For detailed documentation, including installation and usage instructions, pleas
134145
- Manual : [github.com/Gaia3D/mago-3d-terrainer](https://github.com/Gaia3D/mago-3d-terrainer/blob/main/MANUAL.md)
135146

136147
## Supported Java versions
137-
Supports long-term support (LTS) versions of the JDK, including JDK17 and JDK21.
148+
Requires JDK 21 or later. The release artifacts are built and tested with OpenJDK 21.
138149

139150
## License
140151
- mago 3DTerrainer is licensed under the MPL2.0 license (<https://www.mozilla.org/en-US/MPL/2.0/>).

0 commit comments

Comments
 (0)