IHeightmap

Description

interface Tinman.Terrain.Heightmaps.IHeightmap

A heightmap provides raster data of a terrain, including elevation and other data.

To obtain an instance of IHeightmap, you may use one of the pre-defined factories of the Heightmap class:

Heightmap data is returned using HeightmapSample values for individual heightmaps samples, HeightmapRegion objects for rectangular heightmap sample blocks and HeightmapSamples for heightmap samples chunks with individual coordinates:

A heightmap may be mutable, in which case terrain data and meta-data may be updated. Use IMapEntity.CanUpdate to check if a heightmap is mutable. Then, use these methods to update metadata and terrain data:

Instances of IHeightmap may be combined, in order to perform various conversions and computations at runtime, without having to modify the data that is stored on disk. Please refer to IHeightmapOps for details on the available operations.

Public / Methods

Get​Block1x4


[ThreadSafe]
public method GetBlock1x4 → (7)

in : int32

The cubemap face X-coordinate of s01 out.

in : int32

The cubemap face Y-coordinate of s01 out.

face in : CubemapFace

The cubemap face of s01 out.

s00 out : HeightmapSample

Output sample at row 0 column 0.

s01 out : HeightmapSample

Output sample at row 0 column 1.

s02 out : HeightmapSample

Output sample at row 0 column 2.

s03 out : HeightmapSample

Output sample at row 0 column 3.

Reads a fixed-sized block of samples from the heightmap (1 row, 4 columns).

IOException

If an I/O error has occurred.

Get​Block4x1


[ThreadSafe]
public method GetBlock4x1 → (7)

in : int32

The cubemap face X-coordinate of s10 out.

in : int32

The cubemap face Y-coordinate of s10 out.

face in : CubemapFace

The cubemap face of s10 out.

s00 out : HeightmapSample

Output sample at row 0 column 0.

s10 out : HeightmapSample

Output sample at row 1 column 0.

s20 out : HeightmapSample

Output sample at row 2 column 0.

s30 out : HeightmapSample

Output sample at row 3 column 0.

Reads a fixed-sized block of samples from the heightmap (4 rows, 1 column).

IOException

If an I/O error has occurred.

Get​Block4x4


[ThreadSafe]
public method GetBlock4x4 → (19)

in : int32

The cubemap face X-coordinate of s11 out.

in : int32

The cubemap face Y-coordinate of s11 out.

face in : CubemapFace

The cubemap face of s11 out.

s00 out : HeightmapSample

Output sample at row 0 column 0.

s01 out : HeightmapSample

Output sample at row 0 column 1.

s02 out : HeightmapSample

Output sample at row 0 column 2.

s03 out : HeightmapSample

Output sample at row 0 column 3.

s10 out : HeightmapSample

Output sample at row 1 column 0.

s11 out : HeightmapSample

Output sample at row 1 column 1.

s12 out : HeightmapSample

Output sample at row 1 column 2.

s13 out : HeightmapSample

Output sample at row 1 column 3.

s20 out : HeightmapSample

Output sample at row 2 column 0.

s21 out : HeightmapSample

Output sample at row 2 column 1.

s22 out : HeightmapSample

Output sample at row 2 column 2.

s23 out : HeightmapSample

Output sample at row 2 column 3.

s30 out : HeightmapSample

Output sample at row 3 column 0.

s31 out : HeightmapSample

Output sample at row 3 column 1.

s32 out : HeightmapSample

Output sample at row 3 column 2.

s33 out : HeightmapSample

Output sample at row 3 column 3.

Reads a fixed-sized block of samples from the heightmap (4 rows, 4 columns).

IOException

If an I/O error has occurred.

Get​Region


[ThreadSafe]
public method GetRegion → (7)

region in : CubemapFaceRect

The rectangular cubemap face region to fetch.

layers opt : HeightmapLayer = HeightmapLayer.All

The heightmap layers to fetch.

step opt : int32 = 1

[pow2]
Step distance between samples in region.

buffer opt : HeightmapRegion = null

The output heightmap sample buffer. If null or too small, a new buffer will be created.

bufferX opt : int32 = 0

[>=0]
X-coordinate of top-left corner of target rectangle in buffer opt.

bufferY opt : int32 = 0

[>=0]
Y-coordinate of top-left corner of target rectangle buffer opt.

smooth opt : bool = false

Apply smooth filtering?

returns → HeightmapRegion

The heightmap buffer or null if there are no samples to fetch and buffer opt is null.

Reads a block of samples from the heightmap.

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

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

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

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

IOException

If an I/O error has occurred.

Get​Sample


[ThreadSafe]
public method GetSample → (3)

in : int32

X-coordinate of sample.

in : int32

Y-coordinate of sample.

opt : int32 = 0

Z-coordinate of sample.

returns → HeightmapSample

The heightmap sample value.

Reads a single sample from the heightmap.

The returned heightmap sample will store values for each layer in IHeightmapLayers.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 HeightmapSample.Coverage of 0, even if IHeightmapLayers.LayerMask does not contain the HeightmapLayer.Coverage layer.

IOException

If an I/O error has occurred.

Get​Samples


[ThreadSafe]
public method GetSamples → (4)

xyz in : Vec3I [ ]

[not-null]
Array of cubemap coordinates of heightmap map samples to fetch. The coordinates must be specified for a heightmap of size HeightmapsUtil.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 in : int32

[>=0]
Total number of heightmap samples to fetch.

buffer in : HeightmapSamples

[not-null]
The heightmap sample buffer to use. If null or too small, a new buffer will be created.

layers opt : HeightmapLayer = HeightmapLayer.All

The heightmap layers to fetch.

Reads multiple samples from the heightmap in a bulk operation.

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

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

IOException

If an I/O error has occurred.

Has​Region


[ThreadSafe]
public method HasRegion → (2)

region in : CubemapFaceRect

The region to check for data.

flags opt : CoverageFlags = CoverageFlags.Some

The coverage flags that need to be determined. Using specific flags here will allow implementations to early-exit.

returns → CoverageFlags

The resulting flag bits.

Determines if this heightmap contains data in the given region.

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

  • Contiguous blocks containing more than one sample must be reported. Others may be reported but can be as well be ignored.

  • Samples with partial coverage may be treated as non-existent samples.

  • Samples may be grouped in blocks up to 512x512 in size.

IOException

If an I/O error has occurred.

Update​Range


[ThreadSafe]
public method UpdateRange → (1)

range in : VerticalRange

The new vertical range.

Updates the vertical range of this heightmap.

IOException

If an I/O error has occurred.

Update​Region


[ThreadSafe]
public method UpdateRegion → (6)

region in : CubemapFaceRect

The cubemap face region to update.

buffer in : HeightmapRegion

[not-null]
The heightmap sample buffer to use.

merge opt : bool = false

If true, the existing heightmap samples (first) are merged with the given buffer in samples (second); the HeightmapRegion.Vertical property of the given buffer in is ignored, i.e. elevation and displacement samples will not be transformed before the merge.
If false, the given buffer in samples are copied to this heightmap, overwriting any existing data.

layers opt : HeightmapLayer = HeightmapLayer.All

The heightmap layers to update.

bufferX opt : int32 = 0

[>=0]
X-coordinate of top-left sample in buffer in to use.

bufferY opt : int32 = 0

[>=0]
Y-coordinate of top-left sample in buffer in to use.

Updates a region of this heightmap.

IOException

If an I/O error has occurred.

Public / Attributes

Height


public attribute Height → (get)

value : int32

[>0]
Heightmap height, in samples.

Number of heightmap samples along the Y-axis.

Horizontal


public attribute Horizontal → (get)

value : float64

[>0]
The ground sample distance, in UnitOfMeasure.Metre.

Returns the estimated horizontal resolution in terrain-space.

Is​Empty


public attribute IsEmpty → (get)

value : bool

true if all samples of this heightmap are equal to HeightmapSample.Default, false if not.

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

Is​Scaled


public attribute IsScaled → (get)

value : bool

true if the heightmap contains scaled data, false if not.

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

On​Updated


public attribute OnUpdated → (get)

value : IEventGeneric<HeightmapEventArgs>

[not-null]
The event object.

Event for listening to updates made to this heightmap.

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

Size


public attribute Size → (get)

value : int32

[pow2+1]
Heightmap size, in samples.

Cubemap size of heightmap.

Type


public attribute Type → (get)

value : MapType

The heightmap type.

The heightmap type (rectangular or cubic).

Vertical


public attribute Vertical → (get)

value : VerticalRange

The terrain-space elevation range, in vertical units (see CoordinateSystem.VerticalUnit).

Returns the terrain-space range of elevation values.

Width


public attribute Width → (get)

value : int32

[>0]
Heightmap width, in samples.

Number of heightmap samples along the X-axis.

Extensions

Augment


[OwnerReturn] [OwnerThis]
public static method Augment → (2)

sample in : HeightmapSample

The constant heightmap data.

layers opt : HeightmapLayer = HeightmapLayer.All

The layers in sample in to use for filling in data for non-existent layers.

returns → IHeightmap

The resulting heightmap.

Augments this heightmap with constant heightmap data, filling in the given sample value for non-existent layers.

Copy​Samples


[OwnerReturn] [OwnerThis]
public static method CopySamples → (5)

target in : Path

[not-null]
Path to output dataset.

info opt : IDatasetInfo = null

Optional dataset metadata to use. If null, metadata will be copied from the source dataset if create opt is true; otherwise, the current metadata of target in is retained.

operation opt : ICopySamplesOp = null

Optional copy sample operation to perform. If null, CopySamplesOp.None will be used.

format opt : PixelFormat = PixelFormat.Default

The pixel format to use for choosing the output heightmap format (see HeightmapFormat.ForAll). This parameter is ignored when the source heightmap is a IHeightmapDataset: in this case, the source heightmap format will be used (see IHeightmapDataset.SampleFormat).

create opt : bool = true

true to create a new dataset, false to update an existing dataset. Defaults to true.

returns → IOperation

The background operation.

Copies samples from this heightmap to a new dataset.

Elevation​To​Vertical


[Pure]
public static method ElevationToVertical → (2)

elevation in : int64

The elevation value (see HeightmapSample.Elevation).

unit opt : UnitOfMeasure = null

The vertical coordinate unit. If null, the vertical unit of the heightmaps coordinate system is used (see CoordinateSystem.Vertical).

returns → float64

The vertical coordinate (see CoordinateSystem.Vertical), in the given unit opt.

Helper for converting elevation values to vertical coordinates.

See also

VerticalRange

Get​Sample

4 overloads


[ThreadSafe]
public static method GetSample1 → (1)

in : Vec2D

Coordinates of sample. Will be round to the nearest sample.

returns → HeightmapSample

The heightmap sample value.

Reads a single sample from the heightmap.

The returned heightmap sample will store values for each layer in IHeightmapLayers.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 HeightmapSample.Coverage of 0, even if IHeightmapLayers.LayerMask does not contain the HeightmapLayer.Coverage layer.

IOException

If an I/O error has occurred.


[ThreadSafe]
public static method GetSample2 → (1)

in : Vec2I

Coordinates of sample.

returns → HeightmapSample

The heightmap sample value.

Reads a single sample from the heightmap.

The returned heightmap sample will store values for each layer in IHeightmapLayers.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 HeightmapSample.Coverage of 0, even if IHeightmapLayers.LayerMask does not contain the HeightmapLayer.Coverage layer.

IOException

If an I/O error has occurred.


[ThreadSafe]
public static method GetSample3 → (1)

in : Vec3D

Coordinates of sample. Will be round to the nearest sample.

returns → HeightmapSample

The heightmap sample value.

Reads a single sample from the heightmap.

The returned heightmap sample will store values for each layer in IHeightmapLayers.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 HeightmapSample.Coverage of 0, even if IHeightmapLayers.LayerMask does not contain the HeightmapLayer.Coverage layer.

IOException

If an I/O error has occurred.


[ThreadSafe]
public static method GetSample4 → (1)

in : Vec3I

Coordinates of sample.

returns → HeightmapSample

The heightmap sample value.

Reads a single sample from the heightmap.

The returned heightmap sample will store values for each layer in IHeightmapLayers.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 HeightmapSample.Coverage of 0, even if IHeightmapLayers.LayerMask does not contain the HeightmapLayer.Coverage layer.

IOException

If an I/O error has occurred.

Import​Pixels

2 overloads


[OwnerReturn]
public static method ImportPixels1 → (3)

image in : IImage

[not-null]
The pixel data to import.

validate in : bool

Validate input image before processing?

materials opt : Vec4I = default(Vec4I)

The scanline materials to use (see MaterialBuffer.ScanlineMaterials). Will be ignored if IImageInfo.Layer of image in is not HeightmapLayer.Material. If Vec4I.Zero, the default scanline materials are used.

returns → IOperation

The IOperation that performs the pixel import.

Imports pixel data into this dataset.

This method uses geo-referencing information present in image in and this dataset. The pixels of image in will be imported and written to the geo-referenced 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).


[OwnerReturn]
public static method ImportPixels2 → (5)

image in : IImage

[not-null]
The pixel data to import.

validate in : bool

Validate input image before processing?

topLeft in : CubemapFaceCoordsI

Cubemap face coordinates of top-left pixel of transformed input image.

transform opt : Transform = Transform.None

Transform to apply to input image.

materials opt : Vec4I = default(Vec4I)

The scanline materials to use (see MaterialBuffer.ScanlineMaterials). Will be ignored if IImageInfo.Layer of image in is not HeightmapLayer.Material. If Vec4I.Zero, the default scanline materials are used.

returns → IOperation

The IOperation that performs the pixel import.

Imports pixel data into this dataset.

This method ignores geo-referencing information present in image in and/or this dataset. The pixels of image in will be imported and written to a dataset region denoted by topLeft in and transform opt. 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 opt is applied to the input image in, using the center of its map raster as the center of transformation (see MapInfo). This figure shows the transformed image for Transform.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 in) 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).

Is​Solid


[ThreadSafe]
public static method IsSolid → ()

returns → bool

true if this heightmap is solid, false if not.

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

IOException

If an I/O error has occurred.

Material


[OwnerReturn] [OwnerThis]
public static method Material → (1)

materials in : MaterialKeys

[not-null]
The material keys.

returns → IHeightmap

The resulting heightmap.

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

Projector


[OwnerReturn] [OwnerThis]
public static method Projector → (2)

output in : IHeightmap

[not-null]
The output heightmap.

projection opt : IMapProjectionFactory = null

The map projection to use. If null, a map projection will be created based on the geo-referencing information of this heightmap (see IGeorefInfo.Georef).

returns → HeightmapProjector

The HeightmapProjector object.

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

GeorefException

If projection opt is null and the geo-reference parameters are incomplete or invalid.

Project​Samples


[OwnerReturn] [OwnerThis]
public static method ProjectSamples → (1)

target in : IHeightmap own

[not-null]
The target dataset.

returns → IProjectSamplesOperation

The background operation.

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

Regions

3 overloads


[ThreadSafe]
public static method Regions1 → (1)

blockSize opt : int32 = 512

[pow2]
Block size granularity to use for fetching map regions.

returns → MapRegion

The map regions.

Returns the map regions of the this heightmap.

IOException

If an I/O error has occurred.


[ThreadSafe]
public static method Regions2 → (2)

regions in : ICollector<CubemapFaceRect>

[not-null]
Collector of output cubemap face rectangles.

blockSize opt : int32 = 512

[pow2]
Block size granularity to use for fetching map regions.

Returns the map regions of the this heightmap.

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

IOException

If an I/O error has occurred.


[ThreadSafe]
public static method Regions3 → (3)

regions in : ICollector<CubemapFaceRect>

[not-null]
Collector of output cubemap face rectangles.

bounds in : CubemapFaceRect

Region of interest, given as cubemap face rectangle.

blockSize opt : int32 = 512

[pow2]
Block size granularity to use for fetching map regions.

Returns the map regions of the this heightmap.

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

IOException

If an I/O error has occurred.

Slope


[Pure]
public static method Slope → ()

returns → SlopeInfo

The slope info.

Computes a SlopeInfo value for this heightmap, based on its geo-referencing information.

To​Image

2 overloads


public static method ToImage1 → (3)

layer in : HeightmapLayer

The heightmap layer to read.

face in : CubemapFace

The cubemap face.

step opt : int32 = 1

[pow2]
The sample step.

returns → IImage

The created IImage object.

Reads a whole cubemap face of this heightmap as an image.

The returned IImage object will never throw IOExceptions or ValidatingExceptions.


public static method ToImage2 → (3)

layer in : HeightmapLayer

The heightmap layer to read.

region in : CubemapFaceRect

The heightmap region to read.

step opt : int32 = 1

[pow2]
The sample step.

returns → IImage

The created IImage object.

Reads a rectangular region of this heightmap as an image.

The returned IImage object will never throw IOExceptions or ValidatingExceptions.

Vertical​Metre


[Pure]
public static method VerticalMetre → ()

returns → VerticalRange

The terrain-space elevation range, in UnitOfMeasure.Metre.

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

Vertical​To​Elevation


[Pure]
public static method VerticalToElevation → (2)

coordinate in : float64

The vertical coordinate (see CoordinateSystem.Vertical), in the given unit opt.

unit opt : UnitOfMeasure = null

The vertical coordinate unit. If null, the vertical unit of the heightmaps coordinate system is used (see CoordinateSystem.Vertical).

returns → int64

The unclamped elevation value (see HeightmapSample.Elevation).

Helper for converting vertical coordinates to elevation values.

See also

VerticalRange

Vertical​To​Elevation​Clamp


[Pure]
public static method VerticalToElevationClamp → (2)

coordinate in : float64

The vertical coordinate (see CoordinateSystem.Vertical), in the given unit opt.

unit opt : UnitOfMeasure = null

The vertical coordinate unit. If null, the vertical unit of the heightmaps coordinate system is used (see CoordinateSystem.Vertical).

returns → int32

The clamped elevation value (see HeightmapSample.Elevation).

Helper for converting vertical coordinates to elevation values.

See also

VerticalRange

Vertical​To​Sample


[Pure]
public static method VerticalToSample → (2)

coordinate in : float64

The vertical coordinate (see CoordinateSystem.Vertical), in the given unit opt.

unit opt : UnitOfMeasure = null

The vertical coordinate unit. If null, the vertical unit of the heightmaps coordinate system is used (see CoordinateSystem.Vertical).

returns → HeightmapSample

The heightmap sample containing the clamped elevation value (see HeightmapSample.Elevation).

Helper for converting vertical coordinates to heightmap samples.

See also

VerticalRange