Render a minimap of the world - MINALAC-86

docs/usage/parameters/Minimap.md

@@ -0,0 +1,24 @@
+# Minimap
+
+A minimap is a scaled 2D representation of the generated 3D world.
+
+## Stored minimap
+
+Minimaps are created at the beginning of the generation process, remain available throughout the generation, and can be accessed by their names.
+
+You can generate multiple minimaps at the same time by declaring them with different names.
+
+In the example below, two distinct minimaps named overworld and onlyWater are declared:
+
+```yaml
+minimaps:
+  # A minimap named 'overworld' using the default settings
+  overworld: {}
+
+  # A minimap named 'onlyWater' with a custom maximum size
+  onlyWater:
+    size: 200
+```
+
+Fields:
+- `size` : Maximum size in pixel of the longest side of the minimap. By default, this field is set to `1000`.

docs/usage/parameters/Parameters.md

@@ -14,10 +14,12 @@ Generator makes a heavy use of parameters. Generation is described in Yaml (or J
 Only root Yaml parameters are described here. More specific aspects could be found in these other files:
 
 * [FetchDataTask.md](FetchDataTask.md): Description of tasks for fetching data (see [TileTasks.md](TileTasks.md)).
+* [Minimap.md](Minimap.md).
 * [Heightmaps.md](Heightmaps.md): Declaration and usage of heightmaps.
 * [ModelSelection.md](ModelSelection.md): Selection of models (see [TileTasks.md](TileTasks.md)).
 * [ModelValues.md](ModelValues.md): Dynamic numeric values computed from models (see [TileTasks.md](TileTasks.md)).
 * [Placeables.md](Placeables.md): Description of things that can be placed in resulting world (see [TileTasks.md](TileTasks.md)).
+* [Tasks.md](Tasks.md): Tasks that are executes anywhere.
 * [TileTasks.md](TileTasks.md): Tasks that can be run on a generation tile.
 
 ## Example
@@ -34,6 +36,10 @@ references:
         at: [ 0, 0, 0 ]
       - put: default:dirt
         at: [ 0, 0, -10..-1 ]
+
+minimaps:
+  world: {}
+
 area:
   center:
     latitude: 48.845
@@ -98,6 +104,7 @@ forEachTile:
 
 - `worldName`: World name (text, default `Minalac`)
 - `references`: Ignored field where references (or other content) can be put in
+- `minimaps`: [Minimaps](Minimap.md) to be created and accessible throughout the generation
 - `area`: Area to be rendered
   - `center`: Coordinates of the area's center point, expressed in the commonly used coordinate system (EPSG:4326)
     - `latitude`: latitude in decimal degrees

docs/usage/parameters/Tasks.md

@@ -8,6 +8,14 @@ Generic schedules such as the `afterAllTiles` schedule can only execute generic
 
 Each task has a `type`, optional dependencies on other tasks (using `after`), and specific parameters depending on its type.
 
+## Table of contents
+
+* [Dependencies](#dependencies)
+  * [Scope constraints](#scope-constraints)
+* [Tasks operating on minimaps](#tasks-operating-on-minimaps)
+  * [`applyShadingMinimap`](#applyshadingminimap)
+  * [`saveMinimap`](#saveminimap)
+
 ## Dependencies
 
 Dependencies allow to control execution order of tasks. Optional `after` field lists names of every other tasks that should run before the task it belongs to.
@@ -59,3 +67,48 @@ afterAllTiles:
     after: a # Error: 'a' is not defined in this scope
     type: noOperation
 ```
+
+## Tasks operating on minimaps
+
+### `applyShadingMinimap`
+
+Applies post-processing shading to a minimap using its heightmap.
+
+This task simulates sunlight by calculating the directional terrain slope, adjusting pixel brightness according to how the terrain is oriented relative to a light source.
+This enhances the visual perception of elevation changes.
+
+#### Extra parameters
+
+- `minimap` (required): Name of the minimap to shade.
+- `shadowIntensity` (optional, default is `0.5`): The intensity of the shading effect (should be between 0.0 and 1.0).
+- `sunDirection` (optional, default is `90`): The direction of the simulated light source, expressed in degrees.
+
+#### Example
+
+```yaml
+type: applyShadingMinimap
+minimap: overworld
+shadowIntensity: 0.8
+sunDirection: 45
+```
+
+### `saveMinimap`
+
+Export the Minimap to an image file.
+
+The `saveMinimap` task requires the `populateMinimap` task to be executed on each tile beforehand. `populateMinimap` generates the actual map data; without it, the saved image will be empty.
+
+#### Extra parameters
+
+- `minimap` (required): name of the minimap to save.
+- `destination` (required): relative path where the rendered minimap image will be saved. This path is relative to the world's root directory.
+- `format` (optional): format of the minimap to render (ex: `jpeg`, `png`, `gif`, ...).
+
+#### Exemple
+
+```yaml
+type: saveMinimap
+minimap: overworld
+destination: overworld-minimap.png
+format: png
+```

docs/usage/parameters/TileTasks.md

@@ -24,6 +24,8 @@ Each task has a `type`, optional dependencies to other tasks (in `after`), and o
   * [`populateHeightmap`](#populateheightmap)
   * [`copyHeightmap`](#copyheightmap)
   * [`computeHeightmapStats`](#computeheightmapstats)
+* [Tasks operating on minimaps](#tasks-operating-on-minimaps)
+  * [`populateMinimap`](#populateminimap)
 
 ## Organizational tasks
 
@@ -343,3 +345,27 @@ compute:
   maximum: maximum-ground-altitude
   minimum: minimum-ground-altitude
 ```
+
+## Tasks operating on minimaps
+
+### `populateMinimap`
+
+Populates a minimap from each tile.
+
+This task must be executed for all tiles before calling `saveMinimap`. `populateMinimap` gathers the necessary voxel data into the minimap structure; without this step, `saveMinimap` will produce an empty image.
+
+#### Extra parameters
+
+- `minimap` (required): Name of the minimap to populate.
+- `colors` (required): Mapping of voxel type identifiers to their display colors (RGBA).
+
+#### Example
+
+```yaml
+type: populateMinimap
+minimap: overworld
+colors:
+  water: [64, 64, 255, 180] 
+  white_wool: [255, 255, 255]
+  black_wool: [25, 25, 25]
+```

examples/formats/minecraft.yaml

@@ -38,3 +38,18 @@ references:
         at: [ 0, 0, 0..5 ]
   - &voxel-water minecraft:water
   - &voxel-air minecraft:air
+  - &minimap-color-palette
+      # https://minecraft.wiki/w/Map_item_format#Color_table
+      minecraft:stone: [112, 112, 112]
+      minecraft:dirt: [151, 109, 77]
+      minecraft:cobblestone: [112, 112, 112]
+      minecraft:stone_bricks: [112, 112, 112]
+      minecraft:grass_block: [127, 178, 56]
+      minecraft:podzol: [129, 86, 49]
+      minecraft:dirt_path: [151, 109, 77]
+      minecraft:fern: [0, 124, 0]
+      minecraft:oak_leaves: [0, 124, 0]
+      minecraft:birch_leaves: [0, 124, 0]
+      minecraft:water: [64, 64, 255, 180] 
+      minecraft:white_wool: [255, 255, 255]
+      minecraft:black_wool: [25, 25, 25]

examples/formats/minetest.yaml

@@ -32,3 +32,19 @@ references:
         at: [ 0, 0, 0..5 ]
   - &voxel-water default:water_source
   - &voxel-air air
+  - &minimap-color-palette
+      # https://github.com/luanti-org/minetestmapper/blob/master/colors.txt
+      default:stone: [97, 94, 93]
+      default:dirt: [97, 67, 43]
+      default:cobble: [89, 86, 84]
+      default:stonebrick: [102, 99, 98]
+      default:dirt_with_grass: [64, 111, 26]
+      default:dirt_with_rainforest_litter: [76, 39, 10]
+      default:dirt_with_coniferous_litter: [109, 90, 71]
+      default:junglegrass: [67, 110, 28]
+      default:leaves: [36, 55, 29]
+      default:aspen_leaves: [72, 105, 29]
+      default:water_source: [39, 66, 106, 128]
+      wool:white: [220, 220, 220]
+      wool:black: [30, 30, 30]
+      default:snowblock: [225, 225, 238]

examples/places/meije.yaml

@@ -0,0 +1,10 @@
+# A mountaineering center & a resort offering extreme skiing distinguish this snow-capped mountain.
+worldName: Meije
+verticalScale: 1.0
+horizontalScale: 1.0
+area:
+  center:
+    latitude: 45.005
+    longitude: 6.307
+  extentX: 2459
+  extentY: 2145