When Pulling Fails

A streamlined implementation of SDF training and 3D shape reconstruction from sparse slices.

This directory contains the open-source core extracted from the original research project. It keeps the main pipeline minimal, clear, and runnable:

1. Generate 2D mask slices from a .ply or .stl mesh.
2. Reconstruct a training point cloud from the slices.
3. Generate key points with FA-CFPS.
4. Train the SDF network and export the reconstructed mesh.

whenpullingfails/
├── MySDF/                  # SDF models, datasets, and training runner
├── MyCudaK/                # CUDA extension for SDF sampling
├── utils/                  # Shared utility functions
├── scripts/                # Recommended command-line entry points
├── examples/               # Example commands and demo
├── docs/                   # Data format and pipeline documentation
├── tools_archive/          # Evaluation, visualization, and legacy scripts
└── data/                   # Demo or user data; excluded from Git by default

Training requires an NVIDIA GPU and CUDA; the current implementation does not support CPU-only execution. We recommend Conda and a PyTorch build compatible with the local CUDA installation:

cd whenpullingfails
conda activate Mysdf
pip install -U pip
pip install -r requirements.txt
pip install -e .

The CUDA extension is compiled automatically when scripts/train_sdf.py runs for the first time. A working CUDA Toolkit, CUDA-enabled PyTorch, and ninja are required.

Verified environment: Python 3.12, PyTorch 2.10 with CUDA 13.0, Open3D 0.19, and Trimesh 4.9.

The demo creates a small sphere and runs slicing, point-cloud reconstruction, CFPS, and SDF training:

bash examples/run_demo.sh

For a fast smoke test, train for a single iteration:

EPOCHS=1 \
VAL_FREQ=1 \
MESH_RESOLUTION=32 \
IMAGE_SHORT_PIXELS=32 \
CFPS_TARGET=64 \
bash examples/run_demo.sh

This command exports a low-resolution test mesh after one iteration. A regular training run exports a 256³ reconstruction every 1,000 iterations by default.

Use a separate directory for each case:

data/demo_case/
├── object.stl              # Or object.ply; source triangle mesh
├── slices/                 # Generated by slice_mesh.py
├── slice2pointclouds/      # Generated by reconstruct_points.py
└── out/                    # Generated by train_sdf.py

If mask slices are already available, prepare:

data/my_case/
└── slices/
    ├── images/
    │   ├── slice_000.png
    │   ├── slice_001.png
    │   └── ...
    └── meta.json

See docs/data_format.md for the meta.json schema.

Starting from a mesh:

python scripts/slice_mesh.py --inputpath data/demo_case/object.stl
python scripts/reconstruct_points.py --inputpath data/demo_case --interval 8 --jitter 0
python scripts/downsample_cfps.py --in_path data/demo_case/slice2pointclouds/full.ply --out data/demo_case/slice2pointclouds/full_fa.ply
python scripts/train_sdf.py --inputpath data/demo_case --epoch 2000 --useedge 0 --ellipse 1 --usesign 0 --sdfjudge 1 --usenegative 1 --injectlayer 3 --keyopt 1

If slices/images/ and slices/meta.json already exist, start from the second command.

• scripts/slice_mesh.py: Slice a .ply or .stl mesh into 2D masks and generate slices/meta.json.
• scripts/reconstruct_points.py: Build slice2pointclouds/full.ply, edge_recons.ply, and positive/negative samples from mask slices.
• scripts/downsample_cfps.py: Perform feature-aware point sampling, typically producing full_fa.ply.
• scripts/train_sdf.py: Train the SDF model and write reconstructions to out/sdf_*/visualresults/.

tools_archive/ preserves scripts for paper experiments, batch evaluation, visualization, and legacy workflows. batch_scripts/ has been adapted to this directory layout; other research scripts may still require changes for local data paths or external baseline implementations.

• Select a license, such as MIT, Apache-2.0, or GPL.
• Confirm the method name, project name, and paper citation format.
• Add author information, contact details, and a Citation section.