fusemesh 0.2.0__tar.gz

fusemesh-0.2.0/.clang-format

@@ -0,0 +1,8 @@
+BasedOnStyle: Chromium
+ColumnLimit: 120
+IndentWidth: 4
+IndentPPDirectives: BeforeHash
+TabWidth: 4
+AccessModifierOffset: -2
+SortUsingDeclarations: false
+SortIncludes: false

fusemesh-0.2.0/.cmake-format.yaml

@@ -0,0 +1,4 @@
+format:
+  line_width: 100
+  tab_size: 2
+  dangle_parens: true

fusemesh-0.2.0/.format_all

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Like MoPhi's utility: clang-format + Black, with CMake and CI check support.
+set -euo pipefail
+repo_dir=$(cd "$(dirname "$0")" && pwd)
+exec "${PYTHON:-python3}" "$repo_dir/scripts/format_all.py" "$@"

fusemesh-0.2.0/.github/actionlint.yaml

@@ -0,0 +1,7 @@
+self-hosted-runner:
+  labels:
+    - fuse-gpu
+    - sm80
+    - sm86
+    - sm89
+    - sm90

fusemesh-0.2.0/.github/workflows/wheels.yml

@@ -0,0 +1,178 @@
+name: Wheels and release
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Registry (requires protected environment and Trusted Publisher)
+        type: choice
+        options: [none, testpypi, pypi]
+        default: none
+      gpu:
+        description: Optional GPU validation (requires a matching self-hosted runner)
+        type: choice
+        options: [none, sm89, sm80, sm86, sm90]
+        default: none
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: python -m pip install -r requirements/format.txt
+      - run: ./.format_all --check
+      - run: actionlint
+      - run: shellcheck .format_all scripts/*.sh
+
+  source:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: python -m pip install -r requirements/release.txt
+      - run: python -m build --sdist
+      - run: python scripts/check_artifacts.py dist --source-only
+      - run: python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  wheels:
+    needs: [source, format]
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [cp39, cp310, cp311, cp312, cp313, cp314]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - run: python -m pip install -r requirements/release.txt
+      # Every wheel is compiled from the self-contained sdist, without Git/submodules.
+      - run: python -m cibuildwheel dist/*.tar.gz --output-dir wheelhouse
+        env:
+          CIBW_BUILD: ${{ matrix.python }}-manylinux_x86_64
+      - run: python scripts/check_artifacts.py wheelhouse --python-tag ${{ matrix.python }}
+      - run: python -m twine check --strict wheelhouse/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.python }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  native:
+    needs: [source, format]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - name: Build standalone native tests from source archive
+        run: |
+          image=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["tool"]["cibuildwheel"]["linux"]["manylinux-x86_64-image"])')
+          mkdir -p build/native-tests
+          docker run --rm -v "$PWD:/project" -w /project "$image" bash -c 'bash scripts/ci_native_build.sh dist/*.tar.gz build/native-tests'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-tests
+          path: build/native-tests/*
+          if-no-files-found: error
+
+  gpu:
+    # Never execute pull-request code on a persistent GPU runner. Maintainers dispatch
+    # only main or version tags. Each runner needs Docker + NVIDIA Container Toolkit.
+    if: github.event_name == 'workflow_dispatch' && inputs.gpu != 'none' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    needs: [wheels, native]
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    runs-on: [self-hosted, linux, x64, fuse-gpu, '${{ inputs.gpu }}']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: wheelhouse
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: native-tests
+          path: build/native-tests
+      - run: chmod +x build/native-tests/fuse_*
+      - run: bash scripts/ci_gpu_test.sh '${{ matrix.python }}' '${{ inputs.gpu }}'
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: gpu-${{ inputs.gpu }}-py${{ matrix.python }}
+          path: build/gpu-evidence/*
+          if-no-files-found: error
+
+  publish:
+    # An intentionally skipped GPU job must not skip publication. A requested
+    # GPU run must pass; failed/cancelled build or validation jobs block uploads.
+    if: >-
+      always() && !cancelled() &&
+      github.event_name == 'workflow_dispatch' && inputs.publish != 'none' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')) &&
+      needs.format.result == 'success' && needs.source.result == 'success' &&
+      needs.wheels.result == 'success' && needs.native.result == 'success' &&
+      ((inputs.gpu == 'none' && needs.gpu.result == 'skipped') ||
+       (inputs.gpu != 'none' && needs.gpu.result == 'success'))
+    needs: [gpu, wheels, native, source, format]
+    runs-on: ubuntu-24.04
+    environment:
+      name: ${{ inputs.publish }}
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - name: Validate complete release and optional version tag
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            python scripts/check_artifacts.py dist --complete --tag "$GITHUB_REF_NAME"
+          else
+            python scripts/check_artifacts.py dist --complete
+          fi
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ inputs.publish == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}

fusemesh-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+*.i
+*.ii
+*.gpu
+*.ptx
+*.cubin
+*.fatbin
+
+.venv*/
+build/
+dist/
+__pycache__/
+.pytest_cache/
+*.egg-info/

fusemesh-0.2.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/openvdb"]
+	path = external/openvdb
+	url = https://github.com/AcademySoftwareFoundation/openvdb.git

fusemesh-0.2.0/CMakeLists.txt

@@ -0,0 +1,137 @@
+cmake_minimum_required(VERSION 3.24)
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" FUSE_VERSION)
+string(STRIP "${FUSE_VERSION}" FUSE_VERSION)
+if(NOT FUSE_VERSION MATCHES "^[0-9]+\\.[0-9]+\\.[0-9]+$")
+  message(FATAL_ERROR "VERSION must contain a release version MAJOR.MINOR.PATCH")
+endif()
+set_property(
+  DIRECTORY
+  APPEND
+  PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION"
+)
+project(
+  FUSE
+  VERSION ${FUSE_VERSION}
+  LANGUAGES CXX CUDA
+)
+
+option(FUSE_BUILD_PYTHON "Build the fusemesh Python extension" ON)
+option(FUSE_BUILD_TESTS "Build native validation tests" OFF)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CUDA_STANDARD 17)
+set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+# Explicit fat binary: Ampere, Ada, Hopper plus forward PTX. Never host-only.
+set(FUSE_CUDA_ARCHITECTURES
+    "80-real;86-real;89-real;90-real;90-virtual"
+    CACHE STRING "CUDA architectures"
+)
+set(CMAKE_CUDA_ARCHITECTURES "${FUSE_CUDA_ARCHITECTURES}")
+set(CMAKE_CUDA_RUNTIME_LIBRARY Static)
+find_package(CUDAToolkit 12.8 REQUIRED)
+if(NOT CUDAToolkit_VERSION VERSION_LESS 12.9)
+  message(FATAL_ERROR "FUSE currently supports the CUDA 12.8 toolkit family only")
+endif()
+
+set(FUSE_NANOVDB_REVISION "e26f5a569201d3236e0c30580572101022d3d754")
+set(NANOVDB_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/external/openvdb/nanovdb")
+if(NOT EXISTS "${NANOVDB_ROOT}/nanovdb/NanoVDB.h")
+  message(FATAL_ERROR "NanoVDB sources missing. Run git submodule update --init --recursive")
+endif()
+# Check a checkout when Git is available; self-contained sdists need no Git.
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/external/openvdb/.git")
+  find_package(Git QUIET)
+  if(Git_FOUND)
+    execute_process(
+      COMMAND "${GIT_EXECUTABLE}" rev-parse HEAD
+      WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/external/openvdb"
+      OUTPUT_VARIABLE revision
+      OUTPUT_STRIP_TRAILING_WHITESPACE COMMAND_ERROR_IS_FATAL ANY
+    )
+    if(NOT revision STREQUAL FUSE_NANOVDB_REVISION)
+      message(FATAL_ERROR "NanoVDB checkout differs from the pinned revision")
+    endif()
+  endif()
+endif()
+string(REPLACE ";" "," FUSE_ARCH_STRING "${FUSE_CUDA_ARCHITECTURES}")
+configure_file(cmake/build_config.h.in generated/fuse/build_config.h @ONLY)
+add_library(
+  fuse STATIC src/cuda/smoke.cu src/core/reconstruct.cpp src/core/version.cpp
+              src/geometry/scene.cpp src/volume/topology.cpp src/cuda/reconstruct.cu
+)
+add_library(FUSE::fuse ALIAS fuse)
+target_include_directories(
+  fuse
+  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include>
+  PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src" "${NANOVDB_ROOT}"
+          "${CMAKE_CURRENT_BINARY_DIR}/generated"
+)
+target_link_libraries(fuse PUBLIC CUDA::cudart_static)
+target_compile_options(fuse PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:--extended-lambda;--fmad=false>)
+set_target_properties(fuse PROPERTIES CUDA_RUNTIME_LIBRARY Static)
+
+if(FUSE_BUILD_PYTHON)
+  find_package(
+    Python 3.9
+    COMPONENTS Interpreter Development.Module
+    REQUIRED
+  )
+  execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    OUTPUT_VARIABLE nanobind_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE COMMAND_ERROR_IS_FATAL ANY
+  )
+  find_package(nanobind CONFIG REQUIRED)
+  nanobind_add_module(_native bindings/module.cpp)
+  target_link_libraries(_native PRIVATE FUSE::fuse)
+  install(TARGETS _native LIBRARY DESTINATION fusemesh)
+endif()
+if(NOT SKBUILD)
+  include(GNUInstallDirs)
+  include(CMakePackageConfigHelpers)
+  install(
+    TARGETS fuse
+    EXPORT FUSETARGETS
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  )
+  install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+  install(
+    EXPORT FUSETARGETS
+    NAMESPACE FUSE::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/FUSE
+  )
+  configure_package_config_file(
+    cmake/FUSEConfig.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/FUSEConfig.cmake"
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/FUSE
+  )
+  write_basic_package_version_file(
+    "${CMAKE_CURRENT_BINARY_DIR}/FUSEConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY ExactVersion
+  )
+  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/FUSEConfigVersion.cmake"
+                "${CMAKE_CURRENT_BINARY_DIR}/FUSEConfig.cmake"
+          DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/FUSE
+  )
+endif()
+if(FUSE_BUILD_TESTS)
+  enable_testing()
+  add_executable(fuse_version tests/native_version.cpp)
+  target_compile_definitions(fuse_version PRIVATE FUSE_EXPECTED_VERSION="${PROJECT_VERSION}")
+  target_link_libraries(fuse_version PRIVATE FUSE::fuse)
+  add_test(NAME fuse_version COMMAND fuse_version)
+  add_executable(fuse_smoke tests/native_smoke.cpp)
+  target_link_libraries(fuse_smoke PRIVATE FUSE::fuse)
+  add_test(NAME fuse_smoke COMMAND fuse_smoke)
+  add_executable(fuse_cells tests/native_cells.cpp)
+  target_include_directories(fuse_cells PRIVATE src include)
+  add_test(NAME fuse_cells COMMAND fuse_cells)
+  add_executable(fuse_reconstruct tests/native_reconstruct.cpp)
+  target_link_libraries(fuse_reconstruct PRIVATE FUSE::fuse)
+  add_test(NAME fuse_reconstruct COMMAND fuse_reconstruct)
+  add_executable(fuse_extraction tests/native_extraction.cpp)
+  target_include_directories(fuse_extraction PRIVATE src)
+  target_link_libraries(fuse_extraction PRIVATE FUSE::fuse)
+  add_test(NAME fuse_extraction COMMAND fuse_extraction)
+endif()

fusemesh-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ruochun Zhang
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fusemesh-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: fusemesh
+Version: 0.2.0
+Summary: Fast Union Surface Extraction — CUDA/NanoVDB backend
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+License-File: licenses/CUB-LICENSE.txt
+License-File: licenses/CUDA-12.8-EULA.txt
+License-File: licenses/LLVM-Apache-2.0-exception.txt
+License-File: licenses/NanoVDB-Apache-2.0.txt
+License-File: licenses/THIRD-PARTY-NOTICES.txt
+License-File: licenses/nanobind-LICENSE.txt
+License-File: licenses/robin-map-LICENSE.txt
+Requires-Python: >=3.9
+Requires-Dist: numpy<2.1,>=1.23; python_version < "3.10"
+Requires-Dist: numpy>=1.23; python_version >= "3.10"
+Requires-Dist: trimesh<5,>=4.12.2
+Requires-Dist: fast-simplification==0.1.12; python_version < "3.10"
+Requires-Dist: fast-simplification==0.2.0; python_version >= "3.10"
+Requires-Dist: rtree==1.4.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: manifold3d==3.5.4; extra == "test"
+Provides-Extra: quality
+Requires-Dist: manifold3d==3.5.4; extra == "quality"
+Description-Content-Type: text/markdown
+
+# FUSE — Fast Union Surface Extraction
+
+FUSE reconstructs a triangle mesh approximating the solid union of one or more
+closed meshes. It uses CUDA for field evaluation and surface extraction, sparse
+NanoVDB indexing to reduce work around empty space, and a Python API for loading,
+fusing, simplifying, comparing, and saving meshes.
+
+Choose a uniform voxel size in your mesh's units to control sampling resolution.
+FUSE handles overlapping solids, containment, disconnected components, and
+resolved cavities. Optional CPU simplification reduces the output triangle count.
+It is an approximate reconstruction tool: original triangles and subvoxel features
+are not necessarily preserved.
+
+## Install
+
+Use a Linux x86-64 wheel matching your CPython version (3.9–3.14). Download and
+extract the corresponding `wheel-cp…` artifact from a successful
+[GitHub Actions build](https://github.com/Ruochun/FUSE/actions/workflows/wheels.yml),
+then install the **single matching wheel**:
+
+```bash
+python -m pip install /path/to/fusemesh-<version>-<python>-<abi>-<platform>.whl
+python -c 'import fusemesh; print(fusemesh.build_info()); print(fusemesh.smoke_test())'
+```
+
+Replace the placeholder path with the downloaded filename. Reconstruction and
+`smoke_test()` require an NVIDIA GPU and driver. Wheel installations include the
+CUDA runtime and Python dependencies; a CUDA toolkit or compiler is not required.
+Loading, saving, simplification, and quality comparisons run on the CPU without
+initializing CUDA.
+
+See [installation and compatibility](docs/installation.md) for GPU requirements,
+source builds, and reinstalling a changed wheel with the same version number.
+
+## Fuse mesh files
+
+```python
+import fusemesh
+
+result = fusemesh.reconstruct(["a.off", "b.obj"], voxel_size=0.05)
+fusemesh.save_mesh("union.obj", result)
+print(result.metadata)
+```
+
+A single path also works: `fusemesh.reconstruct("model.off", voxel_size=0.05)`.
+For arrays, use `reconstruct([(vertices, faces)], voxel_size=0.05)`; each array
+pair represents one solid. Returned vertices are float64 `(N, 3)` coordinates
+and faces are uint64 `(M, 3)` indices.
+
+From a repository checkout, run the file example:
+
+```bash
+python examples/fuse_files.py a.off b.obj \
+  --voxel-size 0.05 --memory-mib 512 --output union.obj
+```
+
+To try generated geometry without supplying a file:
+
+```bash
+python examples/union_demo.py
+```
+
+## Reduce output triangles
+
+```python
+reduced = fusemesh.simplify(result, max_error=0.01, target_faces=5000)
+fusemesh.save_mesh("reduced.obj", reduced)
+```
+
+Simplification checks surface and sharp-edge deviation, per-shell volume, and
+manifold topology. `target_faces` is a soft goal; quality checks take priority.
+`max_error` is relative to the mesh being simplified, not the original union
+inputs. See [simplification](docs/simplification.md) for controls and limitations.
+
+## Measure surface accuracy
+
+```python
+report = fusemesh.compare_surfaces(
+    "original.off", "reconstructed.obj", tolerance=0.05,
+    degenerate_faces="drop",
+)
+print(report["symmetric"]["rms"])
+print(report["symmetric"]["f_score"])
+```
+
+This CPU comparison accepts open or nonmanifold surfaces. The explicit `drop`
+option excludes zero-area triangles and reports removal counts; the default is
+`error`. Distances use mesh coordinate units. Coverage and F-score depend on the
+chosen tolerance, and sampled maxima are not certified Hausdorff bounds.
+
+From a checkout, compare existing files with
+`python examples/quality_demo.py --inputs original.off reconstructed.obj`.
+Without `--inputs`, the demo reconstructs two boxes and requires a GPU and the
+`quality` extra. Multiple original solids also require that extra to construct
+an independent Boolean reference union. See [quality comparisons](docs/quality.md)
+for installation, metric definitions, and examples.
+
+## Reconstruction requirements and limits
+
+- Inputs must describe closed, consistently oriented manifold solids.
+  `validation="basic"` skips topology checks but does not make open or
+  nonmanifold solids supported. Self-intersections are not detected or repaired.
+- Trimesh loads local files. OFF faces must already be triangles; other formats
+  follow their reader's triangulation and grouping rules. See [mesh loading](docs/mesh-loading.md).
+- Smaller voxel sizes can resolve finer detail but require more work and memory.
+  Thin walls, narrow gaps, and small components may disappear. Voxel size is not
+  a guaranteed surface-error bound; output is not guaranteed manifold in
+  degenerate or unresolved cases.
+- The Python API defaults to a 512 MiB limit on explicit FUSE GPU buffers.
+  The file example defaults to 16 GiB; use `--memory-mib` to set it explicitly.
+  CUDA context memory and host memory are outside that limit.
+- Reconstruction does not perform exact triangle Booleans, mesh repair, adaptive voxel
+  refinement, automatic smoothing, or material/texture transfer.
+
+## Documentation
+
+Start with the [documentation index](docs/README.md), or go directly to:
+
+- [Installation and compatibility](docs/installation.md)
+- [Mesh loading and file examples](docs/mesh-loading.md)
+- [Python and native API](docs/api.md)
+- [Surface simplification](docs/simplification.md)
+- [Reconstruction quality](docs/quality.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Testing and benchmarks](docs/testing.md)
+
+FUSE uses BSD-3-Clause. Third-party notices are in [licenses](licenses/THIRD-PARTY-NOTICES.txt)
+and the installed wheel metadata.

fusemesh-0.2.0/README.md

@@ -0,0 +1,128 @@
+# FUSE — Fast Union Surface Extraction
+
+FUSE reconstructs a triangle mesh approximating the solid union of one or more
+closed meshes. It uses CUDA for field evaluation and surface extraction, sparse
+NanoVDB indexing to reduce work around empty space, and a Python API for loading,
+fusing, simplifying, comparing, and saving meshes.
+
+Choose a uniform voxel size in your mesh's units to control sampling resolution.
+FUSE handles overlapping solids, containment, disconnected components, and
+resolved cavities. Optional CPU simplification reduces the output triangle count.
+It is an approximate reconstruction tool: original triangles and subvoxel features
+are not necessarily preserved.
+
+## Install
+
+Use a Linux x86-64 wheel matching your CPython version (3.9–3.14). Download and
+extract the corresponding `wheel-cp…` artifact from a successful
+[GitHub Actions build](https://github.com/Ruochun/FUSE/actions/workflows/wheels.yml),
+then install the **single matching wheel**:
+
+```bash
+python -m pip install /path/to/fusemesh-<version>-<python>-<abi>-<platform>.whl
+python -c 'import fusemesh; print(fusemesh.build_info()); print(fusemesh.smoke_test())'
+```
+
+Replace the placeholder path with the downloaded filename. Reconstruction and
+`smoke_test()` require an NVIDIA GPU and driver. Wheel installations include the
+CUDA runtime and Python dependencies; a CUDA toolkit or compiler is not required.
+Loading, saving, simplification, and quality comparisons run on the CPU without
+initializing CUDA.
+
+See [installation and compatibility](docs/installation.md) for GPU requirements,
+source builds, and reinstalling a changed wheel with the same version number.
+
+## Fuse mesh files
+
+```python
+import fusemesh
+
+result = fusemesh.reconstruct(["a.off", "b.obj"], voxel_size=0.05)
+fusemesh.save_mesh("union.obj", result)
+print(result.metadata)
+```
+
+A single path also works: `fusemesh.reconstruct("model.off", voxel_size=0.05)`.
+For arrays, use `reconstruct([(vertices, faces)], voxel_size=0.05)`; each array
+pair represents one solid. Returned vertices are float64 `(N, 3)` coordinates
+and faces are uint64 `(M, 3)` indices.
+
+From a repository checkout, run the file example:
+
+```bash
+python examples/fuse_files.py a.off b.obj \
+  --voxel-size 0.05 --memory-mib 512 --output union.obj
+```
+
+To try generated geometry without supplying a file:
+
+```bash
+python examples/union_demo.py
+```
+
+## Reduce output triangles
+
+```python
+reduced = fusemesh.simplify(result, max_error=0.01, target_faces=5000)
+fusemesh.save_mesh("reduced.obj", reduced)
+```
+
+Simplification checks surface and sharp-edge deviation, per-shell volume, and
+manifold topology. `target_faces` is a soft goal; quality checks take priority.
+`max_error` is relative to the mesh being simplified, not the original union
+inputs. See [simplification](docs/simplification.md) for controls and limitations.
+
+## Measure surface accuracy
+
+```python
+report = fusemesh.compare_surfaces(
+    "original.off", "reconstructed.obj", tolerance=0.05,
+    degenerate_faces="drop",
+)
+print(report["symmetric"]["rms"])
+print(report["symmetric"]["f_score"])
+```
+
+This CPU comparison accepts open or nonmanifold surfaces. The explicit `drop`
+option excludes zero-area triangles and reports removal counts; the default is
+`error`. Distances use mesh coordinate units. Coverage and F-score depend on the
+chosen tolerance, and sampled maxima are not certified Hausdorff bounds.
+
+From a checkout, compare existing files with
+`python examples/quality_demo.py --inputs original.off reconstructed.obj`.
+Without `--inputs`, the demo reconstructs two boxes and requires a GPU and the
+`quality` extra. Multiple original solids also require that extra to construct
+an independent Boolean reference union. See [quality comparisons](docs/quality.md)
+for installation, metric definitions, and examples.
+
+## Reconstruction requirements and limits
+
+- Inputs must describe closed, consistently oriented manifold solids.
+  `validation="basic"` skips topology checks but does not make open or
+  nonmanifold solids supported. Self-intersections are not detected or repaired.
+- Trimesh loads local files. OFF faces must already be triangles; other formats
+  follow their reader's triangulation and grouping rules. See [mesh loading](docs/mesh-loading.md).
+- Smaller voxel sizes can resolve finer detail but require more work and memory.
+  Thin walls, narrow gaps, and small components may disappear. Voxel size is not
+  a guaranteed surface-error bound; output is not guaranteed manifold in
+  degenerate or unresolved cases.
+- The Python API defaults to a 512 MiB limit on explicit FUSE GPU buffers.
+  The file example defaults to 16 GiB; use `--memory-mib` to set it explicitly.
+  CUDA context memory and host memory are outside that limit.
+- Reconstruction does not perform exact triangle Booleans, mesh repair, adaptive voxel
+  refinement, automatic smoothing, or material/texture transfer.
+
+## Documentation
+
+Start with the [documentation index](docs/README.md), or go directly to:
+
+- [Installation and compatibility](docs/installation.md)
+- [Mesh loading and file examples](docs/mesh-loading.md)
+- [Python and native API](docs/api.md)
+- [Surface simplification](docs/simplification.md)
+- [Reconstruction quality](docs/quality.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Testing and benchmarks](docs/testing.md)
+
+FUSE uses BSD-3-Clause. Third-party notices are in [licenses](licenses/THIRD-PARTY-NOTICES.txt)
+and the installed wheel metadata.

fusemesh-0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0