This is a reference on how openjpeg codecs are implemented, and how to use them. In this context, a codec is a piece of software which understands how to implement specific parts of the jpeg2000 standard.

OpenJPEG Design

From the user’s perspective, to create jpeg2000 files with openjpeg, you have to take the following steps. These steps are taken from analyzing the opj_compress command. It’s not necessarily a simple process, but it’s unfortunate that it’s not really documented anywhere except code.

1. Get some raw image data if you’re converting to a jpeg2000, or have a jp2 file if you’re reading one.
   See openjpeg’s convert for reference
2. Create a codec with opj_create_compress or opj_create_decompress.
3. Use opj_set_default_(en/de)coder_parameters to get an instance of default options.
4. Execute opj_setup_(en/de)coder, and opj_(en/de)coder_set_extra_options.
5. Create an output file with opj_stream_create_default_file_stream. You can do this earlier as well.
6. Execute opj_start_(de)compress, opj_(en/de)code, opj_end_(de)compress
7. Free up your resources, that’s all.

Internal Workings

If you’re not a new codec for openjpeg, then you don’t need to worry about this.

The opj_create_compress and opj_create_decompress functions create an internal codec instance, which contains function pointers to all the functions needed to perform the compression/decompression operations.

Hierarchy

There is a hierarchical structure to jpeg2000, and openjpeg follows this hierarchy. What I mean is the jpeg2000 codestream, which represents the compressed image data, has its own format. So openjpeg has a codec for handling the codestream itself. This codec has functions which are called for all previously mentioned user-facing functions.

Codestreams aren’t used by themselves very often. So the “jp2” file is a set of metadata that wraps the codestream. openjpeg has a jp2 codec which internally creates a codestream codec. So when the user is using the jp2 codec, internally openjpeg is running both the jp2 and j2k codecs.

Adding JPX Support

I am working on implementing partial support for writing JPX files via openjpeg. I’m creating a new command called opj_merge which can reference multiple jp2 files within a single jpx file.

To do this, I’m following the hierarchy that appears to already exist in openjpeg. I am implementing a new JPX codec, meaning I’m implementing all the codec functions: create_compress, setup_encoder, set_extra_options, start_compress, encode, and end_compress.

Within these functions, I create an instance of the jp2 codec, so that I can leverage the jp2 functions which write out common header information that lives in both the jp2 and jpx files.