IHeightmap

Description

interface Tinman.Terrain.Heightmaps.IHeightmap

Derived from: IMapEntity
IHeightmapOps
IHeightmapLayers
IDisposableGeneric<IHeightmap>
Extended by: Heightmap ^abstract
IHeightmapDataset
IHeightmapProxy
IHeightmapShape

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:

GetSample
GetRegion
GetSamples

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:

IMapEntity.UpdateGeoref (metadata)
UpdateRange (metadata)
UpdateRegion (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

GetBlock1x4

[ThreadSafe]
public method GetBlock1x4 → (7)

x ⁱⁿ : int32: The cubemap face X-coordinate of s01 ^out.
y ⁱⁿ : int32: The cubemap face Y-coordinate of s01 ^out.
face ⁱⁿ : 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.

GetBlock4x1

[ThreadSafe]
public method GetBlock4x1 → (7)

x ⁱⁿ : int32: The cubemap face X-coordinate of s10 ^out.
y ⁱⁿ : int32: The cubemap face Y-coordinate of s10 ^out.
face ⁱⁿ : 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.

GetBlock4x4

[ThreadSafe]
public method GetBlock4x4 → (19)

x ⁱⁿ : int32: The cubemap face X-coordinate of s11 ^out.
y ⁱⁿ : int32: The cubemap face Y-coordinate of s11 ^out.
face ⁱⁿ : 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.

GetRegion

[ThreadSafe]
public method GetRegion → (7)

region ⁱⁿ : 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 ⁱⁿ 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.

See also: IHeightmap.HasRegion

GetSample

[ThreadSafe]
public method GetSample → (3)

x ⁱⁿ : int32: X-coordinate of sample.
y ⁱⁿ : int32: Y-coordinate of sample.
z ^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.

GetSamples

[ThreadSafe]
public method GetSamples → (5)

xyz ⁱⁿ : 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 ⁱⁿ : int32: [>=0]
Total number of heightmap samples to fetch.
buffer ⁱⁿ : 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.
cache ^opt : HeightmapSamplesCache = null: By passing a HeightmapSamplesCache cache object here, the creation of temporary buffers can be minimized. A cache object must not be shared between threads.

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 ⁱⁿ. 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.

HasRegion

[ThreadSafe]
public method HasRegion → (2)

region ⁱⁿ : 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.

UpdateRange

[ThreadSafe]
public method UpdateRange → (1)

range ⁱⁿ : VerticalRange: The new vertical range.

Updates the vertical range of this heightmap.

IOException: If an I/O error has occurred.

See also: IMapEntity.CanUpdate

UpdateRegion

[ThreadSafe]
public method UpdateRegion → (6)

region ⁱⁿ : CubemapFaceRect: The cubemap face region to update.
buffer ⁱⁿ : 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 ⁱⁿ samples (second); the HeightmapRegion.Vertical property of the given buffer ⁱⁿ is ignored, i.e. elevation and displacement samples will not be transformed before the merge.
If false, the given buffer ⁱⁿ 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 ⁱⁿ to use.
bufferY ^opt : int32 = 0: [>=0]
Y-coordinate of top-left sample in buffer ⁱⁿ to use.

Updates a region of this heightmap.

IOException: If an I/O error has occurred.

See also: IMapEntity.CanUpdate

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.

See also: IGeorefInfo.Georef

IsEmpty

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?

IsScaled

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)?

See also: IHeightmapOps.Scale

OnUpdated

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.

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

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 ⁱⁿ : HeightmapSample: The constant heightmap data.
layers ^opt : HeightmapLayer = HeightmapLayer.All: The layers in sample ⁱⁿ 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.

CopySamples

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

target ⁱⁿ : 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 ⁱⁿ 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.
identifier ^opt : GUID = default(GUID): The dataset identifier to use when creating a dataset, see DatasetId.Guid.
returns → IOperation: The background operation.

Copies samples from this heightmap to a new dataset.

ElevationToVertical

[Pure]
public static method ElevationToVertical → (2)

elevation ⁱⁿ : 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

GetSample

_4 overloads

[ThreadSafe]
public static method GetSample¹ → (1)

v ⁱⁿ : Vec2D: Coordinates of sample. Will be round to the nearest sample.
returns → HeightmapSample: The heightmap sample value.

Reads a single sample from the heightmap.

IOException: If an I/O error has occurred.

[ThreadSafe]
public static method GetSample² → (1)

v ⁱⁿ : Vec2I: Coordinates of sample.
returns → HeightmapSample: The heightmap sample value.

Reads a single sample from the heightmap.

IOException: If an I/O error has occurred.

[ThreadSafe]
public static method GetSample³ → (1)

v ⁱⁿ : Vec3D: Coordinates of sample. Will be round to the nearest sample.
returns → HeightmapSample: The heightmap sample value.

Reads a single sample from the heightmap.

IOException: If an I/O error has occurred.

[ThreadSafe]
public static method GetSample⁴ → (1)

v ⁱⁿ : Vec3I: Coordinates of sample.
returns → HeightmapSample: The heightmap sample value.

Reads a single sample from the heightmap.

IOException: If an I/O error has occurred.

ImportPixels

_2 overloads

[OwnerReturn]
public static method ImportPixels¹ → (3)

image ⁱⁿ : IImage: [not-null]
The pixel data to import.
validate ⁱⁿ : 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 ⁱⁿ 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 ⁱⁿ and this dataset. The pixels of image ⁱⁿ 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 ImportPixels² → (5)

image ⁱⁿ : IImage: [not-null]
The pixel data to import.
validate ⁱⁿ : bool: Validate input image before processing?
topLeft ⁱⁿ : 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 ⁱⁿ 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 ⁱⁿ and/or this dataset. The pixels of image ⁱⁿ will be imported and written to a dataset region denoted by topLeft ⁱⁿ 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 ⁱⁿ, 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 ⁱⁿ) 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

[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.

See also: CoverageFlags.NotEmpty

Material

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

materials ⁱⁿ : 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 ⁱⁿ : 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.

ProjectSamples

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

target ⁱⁿ : 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 Regions¹ → (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 Regions² → (2)

regions ⁱⁿ : 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 ⁱⁿ. 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 Regions³ → (3)

regions ⁱⁿ : ICollector<CubemapFaceRect>: [not-null]
Collector of output cubemap face rectangles.
bounds ⁱⁿ : 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 ⁱⁿ. 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.

ToImage

_2 overloads

public static method ToImage¹ → (3)

layer ⁱⁿ : HeightmapLayer: The heightmap layer to read.
face ⁱⁿ : 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 ToImage² → (3)

layer ⁱⁿ : HeightmapLayer: The heightmap layer to read.
region ⁱⁿ : 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.

VerticalMetre

[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.

See also: IHeightmap.Vertical

VerticalToElevation

[Pure]
public static method VerticalToElevation → (2)

coordinate ⁱⁿ : 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

VerticalToElevationClamp

[Pure]
public static method VerticalToElevationClamp → (2)

coordinate ⁱⁿ : 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

VerticalToSample

[Pure]
public static method VerticalToSample → (2)

coordinate ⁱⁿ : 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

IHeightmap

Description

Public / Methods

Get​Block1x4

Get​Block4x1

Get​Block4x4

Get​Region

Get​Sample

Get​Samples

Has​Region

Update​Range

Update​Region

Public / Attributes

Height

Horizontal

Is​Empty

Is​Scaled

On​Updated

Size

Type

Vertical

Width

Extensions

Augment

Copy​Samples

Elevation​To​Vertical

Get​Sample

Import​Pixels

Is​Solid

Material

Projector

Project​Samples

Regions

Slope

To​Image

Vertical​Metre

Vertical​To​Elevation

Vertical​To​Elevation​Clamp

Vertical​To​Sample

GetBlock1x4

GetBlock4x1

GetBlock4x4

GetRegion

GetSample

GetSamples

HasRegion

UpdateRange

UpdateRegion

IsEmpty

IsScaled

OnUpdated

CopySamples

ElevationToVertical

GetSample

ImportPixels

IsSolid

ProjectSamples

ToImage

VerticalMetre

VerticalToElevation

VerticalToElevationClamp

VerticalToSample