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

vigra/imageinfo.hxx

00001 /************************************************************************/
00002 /*                                                                      */
00003 /*               Copyright 1998-2001 by Ullrich Koethe                  */
00004 /*               Copyright 2001-2002 by Gunnar Kedenburg                */
00005 /*       Cognitive Systems Group, University of Hamburg, Germany        */
00006 /*                                                                      */
00007 /*    This file is part of the VIGRA computer vision library.           */
00008 /*    ( Version 1.6.0, Aug 13 2008 )                                    */
00009 /*    The VIGRA Website is                                              */
00010 /*        http://kogs-www.informatik.uni-hamburg.de/~koethe/vigra/      */
00011 /*    Please direct questions, bug reports, and contributions to        */
00012 /*        ullrich.koethe@iwr.uni-heidelberg.de    or                    */
00013 /*        vigra@informatik.uni-hamburg.de                               */
00014 /*                                                                      */
00015 /*    Permission is hereby granted, free of charge, to any person       */
00016 /*    obtaining a copy of this software and associated documentation    */
00017 /*    files (the "Software"), to deal in the Software without           */
00018 /*    restriction, including without limitation the rights to use,      */
00019 /*    copy, modify, merge, publish, distribute, sublicense, and/or      */
00020 /*    sell copies of the Software, and to permit persons to whom the    */
00021 /*    Software is furnished to do so, subject to the following          */
00022 /*    conditions:                                                       */
00023 /*                                                                      */
00024 /*    The above copyright notice and this permission notice shall be    */
00025 /*    included in all copies or substantial portions of the             */
00026 /*    Software.                                                         */
00027 /*                                                                      */
00028 /*    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND    */
00029 /*    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES   */
00030 /*    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND          */
00031 /*    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT       */
00032 /*    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,      */
00033 /*    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      */
00034 /*    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR     */
00035 /*    OTHER DEALINGS IN THE SOFTWARE.                                   */
00036 /*                                                                      */
00037 /************************************************************************/
00038 
00039 /* Modifications by Pablo d'Angelo
00040  * updated to vigra 1.4 by Douglas Wilkins
00041  * as of 18 Febuary 2006:
00042  *  - Added UINT16 and UINT32 pixel types.
00043  *  - Added support for obtaining extra bands beyond RGB.
00044  *  - Added support for a position field that indicates the start of this
00045  *    image relative to some global origin.
00046  *  - Added support for x and y resolution fields.
00047  *  - Added support for ICC profiles
00048  */
00049 
00050 #ifndef VIGRA_IMAGEINFO_HXX
00051 #define VIGRA_IMAGEINFO_HXX
00052 
00053 #include <memory>
00054 #include <string>
00055 #include "config.hxx"
00056 #include "error.hxx"
00057 #include "diff2d.hxx"
00058 #include "codec.hxx"
00059 #include "array_vector.hxx"
00060 
00061 namespace vigra
00062 {
00063 /** \addtogroup VigraImpex Image Import/Export Facilities
00064 
00065     supports GIF, TIFF, JPEG, BMP, PNM (PBM, PGM, PPM), PNG, SunRaster, KHOROS-VIFF formats
00066 **/
00067 //@{
00068 
00069     /** \brief List the image formats VIGRA can read and write.
00070 
00071         This is useful for creating error messages if VIGRA encounters an
00072         image format it doesn't recognize.
00073 
00074         <b> Usage:</b>
00075 
00076         <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00077         Namespace: vigra
00078 
00079         \code
00080         std::cout << "supported formats: " << vigra::impexListFormats() << std::endl;
00081         \endcode
00082 
00083     **/
00084 VIGRA_EXPORT std::string impexListFormats();
00085 
00086     /** \brief List the file extension VIGRA understands.
00087 
00088         This is useful for creating file dialogs that only list image files
00089         VIGRA can actually import.
00090 
00091         <b> Usage:</b>
00092 
00093         <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00094         Namespace: vigra
00095 
00096         \code
00097         std::cout << "supported extensions: " << vigra::impexListExtensions() << std::endl;
00098         \endcode
00099 
00100     **/
00101 VIGRA_EXPORT std::string impexListExtensions();
00102 
00103 /** \brief Test whether a file is an image format known to VIGRA.
00104 
00105     This checks the first few bytes of the file and compares them with the
00106     "magic strings" of each recognized image format.
00107 
00108     <b> Usage:</b>
00109 
00110     <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00111     Namespace: vigra
00112 
00113     \code
00114     std::cout << "is image: " << vigra::isImage("foo.bmp") << std::endl;
00115     \endcode
00116 
00117 **/
00118 VIGRA_EXPORT bool isImage(char const * filename);
00119 
00120 /********************************************************/
00121 /*                                                      */
00122 /*                   ImageExportInfo                    */
00123 /*                                                      */
00124 /********************************************************/
00125 
00126 /** \brief Argument object for the function exportImage().
00127 
00128     See \ref exportImage() for usage example. This object must be used
00129     to define the properties of an image to be written to disk.
00130 
00131     <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00132     Namespace: vigra
00133 **/
00134 class ImageExportInfo
00135 {
00136   public:
00137         /** Construct ImageExportInfo object.
00138 
00139             The image will be stored under the given filename.
00140             The file type will be guessed from the extension unless overridden
00141             by \ref setFileType(). Recognized extensions: '.bmp', '.gif',
00142             '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
00143             '.tif', '.tiff', '.xv', '.hdr'.
00144             JPEG support requires libjpeg, PNG support requires libpng, and
00145             TIFF support requires libtiff.
00146          **/
00147     VIGRA_EXPORT ImageExportInfo( const char * );
00148     VIGRA_EXPORT ~ImageExportInfo();
00149 
00150         /** Set image file name.
00151         
00152             The file type will be guessed from the extension unless overridden
00153             by \ref setFileType(). Recognized extensions: '.bmp', '.gif',
00154             '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
00155             '.tif', '.tiff', '.xv', '.hdr'.
00156             JPEG support requires libjpeg, PNG support requires libpng, and
00157             TIFF support requires libtiff.
00158          **/
00159     VIGRA_EXPORT ImageExportInfo & setFileName(const char * filename);
00160     VIGRA_EXPORT const char * getFileName() const;
00161 
00162         /** Store image as given file type.
00163 
00164             This will override any type guessed
00165             from the file name's extension. Recognized file types:
00166 
00167             <DL>
00168             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
00169             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
00170             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
00171             compressed 24-bit color (only available if libjpeg is installed).
00172             <DT>"PNG"<DD> Portable Network Graphic
00173             (only available if libpng is installed).
00174             <DT>"PBM"<DD> Portable bitmap format (black and white).
00175             <DT>"PGM"<DD> Portable graymap format (gray scale).
00176             <DT>"PNM"<DD> Portable anymap.
00177             <DT>"PPM"<DD> Portable pixmap format (color).
00178             <DT>"SUN"<DD> SUN Rasterfile.
00179             <DT>"TIFF"<DD> Tagged Image File Format.
00180             (only available if libtiff is installed.)
00181             <DT>"VIFF"<DD> Khoros Visualization image file.
00182             </DL>
00183 
00184             With the exception of TIFF, VIFF, PNG, and PNM all file types store
00185             1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
00186             pixel.
00187 
00188             PNG can store UInt8 and UInt16 values, and supports 1 and 3 channel
00189             images. One additional alpha channel is also supported.
00190 
00191             PNM can store 1 and 3 channel images with UInt8, UInt16 and UInt32
00192             values in each channel.
00193 
00194             TIFF and VIFF are aditionally able to store short and long
00195             integers (2 or 4 bytes) and real values (32 bit float and
00196             64 bit double) without conversion. So you will need to use
00197             TIFF or VIFF if you need to store images with high
00198             accuracy (the appropriate type to write is automatically
00199             derived from the image type to be exported). However, many
00200             other programs using TIFF (e.g. ImageMagick) have not
00201             implemented support for those pixel types.  So don't be
00202             surprised if the generated TIFF is not readable in some
00203             cases.  If this happens, export the image as 'unsigned
00204             char' or 'RGBValue<unsigned char>' by calling
00205             \ref ImageExportInfo::setPixelType().
00206 
00207             Support to reading and writing ICC color profiles is
00208             provided for TIFF, JPEG, and PNG images.
00209          **/
00210     VIGRA_EXPORT ImageExportInfo & setFileType( const char * );
00211     VIGRA_EXPORT const char * getFileType() const;
00212 
00213         /** Set compression type.
00214 
00215             Recognized strings: "" (no compression), "LZW",
00216             "RunLength", "1" ... "100". A number is interpreted as the
00217             compression quality for JPEG compression. JPEG compression is
00218             supported by the JPEG and TIFF formats. "LZW" is only available
00219             if libtiff was installed with LZW enabled. By default, libtiff came
00220             with LZW disabled due to Unisys patent enforcement. In this case,
00221             VIGRA stores the image uncompressed.
00222 
00223                 Valid Compression for TIFF files:
00224                   JPEG    jpeg compression, call setQuality as well!
00225                   RLE     runlength compression
00226                   LZW     lzw compression
00227                   DEFLATE deflate compression
00228          **/
00229     VIGRA_EXPORT ImageExportInfo & setCompression( const char * );
00230     VIGRA_EXPORT const char * getCompression() const;
00231 
00232         /** Set the pixel type of the image file. Possible values are:
00233             <DL>
00234             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00235             <DT>"INT16"<DD> 16-bit signed integer (short)
00236             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
00237             <DT>"INT32"<DD> 32-bit signed integer (long)
00238             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
00239             <DT>"FLOAT"<DD> 32-bit floating point (float)
00240             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00241             </DL>
00242 
00243             <b>Usage:</b>
00244             
00245             \code
00246             FImage img(w,h);
00247 
00248             // by default, float images are exported with pixeltype float
00249             // when the target format support this type, i.e. is TIFF or VIFF.
00250             exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
00251 
00252             // if this is not desired, force a different pixeltype
00253             exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
00254             \endcode
00255          **/
00256     VIGRA_EXPORT ImageExportInfo & setPixelType( const char * );
00257 
00258         /** Get the pixel type of the image. Possible values are:
00259             <DL>
00260             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00261             <DT>"INT16"<DD> 16-bit signed integer (short)
00262             <DT>"INT32"<DD> 32-bit signed integer (long)
00263             <DT>"FLOAT"<DD> 32-bit floating point (float)
00264             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00265             </DL>
00266          **/
00267     VIGRA_EXPORT const char * getPixelType() const;
00268     
00269     VIGRA_EXPORT ImageExportInfo & setForcedRangeMapping(double fromMin, double fromMax,
00270                                                      double toMin, double toMax);    
00271     VIGRA_EXPORT bool hasForcedRangeMapping() const;
00272     VIGRA_EXPORT double getFromMin() const;
00273     VIGRA_EXPORT double getFromMax() const;
00274     VIGRA_EXPORT double getToMin() const;
00275     VIGRA_EXPORT double getToMax() const;
00276     
00277         /** Set the image resolution in horizontal direction
00278          **/
00279     VIGRA_EXPORT ImageExportInfo & setXResolution( float );
00280     VIGRA_EXPORT float getXResolution() const;
00281 
00282         /** Set the image resolution in vertical direction
00283          **/
00284     VIGRA_EXPORT ImageExportInfo & setYResolution( float );
00285     VIGRA_EXPORT float getYResolution() const;
00286 
00287         /** Set the position of the upper Left corner on a global
00288             canvas.
00289 
00290             Currently only supported by TIFF and PNG files.
00291 
00292             The offset is encoded in the XPosition and YPosition TIFF tags.
00293 
00294             @param pos     position of the upper left corner in pixels
00295                            (must be >= 0)
00296          **/
00297     VIGRA_EXPORT ImageExportInfo & setPosition(const Diff2D & pos);
00298 
00299         /** Get the position of the upper left corner on
00300             a global canvas.
00301          **/
00302     VIGRA_EXPORT Diff2D getPosition() const;
00303 
00304         /**
00305           ICC profiles (handled as raw data so far).
00306           see getICCProfile()/setICCProfile()
00307          **/
00308     typedef ArrayVector<unsigned char> ICCProfile;
00309 
00310         /** Returns a reference to the ICC profile.
00311          */
00312     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
00313 
00314         /** Sets the ICC profile.
00315             ICC profiles are currently supported by TIFF, PNG and JPEG images.
00316             (Otherwise, the profile data is silently ignored.)
00317          **/
00318     VIGRA_EXPORT ImageExportInfo & setICCProfile(const ICCProfile & profile);
00319 
00320   private:
00321     std::string m_filename, m_filetype, m_pixeltype, m_comp;
00322     float m_x_res, m_y_res;
00323     Diff2D m_pos;
00324     ICCProfile m_icc_profile;
00325     double fromMin_, fromMax_, toMin_, toMax_;
00326 };
00327 
00328 // return an encoder for a given ImageExportInfo object
00329 VIGRA_EXPORT std::auto_ptr<Encoder> encoder( const ImageExportInfo & info );
00330 
00331 
00332 /********************************************************/
00333 /*                                                      */
00334 /*                   ImageImportInfo                    */
00335 /*                                                      */
00336 /********************************************************/
00337 
00338 /** \brief Argument object for the function importImage().
00339 
00340 See \ref importImage() for a usage example. This object must be
00341 used to read an image from disk and enquire about its properties.
00342 
00343 <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00344 Namespace: vigra
00345 **/
00346 class ImageImportInfo
00347 {
00348   public:
00349     enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
00350 
00351         /** Construct ImageImportInfo object.
00352 
00353             The image with the given filename is read into memory.
00354             The file type will be determined by the first few bytes of the
00355             file (magic number). Recognized file types:
00356 
00357             <DL>
00358             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
00359             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
00360             (only available if libjpeg is installed).
00361             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
00362             <DT>"PNG"<DD> Portable Network Graphics
00363             (only available if libpng is installed).
00364             <DT>"PBM"<DD> Portable bitmap format (black and white).
00365             <DT>"PGM"<DD> Portable graymap format (gray scale).
00366             <DT>"PNM"<DD> Portable anymap.
00367             <DT>"PPM"<DD> Portable pixmap format (color).
00368             <DT>"SUN"<DD> SUN Rasterfile.
00369             <DT>"TIFF"<DD> Tagged Image File Format.
00370             (only available if libtiff is installed.)
00371             <DT>"VIFF"<DD> Khoros Visualization image file.
00372             </DL>
00373          **/
00374     VIGRA_EXPORT ImageImportInfo( const char *  );
00375     VIGRA_EXPORT ~ImageImportInfo();
00376 
00377     VIGRA_EXPORT const char * getFileName() const;
00378 
00379         /** Get the file type of the image associated with this
00380             info object.
00381 
00382             See ImageImportInfo::ImageImportInfo for a list of the
00383             available file types.
00384          **/
00385     VIGRA_EXPORT const char * getFileType() const;
00386 
00387         /** Get width of the image.
00388          **/
00389     VIGRA_EXPORT int width() const;
00390 
00391         /** Get height of the image.
00392          **/
00393     VIGRA_EXPORT int height() const;
00394 
00395         /** Get the total number of bands in the image.
00396          **/
00397     VIGRA_EXPORT int numBands() const;
00398 
00399         /** Get the number of extra (non color) bands in the image.
00400          ** Usually these are the alpha channels.
00401          **/
00402     VIGRA_EXPORT int numExtraBands() const;
00403 
00404         /** Get size of the image.
00405          **/
00406     VIGRA_EXPORT Size2D size() const;
00407 
00408         /** Returns true if the image is gray scale.
00409          **/
00410     VIGRA_EXPORT bool isGrayscale() const;
00411 
00412         /** Returns true if the image is colored (RGB).
00413          **/
00414     VIGRA_EXPORT bool isColor() const;
00415 
00416         /** Query the pixel type of the image.
00417 
00418             Possible values are:
00419             <DL>
00420             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00421             <DT>"INT16"<DD> 16-bit signed integer (short)
00422             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
00423             <DT>"INT32"<DD> 32-bit signed integer (long)
00424             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
00425             <DT>"FLOAT"<DD> 32-bit floating point (float)
00426             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00427             </DL>
00428          **/
00429     VIGRA_EXPORT const char * getPixelType() const;
00430 
00431         /// deprecated: use getPixelType()
00432     VIGRA_EXPORT PixelType pixelType() const;
00433 
00434         /** Returns true if the image has 1 byte per pixel (gray) or
00435             3 bytes per pixel (RGB).
00436          **/
00437     VIGRA_EXPORT bool isByte() const;
00438 
00439         /** Returns the layer offset of the current image, if there is one
00440          **/
00441     VIGRA_EXPORT Diff2D getPosition() const;
00442 
00443         /** Returns the image resolution in horizontal direction
00444          **/
00445     VIGRA_EXPORT float getXResolution() const;
00446 
00447         /** Returns the image resolution in vertical direction
00448          **/
00449     VIGRA_EXPORT float getYResolution() const;
00450 
00451         /**
00452           ICC profiles (handled as raw data so far).
00453           see getICCProfile()/setICCProfile()
00454          **/
00455     typedef ArrayVector<unsigned char> ICCProfile;
00456 
00457         /** Returns a reference to the ICC profile.
00458 
00459            Note: The reference will become invalid when the
00460            ImageImportInfo object has been destroyed.
00461          **/
00462     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
00463 
00464   private:
00465     std::string m_filename, m_filetype, m_pixeltype;
00466     int m_width, m_height, m_num_bands, m_num_extra_bands;
00467     float m_x_res, m_y_res;
00468     Diff2D m_pos;
00469     ICCProfile m_icc_profile;
00470 };
00471 
00472 // return a decoder for a given ImageImportInfo object
00473 VIGRA_EXPORT std::auto_ptr<Decoder> decoder( const ImageImportInfo & info );
00474 
00475 //@}
00476 
00477 } // namespace vigra
00478 
00479 #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.6.0 (13 Aug 2008)