class ImageReaderBase in Tinman.Terrain.Imaging

Abstract base class for IImageReader implementations.

abstract class	ImageReaderBase	extends	Disposable
		implements	IImageReader
		base of	ImageReader

Configuration

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 / Attributes

Coverage

The pixel coverage of the image.

public abstract property	Coverage { get }
type	PixelCoverage
value		The pixel coverage.
implements	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.

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

Remarks:

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

• V > 0
  Given a normalized image pixel value N, the resulting linear pixel value L is computed as L = pow(N, V).
• V = -2.2 (see GammaFromSrgb)
  The normalized image pixel value is fed into the FromSrgbF method and its return value is used as the linear pixel value.
• V = -0.45455 (see GammaToSrgb)
  The normalized image pixel value is fed into the ToSrgbF method and its return value is used as the linear pixel value (which is not correct in a mathematical sense, but might be necessary in rare cases).
• For all other values of V, the normalized and linear pixel values are treated as being equivalent.

See also:

IImageReader

Georef

Returns georeferencing information.

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

HasFinished

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

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

Height

Height of the image, in pixels.

public abstract property	Height { get }
type	int32
value	[>0]	Height of the image, in pixels.
implements	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.

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

Remarks:

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

Layer

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

public abstract property	Layer { get }
type	HeightmapLayer
value		The target heightmap layer.
implements	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.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

Map

Returns a MapInfo value that describes the used map raster.

public abstract property	Map { get }
type	MapInfo
value		The map info value.
implements	IMapInfo.Map

NoData

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

public abstract property	NoData { get }
type	float64
value		The nodata value.
implements	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.

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

Remarks:

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

PixelFormat

The pixel format of the image.

public abstract property	PixelFormat { get }
type	PixelFormat
value		The pixel format of the image.
implements	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.

public abstract property	Range { get }
type	PixelRange
value		The pixel range.
implements	IImageInfo.Range

See also:

IImageReader

ScanlineY

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

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

Width

Width of the image, in pixels.

public abstract property	Width { get }
type	int32
value	[>0]	Width of the image, in pixels.
implements	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.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

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

Remarks:

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

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

Adjust

Adjust the brightness and saturation of this image.

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

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]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

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

Function

Transform linear pixel values using a custom function.

[OwnerReturn, OwnerThis]
public method	Function (string function, PixelChannel channel = PixelChannel.Intensity)
type	IImageReader
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	IImageReader
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] IImageReader image)
type	IImageReader
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	IImageReader
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] IImageReader other, ColorOp colorOp)
type	IImageReader
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	IImageReader
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.

ReadAll

Reads the entire image into a color buffer.

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

Remarks:

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

ReadScanline

Reads the next scanline.

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

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	IImageReader
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 abstract method	SetCoverage (PixelCoverage coverage)
type	IImageReader
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 abstract method	SetGamma (float64 gamma)
type	IImageReader
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 abstract method	SetGeoref (Raster georef)
type	IImageReader
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 abstract method	SetLayer (HeightmapLayer layer, PixelFormat format = PixelFormat.Unknown)
type	IImageReader
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 abstract method	SetNoData (float64 noData)
type	IImageReader
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 abstract method	SetRange (PixelRange range, bool reinterpret = false)
type	IImageReader
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	IImageReader
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

SkipScanlines

Skips the given number of scanlines.

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

Smooth

Performs smoothing on this image.

[OwnerReturn, OwnerThis]
public method	Smooth ()
type	IImageReader
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	IImageReader
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.

Validate

Validates the state of this object.

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

Protected / Attributes

flags

The set of ReadImageFlags that has been used to create this image reader.

protected readonly field	flags
type	ReadImageFlags

IsReadingData

Will this ImageReaderBase object be used to read actual image data?

protected property	IsReadingData { get }
type	bool
value		true if image data will be read, false if only metadata will be read.

IsReadingGeo

Will this ImageReaderBase object be used to read georeferencing metadata?

protected property	IsReadingGeo { get }
type	bool
value		true if georeferencing metadata will be read, false if not.

Protected / Constructors

ImageReaderBase

Creates a new instance of ImageReaderBase.

protected constructor	ImageReaderBase (ReadImageFlags flags)
params	flags		The set of ReadImageFlags for this image reader.

Protected / Methods

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected virtual method	DisposeManaged ()
inherited	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.