1 ===============================================================================
2 JPEG2000 Part 10 (ISO/IEC 15444-10 JP3D) Verification Model
5 ===============================================================================
11 This document describes the installation and the use of the JP3D VM decoder and encoder under several operating systems (Linux, Unix, Windows, ...). Version 1.1 contains a complete JPEG 2000 Part 10 encoder, as well as a decoder.
12 The supported functionalities are compliant with the JPEG2000 part 10 algorithm as described in the WD 6.0.
13 The provided encoder and the decoder are compatible also with the International standard IS 15444-1 (core coding system).
14 This implementation has been developped from OpenJPEG implementation of JPEG2000 standard, and for this reason it is written in C language.
16 If you find some bugs or if you have problems using the encoder/decoder, please send an e-mail to jp3d@lpi.tel.uva.es
18 2. Installing the code
19 ======================================================
21 - After decompressing the zip file provided, you should find
22 at least the following files in the created 'jp3d_vm' directory:
24 * libjp3dvm - This directory contains all library related code
25 * codec - This directory contains all codec related code
26 * tcltk - This directory contains the API scripts
27 * README - The file you are reading
28 * LICENCE - Copyright statement of the JP3D VM software
30 2.1. Compiling the source code in Windows
31 -------------------------------------------
33 This version has been compiled with Visual Studio 2003 using
34 the projects included in the distribution:
36 * LibJp3dVM.vcproj - Creates the library with all the JP3D functionalities
37 * jp3d_vm_enc.vcproj - Test encoder
38 * jp3d_vm_dec.vcproj - Test decoder
40 2.2. Compiling the source code in Unix-like systems
41 -------------------------------------------
44 ------------------------
45 This version of the library has been tested under the following OS:
48 The installation process is as simple as this :
49 1) Enter the 'jp3d_vm' directory
50 2) Build the distribution :
53 3) Clean all files produced during the build process
57 ------------------------
58 Once you've built the library, you should compile the JP3D codec.
60 1) Go to the 'codec' directory
61 2) Build the encoder and decoder programs:
63 gcc convert.c volume_to_jp3d.c -o jp3d_vm_enc -I ../libjp3dvm/ -lm -ljp3dvm
64 gcc convert.c jp3d_to_volume.c -o jp3d_vm_dec -I ../libjp3dvm/ -lm -ljp3dvm
66 Note: You should add '-L ../libjp3dvm/' to those lines if you
67 did not use the 'install' target (and the 'clean' target neither...).
69 3. Running the JP3D VM
70 ====================================================
73 ====================================================
76 ------------------------
78 * Input file(s): -i Involume [*.bin, *.pgx]
80 Specifies the volume to compress. Accepted formats are *.BIN (raw binary data) or *.PGX files.
81 Both formats need some particular settings:
83 a) BIN format. As it has no header, volume characteristics will be obtained from a .IMG file. Its location will be specified through the following argument:
85 This file shall have the following structure, with the appropiate value in each case (bit per voxel, color map, dimensions in X,Y,Z):
90 b) PGX format. Program will consider it as a volume slice. In order to denote a volume through a sequence of slices, you can define the input filename with the common pattern of the set of PGX files followed by a dash (as a wildcard character for the sequence numbers).
92 * Output file: -o Outfile [*.jp3d, *j2k]
94 Specifies the name of the file where the codestream will be saved.
95 Part 1 compliant codestream will be created when an outfile has .j2k format.
100 * Rate values : -r 20,10,5
101 This option offers the possibility to define the compression rate to apply.
102 Each value is a factor of compression (i.e. 20 : 1) and will generate a different quality layer. A lossless compression will be signified by the value 1.
103 NOTE : The order used to define the different levels of compression is important and must be from left to right in descending order.
105 * Quality values : -q 30,35,40
106 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.
107 NOTE : The order used to define the different psnr-values is important and must be from left to right in ascending order.
110 * Number of resolutions : -n 3,3,2
111 This option offers the possibility to define the number of resolution levels computed for each dimension of the volume through the discret wavelet transform (DWT). Resolution in axial dimension can have a different value than in horizontal and vertical cases, but must be lower.
112 DEFAULT VALUE : 3,3,1
115 * Switch modes : -M 3
116 This option offers the possibility to use a mode switch during the encoding process:
119 o RESTART(TERMALL) [4]
121 o ERTERM(SEGTERM) [16]
122 o SEGMARK(SEGSYM) [32]
124 For several mode switch just sum corresponding values: i.e. -M 38 => RESTART(4) + RESET(2) + SEGMARK(32)
128 * Progression order : -p LRCP
129 This option offers the possibility to specify the progression order. Possible progression orders are : LRCP, RLCP, RPCL, PCRL and CPRL.
133 * Code-block size : -b 32,32,32
134 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 64x64x64.
135 DEFAULT VALUE: 64,64,64
138 * Precinct size : -c [128,128,128],[128,128,128],...
139 This option offers the possibility to define the size of the precincts at each resolution. Multiple records 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.
140 NOTE : specified values must be power of 2.
141 DEFAULT VALUE: 2^15 x 2^15 x 2^15
144 * Tile size : -t 512,512,512
145 This option offers the possibility to divide the volume in several tiles. The three values define the width, the heigth and the depth of the tile respectivily.
146 DEFAULT VALUE: Volume dimensions (one tile)
149 * Subsampling factor : -s 2,2,2
150 This option offers the possibility to apply a subsampling factor for X, Y and Z axis. Value higher than 2 can be a source of error !
154 * SOP marker before each packet : -SOP
155 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.
158 * EPH marker after each packet header : -EPH
159 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.
162 * Offset of the volume origin : -d 150,300,10
163 This option offers the possibility to move the origine of the volume in X, Y and/or Z axis. The division in tile could be modified as the anchor point for tiling will be different than the volume origin.
164 NOTE : the offset of the volume can not be higher than the tile dimension if the tile option is used.
168 * Offset of the tile origin : -T 100,75,5
169 This option offers the possibility to move the anchor point of the volume in X, Y and/or Z axis.
170 NOTE : the tile anchor point can not be on the volume area.
174 * Display the help menu : -help
175 This option displays on screen the content of this page
178 ----------------------------------
180 * Encoding information file: -x index_name.idx
181 This option offers the possibility to create a text file with some structured information generated through the encoding. The name of the file must be specified, with .idx extension. The information structure is the following:
187 + TileW + TileH + TileD
188 o Number of components:
192 o Number of decompositions (=(number of resolutions - 1)):
193 + NumDWTx + NumDWTy + NumDWTz
195 + [Precinct_width(NumDWT),Precinct_height(NumDWT),Precinct_depth(NumDWT)]
196 + [Precinct_width(NumDWT-1),Precinct_height(NumDWT-1),Precinct_depth(NumDWT-1)]
198 + [Precinct_width(0),Precinct_height(0),Precinct_depth(0)]
199 o Main Header end position:
203 o Tile 0 information:
208 + TotalDisto (this is the sum of the distortion reductions brought by each packet belonging to this tile)
209 + NumPix (this is the number of pixels in the tile)
210 + MaxMSE (=TotalDisto/NumPix)
215 o Tile N information:
218 o Packet 0 from Tile 0 information:
227 + Disto (distortion reduction brought by this packet)
228 o Packet 1 from Tile 0 information:
232 o Packet M from Tile 0 information
233 o Packet 0 from Tile 1 information
235 o Packet M from Tile N information
236 o Maximum distortion reduction on the whole volume:
238 o Total distortion on the whole volume (sum of the distortion reductions from all packets in the volume):
242 ====================================================
245 ------------------------
247 * Infile : -i compressed file
248 Currently accepts JP3D and J2K-files. The file type is identified based on its suffix (*.jp3d, *.j2k).
251 * Outfile(s) : -o decompressed file(s)
252 Currently accepts BIN-files and PGX-files. Binary data is written to the file (not ascii).
253 If a BIN-file is defined, decoder will create automatically the volume characteristic file appending a .IMG extension to the provided output filename.
254 If a PGX-file is defined, decoder will understand this as a file pattern, appending corresponding indice from 0 to the number of decoded slices.
255 NOTE : 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 extension.
259 ------------------------
261 * Reduce factor : -r 1,1,0
262 Set the number of highest resolution levels to be discarded in each dimension. The decoded volume size is effectively divided by 2 to the power of the number of discarded levels.
263 NOTE : The reduce factor is limited by the smallest total number of decomposition levels among tiles.
266 * Layer number : -l 2
267 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.
270 * Performance comparisons : -O original-file
271 This option offers the possibility to compute some quality results for the decompressed volume, like the PSNR value achieved or the global SSIM value. Needs the original file in order to compare with the new one.
272 NOTE: Only valid when -r option is 0,0,0 (both original and decompressed volumes have same resolutions)
273 NOTE: If original file is .BIN file, the volume characteristics file shall be defined with the -m option.
274 (i.e. -O original-BIN-file -m original-IMG-file)
277 * Byte order (Big-endian / Little-endian) : -BE
278 This option offers the possibility to save the decompressed volume with a predefined byte order.
279 DEFAULT VALUE: Little-endian
282 * Display the help menu : -help
283 This option displays on screen the content of this page