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