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