ImageDecodeOptions Class

Immutable options for the eager Image.Load and Image.LoadAsync methods.

public sealed class ImageDecodeOptions

Constructors

NameDescription
ImageDecodeOptions()

ImageDecodeOptions()

ImageDecodeOptions.cs
public ImageDecodeOptions()

No documentation is available.

Properties

NameDescription
CieLabConversionGets the color conversion applied to images whose samples are CIE L*a*b* colors (TIFF pages), or null (the default) to reject them with an UnsupportedImageFeatureException.
CmykConversionGets the color conversion applied to images whose samples are CMYK inks (four-component JPEG, separated TIFF, JPEG 2000, JPEG XL with a black channel) when they are not loaded as CMYK pixels, or null (the default) to reject them with an UnsupportedImageFeatureException.
ConfigurationGets the configuration of the loaded image (resource limits, parallelism). Defaults to ImageConfiguration.Default.
ConversionGets the options used when a typed load converts decoded samples to the requested pixel type. Defaults to PixelConversionOptions.Default.
DefaultGets the default options.
FrameLimitGets the maximum number of displayed frames to decode, or null to decode all frames. This is a deliberate prefix selection: decoding stops after the requested number of frames and the remaining data is not examined or validated. A separate poster frame is always preserved and is not counted.
RegionGets the area of the image to decode, in pixels of the stored image at full resolution (before its orientation is applied), or null (the default) to decode the whole image. The decoded image holds the part of the area that is in the image.
ScaleDenominatorGets the factor by which the decoder divides the width and the height of the image, a power of two. Defaults to 1: the image is decoded at full resolution.
TargetSizeGets the smallest size the decoder needs to produce, or null (the default) to decode at full resolution. A file that can be decoded at a reduced resolution is decoded at the largest ImageDecodeOptions.ScaleDenominator it allows whose size is still at least this size in both dimensions; any other file is decoded at full resolution.

CieLabConversion

ImageDecodeOptions.cs

Gets the color conversion applied to images whose samples are CIE L*a*b* colors (TIFF pages), or null (the default) to reject them with an UnsupportedImageFeatureException.

public CieLabConversionOptions? CieLabConversion { get; init; }

Property value

CieLabConversionOptions?

Remarks

No pixel format holds L*a*b* samples, so such an image can only be loaded by converting its colors, which can lose the ones outside the gamut of the destination. Like every color conversion it is explicit: set new CieLabConversionOptions() to convert to sRGB. Other images are not affected.

CmykConversion

ImageDecodeOptions.cs

Gets the color conversion applied to images whose samples are CMYK inks (four-component JPEG, separated TIFF, JPEG 2000, JPEG XL with a black channel) when they are not loaded as CMYK pixels, or null (the default) to reject them with an UnsupportedImageFeatureException.

public CmykConversionOptions? CmykConversion { get; init; }

Property value

CmykConversionOptions?

Remarks

A JPEG or TIFF image keeps its inks when it is loaded as Cmyk32 or Cmyk64 pixels; another pixel format converts its colors. Like every color conversion it is explicit: set new CmykConversionOptions() to convert to sRGB here, or PixelConversionOptions.CmykConversion to convert the CMYK pixels. Other images are not affected.

Gets the configuration of the loaded image (resource limits, parallelism). Defaults to ImageConfiguration.Default.

public ImageConfiguration Configuration { get; init; }

Property value

ImageConfiguration

Exceptions

ArgumentNullException
The value is null.

Gets the options used when a typed load converts decoded samples to the requested pixel type. Defaults to PixelConversionOptions.Default.

public PixelConversionOptions Conversion { get; init; }

Property value

PixelConversionOptions

Exceptions

ArgumentNullException
The value is null.

Gets the default options.

public static ImageDecodeOptions Default { get; }

Property value

ImageDecodeOptions

Gets the maximum number of displayed frames to decode, or null to decode all frames. This is a deliberate prefix selection: decoding stops after the requested number of frames and the remaining data is not examined or validated. A separate poster frame is always preserved and is not counted.

public int? FrameLimit { get; init; }

Property value

int?

Exceptions

ArgumentOutOfRangeException
The value is not positive.

Gets the area of the image to decode, in pixels of the stored image at full resolution (before its orientation is applied), or null (the default) to decode the whole image. The decoded image holds the part of the area that is in the image.

public Rectangle? Region { get; init; }

Property value

Rectangle?

Exceptions

ArgumentOutOfRangeException
The area is empty or starts at a negative coordinate.

Remarks

A JPEG 2000 file only decodes the tiles that the area meets, in them the code-blocks whose coefficients reach it, and the wavelet transformation only rebuilds the samples the area needs: the samples of the area are those of a full decode, for less time and memory, even in an image of one tile. With ImageDecodeOptions.ScaleDenominator or ImageDecodeOptions.TargetSize, the area is divided like the image: its edges are rounded up, as the reference grid of the format does, and an area narrower than a pixel of the reduced image keeps the pixel that covers it.

A JPEG file transforms only the blocks that the area reads, and a sequential file is not decoded below the area. With ImageDecodeOptions.ScaleDenominator or ImageDecodeOptions.TargetSize, the image holds the pixels of the reduced image that cover the area.

A TIFF page reads and decompresses only the strips or the tiles that the area meets, and an AVIF or HEIC grid decodes only the tiles that the area needs. An AVIF or HEIC image that is not a grid is decoded down to the rows the area needs (with a margin for the in-loop filters, a row of 64 or 128 pixels at most), into planes that hold these rows only, and an AVIF frame of several tiles skips the tiles far from the area; an image that is not a single intra picture (an AVIF image of several layers), an image built from other images and each image of a sequence are decoded whole, and only the area is kept. The pixels are those of a full decode in that area. The blocks, the rows and the tiles that are not decoded are not validated: an error in them is not reported.

The other formats cannot decode an area: a load with a region is an UnsupportedImageFeatureException, and so is an area that does not meet the image.

ScaleDenominator

ImageDecodeOptions.cs

Gets the factor by which the decoder divides the width and the height of the image, a power of two. Defaults to 1: the image is decoded at full resolution.

public int ScaleDenominator { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not a positive power of two.
ArgumentException
The value is not 1 and ImageDecodeOptions.TargetSize is set.

Remarks

The decoded image has ceil(width / ScaleDenominator) by ceil(height / ScaleDenominator) pixels, computed from fewer samples than a full decode, for less time and memory, by the formats that support it (see the format reference of the readme). The pixels are close to a resize of the full image, not equal to it; an interlaced PNG image gives the pixel at the top left of each block, from its first Adam7 passes. The metadata is the one of the file, like after a resize.

A file that cannot be decoded at this scale (a format that only decodes at full resolution, or a scale that the file does not allow) is an UnsupportedImageFeatureException. Set ImageDecodeOptions.TargetSize instead to get the smallest image the file allows without failing. The two properties cannot be set together.

Gets the smallest size the decoder needs to produce, or null (the default) to decode at full resolution. A file that can be decoded at a reduced resolution is decoded at the largest ImageDecodeOptions.ScaleDenominator it allows whose size is still at least this size in both dimensions; any other file is decoded at full resolution.

public Size? TargetSize { get; init; }

Property value

Size?

Exceptions

ArgumentOutOfRangeException
The width or the height of the value is zero.
ArgumentException
The value is not null and ImageDecodeOptions.ScaleDenominator is not 1.

Remarks

The size is compared with the stored dimensions of the image, before its orientation is applied. The decoded image is usually larger than the target: resize it afterwards to get an exact size. For a thumbnail, this is much faster than resizing a full decode, with nearly the same result.