TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IHeightmap in Tinman.Terrain.Heightmaps

A heightmap provides elevation and surface color data for a terrain.

interface IHeightmap extends IHeightmapLayers
  IHeightmapOps
  IMapEntity
  base of Heightmap
  IHeightmapDataset
  IHeightmapShape

Remarks

Heightmap data is returned using HeightmapSample values for individual heightmaps samples, HeightmapRegion objects for heightmap sample blocks and HeightmapSamples for chunks of unrelated heightmap samples.

Attributes

CanUpdate

Does this map allow updates to its content (i.e. sample data and/or metadata)?

property CanUpdate { get }
type bool
value true if the map content can be updated, false if not.
inherited IMapEntity.CanUpdate

Georef

Returns georeferencing information.

property Georef { get }
type Raster
value The georeferencing object or null if no georeferencing is available.
inherited IGeorefInfo.Georef

Height

Number of heightmap samples along the Y-axis.

property Height { get }
type int32
value [>0] Heightmap height, in samples.

Horizontal

Returns the estimated horizontal resolution in terrain-space.

property Horizontal { get }
type float64
value [>0] The ground sample distance, in Metre.

See also:

IGeorefInfo.Georef

IsEmpty

Is this an immutable heightmap which only contains default sample data?

property IsEmpty { get }
type bool
value true if all samples of this heightmap are equal to Default, false if not.

IsScaled

Has this heightmap been scaled (either directly or indirectly)?

property IsScaled { get }
type bool
value true if the heightmap contains scaled data, false if not.

See also:

IHeightmapOps.Scale

LayerMask

The mask of heightmap layers this object uses.

property LayerMask { get }
type HeightmapLayer
value Bitwise combination of HeightmapLayer values.
inherited IHeightmapLayers.LayerMask

Remarks:

These heightmap layers store actual terrain data:

Missing data is represented with the Coverage layer. It describes how much information is present in a stored heightmap sample. The semantics of coverage with heightmap samples is the same as premultiplied alpha with texture samples. A LayerMask without Coverage means that all samples are fully solid. If a LayerMask contains the Coverage layer but no others, the coverage values are used to represent 'holes' in the terrain (e.g. creating holes for caves, tunnels, etc.).

LifecycleState

Returns the lifecycle state of this object.

property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited ILifecycleState.LifecycleState

Map

Returns a MapInfo value that describes the used map raster.

property Map { get }
type MapInfo
value The map info value.
inherited IMapInfo.Map

OnUpdated

Event for listening to updates made to this heightmap.

property OnUpdated { get }
type IEventGeneric<HeightmapEventArgs>
value [not-null] The event object.

Remarks:

This event will be fired by the thread that performs the map update.

Size

Cubemap size of heightmap.

property Size { get }
type int32
value [pow2+1] Heightmap size, in samples.

Type

The heightmap type (rectangular or cubic).

property Type { get }
type MapType
value The heightmap type.

Vertical

Returns the terrain-space range of elevation values.

property Vertical { get }
type VerticalRange
value The terrain-space elevation range, in vertical units (see VerticalUnit).

Remarks:

The default value is Default if Elevation or Displacement is present and None otherwise.

Width

Number of heightmap samples along the X-axis.

property Width { get }
type int32
value [>0] Heightmap width, in samples.

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited IDisposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Border

Pads this heightmap to the smallest fitting size of 2^n+1.

[OwnerReturn, OwnerThis]
method Border (HeightmapSample borderSample, int32 borderFalloff)
type IHeightmap
params borderSample The border heightmap sample.
  borderFalloff [>0] Width of the border falloff region, in heightmap samples.
returns [not-null] The padded heightmap.
inherited IHeightmapOps.Border

Remarks:

This method will add a border region at the right and bottom edges of a rectangular heightmap (see Rect). A smooth falloff is computed at the heightmap edges in order to avoid unnecessary triangles being created by CLOD mesh refinement for overly sharp corners.

Clip

Clips away portions of this heightmap, according to the Coverage layer of the given heightmap.

[OwnerReturn, OwnerThis]
method Clip ([Owner] IHeightmap mask, bool inverse = false)
type IHeightmap
params mask [not-null] The heightmap that is used as the clip mask (see remarks).
  inverse Invert the coverage values in mask before clipping? Defaults to false.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.Clip

Remarks:

The coverage values of the returned heightmap are computed like this:

inverse == false : c_out = c_in * c_mask
inverse == true  : c_out = in * (1 - c_mask)
where c_out is the normalized coverage value (i.e. in the range [0..1]) of the returned heightmap, c_in is the normalized coverage value of this heightmap and c_arg is the normalized coverage value of mask.

Combine

Adds detail to this heightmap by combining it with the given heightmap.

[OwnerReturn, OwnerThis]
method Combine ([Owner] IHeightmap detail, ColorOp textureOp = ColorOp.Blend)
type IHeightmap
params detail [not-null] The detail heightmap.
  textureOp The color operation to apply to the Texture layer, if present. Defaults to Blend.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.Combine

Remarks:

The heightmap samples of this heightmap (source) are modified using the samples of the given detail heightmap (detail) according to these rules:

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
method Dispose ()
inherited IDisposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Flush

Flushes all cached data.

method Flush ()
inherited IFlushable.Flush

Remarks:

Performing a flush may result in I/O work. Depending on the semantics of the implementing class, this work may need to be wrapped in special Begin / End method calls. See the documentation of the implementing classes for details.

In case this object represents a read-only resource, calling the Flush method has no effect.

GetRegion

Reads a block of samples from the heightmap.

[ThreadSafe]
method GetRegion (CubemapFaceRect region, HeightmapLayer layers = HeightmapLayer.All, int32 step = 1, HeightmapRegion buffer = null, int32 bufferX = 0, int32 bufferY = 0, bool smooth = false)
type HeightmapRegion
params region The rectangular cubemap face region to fetch.
  layers The heightmap layers to fetch. Defaults to All.
  step [pow2] Step distance between samples in region. Defaults to 1.
  buffer The output heightmap sample buffer. If null or too small, a new buffer will be created. Defaults to null.
  bufferX [>=0] X-coordinate of top-left corner of target rectangle in buffer. Defaults to 0.
  bufferY [>=0] Y-coordinate of top-left corner of target rectangle buffer. Defaults to 0.
  smooth Apply smooth filtering?
returns The heightmap buffer or null if there are no samples to fetch and buffer is null.

Remarks:

The region coordinates will be aligned to the closest multiple of the step distance. See StepAlign for details.

All heightmap samples that lie outside of the valid coordinate range of this heightmap have a Coverage of 0.

Only the heightmap layers (excluding Coverage) present in layers and the LayerMask of this heightmap will be filled in buffer. The Coverage layer will be filled if it is contained in layers, regardless of whether it is defined by LayerMask or not.

This method will not set Horizontal or Vertical in buffer resp. the returned buffer. The calling code is responsible for doing so if necessary.

See also:

HasRegion

GetSample

Reads a single sample from the heightmap.

[ThreadSafe]
method GetSample (int32 x, int32 y, int32 z = 0)
type HeightmapSample
params x X-coordinate of sample.
  y Y-coordinate of sample.
  z Z-coordinate of sample. Defaults to 0 (i.e. NegZ).

Remarks:

The returned heightmap sample will store values for each layer in LayerMask, all other values will have their respective default value. If the heightmap sample lies outside of the valid coordinate range of this heightmap, it will have a Coverage of 0, even if LayerMask does not contain the Coverage layer.

GetSamples

Reads multiple samples from the heightmap in a bulk operation.

[ThreadSafe]
method GetSamples (Vec3I[] xyz, int32 count, HeightmapSamples buffer, HeightmapLayer layers = HeightmapLayer.All)
params xyz [not-null] Array of cubemap coordinates of heightmap map samples to fetch. The coordinates must be specified for a heightmap of size MaxSize. Each heightmap implementation will translate these normalized coordinates into its own size using bit shifting. This way the coordinates array can be shared by heightmaps of different sizes.
  count [>=0] Total number of heightmap samples to fetch.
  buffer [not-null] The heightmap sample buffer to use. If null or too small, a new buffer will be created.
  layers The heightmap layers to fetch. Defaults to All.

Remarks:

All heightmap samples that lie outside of the valid coordinate range of this heightmap will have a Coverage or 0.

Only the heightmap layers (excluding Coverage) present in layers and the LayerMask of this heightmap will be filled in buffer. The Coverage layer will be filled if it is contained in layers, regardless of whether it is defined by LayerMask or not.

HasRegion

Determines if this heightmap contains data in the given region.

[ThreadSafe]
method HasRegion (CubemapFaceRect region, CoverageFlags flags = CoverageFlags.Some)
type CoverageFlags
params region The region to check for data.
  flags The coverage flags that need to be determined. Using specific flags here will allow implementations to early-exit. Defaults to Some (i.e. all flags).
returns The resulting flag bits (contains at least those bits defined by flags ).

Remarks:

The following semantic relaxations can be exploited by implementing methods in order to improve performance:

Merge

Merges the given heightmap with this one. The coverage of both heightmaps will be taken into account during merging.

[OwnerReturn, OwnerThis]
method Merge ([Owner] IHeightmap second)
type IHeightmap
params second [not-null] The second heightmap.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.Merge

Remarks:

Merged heightmaps fill data into heightmap samples in order, with heightmaps at a later stage overwriting sample data written by heightmaps of an earlier stage.

Both heightmaps (this one and second) will be scaled to the maximum possible size.

Scale

Returns a scaled version of this heightmap.

[OwnerReturn, OwnerThis]
method Scale (int32 newSize)
type IHeightmap
params newSize [pow2+1] The scaled internal size (see Type). The minimum internal size is MinSize.
returns [not-null] The scaled heightmap.
inherited IHeightmapOps.Scale

Remarks:

The maximum upscaling factor for heightmaps is 65536, so the given condition should be met when upscaling a heightmap (otherwise only the 16 most significant bits of the interpolation factor will be used):

(newSize - 1) / (Size - 1) <= 65536
where newSize is the new heightmap size and Type is the current size of this heightmap.

Split

Splits the layers of this heightmap.

[OwnerReturn, OwnerThis]
method Split (HeightmapLayer layers)
type IHeightmap
params layers The heightmap layers to retain in the split heightmap.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.Split

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

ToPyramid

Wraps this heightmap in a pixel pyramid.

[OwnerReturn, OwnerThis]
method ToPyramid (int32 tileSize = 256, int32 tilePad = 0, int32 levels = 0, IPixelLayer pixelLayer = null, PyramidFlags flags = PyramidFlags.None)
type IPixelPyramid
params tileSize [pow2] The tile size. Defaults to 256.
  tilePad [>=0] The tile padding. Defaults to 0.
  levels [>=0] Defines how many pyramid levels (starting at the bottommost level) shall contain data. The heightmap sample step is 1 for the bottommost level and is multiplied by two for each parent level. If 0, all pyramid levels will contain data. Defaults to 0.
  pixelLayer Optional pixel layer to use. Defaults to null.
  flags Optional pyramid flags. Defaults to None.
returns [not-null] The pixel pyramid.
inherited IHeightmapOps.ToPyramid

TransformRange

Translates the normalized elevation values of this heightmap to the given range.

[OwnerReturn, OwnerThis]
method TransformRange (VerticalRange range, UnitOfMeasure unit = null, bool reinterpret = false)
type IHeightmap
params range The range to translate to (see Vertical).
  unit The vertical unit of range. If null, Metre will be used. Defaults to null.
  reinterpret Keep elevation values of this heightmap and reinterpret them according to range and unit, instead of scaling them? Defaults to false.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.TransformRange

UpdateGeoref

Updates georeferencing data of this heightmap.

[ThreadSafe]
method UpdateGeoref (Raster georef)
params georef The new georeferencing data or null.
inherited IMapEntity.UpdateGeoref

See also:

IMapEntity.CanUpdate

UpdateRange

Updates the vertical range of this heightmap.

[ThreadSafe]
method UpdateRange (VerticalRange range)
params range The new vertical range.

See also:

IMapEntity.CanUpdate

UpdateRegion

Updates a region of this heightmap in an atomic operation.

[ThreadSafe]
method UpdateRegion (CubemapFaceRect region, HeightmapRegion buffer, HeightmapRegionDelegate combine = null, HeightmapLayer layers = HeightmapLayer.All, int32 bufferX = 0, int32 bufferY = 0, object userData = null)
params region The cubemap face region to update.
  buffer [not-null] The heightmap sample buffer to use (see remarks).
  combine Optional delegate for combining source and target heightmap samples. Defaults to null.
  layers The heightmap layers to update.
  bufferX [>=0] X-coordinate of top-left sample in buffer to use. Defaults to 0.
  bufferY [>=0] Y-coordinate of top-left sample in buffer to use. Defaults to 0.
  userData Optional user data object to pass to combine. Defaults to null.

Remarks:

Depending on the values passed to buffer and combine, the following operation is performed by this method:

See also:

IMapEntity.CanUpdate

UseColorRamp

Return a heightmap that computes texture colors using an elevation-based color ramp.

[OwnerReturn, OwnerThis]
method UseColorRamp (IColorRamp colorRamp)
type IHeightmap
params colorRamp [not-null] The color ramp to use.
returns [not-null] The resulting heightmap.
inherited IHeightmapOps.UseColorRamp

Remarks:

The terrain-space values of the Elevation layer (according to the vertical range and unit of the heightmap) are fed into the color ramp. The resulting diffuse color is used as the Texture layer.

Extensions

ComputePosition

Computes the terrain-space position of the given heightmap sample.

[ThreadSafe]
method ComputePosition (int32 heightmapX, int32 heightmapY, int32 heightmapZ = 0)
type Vec3D
params heightmapX Heightmap X-coordinate.
  heightmapY Heightmap Y-coordinate.
  heightmapZ Heightmap Z-coordinate.
returns The terrain-space position or Undefined if the georeference is incomplete.

CopySamples

Copies samples from this heightmap to a new dataset.

[OwnerReturn, OwnerThis]
method CopySamples (Path target, IDatasetInfo info = null, PixelFormat format = PixelFormat.Truecolor | PixelFormat.SixteenBits)
type IOperation
params target [not-null] Path to output dataset.
  info Optional dataset metadata to use. If null, metadata will be copied from source dataset, if present. Defaults to null.
  format The pixel format to use for choosing the output heightmap format (see ForAll). This parameter is ignored when the source heightmap is a IHeightmapDataset: in this case, the source heightmap format will be used (see SampleFormat).
returns [not-null] The background operation.

GetSampleV

Reads a single sample from the heightmap.

[ThreadSafe]
method GetSampleV (Vec2I v)
type HeightmapSample
params v Coordinates of sample.

Remarks:

The returned heightmap sample will store values for each layer in LayerMask, all other values will have their respective default value. If the heightmap sample lies outside of the valid coordinate range of this heightmap, it will have a Coverage of 0, even if LayerMask does not contain the Coverage layer.


Reads a single sample from the heightmap.

[ThreadSafe]
method GetSampleV (Vec3I v)
type HeightmapSample
params v Coordinates of sample.

Remarks:

The returned heightmap sample will store values for each layer in LayerMask, all other values will have their respective default value. If the heightmap sample lies outside of the valid coordinate range of this heightmap, it will have a Coverage of 0, even if LayerMask does not contain the Coverage layer.

HasSamples

Determines if this heightmap contains sample data in the given region.

[ThreadSafe]
method HasSamples (Box3I region, int32 step = 1)
type CoverageFlags
params region The region to check for data. The coordinates must be specified for a heightmap of size MaxSize.
  step [pow2] Step distance between samples in region. Defaults to 1.
returns The resulting flags.

See also:

HasRegion

ImportPixels

Imports pixel data into this dataset.

[OwnerReturn]
method ImportPixels (IImage image, bool validate, Vec4I materials = default(Vec4I))
type IOperation
params image [not-null] The pixel data to import.
  validate Validate input image before processing?
  materials The scanline materials to use (see ScanlineMaterials). Will be ignored if Layer of image is not Material. If Zero, the default scanline materials are used. Defaults to Zero.

Remarks:

This method uses georeferencing information present in image and this dataset. The pixels of image will be imported and written to the georeferenced dataset region. Pixel data will not be resampled or reprojected. Only pixel values will be scaled and/or translated if necessary, i.e. raw pixel values (see PixelRange) are mapped to terrain-space elevation values (see VerticalRange).


Imports pixel data into this dataset.

[OwnerReturn]
method ImportPixels (IImage image, bool validate, CubemapFaceCoordsI topLeft, Transform transform = Transform.None, Vec4I materials = default(Vec4I))
type IOperation
params image [not-null] The pixel data to import.
  validate Validate input image before processing?
  topLeft Cubemap face coordinates of top-left pixel of transformed input image.
  transform Transform to apply to input image. Defaults to None.
  materials The scanline materials to use (see ScanlineMaterials). Will be ignored if Layer of image is not Material. If Zero, the default scanline materials are used. Defaults to Zero.

Remarks:

This method ignores georeferencing information present in image and/or this dataset. The pixels of image will be imported and written to a dataset region denoted by topLeft and transform. Pixel data will not be resampled or reprojected. Only pixel values will be scaled and/or translated if necessary, i.e. raw pixel values (see PixelRange) are mapped to terrain-space elevation values (see VerticalRange).

A-------B
|       |    input image: W x H pixels
D-------C
First, the given transform is applied to the input image, using the center of its map raster as the center of transformation (see MapInfo). This figure shows the transformed image for Diagonal:
A----D
|    |
|    |      transformed input image: W' x H' pixels
|    |
B----C
Then, the top-left pixel of the transformed input image (here A) is tied to the given cubemap face coordinates (see topLeft) and the pixels of the transformed image are imported into the cubemap face, where to X-axis resp. Y-axis of the transformed input image correspond to the cubemap face X-axis resp. Y-axis (see Cubemap).

IsSolid

Is this heightmap solid, i.e. all samples have full coverage?

[ThreadSafe]
method IsSolid ()
type bool
returns true if this heightmap is solid, false if not.

See also:

CoverageFlags.NotEmpty

Material

Returns an IHeightmap that applies the given material keys to the Texture values of this heightmap in order to produce material tokens (see Material).

[OwnerReturn, OwnerThis]
method Material (MaterialKeys materials)
type IHeightmap
params materials [not-null] The material keys.
returns [not-null] The resulting heightmap.

Projector

Returns an HeightmapProjector object that can be used to project heightmap samples between this heightmap and the given one.

[OwnerReturn, OwnerThis]
method Projector (IHeightmap output, IMapProjectionFactory projection = null)
type HeightmapProjector
params output [not-null] The output heightmap.
  projection The map projection to use. If null, a map projection will be created based on the georeferencing information of this heightmap (see Georef). Defaults to null.
returns [not-null] The HeightmapProjector object.

ProjectSamples

Reads samples from this dataset, projects them to the coordinate system of the target dataset and stores the projected samples in the target dataset.

[OwnerReturn, OwnerThis]
method ProjectSamples ([Owner] IHeightmap target, DatasetId since = , IMapProjectionFactory factory = null)
type IOperation
params target [not-null] The target dataset.
  since Optional DatasetId value that identifies the dataset revision that has already been processed. Only new and updated data in this dataset will be projected. Set to None to process all data. Defaults to None.
  factory Optional map projection to use. If null, a map projection will be derived from the georeferencing information. Defaults to null.
returns [not-null] The background operation.

ReadAsImage

Reads a field of this heightmap as an image.

[OwnerReturn]
method ReadAsImage (HeightmapLayer layer, CubemapFaceRect region, int32 step = 1)
type IHeightmapReader
params layer The heightmap layer to read.
  region The heightmap region to read.
  step [pow2] The sample step. Defaults to 1.
returns [not-null] The created IImageReader object.

Regions

Returns the map regions of the this heightmap.

[ThreadSafe]
method Regions (int32 blockSize = 512)
type MapRegion
params blockSize [pow2] Block size granularity to use for fetching map regions. Defaults to 512.
returns [not-null] The map regions.

Returns the map regions of the this heightmap.

[ThreadSafe]
method Regions (ICollector<CubemapFaceRect> regions, int32 blockSize = 512)
params regions [not-null] Collector of output cubemap face rectangles.
  blockSize [pow2] Block size granularity to use for fetching map regions. Defaults to 512.
returns [not-null] The map regions.

Remarks:

This method will output zero or more disjoint cubemap face rectangles to regions. If Add returns false, the method will early-exit. This can be used to implement cancellation.


Returns the map regions of the this heightmap.

[ThreadSafe]
method Regions (ICollector<CubemapFaceRect> regions, CubemapFaceRect bounds, int32 blockSize = 512)
params regions [not-null] Collector of output cubemap face rectangles.
  bounds Region of interest, given as cubemap face rectangle.
  blockSize [pow2] Block size granularity to use for fetching map regions. Defaults to 512.
returns [not-null] The map regions.

Remarks:

This method will output zero or more disjoint cubemap face rectangles to regions. If Add returns false, the method will early-exit. This can be used to implement cancellation.

Slope

Computes a SlopeInfo value for this heightmap, based on its georeferencing information.

method Slope ()
type SlopeInfo
returns The slope info.

VerticalMetre

Returns the terrain-space range of elevation values, in Metre.

method VerticalMetre ()
type VerticalRange
returns The terrain-space elevation range, in Metre.

See also:

Vertical