ImageIO.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
Multimediale Systeme der Informationsverarbeitung
Institut fuer Informatik
Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/


#ifndef __BIAS_IMAGEIO_H__
#define __BIAS_IMAGEIO_H__

#include "bias_config.h"


#include <string>
#include "Image.hh"
#include "MetaData.hh"

#define MIP_IDENTIFIER "MIP"
#define MIP_IDENTIFIER_LENGTH 3

#define UNKNOWN_META_DATA -5

// default quality for saving e.g. jpg images from  0..100
#define BIAS_DEFAULT_IMAGE_QUALITY 80
#define BIAS_DEFAULT_SYNC false
#define BIAS_DEFAULT_FORCENEWID true


// return code if no error occured
#define BIAS_IO_SUCCESS 0

#ifdef BIAS_HAVE_OPENEXR
#  ifdef WIN32
#    pragma warning( push, 1)
#    define PLATFORM_WINDOWS
#  endif // WIN32
#    include <ImfPixelType.h>
#  ifdef WIN32
#    pragma warning( pop)
#  endif // WIN32
#endif


namespace BIAS {
  /** @class ImageIO
      @ingroup g_image_io
      @brief Routines for loading and writing all kinds of image formats.
      @note Use Load/Save and Import/ExportImage for foreign+internal file formats
        For proprietary mip format use extension mip and Load/Save.
      As all functions are static call them like ImageIO::Load(). */
  class BIASImageBase_EXPORT ImageIO {
  public:
    /** @enum TFileFormat
        @brief format specifier when writing an image to a file
        Do *NOT* change order or associated enum value
        because it may confuse IO rotines for loading old images.
    */
    enum TFileFormat {
      FF_auto=4242 /* automatic format detection by filename*/
      ,FF_unknown=9999 /* could not be detected by extension */
      ,FF_mip=0
      ,FF_ppm=1
      ,FF_pgm=2
      ,FF_jpg=3
      ,FF_tif=4
      ,FF_png=5
      ,FF_viff=6
      ,FF_exr=7
      ,FF_dds=8
      ,FF_raw4096=9
      ,FF_bmp=10
      ,FF_pbm=12
      ,FF_Real32=13
      ,FF_matrix=14 /* text matrix format */
    };


    /** @brief first tries a call to Read MIP image and if that fails,
        tries to Import Image with all other available format loaders
        and third party libraries.
        Note: Win32 paths such as "C:/data/image.jpg" will work, backslashes not because they escape chars.
        @return 0 on success
        @return UNKNOWN_META_DATA if meta data could not be read
        @author Felix Woelk, Jan Woetzel **/
    static int Load(const std::string& FileName, ImageBase& img);
    
    /** @brief Try to load/import an image from a file using external libs.

        Formats supported are listed in TFileFormat.
        More over a few other formats may be includeable like GIF.
        The imported image is always of the type RGB.
        @param filename name of the file to be loaded
        @return -1 in case of error
        @return UNKNOWN_META_DATA if meta data could not be read
        param assumeGrey : DEPRECATED. Was used to speed up loading with imlib
        @author Ingo Thomsen 2002 - Complete Rewrite by Jan Woetzel 2005 **/
    static int ImportImage(const std::string& filename, ImageBase &result );

    /** @brief Export image as file using extrnal libs.

        @param filename name of the file to be loaded
        @param img Image to be saved, not const because of setUUID side effect.
        @param FileFormat What file format shall be used for saving
        @param jpeg_quality Quality of a jpeg image to be saved,
        unused in all other formats
        @param sync does only worlk with pgm/ppm (woelk)
        @param writeMetaData true to (try to) write meta data to disk and
            false to drop it.
        @return 0 on success
        @author (Ingo Thomsen) - complete rewrite by Jan Woetzel */
    static int Save(const std::string& filename,
                    const ImageBase &img,
                    const enum TFileFormat FileFormat=FF_auto,
                    const bool sync = BIAS_DEFAULT_SYNC,
                    const int c_jpeg_quality=BIAS_DEFAULT_IMAGE_QUALITY,
                    const bool forceNewID = BIAS_DEFAULT_FORCENEWID,
                    const bool & writeMetaData=true);

    /** Write image in binary file format needed by RealEyes.
       \author bartczak 03/2008
     **/
    static int WriteRAW_IMA(const std::string& FileName,
                            const ImageBase &img_const);

    /** @brief Write a mip binary image to disk circumventing OS caches
        as good as possible. (O_DIRECT)
        @author Jan-Friso Evers*/
    static int WriteUnbuffered(const std::string& FileName,
                               const ImageBase &img);

    /**
     * \brief Import text images to BIAS.
     * The format is:
     * cols rows channels interleaved
     * row1 (all channels)
     * row2 .....
     * .....
     * \see ExportMatrix
     * \author Ingo Schiller, moved here from biasconvert
     * \date 03/2011
     */
    static int ImportMatrix(const std::string &FileName,
                                                  ImageBase &img,
                                                  const bool verbose);
    /**
     * \brief Export BIAS images to text images
     * \note currently only one channel images are supported
     * * The format is:
     * cols rows channels interleaved
     * row1 (all channels)
     * row2 .....
     * .....
     * \see ImportMatrix
     * \author Ingo Schiller, moved here from biasconvert
     * \date 03/2011
     */
    static int ExportMatrix(const std::string &FileName,
                                                    const ImageBase &img,
                                    const bool verbose);

    /** @brief appends extension to name if extension is not already extension,
        avoids double extension like ".pgm.pgm"
        @param oldName filename (maybe selected by user)
        @param newExtension desired extension
        @return a filename with extension
        @author Jan Woetzel 04/2003 */
    static std::string ExtensionName(const std::string & oldName,
                                     const std::string & newExtension);

#ifdef BIAS_HAVE_LIBJPEG
    /** @brief Reads an image from disk using the LibJPEG library
               encapsulated in ImportImage.

        @return 0 in case of success, negative value in case of error.
        @param filename the input filename to read from.
        @param result is the returned read image
        @param readComment specifies if comment metadata should be read
        @author esquivel 05/2008 */
    static int ImportLibJPEG(const std::string &filename,
                             BIAS::ImageBase &result,
                             bool readComment = true);

    /** @brief Writes an image to disk using the LibJPEG library
               encapsulated in ExportImage.

        @return 0 in case of success, negative value in case of error.
        @param filename the filename to write image to
        @param image is the image to save
        @param quality determines the compression factor used for JPEG
               (100: no compression, highest quality)
        @author esquivel 05/2008 */
    static int ExportLibJPEG(const std::string &filename,
                             const BIAS::ImageBase &image,
                             const int quality = 100);
#endif // BIAS_HAVE_LIBJPEG


#ifdef BIAS_HAVE_IMAGEMAGICKLIB
    /** @brief Reads an image from disk using the ImageMagick++ library.
        \todo Implement assumeGrey for MagickPP like for Imlib (JW).

        result image must be initialized. Thread image is automatically
        converted to match the result image.

        @return 0 in case of succes, negative value in case of error.
        @param FileName the input filename to read from.
        @param img contains the read image if success.
        @param assumeGrey not implemented for now, just for interface
        compatibility with Bias Import functions
        @param readMetaData try to read ASCII metadata from file comment.

        See http://www.imagemagick.org/script/formats.php for supported
        formats.
        @author Jan Woetzel 10/2004 */
    static int ImportMagickPPAutoconvert(const std::string& FileName,
                                         ImageBase& result,
                                         const bool &assumeGrey=false,
                                         const bool &readMetaData=false );

    /** @brief Reads an image from disk using the ImageMagick++ library.
        is called automatically by ImportImage.
        @param dummy ignored, for consistency with ImportMagickPPAutoconvert
        @param readMetaData true to try to read metadat (from comment field)
        @return 0 in case of succes, negative value in case of error.
        \todo fix the error on reading reference streaming in Metadata
          operator>>
        e.g. on loading ibak "M34/Front/image00000000.jpg" (jw)
        @author jw and woelk 12/2004 */
    static int ImportMagickPP(const std::string & FileName,
                              ImageBase & result,
                              const bool & dummy = false,
                              const bool & readMetaData = true);

    /** @brief Reads an image from disk using the ImageMagick++ library.
        \todo Implement 16bit short write with  Magick++ using BLOB.
        \todo Implement quality directive for jpg saving with Magick++.
        \bug IMageMagick PPM files are alwyas written as ASCII instaed of
           binary (JW)
        @return 0 in case of succes, negative value in case of error.
        @param FileName the input filename to read from.
        @param img contains the image to be written to disk.
        @param quality for saving, e.g.1-100 for jpeg, tested for jpeg. Is
           overridden by losslessMode parameter
        @param writeMetaData try to write ASCII MetaData as comment to file.
        @param forceBinaryPNMformat true to write BINARY pnm/pbm/pgmp/ppm
             instead of human readable ASCII.
        @param losslesMode true to write in jpeg loslles mode. overrides
        quality setting
        @param writeGZipped true for additional gzip compression (e.g. .pgm.gz)
        which may be useful for human readable ASCII pgm output but save disk
        space.

        Output file type is determined automatically by file extension.

        See http://www.imagemagick.org/script/formats.php or \code identify
        -list format \endcode for supported formats.
        @author Jan Woetzel 10/2004 */
    static int ExportMagickPP(const std::string& FileName,
                              const ImageBase img,
                              const int  &quality=BIAS_DEFAULT_IMAGE_QUALITY,
                              const bool &writeMetaData=false,
                              const bool &forceBinaryPNMformat=true,
                              const bool &losslesJpgMode=false,
                              const bool &writeGZipped=false,
                              const std::string & comment=std::string("")
                              );
#endif // BIAS_HAVE_IMAGEMAGICKLIB



#ifdef BIAS_HAVE_OPENCV

    /** @brief Reads an image from disk using the OpenCV library.
        @param[in] filename Specifies the name of the file to read from.
        @param[out] image Returns the image read from file if successful.
        @return Returns 0 in case of success, < 0 in case of errors.
        @author Jan Woetzel
    */
    static int ImportOpenCV(const std::string &filename, ImageBase &image);

    /** @brief Write an image to disk using the OpenCV library.
        @param[in] filename Specifies the name of the file to write to.
        @param[in] image Contains the image to write.
        @return Returns 0 in case of success, < 0 in case of errors.
        @author esquivel
    */
    static int ExportOpenCV(const std::string &filename, const ImageBase &image);

#endif // BIAS_HAVE_OPENCV



#ifdef BIAS_HAVE_OPENEXR
  public:
    /** @brief load an .exr OpenEXR image from disk.
        */
    static int ImportOpenEXR(const std::string& FileName, ImageBase& result);

    /** @brief save an .exr OpenEXR image to disk.
        */
    static int ExportOpenEXR(const std::string& FileName,
                             const ImageBase& input);
#endif // BIAS_HAVE_OPENEXR



#ifdef BIAS_HAVE_DEVIL
    /** @brief Reads an image from disk using the DevIL/OpenIL library.
        See http://openil.sourceforge.net for details.
        Supports reading multiple formats, including
        - .bmp, .gif, .jpg, .pcd, .pcx, .pic, .png, .pnm
        - .tga, .tif , .io
        - .dds
        - Doom graphics, ...  and many other.

        @return 0 in case of succes, negative value in case of error.
        @param FileName the input filename to read from.
        @param tex3DplaneZ ignored for tex2D. Useful to extarct 2D texture from volumetric 2D texture.
        @param result contains the read image if success.

        @author Jan Woetzel 12/2005 */
    static int ImportDevIL(const std::string& FileName,
                           ImageBase& result,
                           const unsigned int & tex3DplaneZ=1);

    /** @brief Save to disk using the DevIL/OpenIL library.
        See http://openil.sourceforge.net for details.
        Supports writing multiple formats, including
        - .dds
        - .tga, .tif,
        - .bmp, .jpg, .pcx, .png, .pnm
        - .sgi,.tga
        the fiel format is determined from the Filenames extension.
        @return 0 in case of succes, negative value in case of error.
        @param FileName the output filename to read from.
        @param img image to be saved
        @param fileOverwrite true to overwrite file if exists
        @author Jan Woetzel 12/2005 */
    static int ExportDevIL(const std::string& FileName,
                           const ImageBase& img,
                           const bool &fileOverwrite=true,
                           const bool &allowPadding=true );

    /** initialize devIL once globally.
        Usually called by IL load and save functions automatically.
        To speed up first load/save you can "pre-call" it on startup.
        @author Jan Woetzel */
    static void InitDevIL();

    /** print info in currently bound DevIL image
        @author Jan Woetzel */
    static void PrintInfoDevIL(std::ostream & os=std::cout);

#endif // BIAS_HAVE_DEVIL


    /** @brief Reads a proprietary .RAW format from disk
        A typical file consists of these blocks:
        - magick cookie + HEADER size - 7 Byte, e.g. "RAW4096"
        thus magick cookies are "RAW8", "RAW4", "RAW2" ,"RAW1", "RAW0"
        for 8192, 4096, 2048, 1024, 0512 Byte header inclufing cookie.

        E.g. RAW4096 is 4096 Byte text header followed by arbitrary size RAW
        datat specicified in the header.
        Used for most efficient write to disk on WIN32 using system calls
        without buffering and cache with DMA.
        E.g:
        \code
        Block Name   -  4   Byte  -  RAW8[192] / RAW4[096] /RAW2[048]
        /RAW1[024] / RAW0[512]
        Block Length -  3/4 Byte  -  8192/192    4096/096  should be 4 Byte but
        is 3 Byte in old RAW4096 fmt witten for "Mediendom" project.
        Block Data   -  binary data area begins at Byte nr. "block length+1",
        e.g. 4096+1 from the begginning of file, including header.
        \endcode
        TODO: encode header information in Write routine compatible to digital
        cameras .raw format which is very similar.

        FYI: IrFanView can read and display this format natively (on WIN32).

        Inspired by http://www.dalibor.cz/minolta/raw_file_format.htm
        and the need to write exactly on aligned memory and disk block sizes
        for performance reasons, in particular on WIN32.

        Works only with 8 bpp one plane Bayer pattern raw images
        (from scorpion camera) actually.

        \bug Reading the data on Linux is broken because fopen ignores the
        binary flag, see "man fopen".

        @return 0 in case of succes, negative value in case of error.
        @author Jan Woetzel 2005 */
    static int ImportRAWwithHeader(const std::string & filename,
                                   BIAS::ImageBase & img);


    /** helper function for ImportRAWwithHeader
        Parses buf for tag
        @return retVal value associated to tag in buf
        @author Jan Woetzel 2005 */
    static int ParseRAWwithHeader(const std::string & buf,
                                  const std::string & tag,
                                  unsigned int & retVal);

    //#ifdef BIAS_HAVE_RADIANCE
    /** @brief import Greg Wards Radiance RGBE image format (.hdr, .rad)
        A high dynamic range RGBE image contains 24 bits RGB Mantissa
        and 8 common exponent bits that encode the dynamic range.
        See http://radsite.lbl.gov/radiance/
        Own implementation just for copyright reasons.
        @author Jan Woetzel 01/2006 */
    static int ImportRADIANCE(const std::string& FileName, ImageBase& result);
    //#endif // BIAS_HAVE_RADIANCE

    /** Loads proprietary raw floating point 2d image from Mathematica Real32
        values
        Example how to export in Mathematica:
        \verbatim
        (* helper functions *)
        Header[img_] := ({1, Dimensions[img][[1]], Dimensions[img][[2]], 1})
        ExportReal32[filename_, img_] := Export[filename <> ".real32",
        Append[Header[img], img], "Real32"]

        (* sample data *)
        img = {
        {1.1, 2.2},
        {3.3, 4.4},
        {5.5, 6.6} };

        (* final usage writing to disk in appropriate format: *)
        ExportReal32["out_img", img]
        \endverbatim
        @author Jan Woetzel */
    static int ImportReal32(const std::string& FileName, ImageBase& result);

#ifdef WIN32

    /** @brief Reads a MS DIB BITMAP (.bmp) image from disk using Windows API directly.

    Windows API LoadImage is used to load HBITMAP and copy it to BIAS ImageBase memory.

    NOTES
    - Seems to need absolute path in addition to working dir,
    i.e. C:/Front258_Rgb.bmp  or  C:\\Front258_Rgb.bmp
    - Colormap is ignored for now.
    - works ast least for normal 24bit DIB

    @return 0 in case of succes, negative value in case of error.
    @param FileName the input filename to read from.
    @param result contains the read image if success.
    @param flipY Windows DIB/BMP is vertically flipped w.r.t BIAS Image layout. true to compensate.
    @author Jan Woetzel 03/2007 */
    static int Import_BITMAP_winapi(const std::string& FileName,
      ImageBase& result,
      const bool flipY=true);

    /** @brief interface for shared memory image exchange with handle
    @author Jan Woetzel */
    static int BIAS::ImageIO::Import_HBITMAP_winapi(const HBITMAP & hbm,
      ImageBase& result,
      const bool flipY=true );

    /** @brief interface for shared memory image exchange with object
    @author Jan Woetzel */
    static int BIAS::ImageIO::Import_BITMAP_winapi(const BITMAP & bm,
      ImageBase& result,
      const bool flipY=true );

#endif // WIN32


// use the same defines as in tiff.h for compatibility with new tokens
#  define BIAS_COMPRESSION_NONE    1     /* dump mode */
#  define BIAS_COMPRESSION_LZW     5     /* lossless Lempel Ziff Welch */
#  define BIAS_COMPRESSION_DEFLATE 32946 /* lossless, known as zip in tiff */
#ifdef BIAS_HAVE_TIFF
    /** @brief Write image to disk using TiffLib directly.
    @param rowsPerStripArg  nr of rows if strip based writing is used in contrast to scanlin or tile based TIFF format.
           for value 0 the imageheight is used => one big strip.
    @param compressionAlgo compression algorithm to use. better compression = slower. E.g. BIAS_COMPRESSION_LZW or BIAS_COMPRESSION_NONE
    @return EXIT_SUCCESS on success, other on failure.
    @author Jan Woetzel */
    static int ExportTIFFLIB(const std::string& FileName,
      const BIAS::ImageBase& img,
      const unsigned int rowsPerStripArg=0,
      const unsigned int compressionAlgo=BIAS_COMPRESSION_NONE,
      const std::string & comment=std::string("BIAS::ImageIO Jan Woetzel") );

    /// @brief read a tiff image from disk using TiffLib directly
    /// @author Jan Woetzel
    static int ImportTIFFLIB(const std::string& FileName, ImageBase& img );
#endif


    /** determines the BIAS::ImageIO::TFileFormat for a given filename/
        extension
        Decision based on extension comparison
        @author Jan Woetzel */
    static BIAS::ImageIO::TFileFormat GetFileFormat(const std::string &str);

    /** return the default extension for a given FileFormat enum
        @author Jan Woetzel */
    static std::string GetExtension(const BIAS::ImageIO::TFileFormat & fmt);

  protected:
    static int ImportImagePnm_(std::ifstream& ifs, ImageBase &result,
                               int depth);
    static int ExportImagePnm_(const std::string &FileName,
                               const ImageBase &img,
                               bool sync=false,
                               const bool & writeMetaData=true);

    /** @brief import a one channel grey float viff image (Khoros image format)
        for compatibility to old stereo code
        @param FileName destination filename
        @param img BIAS ImageBase to be written to disk
        @author Jan Woetzel 01/2003 */
    static int ImportImageViff_(std::ifstream& ifs, ImageBase &result);
    
    // moved from public to protected and renamed - Fernandez 04/09
    /** @brief Read a proprietary mip binary Image from disk and allocate
        memory structure.

        Please note the more general purpose Load/Save interface you may want
        to use instead.

        @param FileName complete name of file to be loaded
        @param img object to receive the image data fro the file
        @param id The image is assigned id if there is no id in the file
        @author Felix Woelk **/
    static int Read_(const std::string& FileName, ImageBase &img);
    
    // moved from public to protected and renamed - Fernandez 04/09
    /** @brief Write a proprietary mip binary Image to disk.

                Please note the more general purpose Load/Save interface you may
                want to use instead.

                @param FileName output file name. Extension .mip is added if
                extension isn't already (case insensitive) 'mip' (JW 04/2003)
                @author Felix Woelk
                @param sync tries to flush all open buffers/caches **/
     static int Write_(const std::string& FileName, const ImageBase &img,
                        const bool sync=false, const bool forceNewID = true);
    

    // to WriteUnbuffered two members are needed
    static char *MemAlignedBuffer_;
    static unsigned long int MemAlignedBufferSize_;


  }; // end of class
} // end of namespace BIAS

#endif