File size: 5,501 Bytes
be9ab0b 65121c6 be9ab0b 65121c6 be9ab0b d8c5068 0a4421d be9ab0b 0a4421d 65121c6 be9ab0b 7f0bd23 65121c6 7f0bd23 65121c6 7f0bd23 65121c6 7f0bd23 65121c6 7f0bd23 65121c6 7f0bd23 65121c6 7f0bd23 65121c6 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 |
---
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 |