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