EXAMPLES_DIRECTORY.md

📁 Examples 目录配置指南

📍 Examples 目录位置

默认位置

Examples 目录应该放在：

workspace/gradio/examples/

完整路径说明

根据 app.py 的配置：

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：使用默认路径（推荐）

直接创建目录：

mkdir -p workspace/gradio/examples

然后添加场景：

# 创建场景文件夹
mkdir -p workspace/gradio/examples/my_scene

# 复制图像文件
cp your_images/* workspace/gradio/examples/my_scene/

方式 2：使用环境变量

通过环境变量自定义位置：

# 设置环境变量
export DA3_WORKSPACE_DIR="/path/to/your/workspace"

# 然后 examples 会在 /path/to/your/workspace/examples

或在 app.py 中修改：

workspace_dir = os.environ.get("DA3_WORKSPACE_DIR", "/custom/path/workspace")

方式 3：在 Hugging Face Spaces 中

在 Spaces 中，可以通过以下方式添加 examples：

1. 通过 Git 上传：

   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 目录

检查目录是否存在

# 检查默认位置
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. 创建目录结构

# 在项目根目录
mkdir -p workspace/gradio/examples

2. 添加示例场景

# 创建场景文件夹
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（推荐）：

   # 在本地准备 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/ 子目录。你需要手动创建：

mkdir -p workspace/gradio/examples

Q: 如何添加新的示例场景？

A: 只需在 workspace/gradio/examples/ 下创建新文件夹并添加图像：

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

快速创建：

mkdir -p workspace/gradio/examples
# 然后添加场景文件夹和图像