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

vigra/imageinfo.hxx
00001 /************************************************************************/
00002 /*                                                                      */
00003 /*               Copyright 1998-2001 by Ullrich Koethe                  */
00004 /*               Copyright 2001-2002 by Gunnar Kedenburg                */
00005 /*                                                                      */
00006 /*    This file is part of the VIGRA computer vision library.           */
00007 /*    The VIGRA Website is                                              */
00008 /*        http://hci.iwr.uni-heidelberg.de/vigra/                       */
00009 /*    Please direct questions, bug reports, and contributions to        */
00010 /*        ullrich.koethe@iwr.uni-heidelberg.de    or                    */
00011 /*        vigra@informatik.uni-hamburg.de                               */
00012 /*                                                                      */
00013 /*    Permission is hereby granted, free of charge, to any person       */
00014 /*    obtaining a copy of this software and associated documentation    */
00015 /*    files (the "Software"), to deal in the Software without           */
00016 /*    restriction, including without limitation the rights to use,      */
00017 /*    copy, modify, merge, publish, distribute, sublicense, and/or      */
00018 /*    sell copies of the Software, and to permit persons to whom the    */
00019 /*    Software is furnished to do so, subject to the following          */
00020 /*    conditions:                                                       */
00021 /*                                                                      */
00022 /*    The above copyright notice and this permission notice shall be    */
00023 /*    included in all copies or substantial portions of the             */
00024 /*    Software.                                                         */
00025 /*                                                                      */
00026 /*    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND    */
00027 /*    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES   */
00028 /*    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND          */
00029 /*    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT       */
00030 /*    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,      */
00031 /*    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      */
00032 /*    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR     */
00033 /*    OTHER DEALINGS IN THE SOFTWARE.                                   */
00034 /*                                                                      */
00035 /************************************************************************/
00036 
00037 /* Modifications by Pablo d'Angelo
00038  * updated to vigra 1.4 by Douglas Wilkins
00039  * as of 18 Febuary 2006:
00040  *  - Added UINT16 and UINT32 pixel types.
00041  *  - Added support for obtaining extra bands beyond RGB.
00042  *  - Added support for a position field that indicates the start of this
00043  *    image relative to some global origin.
00044  *  - Added support for x and y resolution fields.
00045  *  - Added support for ICC profiles
00046  */
00047 
00048 #ifndef VIGRA_IMAGEINFO_HXX
00049 #define VIGRA_IMAGEINFO_HXX
00050 
00051 #include <memory>
00052 #include <string>
00053 #include "config.hxx"
00054 #include "error.hxx"
00055 #include "diff2d.hxx"
00056 #include "codec.hxx"
00057 #include "array_vector.hxx"
00058 #include "multi_iterator.hxx"
00059 
00060 namespace vigra
00061 {
00062 /** \addtogroup VigraImpex Image Import/Export Facilities
00063 
00064     supports GIF, TIFF, JPEG, BMP, PNM (PBM, PGM, PPM), PNG, SunRaster, KHOROS-VIFF formats
00065 **/
00066 //@{
00067 
00068     /** \brief List the image formats VIGRA can read and write.
00069 
00070         This is useful for creating error messages if VIGRA encounters an
00071         image format it doesn't recognize.
00072 
00073         <b> Usage:</b>
00074 
00075         <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00076         Namespace: vigra
00077 
00078         \code
00079         std::cout << "supported formats: " << vigra::impexListFormats() << std::endl;
00080         \endcode
00081 
00082     **/
00083 VIGRA_EXPORT std::string impexListFormats();
00084 
00085     /** \brief List the file extension VIGRA understands.
00086 
00087         This is useful for creating file dialogs that only list image files
00088         VIGRA can actually import.
00089 
00090         <b> Usage:</b>
00091 
00092         <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00093         Namespace: vigra
00094 
00095         \code
00096         std::cout << "supported extensions: " << vigra::impexListExtensions() << std::endl;
00097         \endcode
00098 
00099     **/
00100 VIGRA_EXPORT std::string impexListExtensions();
00101 
00102 /** \brief Test whether a file is an image format known to VIGRA.
00103 
00104     This checks the first few bytes of the file and compares them with the
00105     "magic strings" of each recognized image format.
00106 
00107     <b> Usage:</b>
00108 
00109     <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00110     Namespace: vigra
00111 
00112     \code
00113     std::cout << "is image: " << vigra::isImage("foo.bmp") << std::endl;
00114     \endcode
00115 
00116 **/
00117 VIGRA_EXPORT bool isImage(char const * filename);
00118 
00119 /********************************************************/
00120 /*                                                      */
00121 /*                   ImageExportInfo                    */
00122 /*                                                      */
00123 /********************************************************/
00124 
00125 /** \brief Argument object for the function exportImage().
00126 
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         /** Set image file name.
00150         
00151             The file type will be guessed from the extension unless overridden
00152             by \ref setFileType(). Recognized extensions: '.bmp', '.gif',
00153             '.jpeg', '.jpg', '.p7', '.png', '.pbm', '.pgm', '.pnm', '.ppm', '.ras',
00154             '.tif', '.tiff', '.xv', '.hdr'.
00155             JPEG support requires libjpeg, PNG support requires libpng, and
00156             TIFF support requires libtiff.
00157          **/
00158     VIGRA_EXPORT ImageExportInfo & setFileName(const char * filename);
00159     VIGRA_EXPORT const char * getFileName() const;
00160 
00161         /** Store image as given file type.
00162 
00163             This will override any type guessed
00164             from the file name's extension. Recognized file types:
00165 
00166             <DL>
00167             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
00168             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
00169             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format;
00170             compressed 24-bit color (only available if libjpeg is installed).
00171             <DT>"PNG"<DD> Portable Network Graphic
00172             (only available if libpng is installed).
00173             <DT>"PBM"<DD> Portable bitmap format (black and white).
00174             <DT>"PGM"<DD> Portable graymap format (gray scale).
00175             <DT>"PNM"<DD> Portable anymap.
00176             <DT>"PPM"<DD> Portable pixmap format (color).
00177             <DT>"SUN"<DD> SUN Rasterfile.
00178             <DT>"TIFF"<DD> Tagged Image File Format.
00179             (only available if libtiff is installed.)
00180             <DT>"VIFF"<DD> Khoros Visualization image file.
00181             </DL>
00182 
00183             With the exception of TIFF, VIFF, PNG, and PNM all file types store
00184             1 byte (gray scale and mapped RGB) or 3 bytes (RGB) per
00185             pixel.
00186 
00187             PNG can store UInt8 and UInt16 values, and supports 1 and 3 channel
00188             images. One additional alpha channel is also supported.
00189 
00190             PNM can store 1 and 3 channel images with UInt8, UInt16 and UInt32
00191             values in each channel.
00192 
00193             TIFF and VIFF are aditionally able to store short and long
00194             integers (2 or 4 bytes) and real values (32 bit float and
00195             64 bit double) without conversion. So you will need to use
00196             TIFF or VIFF if you need to store images with high
00197             accuracy (the appropriate type to write is automatically
00198             derived from the image type to be exported). However, many
00199             other programs using TIFF (e.g. ImageMagick) have not
00200             implemented support for those pixel types.  So don't be
00201             surprised if the generated TIFF is not readable in some
00202             cases.  If this happens, export the image as 'unsigned
00203             char' or 'RGBValue<unsigned char>' by calling
00204             \ref ImageExportInfo::setPixelType().
00205 
00206             Support to reading and writing ICC color profiles is
00207             provided for TIFF, JPEG, and PNG images.
00208          **/
00209     VIGRA_EXPORT ImageExportInfo & setFileType( const char * );
00210     VIGRA_EXPORT const char * getFileType() const;
00211 
00212         /** Set compression type.
00213 
00214             Recognized strings: "" (no compression), "LZW",
00215             "RunLength", "1" ... "100". A number is interpreted as the
00216             compression quality for JPEG compression. JPEG compression is
00217             supported by the JPEG and TIFF formats. "LZW" is only available
00218             if libtiff was installed with LZW enabled. By default, libtiff came
00219             with LZW disabled due to Unisys patent enforcement. In this case,
00220             VIGRA stores the image uncompressed.
00221 
00222                 Valid Compression for TIFF files:
00223                   JPEG    jpeg compression, call setQuality as well!
00224                   RLE     runlength compression
00225                   LZW     lzw compression
00226                   DEFLATE deflate compression
00227          **/
00228     VIGRA_EXPORT ImageExportInfo & setCompression( const char * );
00229     VIGRA_EXPORT const char * getCompression() const;
00230 
00231         /** Set the pixel type of the image file. Possible values are:
00232             <DL>
00233             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00234             <DT>"INT16"<DD> 16-bit signed integer (short)
00235             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
00236             <DT>"INT32"<DD> 32-bit signed integer (long)
00237             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
00238             <DT>"FLOAT"<DD> 32-bit floating point (float)
00239             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00240             </DL>
00241 
00242             <b>Usage:</b>
00243             
00244             \code
00245             FImage img(w,h);
00246 
00247             // by default, float images are exported with pixeltype float
00248             // when the target format support this type, i.e. is TIFF or VIFF.
00249             exportImage(srcImageRange(img), ImageExportInfo("asFloat.tif"));
00250 
00251             // if this is not desired, force a different pixeltype
00252             exportImage(srcImageRange(img), ImageExportInfo("asByte.tif").setPixelType("UINT8"));
00253             \endcode
00254          **/
00255     VIGRA_EXPORT ImageExportInfo & setPixelType( const char * );
00256 
00257         /** Get the pixel type of the image. Possible values are:
00258             <DL>
00259             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00260             <DT>"INT16"<DD> 16-bit signed integer (short)
00261             <DT>"INT32"<DD> 32-bit signed integer (long)
00262             <DT>"FLOAT"<DD> 32-bit floating point (float)
00263             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00264             </DL>
00265          **/
00266     VIGRA_EXPORT const char * getPixelType() const;
00267     
00268     VIGRA_EXPORT ImageExportInfo & setForcedRangeMapping(double fromMin, double fromMax,
00269                                                      double toMin, double toMax);    
00270     VIGRA_EXPORT bool hasForcedRangeMapping() const;
00271     VIGRA_EXPORT double getFromMin() const;
00272     VIGRA_EXPORT double getFromMax() const;
00273     VIGRA_EXPORT double getToMin() const;
00274     VIGRA_EXPORT double getToMax() const;
00275     
00276         /** Set the image resolution in horizontal direction
00277          **/
00278     VIGRA_EXPORT ImageExportInfo & setXResolution( float );
00279     VIGRA_EXPORT float getXResolution() const;
00280 
00281         /** Set the image resolution in vertical direction
00282          **/
00283     VIGRA_EXPORT ImageExportInfo & setYResolution( float );
00284     VIGRA_EXPORT float getYResolution() const;
00285 
00286         /** Set the position of the upper Left corner on a global
00287             canvas.
00288 
00289             Currently only supported by TIFF and PNG files.
00290 
00291             The offset is encoded in the XPosition and YPosition TIFF tags.
00292 
00293             @param pos     position of the upper left corner in pixels
00294                            (must be >= 0)
00295          **/
00296     VIGRA_EXPORT ImageExportInfo & setPosition(const Diff2D & pos);
00297 
00298         /** Get the position of the upper left corner on
00299             a global canvas.
00300          **/
00301     VIGRA_EXPORT Diff2D getPosition() const;
00302 
00303         /**
00304           ICC profiles (handled as raw data so far).
00305           see getICCProfile()/setICCProfile()
00306          **/
00307     typedef ArrayVector<unsigned char> ICCProfile;
00308 
00309         /** Returns a reference to the ICC profile.
00310          */
00311     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
00312 
00313         /** Sets the ICC profile.
00314             ICC profiles are currently supported by TIFF, PNG and JPEG images.
00315             (Otherwise, the profile data is silently ignored.)
00316          **/
00317     VIGRA_EXPORT ImageExportInfo & setICCProfile(const ICCProfile & profile);
00318 
00319   private:
00320     std::string m_filename, m_filetype, m_pixeltype, m_comp;
00321     float m_x_res, m_y_res;
00322     Diff2D m_pos;
00323     ICCProfile m_icc_profile;
00324     double fromMin_, fromMax_, toMin_, toMax_;
00325 };
00326 
00327 // return an encoder for a given ImageExportInfo object
00328 VIGRA_EXPORT std::auto_ptr<Encoder> encoder( const ImageExportInfo & info );
00329 
00330 /********************************************************/
00331 /*                                                      */
00332 /*                   ImageImportInfo                    */
00333 /*                                                      */
00334 /********************************************************/
00335 
00336 /** \brief Argument object for the function importImage().
00337 
00338 See \ref importImage() for a usage example. This object must be
00339 used to read an image from disk and enquire about its properties.
00340 
00341 <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00342 Namespace: vigra
00343 **/
00344 class ImageImportInfo
00345 {
00346   public:
00347     enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
00348 
00349         /** Construct ImageImportInfo object.
00350 
00351             The image with the given filename is read into memory.
00352             The file type will be determined by the first few bytes of the
00353             file (magic number). Recognized file types:
00354 
00355             <DL>
00356             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
00357             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
00358             (only available if libjpeg is installed).
00359             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
00360             <DT>"PNG"<DD> Portable Network Graphics
00361             (only available if libpng is installed).
00362             <DT>"PBM"<DD> Portable bitmap format (black and white).
00363             <DT>"PGM"<DD> Portable graymap format (gray scale).
00364             <DT>"PNM"<DD> Portable anymap.
00365             <DT>"PPM"<DD> Portable pixmap format (color).
00366             <DT>"SUN"<DD> SUN Rasterfile.
00367             <DT>"TIFF"<DD> Tagged Image File Format.
00368             (only available if libtiff is installed.)
00369             <DT>"VIFF"<DD> Khoros Visualization image file.
00370             </DL>
00371          **/
00372     VIGRA_EXPORT ImageImportInfo( const char *  );
00373     VIGRA_EXPORT ~ImageImportInfo();
00374 
00375     VIGRA_EXPORT const char * getFileName() const;
00376 
00377         /** Get the file type of the image associated with this
00378             info object.
00379 
00380             See ImageImportInfo::ImageImportInfo for a list of the
00381             available file types.
00382          **/
00383     VIGRA_EXPORT const char * getFileType() const;
00384 
00385         /** Get width of the image.
00386          **/
00387     VIGRA_EXPORT int width() const;
00388 
00389         /** Get height of the image.
00390          **/
00391     VIGRA_EXPORT int height() const;
00392 
00393         /** Get the total number of bands in the image.
00394          **/
00395     VIGRA_EXPORT int numBands() const;
00396 
00397         /** Get the number of extra (non color) bands in the image.
00398          ** Usually these are the alpha channels.
00399          **/
00400     VIGRA_EXPORT int numExtraBands() const;
00401 
00402         /** Get size of the image.
00403          **/
00404     VIGRA_EXPORT Size2D size() const;
00405 
00406         /** Get size of the image in a form compatible to MultiArray.
00407          **/
00408     VIGRA_EXPORT MultiArrayShape<2>::type shape() const;
00409 
00410         /** Returns true if the image is gray scale.
00411          **/
00412     VIGRA_EXPORT bool isGrayscale() const;
00413 
00414         /** Returns true if the image is colored (RGB).
00415          **/
00416     VIGRA_EXPORT bool isColor() const;
00417 
00418         /** Query the pixel type of the image.
00419 
00420             Possible values are:
00421             <DL>
00422             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00423             <DT>"INT16"<DD> 16-bit signed integer (short)
00424             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
00425             <DT>"INT32"<DD> 32-bit signed integer (long)
00426             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
00427             <DT>"FLOAT"<DD> 32-bit floating point (float)
00428             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00429             </DL>
00430          **/
00431     VIGRA_EXPORT const char * getPixelType() const;
00432 
00433         /** Query the pixel type of the image.
00434 
00435             Same as getPixelType(), but the result is returned as a 
00436             ImageImportInfo::PixelType enum. This is useful to implement
00437             a switch() on the pixel type.
00438 
00439             Possible values are:
00440             <DL>
00441             <DT>UINT8<DD> 8-bit unsigned integer (unsigned char)
00442             <DT>INT16<DD> 16-bit signed integer (short)
00443             <DT>UINT16<DD> 16-bit unsigned integer (unsigned short)
00444             <DT>INT32<DD> 32-bit signed integer (long)
00445             <DT>UINT32<DD> 32-bit unsigned integer (unsigned long)
00446             <DT>FLOAT<DD> 32-bit floating point (float)
00447             <DT>DOUBLE<DD> 64-bit floating point (double)
00448             </DL>
00449          **/
00450     VIGRA_EXPORT PixelType pixelType() const;
00451 
00452         /** Returns true if the image has 1 byte per pixel (gray) or
00453             3 bytes per pixel (RGB).
00454          **/
00455     VIGRA_EXPORT bool isByte() const;
00456 
00457         /** Returns the layer offset of the current image, if there is one
00458          **/
00459     VIGRA_EXPORT Diff2D getPosition() const;
00460 
00461         /** Returns the image resolution in horizontal direction
00462          **/
00463     VIGRA_EXPORT float getXResolution() const;
00464 
00465         /** Returns the image resolution in vertical direction
00466          **/
00467     VIGRA_EXPORT float getYResolution() const;
00468 
00469         /**
00470           ICC profiles (handled as raw data so far).
00471           see getICCProfile()/setICCProfile()
00472          **/
00473     typedef ArrayVector<unsigned char> ICCProfile;
00474 
00475         /** Returns a reference to the ICC profile.
00476 
00477            Note: The reference will become invalid when the
00478            ImageImportInfo object has been destroyed.
00479          **/
00480     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
00481 
00482   private:
00483     std::string m_filename, m_filetype, m_pixeltype;
00484     int m_width, m_height, m_num_bands, m_num_extra_bands;
00485     float m_x_res, m_y_res;
00486     Diff2D m_pos;
00487     ICCProfile m_icc_profile;
00488 };
00489 
00490 // return a decoder for a given ImageImportInfo object
00491 VIGRA_EXPORT std::auto_ptr<Decoder> decoder( const ImageImportInfo & info );
00492 
00493 //@}
00494 
00495 } // namespace vigra
00496 
00497 #endif // VIGRA_IMAGEINFO_HXX

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de)
Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany

html generated using doxygen and Python
vigra 1.7.0 (Thu Aug 25 2011)