Class TiffRgbaImage

RGBA-style image support. Provides methods for decoding images into RGBA (or other) format.

Inheritance

System.Object

TiffRgbaImage

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: BitMiracle.LibTiff.Classic

Assembly: BitMiracle.LibTiff.NET.dll

Syntax

public class TiffRgbaImage

Remarks

TiffRgbaImage provide a high-level interface through which TIFF images may be read into memory. Images may be strip- or tile-based and have a variety of different characteristics: bits/sample, samples/pixel, photometric, etc. The target raster format can be customized to a particular application's needs by installing custom methods that manipulate image data according to application requirements.

The default usage for this class: check if an image can be processed using RGBAImageOK(out String), construct an instance of TiffRgbaImage using Create(Tiff, Boolean, out String) and then read and decode an image into a target raster using GetRaster(Int32[], Int32, Int32, Int32). GetRaster(Int32[], Int32, Int32, Int32) can be called multiple times to decode an image using different state parameters. If multiple images are to be displayed and there is not enough space for each of the decoded rasters, multiple instances of TiffRgbaImage can be managed and then calls can be made to GetRaster(Int32[], Int32, Int32, Int32) as needed to display an image.

To use the core support for reading and processing TIFF images, but write the resulting raster data in a different format one need only override the "put methods" used to store raster data. These methods are initially setup by Create(Tiff, Boolean, out String) to point to methods that pack raster data in the default ABGR pixel format. Two different methods are used according to the physical organization of the image data in the file: one for PLANARCONFIG = PlanarConfig.CONTIG (packed samples), and another for PLANARCONFIG = PlanarConfig.SEPARATE (separated samples). Note that this mechanism can be used to transform the data before storing it in the raster. For example one can convert data to colormap indices for display on a colormap display.

To setup custom "put" method please use PutContig property for contiguously packed samples and/or PutSeparate property for separated samples.

The methods of TiffRgbaImage support the most commonly encountered flavors of TIFF. It is possible to extend this support by overriding the "get method" invoked by GetRaster(Int32[], Int32, Int32, Int32) to read TIFF image data. Details of doing this are a bit involved, it is best to make a copy of an existing get method and modify it to suit the needs of an application. To setup custom "get" method please use Get property.

Properties

Alpha

Gets the type of alpha data present.

Declaration

public ExtraSample Alpha { get; }

Property Value

Type	Description
ExtraSample	The type of alpha data present.

BitsPerSample

Gets the image bits per sample count.

Declaration

public short BitsPerSample { get; }

Property Value

Type	Description
System.Int16	The image bits per sample count.

Get

Gets or sets the "get" method (the method that is called to produce RGBA raster).

Declaration

public TiffRgbaImage.GetDelegate Get { get; set; }

Property Value

Type	Description
TiffRgbaImage.GetDelegate	The "get" method.

Height

Gets the image height.

Declaration

public int Height { get; }

Property Value

Type	Description
System.Int32	The image height.

IsContig

Gets a value indicating whether image data has contiguous (packed) or separated samples.

Declaration

public bool IsContig { get; }

Property Value

Type	Description
System.Boolean	true if this image data has contiguous (packed) samples; otherwise, false.

Orientation

Gets the image orientation.

Declaration

public Orientation Orientation { get; }

Property Value

Type	Description
Orientation	The image orientation.

Photometric

Gets the photometric interpretation of the image data.

Declaration

public Photometric Photometric { get; }

Property Value

Type	Description
Photometric	The photometric interpretation of the image data.

PutContig

Gets or sets the "put" method (the method that is called to pack pixel data in the raster) used when converting contiguously packed samples.

Declaration

public TiffRgbaImage.PutContigDelegate PutContig { get; set; }

Property Value

Type	Description
TiffRgbaImage.PutContigDelegate	The "put" method used when converting contiguously packed samples.

PutSeparate

Gets or sets the "put" method (the method that is called to pack pixel data in the raster) used when converting separated samples.

Declaration

public TiffRgbaImage.PutSeparateDelegate PutSeparate { get; set; }

Property Value

Type	Description
TiffRgbaImage.PutSeparateDelegate	The "put" method used when converting separated samples.

ReqOrientation

Gets or sets the requested orientation.

Declaration

public Orientation ReqOrientation { get; set; }

Property Value

Type	Description
Orientation	The requested orientation.

Remarks

The GetRaster(Int32[], Int32, Int32, Int32) method uses this value when placing converted image data into raster buffer.

SamplesPerPixel

Gets the image samples per pixel count.

Declaration

public short SamplesPerPixel { get; }

Property Value

Type	Description
System.Int16	The image samples per pixel count.

Width

Gets the image width.

Declaration

public int Width { get; }

Property Value

Type	Description
System.Int32	The image width.

Methods

Create(Tiff, Boolean, out String)

Creates new instance of the TiffRgbaImage class.

Declaration

public static TiffRgbaImage Create(Tiff tif, bool stopOnError, out string errorMsg)

Parameters

Type	Name	Description
Tiff	tif	The instance of the BitMiracle.LibTiff.Classic class used to retrieve image data.
System.Boolean	stopOnError	if set to true then an error will terminate the conversion; otherwise "get" methods will continue processing data until all the possible data in the image have been requested.
System.String	errorMsg	The error message (if any) gets placed here.

Returns

Type	Description
TiffRgbaImage	New instance of the TiffRgbaImage class if the image specified by tif can be converted to RGBA format; otherwise, null is returned and errorMsg contains the reason why it is being rejected.

GetRaster(Int32[], Int32, Int32, Int32)

Reads the underlaying TIFF image and decodes it into RGBA format raster.

Declaration

public bool GetRaster(int[] raster, int offset, int width, int height)

Parameters

Type	Name	Description
System.Int32[]	raster	The raster (the buffer to place decoded image data to).
System.Int32	offset	The zero-based byte offset in raster at which to begin storing decoded bytes.
System.Int32	width	The raster width.
System.Int32	height	The raster height.

Returns

Type	Description
System.Boolean	true if the image was successfully read and decoded; otherwise, false.

Remarks

GetRaster reads image into memory using current "get" (Get) method, storing the result in the user supplied RGBA raster using one of the "put" (PutContig or PutSeparate) methods. The raster is assumed to be an array of width times height 32-bit entries, where width must be less than or equal to the width of the image (height may be any non-zero size). If the raster dimensions are smaller than the image, the image data is cropped to the raster bounds. If the raster height is greater than that of the image, then the image data placement depends on the value of ReqOrientation property. Note that the raster is assumed to be organized such that the pixel at location (x, y) is raster[y * width + x]; with the raster origin specified by the value of ReqOrientation property.

Raster pixels are 8-bit packed red, green, blue, alpha samples. The GetR(Int32), GetG(Int32), GetB(Int32), and GetA(Int32) should be used to access individual samples. Images without Associated Alpha matting information have a constant Alpha of 1.0 (255).

GetRaster converts non-8-bit images by scaling sample values. Palette, grayscale, bilevel, CMYK, and YCbCr images are converted to RGB transparently. Raster pixels are returned uncorrected by any colorimetry information present in the directory.

Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must be either 1, 3, or 4 (i.e. SamplesPerPixel minus ExtraSamples).

Palette image colormaps that appear to be incorrectly written as 8-bit values are automatically scaled to 16-bits.

All error messages are directed to the current error handler.