---
title: 3D Viewer
emoji: 👀
colorFrom: yellow
colorTo: blue
sdk: gradio
sdk_version: 5.31.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