Update shortener logic and add documentation

app.py

@@ -320,120 +320,125 @@ def get_open_graph_meta_tags(query_params):
         <meta name="twitter:image" content="{og_image}">
     '''
     return meta_tags
+def build_gradio_interface() -> gr.Blocks:
+    placeholder_initial_query_params = {} 
+    processed_placeholder_params = _resolve_short_id_to_query_params(placeholder_initial_query_params)
+    initial_og_tags = get_open_graph_meta_tags(processed_placeholder_params)
 
-placeholder_initial_query_params = {} 
-processed_placeholder_params = _resolve_short_id_to_query_params(placeholder_initial_query_params)
-initial_og_tags = get_open_graph_meta_tags(processed_placeholder_params)
-
-gr.set_static_paths(paths=["images/", "models/", "assets/"])
-with gr.Blocks(css_paths="style_20250503.css", title="3D viewer", theme='Surn/beeuty',delete_cache=(21600,86400), fill_width=True, head=initial_og_tags) as viewer3d:
-    gr.Markdown("# 3D Model Viewer")
+    gr.set_static_paths(paths=["images/", "models/", "assets/"])
+    with gr.Blocks(css_paths="style_20250503.css", title="3D viewer", theme='Surn/beeuty',delete_cache=(21600,86400), fill_width=True, head=initial_og_tags) as viewer3d:
+        gr.Markdown("# 3D Model Viewer")
     
-    with gr.Row():
-        with gr.Column():
-            model_3d = gr.Model3D(
-                label="3D Model",
-                value=None,
-                elem_id="model_3d", key="model_3d", clear_color=[1.0, 1.0, 1.0, 0.1],
-                elem_classes="centered solid imgcontainer", interactive=True
+        with gr.Row():
+            with gr.Column():
+                model_3d = gr.Model3D(
+                    label="3D Model",
+                    value=None,
+                    elem_id="model_3d", key="model_3d", clear_color=[1.0, 1.0, 1.0, 0.1],
+                    elem_classes="centered solid imgcontainer", interactive=True
                 
-            )
-            image_slider = gr.ImageSlider(
-                label="2D Images",
-                value=None,
-                height="100%",
-                elem_id="image_slider", key="image_slider",
-                type="filepath"
-            )
-        
-            with gr.Row():
-                gr.Markdown("## Upload your own files")
-                gr.Markdown("### Supported formats: " + ", ".join([f"`{ext}`" for ext in constants.upload_file_types]))
-            with gr.Row():
-                upload_btn = gr.UploadButton(
-                    "Upload 3D Files", elem_id="upload_btn", key="upload_btn",
-                    file_count="multiple",
-                    file_types=constants.upload_file_types
                 )
-        
-            with gr.Row():
-                folder_name_box = gr.Textbox(
-                    label="Folder Name",
-                    value=default_folder,
-                    elem_id="folder_name",
-                    key="folder_name",
-                    placeholder="Enter folder name...",
-                    elem_classes="solid centered"
+                image_slider = gr.ImageSlider(
+                    label="2D Images",
+                    value=None,
+                    height="100%",
+                    elem_id="image_slider", key="image_slider",
+                    type="filepath"
                 )
-                permalink_button = gr.Button("Generate Permalink", elem_id="permalink_button", key="permalink_button", elem_classes="solid small centered")
+        
+                with gr.Row():
+                    gr.Markdown("## Upload your own files")
+                    gr.Markdown("### Supported formats: " + ", ".join([f"`{ext}`" for ext in constants.upload_file_types]))
+                with gr.Row():
+                    upload_btn = gr.UploadButton(
+                        "Upload 3D Files", elem_id="upload_btn", key="upload_btn",
+                        file_count="multiple",
+                        file_types=constants.upload_file_types
+                    )
+        
+                with gr.Row():
+                    folder_name_box = gr.Textbox(
+                        label="Upload Folder Name",
+                        value=default_folder,
+                        elem_id="folder_name",
+                        key="folder_name",
+                        placeholder="Enter folder name...",
+                        elem_classes="solid centered"
+                    )
+                    permalink_button = gr.Button("Generate Permalink", elem_id="permalink_button", key="permalink_button", elem_classes="solid small centered")
 
-            with gr.Row(visible=False, elem_id="permalink_row") as permalink_row:
-                permalink = gr.Textbox(
-                    show_copy_button=True,
-                    label="Permalink",
-                    elem_id="permalink",
-                    key="permalink",
-                    elem_classes="solid centered",
-                    max_lines=5,
-                    lines=4
-                )
-                gr.Markdown("### Copy the permalink to share your model and images.", elem_classes="solid centered",)
-                permalink_short = gr.Textbox(
-                    show_copy_button=True,
-                    label="Shortened Permalink",
-                    elem_id="short_permalink",
-                    key="permalink",
-                    elem_classes="solid centered",
-                    max_lines=5,
-                    lines=3
-                )
-    with gr.Row():
-        gr.HTML(value=getVersions(), visible=True, elem_id="versions")
+                with gr.Row(visible=False, elem_id="permalink_row") as permalink_row:
+                    permalink = gr.Textbox(
+                        show_copy_button=True,
+                        label="Permalink",
+                        elem_id="permalink",
+                        key="permalink",
+                        elem_classes="solid centered",
+                        max_lines=5,
+                        lines=4
+                    )
+                    gr.Markdown("### Copy the permalink to share your model and images.", elem_classes="solid centered",)
+                    permalink_short = gr.Textbox(
+                        show_copy_button=True,
+                        label="Shortened Permalink",
+                        elem_id="short_permalink",
+                        key="permalink",
+                        elem_classes="solid centered",
+                        max_lines=5,
+                        lines=3
+                    )
+        with gr.Row():
+            gr.HTML(value=getVersions(), visible=True, elem_id="versions")
     
-    viewer3d.load(
-        load_data,
-        inputs=[model_3d, image_slider],
-        outputs=[model_3d, image_slider, permalink, permalink_short],
-        scroll_to_output=True
-    ).then(
-        lambda link: (gr.update(visible=True), gr.update(interactive=False))
-            if link and len(link) > 0
-            else (gr.update(visible=False), gr.update(interactive=True)),
-        inputs=[permalink],
-        outputs=[permalink_row, permalink_button]
-    )
+        viewer3d.load(
+            load_data,
+            inputs=[model_3d, image_slider],
+            outputs=[model_3d, image_slider, permalink, permalink_short],
+            scroll_to_output=True
+        ).then(
+            lambda link: (gr.update(visible=True), gr.update(interactive=False))
+                if link and len(link) > 0
+                else (gr.update(visible=False), gr.update(interactive=True)),
+            inputs=[permalink],
+            outputs=[permalink_row, permalink_button]
+        )
 
-    upload_btn.upload(
-        process_upload, 
-        inputs=[upload_btn, model_3d, image_slider],
-        outputs=[model_3d, image_slider],
-        scroll_to_output=True,
-        api_name="process_upload",
-        show_progress=True
-    ).then(
-        lambda m, i: gr.update(interactive=True),
-        inputs=[model_3d, image_slider],
-        outputs=[permalink_button]
-    )
-    permalink_button.click(
-        lambda model, images, folder: storage.upload_files_to_repo(
-            files=[model] + list(images if images else []),
-            repo_id=constants.HF_REPO_ID,
-            folder_name=folder,
-            create_permalink=True,
-            repo_type="dataset"
-        )[1],
-        inputs=[model_3d, image_slider, folder_name_box],
-        outputs=[permalink],
-        scroll_to_output=True
-    ).then(
-        lambda link: gr.update(visible=True) if link and len(link) > 0 else gr.update(visible=False),
-        inputs=[permalink],
-        outputs=[permalink_row]
-    )
+        upload_btn.upload(
+            process_upload, 
+            inputs=[upload_btn, model_3d, image_slider],
+            outputs=[model_3d, image_slider],
+            scroll_to_output=True,
+            api_name="process_upload",
+            show_progress=True
+        ).then(
+            lambda m, i: gr.update(interactive=True),
+            inputs=[model_3d, image_slider],
+            outputs=[permalink_button]
+        )
+        permalink_button.click(
+            lambda model, images, folder: (
+                lambda res: (res.get("permalink", ""), res.get("short_permalink", ""))
+            )(storage.upload_files_to_repo(
+                files=[model] + list(images if images else []),
+                repo_id=constants.HF_REPO_ID,
+                folder_name=folder,
+                create_permalink=True,
+                repo_type="dataset"
+            )),
+            inputs=[model_3d, image_slider, folder_name_box],
+            outputs=[permalink, permalink_short],
+            scroll_to_output=True
+        ).then(
+            lambda link: gr.update(visible=True) if link and len(link) > 0 else gr.update(visible=False),
+            inputs=[permalink],
+            outputs=[permalink_row]
+        )
+
+        return viewer3d
 
 if __name__ == "__main__":
-    viewer3d.launch(
+    v3d = build_gradio_interface()
+    v3d.launch(
         allowed_paths=["assets", "assets/", "./assets", "images/", "./images", 'e:/TMP', 'models/', '3d_model_viewer/'],
         favicon_path="./assets/favicon.ico", show_api=True, strict_cors=False
     )

modules/storage.md

@@ -0,0 +1,154 @@
+# Storage Module (`modules/storage.py`) Usage Guide
+
+The `storage.py` module provides helper functions for:
+- Generating permalinks for 3D viewer projects.
+- Uploading files in batches to a Hugging Face repository.
+- Managing URL shortening by storing (short URL, full URL) pairs in a JSON file on the repository.
+
+## Key Functions
+
+### 1. `generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Given a list of file paths, it looks for exactly one model file (with an extension defined in `model_extensions`) and exactly two image files (extensions defined in `image_extensions`). If the criteria are met, it returns a permalink URL built from the base URL and query parameters.
+- **Usage Example:**from modules.storage import generate_permalink
+
+valid_files = [
+    "models/3d_model.glb",
+    "images/model_texture.png",
+    "images/model_depth.png"
+]
+base_url_external = "https://huggingface.co/datasets/Surn/Storage/resolve/main/saved_models/my_model"
+permalink = generate_permalink(valid_files, base_url_external)
+if permalink:
+    print("Permalink:", permalink)
+### 2. `generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Constructs a permalink URL by combining individual URLs for a 3D model (`model_url`), height map (`hm_url`), and image (`img_url`) into a single URL with corresponding query parameters.
+- **Usage Example:**from modules.storage import generate_permalink_from_urls
+
+model_url = "https://example.com/model.glb"
+hm_url = "https://example.com/heightmap.png"
+img_url = "https://example.com/source.png"
+
+permalink = generate_permalink_from_urls(model_url, hm_url, img_url)
+print("Generated Permalink:", permalink)
+### 3. `upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space")`
+- **Purpose:**  
+  Uploads a batch of files (each file represented as a path string) to a specified Hugging Face repository (e.g. `"Surn/Storage"`) under a given folder.
+  The function's return type is `Union[Dict[str, Any], List[Tuple[Any, str]]]`.
+  - When `create_permalink` is `True` and exactly three valid files (one model and two images) are provided, the function returns a dictionary:```
+{
+    "response": <upload_folder_response>,
+    "permalink": "<full_permalink_url>",
+    "short_permalink": "<shortened_permalink_url_with_sid>"
+}
+```  - Otherwise (or if `create_permalink` is `False` or conditions for permalink creation are not met), it returns a list of tuples, where each tuple is `(upload_folder_response, individual_file_link)`.
+  - If no valid files are provided, it returns an empty list `[]` (this case should ideally also return the dictionary with empty/None values for consistency, but currently returns `[]` as per the code).
+- **Usage Example:**
+
+  **a. Uploading with permalink creation:**from modules.storage import upload_files_to_repo
+
+files_for_permalink = [
+    "local/path/to/model.glb",
+    "local/path/to/heightmap.png",
+    "local/path/to/image.png"
+]
+repo_id = "Surn/Storage" # Make sure this is defined, e.g., from constants
+folder_name = "my_new_model_with_permalink"
+
+upload_result = upload_files_to_repo(
+    files_for_permalink, 
+    repo_id, 
+    folder_name, 
+    create_permalink=True
+)
+
+if isinstance(upload_result, dict):
+    print("Upload Response:", upload_result.get("response"))
+    print("Full Permalink:", upload_result.get("permalink"))
+    print("Short Permalink:", upload_result.get("short_permalink"))
+elif upload_result: # Check if list is not empty
+    print("Upload Response for individual files:")
+    for res, link in upload_result:
+        print(f"  Response: {res}, Link: {link}")
+else:
+    print("No files uploaded or error occurred.")
+  **b. Uploading without permalink creation (or if conditions for permalink are not met):**from modules.storage import upload_files_to_repo
+
+files_individual = [
+    "local/path/to/another_model.obj",
+    "local/path/to/texture.jpg"
+]
+repo_id = "Surn/Storage"
+folder_name = "my_other_uploads"
+
+upload_results_list = upload_files_to_repo(
+    files_individual, 
+    repo_id, 
+    folder_name, 
+    create_permalink=False # Or if create_permalink=True but not 1 model & 2 images
+)
+
+if upload_results_list: # Will be a list of tuples
+    print("Upload results for individual files:")
+    for res, link in upload_results_list:
+        print(f"  Upload Response: {res}, File Link: {link}")
+else:
+    print("No files uploaded or error occurred.")
+### 4. URL Shortening Functions: `gen_full_url(...)` and Helpers
+The module also enables URL shortening by managing a JSON file (e.g. `shortener.json`) in a Hugging Face repository. It supports CRUD-like operations:
+- **Read:** Look up the full URL using a provided short URL ID.
+- **Create:** Generate a new short URL ID for a full URL if no existing mapping exists.
+- **Update/Conflict Handling:**  
+If both short URL ID and full URL are provided, it checks consistency and either confirms or reports a conflict.
+
+#### `gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space", json_file="shortener.json")`
+- **Purpose:**  
+  Based on which parameter is provided, it retrieves or creates a mapping between a short URL ID and a full URL.  
+  - If only `short_url` (the ID) is given, it returns the corresponding `full_url`.  
+  - If only `full_url` is given, it looks up an existing `short_url` ID or generates and stores a new one.  
+  - If both are given, it validates and returns the mapping or an error status.
+- **Returns:** A tuple `(status_message, result_url)`, where `status_message` indicates the outcome (e.g., `"success_retrieved_full"`, `"created_short"`) and `result_url` is the relevant URL (full or short ID).
+- **Usage Examples:**
+
+  **a. Convert a full URL into a short URL ID:**from modules.storage import gen_full_url
+from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+
+full_permalink = "https://surn-3d-viewer.hf.space/?3d=https%3A%2F%2Fexample.com%2Fmodel.glb&hm=https%3A%2F%2Fexample.com%2Fheightmap.png&image=https%3A%2F%2Fexample.com%2Fsource.png"
+
+status, short_id = gen_full_url(
+    full_url=full_permalink, 
+    repo_id=HF_REPO_ID, 
+    json_file=SHORTENER_JSON_FILE
+)
+print("Status:", status)
+if status == "created_short" or status == "success_retrieved_short":
+    print("Shortened URL ID:", short_id)
+    # Construct the full short URL for sharing:
+    # permalink_viewer_url = "surn-3d-viewer.hf.space" # Or from constants
+    # shareable_short_url = f"https://{permalink_viewer_url}/?sid={short_id}"
+    # print("Shareable Short URL:", shareable_short_url)
+  **b. Retrieve the full URL from a short URL ID:**from modules.storage import gen_full_url
+from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+
+short_id_to_lookup = "aBcDeFg1"  # Example short URL ID
+
+status, retrieved_full_url = gen_full_url(
+    short_url=short_id_to_lookup, 
+    repo_id=HF_REPO_ID, 
+    json_file=SHORTENER_JSON_FILE
+)
+print("Status:", status)
+if status == "success_retrieved_full":
+    print("Retrieved Full URL:", retrieved_full_url)
+## Notes
+- **Authentication:** All functions that interact with Hugging Face Hub use the HF API token defined as `HF_API_TOKEN` in `modules/constants.py`. Ensure this environment variable is correctly set.
+- **Constants:** Functions like `gen_full_url` and `upload_files_to_repo` (when creating short links) rely on `HF_REPO_ID` and `SHORTENER_JSON_FILE` from `modules/constants.py` for the URL shortening feature.
+- **File Types:** Only files with extensions included in `upload_file_types` (a combination of `model_extensions` and `image_extensions` from `modules/constants.py`) are processed by `upload_files_to_repo`.
+- **Repository Configuration:** When using URL shortening and file uploads, ensure that the specified Hugging Face repository (e.g., defined by `HF_REPO_ID`) exists and that you have write permissions.
+- **Temporary Directory:** `upload_files_to_repo` temporarily copies files to a local directory (configured by `TMPDIR` in `modules/constants.py`) before uploading.
+- **Error Handling:** Functions include basic error handling (e.g., catching `RepositoryNotFoundError`, `EntryNotFoundError`, JSON decoding errors, or upload issues) and print messages to the console for debugging. Review function return values to handle these cases appropriately in your application.
+
+---
+
+This guide provides the essential usage examples for interacting with the storage and URL-shortening functionality. You can integrate these examples into your application or use them as a reference when extending functionality.

modules/storage.py

@@ -7,7 +7,10 @@ import json
 import base64
 from huggingface_hub import login, upload_folder, hf_hub_download, HfApi
 from huggingface_hub.utils import RepositoryNotFoundError, EntryNotFoundError
-from modules.constants import HF_API_TOKEN, upload_file_types, model_extensions, image_extensions
+from modules.constants import HF_API_TOKEN, upload_file_types, model_extensions, image_extensions, HF_REPO_ID, SHORTENER_JSON_FILE
+from typing import Any, Dict, List, Tuple, Union
+
+# see storage.md for detailed information about the storage module and its functions.
 
 def generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space"):
     """
@@ -52,7 +55,14 @@ def generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_ur
     query_str = urllib.parse.urlencode(params)
     return f"https://{permalink_viewer_url}/?{query_str}"
 
-def upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space"):
+def upload_files_to_repo(
+    files: List[Any],
+    repo_id: str,
+    folder_name: str,
+    create_permalink: bool = False,
+    repo_type: str = "dataset",
+    permalink_viewer_url: str = "surn-3d-viewer.hf.space"
+) -> Union[Dict[str, Any], List[Tuple[Any, str]]]:
     """
     Uploads multiple files to a Hugging Face repository using a batch upload approach via upload_folder.
 
@@ -64,18 +74,24 @@ def upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, re
                                  returns a single permalink to the project with query parameters.
                                  Otherwise, returns individual permalinks for each file.
         repo_type (str): Repository type ("space", "dataset", etc.). Default is "dataset".
+        permalink_viewer_url (str): The base viewer URL.
 
     Returns:
-        If create_permalink is True and files match the criteria:
-            tuple: (response, permalink) where response is the output of the batch upload
-                   and permalink is the URL string (with fully qualified file paths) for the project.
-        Otherwise:
-            list: A list of tuples (response, permalink) for each file.
+        Union[Dict[str, Any], List[Tuple[Any, str]]]:
+            If create_permalink is True and files match the criteria:
+                dict: {
+                    "response": <upload response>,
+                    "permalink": <full_permalink URL>,
+                    "short_permalink": <shortened permalink URL>
+                }
+            Otherwise:
+                list: A list of tuples (response, permalink) for each file.
     """
     # Log in using the HF API token.
     login(token=HF_API_TOKEN)
     
     valid_files = []
+    permalink_short = None
     
     # Ensure folder_name does not have a trailing slash.
     folder_name = folder_name.rstrip("/")
@@ -110,8 +126,6 @@ def upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, re
         )
     
     # Construct external URLs for each uploaded file.
-    # For datasets, files are served at:
-    # https://huggingface.co/datasets/<repo_id>/resolve/main/<folder_name>/<filename>
     base_url_external = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}"
     individual_links = []
     for file_path in valid_files:
@@ -124,8 +138,19 @@ def upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, re
     if create_permalink and len(valid_files) == 3:
         permalink = generate_permalink(valid_files, base_url_external, permalink_viewer_url)
         if permalink:
-            return response, permalink
-
+            result, short_id = gen_full_url(
+                full_url=permalink,
+                repo_id=HF_REPO_ID,
+                json_file=SHORTENER_JSON_FILE
+            )
+            permalink_short = f"https://{permalink_viewer_url}/?sid={short_id}"
+            print(f"Creating shortened URL: {result} - {short_id}")
+            return {
+                "response": response,
+                "permalink": permalink,
+                "short_permalink": permalink_short
+            }
+    
     # Otherwise, return individual tuples for each file.
     return [(response, link) for link in individual_links]
 
@@ -249,20 +274,9 @@ def gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset
             new_short_id = _generate_short_id()
             # Construct the short URL using the permalink_viewer_url and the new_short_id as a query parameter or path
             # For this example, let's assume short URLs are like: https://permalink_viewer_url/?id=new_short_id
-            # This part might need adjustment based on how you want to structure your short URLs.
-            # A common pattern is permalink_viewer_url/new_short_id if the viewer can handle path-based routing.
-            # Or, if the viewer expects a query param like `?short=new_short_id`
-            # For now, let's assume the short_url itself is just the ID, and the full viewer URL is prepended elsewhere if needed.
-            # Or, more directly, the `short_url` parameter to this function *is* the ID.
-            # The request implies `short_url` is the *key* in the JSON.
-            
-            # Let's refine: the `short_url` stored in JSON is the ID. The "shortened URL" returned to user might be different.
-            # The function is `gen_full_url`, implying it can also *generate* a short URL if one doesn't exist for a full_url.
             
             url_data = _add_url_to_json(url_data, new_short_id, full_url)
             if _upload_json_to_repo(url_data, repo_id, json_file, repo_type):
-                # The value returned as "shortened_url" should be the ID itself, or a URL constructed with it.
-                # Let's return the ID for now, as the prompt asks for "shortened_url" as output.
                 return "created_short", new_short_id 
             else:
                 return "error_upload", None

modules/version_info.py

@@ -102,6 +102,15 @@ def versions_html():
         </a>
     '''
 
+    # Add a link to the shortener JSON file in the Hugging Face repo
+    from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Import constants
+    shortener_url = f"https://huggingface.co/datasets/{HF_REPO_ID}/resolve/main/{SHORTENER_JSON_FILE}"
+    shortener_link = f'''
+        <a href="{shortener_url}" target="_blank" style="cursor: pointer; text-decoration: underline;">
+            View Shortener JSON
+        </a>
+    '''
+
     v_html = f"""
         version: <a href="https://huggingface.co/spaces/Surn/3D-Viewer/commit/{"huggingface" if commit == "<none>" else commit}" target="_blank">{"huggingface" if commit == "<none>" else commit}</a>
         &#x2000;•&#x2000;
@@ -114,6 +123,8 @@ def versions_html():
         gradio: {gr.__version__}
         &#x2000;•&#x2000;
         {toggle_dark_link}
+        &#x2000;•&#x2000;
+        {shortener_link}
         <br>
         Full GPU Info:
         """