|
|
--- |
|
|
title: 3D Viewer |
|
|
emoji: 👀 |
|
|
colorFrom: yellow |
|
|
colorTo: blue |
|
|
sdk: gradio |
|
|
sdk_version: 5.29.0 |
|
|
python_version: 3.12.8 |
|
|
license: apache-2.0 |
|
|
app_file: app.py |
|
|
pinned: false |
|
|
short_description: A very simple 3D ply and glb viewer with link loading |
|
|
hf_oauth: true |
|
|
fullWidth: true |
|
|
thumbnail: >- |
|
|
https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/7Dhr01P8ZHeCt1WL2yzZR.png |
|
|
--- |
|
|
|
|
|
# 3D Viewer |
|
|
|
|
|
**3D Viewer** is a lightweight web application built with [Gradio](https://gradio.app) that allows users to view 3D models along with their corresponding height map and source images. The app dynamically loads these resources by parsing URL query string parameters, providing a seamless and interactive experience. |
|
|
|
|
|
## Features |
|
|
|
|
|
- **3D Model Display:** |
|
|
Uses `gr.Model3D` to render 3D models dynamically from a URL parameter (`3d`). |
|
|
|
|
|
- **Image Slider:** |
|
|
Displays images (height map and source image) using `gr.ImageSlider`. The images are loaded via URL query parameters named `hm` (height map) and `image` (source image). |
|
|
|
|
|
- **File Upload:** |
|
|
Includes an `gr.UploadButton` for uploading new file types like `.glb`, `.gltf`, `.obj`, `.png`, `.jpg`, `.jpeg`, `.webp`, and `.ply`. |
|
|
|
|
|
- **Permalink Generation:** |
|
|
- Automatically generates a permalink when query parameters are provided in the URL. |
|
|
- Users can also generate a permalink manually after uploading files by clicking the "Generate Permalink" button. |
|
|
- The permalink includes query parameters (`3d`, `hm`, and `image`) to share the current model and images. |
|
|
|
|
|
- **Dynamic Button Behavior:** |
|
|
- The "Generate Permalink" button is disabled when a permalink is automatically generated from query parameters. |
|
|
- The button is re-enabled when new files are uploaded, allowing users to generate a new permalink. |
|
|
|
|
|
- **HuggingFace Integration:** |
|
|
- Downloads files from HuggingFace repositories using `huggingface_hub.hf_hub_download`. |
|
|
- Supports authentication with HuggingFace via an API token. |
|
|
- Handles nested subfolders and filenames in HuggingFace datasets. |
|
|
|
|
|
- **Custom Theming:** |
|
|
The interface is styled with the `Surn/Beeuty` theme to ensure a modern and cohesive look. |
|
|
|
|
|
## How It Works |
|
|
|
|
|
- **Query String Parsing:** |
|
|
The app retrieves query string values (e.g., `3d`, `hm`, `image`) and dynamically loads the corresponding 3D model and images. If query parameters are provided, a permalink is automatically generated and displayed. |
|
|
|
|
|
- **Permalink Generation:** |
|
|
- The app uses the `generate_permalink_from_urls` function in `storage.py` to construct a permalink URL with query parameters. |
|
|
- The permalink can be shared to load the same 3D model and images in another session. |
|
|
|
|
|
- **File Upload and Permalink Behavior:** |
|
|
- Users can upload files (3D models and images) using the upload button. |
|
|
- After uploading, the "Generate Permalink" button becomes active, allowing users to create a new permalink for the uploaded files. |
|
|
- The permalink includes the uploaded files' URLs. |
|
|
|
|
|
- **HuggingFace Downloads:** |
|
|
- The app uses `huggingface_hub.hf_hub_download` to download files from HuggingFace repositories. |
|
|
- It supports nested subfolders and filenames in HuggingFace datasets. |
|
|
- Authentication is handled via the HuggingFace API token. |
|
|
|
|
|
- **Static Paths:** |
|
|
The app sets static paths for directories such as `images/`, `models/`, and `assets/` for accessing local resources. |
|
|
|
|
|
## Getting Started |
|
|
|
|
|
1. **Install Dependencies:** |
|
|
|
|
|
Ensure you have Python 3.12.8 installed and install Gradio (v5.29.0 or compatible): |
|
|
|
|
|
```pip install gradio==5.29.0 huggingface_hub``` |
|
|
|
|
|
|
|
|
2. **Run the Application:** |
|
|
|
|
|
Start the app by executing: |
|
|
|
|
|
```python app.py``` |
|
|
|
|
|
|
|
|
3. **Use the Query String:** |
|
|
|
|
|
After launching, the app can load specific resources if you pass the following query parameters in the URL: |
|
|
|
|
|
- `3d`: URL for the 3D model (e.g., `?3d=https://example.com/model.glb`) |
|
|
- `hm`: URL for the height map image (e.g., `?hm=https://example.com/heightmap.png`) |
|
|
- `image`: URL for the source image (e.g., `?image=https://example.com/source.png`) |
|
|
|
|
|
Example URL: |
|
|
|
|
|
``` |
|
|
http://localhost:7860/?3d=https://example.com/model.glb&hm=https://example.com/heightmap.png&image=https://example.com/source.png |
|
|
|
|
|
https://surn-3d-viewer.hf.space/?3d=https://huggingface.co/datasets/Surn/Storage/resolve/main/dngblfpc3w/scifi_city_3neol7yc_Colorful.ply&hm=https://huggingface.co/datasets/Surn/Storage/resolve/main/dngblfpc3w/scifi_city_3neol7yc_colorful_depth.png&image=https://huggingface.co/datasets/Surn/Storage/resolve/main/dngblfpc3w/scifi_city_3neol7yc_Colorful.png |
|
|
``` |
|
|
|
|
|
4. **Upload Files and Generate Permalink:** |
|
|
|
|
|
- Use the "Upload 3D Files" button to upload a 3D model and up to two images. |
|
|
- After uploading, click the "Generate Permalink" button to create a shareable link for the uploaded files. |
|
|
|
|
|
## Project Structure |
|
|
|
|
|
- **app.py:** |
|
|
The core application script defining the Gradio interface, callbacks, and dynamic query string processing. |
|
|
|
|
|
- **modules/storage.py:** |
|
|
Contains helper functions for uploading files to HuggingFace repositories and generating permalinks. |
|
|
|
|
|
- **README.md:** |
|
|
This documentation file outlining the project details and configuration. |
|
|
|
|
|
- **assets, images, models:** |
|
|
Directories containing static resources such as images, 3D models, and other assets. |
|
|
|
|
|
## License |
|
|
|
|
|
This project is licensed under the Apache-2.0 license. |
|
|
|
|
|
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference |
