{"id":26488072,"url":"https://github.com/sarahweiii/diso","last_synced_at":"2025-03-20T06:57:20.685Z","repository":{"id":209734856,"uuid":"715343671","full_name":"SarahWeiii/diso","owner":"SarahWeiii","description":"Differentiable Iso-Surface Extraction Package (DISO)","archived":false,"fork":false,"pushed_at":"2024-05-21T21:26:24.000Z","size":435,"stargazers_count":128,"open_issues_count":0,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-21T22:30:03.002Z","etag":null,"topics":["differentiable","dual-marching-cubes","iso-surface","iso-surface-extraction","marching-cubes"],"latest_commit_sha":null,"homepage":"","language":"Cuda","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SarahWeiii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-07T00:28:40.000Z","updated_at":"2024-05-21T21:26:27.000Z","dependencies_parsed_at":"2023-12-27T05:22:18.327Z","dependency_job_id":"76f89d0c-f5c6-47e3-9daa-59489a3ce275","html_url":"https://github.com/SarahWeiii/diso","commit_stats":null,"previous_names":["sarahweiii/diso"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SarahWeiii%2Fdiso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SarahWeiii%2Fdiso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SarahWeiii%2Fdiso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SarahWeiii%2Fdiso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SarahWeiii","download_url":"https://codeload.github.com/SarahWeiii/diso/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244566889,"owners_count":20473451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["differentiable","dual-marching-cubes","iso-surface","iso-surface-extraction","marching-cubes"],"created_at":"2025-03-20T06:57:20.194Z","updated_at":"2025-03-20T06:57:20.678Z","avatar_url":"https://github.com/SarahWeiii.png","language":"Cuda","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Differentiable Iso-Surface Extraction Package (DISO)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/diso)\n\n[***News***] DISO now supports batch training and checkpointing! It is no longer necessary to allocate multiple iso-surface extractors.\n\nThis repository consists of a variety of differentiable iso-surface extraction algorithms implemented in `cuda`.\n\nCurrently, two algorithms are incorporated:\n* Differentiable **Marching Cubes** [1] (DiffMC)\n* Differentiable **Dual Marching Cubes** [2] (DiffDMC)\n\nThe differentiable iso-surface algorithms have multiple applications in gradient-based optimization, such as shape, texture, materials reconstruction from images.\n\n# Installation\nRequirements: torch (must be compatible with CUDA version), trimesh\n```\npip install diso\n```\n\n# Quick Start\nYou can effortlessly try the following command, which converts a sphere SDF into triangle mesh using different algorithms. The generated results are saved in `out/`.\n```\npython test/example.py\n```\n\nNote:\n* `DiffMC` and `DiffDMC` generate watertight manifold meshes when grid deformation is disabled. When enabling grid deformation, self-intersection may occur, but the face connectivity remains manifold.\n* `DiffDMC` can produce a more uniform triangle distribution and smoother surfaces than `DiffMC` and supports generating quad meshes (in the example, the quad is automatically divided into two triangles by `trimesh`).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/example.png\" alt=\"four_examples\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n# Usage\nAll the functions share the same interfaces. Firstly you should build an iso-surface extractor as follows:\n```\nfrom diso import DiffMC\nfrom diso import DiffDMC\n\ndiffmc = DiffMC(dtype=torch.float32).cuda() # or dtype=torch.float64\ndiffdmc = DiffDMC(dtype=torch.float32).cuda() # or dtype=torch.float64\n```\nThen use its `forward` function to generate a single mesh:\n```\nverts, faces = diffmc(sdf, deform, normalize=True)  # or deform=None\nverts, faces = diffdmc(sdf, deform, return_quads=False, normalize=True)  # or deform=None\n```\n\nInput\n* `sdf`: queries SDF values on the grid vertices (see the `test/example.py` for how to create the grid). The gradient will be back-propagated to the source that generates the SDF values. (**[N, N, N, 3]**)\n* `deform (optional)`: (learnable) deformation values on the grid vertices, the range must be [-0.5, 0.5], default=None.  (**[N, N, N, 3]**)\n* `normalize`: whether to normalize the output vertices, default=True. If set to **True**, the vertices are normalized to [0, 1]. When **False**, the vertices remain unnormalized as [0, dim-1], \n* `return_quads`: whether return quad meshes; only applicable for DiffDMC, default=False. If set to **True**, the function returns quad meshes (**[F, 4]**).\n\nOutput\n* `verts`: mesh vertices within the range of [0, 1] or [0, dim-1]. (**[V, 3]**)\n* `faces`: mesh face indices (starting from 0). (**[F, 3]**).\n\nThe gradient will be automatically computed when `backward` function is called.\n\n# Batch Training\nYou can loop over the batch size to conduct an iso-surface extraction on each object, then compute the loss for the backward pass.\n```\nextractor = DiffMC(dtype=torch.float32).cuda()  # or DiffDMC\nfor bs in range(batchsize):\n    verts, faces = extractor(sdf, deform)\n    # compute and accumulate losses\nloss.backward()\n```\nNote: It is suggested to create the extractors outside the `epoch` loop so that they can be reused by different iterations and avoid allocating memory every time.\n\n# Speed Comparison\nWe compare our library with DMTet [3] and FlexiCubes [4] on two examples: a simple round cube and a random initialized signed distance function.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"imgs/speed.png\" alt=\"speed_example\" width=\"400\" /\u003e\n\u003c/p\u003e\n\nThe algorithms have been rigorously tested on an NVIDIA RTX 4090 GPU. Each algorithm underwent 100 repeated runs, and the table presents the time and CUDA memory consumption for **a single run**.\n\n| Round Cube | DMTet | FlexiCubes | DiffMC | DiffDMC |\n| --- | --- | --- | --- | --- |\n| \\# Vertices | 19622 | 19424 | 19944 | 19946 |\n| \\# Faces | 39240 | 38844 | 39884 | 39888 |\n| VRAM / G | 1.57 | 5.40 | 0.60 | 0.60 |\n| Time / ms | 9.61 | 10.00 | 1.54 | 1.44 |\n\n\n| Rand Init. | DMTet | FlexiCubes | DiffMC | DiffDMC |\n| --- | --- | --- | --- | --- |\n| \\# Vertices | 2597474 | 2785274 | 2651046 | 2713134 |\n| \\# Faces | 4774241 | 4364842 | 4717384 | 4431380 |\n| VRAM / G | 3.07 | 4.07 | 0.59 | 0.45 |\n| Time / ms | 49.10 | 65.35 | 2.55 | 2.78 |\n\n\n# Citation\nIf you find this repository useful, please cite the following paper:\n```\n@article{wei2023neumanifold,\n  title={NeuManifold: Neural Watertight Manifold Reconstruction with Efficient and High-Quality Rendering Support},\n  author={Wei, Xinyue and Xiang, Fanbo and Bi, Sai and Chen, Anpei and Sunkavalli, Kalyan and Xu, Zexiang and Su, Hao},\n  journal={arXiv preprint arXiv:2305.17134},\n  year={2023}\n}\n```\n\n# Reference\n[1] We L S. Marching cubes: A high resolution 3d surface construction algorithm[J]. Comput Graph, 1987, 21: 163-169.\n\n[2] Nielson G M. Dual marching cubes[C]//IEEE visualization 2004. IEEE, 2004: 489-496.\n\n[3] Shen T, Gao J, Yin K, et al. Deep marching tetrahedra: a hybrid representation for high-resolution 3d shape synthesis[J]. Advances in Neural Information Processing Systems, 2021, 34: 6087-6101.\n\n[4] Shen T, Munkberg J, Hasselgren J, et al. Flexible isosurface extraction for gradient-based mesh optimization[J]. ACM Transactions on Graphics (TOG), 2023, 42(4): 1-16.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarahweiii%2Fdiso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsarahweiii%2Fdiso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarahweiii%2Fdiso/lists"}