vendor: dgrauet/Hunyuan3D-2.1-mlx snapshot (baseline)

.gitignore

@@ -0,0 +1,185 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!hy3dpaint/custom_rasterizer/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+.DS_Store
+# Cython debug symbols
+cython_debug/
+gradio_cache/
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+
+
+
+hy3dshape/tools/cmd*.sh
+hy3dshape/output_folder/
+demo.glb
+demo_textured.glb
+demo_textured.jpg
+demo_textured.mtl
+demo_textured_metallic.jpg
+demo_textured_roughness.jpg
+demo_untextured.glb
+white_mesh_remesh.obj
+hy3dpaint/ckpt/
+

.intendant.toml

@@ -0,0 +1,7 @@
+[intendant]
+version = "1"
+stack = "auto"
+enforcement = "advisory"
+
+[exemptions]
+PYTHON_LO001 = "Fork upstream avec layout flat, refactor reporté"

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks

API_DOCUMENTATION.md

@@ -0,0 +1,248 @@
+# Hunyuan3D API Documentation
+
+This document explains how the FastAPI documentation has been enhanced to provide comprehensive parameter documentation for the Hunyuan3D API server.
+
+## Overview
+
+The API server now uses Pydantic models to automatically generate interactive documentation that includes:
+
+- **Parameter descriptions and types**
+- **Default values and constraints**
+- **Example requests and responses**
+- **Organized endpoint groups**
+- **Interactive testing interface**
+
+## Key Improvements
+
+### 1. Pydantic Models
+
+The API now uses structured Pydantic models instead of raw JSON requests:
+
+```python
+class GenerationRequest(BaseModel):
+    """Request model for 3D generation API"""
+    image: str = Field(
+        ..., 
+        description="Base64 encoded input image for 3D generation",
+        example="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
+    )
+    texture: bool = Field(
+        False,
+        description="Whether to generate textures for the 3D model"
+    )
+    seed: int = Field(
+        1234,
+        description="Random seed for reproducible generation",
+        ge=0,
+        le=2**32-1
+    )
+    # ... more parameters
+```
+
+### 2. Parameter Documentation
+
+Each parameter includes:
+- **Description**: What the parameter does
+- **Type**: Data type (str, int, float, bool, etc.)
+- **Constraints**: Min/max values, allowed values
+- **Default values**: What happens if not provided
+- **Examples**: Sample values for testing
+
+### 3. API Organization
+
+Endpoints are organized into logical groups using tags:
+
+- **`generation`**: 3D model generation endpoints
+- **`status`**: Task status and health check endpoints
+
+### 4. Comprehensive Metadata
+
+The FastAPI app includes:
+- **Title and version**
+- **Detailed description**
+- **Contact information**
+- **License information**
+- **Feature overview**
+
+## Available Endpoints
+
+### Generation Endpoints
+
+#### POST `/generate`
+Generate a 3D model from an input image.
+
+**Parameters:**
+- `image` (required): Base64 encoded input image
+- `remove_background` (optional): Auto-remove background (default: true)
+- `texture` (optional): Generate textures (default: false)
+- `seed` (optional): Random seed (default: 1234)
+- `octree_resolution` (optional): Mesh resolution (default: 256)
+- `num_inference_steps` (optional): Generation steps (default: 5)
+- `guidance_scale` (optional): Generation guidance (default: 5.0)
+- `num_chunks` (optional): Processing chunks (default: 8000)
+- `face_count` (optional): Max faces for textures (default: 40000)
+- `type` (optional): Output format (default: "glb")
+
+#### POST `/send`
+Start asynchronous 3D generation task.
+
+**Parameters:** Same as `/generate`
+**Returns:** Task ID for status tracking
+
+### Status Endpoints
+
+#### GET `/health`
+Check service health status.
+
+#### GET `/status/{uid}`
+Check task status and retrieve results.
+
+## Accessing the Documentation
+
+### Interactive Documentation
+
+1. Start the API server:
+   ```bash
+   python api_server.py
+   ```
+
+2. Open your browser to:
+   - **Swagger UI**: `http://localhost:8081/docs`
+   - **ReDoc**: `http://localhost:8081/redoc`
+
+### Features of the Interactive Docs
+
+- **Try it out**: Test endpoints directly from the browser
+- **Parameter validation**: Automatic validation of input parameters
+- **Response examples**: See expected response formats
+- **Error handling**: Understand possible error responses
+- **Authentication**: Configure if needed (currently not required)
+
+## Example Usage
+
+### Basic 3D Generation
+
+```python
+import requests
+import base64
+
+# Load and encode image
+with open("input_image.png", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode()
+
+# Prepare request
+request_data = {
+    "image": image_data,
+    "texture": True,
+    "seed": 42,
+    "type": "glb"
+}
+
+# Send request
+response = requests.post("http://localhost:8081/generate", json=request_data)
+
+if response.status_code == 200:
+    # Save the generated 3D model
+    with open("output_model.glb", "wb") as f:
+        f.write(response.content)
+```
+
+### Asynchronous Generation
+
+```python
+# Start async task
+response = requests.post("http://localhost:8081/send", json=request_data)
+task_id = response.json()["uid"]
+
+# Check status
+status_response = requests.get(f"http://localhost:8081/status/{task_id}")
+status = status_response.json()
+
+if status["status"] == "completed":
+    # Decode and save the model
+    model_data = base64.b64decode(status["model_base64"])
+    with open("async_model.glb", "wb") as f:
+        f.write(model_data)
+```
+
+## Testing
+
+Use the provided test script to verify the API:
+
+```bash
+python test_api_docs.py
+```
+
+This script demonstrates:
+- Parameter validation
+- Request formatting
+- Response handling
+- Error scenarios
+
+## Benefits
+
+### For Developers
+- **Self-documenting API**: Parameters are clearly defined
+- **Type safety**: Automatic validation prevents errors
+- **Interactive testing**: Try endpoints without writing code
+- **Clear examples**: See exactly what to send and expect
+
+### For Users
+- **Easy integration**: Clear parameter documentation
+- **Error prevention**: Validation catches issues early
+- **Quick testing**: Interactive interface for exploration
+- **Comprehensive examples**: Working code samples
+
+## Technical Details
+
+### Dependencies
+- `fastapi`: Web framework with automatic documentation
+- `pydantic`: Data validation and serialization
+- `uvicorn`: ASGI server
+
+### File Structure
+```
+api_server.py          # Main API server with Pydantic models
+test_api_docs.py       # Test script demonstrating usage
+API_DOCUMENTATION.md   # This documentation file
+```
+
+### Customization
+
+To add new parameters or endpoints:
+
+1. **Add to Pydantic model**:
+   ```python
+   new_param: str = Field(
+       "default_value",
+       description="Parameter description"
+   )
+   ```
+
+2. **Update endpoint function**:
+   ```python
+   @app.post("/new_endpoint", tags=["category"])
+   async def new_endpoint(request: RequestModel):
+       """Endpoint description"""
+       # Implementation
+   ```
+
+3. **Documentation updates automatically**!
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Import errors**: Ensure all dependencies are installed
+2. **Port conflicts**: Change port in `api_server.py` if needed
+3. **Model loading**: Check model paths and GPU availability
+
+### Getting Help
+
+- Check the interactive documentation at `/docs`
+- Review the test script for working examples
+- Examine the Pydantic models for parameter details
+
+## Conclusion
+
+The enhanced API documentation provides a professional, user-friendly interface for the Hunyuan3D API. Users can now understand all parameters, test endpoints interactively, and integrate the API more easily into their applications. 

API_TESTING_SUMMARY.md

@@ -0,0 +1,174 @@
+# Hunyuan3D API Testing Summary
+
+## ✅ Successfully Implemented
+
+### 1. **Enhanced API Documentation**
+- **Pydantic Models**: Created comprehensive request/response models with detailed parameter documentation
+- **Parameter Validation**: All parameters now have descriptions, types, constraints, and examples
+- **Interactive Documentation**: FastAPI automatically generates Swagger UI and ReDoc interfaces
+- **API Organization**: Endpoints are tagged and organized by functionality
+
+### 2. **Fixed FastAPI Issues**
+- **Resolved Error**: Fixed the `FileResponse` response_model issue that was preventing server startup
+- **Parameter Documentation**: All API parameters now show up in the interactive documentation
+- **Validation**: Proper request validation with helpful error messages
+- **Simplified API**: Removed mesh upload functionality to prevent potential errors
+
+### 3. **Created Test Scripts**
+- **`test_generate_endpoint.py`**: Comprehensive testing with all parameters
+- **`curl_example.sh`**: Command-line examples using curl
+- **`simple_test.py`**: Simple Python script for testing with real images
+
+## 📋 API Endpoints Status
+
+### ✅ Working Endpoints
+
+| Endpoint | Method | Status | Description |
+|----------|--------|--------|-------------|
+| `/health` | GET | ✅ Working | Health check endpoint |
+| `/generate` | POST | ✅ Structured | 3D generation from images with full parameter documentation |
+| `/send` | POST | ✅ Structured | Async 3D generation |
+| `/status/{uid}` | GET | ✅ Structured | Task status checking |
+| `/docs` | GET | ✅ Working | Interactive Swagger UI documentation |
+| `/redoc` | GET | ✅ Working | Alternative API documentation |
+
+### 📊 Parameter Documentation
+
+All parameters in the `/generate` endpoint are now fully documented:
+
+| Parameter | Type | Default | Description | Constraints |
+|-----------|------|---------|-------------|-------------|
+| `image` | string | Required | Base64 encoded input image | - |
+| `remove_background` | boolean | true | Auto-remove background | - |
+| `texture` | boolean | false | Generate textures | - |
+| `seed` | integer | 1234 | Random seed | 0 to 2^32-1 |
+| `octree_resolution` | integer | 256 | Mesh resolution | 64 to 512 |
+| `num_inference_steps` | integer | 5 | Generation steps | 1 to 20 |
+| `guidance_scale` | float | 5.0 | Generation guidance | 0.1 to 20.0 |
+| `num_chunks` | integer | 8000 | Processing chunks | 1000 to 20000 |
+| `face_count` | integer | 40000 | Max faces for textures | 1000 to 100000 |
+| `type` | string | "glb" | Output format | "glb" or "obj" |
+
+## 🧪 Test Results
+
+### ✅ Successful Tests
+
+1. **Health Check**: ✅ Server responds correctly
+2. **Parameter Validation**: ✅ Invalid requests properly rejected with 422 errors
+3. **Request Structure**: ✅ All parameters properly documented and validated
+4. **API Documentation**: ✅ Interactive docs accessible at `/docs` and `/redoc`
+5. **Mesh Parameter Fix**: ✅ Removed mesh upload functionality to prevent errors
+
+### ⚠️ Expected Issues
+
+1. **Generation Failures**: 404 errors during actual 3D generation (expected due to GPU/model constraints)
+2. **Timeout Issues**: Generation may take longer than expected
+
+## 📁 Files Created
+
+### Core API Files
+- **`api_server.py`**: Enhanced with Pydantic models and comprehensive documentation
+- **`API_DOCUMENTATION.md`**: Complete documentation guide
+
+### Test Files
+- **`test_generate_endpoint.py`**: Comprehensive API testing script
+- **`curl_example.sh`**: Command-line curl examples
+- **`simple_test.py`**: Simple Python testing script
+- **`test_api_docs.py`**: Original documentation test script
+
+## 🚀 How to Use
+
+### 1. Start the API Server
+```bash
+python api_server.py --port 7860 --host 0.0.0.0
+```
+
+### 2. View Documentation
+- **Swagger UI**: http://localhost:7860/docs
+- **ReDoc**: http://localhost:7860/redoc
+
+### 3. Test the API
+```bash
+# Comprehensive testing
+python test_generate_endpoint.py
+
+# Simple testing with real image
+python simple_test.py assets/example_images/004.png
+
+# Command-line testing
+./curl_example.sh
+```
+
+### 4. Example API Call
+```python
+import requests
+import base64
+
+# Load and encode image
+with open("image.png", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode()
+
+# Prepare request
+request_data = {
+    "image": image_data,
+    "texture": True,
+    "seed": 42,
+    "type": "glb"
+}
+
+# Send request
+response = requests.post("http://localhost:7860/generate", json=request_data)
+
+if response.status_code == 200:
+    with open("output.glb", "wb") as f:
+        f.write(response.content)
+```
+
+## 🎯 Key Achievements
+
+### For Developers
+- **Self-documenting API**: All parameters clearly defined with types and constraints
+- **Interactive testing**: Try endpoints directly from the browser
+- **Type safety**: Automatic validation prevents errors
+- **Clear examples**: Working code samples provided
+- **Simplified interface**: Removed complex mesh upload functionality
+
+### For Users
+- **Easy integration**: Clear parameter documentation
+- **Error prevention**: Validation catches issues early
+- **Quick testing**: Interactive interface for exploration
+- **Comprehensive examples**: Multiple test scripts available
+- **Reliable operation**: No mesh upload errors
+
+## 🔧 Technical Details
+
+### Dependencies
+- `fastapi`: Web framework with automatic documentation
+- `pydantic`: Data validation and serialization
+- `uvicorn`: ASGI server
+
+### API Structure
+- **Request Models**: `GenerationRequest` with all documented parameters
+- **Response Models**: `GenerationResponse`, `StatusResponse`, `HealthResponse`
+- **Error Handling**: Proper validation and error messages
+- **Documentation**: Automatic OpenAPI/Swagger generation
+
+## 📈 Next Steps
+
+1. **Model Optimization**: Address GPU memory issues for actual generation
+2. **Performance**: Optimize generation speed and resource usage
+3. **Error Handling**: Add more specific error messages for generation failures
+4. **Monitoring**: Add request logging and performance metrics
+
+## ✅ Conclusion
+
+The API documentation enhancement is **complete and working**. Users can now:
+
+- ✅ View comprehensive parameter documentation
+- ✅ Test endpoints interactively
+- ✅ Understand all available options
+- ✅ Get proper validation and error messages
+- ✅ Use the API with confidence
+- ✅ Avoid mesh upload related errors
+
+The FastAPI server now provides a professional, well-documented interface for the Hunyuan3D API with full parameter visibility and validation, simplified to focus on image-to-3D generation. 

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

LICENSE

@@ -0,0 +1,83 @@
+TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT
+Tencent Hunyuan 3D 2.1 Release Date: June 13, 2025
+THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA AND IS EXPRESSLY LIMITED TO THE TERRITORY, AS DEFINED BELOW.
+By clicking to agree or by using, reproducing, modifying, distributing, performing or displaying any portion or element of the Tencent Hunyuan 3D 2.1 Works, including via any Hosted Service, You will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+1.	DEFINITIONS.
+a.	“Acceptable Use Policy” shall mean the policy made available by Tencent as set forth in the Exhibit A.
+b.	“Agreement” shall mean the terms and conditions for use, reproduction, distribution, modification, performance and displaying of Tencent Hunyuan 3D 2.1 Works or any portion or element thereof set forth herein.
+c.	“Documentation” shall mean the specifications, manuals and documentation for Tencent Hunyuan 3D 2.1 made publicly available by Tencent.
+d.	“Hosted Service” shall mean a hosted service offered via an application programming interface (API), web access, or any other electronic or remote means.
+e.	“Licensee,” “You” or “Your” shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Tencent Hunyuan 3D 2.1 Works for any purpose and in any field of use.
+f.	“Materials” shall mean, collectively, Tencent’s proprietary Tencent Hunyuan 3D 2.1 and Documentation (and any portion thereof) as made available by Tencent under this Agreement.
+g.	“Model Derivatives” shall mean all: (i) modifications to Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1; (ii) works based on Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1; or (iii) any other machine learning model which is created by transfer of patterns of the weights, parameters, operations, or Output of Tencent Hunyuan 3D 2.1 or any Model Derivative of Tencent Hunyuan 3D 2.1, to that model in order to cause that model to perform similarly to Tencent Hunyuan 3D 2.1 or a Model Derivative of Tencent Hunyuan 3D 2.1, including distillation methods, methods that use intermediate data representations, or methods based on the generation of synthetic data Outputs by Tencent Hunyuan 3D 2.1 or a Model Derivative of Tencent Hunyuan 3D 2.1 for training that model. For clarity, Outputs by themselves are not deemed Model Derivatives.
+h.	“Output” shall mean the information and/or content output of Tencent Hunyuan 3D 2.1 or a Model Derivative that results from operating or otherwise using Tencent Hunyuan 3D 2.1 or a Model Derivative, including via a Hosted Service.
+i.	“Tencent,” “We” or “Us” shall mean the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials.
+*   Section 1.i of the previous Hunyuan License Agreement defined “Tencent,” “We” or “Us” to mean THL A29 Limited, and the copyright notices pertaining to the Materials were previously in the name of “THL A29 Limited.”  That entity has now been de-registered.  You should treat all previously distributed copies of the Materials as if Section 1.i of the Agreement defined “Tencent,” “We” or “Us” to mean “the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials,” and treat the copyright notice(s) accompanying the Materials as if they were in the name of “Tencent.”  When providing a copy of any Agreement to Third Party recipients of the Tencent Hunyuan Works or products or services using them, as required by Section 3.a of the Agreement, you should provide the most current version of the Agreement, including the change of definition in Section 1.i of the Agreement.
+j.	“Tencent Hunyuan 3D 2.1” shall mean the 3D generation models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Us at [ https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1].
+k.	“Tencent Hunyuan 3D 2.1 Works” shall mean: (i) the Materials; (ii) Model Derivatives; and (iii) all derivative works thereof.
+l.	“Territory” shall mean the worldwide territory, excluding the territory of the European Union, United Kingdom and South Korea. 
+m.	“Third Party” or “Third Parties” shall mean individuals or legal entities that are not under common control with Us or You.
+n.	“including” shall mean including but not limited to.
+2.	GRANT OF RIGHTS.
+We grant You, for the Territory only, a non-exclusive, non-transferable and royalty-free limited license under Tencent’s intellectual property or other rights owned by Us embodied in or utilized by the Materials to use, reproduce, distribute, create derivative works of (including Model Derivatives), and make modifications to the Materials, only in accordance with the terms of this Agreement and the Acceptable Use Policy, and You must not violate (or encourage or permit anyone else to violate) any term of this Agreement or the Acceptable Use Policy.
+3.	DISTRIBUTION.
+You may, subject to Your compliance with this Agreement, distribute or make available to Third Parties the Tencent Hunyuan 3D 2.1 Works, exclusively in the Territory, provided that You meet all of the following conditions:
+a.	You must provide all such Third Party recipients of the Tencent Hunyuan 3D 2.1 Works or products or services using them a copy of this Agreement;
+b.	You must cause any modified files to carry prominent notices stating that You changed the files;
+c.	You are encouraged to: (i) publish at least one technology introduction blogpost or one public statement expressing Your experience of using the Tencent Hunyuan 3D 2.1 Works; and (ii) mark the products or services developed by using the Tencent Hunyuan 3D 2.1 Works to indicate that the product/service is “Powered by Tencent Hunyuan”; and
+d.	All distributions to Third Parties (other than through a Hosted Service) must be accompanied by a “Notice” text file that contains the following notice: “Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of “Tencent Hunyuan” are owned by Tencent or its affiliate.”
+You may add Your own copyright statement to Your modifications and, except as set forth in this Section and in Section 5, may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Model Derivatives as a whole, provided Your use, reproduction, modification, distribution, performance and display of the work otherwise complies with the terms and conditions of this Agreement (including as regards the Territory). If You receive Tencent Hunyuan 3D 2.1 Works from a Licensee as part of an integrated end user product, then this Section 3 of this Agreement will not apply to You.
+e.In the event that You use, integrate, implement, or otherwise deploy the Tencent Hunyuan Works, in whole or in part, to provide, enable, or support any service, product, or functionality to third parties, You shall clearly, accurately, and prominently disclose to all end users the full legal name and entity of the actual provider of such service, product, or functionality. You shall expressly and conspicuously state that Tencent is not affiliated with, associated with, sponsoring, or endorsing any such service, product, or functionality. You shall not use or display any name, logo, trademark, trade name, or other indicia of Tencent in any manner that could be construed as, or be likely to create, confusion, deception, or a false impression regarding any relationship, affiliation, sponsorship, or endorsement by Tencent. 
+4.	ADDITIONAL COMMERCIAL TERMS.
+If, on the Tencent Hunyuan 3D 2.1 version release date, the monthly active users of all products or services made available by or for Licensee is greater than 1 million monthly active users in the preceding calendar month, You must request a license from Tencent, which Tencent may grant to You in its sole discretion, and You are not authorized to exercise any of the rights under this Agreement unless or until Tencent otherwise expressly grants You such rights. 
+Subject to Tencent's written approval, you may request a license for the use of Tencent Hunyuan 3D 2.1 by submitting the following information to hunyuan3d@tencent.com:
+a.	Your company’s name and associated business sector that plans to use Tencent Hunyuan 3D 2.1.
+b.	Your intended use case and the purpose of using Tencent Hunyuan 3D 2.1.
+c.	Your plans to modify Tencent Hunyuan 3D 2.1 or create Model Derivatives.
+5.	RULES OF USE.
+a.	Your use of the Tencent Hunyuan 3D 2.1 Works must comply with applicable laws and regulations (including trade compliance laws and regulations) and adhere to the Acceptable Use Policy for the Tencent Hunyuan 3D 2.1 Works, which is hereby incorporated by reference into this Agreement. You must include the use restrictions referenced in these Sections 5(a) and 5(b) as an enforceable provision in any agreement (e.g., license agreement, terms of use, etc.) governing the use and/or distribution of Tencent Hunyuan 3D 2.1 Works and You must provide notice to subsequent users to whom You distribute that Tencent Hunyuan 3D 2.1 Works are subject to the use restrictions in these Sections 5(a) and 5(b).
+b.	You must not use the Tencent Hunyuan 3D 2.1 Works or any Output or results of the Tencent Hunyuan 3D 2.1 Works to improve any other AI model (other than Tencent Hunyuan 3D 2.1 or Model Derivatives thereof).
+c.	You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan 3D 2.1 Works, Output or results of the Tencent Hunyuan 3D 2.1 Works outside the Territory. Any such use outside the Territory is unlicensed and unauthorized under this Agreement.
+6.	INTELLECTUAL PROPERTY.
+a.	Subject to Tencent’s ownership of Tencent Hunyuan 3D 2.1 Works made by or for Tencent and intellectual property rights therein, conditioned upon Your compliance with the terms and conditions of this Agreement, as between You and Tencent, You will be the owner of any derivative works and modifications of the Materials and any Model Derivatives that are made by or for You.
+b.	No trademark licenses are granted under this Agreement, and in connection with the Tencent Hunyuan 3D 2.1 Works, Licensee may not use any name or mark owned by or associated with Tencent or any of its affiliates, except as required for reasonable and customary use in describing and distributing the Tencent Hunyuan 3D 2.1 Works. Tencent hereby grants You a license to use “Tencent Hunyuan” (the “Mark”) in the Territory solely as required to comply with the provisions of Section 3(c), provided that You comply with any applicable laws related to trademark protection. All goodwill arising out of Your use of the Mark will inure to the benefit of Tencent.
+c.	If You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Us or any person or entity alleging that the Materials or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by You, then all licenses granted to You under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed. You will defend, indemnify and hold harmless Us from and against any claim by any Third Party arising out of or related to Your or the Third Party’s use or distribution of the Tencent Hunyuan 3D 2.1 Works.
+d.	Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses.
+7.	DISCLAIMERS OF WARRANTY AND LIMITATIONS OF LIABILITY.
+a.	We are not obligated to support, update, provide training for, or develop any further version of the Tencent Hunyuan 3D 2.1 Works or to grant any license thereto.
+b.	UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE TENCENT HUNYUAN 3D 2.1 WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+c.	TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TENCENT OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE TENCENT HUNYUAN 3D 2.1 WORKS OR OUTPUTS, EVEN IF TENCENT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+8.	SURVIVAL AND TERMINATION.
+a.	The term of this Agreement shall commence upon Your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+b.	We may terminate this Agreement if You breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, You must promptly delete and cease use of the Tencent Hunyuan 3D 2.1 Works. Sections 6(a), 6(c), 7 and 9 shall survive the termination of this Agreement.
+9.	GOVERNING LAW AND JURISDICTION.
+a.	This Agreement and any dispute arising out of or relating to it will be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+b.	Exclusive jurisdiction and venue for any dispute arising out of or relating to this Agreement will be a court of competent jurisdiction in the Hong Kong Special Administrative Region of the People’s Republic of China, and Tencent and Licensee consent to the exclusive jurisdiction of such court with respect to any such dispute.
+ 
+EXHIBIT A
+ACCEPTABLE USE POLICY
+
+Tencent reserves the right to update this Acceptable Use Policy from time to time.
+Last modified: November 5, 2024
+
+Tencent endeavors to promote safe and fair use of its tools and features, including Tencent Hunyuan 3D 2.1. You agree not to use Tencent Hunyuan 3D 2.1 or Model Derivatives:
+1.	Outside the Territory;
+2.	In any way that violates any applicable national, federal, state, local, international or any other law or regulation;
+3.	To harm Yourself or others;
+4.	To repurpose or distribute output from Tencent Hunyuan 3D 2.1 or any Model Derivatives to harm Yourself or others; 
+5.	To override or circumvent the safety guardrails and safeguards We have put in place;
+6.	For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+7.	To generate or disseminate verifiably false information and/or content with the purpose of harming others or influencing elections;
+8.	To generate or facilitate false online engagement, including fake reviews and other means of fake online engagement;
+9.	To intentionally defame, disparage or otherwise harass others;
+10.	To generate and/or disseminate malware (including ransomware) or any other content to be used for the purpose of harming electronic systems;
+11.	To generate or disseminate personal identifiable information with the purpose of harming others;
+12.	To generate or disseminate information (including images, code, posts, articles), and place the information in any public context (including –through the use of bot generated tweets), without expressly and conspicuously identifying that the information and/or content is machine generated;
+13.	To impersonate another individual without consent, authorization, or legal right;
+14.	To make high-stakes automated decisions in domains that affect an individual’s safety, rights or wellbeing (e.g., law enforcement, migration, medicine/health, management of critical infrastructure, safety components of products, essential services, credit, employment, housing, education, social scoring, or insurance);
+15.	In a manner that violates or disrespects the social ethics and moral standards of other countries or regions;
+16.	To perform, facilitate, threaten, incite, plan, promote or encourage violent extremism or terrorism;
+17.	For any use intended to discriminate against or harm individuals or groups based on protected characteristics or categories, online or offline social behavior or known or predicted personal or personality characteristics;
+18.	To intentionally exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+19.	For military purposes;
+20.	To engage in the unauthorized or unlicensed practice of any profession including, but not limited to, financial, legal, medical/health, or other professional practices.

Notice.txt

@@ -0,0 +1,122 @@
+Usage and Legal Notices:
+
+Tencent is pleased to support the open source community by making Hunyuan 3D 2.1 available.
+
+Copyright (C) 2025 Tencent.  All rights reserved. The below software and/or models in this distribution may have been modified by Tencent ("Tencent Modifications"). All Tencent Modifications are Copyright (C) Tencent.
+
+Hunyuan 3D 2.1 is licensed under the TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT except for the third-party components listed below, which is licensed under different terms. Hunyuan 3D 2.1 does not impose any additional limitations beyond what is outlined in the respective licenses of these third-party components. Users must comply with all terms and conditions of original licenses of these third-party components and must ensure that the usage of the third party components adheres to all relevant laws and regulations. 
+
+For avoidance of doubts, Hunyuan 3D 2.1 means inference-enabling code, parameters, and weights of this Model only, which are made publicly available by Tencent in accordance with TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT.
+
+
+Other dependencies and licenses:
+
+
+Open Source Model Licensed under the MIT and CreativeML Open RAIL++-M License:
+--------------------------------------------------------------------
+1. Stable Diffusion
+Copyright (c) 2022 Stability AI
+
+
+Terms of the MIT and CreativeML Open RAIL++-M License:
+--------------------------------------------------------------------
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+CreativeML Open RAIL++-M License
+dated November 24, 2022
+
+Section I: PREAMBLE
+
+Multimodal generative models are being widely adopted and used, and have the potential to transform the way artists, among other individuals, conceive and benefit from AI or ML technologies as a tool for content creation.
+
+Notwithstanding the current and potential benefits that these artifacts can bring to society at large, there are also concerns about potential misuses of them, either due to their technical limitations or ethical considerations.
+
+In short, this license strives for both the open and responsible downstream use of the accompanying model. When it comes to the open character, we took inspiration from open source permissive licenses regarding the grant of IP rights. Referring to the downstream responsible use, we added use-based restrictions not permitting the use of the Model in very specific scenarios, in order for the licensor to be able to enforce the license in case potential misuses of the Model may occur. At the same time, we strive to promote open and responsible research on generative models for art and content generation.
+
+Even though downstream derivative versions of the model could be released under different licensing terms, the latter will always have to include - at minimum - the same use-based restrictions as the ones in the original license (this license). We believe in the intersection between open and responsible AI development; thus, this License aims to strike a balance between both in order to enable responsible open-science in the field of AI.
+
+This License governs the use of the model (and its derivatives) and is informed by the model card associated with the model.
+
+NOW THEREFORE, You and Licensor agree as follows:
+
+1. Definitions
+
+- "License" means the terms and conditions for use, reproduction, and Distribution as defined in this document.
+- "Data" means a collection of information and/or content extracted from the dataset used with the Model, including to train, pretrain, or otherwise evaluate the Model. The Data is not licensed under this License.
+- "Output" means the results of operating a Model as embodied in informational content resulting therefrom.
+- "Model" means any accompanying machine-learning based assemblies (including checkpoints), consisting of learnt weights, parameters (including optimizer states), corresponding to the model architecture as embodied in the Complementary Material, that have been trained or tuned, in whole or in part on the Data, using the Complementary Material.
+- "Derivatives of the Model" means all modifications to the Model, works based on the Model, or any other model which is created or initialized by transfer of patterns of the weights, parameters, activations or output of the Model, to the other model, in order to cause the other model to perform similarly to the Model, including - but not limited to - distillation methods entailing the use of intermediate data representations or methods based on the generation of synthetic data by the Model for training the other model.
+- "Complementary Material" means the accompanying source code and scripts used to define, run, load, benchmark or evaluate the Model, and used to prepare data for training or evaluation, if any. This includes any accompanying documentation, tutorials, examples, etc, if any.
+- "Distribution" means any transmission, reproduction, publication or other sharing of the Model or Derivatives of the Model to a third party, including providing the Model as a hosted service made available by electronic or other remote means - e.g. API-based or web access.
+- "Licensor" means the copyright owner or entity authorized by the copyright owner that is granting the License, including the persons or entities that may have rights in the Model and/or distributing the Model.
+- "You" (or "Your") means an individual or Legal Entity exercising permissions granted by this License and/or making use of the Model for whichever purpose and in any field of use, including usage of the Model in an end-use application - e.g. chatbot, translator, image generator.
+- "Third Parties" means individuals or legal entities that are not under common control with Licensor or You.
+- "Contribution" means any work of authorship, including the original version of the Model and any modifications or additions to that Model or Derivatives of the Model thereof, that is intentionally submitted to Licensor for inclusion in the Model by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Model, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+- "Contributor" means Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Model.
+
+Section II: INTELLECTUAL PROPERTY RIGHTS
+
+Both copyright and patent grants apply to the Model, Derivatives of the Model and Complementary Material. The Model and Derivatives of the Model are subject to additional terms as described in Section III.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare, publicly display, publicly perform, sublicense, and distribute the Complementary Material, the Model, and Derivatives of the Model.
+3. Grant of Patent License. Subject to the terms and conditions of this License and where and as applicable, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this paragraph) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Model and the Complementary Material, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Model to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Model and/or Complementary Material or a Contribution incorporated within the Model and/or Complementary Material constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for the Model and/or Work shall terminate as of the date such litigation is asserted or filed.
+
+Section III: CONDITIONS OF USAGE, DISTRIBUTION AND REDISTRIBUTION
+
+4. Distribution and Redistribution. You may host for Third Party remote access purposes (e.g. software-as-a-service), reproduce and distribute copies of the Model or Derivatives of the Model thereof in any medium, with or without modifications, provided that You meet the following conditions:
+Use-based restrictions as referenced in paragraph 5 MUST be included as an enforceable provision by You in any type of legal agreement (e.g. a license) governing the use and/or distribution of the Model or Derivatives of the Model, and You shall give notice to subsequent users You Distribute to, that the Model or Derivatives of the Model are subject to paragraph 5. This provision does not apply to the use of Complementary Material.
+You must give any Third Party recipients of the Model or Derivatives of the Model a copy of this License;
+You must cause any modified files to carry prominent notices stating that You changed the files;
+You must retain all copyright, patent, trademark, and attribution notices excluding those notices that do not pertain to any part of the Model, Derivatives of the Model.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions - respecting paragraph 4.a. - for use, reproduction, or Distribution of Your modifications, or for any such Derivatives of the Model as a whole, provided Your use, reproduction, and Distribution of the Model otherwise complies with the conditions stated in this License.
+5. Use-based restrictions. The restrictions set forth in Attachment A are considered Use-based restrictions. Therefore You cannot use the Model and the Derivatives of the Model for the specified restricted uses. You may use the Model subject to this License, including only for lawful purposes and in accordance with the License. Use may include creating any content with, finetuning, updating, running, training, evaluating and/or reparametrizing the Model. You shall require all of Your users who use the Model or a Derivative of the Model to comply with the terms of this paragraph (paragraph 5).
+6. The Output You Generate. Except as set forth herein, Licensor claims no rights in the Output You generate using the Model. You are accountable for the Output you generate and its subsequent uses. No use of the output can contravene any provision as stated in the License.
+
+Section IV: OTHER PROVISIONS
+
+7. Updates and Runtime Restrictions. To the maximum extent permitted by law, Licensor reserves the right to restrict (remotely or otherwise) usage of the Model in violation of this License.
+8. Trademarks and related. Nothing in this License permits You to make use of Licensors’ trademarks, trade names, logos or to otherwise suggest endorsement or misrepresent the relationship between the parties; and any rights not expressly granted herein are reserved by the Licensors.
+9. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Model and the Complementary Material (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Model, Derivatives of the Model, and the Complementary Material and assume any risks associated with Your exercise of permissions under this License.
+10. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Model and the Complementary Material (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+11. Accepting Warranty or Additional Liability. While redistributing the Model, Derivatives of the Model and the Complementary Material thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+12. If any provision of this License is held to be invalid, illegal or unenforceable, the remaining provisions shall be unaffected thereby and remain valid as if such provision had not been set forth herein.
+
+END OF TERMS AND CONDITIONS
+
+
+
+
+Attachment A
+
+Use Restrictions
+
+You agree not to use the Model or Derivatives of the Model:
+
+- In any way that violates any applicable national, federal, state, local or international law or regulation;
+- For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+- To generate or disseminate verifiably false information and/or content with the purpose of harming others;
+- To generate or disseminate personal identifiable information that can be used to harm an individual;
+- To defame, disparage or otherwise harass others;
+- For fully automated decision making that adversely impacts an individual’s legal rights or otherwise creates or modifies a binding, enforceable obligation;
+- For any use intended to or which has the effect of discriminating against or harming individuals or groups based on online or offline social behavior or known or predicted personal or personality characteristics;
+- To exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+- For any use intended to or which has the effect of discriminating against individuals or groups based on legally protected characteristics or categories;
+- To provide medical advice and medical results interpretation;
+- To generate or disseminate information for the purpose to be used for administration of justice, law enforcement, immigration or asylum processes, such as predicting an individual will commit fraud/crime commitment (e.g. by text profiling, drawing causal relationships between assertions made in documents, indiscriminate and arbitrarily-targeted use).

README.md

@@ -0,0 +1,282 @@
+
+<p align="center">
+  <img src="assets/images/teaser.jpg">
+</p>
+
+
+<div align="center">
+  <a href=https://3d.hunyuan.tencent.com target="_blank"><img src=https://img.shields.io/badge/Official%20Site-333399.svg?logo=homepage height=22px></a>
+  <a href=https://huggingface.co/spaces/tencent/Hunyuan3D-2.1  target="_blank"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Demo-276cb4.svg height=22px></a>
+  <a href=https://huggingface.co/tencent/Hunyuan3D-2.1 target="_blank"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Models-d96902.svg height=22px></a>
+  <a href=https://3d-models.hunyuan.tencent.com/ target="_blank"><img src= https://img.shields.io/badge/Page-bb8a2e.svg?logo=github height=22px></a>
+  <a href=https://discord.gg/dNBrdrGGMa target="_blank"><img src= https://img.shields.io/badge/Discord-white.svg?logo=discord height=22px></a>
+  <a href=https://arxiv.org/pdf/2506.15442 target="_blank"><img src=https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv height=22px></a>
+  <a href=https://x.com/TencentHunyuan target="_blank"><img src=https://img.shields.io/badge/Hunyuan-black.svg?logo=x height=22px></a>
+ <a href="#community-resources" target="_blank"><img src=https://img.shields.io/badge/Community-lavender.svg?logo=homeassistantcommunitystore height=22px></a>
+</div>
+
+[//]: # (  <a href=# target="_blank"><img src=https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv height=22px></a>)
+
+[//]: # (  <a href=# target="_blank"><img src= https://img.shields.io/badge/Colab-8f2628.svg?logo=googlecolab height=22px></a>)
+
+[//]: # (  <a href="#"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/v/mulankit?logo=pypi"  height=22px></a>)
+<br>
+
+## Apple MLX Port (Apple Silicon)
+
+This fork adds native **MLX inference** for the full Hunyuan3D-2.1 pipeline on Apple Silicon Macs — both shape generation (image → mesh) and PBR texture synthesis (mesh + reference image → textured GLB).
+
+### Weights
+
+Pre-converted MLX weights are hosted on HuggingFace and auto-downloaded on first use:
+
+> [`dgrauet/hunyuan3d-2.1-mlx`](https://huggingface.co/dgrauet/hunyuan3d-2.1-mlx)
+
+If you'd rather convert from the original PyTorch checkpoints yourself:
+
+```bash
+pip install mlx-forge
+mlx-forge convert hunyuan3d-2.1 --output ./models/hunyuan3d-2.1-mlx
+# or quantized for 16GB Macs:
+mlx-forge convert hunyuan3d-2.1 --quantize --bits 8 --output ./models/hunyuan3d-2.1-mlx
+```
+
+Override the default HF lookup by setting `HUNYUAN3D_MLX_WEIGHTS_DIR=/path/to/local/models`.
+
+### Install
+
+```bash
+pip install mlx mlx-arsenal safetensors Pillow trimesh scikit-image PyMCubes scipy
+pip install huggingface_hub xatlas opencv-python  # for Stage 2
+```
+
+### Stage 1 — Shape Generation (image → mesh)
+
+```python
+from hy3dshape.hy3dshape.pipeline_mlx import ShapePipeline
+
+pipe = ShapePipeline.from_pretrained("dgrauet/hunyuan3d-2.1-mlx")
+mesh = pipe("your_image.png", num_inference_steps=50, guidance_scale=7.5, octree_resolution=256)
+mesh.export("output.glb")
+```
+
+### Stage 2 — PBR Texture Synthesis (mesh + reference → textured GLB)
+
+```python
+from textureGenPipeline_mlx import Hunyuan3DPaintConfigMLX, Hunyuan3DPaintPipelineMLX
+
+cfg = Hunyuan3DPaintConfigMLX(max_num_view=6, resolution=512)
+pipe = Hunyuan3DPaintPipelineMLX(cfg)
+pipe(
+    mesh_path="mesh.glb",
+    image_path="reference.png",
+    output_mesh_path="textured.obj",
+    save_glb=True,
+)
+```
+
+Output: `textured.glb` with 2048² PBR albedo + metallic-roughness textures baked onto the mesh UVs (~9 min for 6 views at 512px on an M2 Pro).
+
+Defaults match the PyTorch reference config exactly, with one documented exception: `texture_size=2048` (PT uses 4096). The MLX Metal rasterizer has no tiling and would exceed the GPU command-buffer budget at 4096² on laptop GPUs (`kIOGPUCommandBufferCallbackErrorImpactingInteractivity`). Every other knob — `max_num_view`, `render_size`, `num_inference_steps`, `guidance_scale`, bake mode, inpaint method — is PT-identical.
+
+### End-to-end (image → textured GLB)
+
+`tests/test_stage1_to_stage2.py` chains both stages on a single reference image. Stage 1's dense marching-cubes mesh is automatically remeshed to ~40k faces before Stage 2's bake (the Metal rasterizer can't handle Stage 1's raw ~500k faces at `texture_size=2048`).
+
+### Memory Requirements
+
+| Precision | DiT Size | Peak Memory | Recommended Mac |
+|-----------|----------|-------------|-----------------|
+| FP16      | 5.7 GB   | ~10 GB      | 32 GB+          |
+| INT8      | 3.0 GB   | ~6 GB       | 16 GB+          |
+| INT4      | 1.6 GB   | ~4 GB       | 16 GB           |
+
+Stage 2 (paint) adds ~6 GB peak for the UNet + VAE + DINOv2 at fp32.
+
+### Scope
+
+- ✅ **Stage 1** (shape generation): fully ported to MLX, validated numerically against PyTorch (1e-5)
+- ✅ **Stage 2** (PBR texture synthesis): fully ported to MLX, full UNet match within 1.17e-5 vs PyTorch
+  - Metal rasterizer, UNet 2.5D with dual-stream reference attention, VAE, DINOv2, v_prediction scheduler
+  - **Cosine-weighted bake blend** (PT-parity `fast_bake_texture`) smooths across face seams
+  - **Mesh-aware vertex-color propagation + face barycentric raster**, `cv2.INPAINT_NS` (PT-parity), plus an EDT nearest-fill post-pass that pads UV gutters so 3D viewers doing bilinear sampling across island boundaries never pull in the atlas background
+  - **RealESRGAN x4 super-resolution** in MLX (512² → 2048² per view before bake)
+  - **GLB export**: PBRMaterial with sRGB `baseColorTexture`, `metallicRoughnessTexture` (glTF channel order), `doubleSided=true`
+  - All pipeline defaults now match the PyTorch reference exactly (see porting principle in `docs/forward_pass.md`)
+
+### Texture quality notes
+
+- Reference image must match the mesh content (e.g. mermaid image on mermaid mesh). Cross-pairing produces fragmented atlases since the diffusion's albedo views can't coherently project onto an unrelated 3D layout.
+- Tested on `assets/case_1/mesh.glb` (fox) and `assets/case_2/mesh.glb` (mermaid) — all 6/6 views clean with PT-aligned defaults.
+
+---
+
+## 🔥 News
+
+- Jul 26, 2025: 🤗 We release the first open-source, simulation-capable, immersive 3D world generation model, [HunyuanWorld-1.0](https://github.com/Tencent-Hunyuan/HunyuanWorld-1.0)!
+- Jun 19, 2025: 👋 We present the [technical report](https://arxiv.org/pdf/2506.15442) of Hunyuan3D-2.1, please check out the details and spark some discussion!
+- Jun 13, 2025: 🤗 We release the first production-ready 3D asset generation model, Hunyuan3D-2.1!
+
+> Join our **[Wechat](#)** and **[Discord](https://discord.gg/dNBrdrGGMa)** group to discuss and find help from us.
+
+| Wechat Group                                     | Xiaohongshu                                           | X                                           | Discord                                           |
+|--------------------------------------------------|-------------------------------------------------------|---------------------------------------------|---------------------------------------------------|
+| <img src="assets/qrcode/wechat.png"  height=140> | <img src="assets/qrcode/xiaohongshu.png"  height=140> | <img src="assets/qrcode/x.png"  height=140> | <img src="assets/qrcode/discord.png"  height=140> |        
+
+## 🤗 Community Contribution Leaderboard
+1. By [@visualbruno](https://github.com/visualbruno)
+  - ComfyUI-Hunyuan3d-2-1: https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1
+2. By [@VR-Jobs](https://github.com/VR-Jobs)
+  - Hunyuan3d-2-1 Unity Support: https://github.com/VR-Jobs/Hunyuan3D-2.1-Unity-XR-PC-Phone
+
+## ☯️ **Hunyuan3D 2.1**
+
+### Architecture
+
+Tencent Hunyuan3D-2.1 is a scalable 3D asset creation system that advances state-of-the-art 3D generation through two pivotal innovations: Fully Open-Source Framework and  Physically-Based Rendering (PBR) Texture Synthesis. For the first time, the system releases full model weights and training code, enabling community developers to directly fine-tune and extend the model for diverse downstream applications. This transparency accelerates academic research and industrial deployment. Moreover, replacing the prior RGB-based texture model, the upgraded PBR pipeline leverages  physics-grounded material simulation  to generate textures with photorealistic light interaction (e.g., metallic reflections, subsurface scattering).
+
+<p align="left">
+  <img src="assets/images/pipeline.png">
+</p>
+
+### Performance
+
+We have evaluated Hunyuan3D 2.1 with other open-source as well as close-source 3d-generation methods.
+The numerical results indicate that Hunyuan3D 2.1 surpasses all baselines in the quality of generated textured 3D assets
+and the condition following ability.
+
+| Model                   | ULIP-T(⬆)   | ULIP-I(⬆) | Uni3D-T(⬆)      | Uni3D-I(⬆) |
+|-------------------------|-----------|-------------|-------------|---------------|
+| Michelangelo  | 0.0752     | 0.1152      | 0.2133     | 0.2611         |
+| Craftsman | 0.0745     | 0.1296      | 0.2375     | 0.2987         |
+| TripoSG | 0.0767     | 0.1225      | 0.2506     | 0.3129       |
+| Step1X-3D | 0.0735     | 0.1183      | 0.2554     | 0.3195         |
+| Trellis | 0.0769     | 0.1267      | 0.2496     | 0.3116         |
+| Direct3D-S2 | 0.0706     | 0.1134      | 0.2346     | 0.2930         |
+| Hunyuan3D-Shape-2.1           | **0.0774** | **0.1395**  | **0.2556** | **0.3213** |
+
+
+| Model                   | CLIP-FiD(⬇)   | CMMD(⬇) | CLIP-I(⬆)      | LPIPS(⬇) |
+|-------------------------|-----------|-------------|-------------|---------------|
+| SyncMVD-IPA  | 28.39     | 2.397      | 0.8823     | 0.1423         |
+| TexGen | 28.24     | 2.448      | 0.8818     | 0.1331         |
+| Hunyuan3D-2.0 | 26.44     | 2.318     | 0.8893     | 0.1261         |
+| Hunyuan3D-Paint-2.1           | **24.78** | **2.191**  | **0.9207** | **0.1211**     |
+
+
+
+## 🎁 Models Zoo
+
+It takes 10 GB VRAM for shape generation, 21GB for texture generation and 29GB for shape and texture generation in total.
+
+
+| Model                      | Description                 | Date       | Size | Huggingface                                                                               |
+|----------------------------|-----------------------------|------------|------|-------------------------------------------------------------------------------------------| 
+| Hunyuan3D-Shape-v2-1         | Image to Shape Model        | 2025-06-14 | 3.3B | [Download](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-dit-v2-1)         |
+| Hunyuan3D-Paint-v2-1       | Texture Generation Model    | 2025-06-14 | 2B | [Download](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-paintpbr-v2-1)       |
+
+
+## 🤗 Get Started with Hunyuan3D 2.1
+
+Hunyuan3D 2.1 supports Macos, Windows, Linux. You may follow the next steps to use Hunyuan3D 2.1 via:
+
+### Install Requirements
+We test our model with Python 3.10 and PyTorch 2.5.1+cu124.
+```bash
+pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
+pip install -r requirements.txt
+
+cd hy3dpaint/custom_rasterizer
+pip install -e .
+cd ../..
+cd hy3dpaint/DifferentiableRenderer
+bash compile_mesh_painter.sh
+cd ../..
+
+wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt
+```
+
+### Code Usage
+
+We designed a diffusers-like API to use our shape generation model - Hunyuan3D-Shape and texture synthesis model -
+Hunyuan3D-Paint.
+
+```python
+import sys
+sys.path.insert(0, './hy3dshape')
+sys.path.insert(0, './hy3dpaint')
+from textureGenPipeline import Hunyuan3DPaintPipeline
+from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
+from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline
+
+# let's generate a mesh first
+shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2.1')
+mesh_untextured = shape_pipeline(image='assets/demo.png')[0]
+
+paint_pipeline = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=6, resolution=512))
+mesh_textured = paint_pipeline(mesh_path, image_path='assets/demo.png')
+```
+
+
+### Gradio App
+
+You could also host a [Gradio](https://www.gradio.app/) App in your own computer via:
+
+
+```bash
+python3 gradio_app.py \
+  --model_path tencent/Hunyuan3D-2.1 \
+  --subfolder hunyuan3d-dit-v2-1 \
+  --texgen_model_path tencent/Hunyuan3D-2.1 \
+  --low_vram_mode
+```
+
+
+## 🔗 BibTeX
+
+If you found this repository helpful, please cite our reports:
+
+```bibtex
+@misc{hunyuan3d2025hunyuan3d,
+    title={Hunyuan3D 2.1: From Images to High-Fidelity 3D Assets with Production-Ready PBR Material},
+    author={Tencent Hunyuan3D Team},
+    year={2025},
+    eprint={2506.15442},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+
+@misc{hunyuan3d22025tencent,
+    title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation},
+    author={Tencent Hunyuan3D Team},
+    year={2025},
+    eprint={2501.12202},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+
+@misc{yang2024hunyuan3d,
+    title={Hunyuan3D 1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation},
+    author={Tencent Hunyuan3D Team},
+    year={2024},
+    eprint={2411.02293},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+}
+```
+
+## Acknowledgements
+
+We would like to thank the contributors to
+the [TripoSG](https://github.com/VAST-AI-Research/TripoSG), [Trellis](https://github.com/microsoft/TRELLIS),  [DINOv2](https://github.com/facebookresearch/dinov2), [Stable Diffusion](https://github.com/Stability-AI/stablediffusion), [FLUX](https://github.com/black-forest-labs/flux), [diffusers](https://github.com/huggingface/diffusers), [HuggingFace](https://huggingface.co), [CraftsMan3D](https://github.com/wyysf-98/CraftsMan3D), [Michelangelo](https://github.com/NeuralCarver/Michelangelo/tree/main), [Hunyuan-DiT](https://github.com/Tencent-Hunyuan/HunyuanDiT), and [HunyuanVideo](https://github.com/Tencent-Hunyuan/HunyuanVideo) repositories, for their open research and
+exploration.
+
+## Star History
+
+<a href="https://star-history.com/#Tencent-Hunyuan/Hunyuan3D-2.1&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Tencent-Hunyuan/Hunyuan3D-2.1&type=Date" />
+ </picture>
+</a>

api_models.py

@@ -0,0 +1,82 @@
+"""
+Pydantic models for Hunyuan3D API server.
+"""
+from typing import Optional, Literal
+from pydantic import BaseModel, Field
+
+
+class GenerationRequest(BaseModel):
+    """Request model for 3D generation API"""
+    image: str = Field(
+        ..., 
+        description="Base64 encoded input image for 3D generation",
+        example="iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIAAAAmkwkpAAAAEElEQVR4nGP8z4AATAxEcQAz0QEHOoQ+uAAAAABJRU5ErkJggg=="
+    )
+    remove_background: bool = Field(
+        True,
+        description="Whether to automatically remove background from input image"
+    )
+    texture: bool = Field(
+        False,
+        description="Whether to generate textures for the 3D model"
+    )
+    seed: int = Field(
+        1234,
+        description="Random seed for reproducible generation",
+        ge=0,
+        le=2**32-1
+    )
+    octree_resolution: int = Field(
+        256,
+        description="Resolution of the octree for mesh generation",
+        ge=64,
+        le=512
+    )
+    num_inference_steps: int = Field(
+        5,
+        description="Number of inference steps for generation",
+        ge=1,
+        le=20
+    )
+    guidance_scale: float = Field(
+        5.0,
+        description="Guidance scale for generation",
+        ge=0.1,
+        le=20.0
+    )
+    num_chunks: int = Field(
+        8000,
+        description="Number of chunks for processing",
+        ge=1000,
+        le=20000
+    )
+    face_count: int = Field(
+        40000,
+        description="Maximum number of faces for texture generation",
+        ge=1000,
+        le=100000
+    )
+
+
+class GenerationResponse(BaseModel):
+    """Response model for generation status"""
+    uid: str = Field(..., description="Unique identifier for the generation task")
+
+
+class StatusResponse(BaseModel):
+    """Response model for status endpoint"""
+    status: str = Field(..., description="Status of the generation task")
+    model_base64: Optional[str] = Field(
+        None, 
+        description="Base64 encoded generated model file (only when status is 'completed')"
+    )
+    message: Optional[str] = Field(
+        None,
+        description="Error message (only when status is 'error')"
+    )
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check"""
+    status: str = Field(..., description="Health status")
+    worker_id: str = Field(..., description="Worker identifier") 

api_server.py

@@ -0,0 +1,230 @@
+# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
+# except for the third-party components listed below.
+# Hunyuan 3D does not impose any additional limitations beyond what is outlined
+# in the repsective licenses of these third-party components.
+# Users must comply with all terms and conditions of original licenses of these third-party
+# components and must ensure that the usage of the third party components adheres to
+# all relevant laws and regulations.
+
+# For avoidance of doubts, Hunyuan 3D means the large language models and
+# their software and algorithms, including trained model weights, parameters (including
+# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
+# fine-tuning enabling code and other elements of the foregoing made publicly available
+# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.
+
+"""
+A model worker executes the model.
+"""
+import argparse
+import asyncio
+import base64
+import logging
+import os
+import sys
+import threading
+import traceback
+import uuid
+from typing import Optional
+
+import torch
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, FileResponse
+
+# Import from root-level modules
+from api_models import GenerationRequest, GenerationResponse, StatusResponse, HealthResponse
+from logger_utils import build_logger
+from constants import (
+    SERVER_ERROR_MSG, DEFAULT_SAVE_DIR, API_TITLE, API_DESCRIPTION, 
+    API_VERSION, API_CONTACT, API_LICENSE_INFO, API_TAGS_METADATA
+)
+from model_worker import ModelWorker
+
+# Global variables
+SAVE_DIR = DEFAULT_SAVE_DIR
+worker_id = str(uuid.uuid4())[:6]
+logger = build_logger("controller", f"{SAVE_DIR}/controller.log")
+
+# Global worker and semaphore instances
+worker = None
+model_semaphore = None
+
+
+app = FastAPI(
+    title=API_TITLE,
+    description=API_DESCRIPTION,
+    version=API_VERSION,
+    contact=API_CONTACT,
+    license_info=API_LICENSE_INFO,
+    tags_metadata=API_TAGS_METADATA
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.post("/generate", tags=["generation"])
+async def generate_3d_model(request: GenerationRequest):
+    """
+    Generate a 3D model from an input image.
+    
+    This endpoint takes an image and generates a 3D model with optional textures.
+    The generation process includes background removal, mesh generation, and optional texture mapping.
+    
+    Returns:
+        FileResponse: The generated 3D model file (GLB or OBJ format)
+    """
+    logger.info("Worker generating...")
+    
+    # Convert Pydantic model to dict for compatibility
+    params = request.dict()
+    
+    uid = uuid.uuid4()
+    try:
+        file_path, uid = worker.generate(uid, params)
+        return FileResponse(file_path)
+    except ValueError as e:
+        traceback.print_exc()
+        logger.error(f"Caught ValueError: {e}")
+        ret = {
+            "text": SERVER_ERROR_MSG,
+            "error_code": 1,
+        }
+        return JSONResponse(ret, status_code=404)
+    except torch.cuda.CudaError as e:
+        logger.error(f"Caught torch.cuda.CudaError: {e}")
+        ret = {
+            "text": SERVER_ERROR_MSG,
+            "error_code": 1,
+        }
+        return JSONResponse(ret, status_code=404)
+    except Exception as e:
+        logger.error(f"Caught Unknown Error: {e}")
+        traceback.print_exc()
+        ret = {
+            "text": SERVER_ERROR_MSG,
+            "error_code": 1,
+        }
+        return JSONResponse(ret, status_code=404)
+
+
+@app.post("/send", response_model=GenerationResponse, tags=["generation"])
+async def send_generation_task(request: GenerationRequest):
+    """
+    Send a 3D generation task to be processed asynchronously.
+    
+    This endpoint starts the generation process in the background and returns a task ID.
+    Use the /status/{uid} endpoint to check the progress and retrieve the result.
+    
+    Returns:
+        GenerationResponse: Contains the unique task identifier
+    """
+    logger.info("Worker send...")
+    
+    # Convert Pydantic model to dict for compatibility
+    params = request.dict()
+    
+    uid = uuid.uuid4()
+    try:
+        threading.Thread(target=worker.generate, args=(uid, params,)).start()
+        ret = {"uid": str(uid)}
+        return JSONResponse(ret, status_code=200)
+    except Exception as e:
+        logger.error(f"Failed to start generation thread: {e}")
+        ret = {"error": "Failed to start generation"}
+        return JSONResponse(ret, status_code=500)
+
+
+@app.get("/health", response_model=HealthResponse, tags=["status"])
+async def health_check():
+    """
+    Health check endpoint to verify the service is running.
+    
+    Returns:
+        HealthResponse: Service health status and worker identifier
+    """
+    return JSONResponse({"status": "healthy", "worker_id": worker_id}, status_code=200)
+
+
+@app.get("/status/{uid}", response_model=StatusResponse, tags=["status"])
+async def status(uid: str):
+    """
+    Check the status of a generation task.
+    
+    Args:
+        uid: The unique identifier of the generation task
+        
+    Returns:
+        StatusResponse: Current status of the task and result if completed
+    """
+    # Check for textured file first (preferred output)
+    textured_file_path = os.path.join(SAVE_DIR, f'{uid}_textured.glb')
+    initial_file_path = os.path.join(SAVE_DIR, f'{uid}_initial.glb')
+    
+    #print(f"Checking files: {textured_file_path} ({os.path.exists(textured_file_path)}), {initial_file_path} ({os.path.exists(initial_file_path)})")
+    
+    # If textured file exists, generation is complete
+    if os.path.exists(textured_file_path):
+        try:
+            base64_str = base64.b64encode(open(textured_file_path, 'rb').read()).decode()
+            response = {'status': 'completed', 'model_base64': base64_str}
+            return JSONResponse(response, status_code=200)
+        except Exception as e:
+            logger.error(f"Error reading file {textured_file_path}: {e}")
+            response = {'status': 'error', 'message': 'Failed to read generated file'}
+            return JSONResponse(response, status_code=500)
+    
+    # If only initial file exists, texturing is in progress
+    elif os.path.exists(initial_file_path):
+        response = {'status': 'texturing'}
+        return JSONResponse(response, status_code=200)
+    
+    # If no files exist, still processing
+    else:
+        response = {'status': 'processing'}
+        return JSONResponse(response, status_code=200)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--host", type=str, default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8081)
+    parser.add_argument("--model_path", type=str, default='tencent/Hunyuan3D-2.1')
+    parser.add_argument("--subfolder", type=str, default='hunyuan3d-dit-v2-1')
+    parser.add_argument("--device", type=str, default="cuda")
+    parser.add_argument('--mc_algo', type=str, default='mc')
+    parser.add_argument("--limit-model-concurrency", type=int, default=5)
+    parser.add_argument('--enable_flashvdm', action='store_true')
+    parser.add_argument('--compile', action='store_true')
+    parser.add_argument('--low_vram_mode', action='store_true')
+    parser.add_argument('--cache-path', type=str, default='./gradio_cache')
+    args = parser.parse_args()
+    logger.info(f"args: {args}")
+
+    # Update SAVE_DIR based on cache-path argument
+    SAVE_DIR = args.cache_path
+    os.makedirs(SAVE_DIR, exist_ok=True)
+    
+
+    model_semaphore = asyncio.Semaphore(args.limit_model_concurrency)
+
+    worker = ModelWorker(
+        model_path=args.model_path, 
+        subfolder=args.subfolder,
+        device=args.device, 
+        low_vram_mode=args.low_vram_mode,
+        worker_id=worker_id,
+        model_semaphore=model_semaphore,
+        save_dir=SAVE_DIR,
+        mc_algo=args.mc_algo,
+        enable_flashvdm=args.enable_flashvdm,
+        compile=args.compile
+    )
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")