VIGRA - VIGRA: vigra/imageinfo.hxx Source File

[ 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)