Add Layouts and renderFacade task

docs/usage/parameters/Layouts.md

@@ -0,0 +1,88 @@
+
+# Layouts
+
+Layouts are a kind of structure that can adapt itself to fit a requested space.
+
+## Table of contents
+
+* [Stretchable Layout](#stretchable-layout)
+* [Repeat Layout](#repeat-layout)
+* [Concatenate Layout](#concatenate-layout)
+
+## Stretchable Layout
+
+Makes a structure stretchable by having one band per axis (row, column or layer) that gets repeated or omitted to fit the requested size.
+
+```yaml
+structure:
+  axes: x
+  blueprint: "rgb"
+  with:
+    "r": wool:red
+    "g": wool:green
+    "b": wool:blue
+stretchableAlongX:
+  at: 2
+  atLeast: 2
+  atMost: 5
+stretchableAlongY:
+  at: 1
+```
+
+Fields:
+  - `structure` (required): The structure to make stretchable
+  - `stretchableAlongX`/`Y`/`Z` (each optional): Strech parameters along x/y/z-axis. Omit to keep that fixed (non-stretchable).
+    - `at` (required): coordinate of the band to stretch
+    - `atLeast` (optional, default `1`): Minimum repetition of the band. `0` allows squeezing.
+    - `atMost` (optional, default `infinite`): Maximum repetition of the band.
+
+## Repeat Layout
+
+Repeats a layout along a given axis. If the repeated layout is resizable on that axis,
+it may be stretched to fill the requested size.
+
+```yaml
+repeat: otherLayout
+along: x
+atLeast: 1
+atMost: 2
+```
+
+Fields:
+  - `repeat` (required): The layout to repeat.
+  - `along` (required): Axis along which the layout is repeated (`x`, `y` or `z`)
+  - `atLeast` (optional, default `1`): Minimum repetitions of the layout. `0` allows the layout to be empty.
+  - `atMost` (optional, default `infinite`): Maximum repetitions of the layout.
+
+## Concatenate Layout
+
+Places several layouts side by side on a given axis, with priorities.
+
+It proceeds that way:
+1. All layouts gets their minimal required space (minimum size).
+1. Higher priority layouts (higher number) start first and get as much remaining space as possible.
+1. If space still remains, continue with lower priorities until no space left.
+
+If serveral layouts have the same priority, the available space is distributed between them as evenly as possible.
+
+```yaml
+concatenate:
+  - priority: 1
+    otherLayout
+  - priority: 2
+    anotherLayout
+along: y
+zPolicy: keep
+```
+
+Fields:
+- `concatenate` (required): List of layouts to place side by side. Each layout definition may have an extra `priority` field (default `0`) to set its order of priority (higher values get space first).
+- `along` (required): Axis along which the layouts are placed (`x`, `y` or `z`)
+- `x`/`y`/`zPolicy` (optional, default `inherit`): Policy for the x/y/z-axis (only for axes other than `along` axis).
+
+Policies control how other axes are sized:
+| Policy    | Constraint on concerned axis                            |
+|:----------|:--------------------------------------------------------|
+| `inherit` | Use parent policy (layout or task).                     |
+| `adjust`  | Force same size for all child layouts.                  |
+| `keep`    | Keep child layouts sizes (different sizes are allowed). |

docs/usage/parameters/TileTasks.md

@@ -20,10 +20,13 @@ Each task has a `type`, optional dependencies to other tasks (in `after`), and o
   * [`fillBetweenHeightmapAndValue`](#fillbetweenheightmapandvalue)
   * [`renderBuildings`](#renderbuildings)
   * [`setSpawn`](#setspawn)
+  * [`renderFacades`](#renderfacades)
 * [Tasks operating on heightmaps](#tasks-operating-on-heightmaps)
   * [`populateHeightmap`](#populateheightmap)
   * [`copyHeightmap`](#copyheightmap)
   * [`computeHeightmapStats`](#computeheightmapstats)
+* [Tool tasks](#tool-tasks)
+  * [`buildLayout`](#buildlayout)
 
 ## Organizational tasks
 
@@ -162,7 +165,7 @@ The blueprint shows five successive vertical slices of the structure. This will
 
 ### `renderPoints`
 
-Renders 3d points as a placeable. 
+Renders 3d points as a placeable.
 
 #### Extra parameters
 
@@ -278,6 +281,37 @@ x: 2
 y: -1
 ```
 
+### `renderFacades`
+
+Renders facades using [layouts](Layouts.md) from 2D shapes.
+Layouts are tried in order, the first one that can fit the requested space is used.
+
+#### Extra parameters
+
+- `models`: [Selection of models](ModelSelection.md) to render (required, models must be convertible to 2d shapes)
+- `height` (string): Name of the metadata containing the desired height. (required)
+- `altitude` (string): Name of the metadata containing the altitude. (required)
+- `build`: List of [layouts](Layouts.md) to try. Default axis policies are `ADJUST` on `X` and `Z`, `KEEP` on `Y`.
+
+See [Layouts](Layouts.md) for more information about layouts
+
+#### Example
+
+```yaml
+type: renderFacades
+models: buildings
+height: height
+altitude: ground-floor-altitude
+build:
+  - structure:
+      at: [ 0, -1..0, 0 ]
+      put: stone
+    stretchableAlongX:
+      at: 0
+    stretchableAlongZ:
+      at: 0
+```
+
 ## Tasks operating on heightmaps
 
 ### `populateHeightmap`
@@ -343,3 +377,36 @@ compute:
   maximum: maximum-ground-altitude
   minimum: minimum-ground-altitude
 ```
+
+## Tool tasks
+
+These tasks are not intended to be used to create worlds from geographical data but rather to help parameter files development.
+
+### `buildLayout`
+
+This task builds a structure of a given size from a layout (or a fallback list of layouts) and places it into the world at a given position.
+
+#### Extra parameters
+
+- `build` (required) : [Layouts](Layouts.md) or list of layouts to build (first buildable will be used).
+- `at` (required): Where to place the built layout.
+- `size` (optional): wanted size:
+  - `x` / `y` / `z` (optional, defaults to minimum layout size): wanted size in each dimension
+- `policies` (optional): size policies to apply in each three dimensions:
+  - `x` / `y` / `z` (optional, default `adjust`): `keep` means layout sizes are kept as is, `adjust` meands layout sizes should adjust to content.
+
+See [Layouts](Layouts.md) for more information about layouts and policies.
+
+#### Example
+```yaml
+type: buildLayout
+build:
+  - ... # First layout candidate
+  - ... # Second layout candidate (fallback)
+  - ...
+at: [ 10, 20, 0 ]
+size:
+  x: 4
+policies:
+  x: keep
+```

examples/formats/minecraft.yaml

@@ -3,7 +3,6 @@ references:
   - &voxel-stone minecraft:stone
   - &voxel-dirt minecraft:dirt
   - &voxel-cobble minecraft:cobblestone
-  - &voxel-empty minecraft:air
   - &voxel-building-ground minecraft:stone_bricks
   - &voxel-grass minecraft:grass_block
   - &voxel-glass minecraft:glass
@@ -38,3 +37,21 @@ references:
         at: [ 0, 0, 0..5 ]
   - &voxel-water minecraft:water
   - &voxel-air minecraft:air
+  - &corner-material minecraft:smooth_red_sandstone
+  - &base-material minecraft:sandstone
+  - &other-material minecraft:red_sandstone
+  - &borders-material minecraft:smooth_red_sandstone
+  - &cornice-material minecraft:smooth_red_sandstone
+  - &lintel-material minecraft:cut_sandstone
+  - &facade-residential-materials
+    "-": *base-material
+    "+": *other-material
+    "O": *borders-material
+    "*": minecraft:tinted_glass
+    "=": *lintel-material
+    "|": minecraft:jungle_fence
+  - &modern-wall minecraft:clay
+  - &modern-glass minecraft:tinted_glass
+  - &modern-materials
+    "O": *modern-wall
+    "*": *modern-glass

examples/formats/minetest.yaml

@@ -3,7 +3,6 @@ references:
   - &voxel-stone default:stone
   - &voxel-dirt default:dirt
   - &voxel-cobble default:cobble
-  - &voxel-empty default:air
   - &voxel-building-ground default:stonebrick
   - &voxel-grass default:dirt_with_grass
   - &voxel-glass default:glass
@@ -32,3 +31,21 @@ references:
         at: [ 0, 0, 0..5 ]
   - &voxel-water default:water_source
   - &voxel-air air
+  - &corner-material default:desert_sandstone_block
+  - &base-material default:sandstone
+  - &other-material default:desert_stone
+  - &borders-material default:desert_sandstone_block
+  - &cornice-material default:desert_sandstone_block
+  - &lintel-material default:sandstonebrick
+  - &facade-residential-materials
+    "-": *base-material
+    "+": *other-material
+    "O": *borders-material
+    "*": default:obsidian_glass
+    "=": *lintel-material
+    "|": default:fence_junglewood
+  - &modern-wall default:clay
+  - &modern-glass default:obsidian_glass
+  - &modern-materials
+    "O": *modern-wall
+    "*": *modern-glass