---

image.h

Go to the documentation of this file.

#ifndef fl_image_h
#define fl_image_h


#include "fl/pointer.h"

#include <iostream>
#include <string>
#include <vector>


namespace fl
{
  // Forward declaration for use by Image
  class PixelFormat;
  class Pixel;
  class ImageFileFormat;
  

  // Image --------------------------------------------------------------------

  class Image
  {
  public:
        Image ();  
        Image (const PixelFormat & format);  
        Image (int width, int height);  
        Image (int width, int height, const PixelFormat & format);  
        Image (const Image & that);  
        Image (unsigned char * buffer, int width, int height, const PixelFormat & format);  
        Image (const std::string & fileName);  

        void read (const std::string & fileName);  
        void read (std::istream & stream);
        void write (const std::string & fileName, const std::string & formatName = "pgm") const;  
        void write (std::ostream & stream, const std::string & formatName = "pgm") const;

        Image & operator <<= (const Image & that);  
        void copyFrom (const Image & that);  
        void copyFrom (unsigned char * buffer, int width, int height, const PixelFormat & format);  
        void attach (unsigned char * buffer, int width, int height, const PixelFormat & format);  
        void detach ();  

        void resize (int width, int height);  
        void bitblt (const Image & that, int toX = 0, int toY = 0, int fromX = 0, int fromY = 0, int width = -1, int height = -1);  
        void clear (unsigned int rgba = 0);  

        Image operator + (const Image & that);  
        Image operator - (const Image & that);  
        Image operator * (double factor);  
        Image & operator *= (double factor);  
        Image & operator += (double value);  

        Pixel         operator () (int x, int y) const;  
        unsigned int  getRGBA  (int x, int y) const;  
        void          getRGBA  (int x, int y, float values[]) const;
        unsigned int  getYUV   (int x, int y) const;
        unsigned char getGray  (int x, int y) const;
        void          getGray  (int x, int y, float & gray) const;
        unsigned char getAlpha (int x, int y) const;
        void          setRGBA  (int x, int y, unsigned int rgba);  
        void          setRGBA  (int x, int y, float values[]);
        void          setYUV   (int x, int y, unsigned int yuv);
        void          setGray  (int x, int y, unsigned char gray);
        void          setGray  (int x, int y, float gray);
        void          setAlpha (int x, int y, unsigned char alpha);

        // Data
        Pointer             buffer;
        const PixelFormat * format;
        int                 width;  
        int                 height;  
        double              timestamp;  
  };

  template<class T>
  class ImageOf : public Image
  {
  public:
        // These constructors blindly wrap the constructors of Image, without
        // regard to the size or type of data returned by operator (x,y).
        ImageOf () {}
        ImageOf (const PixelFormat & format) : Image (format) {}
        ImageOf (int width, int height) : Image (width, height) {}
        ImageOf (int width, int height, const PixelFormat & format) : Image (width, height, format) {}
        ImageOf (const Image & that) : Image (that) {}

        T & operator () (int x, int y) const
        {
          return ((T *) buffer)[y * width + x];
        }
  };


  // Filter -------------------------------------------------------------------

  class Filter
  {
  public:
        virtual Image filter (const Image & image) = 0;  
  };

  inline Image
  operator * (const Filter & filter, const Image & image)
  {
        // We lie about Filter being const.  This allows you to construct a Filter
        // object right in the middle of an expression without getting complaints
        // from the compiler.  Ditto for the other operators below.
        return ((Filter &) filter).filter (image);
  }

  inline Image
  operator * (const Image & image, const Filter & filter)
  {
        return ((Filter &) filter).filter (image);
  }

  inline Image &
  operator *= (Image & image, const Filter & filter)
  {
        return image = image * ((Filter &) filter);
  }


  // PixelFormat --------------------------------------------------------------

  class PixelFormat : public Filter
  {
  public:
        virtual Image filter (const Image & image);  
        void fromAny (const Image & image, Image & result) const;

        virtual bool operator == (const PixelFormat & that) const;  
        bool operator != (const PixelFormat & that) const
        {
          return ! operator == (that);
        }

        virtual unsigned int  getRGBA  (void * pixel) const = 0;  
        virtual void          getRGBA  (void * pixel, float values[]) const;  
        virtual void          getXYZ   (void * pixel, float values[]) const;
        virtual unsigned int  getYUV   (void * pixel) const;
        virtual unsigned char getGray  (void * pixel) const;
        virtual void          getGray  (void * pixel, float & gray) const;
        virtual unsigned char getAlpha (void * pixel) const;  
        virtual void          setRGBA  (void * pixel, unsigned int rgba) const = 0;
        virtual void          setRGBA  (void * pixel, float values[]) const;  
        virtual void          setXYZ   (void * pixel, float values[]) const;
        virtual void          setYUV   (void * pixel, unsigned int yuv) const;
        virtual void          setGray  (void * pixel, unsigned char gray) const;
        virtual void          setGray  (void * pixel, float gray) const;
        virtual void          setAlpha (void * pixel, unsigned char alpha) const;  

        int depth;  
        int precedence;  
        // The following two flags could be implemented several different ways.
        // One alternative would be to make a more complicated class hierarchy
        // that implies the information.  Eg: have intermediate classes
        // PixelFormatMonochrome and PixelFormatColor.  Another alternative is
        // to put channel information into a bitmap and use masks to determine
        // various states.
        bool monochrome;  
        bool hasAlpha;  
  };

  class PixelFormatGrayChar : public PixelFormat
  {
  public:
        PixelFormatGrayChar ();

        virtual Image filter (const Image & image);
        void fromGrayFloat  (const Image & image, Image & result) const;
        void fromGrayDouble (const Image & image, Image & result) const;
        void fromRGBAChar   (const Image & image, Image & result) const;
        void fromRGBABits   (const Image & image, Image & result) const;
        void fromAny        (const Image & image, Image & result) const;

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual void          getXYZ  (void * pixel, float values[]) const;
        virtual unsigned char getGray (void * pixel) const;
        virtual void          getGray (void * pixel, float & gray) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setXYZ  (void * pixel, float values[]) const;
        virtual void          setGray (void * pixel, unsigned char gray) const;
        virtual void          setGray (void * pixel, float gray) const;
  };

  class PixelFormatGrayFloat : public PixelFormat
  {
  public:
        PixelFormatGrayFloat ();

        virtual Image filter (const Image & image);
        void fromGrayChar   (const Image & image, Image & result) const;
        void fromGrayDouble (const Image & image, Image & result) const;
        void fromRGBAChar   (const Image & image, Image & result) const;
        void fromRGBABits   (const Image & image, Image & result) const;
        void fromAny        (const Image & image, Image & result) const;

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual void          getRGBA (void * pixel, float values[]) const;
        virtual void          getXYZ  (void * pixel, float values[]) const;
        virtual unsigned char getGray (void * pixel) const;
        virtual void          getGray (void * pixel, float & gray) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setRGBA (void * pixel, float values[]) const;
        virtual void          setXYZ  (void * pixel, float values[]) const;
        virtual void          setGray (void * pixel, unsigned char gray) const;
        virtual void          setGray (void * pixel, float gray) const;
  };

  class PixelFormatGrayDouble : public PixelFormat
  {
  public:
        PixelFormatGrayDouble ();

        virtual Image filter (const Image & image);
        void fromGrayChar  (const Image & image, Image & result) const;
        void fromGrayFloat (const Image & image, Image & result) const;
        void fromRGBAChar  (const Image & image, Image & result) const;
        void fromRGBABits  (const Image & image, Image & result) const;
        void fromAny       (const Image & image, Image & result) const;

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual void          getRGBA (void * pixel, float values[]) const;
        virtual void          getXYZ  (void * pixel, float values[]) const;
        virtual unsigned char getGray (void * pixel) const;
        virtual void          getGray (void * pixel, float & gray) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setRGBA (void * pixel, float values[]) const;
        virtual void          setXYZ  (void * pixel, float values[]) const;
        virtual void          setGray (void * pixel, unsigned char gray) const;
        virtual void          setGray (void * pixel, float gray) const;
  };

  class PixelFormatRGBAChar : public PixelFormat
  {
  public:
        PixelFormatRGBAChar ();

        virtual Image filter (const Image & image);
        void fromGrayChar   (const Image & image, Image & result) const;
        void fromGrayFloat  (const Image & image, Image & result) const;
        void fromGrayDouble (const Image & image, Image & result) const;
        void fromRGBABits   (const Image & image, Image & result) const;

        virtual bool operator == (const PixelFormat & that) const;

        virtual unsigned int  getRGBA  (void * pixel) const;
        virtual unsigned char getAlpha (void * pixel) const;
        virtual void          setRGBA  (void * pixel, unsigned int rgba) const;
        virtual void          setAlpha (void * pixel, unsigned char alpha) const;

        static void shift (unsigned int redMask, unsigned int greenMask, unsigned int blueMask, unsigned int alphaMask, int & redShift, int & greenShift, int & blueShift, int & alphaShift);  
  };

  class PixelFormatRGBABits : public PixelFormat
  {
  public:
        PixelFormatRGBABits (int depth, unsigned int redMask, unsigned int greenMask, unsigned int blueMask, unsigned int alphaMask);

        virtual Image filter (const Image & image);
        void fromGrayChar   (const Image & image, Image & result) const;
        void fromGrayFloat  (const Image & image, Image & result) const;
        void fromGrayDouble (const Image & image, Image & result) const;
        void fromRGBAChar   (const Image & image, Image & result) const;
        void fromRGBABits   (const Image & image, Image & result) const;

        virtual bool operator == (const PixelFormat & that) const;

        virtual unsigned int  getRGBA  (void * pixel) const;
        virtual unsigned char getAlpha (void * pixel) const;
        virtual void          setRGBA  (void * pixel, unsigned int rgba) const;
        virtual void          setAlpha (void * pixel, unsigned char alpha) const;

        void shift (unsigned int redMask, unsigned int greenMask, unsigned int blueMask, unsigned int alphaMask, int & redShift, int & greenShift, int & blueShift, int & alphaShift) const;

        unsigned int redMask;
        unsigned int greenMask;
        unsigned int blueMask;
        unsigned int alphaMask;
  };

  class PixelFormatRGBAFloat : public PixelFormat
  {
  public:
        PixelFormatRGBAFloat ();

        virtual unsigned int  getRGBA  (void * pixel) const;
        virtual void          getRGBA  (void * pixel, float values[]) const;
        virtual unsigned char getAlpha (void * pixel) const;
        virtual void          setRGBA  (void * pixel, unsigned int rgba) const;
        virtual void          setRGBA  (void * pixel, float values[]) const;
        virtual void          setAlpha (void * pixel, unsigned char alpha) const;
  };

  class PixelFormatYVYUChar : public PixelFormat
  {
  public:
        PixelFormatYVYUChar ();

        virtual Image filter (const Image & image);
        void fromVYUYChar (const Image & image, Image & result) const;

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual unsigned int  getYUV  (void * pixel) const;
        virtual unsigned char getGray (void * pixel) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setYUV  (void * pixel, unsigned int yuv) const;
  };

  // Same as YVYU, but with different ordering within the word
  class PixelFormatVYUYChar : public PixelFormat
  {
  public:
        PixelFormatVYUYChar ();

        virtual Image filter (const Image & image);
        void fromYVYUChar (const Image & image, Image & result) const;

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual unsigned int  getYUV  (void * pixel) const;
        virtual unsigned char getGray (void * pixel) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setYUV  (void * pixel, unsigned int yuv) const;
  };

  class PixelFormatHLSFloat : public PixelFormat
  {
  public:
        PixelFormatHLSFloat ();

        virtual unsigned int  getRGBA (void * pixel) const;
        virtual void          getRGBA (void * pixel, float values[]) const;
        virtual void          setRGBA (void * pixel, unsigned int rgba) const;
        virtual void          setRGBA (void * pixel, float values[]) const;

        float HLSvalue (const float & n1, const float & n2, float h) const;  
  };

  extern PixelFormatGrayChar   GrayChar;
  extern PixelFormatGrayFloat  GrayFloat;
  extern PixelFormatGrayDouble GrayDouble;
  extern PixelFormatRGBAChar   RGBAChar;
  extern PixelFormatRGBABits   BGRChar;  
  extern PixelFormatRGBABits   ABGRChar;  
  extern PixelFormatRGBAFloat  RGBAFloat;
  extern PixelFormatYVYUChar   YVYUChar;
  extern PixelFormatVYUYChar   VYUYChar;
  extern PixelFormatHLSFloat   HLSFloat;

  // Naming convention for RGBBits (other than BGRChar):
  // R<red bits>G<green bits>B<blue bits>
  // EG: R5G5B5 would be a 15 bit RGB format.


  // Pixel --------------------------------------------------------------------

  class Pixel
  {
  public:
        Pixel ();
        Pixel (unsigned int rgba);
        Pixel (const Pixel & that);
        Pixel (const PixelFormat & format, void * pixel);

        unsigned int getRGBA () const;
        void         getRGBA (float values[]) const;
        void         getXYZ  (float values[]) const;
        void         setRGBA (unsigned int rgba) const;
        void         setRGBA (float values[]) const;
        void         setXYZ  (float values[]) const;

        Pixel & operator = (const Pixel & that);  
        Pixel & operator += (const Pixel & that);  
        Pixel operator + (const Pixel & that) const;  
        Pixel operator * (const Pixel & that) const;  
        Pixel operator * (float scalar) const;  
        Pixel operator / (float scalar) const;  
        Pixel operator << (const Pixel & that);  

        const PixelFormat * format;
        void * pixel;  

        // This union is rather gross, and it would be nice not carry the baggage
        // around.  However, this is cheaper than allocating a small piece on the
        // heap.  Since Pixel is mainly intended to allow linear ops on abstract
        // image elements, it will frequently need its own storage (for
        // intermediate values) as opposed to referrencing an Image buffer.
        // "Frequently" means in the middle of an O(n^3) loop where n is the width
        // or height of an Image.
        union
        {
          unsigned char graychar;
          float         grayfloat;
          double        graydouble;
          unsigned int  rgbchar;
          float         rgbafloat[4];
        } data;
  };


  // File formats -------------------------------------------------------------

  class ImageFileFormat
  {
  public:
        ImageFileFormat ();
        virtual ~ImageFileFormat ();

        virtual void read (const std::string & fileName, Image & image) const;
        virtual void read (std::istream & stream, Image & image) const = 0;
        virtual void write (const std::string & fileName, const Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const = 0;
        virtual bool isIn (std::istream & stream) const = 0;  
        virtual bool handles (const std::string & formatName) const = 0;  

        static ImageFileFormat * find (const std::string & fileName);  
        static ImageFileFormat * find (std::istream & stream);  
        static ImageFileFormat * findName (const std::string & formatName);  
        static void getMagic (std::istream & stream, std::string & magic);  

        static std::vector<ImageFileFormat *> formats;
  };

  class ImageFileFormatPGM : public ImageFileFormat
  {
  public:
        virtual void read (std::istream & stream, Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const;
        virtual bool isIn (std::istream & stream) const;
        virtual bool handles (const std::string & formatName) const;
  };

  class ImageFileFormatEPS : public ImageFileFormat
  {
  public:
        virtual void read (std::istream & stream, Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const;
        virtual bool isIn (std::istream & stream) const;
        virtual bool handles (const std::string & formatName) const;
  };

  class ImageFileFormatJPEG : public ImageFileFormat
  {
  public:
        virtual void read (std::istream & stream, Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const;
        virtual bool isIn (std::istream & stream) const;
        virtual bool handles (const std::string & formatName) const;
  };

  class ImageFileFormatTIFF : public ImageFileFormat
  {
  public:
        // Note: This format can't read and write streams, so those two methods
        // will throw an exception.
        virtual void read (const std::string & fileName, Image & image) const;
        virtual void read (std::istream & stream, Image & image) const;
        virtual void write (const std::string & fileName, const Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const;
        virtual bool isIn (std::istream & stream) const;
        virtual bool handles (const std::string & formatName) const;
  };

  class ImageFileFormatMatlab : public ImageFileFormat
  {
  public:
        virtual void read (std::istream & stream, Image & image) const;
        virtual void write (std::ostream & stream, const Image & image) const;
        virtual bool isIn (std::istream & stream) const;
        virtual bool handles (const std::string & formatName) const;
        void parseType (int type, int & numericType) const;
  };


  // Image inlines ------------------------------------------------------------

  inline Image &
  Image::operator <<= (const Image & that)
  {
        buffer    = that.buffer;
        format    = that.format;
        width     = that.width;
        height    = that.height;
        timestamp = that.timestamp;
        return *this;
  }

  inline Pixel
  Image::operator () (int x, int y) const
  {
        return Pixel (*format, & ((char *) buffer)[(y * width + x) * format->depth]);
  }

  inline void
  Image::getRGBA (int x, int y, float values[]) const
  {
        format->getRGBA (& ((char *) buffer)[(y * width + x) * format->depth], values);
  }

  inline unsigned int
  Image::getYUV (int x, int y) const
  {
        return format->getYUV (& ((char *) buffer)[(y * width + x) * format->depth]);
  }

  inline unsigned char
  Image::getGray (int x, int y) const
  {
        return format->getGray (& ((char *) buffer)[(y * width + x) * format->depth]);
  }

  inline void
  Image::getGray (int x, int y, float & gray) const
  {
        format->getGray (& ((char *) buffer)[(y * width + x) * format->depth], gray);
  }

  inline unsigned char
  Image::getAlpha (int x, int y) const
  {
        return format->getAlpha (& ((char *) buffer)[(y * width + x) * format->depth]);
  }

  inline void
  Image::setRGBA (int x, int y, float values[])
  {
        format->setRGBA (& ((char *) buffer)[(y * width + x) * format->depth], values);
  }

  inline void
  Image::setYUV (int x, int y, unsigned int yuv)
  {
        format->setYUV (& ((char *) buffer)[(y * width + x) * format->depth], yuv);
  }

  inline void
  Image::setGray (int x, int y, unsigned char gray)
  {
        format->setGray (& ((char *) buffer)[(y * width + x) * format->depth], gray);
  }

  inline void
  Image::setGray (int x, int y, float gray)
  {
        format->setGray (& ((char *) buffer)[(y * width + x) * format->depth], gray);
  }

  inline void
  Image::setAlpha (int x, int y, unsigned char alpha)
  {
        format->setAlpha (& ((char *) buffer)[(y * width + x) * format->depth], alpha);
  }
}


#endif

---