[ 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 /*       Cognitive Systems Group, University of Hamburg, Germany        */
00006 /*                                                                      */
00007 /*    This file is part of the VIGRA computer vision library.           */
00008 /*    The VIGRA Website is                                              */
00009 /*        http://kogs-www.informatik.uni-hamburg.de/~koethe/vigra/      */
00010 /*    Please direct questions, bug reports, and contributions to        */
00011 /*        ullrich.koethe@iwr.uni-heidelberg.de    or                    */
00012 /*        vigra@informatik.uni-hamburg.de                               */
00013 /*                                                                      */
00014 /*    Permission is hereby granted, free of charge, to any person       */
00015 /*    obtaining a copy of this software and associated documentation    */
00016 /*    files (the "Software"), to deal in the Software without           */
00017 /*    restriction, including without limitation the rights to use,      */
00018 /*    copy, modify, merge, publish, distribute, sublicense, and/or      */
00019 /*    sell copies of the Software, and to permit persons to whom the    */
00020 /*    Software is furnished to do so, subject to the following          */
00021 /*    conditions:                                                       */
00022 /*                                                                      */
00023 /*    The above copyright notice and this permission notice shall be    */
00024 /*    included in all copies or substantial portions of the             */
00025 /*    Software.                                                         */
00026 /*                                                                      */
00027 /*    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND    */
00028 /*    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES   */
00029 /*    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND          */
00030 /*    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT       */
00031 /*    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,      */
00032 /*    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      */
00033 /*    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR     */
00034 /*    OTHER DEALINGS IN THE SOFTWARE.                                   */
00035 /*                                                                      */
00036 /************************************************************************/
00037 
00038 /* Modifications by Pablo d'Angelo
00039  * updated to vigra 1.4 by Douglas Wilkins
00040  * as of 18 Febuary 2006:
00041  *  - Added UINT16 and UINT32 pixel types.
00042  *  - Added support for obtaining extra bands beyond RGB.
00043  *  - Added support for a position field that indicates the start of this
00044  *    image relative to some global origin.
00045  *  - Added support for x and y resolution fields.
00046  *  - Added support for ICC profiles
00047  */
00048 
00049 #ifndef VIGRA_IMAGEINFO_HXX
00050 #define VIGRA_IMAGEINFO_HXX
00051 
00052 #include <memory>
00053 #include <string>
00054 #include "config.hxx"
00055 #include "error.hxx"
00056 #include "diff2d.hxx"
00057 #include "codec.hxx"
00058 #include "array_vector.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 /*                                                      */
00333 /*                   ImageImportInfo                    */
00334 /*                                                      */
00335 /********************************************************/
00336 
00337 /** \brief Argument object for the function importImage().
00338 
00339 See \ref importImage() for a usage example. This object must be
00340 used to read an image from disk and enquire about its properties.
00341 
00342 <b>\#include</b> <<a href="imageinfo_8hxx-source.html">vigra/imageinfo.hxx</a>><br>
00343 Namespace: vigra
00344 **/
00345 class ImageImportInfo
00346 {
00347   public:
00348     enum PixelType { UINT8, INT16, UINT16, INT32, UINT32, FLOAT, DOUBLE };
00349 
00350         /** Construct ImageImportInfo object.
00351 
00352             The image with the given filename is read into memory.
00353             The file type will be determined by the first few bytes of the
00354             file (magic number). Recognized file types:
00355 
00356             <DL>
00357             <DT>"BMP"<DD> Microsoft Windows bitmap image file.
00358             <DT>"JPEG"<DD> Joint Photographic Experts Group JFIF format
00359             (only available if libjpeg is installed).
00360             <DT>"GIF"<DD> CompuServe graphics interchange format; 8-bit color.
00361             <DT>"PNG"<DD> Portable Network Graphics
00362             (only available if libpng is installed).
00363             <DT>"PBM"<DD> Portable bitmap format (black and white).
00364             <DT>"PGM"<DD> Portable graymap format (gray scale).
00365             <DT>"PNM"<DD> Portable anymap.
00366             <DT>"PPM"<DD> Portable pixmap format (color).
00367             <DT>"SUN"<DD> SUN Rasterfile.
00368             <DT>"TIFF"<DD> Tagged Image File Format.
00369             (only available if libtiff is installed.)
00370             <DT>"VIFF"<DD> Khoros Visualization image file.
00371             </DL>
00372          **/
00373     VIGRA_EXPORT ImageImportInfo( const char *  );
00374     VIGRA_EXPORT ~ImageImportInfo();
00375 
00376     VIGRA_EXPORT const char * getFileName() const;
00377 
00378         /** Get the file type of the image associated with this
00379             info object.
00380 
00381             See ImageImportInfo::ImageImportInfo for a list of the
00382             available file types.
00383          **/
00384     VIGRA_EXPORT const char * getFileType() const;
00385 
00386         /** Get width of the image.
00387          **/
00388     VIGRA_EXPORT int width() const;
00389 
00390         /** Get height of the image.
00391          **/
00392     VIGRA_EXPORT int height() const;
00393 
00394         /** Get the total number of bands in the image.
00395          **/
00396     VIGRA_EXPORT int numBands() const;
00397 
00398         /** Get the number of extra (non color) bands in the image.
00399          ** Usually these are the alpha channels.
00400          **/
00401     VIGRA_EXPORT int numExtraBands() const;
00402 
00403         /** Get size of the image.
00404          **/
00405     VIGRA_EXPORT Size2D size() const;
00406 
00407         /** Returns true if the image is gray scale.
00408          **/
00409     VIGRA_EXPORT bool isGrayscale() const;
00410 
00411         /** Returns true if the image is colored (RGB).
00412          **/
00413     VIGRA_EXPORT bool isColor() const;
00414 
00415         /** Query the pixel type of the image.
00416 
00417             Possible values are:
00418             <DL>
00419             <DT>"UINT8"<DD> 8-bit unsigned integer (unsigned char)
00420             <DT>"INT16"<DD> 16-bit signed integer (short)
00421             <DT>"UINT16"<DD> 16-bit unsigned integer (unsigned short)
00422             <DT>"INT32"<DD> 32-bit signed integer (long)
00423             <DT>"UINT32"<DD> 32-bit unsigned integer (unsigned long)
00424             <DT>"FLOAT"<DD> 32-bit floating point (float)
00425             <DT>"DOUBLE"<DD> 64-bit floating point (double)
00426             </DL>
00427          **/
00428     VIGRA_EXPORT const char * getPixelType() const;
00429 
00430         /// deprecated: use getPixelType()
00431     VIGRA_EXPORT PixelType pixelType() const;
00432 
00433         /** Returns true if the image has 1 byte per pixel (gray) or
00434             3 bytes per pixel (RGB).
00435          **/
00436     VIGRA_EXPORT bool isByte() const;
00437 
00438         /** Returns the layer offset of the current image, if there is one
00439          **/
00440     VIGRA_EXPORT Diff2D getPosition() const;
00441 
00442         /** Returns the image resolution in horizontal direction
00443          **/
00444     VIGRA_EXPORT float getXResolution() const;
00445 
00446         /** Returns the image resolution in vertical direction
00447          **/
00448     VIGRA_EXPORT float getYResolution() const;
00449 
00450         /**
00451           ICC profiles (handled as raw data so far).
00452           see getICCProfile()/setICCProfile()
00453          **/
00454     typedef ArrayVector<unsigned char> ICCProfile;
00455 
00456         /** Returns a reference to the ICC profile.
00457 
00458            Note: The reference will become invalid when the
00459            ImageImportInfo object has been destroyed.
00460          **/
00461     VIGRA_EXPORT const ICCProfile & getICCProfile() const;
00462 
00463   private:
00464     std::string m_filename, m_filetype, m_pixeltype;
00465     int m_width, m_height, m_num_bands, m_num_extra_bands;
00466     float m_x_res, m_y_res;
00467     Diff2D m_pos;
00468     ICCProfile m_icc_profile;
00469 };
00470 
00471 // return a decoder for a given ImageImportInfo object
00472 VIGRA_EXPORT std::auto_ptr<Decoder> decoder( const ImageImportInfo & info );
00473 
00474 //@}
00475 
00476 } // namespace vigra
00477 
00478 #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.6.0 (5 Nov 2009)