Hugging Face's logo

Spaces:
Surn
/
3D-Viewer
Running

App Files Community
3D-Viewer / README.md
Surn's picture
Surn
Update README.md
65121c6
preview code
|
raw
history blame contribute delete
5.5 kB
metadata
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 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

  1. Run the Application:

    Start the app by executing:

python app.py

  1. 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

  1. 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