Jpeg2000Encoder Class

Immutable JPEG 2000 encoder settings (ISO/IEC 15444-1). By default the output is a JP2 file compressed without loss: every pixel format is stored as it is, 16-bit samples and the color of fully transparent pixels included.

public sealed class Jpeg2000Encoder : ImageEncoder

Remarks

Gray pixel formats are written as one component, the other formats as red, green and blue components with the multiple component transformation, and an opacity component when the pixel format has an alpha channel. The layout follows the pixel format, never the pixels. By default the image is one tile of one tile-part, with one quality layer in the Jpeg2000ProgressionOrder.Lrcp order, up to five decomposition levels and no precinct; Jpeg2000Encoder.TileWidth, Jpeg2000Encoder.TileHeight, Jpeg2000Encoder.TilePartDivision, Jpeg2000Encoder.QualityLayers, Jpeg2000Encoder.ProgressionOrder, Jpeg2000Encoder.DecompositionLevels and Jpeg2000Encoder.PrecinctSizes change them. The code-blocks have 64 by 64 coefficients (fewer in small precincts) and are coded with the block coder of ISO/IEC 15444-1, or with the high-throughput block coder of ISO/IEC 15444-15 (HTJ2K) with Jpeg2000Encoder.BlockCoder.

A JP2 file stores the ICC profile, the resolution, the EXIF data (which carries the orientation) and the XMP packet. The ICC profile must be a grayscale profile or a matrix-based RGB profile, the only ones a JP2 file allows; any other profile follows ImageEncoder.MetadataHandling. A codestream stores no metadata at all.

With ImageConfiguration.MaxDegreeOfParallelism above 1 (the configuration of the saved image), an image of at least 65,536 pixels is transformed and its code-blocks are coded by up to that many workers; the bytes are those of one worker.

Inheritance
ImageEncoder Jpeg2000Encoder

Constructors

NameDescription
Jpeg2000Encoder()

Jpeg2000Encoder()

Jpeg2000Encoder.cs
public Jpeg2000Encoder()

No documentation is available.

Properties

NameDescription
BlockCoderGets the coder of the code-blocks. Defaults to Jpeg2000BlockCoder.Standard, the block coder of ISO/IEC 15444-1.
CompressionGets whether the image is compressed without loss. Defaults to Jpeg2000Compression.Lossless.
ContainerGets whether the output is a JP2 file or a codestream alone. Defaults to Jpeg2000Container.Jp2.
DecompositionLevelsGets the largest number of decomposition levels of the wavelet transformation, from 0 to 32. Defaults to 5. A tile gets fewer levels when its smaller side is shorter than 2^levels pixels, so that its lowest resolution level is not empty; the tiles of the last row or column do not reduce it.
FormatGets the format produced by this encoder.
PrecinctSizesGets the size of the precincts of each resolution level, from the highest one (the full size) down; the last size is used for the lower levels. Defaults to an empty list: each resolution level of a tile-component is one precinct.
ProgressionOrderGets the order of the packets of each tile. Defaults to Jpeg2000ProgressionOrder.Lrcp.
QualityGets the quality of a Jpeg2000Compression.Lossy output, from 1 (smallest output) to 100 (best quality). Defaults to 90. It is ignored by a lossless output.
QualityLayersGets the quality layers of the output, in order. Defaults to an empty list: one layer with every coding pass, which is [Jpeg2000QualityLayer.Complete].
TileHeightGets the height of a tile, in pixels, or 0 (the default) for tiles as high as the image. The tiles of the last row are lower when the height of the image is not a multiple of it. See Jpeg2000Encoder.TileWidth.
TilePartDivisionGets where each tile is cut into tile-parts. Defaults to Jpeg2000TilePartDivision.None: one tile-part per tile.
TileWidthGets the width of a tile, in pixels, or 0 (the default) for tiles as wide as the image. The tiles of the last column are narrower when the width of the image is not a multiple of it.
WritePacketLengthsGets whether the header of each tile-part lists the length of each of its packets (PLT marker segments, T.800, A.7.3), so that a reader can seek to any packet without reading the packet headers. Defaults to false.
WriteTilePartLengthsGets whether the main header lists the length of every tile-part (a TLM marker segment, T.800, A.7.1), so that a reader can seek to any tile-part without reading the others. Defaults to false.

Gets the coder of the code-blocks. Defaults to Jpeg2000BlockCoder.Standard, the block coder of ISO/IEC 15444-1.

public Jpeg2000BlockCoder BlockCoder { get; init; }

Property value

Jpeg2000BlockCoder

Exceptions

ArgumentOutOfRangeException
The value is not a defined Jpeg2000BlockCoder.

Remarks

Jpeg2000BlockCoder.HighThroughput codes each code-block with the coding passes of ISO/IEC 15444-15, and declares it in the codestream (the CAP marker segment, the code-block style); a Jpeg2000Container.Jp2 output is then a JPH file, of the brand jph . The pass codes the same quantized coefficients as the standard coder: a lossless output is the image, and a lossy output decodes to the samples of the standard coder at the same Jpeg2000Encoder.Quality.

Without a target in Jpeg2000Encoder.QualityLayers, the HT cleanup pass codes every bit-plane. With a target, the encoder codes, for each code-block, one HT set for each lowest bit-plane: an HT cleanup pass, then an HT SigProp pass and an HT MagRef pass that refine the bit-plane below it. It keeps the set and the refinement passes that reduce the error most for their bytes, at the same rate-distortion slopes as the coding passes of the standard coder. A code-block has one HT set, which a layer holds whole: the layers share out the code-blocks, each with the precision the last layer gives it, so that the first layers have fewer code-blocks rather than coarser ones. A reader that decodes the first layers gets the code-blocks they hold; OpenJPEG reads such files, which have no placeholder pass and no refinement pass in a later packet than its HT cleanup pass.

Gets whether the image is compressed without loss. Defaults to Jpeg2000Compression.Lossless.

public Jpeg2000Compression Compression { get; init; }

Property value

Jpeg2000Compression

Exceptions

ArgumentOutOfRangeException
The value is not a defined Jpeg2000Compression.

Gets whether the output is a JP2 file or a codestream alone. Defaults to Jpeg2000Container.Jp2.

public Jpeg2000Container Container { get; init; }

Property value

Jpeg2000Container

Exceptions

ArgumentOutOfRangeException
The value is not a defined Jpeg2000Container.

Remarks

With the Jpeg2000BlockCoder.HighThroughput block coder, the file is a JPH file.

DecompositionLevels

Jpeg2000Encoder.cs

Gets the largest number of decomposition levels of the wavelet transformation, from 0 to 32. Defaults to 5. A tile gets fewer levels when its smaller side is shorter than 2^levels pixels, so that its lowest resolution level is not empty; the tiles of the last row or column do not reduce it.

public int DecompositionLevels { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not between 0 and 32.

Remarks

Each level halves the size of the lowest resolution: more levels compress large smooth images slightly better and let a reader decode smaller thumbnails (a decode at 1/2^n of the size discards n levels).

Gets the format produced by this encoder.

public override ImageFormat Format { get; }

Property value

ImageFormat

PrecinctSizes

Jpeg2000Encoder.cs

Gets the size of the precincts of each resolution level, from the highest one (the full size) down; the last size is used for the lower levels. Defaults to an empty list: each resolution level of a tile-component is one precinct.

public IReadOnlyList<Size> PrecinctSizes { get; init; }

Property value

IReadOnlyList<Size>

Exceptions

ArgumentNullException
The value is null.
ArgumentException
The value has more than 33 sizes, or a width or a height that is not a power of two from 2 to 32,768.

Remarks

A precinct is an area of a resolution level whose code-blocks are in packets of their own (T.800, B.6), so that a reader can find the bytes of a part of the image, and a position progression (Jpeg2000Encoder.ProgressionOrder) can give the image area by area. The width and the height are powers of two from 2 to 32,768, on the grid of the resolution level (a sample of the level n levels below the highest one stands for 2^n pixels of the image). The code-blocks of a precinct are cut to it: a precinct narrower than 128 coefficients (64 for the lowest level) has code-blocks of half its width, and the same for the height.

Small precincts add packets, and small code-blocks code worse: precincts of 128 to 512 coefficients cost less than one percent of the size of a photograph.

ProgressionOrder

Jpeg2000Encoder.cs

Gets the order of the packets of each tile. Defaults to Jpeg2000ProgressionOrder.Lrcp.

public Jpeg2000ProgressionOrder ProgressionOrder { get; init; }

Property value

Jpeg2000ProgressionOrder

Exceptions

ArgumentOutOfRangeException
The value is not a defined Jpeg2000ProgressionOrder.

Remarks

A packet holds the coding passes a layer adds to the code-blocks of one precinct. Without Jpeg2000Encoder.PrecinctSizes, a resolution level of a tile-component is one precinct, so one position: Jpeg2000ProgressionOrder.Pcrl and Jpeg2000ProgressionOrder.Cprl then give the same packets, component by component, and Jpeg2000ProgressionOrder.Rpcl the packets of Jpeg2000ProgressionOrder.Rlcp with the layers of a component together. With precincts, the position progressions visit the precincts from the top-left corner of the tile, as the reference grid places them (T.800, B.12).

Gets the quality of a Jpeg2000Compression.Lossy output, from 1 (smallest output) to 100 (best quality). Defaults to 90. It is ignored by a lossless output.

public int Quality { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not between 1 and 100.

Remarks

The quality sets the quantization step sizes of the sub-bands; there is no rate control, so the size of the output follows from the image. With the scale of JpegEncoder.Quality, s = 5000 / Quality below 50 and s = 200 - 2 * Quality otherwise (at least 1), the error that the quantization of a sub-band of the luminance (or of the gray levels) adds to the image has a step of 0.47 * s^(3/4) levels of an 8-bit sample, proportionally more for deeper samples; the two chrominances are quantized twice as coarsely.

The values are calibrated on JpegEncoder: on photographs, a quality gives the structural similarity (SSIM) of a JPEG file of the same quality, with chrominances that are not worse than its sub-sampled ones, in a file of about two thirds of the size (half of it at the quality 20). 100 is the finest quantization, still lossy.

QualityLayers

Jpeg2000Encoder.cs

Gets the quality layers of the output, in order. Defaults to an empty list: one layer with every coding pass, which is [Jpeg2000QualityLayer.Complete].

public IReadOnlyList<Jpeg2000QualityLayer> QualityLayers { get; init; }

Property value

IReadOnlyList<Jpeg2000QualityLayer>

Exceptions

ArgumentNullException
The value is null, or holds null.
ArgumentException
The value has more than 65,535 layers, or Jpeg2000QualityLayer.Complete before its last layer.

Remarks

Each layer adds coding passes to the previous ones, so that a reader that stops after a layer gets the best image of that size: with the Jpeg2000ProgressionOrder.Lrcp order, the bytes of the first layers are the start of the output. A target of a size or of a number of bits per pixel is reached by truncating the coding passes of the code-blocks at the points that reduce the squared error of the image most for their bytes (the post-compression rate-distortion optimization of T.800, J.14); a layer whose target is not above the size of the previous ones adds nothing. A target only removes coding passes: Jpeg2000Encoder.Quality still sets the finest quantization of a lossy output, and a lossless output whose last layer has a target is not lossless when the target cuts coding passes.

The coded bytes of every code-block are kept until the layers are chosen, as with one layer; choosing the layers writes the packet headers a few dozen times. Jpeg2000QualityLayer.Complete is only allowed last.

Gets the height of a tile, in pixels, or 0 (the default) for tiles as high as the image. The tiles of the last row are lower when the height of the image is not a multiple of it. See Jpeg2000Encoder.TileWidth.

public int TileHeight { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is negative.

TilePartDivision

Jpeg2000Encoder.cs

Gets where each tile is cut into tile-parts. Defaults to Jpeg2000TilePartDivision.None: one tile-part per tile.

public Jpeg2000TilePartDivision TilePartDivision { get; init; }

Property value

Jpeg2000TilePartDivision

Exceptions

ArgumentOutOfRangeException
The value is not a defined Jpeg2000TilePartDivision.

Remarks

A tile-part starts at each change of the resolution level, of the layer or of the component of the packets, in the Jpeg2000Encoder.ProgressionOrder: the division follows the progression best when the progression changes that dimension last, such as Jpeg2000TilePartDivision.Resolution with Jpeg2000ProgressionOrder.Rpcl. A tile has at most 255 tile-parts. The tile-parts of a tile follow each other: a reader can stop after any of them. Each tile-part adds 14 bytes.

Gets the width of a tile, in pixels, or 0 (the default) for tiles as wide as the image. The tiles of the last column are narrower when the width of the image is not a multiple of it.

public int TileWidth { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is negative.

Remarks

Each tile is transformed and coded on its own, so that the encoder holds the coefficients of one tile at a time instead of those of the whole image: a large image is coded with tiles of 512 to 2048 pixels without holding its transformation. A reader can also decode one tile alone. Small tiles cost bytes and quality at their edges. An image has at most 65,535 tiles.

WritePacketLengths

Jpeg2000Encoder.cs

Gets whether the header of each tile-part lists the length of each of its packets (PLT marker segments, T.800, A.7.3), so that a reader can seek to any packet without reading the packet headers. Defaults to false.

public bool WritePacketLengths { get; init; }

Property value

bool

Remarks

Each packet adds 1 to 5 bytes (1 for a packet shorter than 128 bytes), and each tile-part about 5.

WriteTilePartLengths

Jpeg2000Encoder.cs

Gets whether the main header lists the length of every tile-part (a TLM marker segment, T.800, A.7.1), so that a reader can seek to any tile-part without reading the others. Defaults to false.

public bool WriteTilePartLengths { get; init; }

Property value

bool

Remarks

Each tile-part adds 5 or 6 bytes (6 with more than 255 tiles).