[[TOC]]

The [source:ps/trunk/binaries/data/mods/public/maps/random/heightmap heightmap] library contains functionality for global heightmap/reliefmap manipulation for random maps.

== What is a heightmap? ==
A heightmap or reliefmap is an array of map width +1 arrays of map depth +1 numbers. The values define how high a given vertex between terrain tiles is compared to the default water level (not that of the map!) in meters. By default the heightmap is stored in `g_Map.height` (see the map object in [source:ps/trunk/binaries/data/mods/public/maps/random/rmgen/map.js map.js]). The limits are given by the engine and are stored in [source:ps/trunk/binaries/data/mods/public/maps/random/rmgen/library.js library.js] of the more fundamental [wiki:Rmgen_Library rmgen] library:
 * `SEA_LEVEL` The default water height of 20 meters (above the minimum value) that will count as 0 for the height values in the heightmap
 * `MAX_HEIGHT_RANGE` The difference of minimum and maximum height values the engine allows, roughly 712 (values out of range will be cut to minimum and maximum value)
 * `MIN_HEIGHT` The minimum value of a heightmap of -20 (not cut by the engine)
 * `MAX_HEIGHT` The maximum value of a heightmap of roughly 692
Between those vertices the terrain tiles are placed (which is why there is one tile less in x/y direction then vertices).
To get a better feeling for what one heightmap unit means for random maps: Terrain tile width = 4 meters.

== General heightmap functionality ==
The file [source:ps/trunk/binaries/data/mods/public/maps/random/heightmap/heightmap.js heightmap.js] contains the fundamental tools to work with heightmaps.

 * `getMinAndMaxHeight` Takes a heightmap and returns an object with properties `min` and `max`, the minimum and maximum height value present in a heightmap.
 * `rescaleHeightmap` Rescales a heightmap's height values linear to have minimum and maximum as given by the arguments. `ToDo`: Add a height to be unchanged (e.g. the water height to preserve the costline) and rescale above/below that value seperately. Logarithmic/exponential scaling would also be nice with the base as parameter.
 * `getStartLocationsByHeightmap` Searches a heightmap for a given number of points within a given height range and distance to the map border and tries to maximize the distance between the points returning them in a list.
 * `distributeEntitiesByHeight` Places entities/actors randomly chosen from a given list in a specific height range while avoiding given points (e.g. start locations) and the map border by the given distance.
 * `setRandomHeightmap` Sets a given heightmap to entirely random values. This is mainly meant for using erosion/smoothing on it later to get a realistic over all map shape (or test stability of erosion/smoothing functions)
 * `setBaseTerrainDiamondSquare` A method to set a heightmap to a realistic shape within the given height range limits (they might not be reached though). The `initialHeightmap` defines the global shape. The smoothness parameter can be chosen between 0 (uniform in roughness on all scales so quite rough even at small scales) and 1 (roughness decreases with smaller scales exponentially so quite smooth on small scales).
 * `globalSmoothHeightmap` Smoothes the heightmap depending on the adjacent tiles height. The `strength`value should be chosen between 0 (no effect at all) and 1 (quite strong smoothing). To get an even stronger smoothing effect apply it multiple times (rather than increasing the strength above 1). This can be seen as a very simple erosion function (e.g. erosion by decay and gravity). To get directional effects an assymetrical smoothMap can be used (e.g. to simulate wind/sun driven erosion).
 * `rectangularSmoothToHeight` Pushes the center of a rectangular region towards a target height while preserving the original height and shape at the edges.

Further planned functions: `getTileCenteredHeightmap` e.g. to paint tiles by height, `getInclineMap` a vector map e.g. for water driven erosion, `getSlopeMap` a scalar map e.g. for painting cliffs.

== Erosion ==
WIP. It's planned to put (more complex) erosion functionality (like water driven erosion) in a separate file.

== Painting terrain by height and inclination ==
WIP. A fully automated method to paint the whole map realistically will go here. It is planned to make use of the biome system (the current biome functions are not sufficient though).

== Local heightmap manimulation and window functions ==
WIP. All global heightmap functionalities can be used locally by manipulating a partial heightmap and fuse that manipulated part back into the original heightmap with appropriate windows functions (that fullfill the boundary conditions).