[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

imageinfo.hxx
1 /************************************************************************/
2 /* */
3 /* Copyright 1998-2001 by Ullrich Koethe */
4 /* Copyright 2001-2002 by Gunnar Kedenburg */
5 /* */
6 /* This file is part of the VIGRA computer vision library. */
7 /* The VIGRA Website is */
8 /* http://hci.iwr.uni-heidelberg.de/vigra/ */
9 /* Please direct questions, bug reports, and contributions to */
10 /* ullrich.koethe@iwr.uni-heidelberg.de or */
11 /* vigra@informatik.uni-hamburg.de */
12 /* */
13 /* Permission is hereby granted, free of charge, to any person */
14 /* obtaining a copy of this software and associated documentation */
15 /* files (the "Software"), to deal in the Software without */
16 /* restriction, including without limitation the rights to use, */
17 /* copy, modify, merge, publish, distribute, sublicense, and/or */
18 /* sell copies of the Software, and to permit persons to whom the */
19 /* Software is furnished to do so, subject to the following */
20 /* conditions: */
21 /* */
22 /* The above copyright notice and this permission notice shall be */
23 /* included in all copies or substantial portions of the */
24 /* Software. */
25 /* */
26 /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND */
27 /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES */
28 /* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND */
29 /* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT */
30 /* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, */
31 /* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING */
32 /* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR */
33 /* OTHER DEALINGS IN THE SOFTWARE. */
34 /* */
35 /************************************************************************/
36 
37 /* Modifications by Pablo d'Angelo
38  * updated to vigra 1.4 by Douglas Wilkins
39  * as of 18 February 2006:
40  * - Added UINT16 and UINT32 pixel types.
41  * - Added support for obtaining extra bands beyond RGB.
42  * - Added support for a position field that indicates the start of this
43  * image relative to some global origin.
44  * - Added support for x and y resolution fields.
45  * - Added support for ICC profiles
46  */
47 
48 #ifndef VIGRA_IMAGEINFO_HXX
49 #define VIGRA_IMAGEINFO_HXX
50 
51 #include <memory>
52 #include <string>
53 #include "config.hxx"
54 #include "error.hxx"
55 #include "diff2d.hxx"
56 #include "codec.hxx"
57 #include "array_vector.hxx"
58 #include "multi_iterator.hxx"
59 
60 namespace vigra
61 {
62 /** \addtogroup VigraImpex Image Import/Export Facilities
63 
64  supports GIF, TIFF, JPEG, BMP, EXR, HDR, PNM (PBM, PGM, PPM), PNG, SunRaster, KHOROS-VIFF formats
65 **/
66 //@{
67 
68  /** \brief List the image formats VIGRA can read and write.
69 
70  This is useful for creating error messages if VIGRA encounters an
71  image format it doesn't recognize.
72 
73  <b> Usage:</b>
74 
75  <b>\#include</b> <vigra/imageinfo.hxx><br>
76  Namespace: vigra
77 
78  \code
79  std::cout << "supported formats: " << vigra::impexListFormats() << std::endl;
80  \endcode
81 
82  **/
83 VIGRA_EXPORT std::string impexListFormats();
84 
85  /** \brief List the file extension VIGRA understands.
86 
87  This is useful for creating file dialogs that only list image files
88  VIGRA can actually import.
89 
90  <b> Usage:</b>
91 
92  <b>\#include</b> <vigra/imageinfo.hxx><br>
93  Namespace: vigra
94 
95  \code
96  std::cout << "supported extensions: " << vigra::impexListExtensions() << std::endl;
97  \endcode
98 
99  **/
100 VIGRA_EXPORT std::string impexListExtensions();
101 
102 /** \brief Test whether a file is an image format known to VIGRA.
103 
104  This checks the first few bytes of the file and compares them with the
105  "magic strings" of each recognized image format.
106 
107  <b> Usage:</b>
108 
109  <b>\#include</b> <vigra/imageinfo.hxx><br>
110  Namespace: vigra
111 
112  \code
113  std::cout << "is image: " << vigra::isImage("foo.bmp") << std::endl;
114  \endcode
115 
116 **/
117 VIGRA_EXPORT bool isImage(char const * filename);
118 
119 /********************************************************/
120 /* */
121 /* ImageExportInfo */
122 /* */
123 /********************************************************/
124 
125 /** \brief Argument object for the function exportImage().
126 
127  See \ref exportImage() for usage example. This object must be used
128  to define the properties of an image to be written to disk.
129 
130  <b>\#include</b> <vigra/imageinfo.hxx><br>
131  Namespace: vigra
132 **/
134 {
135  public:
136  /** Construct ImageExportInfo object.
137 
138  The image will be stored under the given filename.
139  The file type will be guessed from the extension unless overridden
140  by \ref setFileType(). Recognized extensions: '.bmp', '.exr', '.gif',
141  '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
142  '.tif', '.tiff', '.xv', '.hdr'.
143  EXR support requires libopenexr, JPEG support requires libjpeg,
144  PNG support requires libpng and TIFF support requires libtiff.
145  **/
146  VIGRA_EXPORT ImageExportInfo( const char *, const char * = "w" );
147  VIGRA_EXPORT ~ImageExportInfo();
148 
149  /** Set image file name.
150 
151  The file type will be guessed from the extension unless overridden
152  by \ref setFileType(). Recognized extensions: '.bmp', '.exr', '.gif',
153  '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
154  '.tif', '.tiff', '.xv', '.hdr'.
155  EXR support requires libopenexr, JPEG support requires libjpeg,
156  PNG support requires libpng and TIFF support requires libtiff.
157  **/
158  VIGRA_EXPORT ImageExportInfo & setFileName(const char * filename);
159  VIGRA_EXPORT const char * getFileName() const;
160 
161  /** Return the image file opening mode.
162  **/
163  VIGRA_EXPORT const char * getMode() const;
164 
165  /** Store image as given file type.
166 
167  This will override any type guessed
168  from the file name's extension. Recognized file types:
169 
170  <DL>
171  <DT>"BMP"<DD> Microsoft Windows bitmap image file.
172  <DT>"EXR"<DD> OpenEXR high dynamic range image format.
173  (only available if libopenexr is installed)
174  <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
175  <DT>"HDR"<DD> Radiance RGBE high dynamic range image format.
176  <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
177  compressed 24-bit color (only available if libjpeg is installed).
178  <DT>"PNG"<DD> Portable Network Graphic
179  (only available if libpng is installed).
180  <DT>"PBM"<DD> Portable bitmap format (black and white).
181  <DT>"PGM"<DD> Portable graymap format (gray scale).
182  <DT>"PNM"<DD> Portable anymap.
183  <DT>"PPM"<DD> Portable pixmap format (color).
184  <DT>"SUN"<DD> SUN Rasterfile.
185  <DT>"TIFF"<DD> Tagged Image File Format.
186  (only available if libtiff is installed.)
187  <DT>"VIFF"<DD> Khoros Visualization image file.
188  </DL>
189 
190  With the exception of TIFF, VIFF, PNG, and PNM all file types store
191  1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
192  pixel.
193 
194  PNG can store UInt8 and UInt16 values, and supports 1 and 3 channel
195  images. One additional alpha channel is also supported.
196 
197  PNM can store 1 and 3 channel images with UInt8, UInt16 and UInt32
198  values in each channel.
199 
200  TIFF and VIFF are additionally able to store short and long
201  integers (2 or 4 bytes) and real values (32 bit float and
202  64 bit double) without conversion. So you will need to use
203  TIFF or VIFF if you need to store images with high
204  accuracy (the appropriate type to write is automatically
205  derived from the image type to be exported). However, many
206  other programs using TIFF (e.g. ImageMagick) have not
207  implemented support for those pixel types. So don't be
208  surprised if the generated TIFF is not readable in some
209  cases. If this happens, export the image as 'unsigned
210  char' or 'RGBValue<unsigned char>' by calling
211  \ref ImageExportInfo::setPixelType().
212 
213  Support to reading and writing ICC color profiles is
214  provided for TIFF, JPEG, and PNG images.
215  **/
216  VIGRA_EXPORT ImageExportInfo & setFileType( const char * );
217  VIGRA_EXPORT const char * getFileType() const;
218 
219  /** Set compression type and quality.
220 
221  This option is ignored when the target file format doesn't recognize
222  the compression type. Valid arguments:
223 
224  <DL>
225  <DT>"NONE"<DD> (recognized by EXR and TIFF): do not compress (many other formats don't
226  compress either, but it is not an option for them).
227  <DT>"JPEG"<DD> (recognized by JPEG and TIFF): use JPEG compression.
228  You can also specify a compression quality parameter by
229  passing "JPEG QUALITY=N", where "N" must be an integer between 1 and 100
230  (e.g. "JPEG QUALITY=70").
231  <DT>"JPEG-ARITH"<DD> (recognized by new versions of JPEG): use arithmetic coding as a back-end
232  after JPEG compression (by default, the back-end is Huffman coding).
233  You can also specify a compression quality parameter by
234  passing "JPEG-ARITH QUALITY=N", where "N" must be an integer between 1 and 100
235  (e.g. "JPEG-ARITH QUALITY=70").
236  <DT>"RLE", "RunLength"<DD> (recognized by EXR and TIFF): use run-length encoding. (BMP also
237  uses run-length encoding, but there it is not an option).
238  <DT>"PACKBITS"<DD> (recognized by TIFF): use packbits encoding (a variant of RLE).
239  <DT>"DEFLATE"<DD> (recognized by TIFF): use deflate encoding, as defined in zlib (PNG also
240  uses deflate, but there it is not an option).
241  <DT>"LZW"<DD> (recognized by TIFF): use Lempel-Ziv-Welch encoding.
242  <DT>"ZIP"<DD> (recognized by EXR): use zip-style encoding.
243  <DT>"PIZ"<DD> (recognized by EXR): use wavelet encoding.
244  <DT>"PXR24"<DD> (recognized by EXR): reduce to 24-bit, then use zip-style encoding.
245  <DT>"B44", "B44A"<DD> (recognized by EXR): see OpenEXR documentation.
246  <DT>"ASCII"<DD> (recognized by PNM): store pixels as ASCII (human readable numbers).
247  <DT>"RAW"<DD> (recognized by PNM): store pixels as uncompressed binary data.
248  <DT>"BILEVEL"<DD> (recognized by PNM): store as one bit per pixel.
249  <DT>"1" ... "100"<DD> deprecated (equivalent to <tt>setCompression("JPEG QUALITY=number")</tt>
250  where the number denotes the desired quality).
251  </DL>
252 
253  Some of these options (e.g. "JPEG-ARITH", "LZW", "B44", "B44A") may only be available when
254  they have been enabled in the corresponding third-party library.
255  **/
256  VIGRA_EXPORT ImageExportInfo & setCompression( const char * type);
257 
258  VIGRA_EXPORT const char * getCompression() const;
259 
260  /** Set the pixel type of the image file. Possible values are:
261  <DL>
262  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
263  <DT>"INT16"<DD> 16-bit signed integer (short)
264  <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
265  <DT>"INT32"<DD> 32-bit signed integer (long)
266  <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
267  <DT>"FLOAT"<DD> 32-bit floating point (float)
268  <DT>"DOUBLE"<DD> 64-bit floating point (double)
269  </DL>
270 
271  <b>Usage:</b>
272 
273  \code
274  FImage img(w,h);
275 
276  // by default, float images are exported with pixeltype float
277  // when the target format support this type, i.e. is TIFF or VIFF.
278  exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
279 
280  // if this is not desired, force a different pixeltype
281  exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
282  \endcode
283  **/
284  VIGRA_EXPORT ImageExportInfo & setPixelType( const char * );
285 
286  /** Get the pixel type of the image. Possible values are:
287  <DL>
288  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
289  <DT>"INT16"<DD> 16-bit signed integer (short)
290  <DT>"INT32"<DD> 32-bit signed integer (long)
291  <DT>"FLOAT"<DD> 32-bit floating point (float)
292  <DT>"DOUBLE"<DD> 64-bit floating point (double)
293  </DL>
294  **/
295  VIGRA_EXPORT const char * getPixelType() const;
296 
297  VIGRA_EXPORT ImageExportInfo & setForcedRangeMapping(double fromMin, double fromMax,
298  double toMin, double toMax);
299  VIGRA_EXPORT bool hasForcedRangeMapping() const;
300  VIGRA_EXPORT double getFromMin() const;
301  VIGRA_EXPORT double getFromMax() const;
302  VIGRA_EXPORT double getToMin() const;
303  VIGRA_EXPORT double getToMax() const;
304 
305  /** Set the image resolution in horizontal direction
306  **/
307  VIGRA_EXPORT ImageExportInfo & setXResolution( float );
308  VIGRA_EXPORT float getXResolution() const;
309 
310  /** Set the image resolution in vertical direction
311  **/
312  VIGRA_EXPORT ImageExportInfo & setYResolution( float );
313  VIGRA_EXPORT float getYResolution() const;
314 
315  /** Set the position of the upper Left corner on a global
316  canvas.
317 
318  Currently only supported by TIFF, PNG and OpenEXR files.
319 
320  The offset is encoded in the XPosition and YPosition TIFF tags.
321 
322  @param pos position of the upper left corner in pixels
323  (must be >= 0)
324  **/
325  VIGRA_EXPORT ImageExportInfo & setPosition(const Diff2D & pos);
326 
327  /** Get the position of the upper left corner on
328  a global canvas.
329  **/
330  VIGRA_EXPORT Diff2D getPosition() const;
331 
332  /** Get the size of the canvas, on which the image is positioned at
333  getPosition()
334  **/
335  VIGRA_EXPORT Size2D getCanvasSize() const;
336 
337  /** Get the size of the canvas, on which the image is positioned at
338  getPosition()
339  **/
340  VIGRA_EXPORT ImageExportInfo & setCanvasSize(const Size2D & size);
341 
342  /**
343  ICC profiles (handled as raw data so far).
344  see getICCProfile()/setICCProfile()
345  **/
347 
348  /** Returns a reference to the ICC profile.
349  */
350  VIGRA_EXPORT const ICCProfile & getICCProfile() const;
351 
352  /** Sets the ICC profile.
353  ICC profiles are currently supported by TIFF, PNG and JPEG images.
354  (Otherwise, the profile data is silently ignored.)
355  **/
356  VIGRA_EXPORT ImageExportInfo & setICCProfile(const ICCProfile & profile);
357 
358  private:
359  std::string m_filename, m_filetype, m_pixeltype, m_comp, m_mode;
360  float m_x_res, m_y_res;
361  Diff2D m_pos;
362  ICCProfile m_icc_profile;
363  Size2D m_canvas_size;
364  double fromMin_, fromMax_, toMin_, toMax_;
365 };
366 
367 // return an encoder for a given ImageExportInfo object
368 VIGRA_EXPORT VIGRA_UNIQUE_PTR<Encoder> encoder( const ImageExportInfo & info );
369 
370 /********************************************************/
371 /* */
372 /* ImageImportInfo */
373 /* */
374 /********************************************************/
375 
376 /** \brief Argument object for the function importImage().
377 
378 See \ref importImage() for a usage example. This object must be
379 used to read an image from disk and enquire about its properties.
380 
381 <b>\#include</b> <vigra/imageinfo.hxx><br>
382 Namespace: vigra
383 **/
385 {
386  public:
387  enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
388 
389  /** Construct ImageImportInfo object.
390 
391  The image with the given filename is read into memory.
392  The file type will be determined by the first few bytes of the
393  file (magic number). Recognized file types:
394 
395  <DL>
396  <DT>"BMP"<DD> Microsoft Windows bitmap image file.
397  <DT>"EXR"<DD> OpenEXR high dynamic range image format.
398  (only available if libopenexr is installed)
399  <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
400  <DT>"HDR"<DD> Radiance RGBE high dynamic range image format.
401  <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
402  compressed 24-bit color (only available if libjpeg is installed).
403  <DT>"PNG"<DD> Portable Network Graphic
404  (only available if libpng is installed).
405  <DT>"PBM"<DD> Portable bitmap format (black and white).
406  <DT>"PGM"<DD> Portable graymap format (gray scale).
407  <DT>"PNM"<DD> Portable anymap.
408  <DT>"PPM"<DD> Portable pixmap format (color).
409  <DT>"SUN"<DD> SUN Rasterfile.
410  <DT>"TIFF"<DD> Tagged Image File Format.
411  (only available if libtiff is installed.)
412  <DT>"VIFF"<DD> Khoros Visualization image file.
413  </DL>
414  **/
415  VIGRA_EXPORT ImageImportInfo( const char *, unsigned int = 0 );
416  VIGRA_EXPORT ~ImageImportInfo();
417 
418  VIGRA_EXPORT const char * getFileName() const;
419 
420  /** Get the file type of the image associated with this
421  info object.
422 
423  See ImageImportInfo::ImageImportInfo for a list of the
424  available file types.
425  **/
426  VIGRA_EXPORT const char * getFileType() const;
427 
428  /** Get width of the image.
429  **/
430  VIGRA_EXPORT int width() const;
431 
432  /** Get height of the image.
433  **/
434  VIGRA_EXPORT int height() const;
435 
436  /** Get the total number of bands in the image.
437  **/
438  VIGRA_EXPORT int numBands() const;
439 
440  /** Get the number of extra (non color) bands in the image.
441  ** Usually these are the alpha channels.
442  **/
443  VIGRA_EXPORT int numExtraBands() const;
444 
445  /** Get the number of images contained in the image file.
446  **/
447  VIGRA_EXPORT int numImages() const;
448 
449  /** Sets the index of the image to import from the image file.
450  **/
451  VIGRA_EXPORT void setImageIndex(const int);
452 
453  /** Gets the index of the image to import from the image file.
454  **/
455  VIGRA_EXPORT int getImageIndex() const;
456 
457  /** Get size of the image.
458  **/
459  VIGRA_EXPORT Size2D size() const;
460 
461  /** Get size of the image in a form compatible to MultiArray.
462  **/
463  VIGRA_EXPORT MultiArrayShape<2>::type shape() const;
464 
465  /** Returns true if the image is gray scale.
466  **/
467  VIGRA_EXPORT bool isGrayscale() const;
468 
469  /** Returns true if the image is colored (RGB).
470  **/
471  VIGRA_EXPORT bool isColor() const;
472 
473  /** Query the pixel type of the image.
474 
475  Possible values are:
476  <DL>
477  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
478  <DT>"INT16"<DD> 16-bit signed integer (short)
479  <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
480  <DT>"INT32"<DD> 32-bit signed integer (long)
481  <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
482  <DT>"FLOAT"<DD> 32-bit floating point (float)
483  <DT>"DOUBLE"<DD> 64-bit floating point (double)
484  </DL>
485  **/
486  VIGRA_EXPORT const char * getPixelType() const;
487 
488  /** Query the pixel type of the image.
489 
490  Same as getPixelType(), but the result is returned as a
491  ImageImportInfo::PixelType enum. This is useful to implement
492  a switch() on the pixel type.
493 
494  Possible values are:
495  <DL>
496  <DT>UINT8<DD> 8-bit unsigned integer (unsigned char)
497  <DT>INT16<DD> 16-bit signed integer (short)
498  <DT>UINT16<DD> 16-bit unsigned integer (unsigned short)
499  <DT>INT32<DD> 32-bit signed integer (long)
500  <DT>UINT32<DD> 32-bit unsigned integer (unsigned long)
501  <DT>FLOAT<DD> 32-bit floating point (float)
502  <DT>DOUBLE<DD> 64-bit floating point (double)
503  </DL>
504  **/
505  VIGRA_EXPORT PixelType pixelType() const;
506 
507  /** Returns true if the image has 1 byte per pixel (gray) or
508  3 bytes per pixel (RGB).
509  **/
510  VIGRA_EXPORT bool isByte() const;
511 
512  /** Returns the layer offset of the current image, if there is one
513  **/
514  VIGRA_EXPORT Diff2D getPosition() const;
515 
516  /** Get the size of the canvas, on which the image is positioned at
517  getPosition()
518  **/
519  VIGRA_EXPORT Size2D getCanvasSize() const;
520 
521  /** Returns the image resolution in horizontal direction
522  **/
523  VIGRA_EXPORT float getXResolution() const;
524 
525  /** Returns the image resolution in vertical direction
526  **/
527  VIGRA_EXPORT float getYResolution() const;
528 
529  /**
530  ICC profiles (handled as raw data so far).
531  see getICCProfile()/setICCProfile()
532  **/
534 
535  /** Returns a reference to the ICC profile.
536 
537  Note: The reference will become invalid when the
538  ImageImportInfo object has been destroyed.
539  **/
540  VIGRA_EXPORT const ICCProfile & getICCProfile() const;
541 
542  private:
543  std::string m_filename, m_filetype, m_pixeltype;
544  int m_width, m_height, m_num_bands, m_num_extra_bands, m_num_images, m_image_index;
545  float m_x_res, m_y_res;
546  Diff2D m_pos;
547  Size2D m_canvas_size;
548  ICCProfile m_icc_profile;
549 
550  void readHeader_();
551 };
552 
553 // return a decoder for a given ImageImportInfo object
554 VIGRA_EXPORT VIGRA_UNIQUE_PTR<Decoder> decoder( const ImageImportInfo & info );
555 
556 //@}
557 
558 } // namespace vigra
559 
560 #endif // VIGRA_IMAGEINFO_HXX

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de)
Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany

html generated using doxygen and Python
vigra 1.9.0 (Wed Feb 27 2013)