GEO/GEO_PrimVolume.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.
 *
 * Produced by:
 *      Jeff Lait
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        GEO_PrimVolume.h ( GEO Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GEO_PrimVolume__
#define __GEO_PrimVolume__

#include <UT/UT_VoxelArray.h>

#include "GEO_API.h"
#include "GEO_Vertex.h"
#include "GEO_Primitive.h"

class UT_JSONWriter;
class UT_JSONParser;
class GA_SaveMap;
class GA_LoadMap;

enum GEO_VolumeBorder
{
    GEO_VOLUMEBORDER_CONSTANT,
    GEO_VOLUMEBORDER_REPEAT,
    GEO_VOLUMEBORDER_STREAK,
    GEO_VOLUMEBORDER_SDF,
    NUM_GEO_VOLUMEBORDERS
};

enum GEO_VolumeVis
{
    GEO_VOLUMEVIS_SMOKE,
    GEO_VOLUMEVIS_RAINBOW,
    GEO_VOLUMEVIS_ISO,
    GEO_VOLUMEVIS_INVISIBLE,
    NUM_GEO_VOLUMEVIS
};


///
/// Stores the transform associated with a volume, allowing the
/// to/from code to be inlined outside of this library.
///
class GEO_API GEO_PrimVolumeXform
{
public:
    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;
    }

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

    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]));
        }
    }

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

class GEO_API GEO_PrimVolume : public GEO_Primitive
{
public:
     GEO_PrimVolume(GEO_Detail *d, GA_Offset offset = GA_INVALID_OFFSET);
     virtual ~GEO_PrimVolume();

//
//  Methods common to all primitives.
    virtual int          getBBox(UT_BoundingBox *bbox) const;
    virtual void         addToBSphere(UT_BoundingSphere *bsphere) const;
    virtual void         enlargePointBounds(UT_BoundingBox &box) const;
    /// @{
    /// Enlarge a bounding box by the bounding box of the primitive.  A
    /// return value of false indicates an error in the operation, most
    /// likely an invalid P.  For any attribute other than the position
    /// these methods simply enlarge the bounding box based on the vertex.
    virtual bool         enlargeBoundingBox(UT_BoundingRect &b,
                                        const GA_Attribute *P) const;
    virtual bool         enlargeBoundingBox(UT_BoundingBox &b,
                                        const GA_Attribute *P) const;
    /// @}
    /// Enlarge a bounding sphere to encompass the primitive.  A return value
    /// of false indicates an error in the operation, most likely an invalid
    /// P.  For any attribute other than the position this method simply
    /// enlarges the sphere based on the vertex.
    virtual bool         enlargeBoundingSphere(UT_BoundingSphere &b,
                                        const GA_Attribute *P) const;
    /// For a volume the barycenter is the same as the point.
    virtual UT_Vector3   baryCenter() const;
    virtual UT_Vector3   computeNormal() const;
    virtual bool         saveH9(ostream &os, bool binary,
                           const UT_RefArray<GA_AttribSaveDataH9> &prim_attribs,
                           const UT_RefArray<GA_AttribSaveDataH9> &vtx_attribs)
                            const;
    virtual bool         loadH9(UT_IStream &is,
                           const UT_RefArray<GA_AttribLoadDataH9> &prim_attribs,
                           const UT_RefArray<GA_AttribLoadDataH9> &vtx_attribs);

    bool                saveVoxelArray(UT_JSONWriter &w,
                                const GA_SaveMap &map) const;
    bool                loadVoxelArray(UT_JSONParser &p,
                                const GA_LoadMap &map);

    bool                loadRes(const UT_JSONValue &jval);
    bool                saveBorder(UT_JSONWriter &w,
                                const GA_SaveMap &map) const;
    bool                loadBorder(UT_JSONParser &p,
                                const GA_LoadMap &map);
    bool                saveCompression(UT_JSONWriter &w,
                                const GA_SaveMap &map) const;
    bool                loadCompression(UT_JSONParser &p,
                                const GA_LoadMap &map);
    bool                saveVisualization(UT_JSONWriter &w,
                                const GA_SaveMap &map) const;
    bool                loadVisualization(UT_JSONParser &p,
                                const GA_LoadMap &map);

    // Transforms the matrix associated with this primitive.  The
    // translate component is ignored: Translate the vertices of
    // the primitive to translate the primitive.
    // This only works with quadrics (sphere, tube, metaballs) and volumes.
    virtual void                 transform(const UT_Matrix4 &mat);

    virtual void                 untransform(void);
    virtual GEO_Primitive       *copy(int preserve_shared_pts = 0) const;
    virtual void        copyPrimitive(const GEO_Primitive *src, 
                                GEO_Point **ptredirect);
    virtual void        copyUnwiredForMerge(const GA_Primitive *src,
                                            const GA_MergeMap &map);
    virtual void        addPointRefToGroup(GA_PointGroup &grp) const;

    virtual int         vertexApply(int (*a)(GEO_Vertex, void *), void *);
    virtual int         vertexApply(int (*a)(const GEO_Vertex &, void *),
                                    void *) const;
    virtual void        reverse(void); 

    virtual GA_Size     getVertexCount() const;
    virtual GA_Offset   getVertexOffset(GA_Size index) const;

    // Take the whole set of points into consideration when applying the
    // point removal operation to this primitive. The method returns 0 if
    // successful, -1 if it failed because it would have become degenerate,
    // and -2 if it failed because it would have had to remove the primitive
    // altogether.
    virtual int          detachPoints (GA_PointGroup &grp);

    /// Before a point is deleted, all primitives using the point will be
    /// notified.  The method should return "false" if it's impossible to
    /// delete the point.  Otherwise, the vertices should be removed.
    virtual GA_DereferenceStatus        dereferencePoint(GA_Offset point,
                                                bool dry_run=false);
    virtual GA_DereferenceStatus        dereferencePoints(
                                                const GA_RangeMemberQuery &pt_q,
                                                bool dry_run=false);

    virtual bool         isDegenerate() const;

    // Map the normalized length (distance value [0,1]) parameter to the unit 
    // parameterization of the primitve
    virtual void         unitLengthToUnitPair(float  ulength, float  vlength,
                                              float &uparm,  float &vparm)const;

    virtual void         unitToUnitLengthPair(float  uparm,   float  vparm,
                                              float &ulength, float &vlength)
                                                                        const;

    virtual fpreal       calcVolume(const UT_Vector3 &refpt) const;
    virtual fpreal       calcArea() const;

//
//  Methods unique to PrimVolume.

    void                 setVertex(GEO_Point *ppt)
                         {
                             wireVertex(myVertex,ppt ? ppt->getMapOffset()
                                            : GA_INVALID_OFFSET);
                         }
    void                 setVertexPoint(GA_Offset pt)
                         {
                             wireVertex(myVertex, pt);
                         }

    /// This method assigns a preallocated vertex to the quadric, optionally
    /// creating the topological link between the primitive and new vertex.
    void                 assignVertex(GA_Offset new_vtx, bool update_topology);

    // Have we been deactivated and stashed?
    virtual              void   stashed(int onoff,
                                        GA_Offset offset = GA_INVALID_OFFSET);

    const UT_Matrix3    &getTransform(void) const { return myXform; }
    void                 setTransform(const UT_Matrix3 &m) 
                         { myXform = m; 
                           myInverseXform = m;
                           myInverseXform.invert();
                         }

    void                 getTransform4(      UT_Matrix4 &matx) const;
    void                 getTransform4(      UT_DMatrix4 &matx) const;
    void                 setTransform4(const UT_Matrix4 &matx);
    void                 setTransform4(const UT_DMatrix4 &matx);

    /// Converts from world space to local space.
    const UT_Matrix3    &getInverseTransform() const { return myInverseXform; }
    void                 getInverseTransform4(UT_Matrix4 &matx) const;

    float                getTaperX(void) const { return myTaperX; }
    void                 setTaperX(float t) { myTaperX = t; }
    float                getTaperY(void) const { return myTaperY; }
    void                 setTaperY(float t) { myTaperY = t; }

    /// True if the two volumes have same resolution and map the
    /// same indices to the same positions.
    bool                 isAligned(const GEO_PrimVolume *vol) const;

    /// Returns the POD class which can convert to and from
    /// voxel space.
    GEO_PrimVolumeXform  getSpaceTransform() const;

    /// Converts from world space to 0..1 voxel space.
    UT_Vector3           toVoxelSpace(const UT_Vector3 &pos) const;
    /// Converts from 0..1 voxel space to world space.
    UT_Vector3           fromVoxelSpace(const UT_Vector3 &pos) const;

    /// Converts from world space to 0..1 voxel space.
    void                 toVoxelSpace(UT_BoundingBox &box) const;
    /// Converts from 0..1 voxel space to world space.
    void                 fromVoxelSpace(UT_BoundingBox &box) const;

    /// Copies the given voxel array and makes it our own voxel array.
    void                 setVoxels(const UT_VoxelArrayF *vox);
    void                 setVoxels(UT_VoxelArrayHandleF handle);

    /// Takes ownership of the voxel array, caller should not refer
    /// to vox any more.
    void                 stealVoxels(UT_VoxelArrayF *vox);

    /// Returns a handle to a voxel array containing our data.
    /// This is should be thought of a copy of the data - changing
    /// it will not change the underlying data, casting this to
    /// a write handle will write to the newly created handle, not
    /// the one stored in this volume.
    UT_VoxelArrayHandleF        getVoxelHandle() const;

    /// This is a handle that you can write to and affect the volume.
    UT_VoxelArrayWriteHandleF   getVoxelWriteHandle();

    /// Convert an index in the voxel array into the corresponidng worldspace 
    /// location
    bool                 indexToPos(int x, int y, int z, UT_Vector3 &pos) const;
    void                 findexToPos(UT_Vector3 index, UT_Vector3 &pos) const;

    /// Returns true if the given point is entirely inside the volume's
    /// definition, ie, if posToIndex would return true.
    bool                 isInside(UT_Vector3 pos) const;

    /// Returns true only if strictly inside.  This means only actual
    /// voxel samples will be used for interpolation, so the boundary
    /// conditions will be unused
    bool                 isInsideStrict(UT_Vector3 pos) const;

    /// Convert a 3d position into the closest index value.  Returns
    /// false if the resulting index was out of range (but still sets it)
    bool                 posToIndex(UT_Vector3 pos, int &x, int &y, int &z) const;      

    /// Evaluate the voxel value at the given world space position.
    fpreal               getValue(const UT_Vector3 &pos) const;
    UT_Vector3           getGradient(const UT_Vector3 &pos) const;

    /// By passing in a specific read handle and inverse transform
    /// we can accelerate the getValue()
    fpreal               getValue(const UT_Vector3 &pos, const UT_VoxelArrayReadHandleF &handle) const;

    /// Evaluate the specific voxel indexed from 0,0,0.
    fpreal               getValueAtIndex(int ix, int iy, int iz) const;
    /// Returns the resolution of the voxel array.
    void                 getRes(int &rx, int &ry, int &rz) const;
    /// Computes the voxel diameter by taking a step in x, y, and z
    /// converting to world space and taking the length of that vector.
    fpreal               getVoxelDiameter() const;

    /// Returns the length of the voxel when you take an x, y, and z step
    UT_Vector3           getVoxelSize() const;

    /// Computes the total density of the volume, scaled by
    /// the volume's size.  Negative values will be ignored.
    fpreal               calcPositiveDensity() const;

    /// Compute useful aggregate properties of the volume.
    fpreal               calcMinimum() const;
    fpreal               calcMaximum() const;
    fpreal               calcAverage() const;

    /// Determines if we should be treated as an SDF.  This means
    /// our function will continue to increase outside of the bounding
    /// box according to the distance to the bounding box.
    bool                 isSDF() const { return myIsSDF; }

    /// Get the border options in terms of GEO's values.
    static const char           *getBorderToken(GEO_VolumeBorder border);
    static GEO_VolumeBorder      getBorderEnum(const char *token,
                                    GEO_VolumeBorder def=GEO_VOLUMEBORDER_STREAK);
    void                 setBorder(GEO_VolumeBorder border, fpreal val);
    GEO_VolumeBorder     getBorder() const;
    fpreal               getBorderValue() const;

    /// Control the compression of these objects.
    fpreal               getCompressionTolerance() const;
    void                 setCompressionTolerance(fpreal tol);
    void                 recompress();

    /// Control how we display this in the viewport
    static const char           *getVisualizationToken(GEO_VolumeVis vis);
    static GEO_VolumeVis         getVisualizationEnum(const char *vis,
                                        GEO_VolumeVis def=GEO_VOLUMEVIS_SMOKE);
    void                 setVisualization(GEO_VolumeVis vis, fpreal iso, fpreal density);
    fpreal               getVisIso() const { return myVisIso; }
    fpreal               getVisDensity() const { return myVisDensity; }
    GEO_VolumeVis        getVisualization() const { return myVisMode; }

    virtual const GA_PrimitiveJSON      *getJSON() const;

    /// Voxel traverser.  This serializes the voxels into a linear array of
    /// scalar data.
    class serialize
    {
    public:
        serialize()
            : myVoxels()
            , myBorder(0)
            , myXres(0)
            , myYres(0)
            , myZres(0)
            , myEntries(0)
            , myCurr(0)
        {}
        serialize(const serialize &src)
            : myVoxels(src.myVoxels)
            , myBorder(src.myBorder)
            , myXres(src.myXres)
            , myYres(src.myYres)
            , myZres(src.myZres)
            , myEntries(src.myEntries)
            , myCurr(src.myCurr)
        {}
        serialize       &operator=(const serialize &src)
                        {
                             myVoxels = src.myVoxels;
                             myBorder = src.myBorder;
                             myXres = src.myXres;
                             myYres = src.myYres;
                             myZres = src.myZres;
                             myEntries = src.myEntries;
                             myCurr = src.myCurr;
                             return *this;
                        }
        /// Random access of a voxel value
        fpreal          getVoxel(exint index) const
                        {
                            if (index >= 0 && index < myEntries)
                            {
                                exint   x, y, z;
                                x = index % myXres;
                                index = (index - x) / myXres;
                                y = index % myYres;
                                index = (index - y) / myYres;
                                z = index % myZres;
                                return (*myVoxels)(x, y, z);
                            }
                            return myBorder;
                        }

        /// @{
        /// Iterator interface
        bool            atEnd() const   { return myCurr >= myEntries; }
        void            rewind()        { myCurr = 0; }
        void            advance()       { myCurr++; }
        serialize       &operator++()   { advance(); return *this; }
        /// No post increment as it is harmful.
        /// @}
        /// Iterator access methods
        exint           entries() const { return myEntries; }
        exint           index() const   { return myCurr; }
        fpreal          voxel() const   { return getVoxel(myCurr); }
    private:
        serialize(const GEO_PrimVolume &prim)
            : myVoxels(prim.getVoxelHandle())
            , myCurr(0)
        {
            prim.getRes(myXres, myYres, myZres);
            myBorder = prim.getBorderValue();
            myEntries = myXres*myYres*myZres;
        }
        UT_VoxelArrayReadHandleF        myVoxels;
        fpreal                          myBorder;
        exint                           myCurr, myEntries;
        int                             myXres, myYres, myZres;
        friend class GEO_PrimVolume;
    };
    serialize   getSerialize() const    { return serialize(*this); }

protected:
    GEO_PrimVolume(const GA_MergeMap &map,
                    GEO_Detail &detail,
                    GA_Offset offset,
                    const GEO_PrimVolume &src);
    static GA_PrimitiveFamilyMask       buildFamilyMask()
                                            { return GA_FAMILY_NONE; }

    /// Defragmentation
    virtual void        swapVertexOffsets(const GA_Defragment &defrag);

    /// All subclasses should call this method to register the curve intrinsics.
    /// @see GA_IntrinsicManager
    static GA_IntrinsicManager::Registrar
                        registerIntrinsics(GA_PrimitiveDefinition &defn);
    /// @{
    /// Evaluate intrinsics
    virtual int         localIntrinsicTupleSize(
                                const GA_IntrinsicEval &eval) const;
    virtual int         localGetIntrinsicS(const GA_IntrinsicEval &eval,
                                UT_String &value) const;
    virtual int         localGetIntrinsicSA(const GA_IntrinsicEval &eval,
                                UT_StringArray &value) const;
    virtual int         localGetIntrinsicI(const GA_IntrinsicEval &eval,
                                int64 *value, GA_Size size) const;
    virtual int         localGetIntrinsicF(const GA_IntrinsicEval &eval,
                                fpreal *value, GA_Size size) const;
    virtual int         localSetIntrinsicSA(const GA_IntrinsicEval &eval,
                                const UT_StringArray &value);
    virtual int         localSetIntrinsicSS(const GA_IntrinsicEval &eval,
                                const char **value, GA_Size size);
    virtual int         localSetIntrinsicI(const GA_IntrinsicEval &eval,
                                const int64 *value, GA_Size size);
    virtual int         localSetIntrinsicF(const GA_IntrinsicEval &eval,
                                const fpreal *value, GA_Size size);
    /// @}

    // Methods for finding out about point references
    virtual void        copyOffsetPrimitive(const GEO_Primitive *src,
                                            int basept);
    virtual bool        savePrivateH9(ostream &os, bool binary) const;
    virtual bool        loadPrivateH9(UT_IStream &is);
    virtual int         isPointUsed(GA_GBPoint *pt) const;

    // A versioned loading method.
    bool                loadVoxelDataH9(UT_IStream &is,
                                        UT_VoxelArrayWriteHandleF voxels,
                                        int version);

    GA_Offset           vertexPoint() const
                            { return getDetail().vertexPoint(myVertex); }

    UT_VoxelArrayHandleF         myVoxelHandle;

    virtual bool        evaluatePointRefMap(GA_Offset result_vtx,
                                    GA_AttributeRefMap &hlist,
                                    fpreal u, fpreal v, uint du, uint dv) const;
    virtual int          evaluatePointV4( UT_Vector4 &pos, float u, float v = 0,
                                        unsigned du=0, unsigned dv=0) const
                         {
                            return GEO_Primitive::evaluatePoint(pos, u, v,
                                        du, dv);
                         }
    virtual bool         evaluateBaryCenterRefMap(GA_Offset result_vertex,
                                        GA_AttributeRefMap &hlist) const;    
    
    virtual bool         evaluateInteriorPointRefMap(GA_Offset result,
                                        GA_AttributeRefMap &map,
                                        fpreal u, fpreal v, fpreal w = 0) const;
    virtual int          evaluateInteriorPointV4(UT_Vector4 &pos,
                                       fpreal u, fpreal v, fpreal w = 0) const;

private:
    GA_Offset           myVertex;       // My vertex
    UT_Matrix3          myXform;        // My Transform
    UT_Matrix3          myInverseXform; // My inverse transform
    bool                myIsSDF : 1;    // Are we a signed distance field?

    GEO_VolumeVis       myVisMode;
    fpreal              myVisIso;
    fpreal              myVisDensity;

    // The taper is the radius of the bottom half, z-minus, of the default box
    // The top half's radius is one.  These radii are then modified by
    // myXform.
    fpreal              myTaperX, myTaperY;

    friend ostream      &operator<<(ostream &os, const GEO_PrimVolume &d)
                        {
                            d.saveH9(os, 0,
                                     GEO_Primitive::theEmptySaveAttribs,
                                     GEO_Primitive::theEmptySaveAttribs);
                            return os;
                        }
    // This is used to track whether we are stashed.  That tells us
    // if we need to tell update our detail's count of the number
    // of yucky quadric-like primitives.
    bool                myStashedState : 1;
};

#endif

---