Meziantou.FrameworkHeicEncoder Class
Immutable settings for HEIC encoding.
public sealed class HeicEncoder : ImageEncoderRemarks
HeicEncoder.Compression selects the HEVC coding: HeicCompression.Lossless (the default) preserves every sample; HeicCompression.Lossy trades fidelity for size according to HeicEncoder.Quality. HeicEncoder.Effort trades encoding time for size and never changes the decoded pixels of lossless output. Lossless HEIC files are large: select the lossy coding for photographs.
A file is read by the software that has a decoder for the profile of its HEVC bitstream. Lossy 4:2:0 output of 8 or 10 bits uses the Main Still Picture, Main and Main 10 profiles, which every HEIC reader decodes. Lossless output, 4:4:4 and 4:2:2 output, 12-bit output, gray images and alpha planes use the format range extensions profiles, which fewer readers decode: select the lossy coding with HeicChromaSubsampling.Ratio420 for files that other devices must open.
HEIC stores 8, 10 or 12 bits per sample. 8-bit pixel formats are written with 8 bits unless HeicEncoder.BitDepth asks for more; 16-bit pixel formats need HeicEncoder.BitDepth or HeicEncoder.AllowBitDepthReduction, because they lose precision. Gray pixel formats are written as monochrome images. Alpha is always stored when the image has a pixel that is not opaque, losslessly, as an auxiliary image.
An image with several frames is written as an image sequence: every frame is a full image, with its exact duration, and the play count of the animation. The first frame is a key frame; the others are predicted from the frame that precedes them, unless HeicEncoder.KeyFrameInterval asks for more key frames. A sequence needs a seekable destination and the number of its frames (ImageWriterOptions.ExpectedFrameCount for a writer), because the box that describes the frames precedes them and is written last. A still image goes to any stream. An image sequence of one image cannot store animation settings: it is read back as a still image.
Metadata (subject to ImageEncoder.MetadataHandling): the CICP color description (colr box, with the matrix coefficients and the range that the encoder used), the ICC profile, EXIF and XMP items, and the orientation (irot and imir properties). HEIC has no text or resolution field.
HEVC is covered by patents in many countries: check the licensing terms that apply to what you distribute.
- Inheritance
ImageEncoderHeicEncoder
Constructors
| Name | Description |
|---|---|
| HeicEncoder() |
HeicEncoder()
HeicEncoder.cspublic HeicEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowBitDepthReduction | Gets a value indicating whether 16-bit pixel formats may be reduced to 12 bits per sample (nearest rounding) when HeicEncoder.BitDepth is not set. Defaults to false. |
| BitDepth | Gets the number of bits of a sample: 8, 10 or 12, or null (the default) for the depth of the pixel format. 8-bit pixels are scaled up exactly. A value for a 16-bit pixel format is the consent to reduce its samples to this depth (nearest rounding). |
| ChromaSubsampling | Gets the chroma subsampling of HeicCompression.Lossy color output. Defaults to HeicChromaSubsampling.Auto (4:2:0). Ignored by lossless output (4:4:4) and by gray pixel formats. |
| ClearTransparentColors | Gets a value indicating whether the color of fully transparent pixels is replaced with transparent black before encoding. Defaults to false: lossless output then preserves the color of fully transparent pixels exactly. |
| Compression | Gets the HEVC coding of every image. Defaults to HeicCompression.Lossless. |
| DurationRounding | Gets how the durations of the images of a sequence are stored. Defaults to FrameDurationRounding.RequireExact: the time scale of the sequence is the smallest one that holds every duration exactly, and a sequence whose durations have no common time scale of 32 bits is an error. FrameDurationRounding.RoundToNearest then rounds the durations to microseconds. |
| Effort | Gets the compression effort, from 0 (fastest, largest output) to 9 (slowest, smallest output). Defaults to 5. The effort never changes the decoded pixels of lossless output. |
| Format | Gets the format produced by this encoder. |
| GridTileSize | Gets the size of the tiles of a still image that is coded as a grid, or null (the default) for an image that is coded whole. An image that is larger than a tile is cut into tiles of this size, each one coded on its own, which a grid item assembles; an image that one tile holds is coded whole. |
| KeyFrameInterval | Gets the number of images from a key frame to the next one in an image sequence. Defaults to 0: the first image is the only key frame. 1 makes every image a key frame. An image that is not a key frame is predicted from the image that precedes it, which makes it smaller; a reader that seeks decodes from the last key frame. Ignored by a still image, and never changes the decoded pixels of lossless output. |
| OptimizeQuantization | Gets a value indicating whether lossy transform blocks search several quantization rounding offsets and select the best balance of reconstructed error and estimated coded size. Defaults to false. |
| Quality | Gets the quality of HeicCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output. |
AllowBitDepthReduction
HeicEncoder.csGets a value indicating whether 16-bit pixel formats may be reduced to 12 bits per sample (nearest rounding) when HeicEncoder.BitDepth is not set. Defaults to false.
public bool AllowBitDepthReduction { get; init; }Property value
BitDepth
HeicEncoder.csGets the number of bits of a sample: 8, 10 or 12, or null (the default) for the depth of the pixel format. 8-bit pixels are scaled up exactly. A value for a 16-bit pixel format is the consent to reduce its samples to this depth (nearest rounding).
public int? BitDepth { get; init; }ChromaSubsampling
HeicEncoder.csGets the chroma subsampling of HeicCompression.Lossy color output. Defaults to HeicChromaSubsampling.Auto (4:2:0). Ignored by lossless output (4:4:4) and by gray pixel formats.
public HeicChromaSubsampling ChromaSubsampling { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
HeicChromaSubsampling.
ClearTransparentColors
HeicEncoder.csGets a value indicating whether the color of fully transparent pixels is replaced with transparent black before encoding. Defaults to false: lossless output then preserves the color of fully transparent pixels exactly.
public bool ClearTransparentColors { get; init; }Property value
Remarks
Setting it usually makes the output smaller; the visible pixels and every alpha value are unchanged.
Compression
HeicEncoder.csGets the HEVC coding of every image. Defaults to HeicCompression.Lossless.
public HeicCompression Compression { get; init; }DurationRounding
HeicEncoder.csGets how the durations of the images of a sequence are stored. Defaults to FrameDurationRounding.RequireExact: the time scale of the sequence is the smallest one that holds every duration exactly, and a sequence whose durations have no common time scale of 32 bits is an error. FrameDurationRounding.RoundToNearest then rounds the durations to microseconds.
public FrameDurationRounding DurationRounding { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
FrameDurationRounding.
Effort
HeicEncoder.csGets the compression effort, from 0 (fastest, largest output) to 9 (slowest, smallest output). Defaults to 5. The effort never changes the decoded pixels of lossless output.
public int Effort { get; init; }Format
HeicEncoder.csGridTileSize
HeicEncoder.csGets the size of the tiles of a still image that is coded as a grid, or null (the default) for an image that is coded whole. An image that is larger than a tile is cut into tiles of this size, each one coded on its own, which a grid item assembles; an image that one tile holds is coded whole.
public Size? GridTileSize { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- A side of the tiles is not between 64 and 65,528.
Remarks
A grid bounds the size of what a decoder decodes at once, and the memory that encoding takes (one tile at a time): cameras write their photos as grids of 512x512 tiles. The tiles of the right column and of the bottom row extend past the image, whose last column and last row they repeat. The alpha plane is a grid of the same tiles. A tile is coded without its neighbors: lossy output can show the edges of the tiles, and is larger than the image coded whole.
With ImageConfiguration.MaxDegreeOfParallelism above 1, the tiles of a grid of at least 65,536 samples are coded by up to that many workers at once, each with encoders of its own (charged to ImageResourceLimits.MaxLiveAllocationBytes); the output is byte-identical to the one of one worker.
Each side of a tile is between 64 and 65,528 pixels (the largest HEVC picture), and a grid has at most 256 columns and 256 rows. A tile whose size is not a whole number of coding blocks of 8 samples is cropped to its size by the conformance window of its picture. With subsampled chroma (HeicEncoder.ChromaSubsampling), the widths of the tiles and of the image must be even, and their heights too for 4:2:0. Ignored by an image sequence.
KeyFrameInterval
HeicEncoder.csGets the number of images from a key frame to the next one in an image sequence. Defaults to 0: the first image is the only key frame. 1 makes every image a key frame. An image that is not a key frame is predicted from the image that precedes it, which makes it smaller; a reader that seeks decodes from the last key frame. Ignored by a still image, and never changes the decoded pixels of lossless output.
public int KeyFrameInterval { get; init; }OptimizeQuantization
HeicEncoder.csGets a value indicating whether lossy transform blocks search several quantization rounding offsets and select the best balance of reconstructed error and estimated coded size. Defaults to false.
public bool OptimizeQuantization { get; init; }Property value
Remarks
This increases encoding time and can change the decoded pixels at the same HeicEncoder.Quality. It does not impose a target file size or bit rate. Ignored by lossless output, including alpha planes.
Quality
HeicEncoder.csGets the quality of HeicCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output.
public int Quality { get; init; }