AlternativeUniversity.net
Alternative University

Computer Science

Raster Image Storage

Higher Precision Extended Range

JX4 File Format

The JX4 file format (with  .jx4  file name extension) is a simple standard royalties-free file format for storing and archiving 32-bit floating point color images, one image per file, using JPEG 2000 for compression of the color channels. It is a subset variation of the XRH file format.

JX4 files store 32-bit floating point RGB and RGBA images as 24-bit encoded samples that are compressed. Color channels use lossy JPEG 2000 for compression.

The three 32-bit floating point color channels (RGB) are transformed into YCbCr channels for decorrelation before encoding into 24-bit samples.

An alpha channel is optional. If there is an alpha channel, the 32-bit floating point samples of the alpha channel are encoded into 24-bit samples and compressed with Zebra compression.


File Layout

Each JX4 file stores a rectangular raster image of 3 or 4 channels (RGB or RGBA respectively in that order). A channel is also called an image plane or component.

Each channel is stored as scanlines in raster order (consecutive rows of samples beginning with the top row, with samples stored left-to-right in each row).

A JX4 file begins with a File Header, followed with Custom Properties, followed with the Image Planes (channels of pixel samples) to the end of the file:

Figure 1:  JX4 file layout.

All multi-byte numbers in a JX4 file are stored in Big Endian format (network byte order).


File Header

The first 64 bytes of an XRH file are the file header:

Figure 2:  XRH file header.

The first 4 bytes (0−3) of a JX4 file are the magic number 0x4A583400.

The next 4 bytes (4−7) are the file version 0x00010000.

The next 4 bytes (8−11) are the image width in pixels (number of samples per scanline of a channel).

The next 4 bytes (12−15) are the image height in pixels (number of scanlines per channel).

The next 4 bytes (16−19) are the number of image channels. This must be 3 or 4, for RGB and RGBA respectively. The Y channel is stored first, the Cb channel stored second, and the Cr channel is stored third. If there is an alpha channel, it is stored as the fourth channel in the file.

The next 28 bytes (20−47) are reserved for future use and must be zero.

The next 4 bytes (48−51) are the color transformation type, which specifies which decorrelation components are used to transform the RGB channels to YCbCr channels. If this is 1, the ITU-R BT.709 coefficients are used. If this is 1, the ITU-R BT.2020 coefficients are used. If this is zero, a custom color transformation is performed. For more information, see:

Color Transformations

The next 12 bytes (52−63) of the File Header is the null terminated ASCII string:

EndOfHeader\0

which marks the end of the file header.


Custom Properties

Following the File Header, beginning at byte offset 64 of the file, is the Custom Properties block.

Custom properties are a list of key/value pairs for storing any type of data. Each key must be ASCII text. The values can be any binary data.

The Custom Properties block (henceforth referred to as the Properties block) begins with a 4-byte start-of-properties marker, followed with a 4-byte Size integer, followed with a 4-byte Count integer, followed with key/value pairs (if there are any custom properties), and ending with a 4-byte end-of-properties marker.

The first four bytes of the Properties block store the value 0x534F5000 (ASCII string SOP\0) which marks the start-of-properties.

Start of Properties Marker:  SOP\0

The Size integer follows. It is a 32-bit integer that specifies the total size (number of bytes) of the entire Properties block including the Size integer and the start-of-properties marker.

The Count integer follows. It is a 32-bit integer that specifies how many properties (key/value pairs) there are. That is followed with that many key/value pairs, which is followed by an end-of-properties marker.

For each key/value pair, the key specifies the title of custom data, and the value is the custom data.

After the last key/value pair, a 4 byte end-of-properties marker stores 0x454F5000 (ASCII string EOP\0) marking the end of the Properties block.

End of Properties Marker:  EOP\0

Each key, of a key/value pair, is a 32-bit integer specifying how many characters the title has (including a termination null byte), followed with that many ASCII characters that are the title of the custom property (including the terminating null byte).

Each value, of a key/value pair, is a 32-bit integer that specifies the number of bytes of custom data, followed with that many bytes of custom data.

The shortest possible Properties block, for no properties, would be 16 bytes. In that case, the first four bytes of the Properties block would be the start-of-properties marker, followed with a 4-byte integer equal to 16 (the total size of the Properties block), followed with a 4-byte integer equal to zero indicating there was zero properties in the Properties block, and the last four bytes storing the end-of-properties marker.


Channels

The channels (image planes) follow the Custom Properties block to the end of file.

The Y channel is stored first, followed with the Cb channel, followed with the Cr channel. If there is an alpha channel, it follows the Cr channel.

Channels are just like in an XRH file:

Channels

Each of the YCbCr channels must be stored using JP2K compression of STOR_USI_FLOAT24 (Unsigned Scaled Integer):

JP2K Compression

STOR_USI_FLOAT24

If there is an alpha channel, it must be stored using Zebra compression of STOR_U_FLOAT24 (Unsigned 24-bit Float):

Zebra Compression

STOR_U_FLOAT24


JX4LIB Software

JX4LIB is free C language source code for reading and writing RGB JX4 files. JX4LIB is released under the ZLIB-style license, and requires that OpenJPEG be downloaded separately from the OpenJPEG web site.

Download the JX4LIB source code here:

jx4lib100.zip
(12 K)

This JX4LIB version has been implemented on Microsoft Windows with the OpenJPEG 2.5 dynamic link library (DLL). If you are already using OpenJPEG, use that installation, otherwise download the portable prebuilt DLL from the OpenJPEG web site.

Other OpenJPEG versions and other operating systems should also work.

JX4LIB is two .c files and two .h files. To use JX4LIB, include the two .c files in your project. If you are already using XRHLIB, then you will only need one of these .c files (the other .c file is a duplicate of a file that also comes with XRHLIB).

To use JX4LIB, you only need these two .c files, and the OpenJPEG prebuilt DLL from their web site (if OpenJPEG is not already available on your system).


Example File

The following RGB JX4 image stores 32-bit floating point samples, as scaled 24-bit samples compressed with JPEG 2000:

Underwater.jx4
(2.8 MB)

Image dimensions: 2160 × 1080 pixels
Scene model credit: Lux Core Render