[ 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 Febuary 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, 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> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><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> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><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> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><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> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><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', '.gif',
141  '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
142  '.tif', '.tiff', '.xv', '.hdr'.
143  JPEG support requires libjpeg, PNG support requires libpng, and
144  TIFF support requires libtiff.
145  **/
146  VIGRA_EXPORT ImageExportInfo( const char * );
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', '.gif',
153  '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
154  '.tif', '.tiff', '.xv', '.hdr'.
155  JPEG support requires libjpeg, PNG support requires libpng, and
156  TIFF support requires libtiff.
157  **/
158  VIGRA_EXPORT ImageExportInfo & setFileName(const char * filename);
159  VIGRA_EXPORT const char * getFileName() const;
160 
161  /** Store image as given file type.
162 
163  This will override any type guessed
164  from the file name's extension. Recognized file types:
165 
166  <DL>
167  <DT>"BMP"<DD> Microsoft Windows bitmap image file.
168  <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
169  <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
170  compressed 24-bit color (only available if libjpeg is installed).
171  <DT>"PNG"<DD> Portable Network Graphic
172  (only available if libpng is installed).
173  <DT>"PBM"<DD> Portable bitmap format (black and white).
174  <DT>"PGM"<DD> Portable graymap format (gray scale).
175  <DT>"PNM"<DD> Portable anymap.
176  <DT>"PPM"<DD> Portable pixmap format (color).
177  <DT>"SUN"<DD> SUN Rasterfile.
178  <DT>"TIFF"<DD> Tagged Image File Format.
179  (only available if libtiff is installed.)
180  <DT>"VIFF"<DD> Khoros Visualization image file.
181  </DL>
182 
183  With the exception of TIFF, VIFF, PNG, and PNM all file types store
184  1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
185  pixel.
186 
187  PNG can store UInt8 and UInt16 values, and supports 1 and 3 channel
188  images. One additional alpha channel is also supported.
189 
190  PNM can store 1 and 3 channel images with UInt8, UInt16 and UInt32
191  values in each channel.
192 
193  TIFF and VIFF are aditionally able to store short and long
194  integers (2 or 4 bytes) and real values (32 bit float and
195  64 bit double) without conversion. So you will need to use
196  TIFF or VIFF if you need to store images with high
197  accuracy (the appropriate type to write is automatically
198  derived from the image type to be exported). However, many
199  other programs using TIFF (e.g. ImageMagick) have not
200  implemented support for those pixel types. So don't be
201  surprised if the generated TIFF is not readable in some
202  cases. If this happens, export the image as 'unsigned
203  char' or 'RGBValue<unsigned char>' by calling
204  \ref ImageExportInfo::setPixelType().
205 
206  Support to reading and writing ICC color profiles is
207  provided for TIFF, JPEG, and PNG images.
208  **/
209  VIGRA_EXPORT ImageExportInfo & setFileType( const char * );
210  VIGRA_EXPORT const char * getFileType() const;
211 
212  /** Set compression type.
213 
214  Recognized strings: "" (no compression), "LZW",
215  "RunLength", "1" ... "100". A number is interpreted as the
216  compression quality for JPEG compression. JPEG compression is
217  supported by the JPEG and TIFF formats. "LZW" is only available
218  if libtiff was installed with LZW enabled. By default, libtiff came
219  with LZW disabled due to Unisys patent enforcement. In this case,
220  VIGRA stores the image uncompressed.
221 
222  Valid Compression for TIFF files:
223  JPEG jpeg compression, call setQuality as well!
224  RLE runlength compression
225  LZW lzw compression
226  DEFLATE deflate compression
227  **/
228  VIGRA_EXPORT ImageExportInfo & setCompression( const char * );
229  VIGRA_EXPORT const char * getCompression() const;
230 
231  /** Set the pixel type of the image file. Possible values are:
232  <DL>
233  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
234  <DT>"INT16"<DD> 16-bit signed integer (short)
235  <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
236  <DT>"INT32"<DD> 32-bit signed integer (long)
237  <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
238  <DT>"FLOAT"<DD> 32-bit floating point (float)
239  <DT>"DOUBLE"<DD> 64-bit floating point (double)
240  </DL>
241 
242  <b>Usage:</b>
243 
244  \code
245  FImage img(w,h);
246 
247  // by default, float images are exported with pixeltype float
248  // when the target format support this type, i.e. is TIFF or VIFF.
249  exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
250 
251  // if this is not desired, force a different pixeltype
252  exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
253  \endcode
254  **/
255  VIGRA_EXPORT ImageExportInfo & setPixelType( const char * );
256 
257  /** Get the pixel type of the image. Possible values are:
258  <DL>
259  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
260  <DT>"INT16"<DD> 16-bit signed integer (short)
261  <DT>"INT32"<DD> 32-bit signed integer (long)
262  <DT>"FLOAT"<DD> 32-bit floating point (float)
263  <DT>"DOUBLE"<DD> 64-bit floating point (double)
264  </DL>
265  **/
266  VIGRA_EXPORT const char * getPixelType() const;
267 
268  VIGRA_EXPORT ImageExportInfo & setForcedRangeMapping(double fromMin, double fromMax,
269  double toMin, double toMax);
270  VIGRA_EXPORT bool hasForcedRangeMapping() const;
271  VIGRA_EXPORT double getFromMin() const;
272  VIGRA_EXPORT double getFromMax() const;
273  VIGRA_EXPORT double getToMin() const;
274  VIGRA_EXPORT double getToMax() const;
275 
276  /** Set the image resolution in horizontal direction
277  **/
278  VIGRA_EXPORT ImageExportInfo & setXResolution( float );
279  VIGRA_EXPORT float getXResolution() const;
280 
281  /** Set the image resolution in vertical direction
282  **/
283  VIGRA_EXPORT ImageExportInfo & setYResolution( float );
284  VIGRA_EXPORT float getYResolution() const;
285 
286  /** Set the position of the upper Left corner on a global
287  canvas.
288 
289  Currently only supported by TIFF and PNG files.
290 
291  The offset is encoded in the XPosition and YPosition TIFF tags.
292 
293  @param pos position of the upper left corner in pixels
294  (must be >= 0)
295  **/
296  VIGRA_EXPORT ImageExportInfo & setPosition(const Diff2D & pos);
297 
298  /** Get the position of the upper left corner on
299  a global canvas.
300  **/
301  VIGRA_EXPORT Diff2D getPosition() const;
302 
303  /**
304  ICC profiles (handled as raw data so far).
305  see getICCProfile()/setICCProfile()
306  **/
308 
309  /** Returns a reference to the ICC profile.
310  */
311  VIGRA_EXPORT const ICCProfile & getICCProfile() const;
312 
313  /** Sets the ICC profile.
314  ICC profiles are currently supported by TIFF, PNG and JPEG images.
315  (Otherwise, the profile data is silently ignored.)
316  **/
317  VIGRA_EXPORT ImageExportInfo & setICCProfile(const ICCProfile & profile);
318 
319  private:
320  std::string m_filename, m_filetype, m_pixeltype, m_comp;
321  float m_x_res, m_y_res;
322  Diff2D m_pos;
323  ICCProfile m_icc_profile;
324  double fromMin_, fromMax_, toMin_, toMax_;
325 };
326 
327 // return an encoder for a given ImageExportInfo object
328 VIGRA_EXPORT std::auto_ptr<Encoder> encoder( const ImageExportInfo & info );
329 
330 /********************************************************/
331 /* */
332 /* ImageImportInfo */
333 /* */
334 /********************************************************/
335 
336 /** \brief Argument object for the function importImage().
337 
338 See \ref importImage() for a usage example. This object must be
339 used to read an image from disk and enquire about its properties.
340 
341 <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
342 Namespace: vigra
343 **/
345 {
346  public:
347  enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
348 
349  /** Construct ImageImportInfo object.
350 
351  The image with the given filename is read into memory.
352  The file type will be determined by the first few bytes of the
353  file (magic number). Recognized file types:
354 
355  <DL>
356  <DT>"BMP"<DD> Microsoft Windows bitmap image file.
357  <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
358  (only available if libjpeg is installed).
359  <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
360  <DT>"PNG"<DD> Portable Network Graphics
361  (only available if libpng is installed).
362  <DT>"PBM"<DD> Portable bitmap format (black and white).
363  <DT>"PGM"<DD> Portable graymap format (gray scale).
364  <DT>"PNM"<DD> Portable anymap.
365  <DT>"PPM"<DD> Portable pixmap format (color).
366  <DT>"SUN"<DD> SUN Rasterfile.
367  <DT>"TIFF"<DD> Tagged Image File Format.
368  (only available if libtiff is installed.)
369  <DT>"VIFF"<DD> Khoros Visualization image file.
370  </DL>
371  **/
372  VIGRA_EXPORT ImageImportInfo( const char * );
373  VIGRA_EXPORT ~ImageImportInfo();
374 
375  VIGRA_EXPORT const char * getFileName() const;
376 
377  /** Get the file type of the image associated with this
378  info object.
379 
380  See ImageImportInfo::ImageImportInfo for a list of the
381  available file types.
382  **/
383  VIGRA_EXPORT const char * getFileType() const;
384 
385  /** Get width of the image.
386  **/
387  VIGRA_EXPORT int width() const;
388 
389  /** Get height of the image.
390  **/
391  VIGRA_EXPORT int height() const;
392 
393  /** Get the total number of bands in the image.
394  **/
395  VIGRA_EXPORT int numBands() const;
396 
397  /** Get the number of extra (non color) bands in the image.
398  ** Usually these are the alpha channels.
399  **/
400  VIGRA_EXPORT int numExtraBands() const;
401 
402  /** Get size of the image.
403  **/
404  VIGRA_EXPORT Size2D size() const;
405 
406  /** Get size of the image in a form compatible to MultiArray.
407  **/
408  VIGRA_EXPORT MultiArrayShape<2>::type shape() const;
409 
410  /** Returns true if the image is gray scale.
411  **/
412  VIGRA_EXPORT bool isGrayscale() const;
413 
414  /** Returns true if the image is colored (RGB).
415  **/
416  VIGRA_EXPORT bool isColor() const;
417 
418  /** Query the pixel type of the image.
419 
420  Possible values are:
421  <DL>
422  <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
423  <DT>"INT16"<DD> 16-bit signed integer (short)
424  <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
425  <DT>"INT32"<DD> 32-bit signed integer (long)
426  <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
427  <DT>"FLOAT"<DD> 32-bit floating point (float)
428  <DT>"DOUBLE"<DD> 64-bit floating point (double)
429  </DL>
430  **/
431  VIGRA_EXPORT const char * getPixelType() const;
432 
433  /** Query the pixel type of the image.
434 
435  Same as getPixelType(), but the result is returned as a
436  ImageImportInfo::PixelType enum. This is useful to implement
437  a switch() on the pixel type.
438 
439  Possible values are:
440  <DL>
441  <DT>UINT8<DD> 8-bit unsigned integer (unsigned char)
442  <DT>INT16<DD> 16-bit signed integer (short)
443  <DT>UINT16<DD> 16-bit unsigned integer (unsigned short)
444  <DT>INT32<DD> 32-bit signed integer (long)
445  <DT>UINT32<DD> 32-bit unsigned integer (unsigned long)
446  <DT>FLOAT<DD> 32-bit floating point (float)
447  <DT>DOUBLE<DD> 64-bit floating point (double)
448  </DL>
449  **/
450  VIGRA_EXPORT PixelType pixelType() const;
451 
452  /** Returns true if the image has 1 byte per pixel (gray) or
453  3 bytes per pixel (RGB).
454  **/
455  VIGRA_EXPORT bool isByte() const;
456 
457  /** Returns the layer offset of the current image, if there is one
458  **/
459  VIGRA_EXPORT Diff2D getPosition() const;
460 
461  /** Returns the image resolution in horizontal direction
462  **/
463  VIGRA_EXPORT float getXResolution() const;
464 
465  /** Returns the image resolution in vertical direction
466  **/
467  VIGRA_EXPORT float getYResolution() const;
468 
469  /**
470  ICC profiles (handled as raw data so far).
471  see getICCProfile()/setICCProfile()
472  **/
474 
475  /** Returns a reference to the ICC profile.
476 
477  Note: The reference will become invalid when the
478  ImageImportInfo object has been destroyed.
479  **/
480  VIGRA_EXPORT const ICCProfile & getICCProfile() const;
481 
482  private:
483  std::string m_filename, m_filetype, m_pixeltype;
484  int m_width, m_height, m_num_bands, m_num_extra_bands;
485  float m_x_res, m_y_res;
486  Diff2D m_pos;
487  ICCProfile m_icc_profile;
488 };
489 
490 // return a decoder for a given ImageImportInfo object
491 VIGRA_EXPORT std::auto_ptr<Decoder> decoder( const ImageImportInfo & info );
492 
493 //@}
494 
495 } // namespace vigra
496 
497 #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.7.1 (Wed Mar 12 2014)