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_CameraParms.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_Layer;
using IMX_LayerPtr = UT_SharedPtr<IMX_Layer>;
using IMX_LayerConstPtr = UT_SharedPtr<const IMX_Layer>;

class IMX_API IMX_Layer : public IMX_Buffer
{
public:

    static constexpr UT_StringLit theCameraMetadataKey = "camera_metadata";

    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());
        setBufferToPixels();
    }

    /// Returns true for successful save.
    bool                 save(std::ostream &os) const;
    bool                 saveJSON(UT_JSONWriter &w) const;

    /// Returns a newly created Layer loaded from the stream, or null
    /// if load failure.
    static IMX_LayerPtr  load(UT_IStream &is);
    static IMX_LayerPtr  loadJSON(UT_JSONParser &p);

    /// Write our fields into the provided options:
    /// THis does not include the stat block, nor properties.
    void        copyMetadataToOptions(UT_Options &opt) const;
    /// Load ourselves from the options, ignoring fields we don't know
    void        updateMetadataFromOptions(const UT_Options &opt);

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

    /// 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; }

    /// World space voxel size, where xy is the pixel size and z is max(x,y).
    UT_Vector3D voxelSize() const;

    /// 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
    IMX_Projection     projection()     const { return statProjection(); }
    bool               isOrtho()        const { return statProjection() == IMX_Projection::IMX_ORTHOGRAPHIC; }
    bool               isPerspective()  const { return statProjection() == IMX_Projection::IMX_PERSPECTIVE; }
    fpreal64           apertureMax()    const { return d->myApertureMax; }
    fpreal64           focalLength()    const { return d->myFocalLength; }
    fpreal64           fStop()          const { return d->myFStop; }
    fpreal64           lensDiameter()   const { return focalLength() * d->myFStop; }
    const UT_Vector2D &clippingRange()  const { return d->myClippingRange; }
    fpreal64           focusDistance()  const { return d->myFocusDistance; }
    const UT_Vector3D &cameraPosition() const { return d->myCamera; }
    fpreal64           cameraZ()        const { return d->myCamera[2]; }
    fpreal64           imagingDist()    const { return cameraZ(); }
    fpreal64           guideScale()     const { return d->myGuideScale; }
    const UT_Vector2D &shutter()        const { return d->myShutter; }

    void getCameraParms(UT_CameraParms &cam_parms, UT_Matrix4D &xform) const;
    void setCameraParms(const UT_CameraParms &cam_parms, const UT_Matrix4D &xform);

    /// 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.
    UT_Matrix4D        baseTransform()     const { return d->myTransform; }
    UT_Matrix4D        transform()         const { return imageToWorldXform(); }
    UT_Matrix4D        imageToWorldXform() const 
    {
        UT_Matrix4D xform = baseTransform();
        xform.prescale(d->myImagingScale);

        // Image space has a unit z scale to world space.
        // If this assert was triggered, we likely missed setBufferXforms().
        UT_ASSERT(SYSisEqual(UT_Vector3D(xform(2)).length2(), 1.0));

        return xform;
    }

    UT_Vector3D         imagingScale() const { return d->myImagingScale; }

    /// 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 bufferToLocalScale() const { return UT_Vector2D(voxelSize()); }
    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)); }

    // Image <-> world
    UT_Vector3D imageToWorld(const UT_Vector2D &v) const
    { return image3ToWorld(UT_Vector3D(v.x(), v.y(), 0)); }
    UT_Vector2D worldToImage(const UT_Vector3D &v) const
    { UT_Vector3D image = worldToImage3(v);
      return UT_Vector2D(image.x(), image.y()); }
    UT_Vector3D image3ToWorld(const UT_Vector3D &v) const;
    UT_Vector3D worldToImage3(const UT_Vector3D &v) const;

    // Image <-> local
    UT_Vector3D imageToLocal(const UT_Vector2D &v) const
    { return UT_Vector3D(v * imageToBufferScale() * bufferToLocalScale()); }
    UT_Vector2D localToImage(const UT_Vector3D &v) const
    { return UT_Vector2D(v) / bufferToLocalScale() / imageToBufferScale(); }
    UT_Vector3D image3ToLocal(const UT_Vector3D &v) const
    {
        UT_Vector3D s(imageToBufferScale() * bufferToLocalScale());
        s.z() = 1;
        return v * s;
    }
    UT_Vector3D localToImage3(const UT_Vector3D &v) const
    {
        UT_Vector3D s(imageToBufferScale() * bufferToLocalScale());
        s.z() = 1;
        return v / s;
    }

    // Local <-> world
    UT_Vector3D localToWorld(const UT_Vector3D &v) const
    { return image3ToWorld(localToImage3(v)); }
    UT_Vector3D worldToLocal(const UT_Vector3D &v) const
    { return image3ToLocal(worldToImage3(v)); }

    /// This is used to convert the layer to a volume, so the resulting
    /// buffer coordinates will line up with the canonical "volume" space.
    /// The z-scale is set so that the volume has isotropic voxels.
    /// If pixels are not square, voxelsize.z is max(voxelsize.x, voxelsize.y).
    UT_Matrix4D bufferUVToWorldXform(fpreal *taper = nullptr) const;
    /// Sets the world transform such that the given transformation becomes this
    /// layer's UV to world.
    void setBufferUVToWorldXform(UT_Matrix4D xform, fpreal taper);

    /// 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();

    /// Reset the transform and camera metadata to the default.
    /// Unlike setDefault(), this does not reset the data or display windows.
    void setCanonical();

    /// 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;
        d = a.d;
        myProperties = a.myProperties;
    }

    /// 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;
    }

    void setDisplayWindow(const UT_DimRect &rect)
    {
        setDisplayWindow(rect.x(), rect.y(), rect.w(), rect.h());
    }

    /// Our "pixel" space 0,0 doesn't necessarily correspond to the
    /// corner of our Image space. This adjusts that offset by panning
    /// both the data and the dispaly window.  Data window is always
    /// integral so this only allows pixel level adjustment.
    void translatePixelOrigin(int dx, int dy)
    {
        Metadata *w = wd();
        w->myImageToPixelTranslate += UT_Vector2D(dx, dy);
        w->myDataWindow.setX(w->myDataWindow.x()+dx);
        w->myDataWindow.setY(w->myDataWindow.y()+dy);
        myBufferToPixelTranslate += UT_Vector2D(dx, dy);
        setBufferXforms();
    }

    /// 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(IMX_Projection p) 
    { if (statProjection() == p) return; 
      setStatProjection(p); setBufferXforms(); }
    void setOrtho() { setProjection(IMX_Projection::IMX_ORTHOGRAPHIC); }
    void setPerspective() { setProjection(IMX_Projection::IMX_PERSPECTIVE); }
    void setCameraPosition(const UT_Vector3D &p) { wdf()->myCamera = p; setBufferXforms(); }
    void setCameraZ(fpreal64 z) { wdf()->myCamera[2] = z; setBufferXforms(); }
    void setImagingDist(fpreal64 z);
    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()->myFocalLength = mm; 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 setFocusDistance(fpreal64 f) { wd()->myFocusDistance = f; setBufferXforms(); }
    void setShutter(const UT_Vector2D &v) { wd()->myShutter = v; setBufferXforms(); }

    /// this can be set at any time as it doesn't affect the buffer's xforms
    /// it's only used to change the display of metadata only layers
    /// as they display as cameras
    void setGuideScale(fpreal64 scale) { wd()->myGuideScale = scale; }
    
    /// set the imageToWorld transform. This can be done at any time
    void setBaseTransform(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(); }
    void setImageToWorldXform(const UT_Matrix4D &m);
    /// 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.
    /// ALL of these _may_ freeBuffers() and make your layer dirty(),
    /// especially with constant source layers.  They may leave it intact,
    /// if resizing isn't needed, but that should not be relied upon.

    /// 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             setProperties(const UT_OptionsHolder &props) 
                     { myProperties = props; }
    UT_OptionsHolder properties() const 
                     { return myProperties; }

    /// Updates the contents of the properties, 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             updateProperties(const OP &op)
                     { myProperties.update(op); }

    /// Layer registration to allow layers to be converted
    /// to integers across HOM boundaries.
    
    /// Registers & returns the handle, adding the handle to the registered
    /// list
    static int       registerLayer(IMX_LayerConstPtr layer, UT_IntArray &registered);
    /// Unregister all layers corresponding to the provided list,
    /// erase the list afterwards.   Assertion if handle wasn't regsitered
    static void      unregisterLayers(UT_IntArray &registered);
    /// Look up a registered layer by handle.
    static IMX_LayerConstPtr lookupLayer(int handle);

    /// a layer that is metadata only does not have a buffer
    /// and is represented in the viewport by a camera along 
    /// with an imaging plane
    /// layers marked metadata only can only be plugged into metadata inputs
    void setIsMetadataOnly(bool v) { myIsMetadataOnly = v; }
    bool isMetadataOnly() const    { return myIsMetadataOnly; }

    /// Compute useful aggregate properties of the layer.
    /// For integer layers, use computeMinI() and computeMaxI().
    fpreal64    computeMin(int channel = 0) const;
    fpreal64    computeMax(int channel = 0) const;
    fpreal64    computeMinLength() const;
    fpreal64    computeMaxLength() const;
    fpreal64    computeAverage(int channel = 0) const;
    exint       computeMinI(int channel = 0) const;
    exint       computeMaxI(int channel = 0) const;

private:
    void setBufferXforms();

    /// 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 is in stat.
        fpreal64        myApertureMax = 20.955;
        fpreal64        myFocalLength = 10.4775;
        // camera z implicitly defines the imaging plane's distance
        // from the camera, as our imaging plane is at zero.
        // Camera position is in imaging space-relative World space.
        // It thus always represents world-distance offsets, so scaling
        // myTransform would leave camera unscaled.
        // It is relative to the origin of the imaging space, using
        // the space (possibly non-ortho, but normalized) defined by 
        // myTransform.
        UT_Vector3D     myCamera{0, 0, 1}; // camera pos in image-relative world space
        // The x and y components are the size of imaging plane, 
        // Has to update with cameraz/focallength/aperture
        // Could be baked into myTransform, but then we'd lose precision
        // on updates.
        // The z component is the reciprocal of myTransform's z-scale,
        // and ensures that image space has a unit z scale to world space.
        UT_Vector3D     myImagingScale{1, 1, 1};
        // The scale sizes of the axes of the imaging space at the
        // imaging origin (so independent of taper)  This is baked
        // into myTransform and is used to convert imagelengths to 
        // world lengths.
        UT_Vector3D     myTransformScale{1, 1, 1};
        UT_Vector2D     myClippingRange{0, 2}; // near/far in image space
        fpreal64        myFocusDistance = 0; // relative to origin
        fpreal64        myFStop = 0;
        UT_Vector2D     myShutter{-0.25, 0.25}; // usd default is 0,0

        // only used for metadata only layers as they draw as cameras
        fpreal64        myGuideScale = 1.0;

        // lens distortion

        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             myProperties;

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

    bool myIsMetadataOnly = false;
};