JPEG 2000

edit

JPEG 2000 compresses images with wavelets, without loss or with loss, up to 16 bits per sample. The library reads JP2 files and bare codestreams, and Jpeg2000Encoder writes lossless JP2 files by default.

What is read and written

ReadingWriting
FilesJP2 files, JPX and JPH files of one codestream, bare codestreamsJP2 files (default), JPH files, or bare codestreams
CodingLossless (5-3) and lossy (9-7) wavelets, tiles, layers, every progression order, regions of interest, the high-throughput block coder (HTJ2K)Lossless or lossy; tiles and tile-parts, precincts, quality layers with size targets (rate control), the five progression orders, up to 32 decomposition levels, TLM and PLT length markers; the high-throughput block coder, with quality layers and refinement passes
Samples1 to 16 bits, unsigned or signed; gray, RGB, sYCC, palettes, opacity; CMYK with a color conversionEvery pixel format at its own depth (Gray8, Gray16, Rgb24, Rgba32, Bgra32, Rgba64), lossless opacity
MetadataICC profile, EXIF, XMP, resolutionThe same, in a JP2 file only

Files of at most 8 bits load as Gray8, Rgb24 or Rgba32; deeper files as Gray16, Rgb48 or Rgba64. The EXIF orientation is reported, never applied.

Save a JPEG 2000 file

public static string SaveJpeg2000(string inputPath, string jp2Path, string codestreamPath)
{
    using var image = Image.Load(inputPath);

    // Lossless by default: every pixel format is stored as it is, 16-bit samples and the colors of fully
    // transparent pixels included. A JP2 file stores the ICC profile, the resolution, EXIF and XMP.
    image.Save(jp2Path);

    // Lossy: the quality sets the quantization, on the scale of the JPEG encoder; the opacity stays exact.
    // A codestream alone (.j2k, .j2c, .jpc) stores no metadata: a strict save rejects an image that has some.
    image.Save(codestreamPath, new Jpeg2000Encoder
    {
        Compression = Jpeg2000Compression.Lossy,
        Quality = 80,
        Container = Jpeg2000Container.Codestream,
        MetadataHandling = MetadataHandling.DiscardUnsupported,
    });

    // Files, codestreams and the high-throughput block coder (HTJ2K) are decoded, whatever wrote them.
    var info = Image.Identify(jp2Path);
    return $"{info.Format} {info.Size.Width}x{info.Size.Height} {info.PixelFormat}, {info.BitsPerComponent} bits";
}

The .jp2 extension writes a JP2 file, and .j2k, .j2c and .jpc a codestream, both lossless; .jph and .jhc write them with the high-throughput block coder (see below).

Options

OptionWhat it doesDefault
CompressionLossless or LossyLossless
Quality1 (smallest) to 100 (best) for lossy output, on the scale of JpegEncoder.Quality; 100 is still lossy90
ContainerJp2 (a file with metadata) or Codestream (no metadata)Jp2
QualityLayersThe quality layers, each with a target size or number of bits per pixel (Jpeg2000QualityLayer)One layer with every coding pass
ProgressionOrderThe order of the packets: Lrcp, Rlcp, Rpcl, Pcrl or CprlLrcp
TileWidth, TileHeightThe size of the tiles, 0 for the size of the image0 (one tile)
DecompositionLevelsThe largest number of wavelet levels, 0 to 32, reduced for small tiles5
PrecinctSizesThe precinct sizes, from the highest resolution level down, the last one for the lower levels; powers of two from 2 to 32,768None (a precinct per level)
TilePartDivisionCut each tile into tile-parts at each Resolution, Layer or Component of the packetsNone
WriteTilePartLengthsList the length of every tile-part in the main header (TLM)false
WritePacketLengthsList the length of every packet in the header of its tile-part (PLT)false
BlockCoderStandard (Part 1) or HighThroughput (HTJ2K, Part 15)Standard

Quality sets the quantization, not a size: without a target, the size of the file follows from the image. On photos, a quality gives about the visual similarity of a JPEG file of the same quality.

Target sizes, quality layers and tiles

A layer with a target (Jpeg2000QualityLayer.FromSize or FromBitsPerPixel) is rate control: the encoder truncates the coding passes of the code-blocks where they reduce the error most for their bytes (the rate-distortion optimization of the standard), so the file has at most the target size, usually within 1% of it. Several layers make a file a reader can stop early in: the first layers of an Lrcp file are its first bytes. On photographs, the quality at a given size is the one of OpenJPEG's own rate control (opj_compress -r).

public static (long SmallLength, long LayeredLength) SaveJpeg2000Layers(string inputPath, string smallPath, string layeredPath)
{
    using var image = Image.Load(inputPath);

    // A file of at most 40 KB: the rate control keeps the coding passes that reduce the error most for their bytes.
    // Quality only sets the finest quantization, so 100 leaves every choice to the target.
    image.Save(smallPath, new Jpeg2000Encoder
    {
        Compression = Jpeg2000Compression.Lossy,
        Quality = 100,
        QualityLayers = [Jpeg2000QualityLayer.FromSize(40_000)],
    });

    // Three quality layers: a reader that stops after the first 0.25 bit per pixel (the first bytes of the file in the
    // LRCP order) gets a preview, after 1 bit per pixel a good image, and the last layer makes it lossless. Tiles of
    // 256x256 bound the memory of the encoder, and a reader can decode one tile alone.
    image.Save(layeredPath, new Jpeg2000Encoder
    {
        QualityLayers = [Jpeg2000QualityLayer.FromBitsPerPixel(0.25), Jpeg2000QualityLayer.FromBitsPerPixel(1), Jpeg2000QualityLayer.Complete],
        ProgressionOrder = Jpeg2000ProgressionOrder.Lrcp,
        TileWidth = 256,
        TileHeight = 256,
    });

    return (new FileInfo(smallPath).Length, new FileInfo(layeredPath).Length);
}

Tiles are coded one at a time: the encoder holds the wavelet coefficients of one tile instead of the whole image, and a reader can decode a tile alone. Small tiles cost bytes and, for lossy output, quality at their edges.

Precincts, tile-parts and length markers

These options change where the bytes are, not the image: a server that sends parts of a file (JPIP), or a viewer that reads a large file area by area, finds what it needs without reading the rest.

  • PrecinctSizes cuts each resolution level into precincts, whose code-blocks are in packets of their own. With Rpcl, Pcrl or Cprl, the packets of an area of a tile follow each other. A size is in coefficients of its resolution level: 256 at the level below the highest one covers 512 pixels. A precinct smaller than two code-blocks cuts them, which codes worse: choose precincts of 128 coefficients or more, the size of the areas a reader asks for, and smaller ones only when the areas are smaller.
  • TilePartDivision starts a tile-part at each change of resolution level, layer or component of the packets, in the progression order. It suits the order whose outermost loop it follows: Resolution with Rpcl or Rlcp, Layer with Lrcp, Component with Cprl. Each tile-part adds 14 bytes, and a tile has at most 255.
  • WriteTilePartLengths lists the length of every tile-part in the main header (5 or 6 bytes each), and WritePacketLengths the length of every packet in the header of its tile-part (1 byte for a packet shorter than 128 bytes).
public static void SaveJpeg2000ForStreaming(string inputPath, string path)
{
    using var image = Image.Load(inputPath);

    // Precincts of 256x256 coefficients at the full resolution and 128x128 below: the packets of each area of a tile
    // are apart, and the RPCL order gives the image resolution by resolution, area by area. A tile-part starts at each
    // resolution level, and the TLM and PLT marker segments list the lengths of the tile-parts and of the packets, so
    // that a reader or a JPIP server finds the bytes of a resolution and of an area without reading the others.
    image.Save(path, new Jpeg2000Encoder
    {
        PrecinctSizes = [new Size(256, 256), new Size(128, 128)],
        ProgressionOrder = Jpeg2000ProgressionOrder.Rpcl,
        TilePartDivision = Jpeg2000TilePartDivision.Resolution,
        WriteTilePartLengths = true,
        WritePacketLengths = true,
        TileWidth = 1024,
        TileHeight = 1024,
    });
}

The rate control counts the tile-part headers and the length markers: a file with a target still fits it. OpenJPEG (opj_dump, opj_decompress) reads the precincts, the tile-parts and the length markers of these files.

High-throughput JPEG 2000 (HTJ2K)

BlockCoder = HighThroughput codes each code-block with the high-throughput block coder of Part 15 of the standard instead of the arithmetic coder of Part 1. The wavelets, the quantization, the tiles and the progression orders are the same, and so are the decoded samples: a lossless file is exact, and a lossy one decodes to the samples of the standard coder at the same quality. On photographs, a lossless file is coded about 4 times and decoded 6 times faster, for about 8% more bytes; a lossy one 1.2 to 3.7 times faster, for 7% to 11% more. A file is a JPH file (.jph), which readers of Part 15 read (OpenJPEG 2.5, FFmpeg, OpenJPH), not every JP2 reader.

public static void SaveHighThroughputJpeg2000(string inputPath, string jphPath, string codestreamPath)
{
    using var image = Image.Load(inputPath);

    // The .jph extension writes a JPH file whose code-blocks use the high-throughput block coder: lossless by
    // default, several times faster to encode and decode than the standard block coder, for a few percent more bytes.
    // Its readers must support Part 15 of the standard, as OpenJPEG 2.5, FFmpeg and OpenJPH do.
    image.Save(jphPath);

    // A codestream (.jhc) of at most 100 KB in two layers: the rate control chooses, for each code-block, the lowest
    // bit-plane of its HT cleanup pass and its HT SigProp and HT MagRef refinement passes, and the first layer holds
    // the code-blocks that reduce the error most for their bytes, up to 30 KB.
    image.Save(codestreamPath, new Jpeg2000Encoder
    {
        BlockCoder = Jpeg2000BlockCoder.HighThroughput,
        Compression = Jpeg2000Compression.Lossy,
        Quality = 100,
        Container = Jpeg2000Container.Codestream,
        QualityLayers = [Jpeg2000QualityLayer.FromSize(30_000), Jpeg2000QualityLayer.FromSize(100_000)],
        MetadataHandling = MetadataHandling.DiscardUnsupported,
    });
}

Without a target, each code-block is one HT cleanup pass that codes every bit-plane. With a target, the encoder codes, for each code-block, the HT cleanup pass that ends at each bit-plane, and the HT SigProp and HT MagRef passes that refine the bit-plane below it, and keeps the combination that reduces the error most for its bytes. It fits the target as closely as the standard coder, at a slightly lower quality; the refinement passes give each code-block a finer choice of size than whole bit-planes. Coding every candidate takes most of the speed of the high-throughput coder away: with a target, choose it for the speed of decoding, and the standard coder for the best quality at a size.

A code-block has one set of these passes, which a layer holds whole: the layers of an HTJ2K file share out the code-blocks, each with the precision the last layer gives it, rather than refining every code-block layer after layer. The first layers of a file then hold fewer code-blocks, the ones that matter most; a reader that decodes them gets the others blank. OpenJPEG reads these files at every number of layers and FFmpeg reads them whole; OpenJPH only reads files of one layer.

Thumbnails and viewports

ImageDecodeOptions.ScaleDenominator (or TargetSize) decodes a lower resolution level: each halving discards one level of the wavelet transformation, up to the number of levels of the file (5 for the files of the library), and the work and the memory shrink with the number of pixels. ImageDecodeOptions.Region decodes an area: the tiles it does not meet are skipped, and in the others only the code-blocks that reach it are decoded, and the wavelet transformation only rebuilds the samples it needs, so the work and the memory follow the area even in an image of one tile. The samples are those of a full decode (OpenJPEG's -r and -d give the same ones). The compressed data of a tile that the area meets is still read whole: tiles make the viewports of very large files cheaper.

public static (Image Thumbnail, Image Preview, Image Viewport) LoadJpeg2000Parts(string path)
{
    // A thumbnail at a quarter of the size: the decoder discards the two highest resolution levels of the wavelet
    // transformation, for about a sixteenth of the work and of the memory
    var thumbnail = Image.Load(path, new ImageDecodeOptions { ScaleDenominator = 4 });

    // The smallest image of at least 200x100 pixels the file allows (at most 1/32 with 5 decomposition levels)
    var preview = Image.Load(path, new ImageDecodeOptions { TargetSize = new Size(200, 100) });

    // A viewport: only the tiles and the code-blocks that reach the area are decoded, to the pixels of a full decode.
    // With ScaleDenominator, the area is divided like the image
    var viewport = Image.Load(path, new ImageDecodeOptions { Region = new Rectangle(300, 200, 400, 300) });
    return (thumbnail, preview, viewport);
}

Decode fewer quality layers

Jpeg2000DecodingOptions.QualityLayerLimit, set on ImageConfiguration.Jpeg2000Decoding, decodes the first layers of a file only: the coding passes of the next layers are left out, which gives the image a file cut after these layers would give (opj_decompress -l gives the same samples). It applies to eager loads, sequential readers and collections, and combines with a scale and a region. The packets of the other layers are still read, to find the ones that are needed; in the LRCP order, the decoder stops after the last layer it needs. A limit of at least the number of layers of the file decodes the whole file.

public static Image LoadJpeg2000Preview(string path)
{
    // Only the coding passes of the first quality layer are decoded: the image a reader gets from the first bytes of
    // an LRCP file. A file of one layer decodes as a whole.
    var options = new ImageDecodeOptions
    {
        Configuration = new ImageConfiguration
        {
            Jpeg2000Decoding = new Jpeg2000DecodingOptions { QualityLayerLimit = 1 },
        },
    };

    return Image.Load(path, options);
}

Signed samples

A component of signed samples is read with the offset of half its range: a sample v of B bits is the unsigned sample v + 2^(B-1), the value of an unsigned file whose samples were shifted the same way by the encoder (the DC level shift of the standard). The samples of an 8-bit file go from -128 to 127 and load as 0 to 255; OpenJPEG and FFmpeg show them the same way. The values of a signed palette column are offset alike. The files of the library are unsigned: a signed file is not written back as signed.

Pitfalls

  • A codestream stores no metadata at all: with the default MetadataHandling.Strict, an image with an ICC profile, EXIF, XMP or a resolution is rejected. Use a JP2 file, or set MetadataHandling.
  • A JP2 file only stores grayscale and matrix-based RGB ICC profiles; another profile follows MetadataHandling.
  • Save(path) rejects the .jpx and .jpf extensions with an ArgumentException: those files are read, not written.
  • The first layers of an HTJ2K file hold whole code-blocks, not coarser ones: for previews that improve layer after layer, use the standard block coder. OpenJPH reads HTJ2K files of one layer only.
  • A tile has at most 255 tile-parts: a TilePartDivision that cuts a tile into more (for example Resolution with many layers in the Lrcp order) is an ArgumentException when the image is saved, before anything is written. FFmpeg 9.0.2 reads at most 32 tile-parts per tile: a division by component or by resolution in a position progression with small precincts can make more.
  • A target smaller than the headers and the empty packets cannot be reached: the file then has no coded data. A lossless output whose last layer has a target is not lossless when the target cuts coding passes: end with Jpeg2000QualityLayer.Complete to keep it lossless.
  • The decoder decodes a tile as a whole: a very large image of one tile can exceed the default memory budget, unless it is decoded at a reduced scale. See Resource limits.
  • A region is in pixels of the stored image at full resolution, before the EXIF orientation; a region narrower than a sample of the reduced resolution keeps the sample that covers it.
  • CMYK files load only with ImageDecodeOptions.CmykConversion (see Color management).
  • Samples of more than 16 bits, sYCC or CMYK channels of different depths, premultiplied opacity, signed palette indexes and the extensions of Part 2 of the standard are rejected with an UnsupportedImageFeatureException.
  • A codestream ends with its end marker: a file that is cut is an InvalidImageContentException, never a smaller image.