Update README.md

README.md

@@ -1,8 +1,8 @@
 ---
 title: 3D Viewer
-emoji: 🐢
+emoji: 👀
 colorFrom: yellow
-colorTo: green
+colorTo: blue
 sdk: gradio
 sdk_version: 5.29.0
 python_version: 3.12.8
@@ -13,7 +13,7 @@ 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/s0fQvcoiSBlH36AXpVwPi.png
+  https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/7Dhr01P8ZHeCt1WL2yzZR.png
 ---
 
 # 3D Viewer
@@ -29,7 +29,21 @@ thumbnail: >-
   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`, and `.ply`.
+  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.
@@ -37,7 +51,21 @@ thumbnail: >-
 ## How It Works
 
 - **Query String Parsing:**  
-  While running in Gradio, since the Python callback does not operate within a conventional HTTP request context, the app retrieves query string values by using client-side JavaScript. This JavaScript snippet captures the URL parameters and passes them to the Python callback, which then updates the components accordingly.
+  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.
@@ -48,7 +76,7 @@ thumbnail: >-
 
    Ensure you have Python 3.12.8 installed and install Gradio (v5.29.0 or compatible):
 
-```pip install gradio==5.29.0```
+```pip install gradio==5.29.0 huggingface_hub```
 
 
 2. **Run the Application:**
@@ -68,14 +96,25 @@ thumbnail: >-
 
    Example URL:
 
-```http://localhost:7860/?3d=https://example.com/model.glb&hm=https://example.com/heightmap.png&image=https://example.com/source.png```
+```
+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.
 
@@ -86,5 +125,4 @@ thumbnail: >-
 
 This project is licensed under the Apache-2.0 license.
 
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference