【犀牛鸟实战issue】Add macOS support

README_macOS.md

@@ -0,0 +1,102 @@
+# 🍏 Hunyuan3D-2.1 - macOS Local Usage Guide (Shape Only)
+
+---
+
+## ⚠️ Feature Limitation Notice
+
+Due to macOS only supporting **Metal acceleration (MPS)** and **not CUDA**, Hunyuan3D-2.1 currently disables **texture generation** by default when running on macOS.
+
+Reasons include:
+
+- Texture functionality depends on CUDA-only modules such as `xatlas`, multi-view generation with `diffusers`, etc.
+- macOS does **not support NVIDIA GPUs** or CUDA; Metal backend performance is limited.
+- Texture-related libraries like `xatlas` and `bpy` are difficult to build or run on macOS.
+
+👉 **Recommendation**: If you need full texture generation, please use **Linux or Windows with an NVIDIA GPU**.
+
+---
+
+## System Requirements
+
+- **Operating System**: macOS 10.15 or later
+- **Hardware**:
+  - Apple Silicon chip (M1/M2/M3/M4)
+  - 16GB+ RAM
+  - 10GB+ free disk space
+- **Software**:
+  - [Anaconda](https://www.anaconda.com/download/success) environment manager recommended
+  - Python 3.11–3.12 
+  - Xcode Command Line Tools 
+    ```bash
+    xcode-select --install
+    ```
+
+---
+
+## 📦 Installation Steps
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
+cd Hunyuan3D-2.1
+```
+
+### 2. Create and activate conda environment
+
+```bash
+git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
+cd Hunyuan3D-2.1
+```
+
+### 3. Install macOS-specific dependencies
+
+```bash
+pip install -r requirements_macos.txt
+```
+
+### 4. Download model 
+Download the shape model files from Hugging Face:
+📥 https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-dit-v2-1
+
+---
+
+## 🚀 Usage Instructions
+
+### Run Demo (Shape Generation Only)
+
+```bash
+python demo_macos.py
+```
+### Gradio App 
+```bash
+python gradio_macos.py --device mps --low_vram_mode --disable_tex
+```
+Open your browser and go to: http://127.0.0.1:8080
+
+### Code usage (untextured mesh generation)
+```python
+import sys
+import torch
+sys.path.insert(0, './hy3dshape')
+
+from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline
+
+device = torch.device("mps")
+
+shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+    'tencent/Hunyuan3D-2.1',
+    torch_dtype=torch.float32,
+    device=device
+)
+shape_pipeline.to(device)
+
+mesh_untextured = shape_pipeline(image='path/to/image.png', batch_size=1)[0]
+
+mesh_untextured.export('demo.obj')
+```
+## Notes
+
+- The script will automatically use Apple MPS if available, otherwise it falls back to CPU.
+- It's recommended to disable texture (--disable_tex) to ensure compatibility and stability.
+- If you encounter "python not found" errors, make sure the virtual environment is activated.

demo_macos.py

@@ -0,0 +1,98 @@
+import sys
+import os
+import torch
+from PIL import Image
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+
+sys.path.insert(0, os.path.join(current_dir, 'hy3dshape'))
+sys.path.insert(0, os.path.join(current_dir, 'hy3dpaint'))
+
+INPUT_IMAGE_PATH = os.path.join(current_dir, 'assets', 'demo.png')
+
+
+def setup_device():
+    if torch.backends.mps.is_available():
+        device = torch.device("mps")
+        if hasattr(torch.backends.mps, "enable_mem_efficient"):
+            torch.backends.mps.enable_mem_efficient()
+        print("Using Apple MPS acceleration")
+    else:
+        device = torch.device("cpu")
+        print("Using CPU (MPS support not detected)")
+
+    return device
+
+
+def generate_mesh(low_vram=False):
+
+    device = setup_device()
+
+    if low_vram:
+        print("Low VRAM mode enabled")
+        os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"
+        torch.set_num_threads(1)
+
+    try:
+        print(f"Loading fixed input image: {INPUT_IMAGE_PATH}")
+        image = Image.open(INPUT_IMAGE_PATH).convert("RGBA")
+        # Attempt to remove background
+        from hy3dshape.rembg import BackgroundRemover
+        if image.mode == 'RGB':
+            remover = BackgroundRemover()
+            image = remover(image)
+
+        # Load model
+        from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline
+
+        shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+            'tencent/Hunyuan3D-2.1',
+            torch_dtype=torch.float32,
+            device=device
+        )
+
+        shape_pipeline.to(device)
+
+        # Generate 3D mesh
+        print("Generating 3D mesh...")
+        try:
+            mesh = shape_pipeline(image=image, batch_size=1)[0]
+        except Exception as e:
+            print(f"Mesh generation failed: {e}")
+            return None
+
+        output_path = os.path.join(current_dir, "demo.obj")
+        mesh.export(output_path)
+        print(f"Mesh saved to: {output_path}")
+        return output_path
+
+    except Exception as e:
+        print(f"Unexpected error occurred during processing: {e}")
+        return None
+
+
+def main():
+    print("Hunyuan3D-2.1 Mesh Generator")
+    print(f"Fixed input image: {INPUT_IMAGE_PATH}")
+
+    result = generate_mesh(
+        low_vram=False
+    )
+
+    if result:
+        print("Mesh generation succeeded!")
+        print(f"MESH_OUTPUT:{result}")
+    else:
+        print("Mesh generation failed")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    # macOS-specific settings
+    if sys.platform == "darwin":
+        # Disable CUDA
+        os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
+        # Enable MPS fallback
+        os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
+
+    main()

requirements_macos.txt

@@ -0,0 +1,57 @@
+--extra-index-url https://mirrors.cloud.tencent.com/pypi/simple/
+--extra-index-url https://mirrors.aliyun.com/pypi/simple
+
+# Build Tools
+ninja==1.11.1.1
+pybind11==2.13.4
+
+# Core ML/Deep Learning
+transformers==4.46.0
+diffusers==0.30.0
+accelerate==1.1.1
+pytorch-lightning>=2.0.0
+huggingface-hub==0.30.2
+safetensors==0.4.4
+
+# Scientific Computing
+numpy>=1.26.0
+scipy==1.14.1
+einops==0.8.0
+pandas==2.2.2
+
+# Computer Vision & Image Processing
+opencv-python==4.10.0.84
+imageio==2.36.0
+scikit-image==0.24.0
+rembg==2.0.65
+# realesrgan and basicsr rely on GPU, not supported on macOS for now
+
+# 3D Mesh Processing
+trimesh==4.4.7
+pymeshlab==2023.12.post3
+pygltflib==1.16.3
+open3d>=0.18.0 # May require Apple Silicon specific version
+
+# Configuration Management
+omegaconf==2.3.0
+pyyaml==6.0.2
+configargparse==1.7
+
+# Web Framework (for demo)
+gradio==5.33.0
+fastapi==0.115.12
+uvicorn==0.34.3
+
+# Utilities
+tqdm==4.66.5
+psutil==6.0.0
+
+# ONNX Runtime
+onnxruntime>=1.17.0
+torchmetrics==1.6.0
+
+pydantic==2.10.6
+
+timm
+pythreejs
+torchdiffeq