update examples

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+
+# Image files in examples directory (for Git LFS)
+workspace/gradio/examples/**/*.png filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.jpg filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.jpeg filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.bmp filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.tiff filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.tif filter=lfs diff=lfs merge=lfs -text

EXAMPLES_DIRECTORY.md

@@ -0,0 +1,286 @@
+# 📁 Examples 目录配置指南
+
+## 📍 Examples 目录位置
+
+### 默认位置
+
+Examples 目录应该放在：
+
+```
+workspace/gradio/examples/
+```
+
+### 完整路径说明
+
+根据 `app.py` 的配置：
+
+```python
+workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "workspace/gradio")
+examples_dir = os.path.join(workspace_dir, "examples")
+# 结果: workspace/gradio/examples/
+```
+
+## 📂 目录结构
+
+Examples 目录应该按以下结构组织：
+
+```
+workspace/gradio/examples/
+├── scene1/              # 场景 1
+│   ├── 000.png          # 图像文件
+│   ├── 010.png
+│   ├── 020.png
+│   └── ...
+├── scene2/              # 场景 2
+│   ├── 000.jpg
+│   ├── 010.jpg
+│   └── ...
+└── scene3/              # 场景 3
+    ├── image1.png
+    ├── image2.png
+    └── ...
+```
+
+### 要求
+
+1. **每个场景一个文件夹**：每个场景应该有自己的文件夹
+2. **文件夹名称**：文件夹名称会显示为场景名称
+3. **图像文件**：支持 `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.tif` 格式
+4. **第一张图像**：第一张图像（按文件名排序）会用作缩略图
+
+## 🔧 配置方式
+
+### 方式 1：使用默认路径（推荐）
+
+直接创建目录：
+
+```bash
+mkdir -p workspace/gradio/examples
+```
+
+然后添加场景：
+
+```bash
+# 创建场景文件夹
+mkdir -p workspace/gradio/examples/my_scene
+
+# 复制图像文件
+cp your_images/* workspace/gradio/examples/my_scene/
+```
+
+### 方式 2：使用环境变量
+
+通过环境变量自定义位置：
+
+```bash
+# 设置环境变量
+export DA3_WORKSPACE_DIR="/path/to/your/workspace"
+
+# 然后 examples 会在 /path/to/your/workspace/examples
+```
+
+或在 `app.py` 中修改：
+
+```python
+workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "/custom/path/workspace")
+```
+
+### 方式 3：在 Hugging Face Spaces 中
+
+在 Spaces 中，可以通过以下方式添加 examples：
+
+1. **通过 Git 上传**：
+   ```bash
+   git add workspace/gradio/examples/
+   git commit -m "Add example scenes"
+   git push
+   ```
+
+2. **通过网页界面上传**：
+   - 在 Spaces 的文件浏览器中创建 `workspace/gradio/examples/` 目录
+   - 上传场景文件夹和图像
+
+3. **使用持久存储**：
+   - 如果使用持久存储，examples 会保存在持久存储中
+   - 路径仍然是 `workspace/gradio/examples/`
+
+## 📝 示例场景结构示例
+
+### 示例 1：简单场景
+
+```
+workspace/gradio/examples/
+└── indoor_room/
+    ├── 000.png
+    ├── 010.png
+    ├── 020.png
+    └── 030.png
+```
+
+### 示例 2：多个场景
+
+```
+workspace/gradio/examples/
+├── outdoor_garden/
+│   ├── frame_001.jpg
+│   ├── frame_002.jpg
+│   └── frame_003.jpg
+├── office_space/
+│   ├── img_000.png
+│   ├── img_010.png
+│   └── img_020.png
+└── street_scene/
+    ├── 000.png
+    ├── 010.png
+    └── 020.png
+```
+
+## 🔍 验证 Examples 目录
+
+### 检查目录是否存在
+
+```bash
+# 检查默认位置
+ls -la workspace/gradio/examples/
+
+# 或使用 Python
+python -c "
+import os
+workspace_dir = os.environ.get('DA3_WORKSPACE_DIR', 'workspace/gradio')
+examples_dir = os.path.join(workspace_dir, 'examples')
+print(f'Examples directory: {examples_dir}')
+print(f'Exists: {os.path.exists(examples_dir)}')
+if os.path.exists(examples_dir):
+    scenes = [d for d in os.listdir(examples_dir) if os.path.isdir(os.path.join(examples_dir, d))]
+    print(f'Found {len(scenes)} scenes: {scenes}')
+"
+```
+
+### 检查场景信息
+
+应用启动时会自动扫描 examples 目录，并在日志中显示：
+
+```
+Found 3 example scenes:
+  - scene1 (5 images)
+  - scene2 (10 images)
+  - scene3 (8 images)
+```
+
+## 🚀 快速开始
+
+### 1. 创建目录结构
+
+```bash
+# 在项目根目录
+mkdir -p workspace/gradio/examples
+```
+
+### 2. 添加示例场景
+
+```bash
+# 创建场景文件夹
+mkdir -p workspace/gradio/examples/my_first_scene
+
+# 添加图像文件（复制你的图像）
+cp /path/to/your/images/* workspace/gradio/examples/my_first_scene/
+```
+
+### 3. 验证
+
+启动应用后，你应该能在 UI 中看到示例场景网格。
+
+## 📊 在 Hugging Face Spaces 中
+
+### 上传方式
+
+1. **通过 Git**（推荐）：
+   ```bash
+   # 在本地准备 examples
+   mkdir -p workspace/gradio/examples
+   # ... 添加场景 ...
+   
+   # 提交并推送
+   git add workspace/gradio/examples/
+   git commit -m "Add example scenes"
+   git push
+   ```
+
+2. **通过网页界面**：
+   - 在 Spaces 的文件浏览器中
+   - 创建 `workspace/gradio/examples/` 目录
+   - 上传场景文件夹
+
+### 注意事项
+
+- **文件大小限制**：确保图像文件不超过 Spaces 的文件大小限制
+- **持久存储**：如果使用持久存储，examples 会持久保存
+- **缓存**：示例场景的结果会缓存在 `workspace/gradio/input_images/` 下
+
+## 🔗 相关配置
+
+### 环境变量
+
+- `DA3_WORKSPACE_DIR`: 工作空间目录（默认：`workspace/gradio`）
+- Examples 目录自动设置为：`{DA3_WORKSPACE_DIR}/examples`
+
+### 代码中的配置
+
+- `depth_anything_3/app/gradio_app.py`: `cache_examples()` 方法
+- `depth_anything_3/app/modules/utils.py`: `get_scene_info()` 函数
+- `depth_anything_3/app/modules/event_handlers.py`: `load_example_scene()` 方法
+
+## ❓ 常见问题
+
+### Q: Examples 目录不存在怎么办？
+
+A: 应用会自动创建 `workspace/gradio/` 目录，但不会自动创建 `examples/` 子目录。你需要手动创建：
+
+```bash
+mkdir -p workspace/gradio/examples
+```
+
+### Q: 如何添加新的示例场景？
+
+A: 只需在 `workspace/gradio/examples/` 下创建新文件夹并添加图像：
+
+```bash
+mkdir -p workspace/gradio/examples/new_scene
+cp images/* workspace/gradio/examples/new_scene/
+```
+
+应用会在下次启动时自动检测新场景。
+
+### Q: 场景名称如何显示？
+
+A: 场景名称就是文件夹名称。例如：
+- 文件夹：`workspace/gradio/examples/indoor_room/`
+- 显示名称：`indoor_room`
+
+### Q: 缩略图如何选择？
+
+A: 缩略图是文件夹中按文件名排序后的第一张图像。
+
+## 📝 总结
+
+**Examples 目录位置：**
+- **默认**：`workspace/gradio/examples/`
+- **可通过环境变量**：`DA3_WORKSPACE_DIR` 自定义
+
+**目录结构：**
+```
+workspace/gradio/examples/
+├── scene1/
+│   └── images...
+├── scene2/
+│   └── images...
+└── scene3/
+    └── images...
+```
+
+**快速创建：**
+```bash
+mkdir -p workspace/gradio/examples
+# 然后添加场景文件夹和图像
+```
+

UPLOAD_EXAMPLES.md

@@ -0,0 +1,314 @@
+# 📤 上传 Examples 到 Hugging Face Spaces 指南
+
+## 🚨 问题：二进制文件被拒绝
+
+Hugging Face Spaces 会拒绝大文件（>100MB）或二进制文件，需要使用 **Git LFS** 来上传。
+
+## ✅ 解决方案
+
+### 方案 1：使用 Git LFS（推荐）⭐
+
+#### 步骤 1：配置 Git LFS
+
+我已经为你创建了 `.gitattributes` 文件，配置了图片文件的 Git LFS：
+
+```gitattributes
+# Images in examples directory
+workspace/gradio/examples/**/*.png filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.jpg filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.jpeg filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.bmp filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.tiff filter=lfs diff=lfs merge=lfs -text
+workspace/gradio/examples/**/*.tif filter=lfs diff=lfs merge=lfs -text
+```
+
+#### 步骤 2：安装 Git LFS（如果还没有）
+
+```bash
+# macOS
+brew install git-lfs
+
+# Linux
+sudo apt-get install git-lfs
+
+# Windows
+# 下载安装：https://git-lfs.github.com/
+```
+
+#### 步骤 3：初始化 Git LFS
+
+```bash
+cd /Users/bytedance/depth-anything-3
+
+# 初始化 Git LFS
+git lfs install
+
+# 验证配置
+git lfs track
+```
+
+#### 步骤 4：添加示例场景
+
+```bash
+# 创建 examples 目录
+mkdir -p workspace/gradio/examples/my_scene
+
+# 添加图像文件
+cp your_images/* workspace/gradio/examples/my_scene/
+
+# 添加文件到 Git LFS
+git add workspace/gradio/examples/
+git add .gitattributes
+
+# 提交
+git commit -m "Add example scenes with Git LFS"
+
+# 推送到 Spaces
+git push origin main
+```
+
+#### 步骤 5：验证
+
+```bash
+# 检查哪些文件使用了 LFS
+git lfs ls-files
+
+# 应该看到你的图片文件
+```
+
+---
+
+### 方案 2：使用持久存储（推荐用于大量数据）⭐
+
+如果示例场景很大，可以使用 Hugging Face Spaces 的持久存储功能。
+
+#### 步骤 1：在 Spaces 设置中启用持久存储
+
+1. 进入你的 Space 设置
+2. 启用 "Persistent storage"
+3. 设置存储大小（如 50GB）
+
+#### 步骤 2：在应用启动时下载示例
+
+修改 `app.py`，在启动时从外部源下载示例：
+
+```python
+import os
+import subprocess
+
+def download_examples():
+    """Download examples from external source if not exists"""
+    examples_dir = "workspace/gradio/examples"
+    if not os.path.exists(examples_dir) or not os.listdir(examples_dir):
+        print("Downloading example scenes...")
+        # 从 Hugging Face Dataset 下载
+        # 或从其他存储服务下载
+        # subprocess.run(["huggingface-cli", "download", "dataset/examples", ...])
+        pass
+
+if __name__ == "__main__":
+    download_examples()
+    # ... 启动应用
+```
+
+#### 步骤 3：上传到 Hugging Face Dataset
+
+```bash
+# 安装依赖
+pip install huggingface_hub datasets
+
+# 上传到 Dataset
+python -c "
+from datasets import Dataset
+from huggingface_hub import HfApi
+
+# 创建 dataset 并上传
+api = HfApi()
+api.upload_folder(
+    folder_path='workspace/gradio/examples',
+    repo_id='your-username/your-examples-dataset',
+    repo_type='dataset'
+)
+"
+```
+
+---
+
+### 方案 3：压缩后上传（小文件）
+
+如果图片文件较小（<100MB），可以压缩后上传：
+
+```bash
+# 压缩 examples 目录
+tar -czf examples.tar.gz workspace/gradio/examples/
+
+# 添加到 Git（作为普通文件）
+git add examples.tar.gz
+git commit -m "Add compressed examples"
+git push
+
+# 在应用启动时解压
+# 在 app.py 中添加：
+import tarfile
+if not os.path.exists("workspace/gradio/examples"):
+    print("Extracting examples...")
+    tarfile.open("examples.tar.gz").extractall()
+```
+
+---
+
+### 方案 4：运行时下载（推荐用于生产）⭐
+
+在应用启动时从外部源下载示例场景：
+
+#### 修改 `app.py`
+
+```python
+import os
+import subprocess
+from huggingface_hub import hf_hub_download
+
+def setup_examples():
+    """Setup examples directory by downloading if needed"""
+    examples_dir = "workspace/gradio/examples"
+    os.makedirs(examples_dir, exist_ok=True)
+    
+    # 如果 examples 目录为空，从外部源下载
+    if not os.listdir(examples_dir):
+        print("📥 Downloading example scenes...")
+        
+        # 方式 1: 从 Hugging Face Dataset 下载
+        try:
+            from datasets import load_dataset
+            dataset = load_dataset("your-username/your-examples-dataset")
+            # 处理并保存到 examples_dir
+        except:
+            pass
+        
+        # 方式 2: 从 URL 下载压缩包
+        # import urllib.request
+        # urllib.request.urlretrieve("https://...", "examples.zip")
+        # 解压到 examples_dir
+        
+        print("✅ Examples downloaded")
+
+if __name__ == "__main__":
+    setup_examples()
+    # ... 启动应用
+```
+
+---
+
+## 🎯 推荐方案对比
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|----------|
+| **Git LFS** | ✅ 简单直接<br>✅ 版���控制 | ⚠️ 需要 LFS 配额<br>⚠️ 大文件可能慢 | 小到中等示例（<1GB） |
+| **持久存储** | ✅ 无大小限制<br>✅ 快速访问 | ⚠️ 需要手动上传<br>⚠️ 需要付费 | 大量示例（>1GB） |
+| **运行时下载** | ✅ 不占用仓库空间<br>✅ 灵活 | ⚠️ 首次启动慢<br>⚠️ 需要网络 | 生产环境 |
+| **压缩上传** | ✅ 简单 | ⚠️ 大小限制<br>⚠️ 需要解压 | 小文件（<100MB） |
+
+---
+
+## 📝 完整 Git LFS 设置步骤
+
+### 1. 确保 Git LFS 已安装
+
+```bash
+git lfs version
+# 如果未安装，按照上面的步骤安装
+```
+
+### 2. 初始化 Git LFS
+
+```bash
+cd /Users/bytedance/depth-anything-3
+git lfs install
+```
+
+### 3. 检查 .gitattributes
+
+确保 `.gitattributes` 包含图片文件配置（我已经添加了）。
+
+### 4. 添加示例场景
+
+```bash
+# 创建场景
+mkdir -p workspace/gradio/examples/scene1
+cp your_images/* workspace/gradio/examples/scene1/
+
+# 添加文件
+git add workspace/gradio/examples/
+git add .gitattributes
+
+# 检查哪些文件会使用 LFS
+git lfs ls-files
+
+# 提交
+git commit -m "Add example scenes with Git LFS"
+
+# 推送
+git push origin main
+```
+
+### 5. 验证上传
+
+在 Spaces 中检查文件是否成功上传，图片文件应该显示为 LFS 指针。
+
+---
+
+## 🔧 故障排除
+
+### 问题 1：Git LFS 配额不足
+
+**解决方案：**
+- 使用方案 2（持久存储）或方案 4（运行时下载）
+- 压缩图片文件
+- 只上传必要的示例
+
+### 问题 2：推送失败
+
+**检查：**
+```bash
+# 检查 LFS 文件
+git lfs ls-files
+
+# 检查 LFS 状态
+git lfs status
+
+# 重新推送
+git push origin main --force
+```
+
+### 问题 3：文件仍然被拒绝
+
+**可能原因：**
+- `.gitattributes` 配置不正确
+- 文件没有通过 LFS 添加
+
+**解决：**
+```bash
+# 移除并重新添加
+git rm --cached workspace/gradio/examples/**/*.png
+git add workspace/gradio/examples/
+git commit -m "Fix: Add images via Git LFS"
+git push
+```
+
+---
+
+## 💡 最佳实践
+
+1. **小示例（<100MB）**：使用 Git LFS
+2. **中等示例（100MB-1GB）**：使用 Git LFS 或持久存储
+3. **大示例（>1GB）**：使用持久存储或运行时下载
+4. **生产环境**：使用运行时下载，从外部源获取
+
+---
+
+## 📚 相关资源
+
+- [Git LFS 文档](https://git-lfs.github.com/)
+- [Hugging Face Spaces 文档](https://huggingface.co/docs/hub/spaces)
+- [Hugging Face Datasets](https://huggingface.co/docs/datasets)
+

depth_anything_3/app/gradio_app.py

@@ -21,6 +21,7 @@ The original functionality has been split into modular components for better mai
 
 import argparse
 import os
+from functools import lru_cache
 from typing import Any, Dict, List
 import gradio as gr
 
@@ -575,7 +576,16 @@ class DepthAnything3App:
     ) -> None:
         """Set up example scene handlers."""
 
+        # Cache for example scene loading (in-memory cache for faster access)
+        _example_cache = {}
+
         def load_and_update_measure(name):
+            # Check cache first
+            if name in _example_cache:
+                print(f"✅ Using cached result for example scene: {name}")
+                return _example_cache[name]
+            
+            # Load example scene
             result = self.event_handlers.load_example_scene(name)
             # result = (reconstruction_output, target_dir, image_paths, log_message, processed_data, measure_view_selector, gs_video, gs_video_vis, gs_info_vis)  # noqa: E501
 
@@ -587,8 +597,19 @@ class DepthAnything3App:
                     self.event_handlers.visualization_handler.update_measure_view(result[4], 0)
                 )
 
-            return result + ("True", measure_img, measure_depth)
+            final_result = result + ("True", measure_img, measure_depth)
+            
+            # Cache the result (limit cache size to prevent memory issues)
+            if len(_example_cache) < 20:  # Cache up to 20 scenes
+                _example_cache[name] = final_result
+                print(f"💾 Cached result for example scene: {name}")
+            else:
+                print(f"⚠️ Cache full, not caching: {name}")
+            
+            return final_result
 
+        # Enable caching for example scene loading
+        # Gradio will cache the results based on the scene name
         for i, scene in enumerate(scenes):
             if i < len(scene_components):
                 scene_components[i].select(
@@ -607,6 +628,9 @@ class DepthAnything3App:
                         measure_image,
                         measure_depth_image,
                     ],
+                    # Note: cache_examples is not a valid parameter for select()
+                    # Caching is handled by file-based cache in load_example_scene()
+                    # which checks for predictions.npz files
                 )
 
     def launch(self, host: str = "127.0.0.1", port: int = 7860, **kwargs) -> None: