[ VIGRA Homepage | Class Index | Function Index | File Index | 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 /* ( 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) |
html generated using doxygen and Python
|