Table of Contents

Class RasterMetadata

Namespace
Egami.Metadata
Assembly
Egami.dll

Metadata that belongs to the whole raster. It is kept apart from the pixels and survives operations unless an operation makes it wrong. Metadata problems never fail a load: broken blocks are kept as bytes and noted in Warnings.

public sealed class RasterMetadata
Inheritance
RasterMetadata
Inherited Members

Examples

RasterMetadata metadata = image.Metadata;
metadata.Text.Add(new TextEntry("Comment", "Made with Egami"));
metadata.Resolution = new Resolution(300, 300, ResolutionUnit.PerInch);
Console.WriteLine($"{metadata.ColorSpace}, ICC {metadata.IccProfile.Length} bytes, XMP {metadata.Xmp.Length} bytes");
foreach (EgamiDiagnostic warning in metadata.Warnings)
{
    Console.WriteLine($"Recovered from: {warning.Message} ({warning.Id})");
}

image.Save("duck-300dpi.png");

Properties

CodePoints

Gets or sets the ITU-T H.273 code points the file gave (PNG cICP), or null. They take precedence over every other color tag in GetColorProfile().

public ColorCodePoints? CodePoints { get; set; }

Property Value

ColorCodePoints?

ColorSpace

Gets or sets what the pixel values mean.

public ColorSpaceHint ColorSpace { get; set; }

Property Value

ColorSpaceHint

Exif

Gets or sets the EXIF block, parsed, or null if the file had none. Unedited, it is written back byte for byte.

public ExifData? Exif { get; set; }

Property Value

ExifData

FormatDetails

Gets or sets format-specific details from the reader.

public FormatDetails? FormatDetails { get; set; }

Property Value

FormatDetails

FormatName

Gets or sets the name of the format the raster was read from, such as "PNG", or null.

public string? FormatName { get; set; }

Property Value

string

GainMap

Gets or sets the HDR gain map the file carried (Ultra HDR, ISO 21496-1 or Apple JPEGs), or null. The JPEG writer writes it back while the raster keeps the size it was read at; geometry operations carry it, and operations that change pixel values drop it.

public GainMap? GainMap { get; set; }

Property Value

GainMap

Gamma

Gets or sets the file's gamma when ColorSpace is Gamma, as the exponent that decodes values to linear light.

public double? Gamma { get; set; }

Property Value

double?

Hdr

Gets or sets the HDR mastering display and light levels the file gave (PNG mDCV and cLLI), or null.

public HdrMetadata? Hdr { get; set; }

Property Value

HdrMetadata

IccProfile

Gets or sets the embedded ICC profile. Egami keeps and writes it back but does not apply it. Empty if none.

public ReadOnlyMemory<byte> IccProfile { get; set; }

Property Value

ReadOnlyMemory<byte>

Iptc

Gets or sets the IPTC-IIM datasets, parsed on first use, or null if the file had none. JPEG keeps them in a Photoshop resource block (APP13), PNG in a "Raw profile type iptc" text chunk. Unedited, they are written back byte for byte.

public IptcData? Iptc { get; set; }

Property Value

IptcData

Examples

using Raster photo = Raster.Load("sideways.jpg");
IptcData iptc = photo.Metadata.Iptc ?? new IptcData();
iptc.Headline = "Harbour at dawn";
iptc.Keywords = [.. iptc.Keywords, "harbour", "Bergen"];

// Any dataset by its key; Add appends to the repeatable ones.
iptc.Set(IptcKey.City, "Bergen");

// Text that is not ASCII sets the coded character set (1:90) to UTF-8, so other programs read it right.
iptc.Caption = "Fishing boats at Bryggen, Bergen — first light";
foreach (IptcEntry entry in iptc.Entries)
{
    Console.WriteLine($"{entry.Key} {entry.AsString()}");
}

// JPEG saves it in its Photoshop resource block (APP13), with the digest Photoshop and Lightroom check.
photo.Metadata.Iptc = iptc;
photo.Save("captioned.jpg");

LoopCount

Gets or sets how many times an animation plays. 0 means forever. Ignored for single-frame rasters.

public int LoopCount { get; set; }

Property Value

int

Primaries

Gets or sets the primaries and white point the file gave (PNG cHRM, BMP calibrated endpoints), or null. They apply with a gamma, linear or unspecified curve; an ICC profile or code points carry their own.

public ColorPrimaries? Primaries { get; set; }

Property Value

ColorPrimaries

Resolution

Gets or sets the physical pixel density, if known.

public Resolution? Resolution { get; set; }

Property Value

Resolution?

Text

Gets the text entries, in file order.

public IList<TextEntry> Text { get; }

Property Value

IList<TextEntry>

Warnings

Gets the problems a lenient read recovered from, such as a bad checksum after valid pixel data, in the order found. Each has a stable Id; one id is listed at most 10 times, then once more as a count of the rest. The same entries go to Diagnostics.

public IReadOnlyList<EgamiDiagnostic> Warnings { get; }

Property Value

IReadOnlyList<EgamiDiagnostic>

Examples

// Without a handler the same Warnings are in the metadata, each with its id.
using Raster image = Raster.Load(SampleFiles.Damaged());
foreach (EgamiDiagnostic warning in image.Metadata.Warnings)
{
    Console.WriteLine($"{warning.Id} at byte {warning.Offset}: {warning.Message}");
}

bool checksumsOnly = image.Metadata.Warnings.All(w => w.Id == "Png.ChecksumMismatch");

Xmp

Gets or sets the XMP packet as raw UTF-8 XML. Empty if none. Once XmpData has been edited, this returns the packet written from it; setting it drops the parsed view.

public ReadOnlyMemory<byte> Xmp { get; set; }

Property Value

ReadOnlyMemory<byte>

XmpData

Gets or sets the XMP packet parsed: a live view of Xmp, read on first use, and null when there is no packet or it is not well-formed XML (the bytes are then kept and a warning added). Edits to the view are what Xmp returns and what writers save; assign an empty XmpData to start a packet.

public XmpData? XmpData { get; set; }

Property Value

XmpData

Examples

using Raster photo = Raster.Load("sideways.jpg");

// The parsed view of the packet; it is null when the file has none, so start one.
XmpData xmp = photo.Metadata.XmpData ??= new XmpData();
xmp.Keywords = [.. xmp.Keywords, "harbour"];
xmp.Rating = 5;

// The edit is the packet now: Metadata.Xmp returns it and every format saves it.
photo.Save("rated.png");

Methods

Copy()

Returns a deep copy.

public RasterMetadata Copy()

Returns

RasterMetadata

The copy.

GetColorProfile()

Returns what the raster's pixel values mean, resolved from everything the file said, in this order: the H.273 CodePoints (PNG cICP), the embedded ICC profile, an sRGB tag, a gamma or linear tag with the file's Primaries (sRGB's when it has none), the EXIF marker of an Adobe RGB camera, primaries alone with the sRGB curve, and sRGB when the file said nothing. A damaged or unsupported profile, or code points Egami does not know, count as saying nothing. PNG's gAMA 45455 (1/2.2) with no cHRM, or with sRGB's, counts as sRGB, which is what such files mean.

public ColorProfile GetColorProfile()

Returns

ColorProfile

The encoding: RGB unless an ICC profile says gray or CMYK. Gray pixels are read with an RGB encoding's curve.

Examples

// What the pixels mean, from the file's ICC profile, tags and gamma; sRGB when it said nothing.
ColorProfile stored = raster.Metadata.GetColorProfile();

// Convert in place to sRGB for the web: the metadata then says sRGB, so no profile is written.
raster.Apply(ops => ops.ConvertColor(ColorProfile.Srgb));
Edit this page