Skip to content

Commit

Permalink
documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@LiangliangNan
LiangliangNan committed Feb 9, 2025
1 parent be44eca commit fc0bb60
Show file tree
Hide file tree
Showing 26 changed files with 991 additions and 484 deletions.
4 changes: 1 addition & 3 deletions easy3d/algo/extrusion.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,6 @@
#ifndef EASY3D_ALGO_EXTRUSION_H
#define EASY3D_ALGO_EXTRUSION_H

#include <string>

#include <easy3d/core/types.h>


Expand All @@ -50,7 +48,7 @@ namespace easy3d {

/**
* \brief Extrudes a 3D surface mesh from a set of simple contours.
* \param mesh The output mesh model. Must be allocated before hand.
* \param mesh The output mesh model. Must be allocated beforehand.
* @param contours The input contours, which must be simple, i.e.,
* - free of intersections,
* - CCW contours defining the outer boundary and CW contours defining holes.
Expand Down
4 changes: 2 additions & 2 deletions easy3d/algo/point_cloud_normals.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ namespace easy3d {

class PointCloud;

/// \brief Estimate point cloud normals. It also allows to reorients the point cloud normals based on a minimum
/// \brief Estimate point cloud normals. It also allows to reorient the point cloud normals based on a minimum
/// spanning tree algorithm.
/// \class PointCloudNormals easy3d/algo/point_cloud_normals.h
class PointCloudNormals {
Expand All @@ -45,7 +45,7 @@ namespace easy3d {

/// \brief Reorients the point cloud normals.
/// This method implements the normal reorientation method described in
/// Hoppe et al. Surface reconstruction from unorganized points. SIGGRAPH 1992.
/// Hoppe et al. Surface reconstruction from unorganized points. SIGGRAPH 1992.
/// \param cloud The input point cloud.
/// @param k: the number of neighboring points to construct the graph.
static bool reorient(PointCloud *cloud, unsigned int k = 16);
Expand Down
78 changes: 64 additions & 14 deletions easy3d/algo/point_cloud_poisson_reconstruction.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,35 +36,58 @@ namespace easy3d {
class PointCloud;
class SurfaceMesh;

/// \brief Poisson surface reconstruction.
/// \class PoissonReconstruction easy3d/algo/point_cloud_poisson_reconstruction.h
/**
* \brief Poisson surface reconstruction.
* \class PoissonReconstruction easy3d/algo/point_cloud_poisson_reconstruction.h
*/
class PoissonReconstruction {
public:
/**
* \brief Constructor.
*/
PoissonReconstruction();
/**
* \brief Destructor.
*/
~PoissonReconstruction();

/**
* \brief Set reconstruction depth.
* This integer is the maximum depth of the tree that will be used for surface reconstruction. Running at depth
* d corresponds to solving on a voxel grid whose resolution is no larger than 2^d x 2^d x 2^d. Note that since
* the reconstructor adapts the octree to the sampling density, the specified reconstruction depth is only an
* upper bound. The default value for this parameter is 8.
* \param d The maximum depth of the tree used for surface reconstruction.
* \details This integer is the maximum depth of the tree that will be used for surface reconstruction. Running
* at depth d corresponds to solving on a voxel grid whose resolution is no larger than 2^d x 2^d x 2^d.
* Note that since the reconstructor adapts the octree to the sampling density, the specified
* reconstruction depth is only an upper bound. The default value for this parameter is 8.
*/
void set_depth(int d) { depth_ = d; }

/**
* \brief Set the minimum number of samples.
* This floating point value specifies the minimum number of sample points that should fall within an octree
* node as the octree construction is adapted to sampling density. For noise-free samples, small values in the
* range [1.0 - 5.0] can be used. For more noisy samples, larger values in the range [15.0 - 20.0] may be needed
* to provide a smoother, noise-reduced, reconstruction. The default value is 1.0.
* \param s The minimum number of sample points that should fall within an octree node. This floating point
* value specifies the minimum number of sample points that should fall within an octree node as the
* octree construction is adapted to sampling density. For noise-free samples, small values in the range
* [1.0 - 5.0] can be used. For more noisy samples, larger values in the range [15.0 - 20.0] may be needed
* to provide a smoother, noise-reduced, reconstruction. The default value is 1.0.
*/
void set_samples_per_node(float s) { samples_per_node_ = s; }

/// \brief reconstruction
/**
* \brief Perform Poisson surface reconstruction.
* \param cloud The input point cloud.
* \param density_attr_name The name of the density attribute. Default is "v:density".
* \return A pointer to the reconstructed surface mesh.
*/
SurfaceMesh *apply(const PointCloud *cloud, const std::string &density_attr_name = "v:density") const;

/// \brief Trim the reconstructed surface model based on the density attribute.
/**
* \brief Trim the reconstructed surface model based on the density attribute.
* \param mesh The surface mesh to be trimmed.
* \param trim_value The density value used for trimming.
* \param area_ratio The area ratio used for trimming.
* \param triangulate Whether to triangulate the trimmed surface.
* \param density_attr_name The name of the density attribute. Default is "v:density".
* \return A pointer to the trimmed surface mesh.
*/
static SurfaceMesh *trim(
SurfaceMesh *mesh,
float trim_value,
Expand All @@ -74,13 +97,40 @@ namespace easy3d {
);

public:
/// \brief Other parameters for Poisson surface reconstruction algorithm.
/// These parameters are usually not needed
// Other parameters for Poisson surface reconstruction algorithm. These parameters are usually not needed.
/**
* \brief Set the full depth of the octree.
* \param v The full depth value.
* \details This integer specifies the depth beyond which the octree will be adapted. At coarser depths, the octree will be complete.
* The default value for this parameter is 5.
*/
void set_full_depth(int v) { full_depth_ = v; }
/**
* \brief Set the conjugate gradient depth.
* \param v The conjugate gradient depth value.
*/
void set_cg_depth(int v) { cgDepth_ = v; }
/**
* \brief Set the scale factor.
* \param v The scale factor value.
*/
void set_scale(float v) { scale_ = v; }
/**
* \brief Set the point weight.
* \param v The point weight value.
* \details This floating point value specifies the importance that interpolation of the point samples is given
* in the formulation of the screened Poisson equation. The default value for this parameter is 4.
*/
void set_point_weight(float v) { pointWeight_ = v; }
/**
* \brief Set the number of Gauss-Seidel iterations.
* \param v The number of Gauss-Seidel iterations.
*/
void set_gs_iter(int v) { gsIter_ = v; }
/**
* \brief Set the verbosity of the reconstruction process.
* \param v True to enable verbose output, false otherwise.
*/
void set_verbose(bool v) { verbose_ = v; }

private:
Expand Down
26 changes: 13 additions & 13 deletions easy3d/algo/point_cloud_ransac.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ namespace easy3d {

public:
/**
* \brief Setup the primitive types to be extracted.
* \brief Set up the primitive types to be extracted.
* \details This is done by adding the interested primitive types one by one.
*/
void add_primitive_type(PrimType t);
Expand All @@ -77,7 +77,7 @@ namespace easy3d {
* \details The extracted primitives are stored as properties:
* - "v:primitive_type" (one of PLANE, SPHERE, CYLINDER, CONE, TORUS, and UNKNOWN)
* - "v:primitive_index" (-1, 0, 1, 2...). -1 meaning a vertex does not belong to any primitive (thus its
* primitive_type must be UNKNOWN.
* primitive_type must be UNKNOWN).
* \param cloud The input point cloud.
* \param min_support The minimal number of points required for a primitive.
* \param dist_threshold The distance threshold, defined relative to the bounding box's max dimension.
Expand All @@ -101,7 +101,7 @@ namespace easy3d {
* \details The extracted primitives are stored as per-vertex properties:
* - "v:primitive_type" (one of PLANE, SPHERE, CYLINDER, CONE, TORUS, and UNKNOWN)
* - "v:primitive_index" (-1, 0, 1, 2...). -1 meaning a vertex does not belong to any primitive (thus
* its primitive_type must be UNKNOWN.
* its primitive_type must be UNKNOWN).
* In addition to the primitive information stored as properties, the parameters of the detected primitives
* can also be queried using this functions. \see get_planes, get_cylinders.
* \param cloud The input point cloud.
Expand All @@ -127,11 +127,11 @@ namespace easy3d {
* \brief Information about a plane primitive.
*/
struct PlanePrim {
int primitive_index; // the index of this plane (w.r.t. the entire list of detected primitives)
std::vector<int> vertices; // the vertex indices (w.r.t. the point cloud) of this plane
Plane3 plane; // the plane equation
vec3 position;
vec3 normal;
int primitive_index; /// the index of this plane (w.r.t. the entire list of detected primitives)
std::vector<int> vertices; /// the vertex indices (w.r.t. the point cloud) of this plane
Plane3 plane; /// the plane representation
vec3 position; /// the position of the plane (represented by a point on the plane)
vec3 normal; /// the normal of the plane
};
/**
* \brief Get the detected planes.
Expand All @@ -142,11 +142,11 @@ namespace easy3d {
* \brief Information about a cylinder primitive.
*/
struct CylinderPrim {
int primitive_index; // the index of this cylinder w.r.t. the entire list of detected primitives
std::vector<int> vertices; // the vertex indices (w.r.t. the point cloud) of this cylinder
float radius;
vec3 position;
vec3 direction;
int primitive_index; /// the index of this cylinder (w.r.t. the entire list of detected primitives)
std::vector<int> vertices; /// the vertex indices (w.r.t. the point cloud) of this cylinder
float radius; /// the radius of the cylinder
vec3 position; /// the position of the cylinder (represented by the center of the bottom circle)
vec3 direction; /// the direction of the cylinder
};
/**
* Get the detected cylinders.
Expand Down
98 changes: 83 additions & 15 deletions easy3d/algo/surface_mesh_components.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,63 +21,131 @@ namespace easy3d {
/**
* \brief A connected component of a SurfaceMesh.
* \details Internally, A connected component of a SurfaceMesh stores four lists of SurfaceMesh elements, i.e., vertices,
* faces, edges, and halfedges.
* faces, edges, and halfedges.
* \class SurfaceMeshComponent easy3d/algo/surface_mesh_components.h
*/
class SurfaceMeshComponent {
public:
typedef SurfaceMesh::Face Face;
typedef SurfaceMesh::Vertex Vertex;
typedef SurfaceMesh::Edge Edge;
typedef SurfaceMesh::Halfedge Halfedge;
// convenient type definitions
typedef SurfaceMesh::Face Face; //!< Face type
typedef SurfaceMesh::Vertex Vertex; //!< Vertex type
typedef SurfaceMesh::Edge Edge; //!< Edge type
typedef SurfaceMesh::Halfedge Halfedge; //!< Halfedge type

public:
/**
* \brief Constructor that initializes the component with a given mesh.
* \param mesh The surface mesh to which this component belongs.
*/
explicit SurfaceMeshComponent(SurfaceMesh *mesh) : mesh_(mesh) {}

/** Extracts connected components. The components are sorted in descending order if \p descending is \p true (in terms of number of faces.*/
/**
* \brief Extracts connected components from the given mesh.
* \param mesh The surface mesh from which to extract components.
* \param descending If true, the components are sorted in descending order by the number of faces.
* \return A vector of extracted SurfaceMeshComponent objects.
*/
static std::vector<SurfaceMeshComponent> extract(SurfaceMesh *mesh, bool descending = true);

/** Extracts a single connected component from the seed face */
/**
* \brief Extracts a single connected component from the given seed face.
* \param mesh The surface mesh from which to extract the component.
* \param seed The seed face to start the extraction.
* \return The extracted SurfaceMeshComponent object.
*/
static SurfaceMeshComponent extract(SurfaceMesh *mesh, SurfaceMesh::Face seed);

/** Extracts a single connected component from the seed vertex */
/**
* \brief Extracts a single connected component from the given seed vertex.
* \param mesh The surface mesh from which to extract the component.
* \param seed The seed vertex to start the extraction.
* \return The extracted SurfaceMeshComponent object.
*/
static SurfaceMeshComponent extract(SurfaceMesh *mesh, SurfaceMesh::Vertex seed);

/**
* \brief Returns the list of faces in this component.
* \return A constant reference to the vector of faces.
*/
const std::vector<Face> &faces() const { return faces_; }

/**
* \brief Returns the list of vertices in this component.
* \return A constant reference to the vector of vertices.
*/
const std::vector<Vertex> &vertices() const { return vertices_; }

/**
* \brief Returns the list of edges in this component.
* \return A constant reference to the vector of edges.
*/
const std::vector<Edge> &edges() const { return edges_; }

/**
* \brief Returns the list of halfedges in this component.
* \return A constant reference to the vector of halfedges.
*/
const std::vector<Halfedge> &halfedges() const { return halfedges_; }

/**
* \brief Returns the number of faces in this component.
* \return The number of faces.
*/
std::size_t n_faces() const { return faces_.size(); }

/**
* \brief Returns the number of vertices in this component.
* \return The number of vertices.
*/
std::size_t n_vertices() const { return vertices_.size(); }

/**
* \brief Returns the number of edges in this component.
* \return The number of edges.
*/
std::size_t n_edges() const { return edges_.size(); }

/**
* \brief Returns the number of halfedges in this component.
* \return The number of halfedges.
*/
std::size_t n_halfedges() const { return halfedges_.size(); }

/** Returns the surface mesh to which this component belongs. */
/**
* \brief Returns the surface mesh to which this component belongs.
* \return A pointer to the surface mesh.
*/
SurfaceMesh *mesh() const { return mesh_; }

/**
* Returns the surface area of this component.
* Internally it triangulates the face using the tessellator. So this method also works for concave faces.
* \brief Returns the surface area of this component.
* \details Internally it triangulates the face using the tessellator. So this method also works for concave faces.
* \return The surface area.
*/
float area() const;

/** Returns the total border length of this component. */
/**
* \brief Returns the total border length of this component.
* \return The total border length.
*/
float border_length() const;

/** Returns the bounding box of this component. */
/**
* \brief Returns the bounding box of this component.
* \return The bounding box.
*/
Box3 bbox() const;

/** Translates this component by an offset vector. */
/**
* \brief Translates this component by an offset vector.
* \param offset The offset vector.
*/
void translate(const vec3 &offset);

/** Constructs a surface mesh from this component. */
/**
* \brief Constructs a surface mesh from this component.
* \return A pointer to the constructed surface mesh.
*/
SurfaceMesh *to_mesh() const;

private:
Expand Down
Loading

0 comments on commit fc0bb60

Please sign in to comment.