Add comprehensive model card for DragMesh

README.md

@@ -0,0 +1,89 @@
+---
+license: apache-2.0
+pipeline_tag: robotics
+---
+
+# <img src="https://github.com/AIGeeksGroup/DragMesh/raw/main/assets/dragmesh_logo.png" alt="DragMesh logo" width="60"/> DragMesh: Interactive 3D Generation Made Easy
+
+Official repository for the paper [**DragMesh: Interactive 3D Generation Made Easy**](https://huggingface.co/papers/2512.06424).
+
+[\ud83c\udf10 Project Website](https://aigeeksgroup.github.io/DragMesh/) | [\ud83d\udcbb Code](https://github.com/AIGeeksGroup/DragMesh) | [\ud83d\udcda Paper](https://huggingface.co/papers/2512.06424)
+
+> [!NOTE]  
+> GAPartNet (link above) is the canonical dataset source for all articulated assets used in DragMesh.  
+
+https://github.com/user-attachments/assets/428b0d36-50ab-4b46-ab17-679ad22c826b
+
+## ✨ Introduction
+While generative models have excelled at creating static 3D content, the pursuit of systems that understand how objects move and respond to interactions remains a fundamental challenge. We present DragMesh, a robust framework for real-time interactive 3D articulation built around a lightweight motion generation core. Our core contribution is a novel decoupled kinematic reasoning and motion generation framework, leveraging dual quaternions and FiLM conditioning to enable plausible, generative articulation on novel objects without retraining. This decoupled design allows DragMesh to achieve real-time performance, offering a practical step toward generative 3D intelligence.
+
+## ⚡ Quick Start
+### 🧩 Environment Setup
+We ship a full Conda specification in `environment.yml` (environment name: `dragmesh`). It targets Python 3.10, CUDA 12.1, and PyTorch 2.4.1. Create or update via:
+```bash
+conda env create -f environment.yml
+conda activate dragmesh
+# or update an existing env
+conda env update -f environment.yml --prune
+```
+
+> The spec already installs trimesh, pyrender, pygltflib, viser, Objaverse, SAPIEN, pytorch3d, and tiny-cuda-nn. If you prefer a minimal setup, install those packages manually before running the scripts.
+
+### 🛠️ Native Extensions
+Chamfer distance kernels are required for the VAE loss. Clone and build the upstream project:
+```bash
+git clone https://github.com/ThibaultGROUEIX/ChamferDistancePytorch.git
+cd ChamferDistancePytorch
+python setup.py install
+cd ..
+```
+
+### Custom Mesh Manipulation (manual input)
+You can manipulate custom meshes by supplying drag points/vectors directly through the CLI (no viewer UI). Use `--manual_joint_type revolute` or `--manual_joint_type prismatic` to force a specific motion family when needed.
+
+```bash
+python inference_pipeline.py \
+  --mesh_file assets/cabinet.obj \
+  --mask_file assets/cabinet_vertex_labels.npy \
+  --mask_format vertex \
+  --drag_point 0.12,0.48,0.05 \   # example: x,y,z point on the movable part
+  --drag_vector 0.0,0.0,0.2 \     # example: direction+magnitude of the drag
+  --manual_joint_type revolute \
+  --kpp_checkpoint best_model_kpp.pth \
+  --vae_checkpoint best_model.pth \
+  --output_dir outputs/cabinet_demo \
+  --num_samples 3
+```
+
+## 🎬 Demo Gallery
+
+**Translational drags**
+| | | |
+| --- | --- | --- |
+| <video src="https://github.com/user-attachments/assets/b5f1c6e1-4273-4a5e-9c89-ba87942140be" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/3114a80f-f7d1-4e8f-ad99-232dc679725a" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/c6103c82-e2e9-4d52-8525-87923b66d191" controls width="260"></video> |
+| <video src="https://github.com/user-attachments/assets/f0cad844-e399-46f4-954a-4ef9dea8f6bb" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/f5cfb154-3a98-4078-81da-fc57d1356a1c" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/f2c7c1fe-51bf-4744-a87a-1886f3f89350" controls width="260"></video> |
+
+**Rotational drags**
+| | | |
+| --- | --- | --- |
+| <video src="https://github.com/user-attachments/assets/ad4ee5e4-d634-4063-8201-a883c62c4053" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/284b4ce6-39c6-4c14-ab60-4465b41f6193" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/44dfbfc0-ca4c-475c-abcb-060210a3dc91" controls width="260"></video> |
+| <video src="https://github.com/user-attachments/assets/07915c65-a88c-42b0-87d6-9d398d8d0423" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/5d5e2d2e-0d12-421e-a435-aef0f4167c4d" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/d14b2c4c-9858-4279-b909-3eb9649595da" controls width="260"></video> |
+
+**Self-spin / free-spin**
+| | | |
+| --- | --- | --- |
+| <video src="https://github.com/user-attachments/assets/b255376d-19f4-47c2-b1de-5b8a1c1c39f0" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/b46ac7ff-d83f-43c7-a005-53c77526b3fc" controls width="260"></video> | <video src="https://github.com/user-attachments/assets/610eaab0-cdd0-4206-9cce-f160ee13d199" controls width="260"></video> |
+
+## 🧾 Citation
+If you find DragMesh helpful, please cite:
+```bibtex
+@article{zhang2025dragmesh,
+  title={DragMesh: Interactive 3D Generation Made Easy},
+  author={Zhang, Tianshan and Zhang, Zeyu and Tang, Hao},
+  journal={arXiv preprint arXiv:2512.06424},
+  year={2025}
+}
+```
+
+## 🙏 Acknowledgement
+We thank the GAPartNet team for the articulated dataset, and upstream projects such as ChamferDistancePytorch, Objaverse, SAPIEN, and PyTorch3D for their open-source contributions.