|
Manifold 1.0
Robust computational geometry
|
|
|
Manifold 1.0
Robust computational geometry
|
|
#include <manifold.h>
Classes | |
| struct | Impl |
Information | |
Details of the manifold | |
| enum class | Error { NoError , NonFiniteVertex , NotManifold , VertexOutOfBounds , PropertiesWrongLength , MissingPositionProperties , MergeVectorsDifferentLengths , MergeIndexOutOfBounds , TransformWrongLength , RunIndexWrongLength , FaceIDWrongLength , InvalidConstruction } |
| Mesh | GetMesh () const |
| MeshGL | GetMeshGL (glm::ivec3 normalIdx=glm::ivec3(0)) const |
| bool | IsEmpty () const |
| Error | Status () const |
| int | NumVert () const |
| int | NumEdge () const |
| int | NumTri () const |
| int | NumProp () const |
| int | NumPropVert () const |
| Box | BoundingBox () const |
| float | Precision () const |
| int | Genus () const |
| Properties | GetProperties () const |
| float | MinGap (const Manifold &other, float searchLength) const |
Topological | |
No geometric calculations. | |
| std::vector< Manifold > | Decompose () const |
| static Manifold | Compose (const std::vector< Manifold > &) |
Mesh ID | |
Details of the manifold's relation to its input meshes, for the purposes of reapplying mesh properties. | |
| int | OriginalID () const |
| Manifold | AsOriginal () const |
| static uint32_t | ReserveIDs (uint32_t) |
Modification | |
| Manifold | Translate (glm::vec3) const |
| Manifold | Scale (glm::vec3) const |
| Manifold | Rotate (float xDegrees, float yDegrees=0.0f, float zDegrees=0.0f) const |
| Manifold | Transform (const glm::mat4x3 &) const |
| Manifold | Mirror (glm::vec3) const |
| Manifold | Warp (std::function< void(glm::vec3 &)>) const |
| Manifold | WarpBatch (std::function< void(VecView< glm::vec3 >)>) const |
| Manifold | SetProperties (int, std::function< void(float *, glm::vec3, const float *)>) const |
| Manifold | CalculateCurvature (int gaussianIdx, int meanIdx) const |
| Manifold | CalculateNormals (int normalIdx, float minSharpAngle=60) const |
| Manifold | SmoothByNormals (int normalIdx) const |
| Manifold | SmoothOut (float minSharpAngle=60, float minSmoothness=0) const |
| Manifold | Refine (int) const |
| Manifold | RefineToLength (float) const |
Boolean | |
Combine two manifolds | |
| Manifold | Boolean (const Manifold &second, OpType op) const |
| Manifold | operator+ (const Manifold &) const |
| Manifold & | operator+= (const Manifold &) |
| Manifold | operator- (const Manifold &) const |
| Manifold & | operator-= (const Manifold &) |
| Manifold | operator^ (const Manifold &) const |
| Manifold & | operator^= (const Manifold &) |
| std::pair< Manifold, Manifold > | Split (const Manifold &) const |
| std::pair< Manifold, Manifold > | SplitByPlane (glm::vec3 normal, float originOffset) const |
| Manifold | TrimByPlane (glm::vec3 normal, float originOffset) const |
| static Manifold | BatchBoolean (const std::vector< Manifold > &manifolds, OpType op) |
2D from 3D | |
| CrossSection | Slice (float height=0) const |
| CrossSection | Project () const |
Convex hull | |
| Manifold | Hull () const |
| static Manifold | Hull (const std::vector< Manifold > &manifolds) |
| static Manifold | Hull (const std::vector< glm::vec3 > &pts) |
Testing hooks | |
These are just for internal testing. | |
| bool | MatchesTriNormals () const |
| int | NumDegenerateTris () const |
| int | NumOverlaps (const Manifold &second) const |
This library's internal representation of an oriented, 2-manifold, triangle mesh - a simple boundary-representation of a solid object. Use this class to store and operate on solids, and use MeshGL for input and output, or potentially Mesh if only basic geometry is required.
In addition to storing geometric data, a Manifold can also store an arbitrary number of vertex properties. These could be anything, e.g. normals, UV coordinates, colors, etc, but this library is completely agnostic. All properties are merely float values indexed by channel number. It is up to the user to associate channel numbers with meaning.
Manifold allows vertex properties to be shared for efficient storage, or to have multiple property verts associated with a single geometric vertex, allowing sudden property changes, e.g. at Boolean intersections, without sacrificing manifoldness.
Manifolds also keep track of their relationships to their inputs, via OriginalIDs and the faceIDs and transforms accessible through MeshGL. This allows object-level properties to be re-associated with the output after many operations, particularly useful for materials. Since separate object's properties are not mixed, there is no requirement that channels have consistent meaning between different inputs.
Convert a MeshGL into a Manifold, retaining its properties and merging only the positions according to the merge vectors. Will return an empty Manifold and set an Error Status if the result is not an oriented 2-manifold. Will collapse degenerate triangles and unnecessary vertices.
All fields are read, making this structure suitable for a lossless round-trip of data from GetMeshGL. For multi-material input, use ReserveIDs to set a unique originalID for each material, and sort the materials into triangle runs.
| meshGL | The input MeshGL. |
| propertyTolerance | A vector of precision values for each property beyond position. If specified, the propertyTolerance vector must have size = numProp - 3. This is the amount of interpolation error allowed before two neighboring triangles are considered to be on a property boundary edge. Property boundary edges will be retained across operations even if the triangles are coplanar. Defaults to 1e-5, which works well for most properties in the [-1, 1] range. |
|
static |
Constructs a smooth version of the input mesh by creating tangents; this method will throw if you have supplied tangents with your mesh already. The actual triangle resolution is unchanged; use the Refine() method to interpolate to a higher-resolution curve.
By default, every edge is calculated for maximum smoothness (very much approximately), attempting to minimize the maximum mean Curvature magnitude. No higher-order derivatives are considered, as the interpolation is independent per triangle, only sharing constraints on their boundaries.
| meshGL | input MeshGL. |
| sharpenedEdges | If desired, you can supply a vector of sharpened halfedges, which should in general be a small subset of all halfedges. Order of entries doesn't matter, as each one specifies the desired smoothness (between zero and one, with one the default for all unspecified halfedges) and the halfedge index (3 * triangle index + [0,1,2] where 0 is the edge between triVert 0 and 1, etc). |
At a smoothness value of zero, a sharp crease is made. The smoothness is interpolated along each edge, so the specified value should be thought of as an average. Where exactly two sharpened edges meet at a vertex, their tangents are rotated to be colinear so that the sharpened edge can be continuous. Vertices with only one sharpened edge are completely smooth, allowing sharpened edges to smoothly vanish at termination. A single vertex can be sharpened by sharping all edges that are incident on it, allowing cones to be formed.
|
static |
Constructs a smooth version of the input mesh by creating tangents; this method will throw if you have supplied tangents with your mesh already. The actual triangle resolution is unchanged; use the Refine() method to interpolate to a higher-resolution curve.
By default, every edge is calculated for maximum smoothness (very much approximately), attempting to minimize the maximum mean Curvature magnitude. No higher-order derivatives are considered, as the interpolation is independent per triangle, only sharing constraints on their boundaries.
| mesh | input Mesh. |
| sharpenedEdges | If desired, you can supply a vector of sharpened halfedges, which should in general be a small subset of all halfedges. Order of entries doesn't matter, as each one specifies the desired smoothness (between zero and one, with one the default for all unspecified halfedges) and the halfedge index (3 * triangle index + [0,1,2] where 0 is the edge between triVert 0 and 1, etc). |
At a smoothness value of zero, a sharp crease is made. The smoothness is interpolated along each edge, so the specified value should be thought of as an average. Where exactly two sharpened edges meet at a vertex, their tangents are rotated to be colinear so that the sharpened edge can be continuous. Vertices with only one sharpened edge are completely smooth, allowing sharpened edges to smoothly vanish at termination. A single vertex can be sharpened by sharping all edges that are incident on it, allowing cones to be formed.
|
static |
Constructs a tetrahedron centered at the origin with one vertex at (1,1,1) and the rest at similarly symmetric points.
Constructs a unit cube (edge lengths all one), by default in the first octant, touching the origin. If any dimensions in size are negative, or if all are zero, an empty Manifold will be returned.
| size | The X, Y, and Z dimensions of the box. |
| center | Set to true to shift the center to the origin. |
|
static |
A convenience constructor for the common case of extruding a circle. Can also form cones if both radii are specified.
| height | Z-extent |
| radiusLow | Radius of bottom circle. Must be positive. |
| radiusHigh | Radius of top circle. Can equal zero. Default is equal to radiusLow. |
| circularSegments | How many line segments to use around the circle. Default is calculated by the static Defaults. |
| center | Set to true to shift the center to the origin. Default is origin at the bottom. |
Constructs a geodesic sphere of a given radius.
| radius | Radius of the sphere. Must be positive. |
| circularSegments | Number of segments along its diameter. This number will always be rounded up to the nearest factor of four, as this sphere is constructed by refining an octahedron. This means there are a circle of vertices on all three of the axis planes. Default is calculated by the static Defaults. |
|
static |
Constructs a manifold from a set of polygons by extruding them along the Z-axis. Note that high twistDegrees with small nDivisions may cause self-intersection. This is not checked here and it is up to the user to choose the correct parameters.
| crossSection | A set of non-overlapping polygons to extrude. |
| height | Z-extent of extrusion. |
| nDivisions | Number of extra copies of the crossSection to insert into the shape vertically; especially useful in combination with twistDegrees to avoid interpolation artifacts. Default is none. |
| twistDegrees | Amount to twist the top crossSection relative to the bottom, interpolated linearly for the divisions in between. |
| scaleTop | Amount to scale the top (independently in X and Y). If the scale is {0, 0}, a pure cone is formed with only a single vertex at the top. Note that scale is applied after twist. Default {1, 1}. |
|
static |
Constructs a manifold from a set of polygons by revolving this cross-section around its Y-axis and then setting this as the Z-axis of the resulting manifold. If the polygons cross the Y-axis, only the part on the positive X side is used. Geometrically valid input will result in geometrically valid output.
| crossSection | A set of non-overlapping polygons to revolve. |
| circularSegments | Number of segments along its diameter. Default is calculated by the static Defaults. |
| revolveDegrees | Number of degrees to revolve. Default is 360 degrees. |
Constructs a new manifold from a vector of other manifolds. This is a purely topological operation, so care should be taken to avoid creating overlapping results. It is the inverse operation of Decompose().
| manifolds | A vector of Manifolds to lazy-union together. |
| std::vector< Manifold > Decompose | ( | ) | const |
This operation returns a vector of Manifolds that are topologically disconnected. If everything is connected, the vector is length one, containing a copy of the original. It is the inverse operation of Compose().
| Mesh GetMesh | ( | ) | const |
This returns a Mesh of simple vectors of vertices and triangles suitable for saving or other operations outside of the context of this library.
| MeshGL GetMeshGL | ( | glm::ivec3 | normalIdx = glm::ivec3(0) | ) | const |
The most complete output of this library, returning a MeshGL that is designed to easily push into a renderer, including all interleaved vertex properties that may have been input. It also includes relations to all the input meshes that form a part of this result and the transforms applied to each.
| normalIdx | If the original MeshGL inputs that formed this manifold had properties corresponding to normal vectors, you can specify which property channels these are (x, y, z), which will cause this output MeshGL to automatically update these normals according to the applied transforms and front/back side. Each channel must be >= 3 and < numProp, and all original MeshGLs must use the same channels for their normals. |
| Manifold::Error Status | ( | ) | const |
Returns the reason for an input Mesh producing an empty Manifold. This Status only applies to Manifolds newly-created from an input Mesh - once they are combined into a new Manifold via operations, the status reverts to NoError, simply processing the problem mesh as empty. Likewise, empty meshes may still show NoError, for instance if they are small enough relative to their precision to be collapsed to nothing.
| int NumPropVert | ( | ) | const |
The number of property vertices in the Manifold. This will always be >= NumVert, as some physical vertices may be duplicated to account for different properties on different neighboring triangles.
| float Precision | ( | ) | const |
| int Genus | ( | ) | const |
The genus is a topological property of the manifold, representing the number of "handles". A sphere is 0, torus 1, etc. It is only meaningful for a single mesh, so it is best to call Decompose() first.
| Properties GetProperties | ( | ) | const |
Returns the surface area and volume of the manifold.
Returns the minimum gap between two manifolds. Returns a float between 0 and searchLength.
| other | The other manifold to compute the minimum gap to. |
| searchLength | The maximum distance to search for a minimum gap. |
| int OriginalID | ( | ) | const |
If this mesh is an original, this returns its meshID that can be referenced by product manifolds' MeshRelation. If this manifold is a product, this returns -1.
| Manifold AsOriginal | ( | ) | const |
This function condenses all coplanar faces in the relation, and collapses those edges. In the process the relation to ancestor meshes is lost and this new Manifold is marked an original. Properties are preserved, so if they do not match across an edge, that edge will be kept.
Returns the first of n sequential new unique mesh IDs for marking sets of triangles that can be looked up after further operations. Assign to MeshGL.runOriginalID vector.
| Manifold Translate | ( | glm::vec3 | v | ) | const |
Move this Manifold in space. This operation can be chained. Transforms are combined and applied lazily.
| v | The vector to add to every vertex. |
| Manifold Scale | ( | glm::vec3 | v | ) | const |
Scale this Manifold in space. This operation can be chained. Transforms are combined and applied lazily.
| v | The vector to multiply every vertex by per component. |
Applies an Euler angle rotation to the manifold, first about the X axis, then Y, then Z, in degrees. We use degrees so that we can minimize rounding error, and eliminate it completely for any multiples of 90 degrees. Additionally, more efficient code paths are used to update the manifold when the transforms only rotate by multiples of 90 degrees. This operation can be chained. Transforms are combined and applied lazily.
| xDegrees | First rotation, degrees about the X-axis. |
| yDegrees | Second rotation, degrees about the Y-axis. |
| zDegrees | Third rotation, degrees about the Z-axis. |
Transform this Manifold in space. The first three columns form a 3x3 matrix transform and the last is a translation vector. This operation can be chained. Transforms are combined and applied lazily.
| m | The affine transform matrix to apply to all the vertices. |
| Manifold Mirror | ( | glm::vec3 | normal | ) | const |
Mirror this Manifold over the plane described by the unit form of the given normal vector. If the length of the normal is zero, an empty Manifold is returned. This operation can be chained. Transforms are combined and applied lazily.
| normal | The normal vector of the plane to be mirrored over |
This function does not change the topology, but allows the vertices to be moved according to any arbitrary input function. It is easy to create a function that warps a geometrically valid object into one which overlaps, but that is not checked here, so it is up to the user to choose their function with discretion.
| warpFunc | A function that modifies a given vertex position. |
Same as Manifold::Warp but calls warpFunc with with a VecView which is roughly equivalent to std::span pointing to all vec3 elements to be modified in-place
| warpFunc | A function that modifies multiple vertex positions. |
Create a new copy of this manifold with updated vertex properties by supplying a function that takes the existing position and properties as input. You may specify any number of output properties, allowing creation and removal of channels. Note: undefined behavior will result if you read past the number of input properties or write past the number of output properties.
| numProp | The new number of properties per vertex. |
| propFunc | A function that modifies the properties of a given vertex. |
Curvature is the inverse of the radius of curvature, and signed such that positive is convex and negative is concave. There are two orthogonal principal curvatures at any point on a manifold, with one maximum and the other minimum. Gaussian curvature is their product, while mean curvature is their sum. This approximates them for every vertex and assigns them as vertex properties on the given channels.
| gaussianIdx | The property channel index in which to store the Gaussian curvature. An index < 0 will be ignored (stores nothing). The property set will be automatically expanded to include the channel index specified. |
| meanIdx | The property channel index in which to store the mean curvature. An index < 0 will be ignored (stores nothing). The property set will be automatically expanded to include the channel index specified. |
Fills in vertex properties for normal vectors, calculated from the mesh geometry. Flat faces composed of three or more triangles will remain flat.
| normalIdx | The property channel in which to store the X values of the normals. The X, Y, and Z channels will be sequential. The property set will be automatically expanded such that NumProp will be at least normalIdx + 3. |
| minSharpAngle | Any edges with angles greater than this value will remain sharp, getting different normal vector properties on each side of the edge. By default, no edges are sharp and all normals are shared. With a value of zero, the model is faceted and all normals match their triangle normals, but in this case it would be better not to calculate normals at all. |
Smooths out the Manifold by filling in the halfedgeTangent vectors. The geometry will remain unchanged until Refine or RefineToLength is called to interpolate the surface. This version uses the supplied vertex normal properties to define the tangent vectors. Faces of two coplanar triangles will be marked as quads, while faces with three or more will be flat.
| normalIdx | The first property channel of the normals. NumProp must be at least normalIdx + 3. Any vertex where multiple normals exist and don't agree will result in a sharp edge. |
Smooths out the Manifold by filling in the halfedgeTangent vectors. The geometry will remain unchanged until Refine or RefineToLength is called to interpolate the surface. This version uses the geometry of the triangles and pseudo-normals to define the tangent vectors. Faces of two coplanar triangles will be marked as quads.
| minSharpAngle | degrees, default 60. Any edges with angles greater than this value will remain sharp. The rest will be smoothed to G1 continuity, with the caveat that flat faces of three or more triangles will always remain flat. With a value of zero, the model is faceted, but in this case there is no point in smoothing. |
| minSmoothness | range: 0 - 1, default 0. The smoothness applied to sharp angles. The default gives a hard edge, while values > 0 will give a small fillet on these sharp edges. A value of 1 is equivalent to a minSharpAngle of 180 - all edges will be smooth. |
Increase the density of the mesh by splitting every edge into n pieces. For instance, with n = 2, each triangle will be split into 4 triangles. Quads will ignore their interior triangle bisector. These will all be coplanar (and will not be immediately collapsed) unless the Mesh/Manifold has halfedgeTangents specified (e.g. from the Smooth() constructor), in which case the new vertices will be moved to the interpolated surface according to their barycentric coordinates.
| n | The number of pieces to split every edge into. Must be > 1. |
Increase the density of the mesh by splitting each edge into pieces of roughly the input length. Interior verts are added to keep the rest of the triangulation edges also of roughly the same length. If halfedgeTangents are present (e.g. from the Smooth() constructor), the new vertices will be moved to the interpolated surface according to their barycentric coordinates. Quads will ignore their interior triangle bisector.
| length | The length that edges will be broken down to. |
The central operation of this library: the Boolean combines two manifolds into another by calculating their intersections and removing the unused portions. ε-valid inputs will produce ε-valid output. ε-invalid input may fail triangulation.
These operations are optimized to produce nearly-instant results if either input is empty or their bounding boxes do not overlap.
| second | The other Manifold. |
| op | The type of operation to perform. |
Perform the given boolean operation on a list of Manifolds. In case of Subtract, all Manifolds in the tail are differenced from the head.
Split cuts this manifold in two using the cutter manifold. The first result is the intersection, second is the difference. This is more efficient than doing them separately.
| cutter |
Convenient version of Split() for a half-space.
| normal | This vector is normal to the cutting plane and its length does not matter. The first result is in the direction of this vector, the second result is on the opposite side. |
| originOffset | The distance of the plane from the origin in the direction of the normal vector. |
Identical to SplitByPlane(), but calculating and returning only the first result.
| normal | This vector is normal to the cutting plane and its length does not matter. The result is in the direction of this vector from the plane. |
| originOffset | The distance of the plane from the origin in the direction of the normal vector. |
| CrossSection Slice | ( | float | height = 0 | ) | const |
Returns the cross section of this object parallel to the X-Y plane at the specified Z height, defaulting to zero. Using a height equal to the bottom of the bounding box will return the bottom faces, while using a height equal to the top of the bounding box will return empty.
| CrossSection Project | ( | ) | const |
Returns a cross section representing the projected outline of this object onto the X-Y plane.
| Manifold Hull | ( | ) | const |
Compute the convex hull of this manifold.
Compute the convex hull enveloping a set of manifolds.
| manifolds | A vector of manifolds over which to compute a convex hull. |
Compute the convex hull of a set of points. If the given points are fewer than 4, or they are all coplanar, an empty Manifold will be returned.
| pts | A vector of 3-dimensional points over which to compute a convex hull. |
| bool MatchesTriNormals | ( | ) | const |
The triangle normal vectors are saved over the course of operations rather than recalculated to avoid rounding error. This checks that triangles still match their normal vectors within Precision().
| int NumDegenerateTris | ( | ) | const |
The number of triangles that are colinear within Precision(). This library attempts to remove all of these, but it cannot always remove all of them without changing the mesh by too much.
1.9.8