libopenjpeg/j2k.h

   1 /*
   2  * Copyright (c) 2002-2007, Communications and Remote Sensing Laboratory, Universite catholique de Louvain (UCL), Belgium
   3  * Copyright (c) 2002-2007, Professor Benoit Macq
   4  * Copyright (c) 2001-2003, David Janssens
   5  * Copyright (c) 2002-2003, Yannick Verschueren
   6  * Copyright (c) 2003-2007, Francois-Olivier Devaux and Antonin Descampe
   7  * Copyright (c) 2005, Herve Drolon, FreeImage Team
   8  * Copyright (c) 2006-2007, Parvatha Elangovan
   9  * All rights reserved.
  10  *
  11  * Redistribution and use in source and binary forms, with or without
  12  * modification, are permitted provided that the following conditions
  13  * are met:
  14  * 1. Redistributions of source code must retain the above copyright
  15  *    notice, this list of conditions and the following disclaimer.
  16  * 2. Redistributions in binary form must reproduce the above copyright
  17  *    notice, this list of conditions and the following disclaimer in the
  18  *    documentation and/or other materials provided with the distribution.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  24  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30  * POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 #ifndef __J2K_H
  33 #define __J2K_H
  34 /**
  35 @file j2k.h
  36 @brief The JPEG-2000 Codestream Reader/Writer (J2K)
  37
  38 The functions in J2K.C have for goal to read/write the several parts of the codestream: markers and data.
  39 */
  40
  41 /** @defgroup J2K J2K - JPEG-2000 codestream reader/writer */
  42 /*@{*/
  43
  44 #define J2K_CP_CSTY_PRT 0x01
  45 #define J2K_CP_CSTY_SOP 0x02
  46 #define J2K_CP_CSTY_EPH 0x04
  47 #define J2K_CCP_CSTY_PRT 0x01
  48 #define J2K_CCP_CBLKSTY_LAZY 0x01     /**< Selective arithmetic coding bypass */
  49 #define J2K_CCP_CBLKSTY_RESET 0x02    /**< Reset context probabilities on coding pass boundaries */
  50 #define J2K_CCP_CBLKSTY_TERMALL 0x04  /**< Termination on each coding pass */
  51 #define J2K_CCP_CBLKSTY_VSC 0x08      /**< Vertically stripe causal context */
  52 #define J2K_CCP_CBLKSTY_PTERM 0x10    /**< Predictable termination */
  53 #define J2K_CCP_CBLKSTY_SEGSYM 0x20   /**< Segmentation symbols are used */
  54 #define J2K_CCP_QNTSTY_NOQNT 0
  55 #define J2K_CCP_QNTSTY_SIQNT 1
  56 #define J2K_CCP_QNTSTY_SEQNT 2
  57
  58 /* ----------------------------------------------------------------------- */
  59
  60 #define J2K_MS_SOC 0xff4f       /**< SOC marker value */
  61 #define J2K_MS_SOT 0xff90       /**< SOT marker value */
  62 #define J2K_MS_SOD 0xff93       /**< SOD marker value */
  63 #define J2K_MS_EOC 0xffd9       /**< EOC marker value */
  64 #define J2K_MS_SIZ 0xff51       /**< SIZ marker value */
  65 #define J2K_MS_COD 0xff52       /**< COD marker value */
  66 #define J2K_MS_COC 0xff53       /**< COC marker value */
  67 #define J2K_MS_RGN 0xff5e       /**< RGN marker value */
  68 #define J2K_MS_QCD 0xff5c       /**< QCD marker value */
  69 #define J2K_MS_QCC 0xff5d       /**< QCC marker value */
  70 #define J2K_MS_POC 0xff5f       /**< POC marker value */
  71 #define J2K_MS_TLM 0xff55       /**< TLM marker value */
  72 #define J2K_MS_PLM 0xff57       /**< PLM marker value */
  73 #define J2K_MS_PLT 0xff58       /**< PLT marker value */
  74 #define J2K_MS_PPM 0xff60       /**< PPM marker value */
  75 #define J2K_MS_PPT 0xff61       /**< PPT marker value */
  76 #define J2K_MS_SOP 0xff91       /**< SOP marker value */
  77 #define J2K_MS_EPH 0xff92       /**< EPH marker value */
  78 #define J2K_MS_CRG 0xff63       /**< CRG marker value */
  79 #define J2K_MS_COM 0xff64       /**< COM marker value */
  80 /* UniPG>> */
  81 #ifdef USE_JPWL
  82 #define J2K_MS_EPC 0xff68       /**< EPC marker value (Part 11: JPEG 2000 for Wireless) */
  83 #define J2K_MS_EPB 0xff66       /**< EPB marker value (Part 11: JPEG 2000 for Wireless) */
  84 #define J2K_MS_ESD 0xff67       /**< ESD marker value (Part 11: JPEG 2000 for Wireless) */
  85 #define J2K_MS_RED 0xff69       /**< RED marker value (Part 11: JPEG 2000 for Wireless) */
  86 #endif /* USE_JPWL */
  87 #ifdef USE_JPSEC
  88 #define J2K_MS_SEC 0xff65    /**< SEC marker value (Part 8: Secure JPEG 2000) */
  89 #define J2K_MS_INSEC 0xff94  /**< INSEC marker value (Part 8: Secure JPEG 2000) */
  90 #endif /* USE_JPSEC */
  91 /* <<UniPG */
  92
  93
  94 /* ----------------------------------------------------------------------- */
  95
  96 /**
  97 Values that specify the status of the decoding process when decoding the main header.
  98 These values may be combined with a | operator.
  99 */
 100 typedef enum J2K_STATUS {
 101         J2K_STATE_MHSOC  = 0x0001, /**< a SOC marker is expected */
 102         J2K_STATE_MHSIZ  = 0x0002, /**< a SIZ marker is expected */
 103         J2K_STATE_MH     = 0x0004, /**< the decoding process is in the main header */
 104         J2K_STATE_TPHSOT = 0x0008, /**< the decoding process is in a tile part header and expects a SOT marker */
 105         J2K_STATE_TPH    = 0x0010, /**< the decoding process is in a tile part header */
 106         J2K_STATE_MT     = 0x0020, /**< the EOC marker has just been read */
 107         J2K_STATE_NEOC   = 0x0040, /**< the decoding process must not expect a EOC marker because the codestream is truncated */
 108         J2K_STATE_ERR    = 0x0080  /**< the decoding process has encountered an error */
 109 } J2K_STATUS;
 110
 111 /* ----------------------------------------------------------------------- */
 112
 113 /**
 114 T2 encoding mode
 115 */
 116 typedef enum T2_MODE {
 117         THRESH_CALC = 0,        /** Function called in Rate allocation process*/
 118         FINAL_PASS = 1          /** Function called in Tier 2 process*/
 119 }J2K_T2_MODE;
 120
 121 /**
 122 Quantization stepsize
 123 */
 124 typedef struct opj_stepsize {
 125         /** exponent */
 126         int expn;
 127         /** mantissa */
 128         int mant;
 129 } opj_stepsize_t;
 130
 131 /**
 132 Tile-component coding parameters
 133 */
 134 typedef struct opj_tccp {
 135         /** coding style */
 136         int csty;
 137         /** number of resolutions */
 138         int numresolutions;
 139         /** code-blocks width */
 140         int cblkw;
 141         /** code-blocks height */
 142         int cblkh;
 143         /** code-block coding style */
 144         int cblksty;
 145         /** discrete wavelet transform identifier */
 146         int qmfbid;
 147         /** quantisation style */
 148         int qntsty;
 149         /** stepsizes used for quantization */
 150         opj_stepsize_t stepsizes[J2K_MAXBANDS];
 151         /** number of guard bits */
 152         int numgbits;
 153         /** Region Of Interest shift */
 154         int roishift;
 155         /** precinct width */
 156         int prcw[J2K_MAXRLVLS];
 157         /** precinct height */
 158         int prch[J2K_MAXRLVLS];
 159 } opj_tccp_t;
 160
 161 /**
 162 Tile coding parameters :
 163 this structure is used to store coding/decoding parameters common to all
 164 tiles (information like COD, COC in main header)
 165 */
 166 typedef struct opj_tcp {
 167         /** 1 : first part-tile of a tile */
 168         int first;
 169         /** coding style */
 170         int csty;
 171         /** progression order */
 172         OPJ_PROG_ORDER prg;
 173         /** number of layers */
 174         int numlayers;
 175         /** multi-component transform identifier */
 176         int mct;
 177         /** rates of layers */
 178         float rates[100];
 179         /** number of progression order changes */
 180         int numpocs;
 181         /** indicates if a POC marker has been used O:NO, 1:YES */
 182         int POC;
 183         /** progression order changes */
 184         opj_poc_t pocs[32];
 185         /** packet header store there for futur use in t2_decode_packet */
 186         unsigned char *ppt_data;
 187         /** pointer remaining on the first byte of the first header if ppt is used */
 188         unsigned char *ppt_data_first;
 189         /** If ppt == 1 --> there was a PPT marker for the present tile */
 190         int ppt;
 191         /** used in case of multiple marker PPT (number of info already stored) */
 192         int ppt_store;
 193         /** ppmbug1 */
 194         int ppt_len;
 195         /** add fixed_quality */
 196         float distoratio[100];
 197         /** tile-component coding parameters */
 198         opj_tccp_t *tccps;
 199 } opj_tcp_t;
 200
 201 /**
 202 Coding parameters
 203 */
 204 typedef struct opj_cp {
 205         /** Digital cinema profile*/
 206         OPJ_CINEMA_MODE cinema;
 207         /** Maximum rate for each component. If == 0, component size limitation is not considered */
 208         int max_comp_size;
 209         /** Size of the image in bits*/
 210         int img_size;
 211         /** Rsiz*/
 212         OPJ_RSIZ_CAPABILITIES rsiz;
 213         /** Enabling Tile part generation*/
 214         char tp_on;
 215         /** Flag determining tile part generation*/
 216         char tp_flag;
 217         /** Position of tile part flag in progression order*/
 218         int tp_pos;
 219         /** allocation by rate/distortion */
 220         int disto_alloc;
 221         /** allocation by fixed layer */
 222         int fixed_alloc;
 223         /** add fixed_quality */
 224         int fixed_quality;
 225         /** if != 0, then original dimension divided by 2^(reduce); if == 0 or not used, image is decoded to the full resolution */
 226         int reduce;
 227         /** if != 0, then only the first "layer" layers are decoded; if == 0 or not used, all the quality layers are decoded */
 228         int layer;
 229         /** if == NO_LIMITATION, decode entire codestream; if == LIMIT_TO_MAIN_HEADER then only decode the main header */
 230         OPJ_LIMIT_DECODING limit_decoding;
 231         /** XTOsiz */
 232         int tx0;
 233         /** YTOsiz */
 234         int ty0;
 235         /** XTsiz */
 236         int tdx;
 237         /** YTsiz */
 238         int tdy;
 239         /** comment for coding */
 240         char *comment;
 241         /** number of tiles in width */
 242         int tw;
 243         /** number of tiles in heigth */
 244         int th;
 245         /** ID number of the tiles present in the codestream */
 246         int *tileno;
 247         /** size of the vector tileno */
 248         int tileno_size;
 249         /** packet header store there for futur use in t2_decode_packet */
 250         unsigned char *ppm_data;
 251         /** pointer remaining on the first byte of the first header if ppm is used */
 252         unsigned char *ppm_data_first;
 253         /** if ppm == 1 --> there was a PPM marker for the present tile */
 254         int ppm;
 255         /** use in case of multiple marker PPM (number of info already store) */
 256         int ppm_store;
 257         /** use in case of multiple marker PPM (case on non-finished previous info) */
 258         int ppm_previous;
 259         /** ppmbug1 */
 260         int ppm_len;
 261         /** tile coding parameters */
 262         opj_tcp_t *tcps;
 263         /** fixed layer */
 264         int *matrice;
 265 /* UniPG>> */
 266 #ifdef USE_JPWL
 267         /** enables writing of EPC in MH, thus activating JPWL */
 268         bool epc_on;
 269         /** enables writing of EPB, in case of activated JPWL */
 270         bool epb_on;
 271         /** enables writing of ESD, in case of activated JPWL */
 272         bool esd_on;
 273         /** enables writing of informative techniques of ESD, in case of activated JPWL */
 274         bool info_on;
 275         /** enables writing of RED, in case of activated JPWL */
 276         bool red_on;
 277         /** error protection method for MH (0,1,16,32,37-128) */
 278         int hprot_MH;
 279         /** tile number of header protection specification (>=0) */
 280         int hprot_TPH_tileno[JPWL_MAX_NO_TILESPECS];
 281         /** error protection methods for TPHs (0,1,16,32,37-128) */
 282         int hprot_TPH[JPWL_MAX_NO_TILESPECS];
 283         /** tile number of packet protection specification (>=0) */
 284         int pprot_tileno[JPWL_MAX_NO_PACKSPECS];
 285         /** packet number of packet protection specification (>=0) */
 286         int pprot_packno[JPWL_MAX_NO_PACKSPECS];
 287         /** error protection methods for packets (0,1,16,32,37-128) */
 288         int pprot[JPWL_MAX_NO_PACKSPECS];
 289         /** enables writing of ESD, (0/2/4 bytes) */
 290         int sens_size;
 291         /** sensitivity addressing size (0=auto/2/4 bytes) */
 292         int sens_addr;
 293         /** sensitivity range (0-3) */
 294         int sens_range;
 295         /** sensitivity method for MH (-1,0-7) */
 296         int sens_MH;
 297         /** tile number of sensitivity specification (>=0) */
 298         int sens_TPH_tileno[JPWL_MAX_NO_TILESPECS];
 299         /** sensitivity methods for TPHs (-1,0-7) */
 300         int sens_TPH[JPWL_MAX_NO_TILESPECS];
 301         /** enables JPWL correction at the decoder */
 302         bool correct;
 303         /** expected number of components at the decoder */
 304         int exp_comps;
 305         /** maximum number of tiles at the decoder */
 306         int max_tiles;
 307 #endif /* USE_JPWL */
 308 /* <<UniPG */
 309 } opj_cp_t;
 310
 311 /**
 312 JPEG-2000 codestream reader/writer
 313 */
 314 typedef struct opj_j2k {
 315         /** codec context */
 316         opj_common_ptr cinfo;
 317
 318         /** locate in which part of the codestream the decoder is (main header, tile header, end) */
 319         int state;
 320         /** number of the tile curently concern by coding/decoding */
 321         int curtileno;
 322         /** Tile part number*/
 323         int tp_num;
 324         /** Tilepart number currently coding*/
 325         int cur_tp_num;
 326         /** Total number of tileparts of the current tile*/
 327         int *cur_totnum_tp;
 328         /**
 329         locate the start position of the TLM marker
 330         after encoding the tilepart, a jump (in j2k_write_sod) is done to the TLM marker to store the value of its length.
 331         */
 332         int tlm_start;
 333         /** Total num of tile parts in whole image = num tiles* num tileparts in each tile*/
 334         /** used in TLMmarker*/
 335         int totnum_tp;
 336         /**
 337         locate the position of the end of the tile in the codestream,
 338         used to detect a truncated codestream (in j2k_read_sod)
 339         */
 340         unsigned char *eot;
 341         /**
 342         locate the start position of the SOT marker of the current coded tile:
 343         after encoding the tile, a jump (in j2k_write_sod) is done to the SOT marker to store the value of its length.
 344         */
 345         int sot_start;
 346         int sod_start;
 347         /**
 348         as the J2K-file is written in several parts during encoding,
 349         it enables to make the right correction in position return by cio_tell
 350         */
 351         int pos_correction;
 352         /** array used to store the data of each tile */
 353         unsigned char **tile_data;
 354         /** array used to store the length of each tile */
 355         int *tile_len;
 356         /**
 357         decompression only :
 358         store decoding parameters common to all tiles (information like COD, COC in main header)
 359         */
 360         opj_tcp_t *default_tcp;
 361         /** pointer to the encoded / decoded image */
 362         opj_image_t *image;
 363         /** pointer to the coding parameters */
 364         opj_cp_t *cp;
 365         /** helper used to write the index file */
 366         opj_codestream_info_t *cstr_info;
 367         /** pointer to the byte i/o stream */
 368         opj_cio_t *cio;
 369 } opj_j2k_t;
 370
 371 /** @name Exported functions */
 372 /*@{*/
 373 /* ----------------------------------------------------------------------- */
 374 /**
 375 Creates a J2K decompression structure
 376 @param cinfo Codec context info
 377 @return Returns a handle to a J2K decompressor if successful, returns NULL otherwise
 378 */
 379 opj_j2k_t* j2k_create_decompress(opj_common_ptr cinfo);
 380 /**
 381 Destroy a J2K decompressor handle
 382 @param j2k J2K decompressor handle to destroy
 383 */
 384 void j2k_destroy_decompress(opj_j2k_t *j2k);
 385 /**
 386 Setup the decoder decoding parameters using user parameters.
 387 Decoding parameters are returned in j2k->cp.
 388 @param j2k J2K decompressor handle
 389 @param parameters decompression parameters
 390 */
 391 void j2k_setup_decoder(opj_j2k_t *j2k, opj_dparameters_t *parameters);
 392 /**
 393 Decode an image from a JPEG-2000 codestream
 394 @param j2k J2K decompressor handle
 395 @param cio Input buffer stream
 396 @param cstr_info Codestream information structure if required, NULL otherwise
 397 @return Returns a decoded image if successful, returns NULL otherwise
 398 */
 399 opj_image_t* j2k_decode(opj_j2k_t *j2k, opj_cio_t *cio, opj_codestream_info_t *cstr_info);
 400 /**
 401 Decode an image form a JPT-stream (JPEG 2000, JPIP)
 402 @param j2k J2K decompressor handle
 403 @param cio Input buffer stream
 404 @param cstr_info Codestream information structure if required, NULL otherwise
 405 @return Returns a decoded image if successful, returns NULL otherwise
 406 */
 407 opj_image_t* j2k_decode_jpt_stream(opj_j2k_t *j2k, opj_cio_t *cio, opj_codestream_info_t *cstr_info);
 408 /**
 409 Creates a J2K compression structure
 410 @param cinfo Codec context info
 411 @return Returns a handle to a J2K compressor if successful, returns NULL otherwise
 412 */
 413 opj_j2k_t* j2k_create_compress(opj_common_ptr cinfo);
 414 /**
 415 Destroy a J2K compressor handle
 416 @param j2k J2K compressor handle to destroy
 417 */
 418 void j2k_destroy_compress(opj_j2k_t *j2k);
 419 /**
 420 Setup the encoder parameters using the current image and using user parameters.
 421 Coding parameters are returned in j2k->cp.
 422 @param j2k J2K compressor handle
 423 @param parameters compression parameters
 424 @param image input filled image
 425 */
 426 void j2k_setup_encoder(opj_j2k_t *j2k, opj_cparameters_t *parameters, opj_image_t *image);
 427 /**
 428 Converts an enum type progression order to string type
 429 */
 430 char *j2k_convert_progression_order(OPJ_PROG_ORDER prg_order);
 431 /**
 432 Encode an image into a JPEG-2000 codestream
 433 @param j2k J2K compressor handle
 434 @param cio Output buffer stream
 435 @param image Image to encode
 436 @param cstr_info Codestream information structure if required, NULL otherwise
 437 @return Returns true if successful, returns false otherwise
 438 */
 439 bool j2k_encode(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image, opj_codestream_info_t *cstr_info);
 440
 441 /* ----------------------------------------------------------------------- */
 442 /*@}*/
 443
 444 /*@}*/
 445
 446 #endif /* __J2K_H */