GA_PrimVolumeXform.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.
 *
 * NAME:        GA_PrimVolume.h ( GA Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GA_PrimVolumeXform__
#define __GA_PrimVolumeXform__

#include <GA/GA_API.h>
#include <UT/UT_BoundingBox.h>
#include <UT/UT_BoundingRect.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>

class GA_Detail;

///
/// Stores the transform associated with a volume, allowing the
/// to/from code to be inlined outside of this library.
///
class GA_API GA_PrimVolumeXform
{
public:
    // Converts from world space to [0,1] space.
    inline UT_Vector3 toVoxelSpace(UT_Vector3 pos) const
    {
        pos -= myCenter;
        pos *= myInverseXform;

        // Undo any taper effect.
        if (myHasTaper)
        {
            fpreal              zscale = (1 - pos.z()) * 0.5f;
            fpreal              taperx = 1 + (-1 + myTaperX) * zscale;
            fpreal              tapery = 1 + (-1 + myTaperY) * zscale;

            if (taperx == 0.0f)
                pos.x() = 0.0;
            else
                pos.x() /= taperx;
            if (tapery == 0.0f)
                pos.y() = 0.0;
            else
                pos.y() /= tapery;
        }

        // This gets us a value in the -1 to 1 box.  We need to evaluate
        // in the 0 to 1 box, however.
        pos.x() += 1;
        pos.y() += 1;
        pos.z() += 1;
        pos *= 0.5;

        return pos;
    }

    // Converts from [0,1] space over the voxels to world space
    inline UT_Vector3 fromVoxelSpace(UT_Vector3 pos) const
    {
        // convert to -1 to 1 box.
        pos.x() -= 0.5;
        pos.y() -= 0.5;
        pos.z() -= 0.5;
        pos *= 2;

        // Apply the taper effect.
        if (myHasTaper)
        {
            fpreal              zscale = (1 - pos.z()) * 0.5f;
            fpreal              taperx = 1 + (-1 + myTaperX) * zscale;
            fpreal              tapery = 1 + (-1 + myTaperY) * zscale;

            pos.x() *= taperx;
            pos.y() *= tapery;
        }
        // Convert to world space.
        pos *= myXform;
        pos += myCenter;
        
        return pos;
    }

    // Returns jacobian of the transformation `toVoxelSpace` at point `pos`
    //
    // If `myHasTaper() == false` then the jacobian does not depend on the position `pos`.
    //
    // Vector `v` located at point `pos` gets transformed by `toVoxelSpace` map as:
    // v ->  v * toVoxelSpaceJacobian(pos)
    //
    // `toVoxelSpaceJacobian(pos)` is inverse of `fromVoxelSpaceJacobian(toVoxelSpace(pos))`
    inline UT_Matrix3 toVoxelSpaceJacobian(UT_Vector3 pos) const
    {
        if (!myHasTaper)
            return myInverseXform*0.5;

        pos -= myCenter;
        pos *= myInverseXform;

        float zscale = (1 - pos.z()) * 0.5f;
        float taperx = 1 + (-1 + myTaperX) * zscale;
        float tapery = 1 + (-1 + myTaperY) * zscale;

        UT_Matrix3 tapergrad{
                1.f / taperx,
                0.f,
                0.f,
                0.f,
                1.f / tapery,
                0.f,
                0.5f * (myTaperX - 1.f) * pos.x() / (taperx * taperx),
                0.5f * (myTaperY - 1.f) * pos.y() / (tapery * tapery),
                1.f};

        return myInverseXform*tapergrad*0.5;
    }

    // Returns jacobian of the transformation `fromVoxelSpace` at point `pos`
    //
    // If `myHasTaper == false` then the jacobian does not depend on the position `pos`.
    //
    // Vector `v` located at point `pos` gets transformed by `fromVoxelSpace` map as:
    // v ->  v * fromVoxelSpaceJacobian(pos)
    //
    // `fromVoxelSpaceJacobian(pos)` is inverse of `toVoxelSpaceJacobian(fromVoxelSpace(pos))`
    inline UT_Matrix3 fromVoxelSpaceJacobian(UT_Vector3 pos) const
    {
        if (!myHasTaper)
            return 2.f*myXform;

        pos.x() -= 0.5;
        pos.y() -= 0.5;
        pos.z() -= 0.5;
        pos *= 2;

        float zscale = (1 - pos.z()) * 0.5f;
        float taperx = 1 + (-1 + myTaperX) * zscale;
        float tapery = 1 + (-1 + myTaperY) * zscale;
        
        UT_Matrix3 tapergrad{
                1.f * taperx,
                0.f,
                0.f,
                0.f,
                1.f * tapery,
                0.f,
                0.5f * (1.f - myTaperX) * pos.x(),
                0.5f * (1.f - myTaperY) * pos.y(),
                1.f};

        return 2.f*tapergrad*myXform;
    }


    inline void transform(const UT_Matrix4 &xform)
    {
        myCenter *= xform;
        myXform.multiply3(xform);
        myInverseXform = myXform;
        myInverseXform.invert();
    }

    inline void transform(const UT_Matrix4D &xform)
    {
        myCenter *= xform;
        myXform *= UT_Matrix3D(xform);
        myInverseXform = myXform;
        myInverseXform.invert();
    }

    inline void toVoxelSpace(UT_BoundingBox &box) const
    {
        int             i;
        UT_Vector3      v[8] = {
            UT_Vector3(box.xmin(), box.ymin(), box.zmin()),
            UT_Vector3(box.xmin(), box.ymin(), box.zmax()),
            UT_Vector3(box.xmin(), box.ymax(), box.zmin()),
            UT_Vector3(box.xmin(), box.ymax(), box.zmax()),
            UT_Vector3(box.xmax(), box.ymin(), box.zmin()),
            UT_Vector3(box.xmax(), box.ymin(), box.zmax()),
            UT_Vector3(box.xmax(), box.ymax(), box.zmin()),
            UT_Vector3(box.xmax(), box.ymax(), box.zmax()),
        };

        box.initBounds();
        for (i = 0; i < 8; i++)
        {
            box.enlargeBounds(toVoxelSpace(v[i]));
        }
    }

    inline void fromVoxelSpace(UT_BoundingBox &box) const
    {
        int             i;
        UT_Vector3      v[8] = {
            UT_Vector3(box.xmin(), box.ymin(), box.zmin()),
            UT_Vector3(box.xmin(), box.ymin(), box.zmax()),
            UT_Vector3(box.xmin(), box.ymax(), box.zmin()),
            UT_Vector3(box.xmin(), box.ymax(), box.zmax()),
            UT_Vector3(box.xmax(), box.ymin(), box.zmin()),
            UT_Vector3(box.xmax(), box.ymin(), box.zmax()),
            UT_Vector3(box.xmax(), box.ymax(), box.zmin()),
            UT_Vector3(box.xmax(), box.ymax(), box.zmax()),
        };

        box.initBounds();
        for (i = 0; i < 8; i++)
        {
            box.enlargeBounds(fromVoxelSpace(v[i]));
        }
    }

    /// Returns the *un-tapered* matrix4 corresponding to fromVoxelSpace().
    /// @{
    void getTransform4(UT_Matrix4F &matx) const;
    void getTransform4(UT_Matrix4D &matx) const;
    /// @}

    /// Returns if the transform is flagged as having a taper.
    bool isTapered() const { return myHasTaper; }

    /// Compute the size for this transform (relative to myCenter)
    UT_Vector3R computeSize() const;

    // NOTE: This ordering is saved in .hip files!
    enum SamplingType
    {
        NON_SQUARE = 0,
        X_AXIS,
        Y_AXIS,
        Z_AXIS,
        MAX_AXIS,
        BY_SIZE
    };

    /// Convert the "uniformsamples" parm menu item index to a sampling type
    static SamplingType     samplingType(int i)
                                { return SamplingType(i); }

    /// Compute the resolution (and size) from a common set of parameters.
    /// If twod_axis is one of [0,1,2], then that axis clamped to a divisions
    /// of 1 and a size of 0.  The number of divisions is returned with size
    /// set to div_size multiplied by divisions before the z_div_scale.
    static UT_Vector3R      computeResolution(
                                SamplingType sampling_type,
                                const UT_Vector3R &non_uniform_divs,
                                fpreal uniform_divs,
                                fpreal div_size,
                                fpreal z_div_scale,
                                UT_Vector3R &size_inout,
                                int twod_axis = -1);

    /// Compute a space transform from center, size, and taper
    static GA_PrimVolumeXform frustumSpaceTransform(
                                    const UT_Vector3R &size,
                                    const UT_Vector3R &center,
                                    fpreal taper_x, fpreal taper_y);

    static GA_PrimVolumeXform cameraFrustum(
                                    fpreal focal,
                                    fpreal aperture,
                                    const UT_Vector2R &image_res,
                                    fpreal pixel_aspect,
                                    bool is_ortho,
                                    fpreal ortho_zoom,
                                    fpreal clip_near,
                                    fpreal clip_far,
                                    bool use_cam_window,
                                    const UT_BoundingRectR &cam_window,
                                    const UT_BoundingRectR &cam_crop,
                                    const UT_BoundingRectR &window,
                                    const UT_Matrix4R &post_xform,
                                    const GA_Detail *match_src);

public:
    // @{
    void         save(std::ostream &os, bool binary = false) const;
    bool         load(UT_IStream &is);
    // @}

    void                init()
                        {
                            myCenter.assign(0, 0, 0);
                            myXform.identity();
                            myInverseXform.identity();
                            myHasTaper = false;
                            myTaperX = 1.0;
                            myTaperY = 1.0;
                        }

    bool                operator==(const GA_PrimVolumeXform &x) const
                        {
                            return
                                myXform == x.myXform &&
                                myCenter == x.myCenter &&
                                myHasTaper == x.myHasTaper &&
                                myTaperX == x.myTaperX &&
                                myTaperY == x.myTaperY;
                        }

    UT_Matrix3          myXform, myInverseXform;
    UT_Vector3          myCenter;
    bool                myHasTaper;
    float               myTaperX, myTaperY;
};

#endif