build based on 081fb94

dev/api/index.html

@@ -58,20 +58,20 @@
 end</code></pre><h2><a class="nav-anchor" id="Meshing-Algorithms-1" href="#Meshing-Algorithms-1">Meshing Algorithms</a></h2><p>Three meshing algorithms exist:</p><ul><li><code>MarchingCubes()</code></li><li><code>MarchingTetrahedra()</code></li><li><code>NaiveSurfaceNets()</code></li></ul><p>Each takes optional <code>iso</code>, <code>eps</code>, and <code>insidepositive</code> parameters, e.g. <code>MarchingCubes(iso=0.0,eps=1e-6,insidepositive=false)</code>.</p><p>Here <code>iso</code> controls the offset for the boundary detection. By default this is set to 0. <code>eps</code> is the detection tolerance for a voxel edge intersection. <code>insidepositive</code> sets the sign convention for inside/outside the surface (default: false).</p><p>Users must construct an algorithm type and use it as an argument to a GeometryTypes mesh call or <code>isosurface</code> call.</p><p>Below is a comparison of the algorithms:</p><table><tr><th style="text-align: right">Algorithm Type</th><th style="text-align: right">Face Type</th><th style="text-align: right">Unique Vertices</th><th style="text-align: right">Performance</th><th style="text-align: right">Interpolation</th></tr><tr><td style="text-align: right">Naive Surface Nets</td><td style="text-align: right">Quad</td><td style="text-align: right">Yes</td><td style="text-align: right">~1x</td><td style="text-align: right">Voxel Edge Weight</td></tr><tr><td style="text-align: right">Marching Cubes</td><td style="text-align: right">Triangle</td><td style="text-align: right">No/Partial</td><td style="text-align: right">1x</td><td style="text-align: right">Linear on Edge</td></tr><tr><td style="text-align: right">Marching Tetrahedra</td><td style="text-align: right">Triangle</td><td style="text-align: right">Yes</td><td style="text-align: right">3x</td><td style="text-align: right">Linear on Edge</td></tr></table><p>Visual Comparison: From left: Marching Cubes, Naive Surface Nets, Marching Tetrahedra</p><p><img src="../img/comparison.png" alt="comparison"/></p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.MarchingCubes" href="#Meshing.MarchingCubes"><code>Meshing.MarchingCubes</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">MarchingCubes(iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 MarchingCubes(;iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 MarchingCubes(iso)
-MarchingCubes(iso,eps)</code></pre><p>Specifies the use of the Marching Cubes algorithm for isosurface extraction. This algorithm provides a good balance between performance and vertex count. In contrast to the other algorithms, vertices may be repeated, so mesh size may be large and it will be difficult to extract topological/connectivity information.</p><ul><li><code>iso</code> (default: 0.0) specifies the iso level to use for surface extraction.</li><li><code>eps</code> (default: 1e-3) is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> (default: true) if true will merge vertices within a voxel to reduce mesh size by around 30% and with slight performance improvement.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/9c0d93cb520e67eb08a0e749975298e79e56595d/src/algorithmtypes.jl#L29-L44">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.MarchingTetrahedra" href="#Meshing.MarchingTetrahedra"><code>Meshing.MarchingTetrahedra</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">MarchingTetrahedra(iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
+MarchingCubes(iso,eps)</code></pre><p>Specifies the use of the Marching Cubes algorithm for isosurface extraction. This algorithm provides a good balance between performance and vertex count. In contrast to the other algorithms, vertices may be repeated, so mesh size may be large and it will be difficult to extract topological/connectivity information.</p><ul><li><code>iso</code> (default: 0.0) specifies the iso level to use for surface extraction.</li><li><code>eps</code> (default: 1e-3) is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> (default: true) if true will merge vertices within a voxel to reduce mesh size by around 30% and with slight performance improvement.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/081fb9477fa9a55b1a77ee0b7ae66dc63093eb08/src/algorithmtypes.jl#L29-L44">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.MarchingTetrahedra" href="#Meshing.MarchingTetrahedra"><code>Meshing.MarchingTetrahedra</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">MarchingTetrahedra(iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 MarchingTetrahedra(;iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 MarchingTetrahedra(iso)
-MarchingTetrahedra(iso,eps)</code></pre><p>Specifies the use of the Marching Tetrahedra algorithm for isosurface extraction. This algorithm has a roughly 2x performance penalty compared to Marching Cubes, and generates more faces. However, each vertex is guaranteed to not be repeated, making this algorithm useful for topological analysis.</p><ul><li><code>iso</code> specifies the iso level to use for surface extraction.</li><li><code>eps</code> is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> (default: true) if false, vertices will not be unique and have repeated face references.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/9c0d93cb520e67eb08a0e749975298e79e56595d/src/algorithmtypes.jl#L52-L67">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.NaiveSurfaceNets" href="#Meshing.NaiveSurfaceNets"><code>Meshing.NaiveSurfaceNets</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">NaiveSurfaceNets(iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
+MarchingTetrahedra(iso,eps)</code></pre><p>Specifies the use of the Marching Tetrahedra algorithm for isosurface extraction. This algorithm has a roughly 2x performance penalty compared to Marching Cubes, and generates more faces. However, each vertex is guaranteed to not be repeated, making this algorithm useful for topological analysis.</p><ul><li><code>iso</code> specifies the iso level to use for surface extraction.</li><li><code>eps</code> is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> (default: true) if false, vertices will not be unique and have repeated face references.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/081fb9477fa9a55b1a77ee0b7ae66dc63093eb08/src/algorithmtypes.jl#L52-L67">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.NaiveSurfaceNets" href="#Meshing.NaiveSurfaceNets"><code>Meshing.NaiveSurfaceNets</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">NaiveSurfaceNets(iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 NaiveSurfaceNets(;iso=0.0, eps=1e-3, reduceverts=true, insidepositive=false)
 NaiveSurfaceNets(iso)
-NaiveSurfaceNets(iso,eps)</code></pre><p>Specifies the use of the Naive Surface Nets algorithm for isosurface extraction. This algorithm has a slight performance advantage in some cases over Marching Cubes. Each vertex is guaranteed to not be repeated (useful for topological analysis), however the algorithm does not guarantee accuracy and generates quad faces.</p><ul><li><code>iso</code> specifies the iso level to use for surface extraction.</li><li><code>eps</code> is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> reserved for future use.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/9c0d93cb520e67eb08a0e749975298e79e56595d/src/algorithmtypes.jl#L75-L90">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.AbstractMeshingAlgorithm" href="#Meshing.AbstractMeshingAlgorithm"><code>Meshing.AbstractMeshingAlgorithm</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">AbstractMeshingAlgorithm</code></pre><p>Abstract type to specify an algorithm for isosurface extraction. See:</p><ul><li>MarchingCubes</li><li>MarchingTetrahedra</li><li>NaiveSurfaceNets</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/9c0d93cb520e67eb08a0e749975298e79e56595d/src/algorithmtypes.jl#L2-L10">source</a></section><h2><a class="nav-anchor" id="Isosurface-1" href="#Isosurface-1">Isosurface</a></h2><p><code>isosurface</code> is the common and generic API for isosurface extraction with any type of abstract vector/vertex/face type.</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.isosurface" href="#Meshing.isosurface"><code>Meshing.isosurface</code></a> — <span class="docstring-category">Function</span>.</div><div><div><pre><code class="language-julia">function isosurface(sdf::AbstractArray{T, 3}, [ method::AbstractMeshingAlgorithm ],
+NaiveSurfaceNets(iso,eps)</code></pre><p>Specifies the use of the Naive Surface Nets algorithm for isosurface extraction. This algorithm has a slight performance advantage in some cases over Marching Cubes. Each vertex is guaranteed to not be repeated (useful for topological analysis), however the algorithm does not guarantee accuracy and generates quad faces.</p><ul><li><code>iso</code> specifies the iso level to use for surface extraction.</li><li><code>eps</code> is the tolerence around a voxel corner to ensure manifold mesh generation.</li><li><code>reduceverts</code> reserved for future use.</li><li><code>insidepositive</code> (default: false) set true if the sign convention inside the surface is positive, common for NRRD and DICOM data</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/081fb9477fa9a55b1a77ee0b7ae66dc63093eb08/src/algorithmtypes.jl#L75-L90">source</a></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.AbstractMeshingAlgorithm" href="#Meshing.AbstractMeshingAlgorithm"><code>Meshing.AbstractMeshingAlgorithm</code></a> — <span class="docstring-category">Type</span>.</div><div><div><pre><code class="language-julia">AbstractMeshingAlgorithm</code></pre><p>Abstract type to specify an algorithm for isosurface extraction. See:</p><ul><li>MarchingCubes</li><li>MarchingTetrahedra</li><li>NaiveSurfaceNets</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/081fb9477fa9a55b1a77ee0b7ae66dc63093eb08/src/algorithmtypes.jl#L2-L10">source</a></section><h2><a class="nav-anchor" id="Isosurface-1" href="#Isosurface-1">Isosurface</a></h2><p><code>isosurface</code> is the common and generic API for isosurface extraction with any type of abstract vector/vertex/face type.</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Meshing.isosurface" href="#Meshing.isosurface"><code>Meshing.isosurface</code></a> — <span class="docstring-category">Function</span>.</div><div><div><pre><code class="language-julia">function isosurface(sdf::AbstractArray{T, 3}, [ method::AbstractMeshingAlgorithm ],
                      [ VertType = SVector{3,Float64} ], [ FaceType} = SVector{3, Int} ] ;
                      origin = SVector(-1.0,-1.0,-1.0), widths = SVector(2.0,2.0,2.0))
 
 function isosurface(f::Function, [ method::AbstractMeshingAlgorithm ],
                      [ VertType = SVector{3,Float64} ], [FaceType = SVector{3, Int} ] ;
                      origin = SVector(-1.0,-1.0,-1.0), widths = SVector(2.0,2.0,2.0)
-                     samples=(24,24,24))`</code></pre><p><code>isosurface</code> is the general interface to all isosurface extraction algorithms.</p><p>Returns: (Vector{VertType}, Vector{FaceType})</p><p>Defaults:</p><ul><li>VertType = SVector{3,Float64} (positional)</li><li>FaceType = SVector{3, Int} ] ; (positional)</li><li>origin = SVector(-1.0,-1.0,-1.0) (keyword)</li><li>widths = SVector(2.0,2.0,2.0) (keyword)</li><li>samples=(24,24,24) (keyword, function sampling only)</li></ul><p><code>method</code> must be an instance of an <code>AbstractMeshingAlgorithm</code>, e.g.:</p><ul><li>MarchingCubes()</li><li>MarchingTetrahedra()</li><li>NaiveSurfaceNets()</li></ul><p>If <code>isosurface</code> is called without a specified algorithm, it will default to MarchingCubes.</p><p>If a subtype of <code>AbstractArray</code> is specified, the mesh will by default be centered at the origin between (-1,1) in each axis. This may be overridden by specifying a new origin and widths for the axis-aligned bounding box using keywords of the same names. For example if we want our vertices in the range of (0,1), we can specify <code>origin=SVector(0,0,0)</code> and <code>widths = SVector(1,1,1)</code>.</p><p>If a function is specified, it will be uniformly sampled in each axis by the amount specified in <code>samples</code>. The function is called using the specifed <code>VertType</code>.</p><p>Performance Tips:</p><ul><li>ensure <code>VertType</code>, <code>origin</code>, and <code>widths</code> are all of the same type</li><li>ensure the element type of <code>VertType</code> is the same as the specified isolevel</li></ul><p>See also:</p><ul><li>MarchingCubes</li><li>MarchingTetrahedra</li><li>NaiveSurfaceNets</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/9c0d93cb520e67eb08a0e749975298e79e56595d/src/common.jl#L56-L102">source</a></section><h2><a class="nav-anchor" id="GeometryBasics-1" href="#GeometryBasics-1">GeometryBasics</a></h2><p>Meshing extends the mesh types in GeometryBasics for convenience and use with visualization tools such as Makie and MeshCat. Any instance of a <code>Mesh</code> may be created as follows:</p><pre><code class="language-none">    mesh(df::SignedDistanceField{3,ST,FT}, method::AbstractMeshingAlgorithm; pointtype=nothing, facetype=nothing) where {ST, FT}
+                     samples=(24,24,24))`</code></pre><p><code>isosurface</code> is the general interface to all isosurface extraction algorithms.</p><p>Returns: (Vector{VertType}, Vector{FaceType})</p><p>Defaults:</p><ul><li>VertType = SVector{3,Float64} (positional)</li><li>FaceType = SVector{3, Int} ] ; (positional)</li><li>origin = SVector(-1.0,-1.0,-1.0) (keyword)</li><li>widths = SVector(2.0,2.0,2.0) (keyword)</li><li>samples=(24,24,24) (keyword, function sampling only)</li></ul><p><code>method</code> must be an instance of an <code>AbstractMeshingAlgorithm</code>, e.g.:</p><ul><li>MarchingCubes()</li><li>MarchingTetrahedra()</li><li>NaiveSurfaceNets()</li></ul><p>If <code>isosurface</code> is called without a specified algorithm, it will default to MarchingCubes.</p><p>If a subtype of <code>AbstractArray</code> is specified, the mesh will by default be centered at the origin between (-1,1) in each axis. This may be overridden by specifying a new origin and widths for the axis-aligned bounding box using keywords of the same names. For example if we want our vertices in the range of (0,1), we can specify <code>origin=SVector(0,0,0)</code> and <code>widths = SVector(1,1,1)</code>.</p><p>If a function is specified, it will be uniformly sampled in each axis by the amount specified in <code>samples</code>. The function is called using the specifed <code>VertType</code>.</p><p>Performance Tips:</p><ul><li>ensure <code>VertType</code>, <code>origin</code>, and <code>widths</code> are all of the same type</li><li>ensure the element type of <code>VertType</code> is the same as the specified isolevel</li></ul><p>See also:</p><ul><li>MarchingCubes</li><li>MarchingTetrahedra</li><li>NaiveSurfaceNets</li></ul></div></div><a class="source-link" target="_blank" href="https://github.com/JuliaGeometry/Meshing.jl/blob/081fb9477fa9a55b1a77ee0b7ae66dc63093eb08/src/common.jl#L56-L102">source</a></section><h2><a class="nav-anchor" id="GeometryBasics-1" href="#GeometryBasics-1">GeometryBasics</a></h2><p>Meshing extends the mesh types in GeometryBasics for convenience and use with visualization tools such as Makie and MeshCat. Any instance of a <code>Mesh</code> may be created as follows:</p><pre><code class="language-none">    mesh(df::SignedDistanceField{3,ST,FT}, method::AbstractMeshingAlgorithm; pointtype=nothing, facetype=nothing) where {ST, FT}
     mesh(f::Function, h::Rect, samples::NTuple{3,T}, method::AbstractMeshingAlgorithm; pointtype=nothing, facetype=nothing) where {T &lt;: Integer}
     mesh(f::Function, h::Rect, method::AbstractMeshingAlgorithm; pointtype=nothing, facetype=nothing, samples::NTuple{3,T}=_DEFAULT_SAMPLES) where {T &lt;: Integer}
     mesh(volume::AbstractArray{T, 3}, method::AbstractMeshingAlgorithm; pointtype=nothing, facetype=nothing, vargs...) where {T}</code></pre><p>With the GeometryBasics API, the bounding box is specified by a <code>Rect</code>, or keyword specified <code>origin</code> and <code>widths</code>.</p><p>Some notes on pointtype and facetype. They can be used to create a mesh with the desired point &amp; face types. If they&#39;re left at nothing, the element type best matching the method and signed distancefield is used. Both the element type of the volume, element type of the <code>vertextype</code>, and type of <code>iso</code> in the <code>AbstractMeshingAlgorithm</code> are all promoted. This also allows the use of auto differentiation tools on the isosurface construction.</p><h2><a class="nav-anchor" id="GeometryTypes-1" href="#GeometryTypes-1">GeometryTypes</a></h2><p>Meshing extends the mesh types in GeometryTypes for convience and use with visualization tools such as Makie and MeshCat. Any instance of an <code>AbstractMesh</code> may be called with arguments as follows:</p><pre><code class="language-none">    (::Type{MT})(df::SignedDistanceField{3,ST,FT}, method::AbstractMeshingAlgorithm)::MT where {MT &lt;: AbstractMesh, ST, FT}