VIGRA - vigra/imageinfo.hxx Source File

[ VIGRA Homepage | Class Index | Function Index | File Index | 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.5.0, Dec 07 2006 )                                    */
    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 /*        koethe@informatik.uni-hamburg.de          or                  */
    00013 /*        vigra@kogs1.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     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     VIGRA_EXPORT const char * getFileName() const;
    00150
    00151         /** Store image as given file type.
    00152
    00153             This will override any type guessed
    00154             from the file name's extension. Recognized file types:
    00155
    00156             <DL>
    00157             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
    00158             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
    00159             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
    00160             compressed 24-bit color (only available if libjpeg is installed).
    00161             <DT>"PNG"<DD> Portable Network Graphic
    00162             (only available if libpng is installed).
    00163             <DT>"PBM"<DD> Portable bitmap format (black and white).
    00164             <DT>"PGM"<DD> Portable graymap format (gray scale).
    00165             <DT>"PNM"<DD> Portable anymap.
    00166             <DT>"PPM"<DD> Portable pixmap format (color).
    00167             <DT>"SUN"<DD> SUN Rasterfile.
    00168             <DT>"TIFF"<DD> Tagged Image File Format.
    00169             (only available if libtiff is installed.)
    00170             <DT>"VIFF"<DD> Khoros Visualization image file.
    00171             </DL>
    00172
    00173             With the exception of TIFF, VIFF, PNG, and PNM all file types store
    00174             1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
    00175             pixel.
    00176
    00177             PNG can store UInt8 and UInt16 values, and supports 1 and 3 channel
    00178             images. One additional alpha channel is also supported.
    00179
    00180             PNM can store 1 and 3 channel images with UInt8, UInt16 and UInt32
    00181             values in each channel.
    00182
    00183             TIFF and VIFF are aditionally able to store short and long
    00184             integers (2 or 4 bytes) and real values (32 bit float and
    00185             64 bit double) without conversion. So you will need to use
    00186             TIFF or VIFF if you need to store images with high
    00187             accuracy (the appropriate type to write is automatically
    00188             derived from the image type to be exported). However, many
    00189             other programs using TIFF (e.g. ImageMagick) have not
    00190             implemented support for those pixel types.  So don't be
    00191             surprised if the generated TIFF is not readable in some
    00192             cases.  If this happens, export the image as 'unsigned
    00193             char' or 'RGBValue<unsigned char>' by calling
    00194             \ref ImageExportInfo::setPixelType().
    00195
    00196             Support to reading and writing ICC color profiles is
    00197             provided for TIFF, JPEG, and PNG images.
    00198          **/
    00199     VIGRA_EXPORT ImageExportInfo & setFileType( const char * );
    00200     VIGRA_EXPORT const char * getFileType() const;
    00201
    00202         /** Set compression type.
    00203
    00204             Recognized strings: "" (no compression), "LZW",
    00205             "RunLength", "1" ... "100". A number is interpreted as the
    00206             compression quality for JPEG compression. JPEG compression is
    00207             supported by the JPEG and TIFF formats. "LZW" is only available
    00208             if libtiff was installed with LZW enabled. By default, libtiff came
    00209             with LZW disabled due to Unisys patent enforcement. In this case,
    00210             VIGRA stores the image uncompressed.
    00211
    00212                 Valid Compression for TIFF files:
    00213                   JPEG    jpeg compression, call setQuality as well!
    00214                   RLE     runlength compression
    00215                   LZW     lzw compression
    00216                   DEFLATE deflate compression
    00217          **/
    00218     VIGRA_EXPORT ImageExportInfo & setCompression( const char * );
    00219     VIGRA_EXPORT const char * getCompression() const;
    00220
    00221         /** Set the pixel type of the image file. Possible values are:
    00222             <DL>
    00223             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00224             <DT>"INT16"<DD> 16-bit signed integer (short)
    00225             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
    00226             <DT>"INT32"<DD> 32-bit signed integer (long)
    00227             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
    00228             <DT>"FLOAT"<DD> 32-bit floating point (float)
    00229             <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00230             </DL>
    00231
    00232             <b>Usage:</b>
    00233             FImage img(w,h);
    00234
    00235             // by default, float images are exported with pixeltype float
    00236             // when the target format support this type, i.e. is TIFF or VIFF.
    00237             exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
    00238
    00239             // if this is not desired, force a different pixeltype
    00240             exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
    00241          **/
    00242     VIGRA_EXPORT ImageExportInfo & setPixelType( const char * );
    00243
    00244         /** Get the pixel type of the image. Possible values are:
    00245             <DL>
    00246             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00247             <DT>"INT16"<DD> 16-bit signed integer (short)
    00248             <DT>"INT32"<DD> 32-bit signed integer (long)
    00249             <DT>"FLOAT"<DD> 32-bit floating point (float)
    00250             <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00251             </DL>
    00252          **/
    00253     VIGRA_EXPORT const char * getPixelType() const;
    00254
    00255         /** Set the image resolution in horizontal direction
    00256          **/
    00257     VIGRA_EXPORT ImageExportInfo & setXResolution( float );
    00258     VIGRA_EXPORT float getXResolution() const;
    00259
    00260         /** Set the image resolution in vertical direction
    00261          **/
    00262     VIGRA_EXPORT ImageExportInfo & setYResolution( float );
    00263     VIGRA_EXPORT float getYResolution() const;
    00264
    00265         /** Set the position of the upper Left corner on a global
    00266             canvas.
    00267
    00268             Currently only supported by TIFF and PNG files.
    00269
    00270             The offset is encoded in the XPosition and YPosition TIFF tags.
    00271
    00272             @param position of the upper left corner in pixels
    00273                            must be >= 0
    00274          **/
    00275     VIGRA_EXPORT ImageExportInfo & setPosition(const Diff2D & pos);
    00276
    00277         /** Get the position of the upper left corner on
    00278             a global canvas.
    00279          **/
    00280     VIGRA_EXPORT Diff2D getPosition() const;
    00281
    00282         /**
    00283           ICC profiles (handled as raw data so far).
    00284           see getICCProfile()/setICCProfile()
    00285          **/
    00286     typedef ArrayVector<unsigned char> ICCProfile;
    00287
    00288         /** Returns a reference to the ICC profile.
    00289          */
    00290     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
    00291
    00292         /** Sets the ICC profile.
    00293             ICC profiles are currently supported by TIFF, PNG and JPEG images.
    00294             (Otherwise, the profile data is silently ignored.)
    00295          **/
    00296     VIGRA_EXPORT ImageExportInfo & setICCProfile(const ICCProfile & profile);
    00297
    00298   private:
    00299     std::string m_filename, m_filetype, m_pixeltype, m_comp;
    00300     float m_x_res, m_y_res;
    00301     Diff2D m_pos;
    00302     ICCProfile m_icc_profile;
    00303 };
    00304
    00305 // return an encoder for a given ImageExportInfo object
    00306 VIGRA_EXPORT std::auto_ptr<Encoder> encoder( const ImageExportInfo & info );
    00307
    00308
    00309 /********************************************************/
    00310 /*                                                      */
    00311 /*                   ImageImportInfo                    */
    00312 /*                                                      */
    00313 /********************************************************/
    00314
    00315 /** \brief Argument object for the function importImage().
    00316 See \ref importImage() for a usage example. This object must be
    00317 used to read an image from disk and enquire about its properties.
    00318
    00319 <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00320 Namespace: vigra
    00321 **/
    00322 class ImageImportInfo
    00323 {
    00324   public:
    00325     enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
    00326
    00327         /** Construct ImageImportInfo object.
    00328
    00329             The image with the given filename is read into memory.
    00330             The file type will be determined by the first few bytes of the
    00331             file (magic number). Recognized file types:
    00332
    00333             <DL>
    00334             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
    00335             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
    00336             (only available if libjpeg is installed).
    00337             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
    00338             <DT>"PNG"<DD> Portable Network Graphics
    00339             (only available if libpng is installed).
    00340             <DT>"PBM"<DD> Portable bitmap format (black and white).
    00341             <DT>"PGM"<DD> Portable graymap format (gray scale).
    00342             <DT>"PNM"<DD> Portable anymap.
    00343             <DT>"PPM"<DD> Portable pixmap format (color).
    00344             <DT>"SUN"<DD> SUN Rasterfile.
    00345             <DT>"TIFF"<DD> Tagged Image File Format.
    00346             (only available if libtiff is installed.)
    00347             <DT>"VIFF"<DD> Khoros Visualization image file.
    00348             </DL>
    00349          **/
    00350     VIGRA_EXPORT ImageImportInfo( const char *  );
    00351     VIGRA_EXPORT ~ImageImportInfo();
    00352
    00353     VIGRA_EXPORT const char * getFileName() const;
    00354
    00355         /** Get the file type of the image associated with this
    00356             info object.
    00357
    00358             See ImageImportInfo::ImageImportInfo for a list of the
    00359             available file types.
    00360          **/
    00361     VIGRA_EXPORT const char * getFileType() const;
    00362
    00363         /** Get width of the image.
    00364          **/
    00365     VIGRA_EXPORT int width() const;
    00366
    00367         /** Get height of the image.
    00368          **/
    00369     VIGRA_EXPORT int height() const;
    00370
    00371         /** Get the total number of bands in the image.
    00372          **/
    00373     VIGRA_EXPORT int numBands() const;
    00374
    00375         /** Get the number of extra (non color) bands in the image.
    00376          ** Usually these are the alpha channels.
    00377          **/
    00378     VIGRA_EXPORT int numExtraBands() const;
    00379
    00380         /** Get size of the image.
    00381          **/
    00382     VIGRA_EXPORT Size2D size() const;
    00383
    00384         /** Returns true if the image is gray scale.
    00385          **/
    00386     VIGRA_EXPORT bool isGrayscale() const;
    00387
    00388         /** Returns true if the image is colored (RGB).
    00389          **/
    00390     VIGRA_EXPORT bool isColor() const;
    00391
    00392         /** Query the pixel type of the image.
    00393
    00394             Possible values are:
    00395             <DL>
    00396             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00397             <DT>"INT16"<DD> 16-bit signed integer (short)
    00398             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
    00399             <DT>"INT32"<DD> 32-bit signed integer (long)
    00400             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
    00401             <DT>"FLOAT"<DD> 32-bit floating point (float)
    00402             <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00403             </DL>
    00404          **/
    00405     VIGRA_EXPORT const char * getPixelType() const;
    00406
    00407         /// deprecated: use getPixelType()
    00408     VIGRA_EXPORT PixelType pixelType() const;
    00409
    00410         /** Returns true if the image has 1 byte per pixel (gray) or
    00411             3 bytes per pixel (RGB).
    00412          **/
    00413     VIGRA_EXPORT bool isByte() const;
    00414
    00415         /** Returns the layer offset of the current image, if there is one
    00416          **/
    00417     VIGRA_EXPORT Diff2D getPosition() const;
    00418
    00419         /** Returns the image resolution in horizontal direction
    00420          **/
    00421     VIGRA_EXPORT float getXResolution() const;
    00422
    00423         /** Returns the image resolution in vertical direction
    00424          **/
    00425     VIGRA_EXPORT float getYResolution() const;
    00426
    00427         /**
    00428           ICC profiles (handled as raw data so far).
    00429           see getICCProfile()/setICCProfile()
    00430          **/
    00431     typedef ArrayVector<unsigned char> ICCProfile;
    00432
    00433         /** Returns a reference to the ICC profile.
    00434
    00435            Note: The reference will become invalid when the
    00436            ImageImportInfo object has been destroyed.
    00437          **/
    00438     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
    00439
    00440   private:
    00441     std::string m_filename, m_filetype, m_pixeltype;
    00442     int m_width, m_height, m_num_bands, m_num_extra_bands;
    00443     float m_x_res, m_y_res;
    00444     Diff2D m_pos;
    00445     ICCProfile m_icc_profile;
    00446 };
    00447
    00448 // return a decoder for a given ImageImportInfo object
    00449 VIGRA_EXPORT std::auto_ptr<Decoder> decoder( const ImageImportInfo & info );
    00450
    00451 } // namespace vigra
    00452
    00453 #endif // VIGRA_IMAGEINFO_HXX

© Ullrich Köthe (koethe@informatik.uni-hamburg.de) Cognitive Systems Group, University of Hamburg, Germany | html generated using doxygen and Python VIGRA 1.5.0 (7 Dec 2006)