Skip to content

Parallelize marching cubes: 5-pass core with num_threads - #54

Open
Harold2017 wants to merge 1 commit into
pmneila:masterfrom
Harold2017:master
Open

Harold2017 wants to merge 1 commit into
pmneila:masterfrom
Harold2017:master

Conversation

@Harold2017

Copy link
Copy Markdown

Summary

The marching-cubes core is now a count-then-fill pipeline: one ordered sweep becomes
five passes that each run on the requested number of threads.

 marching_cubes(volume, isovalue, num_threads=4)
-  for i, j, k                            # single ordered sweep
-    evaluate 4 corners -> cube index
-    create a vertex on first sight of an edge (shared_indices_*)
-    push_back triangles immediately
+  pass 1  classify cubes, count owned vertices        (parallel)
+  pass 2  prefix sum counts -> vertex offsets         (parallel scan)
+  pass 3  write every vertex position                 (parallel)
+  pass 4  prefix sum counts -> polygon offsets        (parallel scan)
+  pass 5  emit polygons through the owner table       (parallel)

Parallelism follows from one ownership rule: a cube owns the three edges at its
minimum corner (edge 0, 3, 8), and one extra layer of "ghost" cubes past each upper
boundary owns the edges lying on that boundary. Every edge in the volume therefore
belongs to exactly one cube, so no pass needs a shared-index buffer, a fix-up, or a
boundary special case.

mcubes/src/marchingcubes.h   thread pool, parallel prefix sum, the five passes
mcubes/src/pywrapper.cpp     num_threads, GIL release, dtype dispatch, node sampling
mcubes/src/_mcubes.pyx       marching_cubes(volume, isovalue, num_threads=0)
PARALLEL.md                  algorithm, implementation notes, benchmarks
setup.py                     -pthread on POSIX (needed to link std::thread)

Evidence

Before: pytest -q → 20 passed. marching_cubes(sphere 256³) → 310 ms.
After: pytest -q → 27 passed, flake8 . clean. marching_cubes(sphere 256³, num_threads=4) → 80 ms.

The new core does not change the mesh it produces:

  • 200 random volumes vs. the previous implementation -> 200/200 identical triangles (order-independent)
  • 16 dtype/layout cases (bool, all int widths, float32/64, Fortran order, strided, negative strides) -> identical; max vertex deviation 0 for bool/integer, 3.6e-15 for float
  • same call at 1, 2, 4, 8 and auto threads -> byte-identical vertex and triangle arrays

One thread is already faster than the old sweep everywhere (1.6–2.2×); the func
gain comes from one evaluation per node, not from threading, since the callbacks
hold the GIL.

Detailed performance comparison can be found in PARALLEL.md

Merge Danger

Door: two-way — a single commit, no data or state migration; git revert 63294d5
restores the previous core.

Blast Radius: consumers — the geometry is unchanged but three observable
behaviours are not:

  • Vertex and triangle order differ from before (same triangles, same winding);
    anything that assumed the old index order will see a diff.
  • C++ header contract: mc::marching_cubes now takes value_at(i, j, k) with
    node indices, not coordinates, may call it from several threads, and
    edge_table/triangle_table/num_indices_table are now const. A hand-written
    callable keeps compiling but returns the wrong field. The Python API is unaffected.
  • Memory: 9 bytes per extended cube of scratch (~153 MB at 256³) on top of the
    mesh, allocated regardless of the thread count.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant