IMX_Layer.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 */

#pragma once

#include "IMX_API.h"

#include "IMX_Buffer.h"

#include <UT/UT_Array.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_Rect.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_Vector4.h>
#include <UT/UT_Options.h>

/// This is the object read/written by IMX_Node. It is (usually) one AOV (a
/// Vec4f per pixel) of an image.

class IMX_API IMX_Layer : public IMX_Buffer
{
public:

    IMX_Layer() { setDefault(); }

    /// "copy constructor" that does not copy the buffer pixels
    IMX_Layer(const IMX_Layer &a, bool) { copyMetadata(a); }

    /// Initialize the IMX_Buffer
    IMX_Layer(int width, int height, CE_Image::StorageType storage, int channels)
        : IMX_Buffer(width, height, storage, channels)
    {
        setDefault();   // Initialize metadata
    }

    /// Construct a layer from a PXL_Raster
    IMX_Layer(const PXL_Raster &rp)
        : IMX_Buffer(rp)        // Create the underlying buffer
    {
        setDefault();   // Initialize metadata
        setDataWindow(bufferWidth(), bufferHeight());
    }

    ////////////////////////////////////////////////////////////////
    // Accessors for image data

    /// The name is used to populate channel selector widgets, for VDB channel names,
    /// and may be used to distiguish multiple channels on a wire in the future.
    void setName(const UT_StringHolder& name) { myName = name; }
    const UT_StringHolder& getName() const { return myName; }

    /// The dataWindow surrounds all the pixels
    const UT_DimRect& dataWindow() const { return d->myDataWindow; }
    int x() const { return d->myDataWindow.x(); }
    int y() const { return d->myDataWindow.y(); }
    UT_Vector2I xy() const { return UT_Vector2I(d->myDataWindow.data()); }
    int width() const { return d->myDataWindow.width(); }
    int height() const { return d->myDataWindow.height(); }
    UT_Vector2I wh() const { return UT_Vector2I(d->myDataWindow.width(), d->myDataWindow.height()); }
    int r() const { return d->myDataWindow.x2(); }
    int t() const { return d->myDataWindow.y2(); }
    UT_Vector2I rt() const { return UT_Vector2I(d->myDataWindow.x2(), d->myDataWindow.y2()); }

    /// Distortion in image->pixel space transform
    fpreal64 pixelAspectRatio() const { return d->myPixelAspectRatio; }

    /// Aperture in pixels
    const UT_Vector2D &displayWindowSize() const { return d->myDisplayWindowSize; }
    UT_Vector2D displayWindowXY() const { return d->myImageToPixelTranslate - d->myDisplayWindowSize / 2; }
    UT_Vector2D displayWindowRT() const { return d->myImageToPixelTranslate + d->myDisplayWindowSize / 2; }

    /// width / height of the aperture / displayWindow
    fpreal64 apertureAspect() const
    { return d->myPixelAspectRatio * d->myDisplayWindowSize[0] / d->myDisplayWindowSize[1]; }

    /// Camera
    enum Projection { ORTHOGRAPHIC, PERSPECTIVE };
    Projection         projection()     const { return d->myProjection; }
    bool               isOrtho()        const { return d->myProjection == ORTHOGRAPHIC; }
    bool               isPerspective()  const { return d->myProjection == PERSPECTIVE; }
    fpreal64           apertureMax()    const { return d->myApertureMax; }
    UT_Vector2D        apertureOffset() const { return - UT_Vector2D(d->myCamera) * d->myApertureMax / 2; }
    fpreal64           focalLength()    const { return d->myCamera[2] * d->myApertureMax / 2; }
    fpreal64           fStop()          const { return d->myFStop; }
    fpreal64           lensDiameter()   const { return focalLength() * d->myFStop; }
    const UT_Vector2D &clippingRange()  const { return d->myClippingRange; }
    fpreal64           focusPlane()     const { return d->myFocusPlane; }
    const UT_Vector3D &cameraPosition() const { return d->myCamera; }
    fpreal64           cameraZ()        const { return d->myCamera[2]; }
    const UT_Vector2D &shutter()        const { return d->myShutter; }

    /// Transform from camera space to image space.
    UT_Matrix4D projectionXform() const;

    /// Transform from camera space to texture space for Vulkan rasterization
    UT_Matrix4D projectionXformVk() const;

    /// Transform from image space to world space.
    const UT_Matrix4D &transform()         const { return d->myTransform; }
    const UT_Matrix4D &imageToWorldXform() const { return d->myTransform; }

    /// Transform from world space to camera space.
    /// Equal to invert(transform()).translate(-cameraPosition())
    UT_Matrix4D        inverseCameraXform() const;

    ////////////////////////////////////////////////////////////////
    /// Coordinate transforms
    // translate is always done after scale

    const UT_Vector2D &imageToPixelScale() const { return d->myImageToPixelScale; }
    const UT_Vector2D &imageToPixelTranslate() const { return d->myImageToPixelTranslate; }

    const UT_Vector2D &bufferToPixelScale() const { return myBufferToPixelScale; }
    UT_Vector2D bufferToTextureScale() const
    { return 1.0 / UT_Vector2D(bufferWidth(), bufferHeight()); }
    UT_Vector2D textureToBufferScale() const
    { return UT_Vector2D(bufferWidth(), bufferHeight()); }
    const UT_Vector2D &pixelScale() const { return myBufferToPixelScale; }
    bool isPixelScale() const { return pixelScale() != UT_Vector2D(1,1); }
    const UT_Vector2D &bufferToPixelTranslate() const { return myBufferToPixelTranslate; }

    UT_Vector2D imageToBufferScale() const
    { return d->myImageToPixelScale / myBufferToPixelScale; }
    UT_Vector2D imageToBufferTranslate() const
    { return (d->myImageToPixelTranslate - myBufferToPixelTranslate) / myBufferToPixelScale; }
    UT_Vector2D bufferPixelSize() const
    { return myBufferToPixelScale / d->myImageToPixelScale; }

    /// Image <-> Pixel
    UT_Vector2D imageToPixel(const UT_Vector2D &v) const
    { return v * imageToPixelScale() + imageToPixelTranslate(); }
    UT_Vector2D pixelToImage(const UT_Vector2D &v) const
    { return (v - imageToPixelTranslate()) / imageToPixelScale(); }

    /// Pixel <-> Buffer
    UT_Vector2D pixelToBuffer(const UT_Vector2D &v) const
    { return (v - bufferToPixelTranslate()) / bufferToPixelScale(); }
    UT_Vector2D bufferToPixel(const UT_Vector2D &v) const
    { return v * bufferToPixelScale() + bufferToPixelTranslate(); }

    /// Image <-> Buffer
    UT_Vector2D imageToBuffer(const UT_Vector2D &v) const
    { return pixelToBuffer(imageToPixel(v)); }
    UT_Vector2D bufferToImage(const UT_Vector2D &v) const
    { return pixelToImage(bufferToPixel(v)); }

    // Buffer <-> texture, this is not just a scale as texture goes
    // to the corners of pixels, but buffer is to the center.
    UT_Vector2D bufferToTexture(const UT_Vector2D &v) const
    { return (v + 0.5f) * bufferToTextureScale(); }
    UT_Vector2D textureToBuffer(const UT_Vector2D &v) const
    { return v * textureToBufferScale() - 0.5f; }

    // Image <-> texture
    UT_Vector2D imageToTexture(const UT_Vector2D &v) const
    { return bufferToTexture(imageToBuffer(v)); }
    UT_Vector2D textureToImage(const UT_Vector2D &v) const
    { return bufferToImage(textureToBuffer(v)); }

    // Transform point texture <-> pixel:
    UT_Vector2D textureToPixel(const UT_Vector2D &v) const
    { return bufferToPixel(textureToBuffer(v)); }
    UT_Vector2D pixelToTexture(const UT_Vector2D &v) const
    { return bufferToTexture(pixelToBuffer(v)); }

    /// Transform 0,0 to lower-left of buffer in world space, 1,1 to upper-right of buffer
    /// in world space. This is used to convert the layer to a volume.
    UT_Matrix4D bufferUVToWorldXform() const;
    /// Sets the world transform such that the given transformation becomes this
    /// layer's UV to world.
    void setBufferUVToWorldXform(UT_Matrix4D xform);

    /// Initializes this layer from a given voxel array. Number of channels in
    /// the image will be set to tuple size of T, and the data type will also be
    /// set accordingly. Z-resolution of src must be 1.
    /// If data_too is true, the data is also copied from the source array;
    /// otherwise, this layer is only appropriate formatted and sized to match
    /// the input.
    template <typename T>
    void initFromVoxels(const UT_VoxelArray<T>& src, bool data_too);

    ////////////////////////////////////////////////////////////////
    /// Modifications to layer metadata, in approximate order you call them.

    /// reset metadata to default value
    void setDefault();

    /// Copy everything except the buffer allocations, leaving the result dirty.
    /// This avoids any chance that writing this layer will modify the original layer.
    /// It also avoids shared pointer overhead and keeping buffers around longer than needed.
    void copyMetadata(const IMX_Layer& a)
    {
        IMX_Buffer::copyMetadata(a);
        myBufferToPixelScale = a.myBufferToPixelScale;
        myBufferToPixelTranslate = a.myBufferToPixelTranslate;
        myName = a.myName;
        d = a.d;
        myAttributes = a.myAttributes;
    }

    /// Set pixel aspect ratio. This must be done before setDataWindow
    void setPixelAspectRatio(fpreal64 pa) { wd()->myPixelAspectRatio = pa; }

    /// Set both dataWindow and displayWindow to the same rectangle
    void setDataWindow(int w, int h)  { setDataWindow(0, 0, w, h); }
    void setDataWindow(int x, int y, int w, int h)
    {
        wd()->myDataWindow.set(x, y, w, h);
        setDisplayWindow(x, y, w, h);
    }

    /// Set dataWindow w/o changing displayWindow
    void setDataWindowOnly(int x, int y, int w, int h) { wd()->myDataWindow.set(x, y, w, h); }

    /// Set the displayWindow w/o changing dataWindow
    void setDisplayWindow(int w, int h) { setDisplayWindow(0, 0, w, h); }
    void setDisplayWindow(int x, int y, int w, int h)
    {   setDisplayWindow(UT_Vector2D(x,y), UT_Vector2D(w,h)); }
    void setDisplayWindow(const UT_Vector2D &xy, const UT_Vector2D &wh)
    {
        Metadata *w = wd();
        w->myDisplayWindowSize = wh;
        const fpreal64 pa = w->myPixelAspectRatio;
        const fpreal64 m = (pa * wh[0] >= wh[1]) ? wh[0] / 2 : wh[1] / 2 / pa;
        w->myImageToPixelScale.assign(m, m * pa);
        w->myImageToPixelTranslate = xy + wh / 2;
    }

    /// Set the aspect ratio of displayWindow exactly, centering the new displayWindow
    /// into the old one, two sides will be unchanged, others may be non-integers.
    void setApertureAspect(int n, int d) { setApertureAspect(fpreal64(n)/d); }
    void setApertureAspect(fpreal64 a);

    // set up the camera. You must call these in approximately this order:
    void setProjection(Projection p) { if (d->myProjection != p) wd()->myProjection = p; setBufferXforms(); }
    void setOrtho() { setProjection(ORTHOGRAPHIC); }
    void setPerspective() { setProjection(PERSPECTIVE); }
    void setCameraPosition(const UT_Vector3D &p) { wdf()->myCamera = p; setBufferXforms(); }
    void setCameraZ(fpreal64 z) { wdf()->myCamera[2] = z; setBufferXforms(); }
    void setAperture(fpreal64 mm) { wd()->myApertureMax = mm; setBufferXforms(); }
    void setApertureOffset(const UT_Vector2D &p) { setApertureCenter(p * (2 / d->myApertureMax)); setBufferXforms(); }
    void setApertureCenter(const UT_Vector2D &p) // same but in image units
    { UT_Vector3D &c = wdf()->myCamera; c[0] = -p[0]; c[1] = -p[1]; setBufferXforms(); }
    void setFocalLength(fpreal64 mm) { wdf()->myCamera[2] = 2 * mm / d->myApertureMax; setBufferXforms(); }
    void setFStop(fpreal64 f) { wd()->myFStop = f; setBufferXforms(); }
    void setLensDiameter(fpreal64 mm) { wd()->myFStop = mm / focalLength(); setBufferXforms(); }
    void setClippingRange(const UT_Vector2D &v) { wd()->myClippingRange = v; setBufferXforms(); }
    void setFocusPlane(fpreal64 f) { wd()->myFocusPlane = f; setBufferXforms(); }
    void setShutter(const UT_Vector2D &v) { wd()->myShutter = v; setBufferXforms(); }

    /// set the imageToWorld transform. This can be done at any time
    void setTransform(const UT_Matrix4D& m) { wdf()->myTransform = m; setBufferXforms(); }
    void transform(const UT_Matrix4D& m) { wdf()->myTransform *= m; setBufferXforms(); }
    void preTransform(const UT_Matrix4D& m) { wdf()->myTransform.preMultiply(m); setBufferXforms(); }
    /// set the inverseCameraTransform which will set the transform.
    /// Using this avoids multiple inverts of the matrix to get the value back.
    void setInverseCameraXform(const UT_Matrix4D& m);

    ////////////////////////////////////////////////////////////////
    /// One of these functions *must* be called after changing the display or dataWindow.
    /// This will correctly set up the buffer size and transformations.

    /// Directly set the buffer size. The bufferToPixel transform is set so
    /// this rectangle is mapped to the dataWindow.
    /// Note this overrides the IMX_Buffer method.
    void setBufferSize(int w, int h);

    /// Set buffer size so each buffer pixel is approximately this many pixels.
    /// Value is adjusted down so the width() and height() are an integer number of
    /// buffer pixels. Very tiny numbers are clamped to a minimum.
    void setPixelScale(const UT_Vector2D&);

    /// Make the buffer pixels match the pixels. Same as setPixelScale(1), or
    /// setBufferSize(width(), height())
    void setBufferToPixels()
    {
        myBufferToPixelScale = 1;
        myBufferToPixelTranslate.assign(x()+0.5f, y()+0.5f);
        setBufferSize(width(), height());
        setBufferXforms();
    }

    /// Sets the buffer so isAligned(src) is true. Pretty much the same as
    /// copying the pixelScale but this will allow the buffer edges to
    /// not match the datawindow at all.
    void setAligned(const IMX_Layer& src);

    /// Exactly set pixelScale, however upper-right pixels of buffer may
    /// go outside of the dataWindow. Values outside the range 1..width() are
    /// not recommended.
    void setBufferToPixelScale(const UT_Vector2D &p);

    /// Adjust the transform so the lower-left corner of the dataWindow and buffer
    /// don't match. This value is where the center of the lower-left buffer pixel
    /// is in pixel space.
    void setBufferToPixelTranslate(const UT_Vector2D &p);

    void             setAttributes(const UT_OptionsHolder &attrib) 
                     { myAttributes = attrib; }
    UT_OptionsHolder attributes() const 
                     { return myAttributes; }

    /// Updates the contents of the attributes, first making sure it is
    /// unique.  The provided operator should take a reference to
    /// a UT_Options that it will update.
    /// this->update([](UT_Options &opt) { opt.setOptionS("test", "bar"); });
    template <typename OP>
    void             updateAttributes(const OP &op)
                     { myAttributes.update(op); }

private:
    void setBufferXforms();

    UT_StringHolder myName;

    /// The settings of this are also stored in IMX_Buffer::setBufferXforms.
    /// This is kept here to avoid rounding errors recovering the values
    UT_Vector2D myBufferToPixelScale{1,1};
    UT_Vector2D myBufferToPixelTranslate{0.5, 0.5};

    /// All info that is often identical between images is in this shared object
    struct Metadata
    {   
        // Default size is 1x1, no one should be leaking default sizes
        // but instead should be getting the proper values from
        // context options or from input data.
        UT_DimRect myDataWindow{0, 0, 1, 1}; // overall size
        UT_Vector2D myDisplayWindowSize{1, 1};
        fpreal64 myPixelAspectRatio = 1.0f;
        UT_Vector2D myImageToPixelScale{0.5, 0.5};
        UT_Vector2D myImageToPixelTranslate{0.5, 0.5};

        // Camera:
        Projection myProjection = ORTHOGRAPHIC;
        fpreal64 myApertureMax = 20.955;
        UT_Vector3D myCamera{0, 0, 1}; // camera pos in image space
        UT_Vector2D myClippingRange{0, 2}; // near/far in image space
        fpreal64 myFocusPlane = 0; // relative to origin
        fpreal64 myFStop = 0;
        UT_Vector2D myShutter{-0.25, 0.25}; // usd default is 0,0
        // lens distortion

        // int myFirstFrame = 0; // start of frame range
        // unsigned myNumFrames = 1; // length of frame range
        // fpreal64 myFPS = 30;

        UT_Matrix4D myTransform{1}; // transform to world space
        mutable UT_Matrix4D myICXform{1}; // myTransform.invert.translate(-myCamera)
        mutable bool fixICXform = true; // myICXform is out of date
    };

    UT_SharedPtr<const Metadata> d;

    UT_OptionsHolder             myAttributes;

    Metadata *wd();
    Metadata *wdf() { Metadata *w = wd(); w->fixICXform = true; return w; }
};

using IMX_LayerPtr = UT_SharedPtr<IMX_Layer>;
using IMX_LayerConstPtr = UT_SharedPtr<const IMX_Layer>;