diff --git a/src/Engine/Operator/Geometry.h b/src/Engine/Operator/Geometry.h index 3960e9d..09bf677 100644 --- a/src/Engine/Operator/Geometry.h +++ b/src/Engine/Operator/Geometry.h @@ -24,56 +24,214 @@ using F_index = HeMesh::Face_index; using attributeIterator = std::vector>::iterator; +/** +* @class enzo::geo::Geometry +* @brief [Attribute](@ref enzo::ga::Attribute) based geometry container exchanged and modified by nodes. +* +* The Geometry class represents the core data being passed between nodes +* in the engine. It is the operand of the network. Nodes read, modify, +* and output geometry, which is then used to populate the viewport and +* the geometry spreadsheet. Geometry is stored in an [attribute](@ref enzo::ga::Attribute) based +* structure, similar to a spreadsheet, where each column is an [attribute](@ref enzo::ga::Attribute) +* owned by points, vertices, primitives, or the global context. Most geometry +* information, including built in properties such as positions and connectivity, +* is stored through this same system. These built in [attributes](@ref enzo::ga::Attribute) are intrinsic, +* but they share the same base as user-defined [attributes](@ref enzo::ga::Attribute) to keep the data +* model consistent. +* +* The class provides methods for constructing and querying geometry, including +* adding points and faces, computing normals, and building a CGAL half-edge +* mesh representation. It also exposes accessors for reading positions, +* primitive connectivity, and vertex data, while tracking special cases +* such as isolated points. +* +* @post Geometry in instatiated with some intrinsic attributes required +* to construct geometry, such as P (position) on point attributes, vertexCount +* and closed on primitive attributes, and point on vertices. It is recommended +* not to modify these directy but instead use the helper functions. +*/ class Geometry { public: - Geometry(); - Geometry(const Geometry& other); + /** + * @brief Assignment operator. Performs a deep copy of another Geometry. + * @param rhs The Geometry object to copy from. + * @return Reference to this Geometry. + */ Geometry& operator=(const Geometry& rhs); + + /** + * @brief Adds an integer attribute to the geometry. + * @param owner The attribute owner (point, vertex, primitive, detail). + * @param name The name of the attribute. + * @return Handle to the created integer attribute. + */ ga::AttributeHandle addIntAttribute(ga::AttributeOwner owner, std::string name); + + /** + * @brief Adds a boolean attribute to the geometry. + * @param owner The attribute owner (point, vertex, primitive, detail). + * @param name The name of the attribute. + * @return Handle to the created boolean attribute. + */ ga::AttributeHandleBool addBoolAttribute(ga::AttributeOwner owner, std::string name); + + /** + * @brief Adds a 3D vector attribute to the geometry. + * @param owner The attribute owner (point, vertex, primitive, detail). + * @param name The name of the attribute. + * @return Handle to the created Vector3 attribute. + */ ga::AttributeHandle addVector3Attribute(ga::AttributeOwner owner, std::string name); - // TODO: return weak ptr + + /** + * @brief Retrieves an attribute by its name. + * @param owner The attribute owner. + * @param name The name of the attribute. + * @return Shared pointer to the attribute if found, otherwise nullptr. + */ std::shared_ptr getAttribByName(ga::AttributeOwner owner, std::string name); + /** + * @brief Gets the number of attributes owned by a specific element type. + * @param owner The attribute owner. + * @return Number of attributes. + */ const size_t getNumAttributes(const ga::AttributeOwner owner) const; - std::weak_ptr getAttributeByIndex(ga::AttributeOwner owner, unsigned int index) const; - // attributeIterator attributesBegin(const ga::AttributeOwner owner); - // attributeIterator attributesEnd(const ga::AttributeOwner owner); - std::vector derivePointNormals(); + /** + * @brief Retrieves an attribute by its index. + * @param owner The attribute owner. + * @param index Index of the attribute. + * @return Weak pointer to the attribute. + */ + std::weak_ptr getAttributeByIndex(ga::AttributeOwner owner, unsigned int index) const; + + /** + * @brief Computes per-point normals for the geometry. + * @return Vector of computed normals corresponding to each point. + */ + // std::vector derivePointNormals(); + + /** + * @brief Builds a CGAL half-edge mesh representation of the geometry. + * @return The constructed half-edge mesh. + */ HeMesh computeHalfEdgeMesh(); - // build geometry + /** + * @brief Adds a polygonal face to the geometry. + * @param pointOffsets Offsets of the points forming the face. + * @param closed Whether the face is closed (default true). + */ void addFace(const std::vector& pointOffsets, bool closed=true); - template - void addFace(Args... args) - { - std::vector pointOffsets = { static_cast(args)... }; - addFace(pointOffsets); - } + /** + * @brief Adds a point to the geometry. + * @param pos Position of the new point. + */ void addPoint(const bt::Vector3& pos); + /** + * @brief Iterator to the beginning of the set of solo (isolated) points. + * @return Const iterator to the first solo point. + */ std::set::const_iterator soloPointsBegin(); + + /** + * @brief Iterator to the end of the set of solo (isolated) points. + * @return Const iterator past the last solo point. + */ std::set::const_iterator soloPointsEnd(); + /** + * @brief Sets the position of a point. + * @param offset Offset of the point. + * @param pos New position. + */ void setPointPos(const ga::Offset offset, const bt::Vector3& pos); - ga::Offset getPrimStartVertex(ga::Offset primOffset) const; // returns the first vertex of the primitive - bt::Vector3 getPosFromVert(ga::Offset vertexOffset) const; - bt::Vector3 getPointPos(ga::Offset pointOffset) const; - unsigned int getPrimVertCount(ga::Offset primOffset) const; - ga::Offset getVertexPrim(ga::Offset vertexOffset) const; - ga::Offset getNumPrims() const; - ga::Offset getNumVerts() const; - ga::Offset getNumPoints() const; - ga::Offset getNumSoloPoints() const; + /** + * @brief Gets the first vertex of a primitive. + * @param primOffset Offset of the primitive. + * @return Offset of the first vertex. + */ + ga::Offset getPrimStartVertex(ga::Offset primOffset) const; + /** + * @brief Gets the 3 dimensional position from a vertex offset. + * @param vertexOffset Offset of the vertex. + * @return Position of the vertex. + */ + bt::Vector3 getPosFromVert(ga::Offset vertexOffset) const; + + /** + * @brief Gets the position of a point. + * @param pointOffset Offset of the point. + * @return Position of the point. + */ + bt::Vector3 getPointPos(ga::Offset pointOffset) const; + + /** + * @brief Gets the number of vertices in a primitive. + * @param primOffset Offset of the primitive. + * @return Number of vertices. + */ + unsigned int getPrimVertCount(ga::Offset primOffset) const; + + /** + * @brief Gets the primitive that owns a given vertex. + * @param vertexOffset Offset of the vertex. + * @return Offset of the owning primitive. + */ + ga::Offset getVertexPrim(ga::Offset vertexOffset) const; + + /** + * @brief Gets the number of primitives in the geometry. + * @return Number of primitives. + */ + ga::Offset getNumPrims() const; + + /** + * @brief Gets the number of vertices in the geometry. + * @return Number of vertices. + */ + ga::Offset getNumVerts() const; + + /** + * @brief Gets the number of points in the geometry. + * @return Number of points. + */ + ga::Offset getNumPoints() const; + + /** + * @brief Gets the number of isolated points in the geometry. + * Isolated points are points that are not connnected to any other point + * and don't belong to a primitive. + * @return Number of solo points. + */ + ga::Offset getNumSoloPoints() const; + + /** + * @brief Checks if a primitive is closed or open. + * + * Open primitives are treated and rendered as curves. + * + * @param primOffset Offset of the primitive. + * @return True if the primitive is closed, false otherwise. + */ bt::boolT isClosed(ga::Offset primOffset) const; + /** + * @brief Merges another geometry into this one. + * @param other The geometry to merge. + */ void merge(Geometry& other); + /** + * @brief Computes the starting vertex for each primitive in the geometry. + * @todo Automatically lazy evaluate when requested (make thread safe) + */ void computePrimStartVertices() const; private: using attribVector = std::vector>; diff --git a/src/Engine/Types.h b/src/Engine/Types.h index 31524ca..947fe08 100644 --- a/src/Engine/Types.h +++ b/src/Engine/Types.h @@ -11,6 +11,14 @@ namespace enzo namespace ga { + /** + * @brief The segment of geometry that owns a particular attribute + * + * - POINT attributes are stored per point, these attributes have an value for each point. + * - VERTEX attributes are stored per vertex, these attributes have an value for each vertex. + * - PRIMITIVE attributes are stored per primitive, these attributes have an value for each primitive. + * - GLOBAL attributes are stored globaly, these attributes only have one value. + */ enum class AttributeOwner { POINT, @@ -31,6 +39,14 @@ namespace enzo }; using AttrType = AttributeType; using AttrOwner = AttributeOwner; + /** + * @brief ga::Offset is the index of an element in a given AttributeOwner. + * + * Eg. point index, vertex index, primitive index, or global index. + * This different but similar in concept to a point number. This + * value will stay consistant through geometry modification such + * as adding and deleting points unlress defragmented. + */ using Offset = size_t; } // basic types types