docs: fix marching_cubes return type (unique vertex indices, not normals)

[mvanhorn]

Summary

marching_cubes returns three values: vertices, faces, and an int64 tensor of unique vertex indices (the output of torch.unique_dim at MarchingCubes.cu:357-385). The docstrings in fvdb/grid.py, fvdb/grid_batch.py, and fvdb/functional/_meshing.py described the third return as "vertex normals", which the implementation does not produce.

Why this matters

The docs led users to expect a normals tensor and write code like vertices, faces, normals = .... The third value is actually unqVertIdx from the unique-vertex pass, which has a completely different shape (int64) and meaning.

Changes

• fvdb/grid.py, fvdb/grid_batch.py, fvdb/functional/_meshing.py - update the docstring of marching_cubes at all four call sites to describe the third return as "unique vertex indices (int64)".

Fixes #422

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: mvanhorn / name: Matt Van Horn (07a159e)

[mvanhorn]

The two red CUDA 13.0 jobs look unrelated to this docs-only change. Both fail at import time with ImportError: /...fvdb/libfvdb.so: undefined symbol: _ZNK2at10TensorBase14const_data_ptrIaEEPKT_v (demangled: at::TensorBase::const_data_ptr<signed char>()), which is a PyTorch ATen ABI mismatch between the pip CUDA 13.0 build's libtorch and the one installed at test time. The same tests pass on Conda and pip CUDA 12.8.

No code change should be needed here. Happy to leave it open for a re-run once the CUDA 13.0 build pipeline is reconciled with the test environment.

[swahtz]

Thanks for your contribution @mvanhorn and fixing up this issue. The tests should pass now if you want to just merge main into your PR branch.

While the docstring for unique_vertex_ids is technically accurate, it just defines the output using the variable name and is not really helpful for the user to understand what the meanings are of those vertex IDs.

As I look at what unique_vertex_ids actually is, I think we should expand the scope of this Issue to improve what is being returned here. The shape of this output for the single function is (N, 3) and for the batch function it is (B,-1,3) and the meaning of the rows per vertex is something like[batch_idx, voxel_a, voxel_b] which identifies the grid edge on which the vertex was interpolated, where voxel_a and voxel_b are flat voxel indices of the two endpoint voxels. batch_idx is entirely repetitive information because the batch is encoded by the JaggedTensor implicitly in the batch function and has no meaning (or is 0) in the single function. We could just change this output to be shape (N,2).

So if you want to keep this PR scoped as-is, I think we should change the name of this return value to something like vertex_edge_keys (the uniqueness was just an internal implementation detail) and change our documentation something like (update shape for the batch version as appropriate):

"Edge keys used to deduplicate mesh vertices, dtype torch.int64, shape (N, 3). Each row [batch_idx, voxel_a, voxel_b] identifies the grid edge on which the vertex was interpolated, where voxel_a and voxel_b are flat voxel indices of the two endpoint voxels (voxel_a >= voxel_b). This can be used to map mesh vertices back to the grid edges and voxels they originated from."

If you want to just open an Issue for the return shape difference and just land this docstring change, that's fine, or happy if we want to do both in this one PR since they're both small changes.

[mvanhorn]

The failing CUDA Doc Tests and Unit Tests look unrelated to this PR - the change is a 9-line docstring fix for marching_cubes return-type wording, no source or test files touched. Static analysis (Python parsing, whitespace lint) passed; couldn't run sphinx-build locally without the CUDA env. Could a maintainer re-run CI when the queue allows? Happy to dig in if a re-run still fails.

[swahtz]

The failing CUDA Doc Tests and Unit Tests look unrelated to this PR - the change is a 9-line docstring fix for marching_cubes return-type wording, no source or test files touched. Static analysis (Python parsing, whitespace lint) passed; couldn't run sphinx-build locally without the CUDA env. Could a maintainer re-run CI when the queue allows? Happy to dig in if a re-run still fails.

The issue with CI is related to your branch not having merged the latest from main, if you do that then the tests should pass. The review notes also need to be addressed.