class Image in Tinman.Terrain.Imaging

Abstract base class for IImage implementations.

abstract class	Image	implements	IImage
		base of	CompositeImage
			FileBasedImage

Configuration

Config

The configurator object for IImage values.

public static property	Config { get }
type	IConfigurator<IImage>
value	[not-null]	The configurator object.

ToConfig

Returns the configuration value that describes this object.

public method	ToConfig ()
type	ConfigValue
returns		[not-null]	The configuration value.
implements	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.

Public / Constructors

Combine

Combines the given pixel channels into a new image.

[Pure]
public static method	Combine (IImage source, IImage intensity, IImage red, IImage green, IImage blue, IImage alpha, IImage voidMask)
type	IImage
params	source		The source channel image or null.
	intensity		The grayscale intensity channel image or null (see Intensity).
	red		The red channel image or null (see Red).
	green		The green channel image or null (see Green).
	blue		The blue channel image or null (see Blue).
	alpha		The alpha channel image or null (see Alpha).
	voidMask		The void channel image or null (see Void).
returns			The combined image or null if all given images are null.

Remarks:

The grayscale intensities of each channel image will be used as the channel value. The channels are filled in the parameter order, so truecolor channels will overwrite the grayscale intensities. The given source image will be used to fill in the missing channels.

See also:

IntensityToChannel
IntensityToChannel

Constant

Creates an image that has an uniform color.

[Pure]
public static method	Constant (int32 width, int32 height, int64 color)
type	IImage
params	width	[>0]	The image width, in pixels.
	height	[>0]	The image height, in pixels.
	color		The uniform image color (see Colors).
returns		[not-null]	The image.

EncodeNormals

Encodes a normal map image, assuming that all tangent-space normal vectors point upwards (i.e. the minimum blue channel value is 0.5).

[Pure]
public static method	EncodeNormals (IImage normal, IImage map = null)
type	IImage
params	normal	[not-null]	The normal map image.
	map		Optional grayscale map to encode. Defaults to null.
returns		[not-null]	The normal map image.

Remarks:

The pixels of the given normal map are interpreted as follows:

red  :[0..1] => X:[-1 .. +1]
green:[0..1] => Y:[-1 .. +1]
blue :[0..1] => Z:[-1 .. +1]

The vector (X,Y,Z) is then normalized to unit-length. The grayscale intensity I is computed from the pixel in map (if not null). The pixel P of the resulting image is then computed like this:

map == null :
  P.red   = X * 0.5 - 0.5
  P.green = Y * 0.5 - 0.5

map != null :
  P.red   = X * 0.5 - 0.5
  P.green = I
  P.blue  = Y * 0.5 - 0.5

File

Reads the given image file.

[Pure]
public static method	File (Path file, ImageFormat format = null)
type	IImage
params	file	[not-null]	The file path.
	format		The file format or null if not known. Defaults to null.
returns		[not-null]	The image.

---

Reads the given image file.

[Pure]
public static method	File (IFileData file, ImageFormat format = null)
type	IImage
params	file	[not-null]	The file data.
	format		The file format or null if not known. Defaults to null.
returns		[not-null]	The image.

Grid

Creates an image that arranges a sequence of tile images in a grid.

[Pure]
public static method	Grid (int32 columns, int32 overlap, IImage[] images)
type	IImage
params	columns	[>0]	The number of grid columns.
	overlap	[>=0]	The overlap between adjacent grid cells, in pixels.
	images	[not-null]	The tile images.

Remarks:

A grid image defines a virtual canvas which is divided into a regular grid. An input tile image is placed into each cell of that grid. The resulting image contains the image data of the entire virtual canvas.

         col     col     col     col     col
          0       1       2       3       4
      +-------+-------+-------+-------+-------+
      |       |       |       |       |       |
row 0 |   0   |   1   |   2   |   3   |   4   |
      |       |       |       |       |       |
      +-------+-------+-------+-------+-------+
      |       |       |       |       |       |
row 1 |   5   |   6   |   7   |   8   |   9   |
      |       |       |       |       |       |
      +-------+-------+-------+-------+-------+
      |       |       |       |       |       |
row 2 |  10   |  11   |  12   |  13   |  14   |
      |       |       |       |       |       |
      +-------+-------+-------+-------+-------+

rows    := 3
columns := 5
# tiles := 15

The sequence in which the tile image have been added to the grid determines the grid cell in which each of them will be placed. Given the zero-based index i of a tile image in the sequence, the coordinates of its grid cell then are:

x := i % columns
y := i / columns

An optional overlap value can be specified. This value depicts by how many pixels adjacent grid cells shall overlap. Overlap is usually required for tiled datasets where the first and last rows resp. columns of adjacent tiles contain the same pixels.

Random

Creates an image with random pixels.

[Pure]
public static method	Random (int32 width, int32 height, int32 voidPercent = 0, int32 seed = 0)
type	IImage
params	width	[>0]	The image width, in pixels.
	height	[>0]	The image height, in pixels.
	voidPercent	[0..100]	The amount of void pixels, in percent. Defaults to 0.
	seed		Random seed value. Same seeds will produce same images. Defaults to 0.
returns		[not-null]	The image.

Raw

Reads image pixels from raw binary data.

[Pure]
public static method	Raw (IFileData file, int32 width, int32 height, SampleLayout layout, int64 offset = 0, int32 stride = 0)
type	IImage
params	file	[not-null]	The file data provider.
	width	[>0]	The image width, in pixels.
	height	[>0]	The image height, in pixels.
	layout		Data format of the pixel samples.
	offset	[>=0]	File offset to the first byte of the raw image data. Defaults to 0.
	stride	[>=0]	Distance between pixels in same column of adjacent scanlines, in bytes. If 0, the distance will be computed from width and layout. Defaults to 0.
returns		[not-null]	The resulting image.

Public / Methods

Adjust

Adjust the brightness and saturation of this image.

[OwnerReturn, OwnerThis]
public virtual method	Adjust (int32 brightness, int32 saturation = 0)
type	IImage
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.
implements	IImageOps.Adjust

See also:

Colors.Adjust

Background

The image scanlines will be read using concurrent background tasks.

[OwnerReturn, OwnerThis]
public virtual method	Background ()
type	IImage
returns		[not-null]	The resulting IImageReader object.
implements	IImageOps.Background

ChannelToIntensity

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

[OwnerReturn, OwnerThis]
public virtual method	ChannelToIntensity (PixelChannel channel)
type	IImage
params	channel		The pixel channel.
returns		[not-null]	The resulting image.
implements	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]
public virtual method	Clip (int32 x, int32 y, int32 width, int32 height)
type	IImage
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.
implements	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]
public virtual method	Crop (int64 color = Colors.Black, int32 skip = 1)
type	IImage
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.
implements	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.

Equals

Compares this object with the given one.

[Pure]
public method	Equals (IImage other)
type	bool
params	other		The object to compare to.
returns			true if this object is equal to other, false if not.
implements	IEquatable.Equals

Function

Transform linear pixel values using a custom function.

[OwnerReturn, OwnerThis]
public method	Function (string function, PixelChannel channel = PixelChannel.Intensity)
type	IImage
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.
implements	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:

• raw
  The input pixel value (raw).
• lin
  The input pixel value (linear) in the range [0..1].
• A, B, C, D, E, F
  Coefficients that can be used to transform between raw and linear pixel values:

  lin = pow(raw * A + B, C)
  raw = pow(lin, D) * E + F
  D   = 1 / C
  E   = 1 / A
  F   = -B / A

  where raw is the raw pixel value that is actually stored in the source image (e.g. [0..255] for 8-bit images) and lin is the linear pixel value that is stored in the image scanline buffer (see Scanline). A and B represent the transformation from raw pixel values to normalized pixel values (see SetRange); C is the exponent that best approximates the performed gamma correction (see SetGamma).

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]
public virtual method	IntensityToChannel (PixelChannel channel)
type	IImage
params	channel		The pixel channel.
returns		[not-null]	The resulting image.
implements	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]
public virtual method	IntensityToChannel (PixelChannel channel, [Owner] IImage image)
type	IImage
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.
implements	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]
public virtual method	Invert (PixelChannel channel)
type	IImage
params	channel		The pixel channel.
returns		[not-null]	The resulting image.
implements	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]
public virtual method	Op ([Owner] IImage other, ColorOp colorOp)
type	IImage
params	other	[not-null]	The other image.
	colorOp		The color operation to apply.
returns		[not-null]	The resulting image.
implements	IImageOps.Op

Pad

Pads this image by duplicating pixels at the borders.

[OwnerReturn, OwnerThis]
public virtual method	Pad (int32 amount = 1)
type	IImage
params	amount	[>=0]	The pad amount, in pixels. Defaults to 1.
returns		[not-null]	The resulting image.
implements	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.

ReadImage

Creates an IImageReader object that reads the image data of this image.

[OwnerReturn]
public method	ReadImage (ReadImageFlags flags = ReadImageFlags.Data)
type	IImageReader
params	flags		The read flags to use. Defaults to Data.
returns		[not-null]	The IImageReader object.
implements	IImage.ReadImage

Exceptions:

• TinmanException:
  If the image descriptor is incomplete.

ReadImageInfo

Returns information about the image.

public method	ReadImageInfo (ReadImageFlags flags = ReadImageFlags.Info)
type	IImageInfo
params	flags		The read flags to use. Defaults to Info.
returns		[not-null]	An ImageInfo object that holds information about the image.
implements	IImage.ReadImageInfo

Exceptions:

• GeorefException:
  If the image contains unsupported georeferencing metadata.
• TinmanException:
  If the image descriptor is incomplete.

ReadTexture

Reads this image as a texture.

[OwnerReturn]
public virtual method	ReadTexture (CubemapFace face = CubemapFace.NegZ, TextureFormat format = null, bool srgb = true)
type	TexelBuffer
params	face		The cubemap face to read. Set to NegZ for 2D textures. Defaults to NegZ.
	format		The texture format to use, if not specified by the file format. If null, the texture format will be determined from the pixel format (see For), if necessary. Defaults to null.
	srgb		The Srgb flag to use when pixels need to be encoding into texels. Will be ignored if the file format already contains encoded texels. Defaults to true.
returns			The read texture or null if the given cubemap face does not exit.
implements	IImage.ReadTexture

Scale

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

[OwnerReturn, OwnerThis]
public virtual method	Scale (int32 width, int32 height, InterpolationMode mode = InterpolationMode.UniformB)
type	IImage
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.
implements	IImageOps.Scale

SetCoverage

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

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

Remarks:

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

SetGamma

Updates the value of Gamma.

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

SetGeoref

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

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

SetLayer

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

[OwnerReturn, OwnerThis]
public method	SetLayer (HeightmapLayer layer, PixelFormat format = PixelFormat.Unknown)
type	IImage
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.
implements	IImageOps.SetLayer

SetNoData

Updates the value of NoData.

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

SetRange

Updates the value of Range.

[OwnerReturn, OwnerThis]
public method	SetRange (PixelRange range, bool reinterpret = false)
type	IImage
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.
implements	IImageOps.SetRange

Sharpen

Performs sharpening on this image.

[OwnerReturn, OwnerThis]
public virtual method	Sharpen (IImage detail, float32 scale, int32 downsample = 6)
type	IImage
params	detail	[not-null]	The high-resolution detail image to use for sharpening.
	scale	[>=0]	Scale factor to apply to difference between full and reduced resolution. Defaults to 1.
	downsample	[>0]	The detail image will be downsamples by this factor. The difference between the full and reduced resolutions will be used to sharpen this image. Defaults to 4.
returns		[not-null]	The resulting image.
implements	IImageOps.Sharpen

Smooth

Performs smoothing on this image.

[OwnerReturn, OwnerThis]
public method	Smooth ()
type	IImage
returns		[not-null]	The resulting image.
implements	IImageOps.Smooth

Remarks:

Image smoothing is performed using an Uniform-B spline.

ToCoverage

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

[OwnerReturn, OwnerThis]
public virtual method	ToCoverage (PixelCoverage target, bool wrapX = false)
type	IImage
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.
implements	IImageOps.ToCoverage

Remarks:

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

Write

Outputs the pixels of this image via the given image writer.

[OwnerReturn]
public method	Write ([Owner] IImageWriter writer, bool geo = true)
type	IOperation
params	writer	[not-null]	The image writer to use.
	geo		When set to true, the Geo flag will be used when reading this image, iff HasGeoref also returns true. Otherwise, the flag will not be used. Defaults to true.
returns		[not-null]	The background operation.
implements	IImage.Write

Protected / Constructors

Image

Creates a new instance of Image.

protected constructor

Image ()

Protected / Methods

DoEquals

protected abstract method	DoEquals (IImage other)
type	bool
params	other

DoReadImage

Reads the image data.

[OwnerReturn]
protected abstract method	DoReadImage (ReadImageFlags flags)
type	IImageReader
params	flags		The flags to use.
returns		[not-null]	The IImageReader object.

DoToConfig

protected abstract method	DoToConfig ()
type	ConfigValue