src/lib/openjp2/jp2.h

   1 /*
   2  * The copyright in this software is being made available under the 2-clauses
   3  * BSD License, included below. This software may be subject to other third
   4  * party and contributor rights, including patent rights, and no such rights
   5  * are granted under this license.
   6  *
   7  * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium
   8  * Copyright (c) 2002-2014, Professor Benoit Macq
   9  * Copyright (c) 2002-2003, Yannick Verschueren
  10  * Copyright (c) 2005, Herve Drolon, FreeImage Team
  11  * Copyright (c) 2008, 2011-2012, Centre National d'Etudes Spatiales (CNES), FR
  12  * Copyright (c) 2012, CS Systemes d'Information, France
  13  * All rights reserved.
  14  *
  15  * Redistribution and use in source and binary forms, with or without
  16  * modification, are permitted provided that the following conditions
  17  * are met:
  18  * 1. Redistributions of source code must retain the above copyright
  19  *    notice, this list of conditions and the following disclaimer.
  20  * 2. Redistributions in binary form must reproduce the above copyright
  21  *    notice, this list of conditions and the following disclaimer in the
  22  *    documentation and/or other materials provided with the distribution.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  25  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  28  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34  * POSSIBILITY OF SUCH DAMAGE.
  35  */
  36 #ifndef OPJ_JP2_H
  37 #define OPJ_JP2_H
  38 /**
  39 @file jp2.h
  40 @brief The JPEG-2000 file format Reader/Writer (JP2)
  41
  42 */
  43
  44 /** @defgroup JP2 JP2 - JPEG-2000 file format reader/writer */
  45 /*@{*/
  46
  47 /*#define JPIP_JPIP 0x6a706970*/
  48
  49 #define     JP2_JP   0x6a502020    /**< JPEG 2000 signature box */
  50 #define     JP2_FTYP 0x66747970    /**< File type box */
  51 #define     JP2_JP2H 0x6a703268    /**< JP2 header box (super-box) */
  52 #define     JP2_IHDR 0x69686472    /**< Image header box */
  53 #define     JP2_COLR 0x636f6c72    /**< Colour specification box */
  54 #define     JP2_JP2C 0x6a703263    /**< Contiguous codestream box */
  55 #define     JP2_URL  0x75726c20    /**< Data entry URL box */
  56 #define     JP2_PCLR 0x70636c72    /**< Palette box */
  57 #define     JP2_CMAP 0x636d6170    /**< Component Mapping box */
  58 #define     JP2_CDEF 0x63646566    /**< Channel Definition box */
  59 #define     JP2_DTBL 0x6474626c    /**< Data Reference box */
  60 #define     JP2_BPCC 0x62706363    /**< Bits per component box */
  61 #define     JP2_JP2  0x6a703220    /**< File type fields */
  62
  63 /* For the future */
  64 /* #define JP2_RES 0x72657320 */  /**< Resolution box (super-box) */
  65 /* #define JP2_JP2I 0x6a703269 */  /**< Intellectual property box */
  66 /* #define JP2_XML  0x786d6c20 */  /**< XML box */
  67 /* #define JP2_UUID 0x75756994 */  /**< UUID box */
  68 /* #define JP2_UINF 0x75696e66 */  /**< UUID info box (super-box) */
  69 /* #define JP2_ULST 0x756c7374 */  /**< UUID list box */
  70
  71 /* ----------------------------------------------------------------------- */
  72
  73 typedef enum {
  74     JP2_STATE_NONE            = 0x0,
  75     JP2_STATE_SIGNATURE       = 0x1,
  76     JP2_STATE_FILE_TYPE       = 0x2,
  77     JP2_STATE_HEADER          = 0x4,
  78     JP2_STATE_CODESTREAM      = 0x8,
  79     JP2_STATE_END_CODESTREAM  = 0x10,
  80     JP2_STATE_UNKNOWN         = 0x7fffffff /* ISO C restricts enumerator values to range of 'int' */
  81 }
  82 JP2_STATE;
  83
  84 typedef enum {
  85     JP2_IMG_STATE_NONE        = 0x0,
  86     JP2_IMG_STATE_UNKNOWN     = 0x7fffffff
  87 }
  88 JP2_IMG_STATE;
  89
  90 /**
  91 Channel description: channel index, type, association
  92 */
  93 typedef struct opj_jp2_cdef_info {
  94     OPJ_UINT16 cn, typ, asoc;
  95 } opj_jp2_cdef_info_t;
  96
  97 /**
  98 Channel descriptions and number of descriptions
  99 */
 100 typedef struct opj_jp2_cdef {
 101     opj_jp2_cdef_info_t *info;
 102     OPJ_UINT16 n;
 103 } opj_jp2_cdef_t;
 104
 105 /**
 106 Component mappings: channel index, mapping type, palette index
 107 */
 108 typedef struct opj_jp2_cmap_comp {
 109     OPJ_UINT16 cmp;
 110     OPJ_BYTE mtyp, pcol;
 111 } opj_jp2_cmap_comp_t;
 112
 113 /**
 114 Palette data: table entries, palette columns
 115 */
 116 typedef struct opj_jp2_pclr {
 117     OPJ_UINT32 *entries;
 118     OPJ_BYTE *channel_sign;
 119     OPJ_BYTE *channel_size;
 120     opj_jp2_cmap_comp_t *cmap;
 121     OPJ_UINT16 nr_entries;
 122     OPJ_BYTE nr_channels;
 123 } opj_jp2_pclr_t;
 124
 125 /**
 126 Collector for ICC profile, palette, component mapping, channel description
 127 */
 128 typedef struct opj_jp2_color {
 129     OPJ_BYTE *icc_profile_buf;
 130     OPJ_UINT32 icc_profile_len;
 131
 132     opj_jp2_cdef_t *jp2_cdef;
 133     opj_jp2_pclr_t *jp2_pclr;
 134     OPJ_BYTE jp2_has_colr;
 135 } opj_jp2_color_t;
 136
 137 /**
 138 JP2 component
 139 */
 140 typedef struct opj_jp2_comps {
 141     OPJ_UINT32 depth;
 142     OPJ_UINT32 sgnd;
 143     OPJ_UINT32 bpcc;
 144 } opj_jp2_comps_t;
 145
 146 /**
 147 JPEG-2000 file format reader/writer
 148 */
 149 typedef struct opj_jp2 {
 150     /** handle to the J2K codec  */
 151     opj_j2k_t *j2k;
 152     /** list of validation procedures */
 153     struct opj_procedure_list * m_validation_list;
 154     /** list of execution procedures */
 155     struct opj_procedure_list * m_procedure_list;
 156
 157     /* width of image */
 158     OPJ_UINT32 w;
 159     /* height of image */
 160     OPJ_UINT32 h;
 161     /* number of components in the image */
 162     OPJ_UINT32 numcomps;
 163     OPJ_UINT32 bpc;
 164     OPJ_UINT32 C;
 165     OPJ_UINT32 UnkC;
 166     OPJ_UINT32 IPR;
 167     OPJ_UINT32 meth;
 168     OPJ_UINT32 approx;
 169     OPJ_UINT32 enumcs;
 170     OPJ_UINT32 precedence;
 171     OPJ_UINT32 brand;
 172     OPJ_UINT32 minversion;
 173     OPJ_UINT32 numcl;
 174     OPJ_UINT32 *cl;
 175     opj_jp2_comps_t *comps;
 176     /* FIXME: The following two variables are used to save offset
 177       as we write out a JP2 file to disk. This mechanism is not flexible
 178       as codec writers will need to extand those fields as new part
 179       of the standard are implemented.
 180     */
 181     OPJ_OFF_T j2k_codestream_offset;
 182     OPJ_OFF_T jpip_iptr_offset;
 183     OPJ_BOOL jpip_on;
 184     OPJ_UINT32 jp2_state;
 185     OPJ_UINT32 jp2_img_state;
 186
 187     opj_jp2_color_t color;
 188
 189     OPJ_BOOL ignore_pclr_cmap_cdef;
 190     OPJ_BYTE has_jp2h;
 191     OPJ_BYTE has_ihdr;
 192 }
 193 opj_jp2_t;
 194
 195 /**
 196 JP2 Box
 197 */
 198 typedef struct opj_jp2_box {
 199     OPJ_UINT32 length;
 200     OPJ_UINT32 type;
 201     OPJ_INT32 init_pos;
 202 } opj_jp2_box_t;
 203
 204 typedef struct opj_jp2_header_handler {
 205     /* marker value */
 206     OPJ_UINT32 id;
 207     /* action linked to the marker */
 208     OPJ_BOOL(*handler)(opj_jp2_t *jp2,
 209                        OPJ_BYTE *p_header_data,
 210                        OPJ_UINT32 p_header_size,
 211                        opj_event_mgr_t * p_manager);
 212 }
 213 opj_jp2_header_handler_t;
 214
 215
 216 typedef struct opj_jp2_img_header_writer_handler {
 217     /* action to perform */
 218     OPJ_BYTE*   (*handler)(opj_jp2_t *jp2, OPJ_UINT32 * p_data_size);
 219     /* result of the action : data */
 220     OPJ_BYTE*   m_data;
 221     /* size of data */
 222     OPJ_UINT32  m_size;
 223 }
 224 opj_jp2_img_header_writer_handler_t;
 225
 226 /** @name Exported functions */
 227 /*@{*/
 228 /* ----------------------------------------------------------------------- */
 229
 230 /**
 231 Setup the decoder decoding parameters using user parameters.
 232 Decoding parameters are returned in jp2->j2k->cp.
 233 @param jp2 JP2 decompressor handle
 234 @param parameters decompression parameters
 235 */
 236 void opj_jp2_setup_decoder(opj_jp2_t *jp2, opj_dparameters_t *parameters);
 237
 238 /**
 239 Set the strict mode parameter.  When strict mode is enabled, the entire
 240 bitstream must be decoded or an error is returned.  When it is disabled,
 241 the decoder will decode partial bitstreams.
 242 @param jp2 JP2 decompressor handle
 243 @param strict OPJ_TRUE for strict mode
 244 */
 245 void opj_jp2_decoder_set_strict_mode(opj_jp2_t *jp2, OPJ_BOOL strict);
 246
 247 /** Allocates worker threads for the compressor/decompressor.
 248  *
 249  * @param jp2 JP2 decompressor handle
 250  * @param num_threads Number of threads.
 251  * @return OPJ_TRUE in case of success.
 252  */
 253 OPJ_BOOL opj_jp2_set_threads(opj_jp2_t *jp2, OPJ_UINT32 num_threads);
 254
 255 /**
 256  * Decode an image from a JPEG-2000 file stream
 257  * @param jp2 JP2 decompressor handle
 258  * @param p_stream  FIXME DOC
 259  * @param p_image   FIXME DOC
 260  * @param p_manager FIXME DOC
 261  *
 262  * @return Returns a decoded image if successful, returns NULL otherwise
 263 */
 264 OPJ_BOOL opj_jp2_decode(opj_jp2_t *jp2,
 265                         opj_stream_private_t *p_stream,
 266                         opj_image_t* p_image,
 267                         opj_event_mgr_t * p_manager);
 268
 269 /**
 270  * Setup the encoder parameters using the current image and using user parameters.
 271  * Coding parameters are returned in jp2->j2k->cp.
 272  *
 273  * @param jp2 JP2 compressor handle
 274  * @param parameters compression parameters
 275  * @param image input filled image
 276  * @param p_manager  FIXME DOC
 277  * @return OPJ_TRUE if successful, OPJ_FALSE otherwise
 278 */
 279 OPJ_BOOL opj_jp2_setup_encoder(opj_jp2_t *jp2,
 280                                opj_cparameters_t *parameters,
 281                                opj_image_t *image,
 282                                opj_event_mgr_t * p_manager);
 283
 284 /**
 285 Encode an image into a JPEG-2000 file stream
 286 @param jp2      JP2 compressor handle
 287 @param stream    Output buffer stream
 288 @param p_manager  event manager
 289 @return Returns true if successful, returns false otherwise
 290 */
 291 OPJ_BOOL opj_jp2_encode(opj_jp2_t *jp2,
 292                         opj_stream_private_t *stream,
 293                         opj_event_mgr_t * p_manager);
 294
 295
 296 /**
 297  * Starts a compression scheme, i.e. validates the codec parameters, writes the header.
 298  *
 299  * @param  jp2    the jpeg2000 file codec.
 300  * @param  stream    the stream object.
 301  * @param  p_image   FIXME DOC
 302  * @param p_manager FIXME DOC
 303  *
 304  * @return true if the codec is valid.
 305  */
 306 OPJ_BOOL opj_jp2_start_compress(opj_jp2_t *jp2,
 307                                 opj_stream_private_t *stream,
 308                                 opj_image_t * p_image,
 309                                 opj_event_mgr_t * p_manager);
 310
 311
 312 /**
 313  * Ends the compression procedures and possibiliy add data to be read after the
 314  * codestream.
 315  */
 316 OPJ_BOOL opj_jp2_end_compress(opj_jp2_t *jp2,
 317                               opj_stream_private_t *cio,
 318                               opj_event_mgr_t * p_manager);
 319
 320 /* ----------------------------------------------------------------------- */
 321
 322 /**
 323  * Ends the decompression procedures and possibiliy add data to be read after the
 324  * codestream.
 325  */
 326 OPJ_BOOL opj_jp2_end_decompress(opj_jp2_t *jp2,
 327                                 opj_stream_private_t *cio,
 328                                 opj_event_mgr_t * p_manager);
 329
 330 /**
 331  * Reads a jpeg2000 file header structure.
 332  *
 333  * @param p_stream the stream to read data from.
 334  * @param jp2 the jpeg2000 file header structure.
 335  * @param p_image   FIXME DOC
 336  * @param p_manager the user event manager.
 337  *
 338  * @return true if the box is valid.
 339  */
 340 OPJ_BOOL opj_jp2_read_header(opj_stream_private_t *p_stream,
 341                              opj_jp2_t *jp2,
 342                              opj_image_t ** p_image,
 343                              opj_event_mgr_t * p_manager);
 344
 345 /** Sets the indices of the components to decode.
 346  *
 347  * @param jp2 JP2 decompressor handle
 348  * @param numcomps Number of components to decode.
 349  * @param comps_indices Array of num_compts indices (numbering starting at 0)
 350  *                     corresponding to the components to decode.
 351  * @param p_manager Event manager;
 352  *
 353  * @return OPJ_TRUE in case of success.
 354  */
 355 OPJ_BOOL opj_jp2_set_decoded_components(opj_jp2_t *jp2,
 356                                         OPJ_UINT32 numcomps,
 357                                         const OPJ_UINT32* comps_indices,
 358                                         opj_event_mgr_t * p_manager);
 359
 360 /**
 361  * Reads a tile header.
 362  * @param  p_jp2         the jpeg2000 codec.
 363  * @param  p_tile_index  FIXME DOC
 364  * @param  p_data_size   FIXME DOC
 365  * @param  p_tile_x0     FIXME DOC
 366  * @param  p_tile_y0     FIXME DOC
 367  * @param  p_tile_x1     FIXME DOC
 368  * @param  p_tile_y1     FIXME DOC
 369  * @param  p_nb_comps    FIXME DOC
 370  * @param  p_go_on       FIXME DOC
 371  * @param  p_stream      the stream to write data to.
 372  * @param  p_manager     the user event manager.
 373  */
 374 OPJ_BOOL opj_jp2_read_tile_header(opj_jp2_t * p_jp2,
 375                                   OPJ_UINT32 * p_tile_index,
 376                                   OPJ_UINT32 * p_data_size,
 377                                   OPJ_INT32 * p_tile_x0,
 378                                   OPJ_INT32 * p_tile_y0,
 379                                   OPJ_INT32 * p_tile_x1,
 380                                   OPJ_INT32 * p_tile_y1,
 381                                   OPJ_UINT32 * p_nb_comps,
 382                                   OPJ_BOOL * p_go_on,
 383                                   opj_stream_private_t *p_stream,
 384                                   opj_event_mgr_t * p_manager);
 385
 386 /**
 387  * Writes a tile.
 388  *
 389  * @param  p_jp2    the jpeg2000 codec.
 390  * @param p_tile_index  FIXME DOC
 391  * @param p_data        FIXME DOC
 392  * @param p_data_size   FIXME DOC
 393  * @param  p_stream      the stream to write data to.
 394  * @param  p_manager  the user event manager.
 395  */
 396 OPJ_BOOL opj_jp2_write_tile(opj_jp2_t *p_jp2,
 397                             OPJ_UINT32 p_tile_index,
 398                             OPJ_BYTE * p_data,
 399                             OPJ_UINT32 p_data_size,
 400                             opj_stream_private_t *p_stream,
 401                             opj_event_mgr_t * p_manager);
 402
 403 /**
 404  * Decode tile data.
 405  * @param  p_jp2    the jpeg2000 codec.
 406  * @param  p_tile_index FIXME DOC
 407  * @param  p_data       FIXME DOC
 408  * @param  p_data_size  FIXME DOC
 409  * @param  p_stream      the stream to write data to.
 410  * @param  p_manager  the user event manager.
 411  *
 412  * @return FIXME DOC
 413  */
 414 OPJ_BOOL opj_jp2_decode_tile(opj_jp2_t * p_jp2,
 415                              OPJ_UINT32 p_tile_index,
 416                              OPJ_BYTE * p_data,
 417                              OPJ_UINT32 p_data_size,
 418                              opj_stream_private_t *p_stream,
 419                              opj_event_mgr_t * p_manager);
 420
 421 /**
 422  * Creates a jpeg2000 file decompressor.
 423  *
 424  * @return  an empty jpeg2000 file codec.
 425  */
 426 opj_jp2_t* opj_jp2_create(OPJ_BOOL p_is_decoder);
 427
 428 /**
 429 Destroy a JP2 decompressor handle
 430 @param jp2 JP2 decompressor handle to destroy
 431 */
 432 void opj_jp2_destroy(opj_jp2_t *jp2);
 433
 434
 435 /**
 436  * Sets the given area to be decoded. This function should be called right after opj_read_header and before any tile header reading.
 437  *
 438  * @param  p_jp2      the jpeg2000 codec.
 439  * @param  p_image     FIXME DOC
 440  * @param  p_start_x   the left position of the rectangle to decode (in image coordinates).
 441  * @param  p_start_y    the up position of the rectangle to decode (in image coordinates).
 442  * @param  p_end_x      the right position of the rectangle to decode (in image coordinates).
 443  * @param  p_end_y      the bottom position of the rectangle to decode (in image coordinates).
 444  * @param  p_manager    the user event manager
 445  *
 446  * @return  true      if the area could be set.
 447  */
 448 OPJ_BOOL opj_jp2_set_decode_area(opj_jp2_t *p_jp2,
 449                                  opj_image_t* p_image,
 450                                  OPJ_INT32 p_start_x, OPJ_INT32 p_start_y,
 451                                  OPJ_INT32 p_end_x, OPJ_INT32 p_end_y,
 452                                  opj_event_mgr_t * p_manager);
 453
 454 /**
 455 *
 456 */
 457 OPJ_BOOL opj_jp2_get_tile(opj_jp2_t *p_jp2,
 458                           opj_stream_private_t *p_stream,
 459                           opj_image_t* p_image,
 460                           opj_event_mgr_t * p_manager,
 461                           OPJ_UINT32 tile_index);
 462
 463
 464 /**
 465  *
 466  */
 467 OPJ_BOOL opj_jp2_set_decoded_resolution_factor(opj_jp2_t *p_jp2,
 468         OPJ_UINT32 res_factor,
 469         opj_event_mgr_t * p_manager);
 470
 471 /**
 472  * Specify extra options for the encoder.
 473  *
 474  * @param  p_jp2        the jpeg2000 codec.
 475  * @param  p_options    options
 476  * @param  p_manager    the user event manager
 477  *
 478  * @see opj_encoder_set_extra_options() for more details.
 479  */
 480 OPJ_BOOL opj_jp2_encoder_set_extra_options(
 481     opj_jp2_t *p_jp2,
 482     const char* const* p_options,
 483     opj_event_mgr_t * p_manager);
 484
 485
 486 /* TODO MSD: clean these 3 functions */
 487 /**
 488  * Dump some elements from the JP2 decompression structure .
 489  *
 490  *@param p_jp2        the jp2 codec.
 491  *@param flag        flag to describe what elements are dump.
 492  *@param out_stream      output stream where dump the elements.
 493  *
 494 */
 495 void jp2_dump(opj_jp2_t* p_jp2, OPJ_INT32 flag, FILE* out_stream);
 496
 497 /**
 498  * Get the codestream info from a JPEG2000 codec.
 499  *
 500  *@param  p_jp2        jp2 codec.
 501  *
 502  *@return  the codestream information extract from the jpg2000 codec
 503  */
 504 opj_codestream_info_v2_t* jp2_get_cstr_info(opj_jp2_t* p_jp2);
 505
 506 /**
 507  * Get the codestream index from a JPEG2000 codec.
 508  *
 509  *@param  p_jp2        jp2 codec.
 510  *
 511  *@return  the codestream index extract from the jpg2000 codec
 512  */
 513 opj_codestream_index_t* jp2_get_cstr_index(opj_jp2_t* p_jp2);
 514
 515
 516 /*@}*/
 517
 518 /*@}*/
 519
 520 #endif /* OPJ_JP2_H */
 521