Documentation

Contents

• OpenJPEG library (generated with doxygen) 
• JPEG 2000 Encoder
• JPEG 2000 Decoder
• Motion JPEG 2000
• Viewer JPIP + Indexer JPIP (obsolete)
• JPWL (Wireless JPEG 2000 )

JPEG 2000 encoder

Required arguments

One of the options for specifying Input file; -i or -ImgDir; is required to be used.


• Infile (format bmp, tif, raw, tga, pnm, pgm, ppm or pgx): -i Infile.pgm
  This option is required and specifies the name of the image you want to compress. Concerning the bmp format, the coder accepts 24 bits color images and 8 bits (RLE or no-RLE) images. TIF files can have up to 16 bits per component. With RAW images, the -F parameter must be used (see below). In the case of raw images with a component depth comprised between 9 and 16 bits, each component data must be stored on two bytes, the first byte containing the MSBs and the second byte the LSBs.
  When using this option output file must be specified using -o.
  
  
• Outfile (format j2k, jp2 or j2c): -o Outfile.j2k
  This option is required when using -i option and specifies the name of the file where the codestream will be saved.
  
  
• Image file directory : -ImgDir Folder_Path
  This option specifies the path of the folder where the images you want to compress is stored.
  When Image files are in the same directory as the executable it can be indicated by a dot "." argument.
  Examples:
  • -ImgDir ../samples
  • -ImgDir C:/PPM_Samples
  • -ImgDir .
  When using this option output format must be specified using -OutFor. The output codestream is saved in the same folder.
  
  
• OutFor (format j2k, jp2 or j2c): -OutFor Format
  This option is required when -ImgDir option is used. It specifies the format used to compress the images read from the File_folder.
  Accepted formats are J2K (= J2C) and JP2
  
  

These options (-i & -o or -ImgDir & -OutFor) are the only *required* options.

Ex: openjpeg -i car.pgm -o car.j2k

That means that you will encode the image with the default options:

• Lossless compression, 1 layer of quality
• 1 tile
• Size of precinct 2¹⁵ x 2¹⁵ (means 1 precinct)
• Size of code-block 64 x 64
• Number of resolution (i.e. DWT decomposition level) : 6
• No SOP marker in the codestream
• No EPH marker in the codestream
• No sub-sampling in x and y direction
• No mode switch activated
• Progression order : LRCP
• No index file
• No ROI upshifted
• No offset of the origin of the image
• No offset of the origin of the tiles
• Reversible DWT 5-3

Options available

• Rate values : -r 20,10,5
  This option offers the possibility to define the compression rate to apply. Each value is a factor of compression, thus 20 means 20 times compressed. Each value represents a quality layer. The order used to define the different levels of compression is important and must be from left to right in descending order. A lossless compression will be signified by the value 1.
  
  
  
• Quality values : -q 30,35,40
  This option offers the possibility to define the quality level to achieve. Each value is a psnr, to be given in dB, and represents a quality layer. The order used to define the different psnr-values is important and must be from left to right in ascending order.
  
  
  
• Number of resolution : -n 3
  This option offers the possibility to define the number of resolution or the number of decomposition for the discret wavelet transform (DWT). The default value is 6.
  
  
  
• Code-block size : -b 32,32
  This option offers the possibility to define the size of the code-block. The dimension must respect the constraint defined in the JPEG-2000 standard. The maximum value autorized is 64x64 wich is also the default value.
  
  
  
• Precinct size : -c [128,128],[128,128],...
  This option offers the possibility to define the size of the precincts for at each resolution (the values specified must be power of 2). Multiple recorde may be supplied, in which case the first record refers to the highest resolution level and subsequent records to lower resolution levels. The last specified record is right-shifted for each remaining lower resolution levels. The default dimension is 2¹⁵ x 2¹⁵ at each resolution.
  
  
  
• Tile size : -t 512,512
  This option offers the possibility to divide the image in several tiles. The two numbers specified respectively the width and the heigth of the tile. The default values are the dimension of the global image, thus only one tile.
  
  
  
• Irreversible compression (ICT + DWT 9-7) : -I
  This option offers the possibility to work with the Irreversible Color Transformation (ICT) in place of the Reversible Color Transformation (RCT) and with the irreversible DWT 9-7 in place of the filter 5-3.
  
  
  
• Progression order : -p LRCP
  This option offers the possibility to specify the progression order. The five progression orders are : LRCP, RLCP, RPCL, PCRL and CPRL. By default, the progression order is LRCP.
  
  
  
• Cinema2K profile : -cinema2K 24 or 48
  This option generates a codestream compliant to the Digital cinema specifications for a 2K resolution content. The value given is the frame rate which can be 24 or 48 fps. The main specifications of the JPEG Profile-3 (2K Digital Cinema Profile)
  • Image size = 2048 x 1080 (at least one of the dimensions should match 2048 x 1080)
  • Single tile
  • Wavelet transform levels = Maximum of 5
  • Wavelet filter = 9-7 filter
  • Codeblock size = 32 x 32
  • Precinct size = 128 x 128 (Lowest frequency subband), 256 x 256 (other subbands)
  • Maximum Bit rate for entire frame = 1302083 bytes for 24 fps, 651041 bytes for 48fps
  • Maximum Bit rate for each color component= 1041666 bytes for 24 fps, 520833 bytes for 48fps
  • Tile parts = 3; Each tile part contains data necessary to decompress one 2K color component
  • 12 bits per component
  
  
  
• Cinema4K profile : -cinema4K
  This option generates a codestream compliant to the Digital cinema specifications for a 4K resolution content. The value for frame rate should not be specified. Value is initialised to 24fps. The main specifications of the JPEG Profile-4 (4K Digital Cinema Profile) include:
  • Image size = 4096 x 2160 (at least one of the dimensions must match 4096 x 2160)
  • Single tile
  • Wavelet transform levels = Maximum of 6 and mininum of 1
  • Wavelet filter = 9-7 filter
  • Codeblock size = 32 x 32
  • Precinct size = 128 x 128 (Lowest frequency subband), 256 x 256 (other subbands)
  • Maximum Bit rate for entire frame = 1302083 bytes for 24 fps
  • Maximum Bit rate for each color component= 1041666 bytes for 24 fps
  • Tile parts = 6; Each of first 3 tile part contains data necessary to decompress one 2K color component, and each of last 3 tile part contains data necessary to decompress one 4K color component
  • 12 bits per component
  
  
  
• Progression order change : -POC Ttile num = Resolution num start, Component num start, Layer num end, Resolution num end, Component num end, Progression order
  This defines the bounds of resolution, color component, layer and progression order if a progression order change is desired.
  Example:
  
  • -POC T1=0,0,1,5,3,CPRL/T1=5,0,1,6,3,CPRL
  
  
  
• Subsampling factor : -s 2,2
  This option offers the possibility to apply a subsampling factor. The value are respectively for X and Y axis. Value higher than 2 can be a source of error ! The default value are 1 and 1.
  
  
  
• SOP marker before each packet : -SOP
  This option offers the possibility to add a specific marker before each packet. It is the marker SOP (Start of packet). If the option is not used no SOP marker will be added.
  
  
  
• EPH marker after each packet header : -EPH
  This option offers the possibility to add a specific marker at the head of each packet header. It is the marker EPH (End of packet Header). If the option is not used no EPH marker will be added.
  
  
  
• Switch modes : -M 3
  This option offers the possibility to use a mode switch during the encoding process. There are 6 modes switch :
  • BYPASS(LAZY) [1]
  • RESET [2]
  • RESTART(TERMALL) [4]
  • VSC [8]
  • ERTERM(SEGTERM) [16]
  • SEGMARK(SEGSYM)] [32]
  For several mode switch you have to add the value between []. By default no mode switch is used
  
  Exemple : RESTART(4) + RESET(2) + SEGMARK(32) => -M 38
  
  
  
• Index file *.Idx : -x index_name.Idx
  This option offers the possibility to create an index file. The name of the file must be specified. This index is a text file that summerizes the codestream. This index is useful to create a navigation process. The index structure is the following (each white bullet means a new line in the index-file, black ones are separated by a space, italic information are just indications and do *not* appear in the index-file):
  • Image size:
    • ImgW
    • ImgH
  • Progression Order:
    • Prog
  • Tile size: 
    • TileW
    • TileH
  • Number of components:
    • NumComp
  • Number of layers:
    • NumLayer
  • Number of decompositions (=(number of resolutions - 1)):
    • NumDWT
  • Precinct size:
    • [Precinct_width(NumDWT),Precinct_height(NumDWT)]
    • [Precinct_width(NumDWT-1),Precinct_height(NumDWT-1)]
    • ...
    • [Precinct_width(0),Precinct_height(0)]
  • Main Header end position:
    • MH_EndPos
  • Codestream size:
    • CSSize
  • Tile 0 information:
    • TileNum (0) 
    • StartPos
    • TH_EndPos
    • EndPos
    • TotalDisto (this is the sum of the distortion reductions brought by each packet belonging to this tile)
    • NumPix (this is the number of pixels in the tile)
    • MaxMSE (=TotalDisto/NumPix)
  • Tile1 information:
    • TileNum (1)
    • ...
  • ...
  • Tile N information:
    • TileNum (N)
    • ...
  • Packet 0 from Tile 0 information:
    • PackNum (0)
    • TileNum (0) 
    • LayerNum
    • ResNum
    • CompNum
    • PrecNum
    • StartPos
    • EndPos
    • Disto (distortion reduction brought by this packet)
  • Packet 1 from Tile 0 information:
    • PackNum (1)
    • ...
  • ...
  • Packet M from Tile 0 information
  • Packet 0 from Tile 1 information
  • ...
  • Packet M from Tile N information
  • Maximum distortion reduction on the whole image:
    • MaxDisto
  • Total distortion on the whole image (sum of the distortion reductions from all packets in the image):
    • TotalDisto
  
  
  
• Quantization indices upshifted for a component : -ROI c=0,U=25
  Warning: This option does not implement the usual ROI (Region of Interest). It should be understood as a "Component of Interest".
  This option offers the possibility to upshift the value of a component during quantization step. The value after c= is the composant number [0, 1, 2, ...] and the value after U= is the value of upshifting. U must be in the range [0, 37].
  
  
  
• Offset of the image origin : -d 150,300
  This option offers the possibility to move the origine of the image. The division in tile could be modified as the anchor point for tiling will be different than the image origin. However we must keep in mind that the offset of the image can not be higher than the tile dimension if the tile option is used. The 2 values are respectively for X and Y axis offset, the default value is (0,0).
  
  
  
• Offset of the tile origin : -T 100,75
  This option offers the possibility to move the anchor point of the image. We must keep in mind that the tile anchor point can not be on the image area. The 2 values are respectively for X and Y axis offset, the default value is (0,0).
  
  
  
• Raw format specification : -F 512,512,3,8,u
  This option must be used when encoding an image stored under the RAW format (*.raw). It defines the input image width, height, the number of components, the component bit depth and defines if the values are signed. The syntax is the following:
  -F rawWidth,rawHeight,rawComp,rawBitDepth,s/u (Signed/Unsigned)
  Example of a 512x512 image with 3 unsigned components of 8 bits: image_to_j2k -i lena.raw -o lena.j2k -F 512,512,3,8,u
  As explained above, in the case of raw images with a component depth comprised between 9 and 16 bits, each component data must be stored on two bytes, the first byte containing the MSBs and the second byte the LSBs.
  
  
  
• Display the help menu : -h
  This option displays on screen the content of this page
  
  

JPEG 2000 decoder

Required arguments

One of the options for specifying Input file; -ImgDir or -i; is required to be used.


• Infile : -i compressed file
  Currently accepts J2K, J2C, JP2 and JPT files. The file type is identified based on its suffix.
  
  
  
• Outfile : -o decompressed file
  Currently accepts BMP, TIF, RAW, TGA, PGM, PPM, PNM and PGX files. Binary data is written to the file (not ascii). If a PGX filename is given, there will be as many output files as there are components: an indice starting from 0 will then be appended to the output filename, just before the "pgx" extension. If a PGM filename is given and there are more than one component, only the first component will be written to the file.
  
  
  
• Image file directory : -ImgDir Folder_Path
  This option specifies the path of the folder where the codestream you want to decompress is stored.
  When compressed files are in the same directory as the executable it can be indicated by a dot "." argument.
  Examples:
  • -ImgDir ../samples
  • -ImgDir C:/PPM_Samples
  • -ImgDir .
  
  When using this option output format must be specified using -OutFor. The output image file is saved in the same folder.
  
  
  
• OutFor : -OutFor Format
  This option is required when -ImgDir option is used. It specifies the format used to decompress the codestream read from the Image folder.
  Currently accepts TIF, RAW, TGA, PGM, PPM, PNM, PGX and BMP format.
  
  
  
  

Options available

• Reduce factor : -r n
  Set the number of highest resolution levels to be discarded. The image resolution is effectively divided by 2 to the power of the number of discarded levels. The reduce factor is limited by the smallest total number of decomposition levels among tiles.
  
  
  
• Layer number : -l n
  Set the maximum number of quality layers to decode. If there are less quality layers than the specified number, all the quality layers are decoded.
  
  
  
• Display the help menu : -h
  This option displays on screen the content of this page
  
  
  
• Index file *.Idx : -x index_name.Idx
  This option offers the possibility to create an index file. The name of the file must be specified. This index is a text file that summerizes the codestream. This index is useful to create a navigation process. The index structure is the following (each white bullet means a new line in the index-file, black ones are separated by a space, italic information are just indications and do *not* appear in the index-file):
  • Image size:
    • ImgW
    • ImgH
  • Progression Order:
    • Prog
  • Tile size: 
    • TileW
    • TileH
  • Number of components:
    • NumComp
  • Number of layers:
    • NumLayer
  • Number of decompositions (=(number of resolutions - 1)):
    • NumDWT
  • Precinct size:
    • [Precinct_width(NumDWT),Precinct_height(NumDWT)]
    • [Precinct_width(NumDWT-1),Precinct_height(NumDWT-1)]
    • ...
    • [Precinct_width(0),Precinct_height(0)]
  • Main Header end position:
    • MH_EndPos
  • Codestream size:
    • CSSize
  • Tile 0 information:
    • TileNum (0) 
    • StartPos
    • TH_EndPos
    • EndPos
    • NumPix (this is the number of pixels in the tile)
    • Note: The distorsion information is only available at encoding
  • Tile1 information:
    • TileNum (1)
    • ...
  • ...
  • Tile N information:
    • TileNum (N)
    • ...
  • Packet 0 from Tile 0 information:
    • PackNum (0)
    • TileNum (0) 
    • LayerNum
    • ResNum
    • CompNum
    • PrecNum
    • StartPos
    • EndPos
    • Note: The distorsion information is only available at encoding
  • Packet 1 from Tile 0 information:
    • PackNum (1)
    • ...
  • ...
  • Packet M from Tile 0 information
  • Packet 0 from Tile 1 information
  • ...
  • Packet M from Tile N information
  • Maximum distortion reduction on the whole image:
    • This information is only available at encoding
  • Total distortion on the whole image (sum of the distortion reductions from all packets in the image):
    • This information is only available at encoding
  
  
  

Motion JPEG 2000 files

Attention : The Motion JPEG 2000 codec is currently using OpenJPEG v0.97 and is thus not including all the latest OpenJPEG optimizations and features.

The MJ2 part of OpenJPEG has five modules: An encoder, a decoder, a J2K wrapper (j2k frames to an mj2 file), a J2K extractor (mj2 file to j2k frames) and a XML generator extracting metadata from MJ2 files.

1. MJ2 encoder

The MJ2 encoder compresses YUV files to Motion JPEG 2000 standard file.

The minimum command line for the MJ2 encoder is:
frames_to_mj2 -i yuv_file.yuv  -o mj2_file.mj2 -W width,height,CbCrSubsampling_dx,CbCrSubsampling_dy,

Use the -F option to specifie the frame rate (the default frame-rate is 25)

Example: To encode the standard YUV CIF frames (352*288) formeman.yuv at 30 frames per second, the command line should be:
frames_to_mj2 -i foreman.yuv -o foreman.mj2 -W 352,288,2,2 -F 30

Additionally to that, all the JPEG 2000 Encoder options can be used in the command line.
The MJ2 library generates the MJ2 boxes specified in the mj2_movie structure. This structure can be a standard one, like in  the frames_to_mj2 codec, or a more specific one created by the user.
The standard mj2_movie structure has one video track containig the compressed codestream of the yuv, with a timescale of 1ms, with one sample per chunk.

2. MJ2 decoder

The MJ2 decoder decompresses Motion JPEG 2000 files to YUV files.

The command line for the MJ2 decoder is:
mj2_to_frames mj2_file.mj2  yuv_file.yuv  

3. MJ2 wrapper

The MJ2 wrapper module wraps one or several j2k bitstreams into a mj2 file. This wrapping is done with standard parameters (25 frames per second, no sound or hint tracks, ...), but this can be modified in the setparams function.

The command line for the MJ2 wrapper is:
MJ2_Wrapper infile_root outfile.mj2

where infile_root contains the path and the name of the input files before its number (5 digits, starting from 00000) and extension. For example, if I want to create the MJ2 file video/foreman.mj2 with the input files:
image/foreman_00000.j2k
image/foreman_00001.j2k
image/foreman_00002.j2k
The command line to use is MJ2_Wrapper image/foreman video/foreman.mj2

4. MJ2 extractor

The MJ2 extractor module extracts the j2k bitstreams contained in an MJ2 file.

The command line for the MJ2 extractor is:
MJ2_extractor infile.mj2 outfile_root 

where outfile_root contains the path and the name of the output files before its number (5 digits, starting from 00000) and extension. For example, if the MJ2 file video/foreman.mj2 contains three frames, if I want to create the input files:
image/foreman_00000.j2k
image/foreman_00001.j2k
image/foreman_00002.j2k
The command line to use is MJ2_extractor video/foreman.mj2 image/foreman

5. Metadata Reader

"Mj2_to_metadata", under development, is a Windows command-line function that reads metadata from a Motion JPEG 2000 video file and generates an XML file with a representation of that content.  So far, it is limited to reporting structural metadata, but descriptive metadata is planned.  It is run from the command-line by:

mj2_to_metadata -i input.mj2 -o output.xml

 

Additional options are discussed here.
Thanks to Glenn Pearson for his contributions to this project !!!

MJ2 Sample file

An MJ2 sample file is available here.
To decompress it, use the following command: mj2_to_frames.exe speedway_opj.mj2 speedway_decompressed.yuv
To extract the j2k images, use the following command: MJ2_Extractor.exe speedway_opj.mj2 speedway_frame

JPWL (Wireless JPEG 2000)

1. JPWL ENCODER

The JPWL options will only work with the JPWL library located in the jpwl/ directory obtained when downloading the OpenJPEG source code.

• adoption of JPWL (Part 11) capabilities : -W params
  This option offers the possibility to work with the JPEG2000 for Wireless LANs (JPWL) extension, which is defined in Part 11 of the standard.
  The following parameters, separated by commas, can be written and repeated in any order:

[h<tile><=type>,s<tile><=method>,a=<addr>,z=<size>,g=<range>,p<tile:pack><=type>]

• h selects the header error protection (EPB): type can be

  • 0=none
  • 1,absent=predefined
  • 16=CRC-16
  • 32=CRC-32
  • 37-128=RS
  if tile is absent, it applies to main and tile headers;
  if tile is present, it applies from that tile onwards, up to the next h<tile> spec, or to the last tile in the codestream (max. 16 specs)
  
• p selects the packet error protection (EEP/UEP with EPBs) to be applied to raw data: type can be
  • 0=none
  • 1,absent=predefined
  • 16=CRC-16
  • 32=CRC-32
  • 37-128=RS
  if tile:pack is absent, it starts from tile 0, packet 0;
  if tile:pack is present, it applies from that tile and that packet onwards, up to the next packet spec or to the last packet in the last tile in the codestream (max. 16 specs)
  
• s enables sensitivity data insertion (ESD): method can be
  • -1=NO ESD
  • 0=RELATIVE ERROR
  • 1=MSE
  • 2=MSE REDUCTION
  • 3=PSNR
  • 4=PSNR INCREMENT
  • 5=MAXERR
  • 6=TSE
  • 7=RESERVED
  if tile is absent, it applies to main header only;
  if tile is present, it applies from that tile onwards, up to the next s<tile> spec, or to the last tile in the codestream (max. 16 specs)
  
• g determines the addressing mode: range can be
  • 0=PACKET
  • 1=BYTE RANGE
  • 2=PACKET RANGE
  
  
• a determines the size of data addressing: addr can be 2/4 bytes (small/large codestreams). If not set, auto-mode
  
• z determines the size of sensitivity values: size can be 1/2 bytes, for the transformed pseudo-floating point value

EXAMPLE:

-W h,h0=64,h3=16,h5=0,p0=78,p0:24=56,p1,p3:0=0,p3:20=32,s=0,s0=6,s3=-1,a=0,g=1,z=1

means predefined EPB in MH, rs(64,32) from TPH 0 to TPH 2, CRC-16 in TPH 3 and TPH 4, no EPBs in remaining TPHs, UEP rs(78,32) for packets 0 to 23 of tile 0, UEP rs(56,32) for packets 24 to the last of tile 0, UEP rs default for packets of tile 1, no UEP for packets 0 to 19 of tile 3, UEP CRC-32 for packets 20 of tile 3 to last tile, relative sensitivity ESD for MH, TSE ESD from TPH 0 to TPH 2, byte range with automatic size of addresses and 1 byte for each sensitivity value

EXAMPLE:

-W h,s,p

means default protection to headers (MH and TPHs) as well as data packets, one ESD in MH

2. JPWL Decoder

The JPWL options will only works with the JPWL library located in the jpwl/ directory obtained when downloading the OpenJPEG source code.

• adoption of JPWL (Part 11) capabilities : -W options
  Activates the JPEG2000 for Wireless LANs (Part 11) correction capabilities, if the codestream has been prepared accordingly (i.e. -W switch at the encoder). Options can be a comma separated list of <param=val> tokens:
  
  
• c,c=numcomps
  numcomps is the number of expected components in the codestream (search of first EPB rely upon this, default is 3)