The JX4 file format
file name extension)
is a simple standard royalties-free file format
for storing and archiving
JX4 files store
An alpha channel is optional.
If there is an alpha channel,
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:
All multi-byte numbers in a JX4 file are stored in Big Endian format (network byte order).
The first 64 bytes of an XRH file are the 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:
The next 12 bytes (52−63) of the File Header is the null terminated ASCII string:
which marks the end of the file header.
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
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.
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:
Each of the YCbCr channels must be stored using JP2K compression of STOR_USI_FLOAT24 (Unsigned Scaled Integer):
If there is an alpha channel, it must be stored using Zebra compression of STOR_U_FLOAT24 (Unsigned 24-bit Float):
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:
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).
The following RGB JX4 image stores 32-bit
floating point samples,
Image dimensions: 2160 × 1080 pixels
Scene model credit: Lux Core Render