IImage

Description

interface Tinman.Terrain.Imaging.IImage

Derived from

IImageOps<IImage>
IConfigurable
IEquatable<IImage>

Extended by

Image abstract

The IImage interface is a descriptor for 2D raster images.

An image descriptor encapsulates the information that is needed to create an IImageReader via ReadImage1, which incrementally reads image content, one pixel row after another. The ReadImageInfo1 method may be used to obtain image metadata (see IImageInfo), without reading the image content in the first place.

Some images represent GPU texture data (see TexelBuffer) in a binary format that may directly be used by a GPU. In these cases, reading the image content first and then encoding texture data would be redundant. Instead, the ReadTexture method may be used to read the texture data directly, bypassing the read/encode step if redundant.

To write an image file using the image content of an IImage, the Write method may be used. The image format is defined by the given IImageWriter object, which will consume the image content of the image descriptor.

Public / Methods

Read​Image

2 overloads

[OwnerReturn]
public method ReadImage1 → ()

returns → IImageReader

The IImageReader object.

Creates an IImageReader object that reads the image content of this image descriptor using the ReadImageFlags.Data flag.

IOException

If an I/O error has occurred.

ValidatingException

If validation of the resulting IImageReader has failed, for example because of an unsupported file format feature.

[OwnerReturn]
public method ReadImage2 → (1)

flags in : ReadImageFlags

The read flags to use.

returns → IImageReader

The IImageReader object.

Creates an IImageReader object that reads the image content of this image descriptor.

IOException

If an I/O error has occurred.

ValidatingException

If validation of the resulting IImageReader has failed, for example because of an unsupported file format feature.

GeorefException

If the image contains unsupported geo-referencing metadata.

Read​Image​Info

2 overloads

public method ReadImageInfo1 → ()

returns → IImageInfo

An ImageInfo object that holds information about the image.

Returns the image metadata of this image descriptor using the ReadImageFlags.Info flag.

IOException

If an I/O error has occurred.

ValidatingException

If validation of the resulting IImageReader has failed, for example because of an unsupported file format feature.

public method ReadImageInfo2 → (1)

flags in : ReadImageFlags

The read flags to use.

returns → IImageInfo

An ImageInfo object that holds information about the image.

Returns the image metadata of this image descriptor.

IOException

If an I/O error has occurred.

ValidatingException

If validation of the resulting IImageReader has failed, for example because of an unsupported file format feature.

GeorefException

If the image contains unsupported geo-referencing metadata.

Read​Texture

[OwnerReturn]
public method ReadTexture → (4)

face opt : CubemapFace = CubemapFace.NegZ

The cubemap face to read. Set to CubemapFace.NegZ for 2D textures.

format opt : TextureFormat = null

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 TextureFormat.For), if necessary.

mipmaps opt : int32 = 0

[>=0]
The number of mipmap levels to generate, if not specified by the file format. If 0, the mipmap count will be determined from the texture format and the image dimensions.

srgb opt : bool = true

The ISrgb.Srgb flag to use when pixels need to be encoding into texels. Will be ignored if the file format already contains encoded texels.

returns → TexelBuffer

The read texture or null if the given cubemap face does not exit.

Reads the texture data of this image descriptor.

IOException

If an I/O error has occurred.

ValidatingException

If validation of the resulting IImageReader has failed, for example because of an unsupported file format feature.

Write

[OwnerReturn]
public method Write → (2)

writer in : IImageWriter own

[not-null]
The image writer to use.

geo opt : bool = true

When set to true, the ReadImageFlags.Geo flag will be used when reading this image descriptor, iff IImageWriter.HasGeoref also returns true. Otherwise, the flag will not be used.

returns → IOperation

The background operation.

Outputs the image content of this image descriptor using the given image writer in.

The operation inherits the active geo registry from the calling thread, see GeoRegistry.CurrentInherit.

See also

ImageFormat.WriteImage

Extensions

Import​Pixels

[OwnerReturn]
public static method ImportPixels → (2)

path opt : Path = null

Output path of image or dataset file. If null, the file path of this image will be used, having the file suffix replaced with .pxb resp. .hgt.

identifier opt : GUID = default(GUID)

The dataset identifier to use when creating a heightmap dataset, see DatasetId.Guid.

returns → IOperation

The import operation.

Returns an operation that imports image pixels into a PXB image file or a rectangular HGT heightmap dataset.

The output format can be chosen by using the corresponding file suffix for the path opt parameter. If no path is given, a heightmap dataset will be created if the IImageInfo.Layer of the input image has been set (i.e. it has a value other than HeightmapLayer.None).

The operation inherits the active geo registry from the calling thread, see GeoRegistry.CurrentInherit.

Project​Pixels

[OwnerReturn]
public static method ProjectPixels → (1)

output in : IHeightmap own

[not-null]
The output heightmap dataset.

returns → IMapProjectionOperation

The operation.

Returns an operation that projects image pixels onto a cubemap HGT heightmap dataset.

The operation inherits the active geo registry from the calling thread, see GeoRegistry.CurrentInherit.

Read​Image​Info​Null

[OwnerReturn]
public static method ReadImageInfoNull → (1)

flags opt : ReadImageFlags = ReadImageFlags.Data

The read flags to use.

returns → IImageInfo

The IImageInfo object or null iff IImage.ReadImageInfo2 has thrown one of its declared exceptions.

Delegates to IImage.ReadImageInfo2 to create an IImageReader object that reads the image metadata of this image descriptor.

Read​Image​Null

[OwnerReturn]
public static method ReadImageNull → (1)

flags opt : ReadImageFlags = ReadImageFlags.Data

The read flags to use.

returns → IImageReader

The IImageReader object or null iff IImage.ReadImage2 has thrown one of its declared exceptions.

Delegates to IImage.ReadImage2 to create an IImageReader object that reads the image content of this image descriptor.

Sharpen

public static method Sharpen → (3)

detail in : IImage own

[not-null]
The high-resolution detail image to use for sharpening.

scale opt : float32 = 1

[>=0]
Scale factor to apply to difference between full and reduced resolution.

downsample opt : int32 = 4

[>0]
The detail in image will be downsampled by this factor. The difference between the full and reduced resolutions will be used to sharpen this image.

returns → IImage

The resulting image.

Performs sharpening on this image.

Write​File

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

imageFile in : Path

[not-null]
The image file to write.

returns → IOperation

The background operation.

Outputs the pixels of this image to the given image file, using default options.

This method delegates to IImage.Write, passing a temporary IImageWriter object that has been obtained via ImageFormat.WriteImage of ImageFormat.Any.

IOException

If this image format does not support writing (i.e. IFileFormat.CanWrite would return false).

See also

IImage.Write