[ 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.4.0, Dec 21 2005 )                                    */
    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 #ifndef VIGRA_IMAGEINFO_HXX
    00040 #define VIGRA_IMAGEINFO_HXX
    00041
    00042 #include <memory>
    00043 #include <string>
    00044 #include "vigra/utilities.hxx"
    00045 #include "vigra/codec.hxx"
    00046
    00047 namespace vigra
    00048 {
    00049 /** \addtogroup VigraImpex Image Import/Export Facilities
    00050
    00051     supports GIF, TIFF, JPEG, BMP, PNM (PBM, PGM, PPM), PNG, SunRaster, KHOROS-VIFF formats
    00052 **/
    00053 //@{
    00054
    00055     /** \brief List the image formats VIGRA can read and write.
    00056
    00057         This is useful for creating error messages if VIGRA encounters an
    00058         image format it doesn't recognize.
    00059
    00060         <b> Usage:</b>
    00061
    00062         <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00063         Namespace: vigra
    00064
    00065         \code
    00066         std::cout << "supported formats: " << vigra::impexListFormats() << std::endl;
    00067         \endcode
    00068
    00069     **/
    00070 std::string impexListFormats();
    00071
    00072     /** \brief List the file extension VIGRA understands.
    00073
    00074         This is useful for creating file dialogs that only list image files
    00075         VIGRA can actually import.
    00076
    00077         <b> Usage:</b>
    00078
    00079         <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00080         Namespace: vigra
    00081
    00082         \code
    00083         std::cout << "supported extensions: " << vigra::impexListExtensions() << std::endl;
    00084         \endcode
    00085
    00086     **/
    00087 std::string impexListExtensions();
    00088
    00089 /** \brief Test whether a file is an image format known to VIGRA.
    00090
    00091     This checks the first few bytes of the file and compares them with the
    00092     "magic strings" of each recognized image format.
    00093
    00094     <b> Usage:</b>
    00095
    00096     <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00097     Namespace: vigra
    00098
    00099     \code
    00100     std::cout << "is image: " << vigra::isImage("foo.bmp") << std::endl;
    00101     \endcode
    00102
    00103 **/
    00104 bool isImage(char const * filename);
    00105
    00106 /********************************************************/
    00107 /*                                                      */
    00108 /*                   ImageExportInfo                    */
    00109 /*                                                      */
    00110 /********************************************************/
    00111
    00112 /** \brief Argument object for the function exportImage().
    00113     See \ref exportImage() for usage example. This object must be used
    00114     to define the properties of an image to be written to disk.
    00115
    00116     <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00117     Namespace: vigra
    00118 **/
    00119 class ImageExportInfo
    00120 {
    00121   public:
    00122         /** Construct ImageExportInfo object.
    00123
    00124             The image will be stored under the given filename.
    00125             The file type will be guessed from the extension unless overridden
    00126             by \ref setFileType(). Recognized extensions: '.bmp', '.gif',
    00127             '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
    00128             '.tif', '.tiff', '.xv'.
    00129             JPEG support requires libjpeg, PNG support requires libpng, and
    00130             TIFF support requires libtiff.
    00131         **/
    00132     ImageExportInfo( const char * );
    00133
    00134     const char * getFileName() const;
    00135
    00136     /** Store image as given file type.
    00137
    00138         This will override any type guessed
    00139         from the file name's extension. Recognized file types:
    00140
    00141         <DL>
    00142         <DT>"BMP"<DD> Microsoft Windows bitmap image file.
    00143         <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
    00144         <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
    00145         compressed 24-bit color (only available if libjpeg is installed).
    00146         <DT>"PNG"<DD> Portable Network Graphic
    00147         (only available if libpng is installed).
    00148         <DT>"PBM"<DD> Portable bitmap format (black and white).
    00149         <DT>"PGM"<DD> Portable graymap format (gray scale).
    00150         <DT>"PNM"<DD> Portable anymap.
    00151         <DT>"PPM"<DD> Portable pixmap format (color).
    00152         <DT>"SUN"<DD> SUN Rasterfile.
    00153         <DT>"TIFF"<DD> Tagged Image File Format.
    00154         (only available if libtiff is installed.)
    00155         <DT>"VIFF"<DD> Khoros Visualization image file.
    00156         </DL>
    00157
    00158         With the exception of TIFF and VIFF, all file types store
    00159         1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
    00160         pixel.
    00161
    00162         TIFF and VIFF are aditionally able to store short and long
    00163         integers (2 or 4 bytes) and real values (32 bit float and
    00164         64 bit double) without conversion. So you will need to use
    00165         TIFF or VIFF if you need to store images with high
    00166         accuracy (the appropriate type to write is automatically
    00167         derived from the image type to be exported). However, many
    00168         other programs using TIFF (e.g. ImageMagick) have not
    00169         implemented support for those pixel types.  So don't be
    00170         surprised if the generated TIFF is not readable in some
    00171         cases.  If this happens, export the image as 'unsigned
    00172         char' or 'RGBValue<unsigned char>' by calling
    00173         \ref ImageExportInfo::setPixelType().
    00174     **/
    00175     ImageExportInfo & setFileType( const char * );
    00176     const char * getFileType() const;
    00177
    00178     /** Set compression type.
    00179
    00180         Recognized strings: "" (no compression), "LZW",
    00181         "RunLength", "1" ... "100". A number is interpreted as the
    00182         compression quality for JPEG compression. JPEG compression is
    00183         supported by the JPEG and TIFF formats. "LZW" is only available
    00184         if libtiff was installed with LZW enabled. By default, libtiff comes
    00185         with LZW disabled due to Unisys patent enforcement. In this case,
    00186         VIGRA stores the image uncompressed.
    00187     **/
    00188     ImageExportInfo & setCompression( const char * );
    00189     const char * getCompression() const;
    00190
    00191     /** Set the pixel type of the image file. Possible values are:
    00192         <DL>
    00193         <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00194         <DT>"INT16"<DD> 16-bit signed integer (short)
    00195         <DT>"INT32"<DD> 32-bit signed integer (long)
    00196         <DT>"FLOAT"<DD> 32-bit floating point (float)
    00197         <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00198         </DL>
    00199
    00200         <b>Usage:</b>
    00201         FImage img(w,h);
    00202
    00203         // by default, float images are exported with pixeltype float
    00204         // when the target format support this type, i.e. is TIFF or VIFF.
    00205         exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
    00206
    00207         // if this is not desired, force a different pixeltype
    00208         exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
    00209     **/
    00210     ImageExportInfo & setPixelType( const char * );
    00211
    00212     /** Get the pixel type of the image. Possible values are:
    00213         <DL>
    00214         <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00215         <DT>"INT16"<DD> 16-bit signed integer (short)
    00216         <DT>"INT32"<DD> 32-bit signed integer (long)
    00217         <DT>"FLOAT"<DD> 32-bit floating point (float)
    00218         <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00219         </DL>
    00220     **/
    00221     const char * getPixelType() const;
    00222
    00223     /** Set the image resolution in horizontal direction
    00224     **/
    00225     ImageExportInfo & setXResolution( float );
    00226     float getXResolution() const;
    00227
    00228     /** Set the image resolution in vertical direction
    00229     **/
    00230     ImageExportInfo & setYResolution( float );
    00231     float getYResolution() const;
    00232
    00233   private:
    00234     std::string m_filename, m_filetype, m_pixeltype, m_comp;
    00235     float m_x_res, m_y_res;
    00236 };
    00237
    00238 // return an encoder for a given ImageExportInfo object
    00239 std::auto_ptr<Encoder> encoder( const ImageExportInfo & info );
    00240
    00241
    00242 /********************************************************/
    00243 /*                                                      */
    00244 /*                   ImageImportInfo                    */
    00245 /*                                                      */
    00246 /********************************************************/
    00247
    00248 /** \brief Argument object for the function importImage().
    00249 See \ref importImage() for a usage example. This object must be
    00250 used to read an image from disk and enquire about its properties.
    00251
    00252 <b>\#include</b> "<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>"<br>
    00253 Namespace: vigra
    00254 **/
    00255 class ImageImportInfo
    00256 {
    00257   public:
    00258     enum PixelType { UINT8, INT16, INT32, FLOAT, DOUBLE };
    00259
    00260         /** Construct ImageImportInfo object.
    00261
    00262             The image with the given filename is read into memory.
    00263             The file type will be determined by the first few bytes of the
    00264             file (magic number). Recognized file types:
    00265
    00266             <DL>
    00267             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
    00268             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
    00269             (only available if libjpeg is installed).
    00270             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
    00271             <DT>"PNG"<DD> Portable Network Graphics
    00272             (only available if libpng is installed).
    00273             <DT>"PBM"<DD> Portable bitmap format (black and white).
    00274             <DT>"PGM"<DD> Portable graymap format (gray scale).
    00275             <DT>"PNM"<DD> Portable anymap.
    00276             <DT>"PPM"<DD> Portable pixmap format (color).
    00277             <DT>"SUN"<DD> SUN Rasterfile.
    00278             <DT>"TIFF"<DD> Tagged Image File Format.
    00279             (only available if libtiff is installed.)
    00280             <DT>"VIFF"<DD> Khoros Visualization image file.
    00281             </DL>
    00282         **/
    00283     ImageImportInfo( const char *  );
    00284
    00285     const char * getFileName() const;
    00286
    00287         /** Get the file type of the image associated with this
    00288             info object.
    00289
    00290             See ImageImportInfo::ImageImportInfo for a list of the
    00291             available file types.
    00292         **/
    00293     const char * getFileType() const;
    00294
    00295         /** Get width of the image.
    00296          **/
    00297     int width() const;
    00298
    00299         /** Get height of the image.
    00300          **/
    00301     int height() const;
    00302
    00303         /** Get the number bands in the image.
    00304          **/
    00305     int numBands() const;
    00306
    00307         /** Get size of the image.
    00308          **/
    00309     Size2D size() const;
    00310
    00311         /** Returns true if the image is gray scale.
    00312          **/
    00313     bool isGrayscale() const;
    00314
    00315         /** Returns true if the image is colored (RGB).
    00316          **/
    00317     bool isColor() const;
    00318
    00319         /** Query the pixel type of the image.
    00320
    00321             Possible values are:
    00322             <DL>
    00323             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
    00324             <DT>"INT16"<DD> 16-bit signed integer (short)
    00325             <DT>"INT32"<DD> 32-bit signed integer (long)
    00326             <DT>"FLOAT"<DD> 32-bit floating point (float)
    00327             <DT>"DOUBLE"<DD> 64-bit floating point (double)
    00328             </DL>
    00329         **/
    00330     const char * getPixelType() const;
    00331
    00332         /// deprecated: use getPixelType()
    00333     PixelType pixelType() const;
    00334
    00335         /** Returns true if the image has 1 byte per pixel (gray) or
    00336             3 bytes per pixel (RGB).
    00337         **/
    00338     bool isByte() const;
    00339
    00340         /** Returns the image resolution in horizontal direction
    00341          **/
    00342     float getXResolution() const;
    00343
    00344         /** Returns the image resolution in vertical direction
    00345          **/
    00346     float getYResolution() const;
    00347
    00348   private:
    00349     std::string m_filename, m_filetype, m_pixeltype;
    00350     int m_width, m_height, m_num_bands;
    00351     float m_x_res, m_y_res;
    00352 };
    00353
    00354 // return a decoder for a given ImageImportInfo object
    00355 std::auto_ptr<vigra::Decoder> decoder( const ImageImportInfo & info );
    00356
    00357 } // namespace vigra
    00358
    00359 #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.4.0 (21 Dec 2005)