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

interface IImageReader in Tinman.Terrain.Imaging

Base interface for classes that read images sequentially by scanline.

interface IImageReader extends IDisposableGeneric<IImageReader>
  IImageInfo
  IImageOps<IImageReader>
  IValidatable
  base of ImageReaderBase

Remarks

When an image is read, the following processing is performed:

  1. Images are read one scanline at a time (see Scanline), starting with the scanline at image pixel Y-coordinate zero. The color channels ( Red, Green, Blue, Intensity) and / or alpha channel (Alpha) of each raw pixel in a scanline are processed as described below.
  2. Void regions (see NoData):
    If any channel value of the raw pixel is equal to the no-data value, the output pixel is set to void (see Set_Void) and further processing is skipped.
  3. Range normalization (see Range):
    A linear transformation (see Transform) is applied to all channel values of the raw pixel, outputting a normalized pixel.
  4. Gamma correction (see Gamma):
    The color channel values of the normalized pixel are fed into the gamma correction formula, producing the color channel values of the linear pixel. Gamma correction is not applied to alpha channel values.
  5. The channel values of the linear pixel are clamped to the range [0..16777215] and round to 24-bit integer values (see Pixels).

Attributes

Coverage

The pixel coverage of the image.

property Coverage { get }
type PixelCoverage
value The pixel coverage.
inherited IImageInfo.Coverage

Remarks:

Usually, images have a pixel coverage of PixelIsArea.

Gamma

The gamma correction that must be applied to normalized image pixels in order to obtain linear pixel values.

property Gamma { get }
type float64
value The gamma correction value (see remarks).
inherited IImageInfo.Gamma

Remarks:

Depending on the value V of this property, the following gamma correction is applied:

See also:

IImageReader

Georef

Returns georeferencing information.

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

HasFinished

Has the image reader finished (i.e. the whole image has been read)?

property HasFinished { get }
type bool
value true if the whole image has been read, false if not.

Height

Height of the image, in pixels.

property Height { get }
type int32
value [>0] Height of the image, in pixels.
inherited IImageInfo.Height

Remarks:

This is the number of image pixels along the Y-axis, which may be different from the raster height (see MapInfo), depending on the pixel coverage.

ImageFormat

The file format of the image file.

property ImageFormat { get }
type ImageFormat
value [not-null] The image file format.
inherited IImageInfo.ImageFormat

Remarks:

The default file format is Any, which will try to load image data using any of the available image formats.

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireBase).
inherited IDisposable.IsSoleOwnership

Layer

The heightmap layer which shall receive the data of this image.

property Layer { get }
type HeightmapLayer
value The target heightmap layer.
inherited IImageInfo.Layer

Remarks:

This is not an actual property of the image, but included here for convenience when images are imported into heightmap datasets.

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

NoData

The raw pixel value that represents missing data (i.e. void pixels).

property NoData { get }
type float64
value The nodata value.
inherited IImageInfo.NoData

Remarks:

The default value is NanD (i.e. all raw pixel values are valid).

See also:

IImageReader

PathInfo

Returns a Path object that represents the file path this object is associated with.

property PathInfo { get }
type Path
value [not-null] The path info.
inherited IPathInfo.PathInfo

Remarks:

Objects that do not have a meaningful file path association simply return Unknown.

PixelFormat

The pixel format of the image.

property PixelFormat { get }
type PixelFormat
value The pixel format of the image.
inherited IImageInfo.PixelFormat

Remarks:

Image processing is always performed with with four 24-bit integer channels (see Scanline). The pixel format provides additional information about the stored pixel data.

Range

The mapping between raw pixels values and normalized image pixels.

property Range { get }
type PixelRange
value The pixel range.
inherited IImageInfo.Range

See also:

IImageReader

ScanlineY

The Y-coordinate that will be read upon the next call to ReadScanline.

property ScanlineY { get }
type int32
value [0..Height] The scanline Y-coordinate.

Width

Width of the image, in pixels.

property Width { get }
type int32
value [>0] Width of the image, in pixels.
inherited IImageInfo.Width

Remarks:

This is the number of image pixels along the X-axis, which may be different from the raster width (see MapInfo), depending on the pixel coverage.

Methods

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method Acquire (bool allowNull = false)
type T
params allowNull Depicts what to do when this object is no longer valid:
true: return null
false: throw an exception
returns The strong reference to this disposable object or null iff allowNull is true and this object is no longer valid.
inherited IDisposableGeneric.Acquire

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this 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.

Exceptions:

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method AcquireBase (bool allowNull = false)
type IDisposable
params allowNull Depicts what to do when this object is no longer valid:
true: return null
false: throw an exception
returns The strong reference to this disposable object or null iff allowNull is true and this object is no longer valid.
inherited IDisposable.AcquireBase

Remarks:

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

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

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

Exceptions:

Adjust

Adjust the brightness and saturation of this image.

[OwnerReturn, OwnerThis]
method Adjust (int32 brightness, int32 saturation = 0)
type T
params brightness [-1000..1000] The adjustment factor for image brightness.
  saturation [-1000..1000] The adjustment factor for image saturation. Defaults to 0.
returns [not-null] The resulting image.
inherited IImageOps.Adjust

See also:

Colors.Adjust

AlphaToCoverage

Converts the alpha channel (see Alpha) of this image to a coverage layer (see Void).

[OwnerReturn, OwnerThis]
method AlphaToCoverage ()
type T
returns [not-null] The resulting image.
inherited IImageOps.AlphaToCoverage

Background

The image scanlines will be read using concurrent background tasks.

[OwnerReturn, OwnerThis]
method Background ()
type T
returns [not-null] The resulting IImageReader object.
inherited IImageOps.Background

ChannelToIntensity

Returns an opaque grayscale image which pixel values are equal to the given pixel channel of this image.

[OwnerReturn, OwnerThis]
method ChannelToIntensity (PixelChannel channel)
type T
params channel The pixel channel.
returns [not-null] The resulting image.
inherited IImageOps.ChannelToIntensity

Remarks:

Void pixels in this image will also be void in the resulting image.

See also:

IImageOps.IntensityToChannel

Clip

Returns an image that represents a sub rectangle of this image.

[OwnerReturn, OwnerThis]
method Clip (int32 x, int32 y, int32 width, int32 height)
type T
params x [>=0] X-coordinate of top-left corner of rectangle.
  y [>=0] Y-coordinate of top-left corner of rectangle.
  width [>0] Width of rectangle.
  height [>0] Height of rectangle.
returns [not-null] The resulting image.
inherited IImageOps.Clip

Crop

Assumes the image holds a non-rectangular shape that is padded with a uniform color and replaces all padding pixels with void.

[OwnerReturn, OwnerThis]
method Crop (int64 color = Colors.Black, int32 skip = 1)
type T
params color The padding pixel color (see Colors). Defaults to Black.
  skip The maximum length (in pixels) of a run surrounded by void pixels that will be interpreted as void, too. Defaults to 1.
returns [not-null] The resulting image.
inherited IImageOps.Crop

Remarks:

Since the source image is read scanline after scanline, cropping is performed locally for each scanline: Beginning at the left and right image borders, all pixels having the same color as the color parameter are replaced with void until a consecutive run of pixels having different colors is found (see skip). The following figures illustrates this: Pixels that have the same color as the color parameter are shown as '.' characters, all others are indicated with X:

+-----------------------------------------------------------------------+
|.......................................................................|
|.......................................................................|
|............................XXX........................................|
|...........................XXXXX.......................................|
|.........................XXXXXXX.......................................|
|.......................XXXXXXXXX.......................................|
|.....................XXXXXXXXXXX.......................................|
|...................XXXXXXXXXXXXXX......................................|
|.................XXXXXXXXXXXXXXXX......................................|
|................XXXXXXXXXXXXXXXXX......................................|
|...............XXXXXXXXXXXXXXXXXXX.....................................|
|................XXXXXXXXXXXXXXXXXXX....................................|
|.................XXXXXXXXXXXXXXXXXXXXX.................................|
|...................XXXXXXXXXXXXXXXXXXXXXXX.....X.......................|
|...............XXXXXXXXXX..XXXXXXXXXXXXXXXXXXXXXXXXXXX.................|
|..........XXXXXXXXXXXX.......XXXXXXXXXXXXXXXXXXXXXXXXXXX...............|
|.............XXXXXXX..........XXXXXXXXXXXXXXXXXXXXXXXXXX...............|
|...............XXX.............XXXXXXXXXXXXXXXXXXXXXXXX................|
|................................XXXXXXXXXXXXXXXXXXXXX..................|
|................................XXXXXXXXXXXXXXXXX......................|
|...................................XXXXXXX.............................|
|.......................................................................|
|.......................................................................|
|.......................................................................|
|.......................................................................|
+-----------------------------------------------------------------------+
The cropped image will look like this (whitespace represents void pixels):
+-----------------------------------------------------------------------+
|                                                                       |
|                                                                       |
|                            XXX                                        |
|                           XXXXX                                       |
|                         XXXXXXX                                       |
|                       XXXXXXXXX                                       |
|                     XXXXXXXXXXX                                       |
|                   XXXXXXXXXXXXXX                                      |
|                 XXXXXXXXXXXXXXXX                                      |
|                XXXXXXXXXXXXXXXXX              cropped because         |
|               XXXXXXXXXXXXXXXXXXX             of skipped pixels       |
|                XXXXXXXXXXXXXXXXXXX            |                       |
|                 XXXXXXXXXXXXXXXXXXXXX         V                       |
|                   XXXXXXXXXXXXXXXXXXXXXXX                             |
|               XXXXXXXXXX..XXXXXXXXXXXXXXXXXXXXXXXXXXX                 |
|          XXXXXXXXXXXX.......XXXXXXXXXXXXXXXXXXXXXXXXXXX               |
|             XXXXXXX..........XXXXXXXXXXXXXXXXXXXXXXXXXX               |
|               XXX.............XXXXXXXXXXXXXXXXXXXXXXXX                |
|                         ^      XXXXXXXXXXXXXXXXXXXXX                  |
|                         |      XXXXXXXXXXXXXXXXX                      |
|                  not reachable    XXXXXXX                             |
|                  from left or                                         |
|                  right border                                         |
|                                                                       |
|                                                                       |
+-----------------------------------------------------------------------+
Cropping will not change the image size or modify the georeference.

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.

Implementing methods must not throw any exceptions.

Function

Transform linear pixel values using a custom function.

[OwnerReturn, OwnerThis]
method Function (string function, PixelChannel channel = PixelChannel.Intensity)
type T
params function [not-null] A function expression (see GrammarRuleExpression) that consumes input linear pixel values in the range [0..1] and returns output linear pixel value in the range [0..1]. Output values are clamped (including infinities), not-a-number output values produce void pixels (see Void).
  channel The pixel channel the function shall be applied to. If Void, no transformation will be performed. Defaults to Intensity.
returns [not-null] The resulting image or this if channel is Void.
inherited IImageOps.Function

Remarks:

The given function is evaluated on linear pixel values, that is after raw pixels have been translated to normalized pixel values (see SetRange) and after gamma correction has been applied (see SetGamma). The expression may use all members of the default Tinman script (see Tinman). The following arguments are available to the function expression:

IntensityToChannel

Returns an image that has a single pixel channel (see channel parameter), initialized to the grayscale intensities of this image. All other pixel channels are initialized to their respective default values (see PixelChannel).

[OwnerReturn, OwnerThis]
method IntensityToChannel (PixelChannel channel)
type T
params channel The pixel channel.
returns [not-null] The resulting image.
inherited IImageOps.IntensityToChannel

Remarks:

Void pixels in this image will also be void in the resulting image.

See also:

IImageOps.ChannelToIntensity

Replaces a pixel channel of the given image with the grayscale intensities of this image.

[OwnerReturn, OwnerThis]
method IntensityToChannel (PixelChannel channel, [Owner] T image)
type T
params channel The pixel channel to replace.
  image [not-null] The image which pixel channel is to be replaced.
returns [not-null] The resulting image.
inherited IImageOps.IntensityToChannel

Remarks:

Void pixels in the other image are ignored (i.e. the original pixel remains unchanged). Void pixels in this image are preserved (i.e. the other pixel is ignored).

See also:

PixelChannel

Invert

Inverts the given pixel channel.

[OwnerReturn, OwnerThis]
method Invert (PixelChannel channel)
type T
params channel The pixel channel.
returns [not-null] The resulting image.
inherited IImageOps.Invert

Remarks:

The Void pixel channel cannot be inverted. The method will do nothing in this case.

Op

Combines this image (first) with the given one (second) using the specified color operation (see ColorOp).

[OwnerReturn, OwnerThis]
method Op ([Owner] T other, ColorOp colorOp)
type T
params other [not-null] The other image.
  colorOp The color operation to apply.
returns [not-null] The resulting image.
inherited IImageOps.Op

Pad

Pads this image by duplicating pixels at the borders.

[OwnerReturn, OwnerThis]
method Pad (int32 amount = 1)
type T
params amount [>=0] The pad amount, in pixels. Defaults to 1.
returns [not-null] The resulting image.
inherited IImageOps.Pad

Remarks:

Padding can be used to reduce seams that will occur when tiled geodata is imported incrementally using on-the-fly projection. The correct solution would be to merge all geodata tiles into a dataset and then perform the projection on the whole geodata.

ReadAll

Reads the entire image into a color buffer.

[OwnerThis]
method ReadAll ()
type ColorBuffer
returns [not-null] The color buffer.

Remarks:

This method must only be called when the current scanline is zero (see ScanlineY).

Exceptions:

ReadScanline

Reads the next scanline.

method ReadScanline (Scanline scanline)
type int32
params scanline [not-null] The output buffer for the read scanline pixels.
returns Y-coordinate of processed scanline.

Exceptions:

Scale

Returns an image that represents a scaled version of this image.

[OwnerReturn, OwnerThis]
method Scale (int32 width, int32 height, InterpolationMode mode = InterpolationMode.UniformB)
type T
params width [>0] Width of the scaled image.
  height [>0] Height of the scaled image.
  mode The interpolation mode to use for magnification. Defaults to UniformB.
returns [not-null] The resulting image.
inherited IImageOps.Scale

SetCoverage

Updates the value of Coverage, without modifying the image content.

[OwnerReturn, OwnerThis]
method SetCoverage (PixelCoverage coverage)
type T
params coverage The pixel coverage.
returns [not-null] The resulting image.
inherited IImageOps.SetCoverage

Remarks:

To perform resampling between pixel-is-area and pixel-is point, use ToCoverage.

SetGamma

Updates the value of Gamma.

[OwnerReturn, OwnerThis]
method SetGamma (float64 gamma)
type T
params gamma The gamma correction.
returns [not-null] The resulting image.
inherited IImageOps.SetGamma

SetGeoref

Updates the value of Georef, without modifying the image content.

[OwnerReturn, OwnerThis]
method SetGeoref (Raster georef)
type T
params georef The georeferencing information or null.
returns [not-null] The resulting image.
inherited IImageOps.SetGeoref

SetLayer

Updates the value of Layer, without modifying the image content.

[OwnerReturn, OwnerThis]
method SetLayer (HeightmapLayer layer, PixelFormat format = PixelFormat.Unknown)
type T
params layer The heightmap layer.
  format The pixel format to use for choosing the heightmap format (see For). If Unknown, the pixel format of this image will be used. Defaults to Unknown.
returns [not-null] The resulting image.
inherited IImageOps.SetLayer

SetNoData

Updates the value of NoData.

[OwnerReturn, OwnerThis]
method SetNoData (float64 noData)
type T
params noData The raw pixel value to map to void pixels (see NoData).
returns [not-null] The resulting image.
inherited IImageOps.SetNoData

SetRange

Updates the value of Range.

[OwnerReturn, OwnerThis]
method SetRange (PixelRange range, bool reinterpret = false)
type T
params range The pixel value ranges to use for translating raw pixel values to normalized pixel values (see Range).
  reinterpret true to leave raw pixels values unchanged and reinterpret them according to range, false to normalize raw pixel values to range. Defaults to false.
returns [not-null] The resulting image.
inherited IImageOps.SetRange

SkipScanlines

Skips the given number of scanlines.

method SkipScanlines (int32 count)
params count [>=0] The number of scanlines to skip.

Exceptions:

Smooth

Performs smoothing on this image.

[OwnerReturn, OwnerThis]
method Smooth ()
type T
returns [not-null] The resulting image.
inherited IImageOps.Smooth

Remarks:

Image smoothing is performed using an Uniform-B spline.

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.

Exceptions:

ToCoverage

Transforms this image from the given pixel coverage semantic to the given one.

[OwnerReturn, OwnerThis]
method ToCoverage (PixelCoverage target, bool wrapX = false)
type T
params target The pixel coverage semantic of the resulting image.
  wrapX Is this image wrapped around the X-axis?
returns [not-null] The resulting image.
inherited IImageOps.ToCoverage

Remarks:

If this image already has the given pixel coverage semantic, no transformation will be performed.

Validate

Validates the state of this object.

method Validate (Validator validator)
params validator [not-null] The validator object.
inherited IValidatable.Validate