GU_SurfaceDistance.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:        GU_SurfaceDistance.h (GU Library, C++)
 *
 * COMMENTS:
 *      Approximates geodesic distance.
 *      This code is related to the soft falloff code in GEO_Transform, but is
 *      mostly a replacement for it as of Houdini 16.5. 
 */

#ifndef __GU_SurfaceDistance_h__
#define __GU_SurfaceDistance_h__

#include "GU_API.h"

#include <GA/GA_Types.h>
#include <GA/GA_Handle.h>
#include <GEO/GEO_Detail.h>
#include <UT/UT_Function.h>


// keep this synced with the parameter in $PRM/PRM_Shared.C
enum GU_SoftDistanceMetric
{
    GU_SOFT_CUSTOM = 0,
    GU_SOFT_DISTANCE_ALONG_CONNECTED_EDGES,
    GU_SOFT_GLOBAL_DISTANCE,
    GU_SOFT_GLOBAL_DISTANCE_WITH_CONNECTIVITY,
    GU_SOFT_SURFACE_DISTANCE,
    GU_SOFT_METRIC_INVALID
};

// Utility class for measuring distances along a surface (or along edges).
// Call findDistances() to discover distances to points within 'max_dist' from
// the seed points/position.
//
// The geometry given to the constructor will be converted to polygons (or
// polylines if measuring along edges).  The converted geometry can be explored
// with methods on this class.
class GU_API GU_SurfaceDistance
{
public:
    GU_SurfaceDistance();
    GU_SurfaceDistance(const GEO_Detail &gdp, bool as_polylines);

    // Returns true if the converted geometry representation is polylines.
    bool getAsPolylines() const { return myAsPolylines; }

    // Returns number of polygons in the converted geometry.
    exint getNumPrimitives() const { return myPrimEnd.entries(); }

    // Returns range of vertices for the given converted polygon.
    void getVertexRange(exint pr, exint &start, exint &end) const
    {
        end = myPrimEnd(pr);
        start = pr ? myPrimEnd(pr - 1) : 0;
    }

    // Returns the first vertex referencing the given point.
    exint firstVertex(GA_Offset pt) const { return myPtFirstVtx(exint(pt)); }

    // Returns the next vertex referencing the same point.
    exint nextVertex(exint vtx) const { return myVtxNextVtx(vtx); }

    // Returns the point the given vertex references.
    GA_Offset vertexPoint(exint vtx) const { return myVtxPt(vtx); }

    // Returns the primitive to which the given vertex belongs.
    exint vertexPrimitive(exint vtx) const { return myVtxPrim(vtx); }

    // Seeds known distances for a set of points.  All found distances within
    // 'max_dist' are reported by calling 'func'.
    void findDistances(const GA_ROHandleV3 &p_attr,
                       fpreal max_dist, // negative means no max_dist
                       const GA_OffsetArray &pts,
                       const UT_FloatArray &dists,
                       const UT_Function<void(GA_Offset, fpreal)> &func) const;

    // Seeds known distances for a set of points.  All found distances within
    // 'max_dist' are reported by calling 'func'.
    void findDistances(const GA_ROHandleV3 &p_attr,
                       fpreal max_dist, // negative means no max_dist
                       const GA_OffsetArray &pts,
                       const UT_FloatArray &dists,
                       const UT_Array<exint> &src,
                       const UT_Function<void(GA_Offset, fpreal, exint)> &func) const;

    int64   getMemoryUsage(bool inclusive) const;
private:
    void internalVertex(GA_Offset pt);
    void internalEndPrimitive() { myPrimEnd.append(myVtxPt.entries()); }

    // The following are used by convertPrimitive() to record polygon
    // representation of geometry.  They will discard invalid vertices
    // and convex the results before passing the data along to the internal*
    // methods.
    void polyVertex(GA_OffsetArray &pts, GA_Offset pt)
    {
        if(pt != GA_INVALID_OFFSET)
            pts.append(pt);
    }
    void endPolygon(GA_OffsetArray &pts);
    void endPolyline(GA_OffsetArray &pts);

    bool myAsPolylines;

    // points
    UT_Array<exint> myPtFirstVtx; // first vertex referencing the point

    // converted prim data
    UT_Array<exint> myPrimEnd; // end of vertex list for a given polygon

    // converted vertex data
    UT_Array<GA_Offset> myVtxPt; // vertexPoint
    UT_Array<exint> myVtxPrim; // vertexPrimitive
    UT_Array<exint> myVtxNextVtx; // next vertex referencing the point or -1
};

// This class contains all the data needed to efficiently compute surface
// distances.  It will automatically invalidate cache items when inputs to the
// query are incompatible with the cached data.  This can help SOPs that want
// to save time on repeated calls.
class GU_API GU_SurfaceDistanceCache
{
public:
    UT_NON_COPYABLE(GU_SurfaceDistanceCache);
    GU_SurfaceDistanceCache() { clear(); }
    ~GU_SurfaceDistanceCache() { clear(); }
    GU_SurfaceDistanceCache(GU_SurfaceDistanceCache&& other) = default;
    GU_SurfaceDistanceCache& operator=(GU_SurfaceDistanceCache&& other) = default;

    void clear();

    // utility method to support multithreading of the surfdist VEX function
    bool canReuse(const GEO_Detail &gdp, const char *p_attr, fpreal radius,
                 GU_SoftDistanceMetric metric) const;

    // group of points with valid distances (and lead points)
    const GA_PointGroup *getAffectedGroup() const
        { return myAffectedGroup.get(); }

    // handle to detached attribute describing measured distances
    GA_ROHandleF getDistances() const
        { return GA_ROHandleF(myDistances.get()); }

    // handle to detached attribute describing closest lead point
    GA_ROHandleID getSourcePoints() const
        { return GA_ROHandleID(mySourcePoints.get()); }

    // compute distances from the point specified by hit_prim and hit_uv, for points within the radius, 
    void updateDistancesFromHitPos(const GEO_Detail &gdp,
        const GU_SurfaceDistance& surf_dist,
        int64 hit_prim, UT_Vector3 hit_pos,
        fpreal radius,
        GU_SoftDistanceMetric metric,
        const char *p_attr = "P",
        const GEO_Detail::SoftSymmetryParms *symmetry = nullptr,
        const GEO_Rolloff *rolloff = nullptr);

    // compute distances from the closest member of the point group, for points within the radius
    void updateDistances(const GEO_Detail &gdp,
        const GU_SurfaceDistance& surf_dist,
        const GA_Group *srcgroup,
        fpreal radius,
        GU_SoftDistanceMetric metric,
        const char *p_attr = "P",
        const GEO_Detail::SoftSymmetryParms *symmetry = nullptr,
        const GEO_Rolloff *rolloff = nullptr);

    int64 getMemoryUsage(bool inclusive) const;
private:
    // validates whether the arguments to updateDistances() require recomputation
    bool shouldUpdateDistances(const GEO_Detail &gdp,
        fpreal radius,
        GU_SoftDistanceMetric metric,
        GA_ROHandleV3 p_attrib,
        const GEO_Detail::SoftSymmetryParms *symmetry);

    bool hasSameTopology(const GEO_Detail &gdp) const;

    void updateSurfAndEdgeDistances(const GEO_Detail &gdp,
                    const GU_SurfaceDistance& surf_dist,
                                    const GA_PointGroup *srcgroup,
                                    fpreal radius,
                                    GU_SoftDistanceMetric metric,
                                    const GA_ROHandleV3 &p_attrib,
                                    const GEO_Detail::SoftSymmetryParms *symmetry);

    // set of points with computed distances (and lead points)
    GA_PointGroupUPtr myAffectedGroup;
    // distance to the closest point in the input group
    GA_AttributeUPtr myDistances;
    // the point in the input group that the current point is closest to
    GA_AttributeUPtr mySourcePoints;

    // values used to determine when to invalidate cached data
    int64 myHitPrim;
    UT_Vector3 myHitUV;
    UT_Vector3 myHitPos;
    GU_SoftDistanceMetric myMetric;
    fpreal myRadius;
    GA_DataId myGdpUniqueId;
    GA_DataId myGdpPrimitiveId;
    GA_DataId myGdpTopologyId;

    bool myHasSymmetryParms;
    bool myHasPtGroup;
    GEO_Detail::SoftSymmetryParms mySymmetryParms;
    UT_String myPAttrib;
    GA_OffsetArray myPts;
};

// Utility class for measuring the distances along a surface from a point on the mesh 
// to the point groups for the same mesh. Allows to compute distances to multiple point groups 
// at the same time.
void GU_API GU_FindDistancesToPointGroups(const GU_SurfaceDistance &sdist,
                                          const GEO_Detail &gdp,  
                                          const GA_ROHandleV3 &p_attrib,                  
                                          const GA_Offset &pt, // starting point 
                                          const UT_Array<GA_PointGroupUPtr> &psubset, // points we want to measure the distance to
                                          int k, // stop when we find the k closest points for each group in the psubset
                                          UT_Array<GA_PointGroupUPtr> &affectedgroups, // set of k closest points to pt with computed distances
                                          GA_RWHandleF &h_dists); // distances from the pt to the points in the affectedgroups
#endif