ImfImage.h

Go to the documentation of this file.

///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2014, Industrial Light & Magic, a division of Lucas
// Digital Ltd. LLC
// 
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
// *       Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// *       Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// *       Neither the name of Industrial Light & Magic nor the names of
// its contributors may be used to endorse or promote products derived
// from this software without specific prior written permission. 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////

#ifndef INCLUDED_IMF_IMAGE_H
#define INCLUDED_IMF_IMAGE_H

//----------------------------------------------------------------------------
//
// class Image -- an in-memory data structure that can hold an arbitrary
// OpenEXR image, flat or deep, with one or multiple resolution levels,
// and with an arbitrary set of channels.
// 
// An image is a container for a set of image levels, and an image level
// is a container for a set of image channels.  An image channel contains
// an array of pixel values of type half, float or unsigned int.
// 
// For example:
// 
//     image --+-- level 0 --+-- channel "R" --- pixel data
//             |             |
//             |             +-- channel "G" --- pixel data
//             |             |
//             |             +-- channel "B" --- pixel data
//             |
//             +-- level 1 --+-- channel "R" --- pixel data
//             |             |
//             |             +-- channel "G" --- pixel data
//             |             |
//             |             +-- channel "B" --- pixel data
//             |
//             +-- level 2 --+-- channel "R" --- pixel data
//                           |
//                           +-- channel "G" --- pixel data
//                           |
//                           +-- channel "B" --- pixel data
// 
// An image has a level mode, which can be ONE_LEVEL, MIPMAP_LEVELS or
// RIPMAP_LEVELS, and a level rounding mode, which can be ROUND_UP or
// ROUND_DOWN.  Together, the level mode and the level rounding mode
// determine how many levels an image contains, and how large the data
// window for each level is.  All levels in an image have the same set
// of channels.
// 
// An image channel has a name (e.g. "R", "Z", or "xVelocity"), a type
// (HALF, FLOAT or UINT) and x and y sampling rates.  A channel stores
// samples for a pixel if the pixel is inside the data window of the
// level to which the channel belongs, and the x and y coordinates of
// the pixel are divisible by the x and y sampling rates of the channel.
//
// An image can be either flat or deep.  In a flat image each channel
// in each level stores at most one value per pixel.  In a deep image
// each channel in each level stores an arbitrary number of values per
// pixel.  As an exception, each level of a deep image has a sample count
// channel with a single value per pixel; this value determines how many
// values each of the other channels in the same level has at the same
// pixel location.
//
// The classes Image, ImageLevel and ImageChannel are abstract base
// classes.  Two sets of concrete classes, one for flat and one for
// deep images, are derived from the base classes.
//
//----------------------------------------------------------------------------

#include "ImfImageLevel.h"
#include <ImfTileDescription.h>
#include <ImfArray.h>
#include "ImfExport.h"

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER

class Channel;


class IMF_EXPORT Image
{
  public:

    //
    // Constructor and destructor
    //

    Image ();
    virtual ~Image ();


    //
    // Access to the image's level mode and level rounding mode.
    //

        LevelMode               levelMode() const;
        LevelRoundingMode       levelRoundingMode() const;


    //
    // Number of levels:
    //
    // numXLevels() returns the image's number of levels in the x direction.
    //
    //  if levelMode() == ONE_LEVEL:
    //      return value is: 1
    //
    //  if levelMode() == MIPMAP_LEVELS:
    //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
    //
    //  if levelMode() == RIPMAP_LEVELS:
    //      return value is: rfunc (log (w) / log (2)) + 1
    //
    //  where
    //      w is the width of the image's data window,  max.x - min.x + 1,
    //      h is the height of the image's data window, max.y - min.y + 1,
    //      and rfunc(x) is either floor(x), or ceil(x), depending on
    //      whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
    //
    // numYLevels() returns the image's number of levels in the y direction.
    //
    //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
    //      return value is the same as for numXLevels()
    //
    //  if levelMode() == RIPMAP_LEVELS:
    //      return value is: rfunc (log (h) / log (2)) + 1
    //
    //
    // numLevels() is a convenience function for use with MIPMAP_LEVELS images.
    //
    //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
    //      return value is the same as for numXLevels()
    //
    //  if levelMode() == RIPMAP_LEVELS:
    //      a LogicExc exception is thrown
    //

        int                     numLevels() const;
        int                     numXLevels() const;
        int                     numYLevels() const;


    //
    // Per-level data windows
    //
    // dataWindow() returns the data window for the image; this is the
    // same as the data window for the level with level number (0, 0).
    //
    // dataWindowForLevel(lx, ly) returns the data window for level x,
    // that is, the window for which the image level with level number
    // (lx, ly) has allocated pixel storage.
    //
    //  return value is a Box2i with min value:
    //      (dataWindow().min.x,
    //       dataWindow().min.y)
    //
    //  and max value:
    //      (dataWindow().min.x + levelWidth(lx) - 1,
    //       dataWindow().min.y + levelHeight(ly) - 1)
    //
    // dataWindowForLevel(l) is a convenience function used for ONE_LEVEL
    // and MIPMAP_LEVELS files.  It returns dataWindowForLevel(l,l)).
    //

        const IMATH_NAMESPACE::Box2i &  dataWindow() const;
        const IMATH_NAMESPACE::Box2i &  dataWindowForLevel(int l) const;
        const IMATH_NAMESPACE::Box2i &  dataWindowForLevel(int lx, int ly) const;


    //
    // Size of a level:
    //
    // levelWidth(lx) returns the width of a level with level
    // number (lx, *), where * is any number.
    //
    //  return value is:
    //      max (1, rfunc (w / pow (2, lx)))
    //
    //
    // levelHeight(ly) returns the height of a level with level
    // number (*, ly), where * is any number.
    //
    //  return value is:
    //      max (1, rfunc (h / pow (2, ly)))
    //

    int                     levelWidth  (int lx) const;
    int                     levelHeight (int ly) const;


    //
    // Resize the image:
    //
    // resize(dw,lm,lrm) sets the data window of the image to dw,
    // sets the level mode to lm and the level rounding mode to lrm,
    // and allocates new storage for image levels and image channels.
    // The set of channels in the image does not change.
    //
    // The contents of the image are lost; pixel data are not preserved
    // across the resize operation.  If resizing fails, then the image
    // will be left with an empty data window and no image levels.
    //
    // resize(dw) is the same as resize(dw,levelMode(),levelRoundingMode())
    //

        void                    resize(const IMATH_NAMESPACE::Box2i &dataWindow);

        virtual void            resize(const IMATH_NAMESPACE::Box2i &dataWindow,
                                    LevelMode levelMode,
                                    LevelRoundingMode levelRoundingMode);

    //
    // Shift the pixels and the data window of an image:
    //
    // shiftPixels(dx,dy) shifts the image by dx pixels horizontally and
    // dy pixels vertically.  A pixel at location (x,y) moves to position
    // (x+dx, y+dy).  The data window of the image is shifted along with
    // the pixels.  No pixel data are lost.
    //
    // The horizontal and vertical shift distances must be multiples of
    // the x and y sampling rates of all image channels.  If they are not,
    // shiftPixels() throws an ArgExc exception.
    //

        void                    shiftPixels(int dx, int dy);


    //
    // Insert a new channel into the image.
    //
    // The arguments to this function are the same as for adding a
    // a channel to an OpenEXR file: channel name, x and y sampling
    // rates, and a "perceptually approximately linear" flag.
    //
    // If the image already contains a channel with the same name
    // as the new name then the existing channel is deleted before
    // the new channel is added.
    //

    void                    insertChannel (const std::string &name,
                                           PixelType type,
                                           int xSampling = 1,
                                           int ySampling = 1,
                                           bool pLinear = false);

    void                    insertChannel (const std::string &name,
                                           const Channel &channel);

    //
    // Erase channels from an image:
    //
    // eraseChannel(n) erases the channel with name n.
    // clearChannels() erases all channels.
    //

        void                    eraseChannel(const std::string &name);
        void                    clearChannels();


    //
    // Rename an image channel:
    //
    // renameChannel(nOld,nNew) changes the name of the image channel
    // with name nOld to nNew.
    //
    // If the image already contains a channel called nNew, or if the
    // image does not contain a channel called nOld, then renameChannel()
    // throws an ArgExc exception.
    //
    // In the (unlikely) event that renaming the image channel causes
    // the program to run out of memory, renameChannel() erases the
    // channel that is being renamed, and throws an exception.
    //

        void                    renameChannel(const std::string &oldName,
                                           const std::string &newName);

    //
    // Rename multiple image channels at the same time:
    //
    // Given a map, m, from old to new channel names, renameChannels(m)
    // assigns new names to the channels in the image.  If m has an entry
    // for a channel named c, then the channel will be renamed to m[c].
    // If m has no entry for c, then the channel keeps its old name.
    //
    // If the same name would be assigned to more than one channel, then
    // renameChannels() does not rename any channels but throws an ArgExc
    // exception instead.
    // 
    // In the (unlikely) event that renaming the image channel causes the
    // program to run out of memory, renameChannels() erases all channels
    // in the image and throws an exception.
    //

        void                    renameChannels(const RenamingMap &oldToNewNames);


    //
    // Accessing image levels by level number.
    //
    // level(lx,ly) returns a reference to the image level
    // with level number (lx,ly).
    //
    // level(l) returns level(l,l).
    //

    virtual ImageLevel &            level (int l = 0);
    virtual const ImageLevel &      level (int l = 0) const;

    virtual ImageLevel &            level (int lx, int ly);
    virtual const ImageLevel &      level (int lx, int ly) const;


  protected:

    virtual ImageLevel *
        newLevel (int lx, int ly, const IMATH_NAMESPACE::Box2i &dataWindow) = 0;

  private:

    bool        levelNumberIsValid (int lx, int ly) const;
    void        clearLevels ();

    struct ChannelInfo
    {
        ChannelInfo (PixelType type = HALF,
                     int xSampling = 1,
                     int ySampling = 1,
                     bool pLinear = false);

        PixelType   type;
        int         xSampling;
        int         ySampling;
        bool        pLinear;
    };

    typedef std::map <std::string, ChannelInfo> ChannelMap;

    IMATH_NAMESPACE::Box2i  _dataWindow;
    LevelMode               _levelMode;
    LevelRoundingMode       _levelRoundingMode;
    ChannelMap              _channels;
    Array2D<ImageLevel *>   _levels;
};


OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT

#endif