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

details vigra/imageinfo.hxx VIGRA

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