Class HeicWriterOptions

Namespace

Egami.Heic

Assembly

Egami.Heic.dll

Options for writing HEIC. Lossy images are coded on heif-enc's quality scale, so the same Quality gives about the same file as heif-enc -q with x265; lossless images keep every sample of 4:4:4 RGB. The names and meanings match AvifWriterOptions where the two formats share an option.

public sealed class HeicWriterOptions : WriterOptions

Inheritance

object

WriterOptions

HeicWriterOptions

Inherited Members

WriterOptions.StripMetadata

WriterOptions.OmitSrgbProfile

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// With Egami.Heic registered, Save picks HEIC from the extension: lossy 4:2:0 at quality 50 on heif-enc's scale, effort 4.
duck.Save("duck-q50.heic");

// Smaller and softer, or every sample exact (4:4:4 RGB with the identity matrix, which needs a range extensions decoder).
duck.Save("duck-q30.heic", new HeicWriterOptions { Quality = 30 });
duck.Save("duck-lossless.heic", new HeicWriterOptions { Lossless = true });

Remarks

HEVC is covered by patents, encoding as well as decoding. Egami's authors grant no patent rights and are not lawyers. Whether you need a patent licence depends on your country and on how you use and distribute this package; commercial products may need one from the HEVC patent pools or holders.

Properties

AlphaQuality

Gets the quality of the alpha plane, 0 to 100 on the same scale as Quality: 100 (the default) keeps alpha exactly. Alpha is written straight, not premultiplied, as an auxiliary image every HEVC decoder reads.

public int AlphaQuality { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

BitDepth

Gets the bits a sample has, 8, 10 or 12, or null (the default) for 8 with 8-bit pixels and 10 (Main 10) with deeper ones; a lossless file of deeper pixels takes 12. 12 bits use HEVC's format range extensions.

public int? BitDepth { get; init; }

Property Value

int?

Exceptions

ArgumentOutOfRangeException

The value is not 8, 10 or 12.

Chroma

Gets the chroma format of lossy color, or null (the default) for 4:2:0, which every HEVC decoder reads. 4:4:4, 4:2:2 and 4:0:0 use HEVC's format range extensions, which some phones and operating systems cannot decode. 4:1:1 and 4:1:0 choose as null does.

public ChromaFormat? Chroma { get; init; }

Property Value

ChromaFormat?

Default

Gets the default options.

public static HeicWriterOptions Default { get; }

Property Value

HeicWriterOptions

Effort

Gets how hard the encoder works, 0 (fastest) to 10 (smallest files). Defaults to 4, which makes files about the size of x265's medium preset in about its time.

public int Effort { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 10.

GainMapQuality

Gets the quality of a gain map, 0 to 100 on the same scale as Quality (100 is lossless), or null (the default) for the image's quality.

public int? GainMapQuality { get; init; }

Property Value

int?

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

GridTileSize

Gets the size of the cells of a grid image, or null (the default) to write one picture up to 8,912,896 samples (HEVC level 5.1, which phone and PC decoders take) and a grid of 512 x 512 cells, as iPhones write, for larger images.

public Size? GridTileSize { get; init; }

Property Value

Size?

Exceptions

ArgumentOutOfRangeException

A side is below 64 or above 8192.

Lossless

Gets whether to write lossless (every sample of the RGB or gray image exact: 4:4:4 with the identity matrix, coded without transform or quantization) or lossy data, or null (the default) for lossy. Lossless HEIC needs a decoder of HEVC's format range extensions, which some phones and operating systems lack.

public bool? Lossless { get; init; }

Property Value

bool?

Quality

Gets the lossy quality, 0 (smallest) to 100 (best), on heif-enc's -q scale. Defaults to 50, as heif-enc does. Ignored for lossless images.

public int Quality { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

TargetSize

Gets the largest size the file may have, in bytes, or null (the default) to code at Quality: the quality is searched for the largest file not above the size, then the quantizer between that quality and the next, so the file lands close under the size. When even quality 0 is larger, that file is written and a Heic.TargetSizeExceeded warning says so. Ignored for lossless images.

public int? TargetSize { get; init; }

Property Value

int?

Exceptions

ArgumentOutOfRangeException

The value is below 1.

ThumbnailSize

Gets the size of the square a thumbnail fits in, 16 to 1024 samples, or null (the default) for no thumbnail. A thumbnail is a small HEVC image linked to the image, which file browsers show without decoding the whole picture; iPhones write one 320 samples wide.

public int? ThumbnailSize { get; init; }

Property Value

int?

Exceptions

ArgumentOutOfRangeException

The value is outside 16 to 1024.