Add real metric mode and bump version to 1.0.9

Add `-rm`/`--real-metric` flag that lets users specify the concavity
threshold in meters (real-world scale) instead of normalized units.
The algorithm automatically converts it to the internal normalized
threshold based on the mesh bounding box extent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SarahWeiii

README.md

@@ -4,6 +4,8 @@
  [![Build](https://github.com/SarahWeiii/CoACD/actions/workflows/build.yml/badge.svg)](https://github.com/SarahWeiii/CoACD/actions/workflows/build.yml)
  ![PyPI - Downloads](https://img.shields.io/pypi/dm/coacd)
 
+[***News***] CoACD now supports real metric mode (`-rm`), ideal for meshes in real-world scale (e.g., from 3D scans or CAD models in meters). Specify the concavity threshold directly in meters instead of normalized units!
+
 [***News***] Check our new library, [PaMO](https://github.com/SarahWeiii/pamo.git), which converts any mesh into a low-poly, manifold, intersection-free mesh in seconds (CUDA required). It’s perfect as a preprocessing tool for CoACD.
 
 [***News***] CoACD (both Python and C++) is supported on Linux (x86_64), Windows (amd64) and MacOS (x86_64 & apple sillicon) now!
@@ -31,6 +33,9 @@ import coacd
 mesh = trimesh.load(input_file, force="mesh")
 mesh = coacd.Mesh(mesh.vertices, mesh.faces)
 parts = coacd.run_coacd(mesh) # a list of convex hulls.
+
+# Or use real metric mode (threshold in meters)
+parts = coacd.run_coacd(mesh, threshold=0.01, real_metric=True)
 ```
 The complete example script is in `python/package/bin/coacd`, run it by the following command:
 ```
@@ -155,6 +160,7 @@ Here is the description of the parameters (sorted by importance).
 * `-dt/--max-ch-vertex`: max vertex value for each convex hull, **only when decimate is enabled**, default = 256.
 * `-ex/--extrude`: extrude neighboring convex hulls along the overlapping faces (other faces unchanged), default = false.
 * `-em/--extrude-margin`: extrude margin, **only when extrude is enabled**, default = 0.01.
+* `-rm/--real-metric`: flag to enable real metric mode, where the threshold is interpreted as an error in meters (the input mesh should be in meter scale). The algorithm automatically converts it to the normalized threshold used internally. Default = false.
 * `-am/--approximate-mode`: approximation shape type ("ch" for convex hulls, "box" for cubes), default = "ch". I would recommend using a 2x threshold than it in convex for box approximation.
 * `--seed`: random seed used for sampling, default = random().
 

main.cpp

@@ -110,6 +110,10 @@ int main(int argc, char *argv[])
       {
         sscanf(argv[i + 1], "%le", &params.dmc_thres);
       }
+      if (strcmp(argv[i], "-rm") == 0 || strcmp(argv[i], "--real-metric") == 0)
+      {
+        params.real_metric = true;
+      }
     }
   }
 
@@ -142,17 +146,35 @@ int main(int argc, char *argv[])
     exit(0);
   }
 
-  if (params.threshold > 1)
-    logger::warn("Threshold t exceeds the higher bound and is automatically set as 1!");
-  params.threshold = min(params.threshold, 1.0);
+  if (!params.real_metric)
+  {
+    if (params.threshold > 1)
+      logger::warn("Threshold t exceeds the higher bound and is automatically set as 1!");
+    params.threshold = min(params.threshold, 1.0);
+  }
 
   Model m;
   array<array<double, 3>, 3> rot;
 
-  SaveConfig(params);
-
   m.LoadOBJ(params.input_model);
   vector<double> bbox = m.Normalize();
+
+  double real_metric_len = 0;
+  double real_metric_original_threshold = params.threshold;
+  if (params.real_metric)
+  {
+    real_metric_len = max(max(bbox[1] - bbox[0], bbox[3] - bbox[2]), bbox[5] - bbox[4]);
+    params.threshold = params.threshold * 2.0 / real_metric_len * 0.8;
+  }
+
+  SaveConfig(params);
+
+  if (params.real_metric)
+  {
+    logger::info("Real metric mode: mesh max length = {:.2f} cm", real_metric_len * 100.0);
+    logger::info("Real metric mode: error threshold = {:.2f} cm", real_metric_original_threshold * 100.0);
+    logger::info("Real metric mode: threshold {:.4f} cm (real) -> {:.4f} (normalized)", real_metric_original_threshold * 100.0, params.threshold);
+  }
   // m.SaveOBJ("normalized.obj");
 
   #if WITH_3RD_PARTY_LIBS

public/coacd.cpp

@@ -18,7 +18,8 @@ std::vector<Mesh> CoACD(Mesh const &input, double threshold,
                         int mcts_nodes, int mcts_iteration, int mcts_max_depth,
                         bool pca, bool merge, bool decimate, int max_ch_vertex,
                         bool extrude, double extrude_margin,
-                        std::string apx_mode, unsigned int seed) {
+                        std::string apx_mode, unsigned int seed,
+                        bool real_metric) {
 
   logger::info("threshold               {}", threshold);
   logger::info("max # convex hull       {}", max_convex_hull);
@@ -36,7 +37,7 @@ std::vector<Mesh> CoACD(Mesh const &input, double threshold,
   logger::info("approximate mode        {}", apx_mode);
   logger::info("seed                    {}", seed);
 
-  if (threshold > 1) {
+  if (!real_metric && threshold > 1) {
     throw std::runtime_error("CoACD threshold > 1 (should be 0-1).");
   }
 
@@ -67,10 +68,22 @@ std::vector<Mesh> CoACD(Mesh const &input, double threshold,
   params.extrude_margin = extrude_margin;
   params.apx_mode = apx_mode;
   params.seed = seed;
+  params.real_metric = real_metric;
 
   Model m;
   m.Load(input.vertices, input.indices);
   vector<double> bbox = m.Normalize();
+
+  if (real_metric) {
+    double m_len = max(max(bbox[1] - bbox[0], bbox[3] - bbox[2]), bbox[5] - bbox[4]);
+    double original_threshold = params.threshold;
+    params.threshold = params.threshold * 2.0 / m_len * 0.8;
+    logger::info("Real metric mode: mesh max length = {:.2f} cm", m_len * 100.0);
+    logger::info("Real metric mode: error threshold = {:.2f} cm", original_threshold * 100.0);
+    logger::info("Real metric mode: threshold {:.4f} cm (real) -> {:.4f} (normalized)", original_threshold * 100.0, params.threshold);
+  }
+
+
   array<array<double, 3>, 3> rot{
       {{1.0, 0.0, 0.0}, {0.0, 1.0, 0.0}, {0.0, 0.0, 1.0}}};
 
@@ -139,7 +152,8 @@ CoACD_MeshArray CoACD_run(CoACD_Mesh const &input, double threshold,
                           int mcts_max_depth, bool pca, bool merge,
                           bool decimate, int max_ch_vertex,
                           bool extrude, double extrude_margin,
-                          int apx_mode, unsigned int seed) {
+                          int apx_mode, unsigned int seed,
+                          bool real_metric) {
   coacd::Mesh mesh;
   for (uint64_t i = 0; i < input.vertices_count; ++i) {
     mesh.vertices.push_back({input.vertices_ptr[3 * i],
@@ -171,8 +185,8 @@ CoACD_MeshArray CoACD_run(CoACD_Mesh const &input, double threshold,
 
   auto meshes = coacd::CoACD(mesh, threshold, max_convex_hull, pm,
                              prep_resolution, sample_resolution, mcts_nodes,
-                             mcts_iteration, mcts_max_depth, pca, merge, decimate, max_ch_vertex, 
-                             extrude, extrude_margin, apx, seed);
+                             mcts_iteration, mcts_max_depth, pca, merge, decimate, max_ch_vertex,
+                             extrude, extrude_margin, apx, seed, real_metric);
 
   CoACD_MeshArray arr;
   arr.meshes_ptr = new CoACD_Mesh[meshes.size()];

public/coacd.h

@@ -25,7 +25,8 @@ std::vector<Mesh> CoACD(Mesh const &input, double threshold = 0.05,
                         int mcts_max_depth = 3, bool pca = false,
                         bool merge = true, bool decimate = false, int max_ch_vertex = 256,
                         bool extrude = false, double extrude_margin = 0.01,
-                        std::string apx_mode = "ch", unsigned int seed = 0);
+                        std::string apx_mode = "ch", unsigned int seed = 0,
+                        bool real_metric = false);
 void set_log_level(std::string_view level);
 
 } // namespace coacd
@@ -60,7 +61,8 @@ CoACD_MeshArray COACD_API CoACD_run(CoACD_Mesh const &input, double threshold,
                                     int mcts_max_depth, bool pca, bool merge,
                                     bool decimate, int max_ch_vertex,
                                     bool extrude, double extrude_margin,
-                                    int apx_mode, unsigned int seed);
+                                    int apx_mode, unsigned int seed,
+                                    bool real_metric);
 
 void COACD_API CoACD_setLogLevel(char const *level);
 }

python/package/__init__.py

@@ -61,6 +61,7 @@ class CoACD_MeshArray(ctypes.Structure):
     c_double,
     c_int,
     c_uint,
+    c_bool,
 ]
 _lib.CoACD_run.restype = CoACD_MeshArray
 
@@ -95,6 +96,7 @@ def run_coacd(
     extrude_margin: float = 0.01,
     apx_mode: str = "ch",
     seed: int = 0,
+    real_metric: bool = False,
 ):
     vertices = np.ascontiguousarray(mesh.vertices, dtype=np.double)
     indices = np.ascontiguousarray(mesh.indices, dtype=np.int32)
@@ -143,6 +145,7 @@ def run_coacd(
         extrude_margin,
         apx,
         seed,
+        real_metric,
     )
 
     meshes = []

setup.py

@@ -75,7 +75,7 @@ def build_extension(self, ext):
 
 setup(
     name="coacd",
-    version="1.0.8",
+    version="1.0.9",
     author_email="xiwei@ucsd.edu",
     keywords="collision convex decomposition",
     description="Approximate Convex Decomposition for 3D Meshes with Collision-Aware Concavity and Tree Search",

src/config.h

@@ -40,6 +40,7 @@ namespace coacd
     int max_ch_vertex;
     bool extrude;
     double extrude_margin;
+    bool real_metric;
 
     /////////////// MCTS Config ///////////////
     int mcts_iteration;
@@ -65,6 +66,7 @@ namespace coacd
       max_ch_vertex = 256;
       extrude = false;
       extrude_margin = 0.01;
+      real_metric = false;
 
       mcts_iteration = 150;
       mcts_max_depth = 3;

src/io.cpp

@@ -25,6 +25,7 @@ namespace coacd
         logger::info("\tk for Rv:                                  {}", params.rv_k);
         logger::info("\tHausdorff Sampling Resolution:             {}", params.resolution);
         logger::info("\tApproximation Mode (ch/box):               {}", params.apx_mode);
+        logger::info("\tReal Metric Mode (ON/OFF):                  {}", params.real_metric);
         logger::info("\tRandom Seed:                               {}", params.seed);
     }