conquer3d 0.8.2__tar.gz → 0.8.4__tar.gz

{conquer3d-0.8.2/conquer3d.egg-info → conquer3d-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conquer3d
-Version: 0.8.2
+Version: 0.8.4
 Summary: Geometric Cuda Tool Box
 Author-email: Do Hoang Khoi <khoido8899@gmail.com>
 License-Expression: MIT
@@ -124,7 +124,7 @@ Every stage of one extraction, from input mesh to extracted surface.
 
 <img src="docs/assets/img/fig-sign-modes.webp" alt="Sign modes" width="100%">
 
-One slice through a mesh, signed by each of the six ways of deciding inside.
+One slice through each of two meshes, signed by all seven ways of deciding inside.
 
 ### Ray queries
 

{conquer3d-0.8.2 → conquer3d-0.8.4}/README.md

@@ -91,7 +91,7 @@ Every stage of one extraction, from input mesh to extracted surface.
 
 <img src="docs/assets/img/fig-sign-modes.webp" alt="Sign modes" width="100%">
 
-One slice through a mesh, signed by each of the six ways of deciding inside.
+One slice through each of two meshes, signed by all seven ways of deciding inside.
 
 ### Ray queries
 

{conquer3d-0.8.2 → conquer3d-0.8.4}/conquer3d/_C.pyi

@@ -4,7 +4,7 @@ Conquer3D Python bindings
 from __future__ import annotations
 import torch
 import typing
-__all__: list[str] = ['BVH', 'GSBVH', 'KDTree', 'MeshBVH', 'PGSBVH', 'Ray', 'Triangle', 'TriangleMesh', 'build_sparse_grid_from_active_voxels', 'compute_active_voxels', 'compute_flood_fill', 'compute_flood_fill_cf', 'compute_grid_normal', 'compute_gs_aabb_func', 'compute_gs_covi_func', 'compute_superquadric_mesh_func', 'compute_zcurve', 'create_sphere', 'create_tetrahedra', 'create_voxel_cloud_from_tmesh', 'create_voxel_grid', 'create_voxel_grid_from_tmesh', 'dual_contouring', 'dual_contouring_backward', 'dual_marching_cubes', 'dual_marching_cubes_backward', 'get_active_voxel_ids_from_depth', 'marching_cubes', 'marching_cubes_asymptotic', 'marching_cubes_asymptotic_backward', 'marching_cubes_backward', 'marching_tetrahedra', 'marching_tetrahedra_backward', 'marching_tetrahedra_grid', 'marching_tetrahedra_grid_backward', 'one_sided_chamfer_distance', 'one_sided_chamfer_distance_backward', 'single_view_volume_integral', 'solve_gs_neighbor_mahalanobis_radius_func', 'solve_pgs_cluster_tangency_radius_func']
+__all__: list[str] = ['BVH', 'GSBVH', 'KDTree', 'MeshBVH', 'PGSBVH', 'Ray', 'Triangle', 'TriangleMesh', 'build_sparse_grid_from_active_voxels', 'compute_active_voxels', 'compute_flood_fill', 'compute_flood_fill_band', 'compute_flood_fill_cf', 'compute_grid_normal', 'compute_gs_aabb_func', 'compute_gs_covi_func', 'compute_superquadric_mesh_func', 'compute_zcurve', 'create_sphere', 'create_tetrahedra', 'create_voxel_cloud_from_tmesh', 'create_voxel_grid', 'create_voxel_grid_from_tmesh', 'dual_contouring', 'dual_contouring_backward', 'dual_marching_cubes', 'dual_marching_cubes_backward', 'get_active_voxel_ids_from_depth', 'marching_cubes', 'marching_cubes_asymptotic', 'marching_cubes_asymptotic_backward', 'marching_cubes_backward', 'marching_tetrahedra', 'marching_tetrahedra_backward', 'marching_tetrahedra_grid', 'marching_tetrahedra_grid_backward', 'one_sided_chamfer_distance', 'one_sided_chamfer_distance_backward', 'single_view_volume_integral', 'solve_gs_neighbor_mahalanobis_radius_func', 'solve_pgs_cluster_tangency_radius_func']
 class BVH:
     """
     
@@ -315,7 +315,7 @@ class MeshBVH(BVH):
                          triangles (torch.Tensor): (M, 3) int32 mesh triangles on CUDA.
                          return_sdf (bool, optional): Return signed distance instead of unsigned. Defaults to False.
                          return_prj_pts (bool, optional): Return closest surface projections. Defaults to True.
-                         sign_mode (int, optional): Sign evaluation method (0: ray parity, 1: Fast Winding Number, 2: angle-weighted pseudonormals, 3: flood-fill mask, 4: hybrid, 5: coarse-to-fine flood fill). Defaults to 0.
+                         sign_mode (int, optional): Sign evaluation method (0: ray parity, 1: Fast Winding Number, 2: angle-weighted pseudonormals, 3: flood-fill mask, 4: hybrid, 5: coarse-to-fine flood fill, 6: band flood fill that seals small holes). Defaults to 0.
                          return_occ (bool, optional): If True, additionally returns binary occupancy defined as
                              `distances < 0`. Only active when `return_sdf=True`; with an unsigned distance the
                              occupancy slot is returned as None, since unsigned distances carry no inside/outside
@@ -744,6 +744,37 @@ class TriangleMesh:
         """
         Builds and returns the MeshBVH for the mesh.
         """
+    def build_flood_fill_band_data(self, grid_min: list[float] | None = None, grid_max: list[float] | None = None, res: list[int] | None = None, dilation_radius: int = 2, cavity_max_voxels: int = -1) -> None:
+        """
+                     Pre-computes the leak-resistant band flood fill used by sign_mode=6.
+        
+                     Water floods from the grid boundary and stops at the surface band dilated by
+                     `dilation_radius` lattice spacings, so holes up to about `2 * dilation_radius + 3` spacings
+                     across are sealed; small cavities the dilation encloses are released and the band is resolved
+                     by neighbour agreement. Memory scales with surface area, like sign_mode=5.
+        
+                     The wall trades thin detail for leak resistance: solid parts thinner than about
+                     `2 * dilation_radius + 3` spacings vanish, slots narrower than 3 spacings fill in, and a sealed-off
+                     pocket holding more than `cavity_max_voxels` free vertices stays interior.
+        
+                     Args:
+                         grid_min (List[float], optional): Lower grid corner [x, y, z]. When either bound is omitted,
+                             both default to the mesh bounds padded by (r + 3) * E / (res - 1 - 2 * (r + 3)), with E
+                             the largest extent.
+                         grid_max (List[float], optional): Upper grid corner [x, y, z].
+                         res (List[int], optional): Vertices per axis [rx, ry, rz]. Defaults to [128, 128, 128].
+                         dilation_radius (int, optional): Chebyshev dilation radius in spacings. Defaults to 2.
+                         cavity_max_voxels (int, optional): Largest interior component, in vertices, released for
+                             resolution; -1 selects (2 * dilation_radius + 1)^3 and 0 disables the release.
+                             Defaults to -1.
+        
+                     Raises:
+                         RuntimeError: If explicit bounds leave less than `dilation_radius + 2` spacings between the
+                             mesh and the grid boundary; the message names the padding required.
+        
+                     Example:
+                         >>> mesh.build_flood_fill_band_data(res=[512, 512, 512])
+        """
     def build_flood_fill_cf_data(self, grid_min: list[float] | None = None, grid_max: list[float] | None = None, res: list[int] | None = None, block_size: list[int] | None = None, connectivity: int = 6) -> None:
         """
                      Pre-computes a 2-level Coarse-to-Fine (CF) volumetric flood-fill structure (< 10 MB VRAM at 1024^3).
@@ -1085,6 +1116,7 @@ class TriangleMesh:
                              - 3: Volumetric 3D flood-fill mask (dense).
                              - 4: Hybrid WN + pseudonormals.
                              - 5: Coarse-to-Fine (CF) Hierarchical Volumetric Flood Fill (< 10 MB VRAM).
+                            - 6: Band flood fill that seals small holes (memory like 5).
                              Defaults to 0.
                          distance_mode (int, optional): Distance algorithm (0: Ericson closest point, 1: projected normal). Defaults to 0.
                          return_occ (bool, optional): If True, additionally returns binary occupancy defined as
@@ -1151,6 +1183,41 @@ class TriangleMesh:
                          >>> pts, tri_ids, normals, _ = mesh.sample_points(5000, return_normals=True)
         """
     @property
+    def band_block_lookup(self) -> torch.Tensor:
+        """
+        Band flood fill int32 coarse-index to band-slot lookup, -1 outside the band.
+        """
+    @property
+    def band_coarse_mask(self) -> torch.Tensor:
+        """
+        Band flood fill coarse int8 labels (2 exterior, -1 interior, 1 band block).
+        """
+    @property
+    def band_fine_masks(self) -> torch.Tensor:
+        """
+        Band flood fill (N, 8, 8, 8) int8 fine labels (2 exterior, -1 interior).
+        """
+    @property
+    def band_grid_max(self) -> list[float]:
+        """
+        Band flood fill grid upper corner.
+        """
+    @property
+    def band_grid_min(self) -> list[float]:
+        """
+        Band flood fill grid lower corner.
+        """
+    @property
+    def band_grid_res(self) -> list[int]:
+        """
+        Band flood fill grid vertex resolution.
+        """
+    @property
+    def band_stats(self) -> dict[str, int]:
+        """
+        Band flood fill build diagnostics: num_band_blocks, flood_rounds, num_released_cavity_voxels, resolution_rounds, num_unresolved_defaulted, bvh_stack_overflows.
+        """
+    @property
     def bvh(self) -> MeshBVH:
         """
         The Bounding Volume Hierarchy (MeshBVH) built for this mesh.
@@ -1369,6 +1436,50 @@ def compute_flood_fill(vertices: torch.Tensor, triangles: torch.Tensor, aabb_min
                   >>> from conquer3d._C import compute_flood_fill
                   >>> mask = compute_flood_fill(verts, tris, a_mins, a_maxs, children, obj_ids, [-1,-1,-1], [1,1,1], [64,64,64], 6)
     """
+def compute_flood_fill_band(vertices: torch.Tensor, triangles: torch.Tensor, aabb_mins: torch.Tensor, aabb_maxs: torch.Tensor, bvh_children: torch.Tensor, object_ids: torch.Tensor, grid_min: list[float], grid_max: list[float], grid_res: list[int], dilation_radius: int = 2, cavity_max_voxels: int = -1) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, list[int], list[int], dict[str, int]]:
+    """
+              Computes the leak-resistant band flood fill used by sign_mode=6.
+    
+              Water floods from the grid boundary and stops at a wall of lattice vertices: the corners of
+              every cell a triangle touches, dilated by `dilation_radius` spacings, so holes narrower than
+              the dilation are sealed. Small interior pockets the dilation creates are released and the wall
+              is resolved by neighbour agreement, leaving every vertex exterior or interior. Storage follows
+              compute_flood_fill_cf, so memory scales with surface area rather than volume.
+    
+              The wall trades thin detail for leak resistance: solid parts thinner than about
+              `2 * dilation_radius + 3` spacings vanish, slots narrower than 3 spacings fill in, and a sealed-off
+              pocket holding more than `cavity_max_voxels` free vertices stays interior.
+    
+              The lattice has `grid_res` vertices per axis spanning [grid_min, grid_max]. The mesh must lie
+              at least `dilation_radius + 2` spacings inside it; otherwise a RuntimeError names the padding
+              required.
+    
+              Args:
+                  vertices (torch.Tensor): (V, 3) float32 mesh vertices on CUDA.
+                  triangles (torch.Tensor): (F, 3) int32 triangle indices on CUDA.
+                  aabb_mins (torch.Tensor): (2F-1, 3) float32 BVH node min corners.
+                  aabb_maxs (torch.Tensor): (2F-1, 3) float32 BVH node max corners.
+                  bvh_children (torch.Tensor): (2F-1, 2) int32 BVH child node indices.
+                  object_ids (torch.Tensor): (F,) int32 leaf-to-triangle map.
+                  grid_min (List[float]): Lower grid corner [x, y, z].
+                  grid_max (List[float]): Upper grid corner [x, y, z].
+                  grid_res (List[int]): Vertices per axis [rx, ry, rz].
+                  dilation_radius (int, optional): Chebyshev dilation radius in spacings. Defaults to 2.
+                  cavity_max_voxels (int, optional): Largest interior component, in vertices, released for
+                      resolution; -1 selects (2 * dilation_radius + 1)^3 and 0 disables the release.
+                      Defaults to -1.
+    
+              Returns:
+                  Tuple[Tensor, Tensor, Tensor, Tensor, List[int], List[int], Dict[str, int]]:
+                      - coarse_mask (Tensor): (Cx, Cy, Cz) int8 labels: 2 exterior, -1 interior, 1 band block.
+                      - band_block_coords (Tensor): (N, 3) int32 coarse coordinates of the band blocks.
+                      - band_block_lookup (Tensor): (Cx, Cy, Cz) int32 band slot, -1 elsewhere.
+                      - fine_masks (Tensor): (N, 8, 8, 8) int8 labels: 2 exterior, -1 interior.
+                      - block_size (List[int]): [8, 8, 8].
+                      - coarse_res (List[int]): [Cx, Cy, Cz] = ceil(grid_res / 8).
+                      - stats (Dict[str, int]): num_band_blocks, flood_rounds, num_released_cavity_voxels,
+                        resolution_rounds, num_unresolved_defaulted, bvh_stack_overflows.
+    """
 def compute_flood_fill_cf(vertices: torch.Tensor, triangles: torch.Tensor, aabb_mins: torch.Tensor, aabb_maxs: torch.Tensor, bvh_children: torch.Tensor, object_ids: torch.Tensor, grid_min: list[float], grid_max: list[float], grid_res: list[int], block_size: list[int] = [], connectivity: int = 6) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, list[int], list[int]]:
     """
               Computes a 2-level Coarse-to-Fine (CF) Volumetric Flood Fill on GPU (< 10 MB VRAM at 1024^3).
@@ -1456,8 +1567,7 @@ def compute_superquadric_mesh_func(scales: torch.Tensor, exponents: torch.Tensor
     
               Each primitive is meshed analytically from Barr's parametric form on an
               `(resolution, resolution)` grid of angles spaced by approximately equal arc length,
-              then rotated and translated into world space. The per-primitive meshes are packed
-              into one vertex and triangle array by offsetting indices.
+              placed into world space, then packed into one vertex and triangle array.
     
               Args:
                   scales (torch.Tensor): (K, 3) float32 semi-axes on CUDA, strictly positive.
@@ -1478,16 +1588,8 @@ def compute_superquadric_mesh_func(scales: torch.Tensor, exponents: torch.Tensor
                         when `return_labels` is False.
     
               Note:
-                  The result is a concatenation, not a union: it holds one closed surface per
-                  primitive, and wherever two primitives overlap their triangles pass through one
-                  another with no shared vertices. Each individual primitive is watertight with
-                  Euler characteristic 2.
-    
-              Note:
-                  The surface is evaluated in float64 and narrowed on write. Near the poles a
-                  float32 angle perturbs the cosine by an order of magnitude, and the fractional
-                  power turns that into a visible displacement on exactly the sharp corners this
-                  tessellation exists to capture.
+                  The result is a concatenation, not a union: one closed surface per primitive,
+                  self-intersecting wherever two overlap. Each primitive alone is watertight.
     
               Example:
                   >>> from conquer3d._C import compute_superquadric_mesh_func
@@ -1903,12 +2005,10 @@ def one_sided_chamfer_distance(query_points: torch.Tensor, reference_points: tor
                       - indices (torch.Tensor): (N,) int64 index of the closest reference point for each query point.
     
               Note:
-                  This is the raw kernel entry point and reports empty inputs with sentinels rather
-                  than raising. An empty query cloud yields two empty tensors; an empty reference
-                  cloud yields distances of +inf and indices of -1, since no nearest neighbour
-                  exists. Those +inf values turn into NaN through any mean or backward pass, so
-                  prefer :func:`conquer3d.ops.one_sided_chamfer_distance`, which rejects an empty
-                  reference cloud outright.
+                  This is the raw kernel entry point: it signals empty inputs rather than raising.
+                  An empty query cloud yields empty tensors; an empty reference cloud yields +inf
+                  distances and -1 indices, which become NaN through any mean or backward pass.
+                  Prefer :func:`conquer3d.ops.one_sided_chamfer_distance`, which rejects it.
     
               Example:
                   >>> import torch

{conquer3d-0.8.2 → conquer3d-0.8.4}/conquer3d/conversion/tmesh.py

@@ -45,6 +45,8 @@ def tmesh2voxel(
             - 3: Volumetric 3D flood fill mask (dense).
             - 4: Hybrid WN + pseudonormals.
             - 5: Coarse-to-Fine (CF) Hierarchical Volumetric Flood Fill (< 10 MB VRAM).
+            - 6: Band flood fill that seals holes narrower than the dilation (memory like 5).
+              The mesh must lie at least 4 grid spacings inside `grid_min`/`grid_max`.
         return_occ (bool, optional): If True, additionally returns binary occupancy defined as
             `sdfs < 0`. Points exactly on the surface classify as outside, and occupancy is exactly
             as reliable as the sign produced by `sign_mode`. Defaults to False.
@@ -76,6 +78,8 @@ def tmesh2voxel(
         tm.build_flood_fill_data(grid_min, grid_max, res_list)
     elif sign_mode == 5:
         tm.build_flood_fill_cf_data(grid_min, grid_max, res_list)
+    elif sign_mode == 6:
+        tm.build_flood_fill_band_data(grid_min, grid_max, res_list)
     if sign_mode in [2, 4]:
         tm.compute_triangle_normals()
         tm.compute_vertex_normals(1)
@@ -143,6 +147,8 @@ def tmesh2sparse(
             - 3: Volumetric flood fill (dense).
             - 4: Hybrid WN + pseudonormals.
             - 5: Coarse-to-Fine (CF) Hierarchical Volumetric Flood Fill (< 10 MB VRAM).
+            - 6: Band flood fill that seals holes narrower than the dilation (memory like 5).
+              The mesh must lie at least 4 grid spacings inside `grid_min`/`grid_max`.
         pad (int, optional): Voxel layer dilation radius. Defaults to 0 (set `pad=1` for DMC / DC).
         return_normals (bool, optional): If True, returns surface normal vectors. Defaults to False.
         normal_mode (int, optional): Normal mode (0: face normals, 1: vertex normals, 2: displacement vector).
@@ -211,6 +217,8 @@ def tmesh2sparse(
         tm.build_flood_fill_data(grid_min, grid_max, res_list)
     elif sign_mode == 5:
         tm.build_flood_fill_cf_data(grid_min, grid_max, res_list)
+    elif sign_mode == 6:
+        tm.build_flood_fill_band_data(grid_min, grid_max, res_list)
     if sign_mode in [2, 4]:
         tm.compute_triangle_normals()
         tm.compute_vertex_normals(1)
@@ -269,7 +277,8 @@ def tmesh2voxelcloud(
         chunk_size (int, optional): Chunk size for batch SDF querying. Defaults to 5,000,000.
         device (str, optional): Computation device. Defaults to `'cuda'`.
         show_progress (bool, optional): Whether to display a progress bar. Defaults to True.
-        sign_mode (int, optional): Sign evaluation mode (0: Ray casting, 1: FWN, 2: Pseudonormals, 5: CF Flood Fill).
+        sign_mode (int, optional): Sign evaluation mode (0: Ray casting, 1: FWN, 2: Pseudonormals, 5: CF Flood Fill,
+            6: Band Flood Fill).
         return_normals (bool, optional): If True, returns surface normal vectors. Defaults to False.
         normal_mode (int, optional): Normal mode (0: face normals, 1: vertex normals, 2: displacement vector).
         return_occ (bool, optional): If True, additionally returns binary occupancy defined as

{conquer3d-0.8.2 → conquer3d-0.8.4}/conquer3d/csrc/binds/data_structure/mesh_bvh.cpp

@@ -113,10 +113,11 @@ MeshBVH::query_point(const torch::Tensor &query_points, const torch::Tensor &ver
                      std::optional<std::vector<int64_t>> cf_block_size,
                      std::optional<std::vector<int64_t>> cf_coarse_res, bool return_occ)
 {
-    if (sign_mode != 0 && sign_mode != 1 && sign_mode != 2 && sign_mode != 3 && sign_mode != 4 && sign_mode != 5)
+    if (sign_mode < 0 || sign_mode > 6)
     {
         throw std::runtime_error("sign_mode must be 0 (ray casting), 1 (fast winding number), 2 (pseudonormals), 3 "
-                                 "(flood fill), 4 (hybrid WN + pseudonormal), or 5 (coarse-to-fine flood fill)");
+                                 "(flood fill), 4 (hybrid WN + pseudonormal), 5 (coarse-to-fine flood fill), or 6 "
+                                 "(band flood fill)");
     }
 
     if ((sign_mode == 1 || sign_mode == 4) && !this->has_winding_data)
@@ -214,13 +215,16 @@ MeshBVH::query_point(const torch::Tensor &query_points, const torch::Tensor &ver
                                 (ry > 1) ? (flood_grid_max->at(1) - flood_grid_min->at(1)) / (ry - 1) : 1.0f,
                                 (rz > 1) ? (flood_grid_max->at(2) - flood_grid_min->at(2)) / (rz - 1) : 1.0f);
     }
-    else if (sign_mode == 5)
+    else if (sign_mode == 5 || sign_mode == 6)
     {
         if (!cf_coarse_mask.has_value() || !cf_coarse_mask->defined() || !flood_grid_min.has_value() ||
             !flood_grid_max.has_value() || !flood_grid_res.has_value())
         {
-            throw std::runtime_error("For sign_mode == 5 (coarse-to-fine flood fill), CF flood fill data must be "
-                                     "provided or built beforehand.");
+            throw std::runtime_error(sign_mode == 5
+                                         ? "For sign_mode == 5 (coarse-to-fine flood fill), CF flood fill data must be "
+                                           "provided or built beforehand."
+                                         : "For sign_mode == 6 (band flood fill), band flood fill data must be "
+                                           "provided or built beforehand.");
         }
         p_cf_coarse_mask = cf_coarse_mask->data_ptr<int8_t>();
         if (cf_boundary_lookup.has_value() && cf_boundary_lookup->defined())
@@ -235,6 +239,8 @@ MeshBVH::query_point(const torch::Tensor &query_points, const torch::Tensor &ver
         int64_t rx = flood_grid_res->at(0);
         int64_t ry = flood_grid_res->at(1);
         int64_t rz = flood_grid_res->at(2);
+        // The shared lookup range-checks against the fine grid, so modes 5 and 6 need its dims too.
+        f_dims = make_int3(static_cast<int>(rx), static_cast<int>(ry), static_cast<int>(rz));
         f_spacing = make_float3((rx > 1) ? (flood_grid_max->at(0) - flood_grid_min->at(0)) / (rx - 1) : 1.0f,
                                 (ry > 1) ? (flood_grid_max->at(1) - flood_grid_min->at(1)) / (ry - 1) : 1.0f,
                                 (rz > 1) ? (flood_grid_max->at(2) - flood_grid_min->at(2)) / (rz - 1) : 1.0f);
@@ -502,7 +508,7 @@ void bind_ds_mesh_bvh(py::module_ &m)
                  triangles (torch.Tensor): (M, 3) int32 mesh triangles on CUDA.
                  return_sdf (bool, optional): Return signed distance instead of unsigned. Defaults to False.
                  return_prj_pts (bool, optional): Return closest surface projections. Defaults to True.
-                 sign_mode (int, optional): Sign evaluation method (0: ray parity, 1: Fast Winding Number, 2: angle-weighted pseudonormals, 3: flood-fill mask, 4: hybrid, 5: coarse-to-fine flood fill). Defaults to 0.
+                 sign_mode (int, optional): Sign evaluation method (0: ray parity, 1: Fast Winding Number, 2: angle-weighted pseudonormals, 3: flood-fill mask, 4: hybrid, 5: coarse-to-fine flood fill, 6: band flood fill that seals small holes). Defaults to 0.
                  return_occ (bool, optional): If True, additionally returns binary occupancy defined as
                      `distances < 0`. Only active when `return_sdf=True`; with an unsigned distance the
                      occupancy slot is returned as None, since unsigned distances carry no inside/outside