DngRawImage Class

The raw image of a DNG file before it is demosaiced: the samples it stores (the values of the sensor, a color filter array or linear raw data), the parameters that map them to linear reference values (DNG specification 1.7.1, chapter 5), and those values. Image.Load renders the same samples to an image; this type gives what precedes the demosaicing, which does not depend on the algorithm of a reader.

public sealed class DngRawImage : IDisposable

Remarks

DngRawImage.CopyStoredRow gives the stored samples of the whole raw image after opcode list 1 (stage 1 of the DNG processing model): integers, or the values of floating-point samples. DngRawImage.CopyLinearRow gives the samples of the active area mapped to linear reference values and clipped to [0, 1], after opcode list 2 (stage 2): 0 is no light and 1 the white level.

Loading reads the whole input into memory (up to ImageResourceLimits.MaxEncodedBytes) and decodes the samples once; they are held in memory charged to the limits of the configuration until the instance is disposed.

Implements

Properties

NameDescription
ActiveAreaGets the active area: the rectangle of the stored image that holds the image, outside its masked pixels (ActiveArea).
BitsPerSampleGets the number of bits of a stored sample (8 to 16 for integers; 16, 24 or 32 for floating-point numbers).
BlackLevelDeltaHGets the black level added for each column of the active area (BlackLevelDeltaH), or null.
BlackLevelDeltaVGets the black level added for each row of the active area (BlackLevelDeltaV), or null.
BlackLevelRepeatColumnsGets the number of columns of the repeating pattern of the black levels (BlackLevelRepeatDim).
BlackLevelRepeatRowsGets the number of rows of the repeating pattern of the black levels (BlackLevelRepeatDim).
BlackLevelsGets the black levels of the repeating pattern (BlackLevel), in row, column and sample order; the origin of the pattern is the top-left corner of the active area.
CfaPatternColumnsGets the number of columns of the repeating pattern of the color filter array (1 for linear raw data).
CfaPatternRowsGets the number of rows of the repeating pattern of the color filter array (1 for linear raw data).
CfaPlaneColorsGets the CFA colors of the planes of the camera color space (CFAPlaneColor): 0 red, 1 green, 2 blue, 3 cyan, 4 magenta, 5 yellow, 6 white. Empty for linear raw data.
DefaultCropGets the default crop, relative to the top-left corner of the active area (DefaultCropOrigin and DefaultCropSize, rounded to whole pixels): the area of the rendered image.
IsColorFilterArrayGets a value indicating whether the samples are those of a color filter array (CFA), rather than linear raw data (LinearRaw).
IsFloatingPointGets a value indicating whether the stored samples are floating-point numbers.
LinearizationTableGets the linearization table (LinearizationTable), or null.
SamplesPerPixelGets the number of samples of a pixel: 1 for a color filter array, 1 to 4 for linear raw data.
SizeGets the size of the stored raw image (ImageWidth and ImageLength of the raw IFD).
WhiteLevelsGets the white level of each sample (WhiteLevel).

ActiveArea

DngRawImage.cs

Gets the active area: the rectangle of the stored image that holds the image, outside its masked pixels (ActiveArea).

public Rectangle ActiveArea { get; }

Property value

Rectangle

BitsPerSample

DngRawImage.cs

Gets the number of bits of a stored sample (8 to 16 for integers; 16, 24 or 32 for floating-point numbers).

public int BitsPerSample { get; }

Property value

int

BlackLevelDeltaH

DngRawImage.cs

Gets the black level added for each column of the active area (BlackLevelDeltaH), or null.

public ReadOnlyCollection<double>? BlackLevelDeltaH { get; }

BlackLevelDeltaV

DngRawImage.cs

Gets the black level added for each row of the active area (BlackLevelDeltaV), or null.

public ReadOnlyCollection<double>? BlackLevelDeltaV { get; }

BlackLevelRepeatColumns

DngRawImage.cs

Gets the number of columns of the repeating pattern of the black levels (BlackLevelRepeatDim).

public int BlackLevelRepeatColumns { get; }

Property value

int

BlackLevelRepeatRows

DngRawImage.cs

Gets the number of rows of the repeating pattern of the black levels (BlackLevelRepeatDim).

public int BlackLevelRepeatRows { get; }

Property value

int

BlackLevels

DngRawImage.cs

Gets the black levels of the repeating pattern (BlackLevel), in row, column and sample order; the origin of the pattern is the top-left corner of the active area.

public ReadOnlyCollection<double> BlackLevels { get; }

CfaPatternColumns

DngRawImage.cs

Gets the number of columns of the repeating pattern of the color filter array (1 for linear raw data).

public int CfaPatternColumns { get; }

Property value

int

CfaPatternRows

DngRawImage.cs

Gets the number of rows of the repeating pattern of the color filter array (1 for linear raw data).

public int CfaPatternRows { get; }

Property value

int

CfaPlaneColors

DngRawImage.cs

Gets the CFA colors of the planes of the camera color space (CFAPlaneColor): 0 red, 1 green, 2 blue, 3 cyan, 4 magenta, 5 yellow, 6 white. Empty for linear raw data.

public ReadOnlyCollection<byte> CfaPlaneColors { get; }

DefaultCrop

DngRawImage.cs

Gets the default crop, relative to the top-left corner of the active area (DefaultCropOrigin and DefaultCropSize, rounded to whole pixels): the area of the rendered image.

public Rectangle DefaultCrop { get; }

Property value

Rectangle

IsColorFilterArray

DngRawImage.cs

Gets a value indicating whether the samples are those of a color filter array (CFA), rather than linear raw data (LinearRaw).

public bool IsColorFilterArray { get; }

Property value

bool

IsFloatingPoint

DngRawImage.cs

Gets a value indicating whether the stored samples are floating-point numbers.

public bool IsFloatingPoint { get; }

Property value

bool

LinearizationTable

DngRawImage.cs

Gets the linearization table (LinearizationTable), or null.

public ReadOnlyCollection<ushort>? LinearizationTable { get; }

SamplesPerPixel

DngRawImage.cs

Gets the number of samples of a pixel: 1 for a color filter array, 1 to 4 for linear raw data.

public int SamplesPerPixel { get; }

Property value

int

Gets the size of the stored raw image (ImageWidth and ImageLength of the raw IFD).

public Size Size { get; }

Property value

Size

WhiteLevels

DngRawImage.cs

Gets the white level of each sample (WhiteLevel).

public ReadOnlyCollection<double> WhiteLevels { get; }

Methods

NameDescription
CopyLinearRow(int, Span<float>)Copies a row of the active area mapped to linear reference values, after opcode list 2 (stage 2): 0 is no light and 1 the white level, DngRawImage.SamplesPerPixel values per pixel, clipped to [0, 1].
CopyStoredRow(int, Span<float>)Copies a row of the stored samples of the whole raw image, after opcode list 1 (stage 1): the integer values the file stores, or the values of its floating-point samples, DngRawImage.SamplesPerPixel per pixel.
Dispose()Releases the samples.
GetCfaColor(int, int)Gets the CFA color of a pixel, from its coordinates relative to the top-left corner of the active area (the origin of the pattern).
Load(Stream, ImageConfiguration?)Loads the raw image of a DNG file from a stream, read from its current position to its end.
Load(ReadOnlySpan<byte>, ImageConfiguration?)Loads the raw image of DNG data.
Load(string, ImageConfiguration?)Loads the raw image of a DNG file.

CopyLinearRow(int, Span<float>)

DngRawImage.cs

Copies a row of the active area mapped to linear reference values, after opcode list 2 (stage 2): 0 is no light and 1 the white level, DngRawImage.SamplesPerPixel values per pixel, clipped to [0, 1].

public void CopyLinearRow(int y, Span<float> destination)

Parameters

y int
The row, relative to the active area.
destination Span<float>
The destination, at least ActiveArea.Width * SamplesPerPixel values.

Exceptions

ArgumentOutOfRangeException
y is out of range.
ArgumentException
destination is too short.
ObjectDisposedException
The instance is disposed.

CopyStoredRow(int, Span<float>)

DngRawImage.cs

Copies a row of the stored samples of the whole raw image, after opcode list 1 (stage 1): the integer values the file stores, or the values of its floating-point samples, DngRawImage.SamplesPerPixel per pixel.

public void CopyStoredRow(int y, Span<float> destination)

Parameters

y int
The row, from 0 to the height of DngRawImage.Size.
destination Span<float>
The destination, at least Size.Width * SamplesPerPixel values.

Exceptions

ArgumentOutOfRangeException
y is out of range.
ArgumentException
destination is too short.
ObjectDisposedException
The instance is disposed.

Releases the samples.

public void Dispose()

GetCfaColor(int, int)

DngRawImage.cs

Gets the CFA color of a pixel, from its coordinates relative to the top-left corner of the active area (the origin of the pattern).

public byte GetCfaColor(int x, int y)

Parameters

x int
The column, relative to the active area.
y int
The row, relative to the active area.

Returns

byte The CFA color (an entry of DngRawImage.CfaPlaneColors).

Exceptions

ArgumentOutOfRangeException
x or y is negative.
InvalidOperationException
The samples are linear raw data, which has no color filter array.

Load overloads

Load(Stream, ImageConfiguration?)

DngRawImage.cs

Loads the raw image of a DNG file from a stream, read from its current position to its end.

public static DngRawImage Load(Stream stream, ImageConfiguration? configuration = null)
Parameters
stream Stream
The stream; it is not closed.
configuration ImageConfiguration?
The configuration, or null for ImageConfiguration.Default.
Returns

DngRawImage The raw image, owned by the caller.

Exceptions
ArgumentNullException
stream is null.
ArgumentException
stream is not readable.
UnknownImageFormatException
The data is not a DNG file.
InvalidImageContentException
The data is malformed.
UnsupportedImageFeatureException
The raw image uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.

Load(ReadOnlySpan<byte>, ImageConfiguration?)

DngRawImage.cs

Loads the raw image of DNG data.

public static DngRawImage Load(ReadOnlySpan<byte> data, ImageConfiguration? configuration = null)
Parameters
data ReadOnlySpan<byte>
The encoded data.
configuration ImageConfiguration?
The configuration, or null for ImageConfiguration.Default.
Returns

DngRawImage The raw image, owned by the caller.

Exceptions
UnknownImageFormatException
The data is not a DNG file.
InvalidImageContentException
The data is malformed.
UnsupportedImageFeatureException
The raw image uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.

Load(string, ImageConfiguration?)

DngRawImage.cs

Loads the raw image of a DNG file.

public static DngRawImage Load(string path, ImageConfiguration? configuration = null)
Parameters
path string
The path of the file.
configuration ImageConfiguration?
The configuration, or null for ImageConfiguration.Default.
Returns

DngRawImage The raw image, owned by the caller.

Exceptions
ArgumentException
path is null or empty.
UnknownImageFormatException
The file is not a DNG file.
InvalidImageContentException
The file is malformed.
UnsupportedImageFeatureException
The raw image uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.
IOException
The file cannot be read.