Class SampleImage

Namespace

Egami.Formats

Assembly

Egami.dll

An image as its codestream stores it: every component's samples at their own precision and sign, with no color conversion, widening or offset. For a container that keeps its own pixel description, such as DICOM, which needs the stored values to apply its rescale, window and color rules itself. JPEG (baseline, extended 12-bit and lossless at 2 to 16 bits), JPEG 2000 and JPEG XL load this way.

[Experimental("EGAMIX001", UrlFormat = "https://github.com/inexin/Egami/blob/main/docs/articles/formats/index.md#stored-samples")]
public sealed class SampleImage

Inheritance

object

SampleImage

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// The values the codestream stores: no color conversion, no widening to 8 or 16 bits, signed samples kept signed.
SampleImage image = SampleImage.Load("duck.jpg");
Console.WriteLine($"{image.Color}, {image.Components.Count} components of {image.Components[0].Precision} bits");

// A YCbCr JPEG stays YCbCr: luma, then the two chroma samples of each pixel, at full resolution.
Span<int> row = image.Row(0);
int luma = row[0], cb = row[1], cr = row[2];

Remarks

Samples are interleaved in component order, one int each, so signed values keep their sign. Components sampled at less than full resolution are brought to the image's size: JPEG's chroma upsampled as Load(Stream, EgamiContext?, ReaderOptions?) does it (or replicated with FastUpsampling), JPEG 2000's replicated.

A preview, as DICOM is: marked [Experimental] with the diagnostic EGAMIX001, so a call does not compile until the app suppresses that id, and it may change in any minor release.

Properties

Color

Gets what the components are, as far as the codestream says: YCbCr means no conversion to RGB was made.

public SampleColor Color { get; }

Property Value

SampleColor

Components

Gets each component's precision and sign, in the order the samples are interleaved.

public IReadOnlyList<SampleComponent> Components { get; }

Property Value

IReadOnlyList<SampleComponent>

Height

Gets the height in pixels.

public int Height { get; }

Property Value

int

Metadata

Gets the metadata the file holds, with any warnings from a lenient read of a damaged codestream.

public RasterMetadata Metadata { get; }

Property Value

RasterMetadata

Samples

Gets every sample, row after row, each pixel's components together: sample c of pixel (x, y) is at ((y * Width) + x) * Components.Count + c.

public Memory<int> Samples { get; }

Property Value

Memory<int>

Width

Gets the width in pixels.

public int Width { get; }

Property Value

int

Methods

Load(Stream, EgamiContext?, ReaderOptions?)

Decodes an image to its stored samples. The format comes from the data, as for Load(Stream, EgamiContext?, ReaderOptions?).

public static SampleImage Load(Stream stream, EgamiContext? context = null, ReaderOptions? options = null)

Parameters

stream Stream

The encoded image. It is read from its current position and left open.

context EgamiContext

The context, or null for Default.

options ReaderOptions

How to read, or null for Default. Format options apply where they make sense, such as FastUpsampling and MaxQualityLayers.

Returns

SampleImage

The samples.

Examples

// The values the codestream stores: no color conversion, no widening to 8 or 16 bits, signed samples kept signed.
SampleImage image = SampleImage.Load("duck.jpg");
Console.WriteLine($"{image.Color}, {image.Components.Count} components of {image.Components[0].Precision} bits");

// A YCbCr JPEG stays YCbCr: luma, then the two chroma samples of each pixel, at full resolution.
Span<int> row = image.Row(0);
int luma = row[0], cb = row[1], cr = row[2];

Exceptions

NotSupportedException

The format has no stored samples to give, or this image's do not fit: floating-point or more than 31 bits, or a JPEG with 2 or 4 components. Also thrown for Region, MinimumSize and ConvertColorTo.

UnsupportedFormatException

No registered format matches the data.

CorruptDataException

The data breaks the format's rules.

LimitExceededException

The image breaks a safety limit.

ArgumentNullException

stream is null.

Load(ReadOnlyMemory<byte>, EgamiContext?, ReaderOptions?)

Decodes an image in memory to its stored samples. See Load(Stream, EgamiContext?, ReaderOptions?).

public static SampleImage Load(ReadOnlyMemory<byte> data, EgamiContext? context = null, ReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The encoded image.

context EgamiContext

The context, or null for Default.

options ReaderOptions

How to read, or null for Default.

Returns

SampleImage

The samples.

Examples

// The values the codestream stores: no color conversion, no widening to 8 or 16 bits, signed samples kept signed.
SampleImage image = SampleImage.Load("duck.jpg");
Console.WriteLine($"{image.Color}, {image.Components.Count} components of {image.Components[0].Precision} bits");

// A YCbCr JPEG stays YCbCr: luma, then the two chroma samples of each pixel, at full resolution.
Span<int> row = image.Row(0);
int luma = row[0], cb = row[1], cr = row[2];

Exceptions

NotSupportedException

The format or image has no stored samples to give.

UnsupportedFormatException

No registered format matches the data.

CorruptDataException

The data breaks the format's rules.

LimitExceededException

The image breaks a safety limit.

Load(ReadOnlyMemory<byte>, FormatInfo, EgamiContext?, ReaderOptions?)

Decodes an image of a known format to its stored samples, without detecting the format: a codestream taken from a container, such as a DICOM pixel data fragment. See Load(Stream, EgamiContext?, ReaderOptions?).

public static SampleImage Load(ReadOnlyMemory<byte> data, FormatInfo format, EgamiContext? context = null, ReaderOptions? options = null)

Parameters

data ReadOnlyMemory<byte>

The encoded image.

format FormatInfo

The format to read with, such as Info. It need not be registered in the context.

context EgamiContext

The context, or null for Default.

options ReaderOptions

How to read, or null for Default.

Returns

SampleImage

The samples.

Examples

// A codestream taken out of a container, such as a DICOM pixel data fragment, is read as the format the container names.
SampleImage image = SampleImage.Load(fragment, JpegFormat.Info);
SampleComponent gray = image.Components[0];
int first = image.Samples.Span[0];       // 0 to 4095 for 12 unsigned bits

Exceptions

NotSupportedException

The format or image has no stored samples to give.

UnsupportedFormatException

format has no reader.

CorruptDataException

The data breaks the format's rules.

LimitExceededException

The image breaks a safety limit.

ArgumentNullException

format is null.

Load(string, EgamiContext?, ReaderOptions?)

Decodes an image file to its stored samples. See Load(Stream, EgamiContext?, ReaderOptions?).

public static SampleImage Load(string path, EgamiContext? context = null, ReaderOptions? options = null)

Parameters

path string

The file path.

context EgamiContext

The context, or null for Default.

options ReaderOptions

How to read, or null for Default.

Returns

SampleImage

The samples.

Examples

// The values the codestream stores: no color conversion, no widening to 8 or 16 bits, signed samples kept signed.
SampleImage image = SampleImage.Load("duck.jpg");
Console.WriteLine($"{image.Color}, {image.Components.Count} components of {image.Components[0].Precision} bits");

// A YCbCr JPEG stays YCbCr: luma, then the two chroma samples of each pixel, at full resolution.
Span<int> row = image.Row(0);
int luma = row[0], cb = row[1], cr = row[2];

Exceptions

NotSupportedException

The format or image has no stored samples to give.

UnsupportedFormatException

No registered format matches the data.

CorruptDataException

The data breaks the format's rules.

LimitExceededException

The image breaks a safety limit.

FileNotFoundException

The file does not exist.

Row(int)

Returns row y: Width pixels of Components samples each.

public Span<int> Row(int y)

Parameters

y int

The row, from 0 at the top.

Returns

Span<int>

The row's samples.

Exceptions

ArgumentOutOfRangeException

y is outside the image.