GU_TriangleMesh.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 Library (C++)
 *
 * GU_TriangleMesh is a an implementation of an embedding triangle mesh
 * (UT_EmbeddedTriangleMesh) built over a subset of polygons of a geometry
 * detail. It constructs and maintains the means needed for going from the
 * physical space to the abstract one and vice versa.
 *
 * The represented abstract triangle mesh can be seen as a refinement of the
 * geometry with the added benefit tha all its elements are numbered
 * consecutively from zero and the supporting methods allow to map between
 * elements rapidly. Furthermore, one can map between input geometry elements
 * and mesh element indices, when applicable.
 *
 */

#ifndef __GU_TriangleMesh_h__
#define __GU_TriangleMesh_h__

#include "GU_API.h"

#include "GU_Detail.h"
#include <GA/GA_Handle.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_TriangleMesh.h>

class GU_Detail;
class GEO_DetachedHedgeInterface;
class GA_EdgeGroup;
class GA_Range;
class UT_Classifier;

// Helper class to attach a triangle mesh to a detail and turn it into an
// embedded triangle mesh. This is passed as a template argument to
// GU_TriangleMesh and keeps track of auxiliary points and their positions
// (needed for tessellations that require additional points), as well as
// correspondences between mesh elements and detail ones. Most importantly
// it implements `pointPosition()` expected from template argument.

template <typename T>
class GU_API GU_TriangleMeshDetailLinkT
{
public:
    using value_type = UT_Vector3T<T>;
    using PointCoords = UT_Vector3T<T>;

                         GU_TriangleMeshDetailLinkT(const GU_Detail *gdp,
                                const UT_TriangleMesh &mesh,
                                GA_RWHandleI vtx_pt_attr,
                                const GA_Attribute *pos_attr);


    SYS_FORCE_INLINE
    PointCoords          pointPosition(int pt) const;

    SYS_FORCE_INLINE
    int                  numPrimaryPoints() const
                            { return myNumPrimaryPoints; }

    SYS_FORCE_INLINE
    int                  numAuxiliaryPoints() const
                            { return int(myAuxiliaryPointPos.size()); }

    SYS_FORCE_INLINE
    int                  numPoints() const
                            { return numPrimaryPoints() + numAuxiliaryPoints(); }

    SYS_FORCE_INLINE
    void                 setNumPrimaryPoints(int num)
                            { myNumPrimaryPoints = num; }

    SYS_FORCE_INLINE
    int                  appendAuxiliaryPoint(UT_Vector3R pos)
                            { myAuxiliaryPointPos.append(pos);
                                return numPoints() - 1; }

    void                 appendMappingToDetailVertex(GA_Offset vtx)
                            { myVertexToDetailVertex.append(vtx); }

    SYS_FORCE_INLINE
    GA_Offset            vertexToDetailVertex(int v) const
                            { return myVertexToDetailVertex(v); }

    SYS_FORCE_INLINE
    PointCoords          detailVertexPosition(GA_Offset vtx) const
                            { return myPos.get(myPosFromVertexAttrib ? vtx
                                               : myGdp->vertexPoint(vtx)); }

    SYS_FORCE_INLINE
    int                  vertexFromDetailVertex(GA_Offset vtx) const
                            { return myDetailVertexToVertex.get(vtx); }

    SYS_FORCE_INLINE
    bool                 isEngaged() const
                            { return myVertexToDetailVertex.size() > 0; }

    SYS_FORCE_INLINE
    void                 assignVertexToDetailVertex(GA_Offset vtx, int pt)
                            { myDetailVertexToVertex.set(vtx, pt); }

    SYS_FORCE_INLINE
    bool                 isPosFromVertexAttrib() const
                            { return myPosFromVertexAttrib; }

private:
    using PosHandle = GA_ROHandleT<PointCoords>;
    using PointCoordsArray = UT_Array<PointCoords>;

    const
    UT_TriangleMesh     &myMesh;
    const GU_Detail     *myGdp;

    // Number of points in the mesh that arise (and are mapped back) to actual
    // geometry points. The points with index myNumPrimaryPoints and higher
    // are expected to be auxiliary points.

    int                  myNumPrimaryPoints                     = 0;
    PointCoordsArray     myAuxiliaryPointPos;
    GA_OffsetArray       myVertexToDetailVertex;

    GA_RWHandleI         myDetailVertexToVertex;
    GA_AttributeUPtr             myDetailVertexToVertexAttrib;

    PosHandle            myPos;
    bool                 myPosFromVertexAttrib                  = false;
};

template <typename T>
class GU_API GU_TriangleMeshT :
        public UT_EmbeddedTriangleMesh< GU_TriangleMeshDetailLinkT<T> >
{
public:
    using HedgeInterface = GEO_DetachedHedgeInterface;
    using Base = UT_EmbeddedTriangleMesh< GU_TriangleMeshDetailLinkT<T> >;

    // Various possible ways of splitting polygons with 4 or more vertices
    enum Tessellation
    {
        TRIANGULATE_ALL = 0,    // Triangulate all polygons
        SPLIT_CONVEX_QUADS      // Split convex quads (new point at centroid),
                                // triangulate all other polygons.
    };

    // The constructor needs a constant detail as the reference geometry.
    // Note that no group is specified here. Polygons to be used for the mesh
    // can either be added using `appendPoly()` or `appendPolys()` methods
    // before a call to `buildMesh()`. This allows distribution of polygons
    // into various meshes in a scan.
    //
    // The integer handle can be used to pass an integer vertex attribute to
    // collect the assigned point number to each geometry vertex. If an
    // invalid handle is passed, the structure creates its own detached
    // attribute. The purpose of passing the handle is to share the attribute
    // between multiple meshes.
    //
    // The `tessellation` argument can be used to control the type of
    // refinement. Currently, the only option other than a straightforward
    // triangulation is to split convex quads into four triangles by inserting
    // a virtual vertex at the centroid of the quad.

    explicit             GU_TriangleMeshT(const GU_Detail *gdp,
                                GA_RWHandleI vtx_pt_attr = GA_RWHandleI(),
                                Tessellation tessellation = TRIANGULATE_ALL,
                                const GA_Attribute *pos_attr = nullptr);

    SYS_FORCE_INLINE
    const GU_Detail     *getDetail() const { return myGdp; }

    // List of polygons used in the construction of the mesh.
    SYS_FORCE_INLINE
    const
    GA_OffsetArray      &polys() const { return myPolys; }


    // Add a single polygon to those covered by the mesh. Can only be called
    // before building the mesh.
    SYS_FORCE_INLINE
    void                 appendPoly(GA_Offset poly)
                            { UT_ASSERT_P(!isBuilt()); myPolys.append(poly); }

    // Add a range of polygons to those covered by the mesh.
    // Can only be called before building the mesh.
    void                 appendPolys(const GA_Range &polys);

    // Build the actual mesh. It checks and drops invalid primitives
    // (non-polygons and polygons that are open or have < 3 vertices).
    //
    // `seams` will specify the intended cuts in mesh. Half-edges matching
    // edges in `seams` won't get identified with anything.
    //
    // `shared_vtx_idx_array`, if passed, will be used instead of an internal
    // array for indexing vertices of the involved polygons. This is only used
    // internally and is not meant to deliver any information. It's allowed
    // to be passed here to avoid repeat allocation in cases where multiple
    // disjoint meshes are built on the same geometry (eg uv islands). Note
    // that the size of the array must be at least as one plus the largest
    // vertex offset.
    //
    // Note: The half-edge interface `hip` can be passed if available (though
    // it *must* cover all the added polygons) but is not needed and passing
    // `nullptr` should be faster than building the interface and passing it.
    //
    // If `allow_zero_length_edges` is false, it prevents geometrically
    // degenerate triangles that occur if consecutive points around polygons
    // can have identical positions. In this case, all consecutively coincident
    // vertices of input polygon are identified into the same point in the
    // output mesh and the mapping from detail vertices to mesh vertices will
    // take each vertex v on the polygon to the source vertex of the half edge
    // in the mesh that corresponds to the edge of the polygon of v that has
    // for its source the last vertex around the polygon  (in the winding order)
    // that consecutively coincides with v.

    void                 buildMesh(const HedgeInterface *hip = nullptr,
                                const GA_EdgeGroup *seams = nullptr,
                                UT_IntArray *shared_vtx_idx_array = nullptr,
                                bool allow_zero_length_edges = false);

    template<typename Func>
    void                 forEachPolyVertex(Func func) const
    {
        for (GA_Offset poly : myPolys)
        {
            auto vtxs = myGdp->getPrimitiveVertexList(poly);
            for (int i = 0, ie = int(vtxs.size()); i < ie; i++)
                func(vtxs(i));
        }
    }

    template<typename Func>
    void                 forEachDetailVertex(Func func) const
                            { forEachPolyVertex(func); }

    SYS_FORCE_INLINE
    int                  vertexFromDetailVertex(GA_Offset vtx) const
                            { return myLink.vertexFromDetailVertex(vtx); }

    SYS_FORCE_INLINE
    int                  pointFromDetailVertex(GA_Offset vtx) const;


    // Map a half-edge of the mesh to a vertex in the detail. This differs
    // from the vertexToDetailVertex() in that only half-edges that map
    // exactly to source vertex of half-edges in the detail are mapped and
    // other half-edges are mapped to invalid offsets.

    SYS_FORCE_INLINE
    GA_Offset            hedgeToDetailVertex(int h) const;

    SYS_FORCE_INLINE
    int                  hedgeFromDetailVertex(GA_Offset vtx) const
                            { return vertexFromDetailVertex(vtx); }

    SYS_FORCE_INLINE
    GA_Offset            vertexToDetailVertex(int v) const
                            { return myLink.vertexToDetailVertex(v); }

    SYS_FORCE_INLINE
    GA_Offset            triangleToDetailPoly(int t) const
    {
        auto v = Base::triangleVertex(t, 0);
        return myGdp->vertexPrimitive(vertexToDetailVertex(v));
    }

    // Return for a mesh point *a* geometry vertex mapped to it.
    SYS_FORCE_INLINE
    GA_Offset            pointToDetailVertex(int pt) const
                            { return vertexToDetailVertex(Base::pointVertex(pt)); }

    // Return for a mesh point *the* geometry point mapped to it.
    SYS_FORCE_INLINE
    GA_Offset            pointToDetailPoint(int pt) const;

    Tessellation         tessellation() const { return myTessellation; }

    fpreal               area() const { return myArea; }
    fpreal               polyArea(exint poly_idx) const
                            { return myPolyArea(poly_idx); }

    SYS_FORCE_INLINE
    bool                 isBuilt() const
                            { return myLink.isEngaged(); }

    int                  numPrimaryPoints() const 
                            { return myLink.numPrimaryPoints(); }

protected:
    SYS_FORCE_INLINE
    UT_Vector3R          detailVertexPosition(GA_Offset vtx) const
                            { return myLink.detailVertexPosition(vtx); }

private:
    SYS_FORCE_INLINE
    bool                 isValidPoly(GA_Offset prim) const;

    SYS_FORCE_INLINE
    bool                 coincide(GA_Offset vtx0, GA_Offset vtx1) const;

    bool                 verifyPolys();
    int                  indexPolyVertices(bool allow_zesro_length_edges,
                                UT_IntArray &vtx_idx, int &ntris);

    void                 classifyVertices(const UT_IntArray &vtx_idx,
                                const GA_EdgeGroup *seams,
                                bool allow_zero_length_edges,
                                UT_Classifier &vtx_to_pt_classes,
                                GA_OffsetArray &seam_vtxs);

    void                 classifyVertices(const HedgeInterface *hip,
                                const UT_IntArray &vtx_idx,
                                const GA_EdgeGroup *seams,
                                bool full_range,
                                bool allow_zero_length_edges,
                                UT_Classifier &vtx_to_pt_classes,
                                GA_OffsetArray &seam_vtxs);

    using DetailLink = GU_TriangleMeshDetailLinkT<T>;

    DetailLink           myLink;
    const GU_Detail     *myGdp                                  = nullptr;
    Tessellation         myTessellation;
    GA_OffsetArray       myPolys;

    UT_FprealArray       myPolyArea;
    fpreal               myArea                                 = 0.0;
};

template <typename T>
UT_Vector3T<T>
GU_TriangleMeshDetailLinkT<T>::pointPosition(int pt) const
{
    // Find an arbitrary mesh vertex number corresponding to pt and
    // pap it a an input detail vertex.
    if (pt >= myNumPrimaryPoints)
        return myAuxiliaryPointPos(pt - myNumPrimaryPoints);

    auto vtx = myVertexToDetailVertex(myMesh.pointVertex(pt));
    return detailVertexPosition(vtx);
}

template <typename T>
GA_Offset
GU_TriangleMeshT<T>::pointToDetailPoint(int pt) const
{
    auto vtx = vertexToDetailVertex(Base::pointVertex(pt));
    if (!GAisValid(vtx))
        return GA_INVALID_OFFSET;
    return myGdp->vertexPoint(vtx);
}

template <typename T>
GA_Offset
GU_TriangleMeshT<T>::hedgeToDetailVertex(int h) const
{
    auto vtx = vertexToDetailVertex(Base::srcVertex(h));

    int h_sym = Base::sym(h);
    if (h_sym >= 0 && vtx == vertexToDetailVertex(Base::dstVertex(h_sym)))
        return GA_INVALID_OFFSET;

    return vtx;
}

template <typename T>
int
GU_TriangleMeshT<T>::pointFromDetailVertex(GA_Offset vtx) const
{
    auto v = vertexFromDetailVertex(vtx);
    if (v < 0)
        return -1;
    return Base::vertexPoint(v);
}

template <typename T>
bool
GU_TriangleMeshT<T>::isValidPoly(GA_Offset prim) const
{
    return myGdp->getPrimitiveTypeId(prim) == GEO_PRIMPOLY
           && myGdp->getPrimitiveClosedFlag(prim)
           && myGdp->getPrimitiveVertexCount(prim) > 2;
}

template <typename T>
bool
GU_TriangleMeshT<T>::coincide(GA_Offset vtx0, GA_Offset vtx1) const
{
    return detailVertexPosition(vtx0) == detailVertexPosition(vtx1);
}



typedef GU_TriangleMeshT<fpreal32>              GU_TriangleMeshF;
typedef GU_TriangleMeshT<fpreal64>              GU_TriangleMeshD;
typedef GU_TriangleMeshT<fpreal>                GU_TriangleMeshR;

#endif