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 : IDisposableRemarks
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
| Name | Description |
|---|---|
| ActiveArea | Gets the active area: the rectangle of the stored image that holds the image, outside its masked pixels (ActiveArea). |
| BitsPerSample | Gets the number of bits of a stored sample (8 to 16 for integers; 16, 24 or 32 for floating-point numbers). |
| BlackLevelDeltaH | Gets the black level added for each column of the active area (BlackLevelDeltaH), or null. |
| BlackLevelDeltaV | Gets the black level added for each row of the active area (BlackLevelDeltaV), or null. |
| BlackLevelRepeatColumns | Gets the number of columns of the repeating pattern of the black levels (BlackLevelRepeatDim). |
| BlackLevelRepeatRows | Gets the number of rows of the repeating pattern of the black levels (BlackLevelRepeatDim). |
| BlackLevels | 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. |
| CfaPatternColumns | Gets the number of columns of the repeating pattern of the color filter array (1 for linear raw data). |
| CfaPatternRows | Gets the number of rows of the repeating pattern of the color filter array (1 for linear raw data). |
| CfaPlaneColors | 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. |
| DefaultCrop | 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. |
| IsColorFilterArray | Gets a value indicating whether the samples are those of a color filter array (CFA), rather than linear raw data (LinearRaw). |
| IsFloatingPoint | Gets a value indicating whether the stored samples are floating-point numbers. |
| LinearizationTable | Gets the linearization table (LinearizationTable), or null. |
| SamplesPerPixel | Gets the number of samples of a pixel: 1 for a color filter array, 1 to 4 for linear raw data. |
| Size | Gets the size of the stored raw image (ImageWidth and ImageLength of the raw IFD). |
| WhiteLevels | Gets the white level of each sample (WhiteLevel). |
ActiveArea
DngRawImage.csBitsPerSample
DngRawImage.csBlackLevelDeltaH
DngRawImage.csGets the black level added for each column of the active area (BlackLevelDeltaH), or null.
public ReadOnlyCollection<double>? BlackLevelDeltaH { get; }Property value
BlackLevelDeltaV
DngRawImage.csGets the black level added for each row of the active area (BlackLevelDeltaV), or null.
public ReadOnlyCollection<double>? BlackLevelDeltaV { get; }Property value
BlackLevelRepeatColumns
DngRawImage.csBlackLevelRepeatRows
DngRawImage.csBlackLevels
DngRawImage.csGets 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; }Property value
CfaPatternColumns
DngRawImage.csCfaPatternRows
DngRawImage.csCfaPlaneColors
DngRawImage.csGets 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; }Property value
DefaultCrop
DngRawImage.csIsColorFilterArray
DngRawImage.csIsFloatingPoint
DngRawImage.csLinearizationTable
DngRawImage.csGets the linearization table (LinearizationTable), or null.
public ReadOnlyCollection<ushort>? LinearizationTable { get; }Property value
SamplesPerPixel
DngRawImage.csSize
DngRawImage.csWhiteLevels
DngRawImage.csGets the white level of each sample (WhiteLevel).
public ReadOnlyCollection<double> WhiteLevels { get; }Property value
Methods
| Name | Description |
|---|---|
| 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.csCopies 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].
Parameters
yint- The row, relative to the active area.
destinationSpan<float>- The destination, at least
ActiveArea.Width * SamplesPerPixelvalues.
Exceptions
ArgumentOutOfRangeExceptionyis out of range.ArgumentExceptiondestinationis too short.ObjectDisposedException- The instance is disposed.
CopyStoredRow(int, Span<float>)
DngRawImage.csCopies 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.
Parameters
yint- The row, from 0 to the height of
DngRawImage.Size. destinationSpan<float>- The destination, at least
Size.Width * SamplesPerPixelvalues.
Exceptions
ArgumentOutOfRangeExceptionyis out of range.ArgumentExceptiondestinationis too short.ObjectDisposedException- The instance is disposed.
Dispose()
DngRawImage.csReleases the samples.
public void Dispose()GetCfaColor(int, int)
DngRawImage.csGets the CFA color of a pixel, from its coordinates relative to the top-left corner of the active area (the origin of the pattern).
Parameters
Returns
byte The CFA color (an entry of DngRawImage.CfaPlaneColors).
Exceptions
ArgumentOutOfRangeExceptionxoryis negative.InvalidOperationException- The samples are linear raw data, which has no color filter array.
Load overloads
Load(Stream, ImageConfiguration?)
DngRawImage.csLoads 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
streamStream- The stream; it is not closed.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.Default.
Returns
DngRawImage The raw image, owned by the caller.
Exceptions
ArgumentNullExceptionstreamisnull.ArgumentExceptionstreamis 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.csLoads the raw image of DNG data.
public static DngRawImage Load(ReadOnlySpan<byte> data, ImageConfiguration? configuration = null)Parameters
dataReadOnlySpan<byte>- The encoded data.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.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.csLoads the raw image of a DNG file.
public static DngRawImage Load(string path, ImageConfiguration? configuration = null)Parameters
pathstring- The path of the file.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.Default.
Returns
DngRawImage The raw image, owned by the caller.
Exceptions
ArgumentExceptionpathisnullor 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.