HiTOPS: Hierarchical Topology-aware Scoring Prior for 3D Part Decomposition

Geometry-only decomposition of 3D meshes into structurally meaningful components.

HiTOPS combines a hierarchical Flow-Freeze prior with TSDF-guided superquadric (SQ) fitting. The prior fuses multi-resolution structural scores through rule-based split and freeze decisions, while the fitting and surface mapping stages preserve articulation seams, thin structures, and structural decomposition details.

HiTOPS first constructs a hierarchical topology-aware Flow-Freeze prior, then fits body-surface superquadrics under TSDF guidance and aligns the fitted parts with the input mesh.

Highlights

• Geometry only: no learned model weights are required by the core pipeline.
• Hierarchical Flow-Freeze prior: multi-resolution 16³, 32³, and 64³ structural scores are fused through rule-based octree split/freeze decisions.
• TSDF-guided SQ fitting: editable superquadrics are inflated and fitted under a signed-distance constraint.
• Surface-aware decomposition: curvature segmentation and atom-to-SQ assignment produce dense per-face part labels and a colored mesh.

Pipeline

Stage	Module	Output
Hierarchical Flow-Freeze prior	hitops/adaptive/ (adaptive_block, adaptive_res_block)	octree multi-resolution block map
SDF volume	hitops/sdf/build_adaptive_sdf.py	TSDF on the adaptive grid
SQ fitting	hitops/sqfit/sq_fit.py (SDFAdaptiveFitter)	fitted superquadrics
Curvature segmentation	hitops/segment/curvature_seg.py (segment_pipeline)	mesh atoms (face labels)
Surface assignment	hitops/mapping/mesh_mapper.py (map_with_atoms)	final per-face SQ labels

The superquadric SDF implementation is vendored under third_party/marching_primitives/ and retains its own license.

Installation

Core pipeline

git clone https://github.com/EngineeringAI-LAB/HiTOPS.git
cd HiTOPS
pip install -e .

The core pipeline requires Python 3.9 or later and can run without learned weights.

Optional watertight preprocessing

The watertight remeshing utility requires additional GPU dependencies:

pip install -e ".[preprocess]"
pip install git+https://github.com/ashawkey/cubvh

See docs/DATA.md for the expected data layout and preprocessing workflow.

Quickstart

Five HY3D meshes with ground-truth part labels are included under examples/hy3d/00/. Run the complete pipeline on all examples:

bash scripts/run_example.sh

Results are written to:

outputs/example/<uid>/
├── adaptive_map_v4/
├── sdf_vol/
├── sq_fit_v20/
├── curv_seg_v4/
├── mesh_mapping_v8/
│   ├── face_labels_v8.npy
│   └── mesh_mapped_v8.ply
└── summary.json

Usage

Single mesh: SQ fitting only

python scripts/run_pipeline.py \
    --mesh_path /path/to/mesh.ply \
    --output_root /path/to/out

This produces adaptive_map/, sdf_vol/, and sq_fit_v20/ under <output_root>/<mesh_name>/.

Full batch: fitting, segmentation, and mapping

python scripts/run_batch_sqfit.py \
    --mesh_root /path/to/meshes/ply \
    --shard 00 \
    --output_root /path/to/out

Mapping only

Reuse existing SQ fitting and curvature-segmentation outputs:

python scripts/run_batch_mapper.py \
    --mesh_dir /path/to/meshes/ply/00 \
    --v4_dir /path/to/curv_seg_out \
    --sq_root /path/to/sqfit_out \
    --output_root /path/to/mapping_out

Input requirements

Watertight meshes are recommended because TSDF construction benefits from a well-defined interior. The Gradio demo also accepts non-watertight inputs: it automatically converts supported uploads to the PLY format expected by the pipeline and attempts decomposition.

Format conversion is not the same as topology repair. If a non-watertight mesh fails or produces an invalid interior, use hitops/preprocess/to_watertight_mesh.py before running HiTOPS.

All meshes are normalized to [-0.5, 0.5]³ internally.

License

HiTOPS is released under the terms in LICENSE. Vendored third-party code retains its original license under third_party/.