把六张 cubemap 图片直接放入 VR 场景，或者由 AliceVision 后端把普通手机照片拼成球面全景。
- 六面图（快速）：完全在浏览器处理。优先读取文件名方向，其次比较图片边缘，最后允许手动指定。
- 普通照片（后端拼接）：上传两张以上有重叠区域的照片，由 AliceVision 读取 EXIF 方向、估计焦距、畸变和相机方向，完成球面投影、接缝选择与多频段融合。
普通照片应当围绕相机光心拍摄，并在相邻照片间保留约 30%–50% 的重叠。近景物体和明显的相机平移会产生视差，球面拼接无法完全消除。
docker compose up --build如果 444 已被占用，可以指定其他宿主机端口：
PANORAMA_PORT=18081 docker compose up --build第一次构建会下载 AliceVision 3.3.0 官方 Linux 包，大小约 1.5GB，最终镜像也会比较大。全景处理使用 CPU，不要求 CUDA。
如果本机已经安装 AliceVision，可以只启动 Python 服务：
python3 -m venv .venv
. .venv/bin/activate
pip install -r backend/requirements.txt
ALICEVISION_BIN=/path/to/AliceVision/bin \
ALICEVISION_ROOT=/path/to/AliceVision \
uvicorn backend.app:app --host 0.0.0.0 --port 8000服务会同时托管前端和 API。GET /api/health 可检查所有必要的 AliceVision 命令是否就绪。
POST /api/panoramas
Content-Type: multipart/form-data
files=<image>
files=<image>返回 202 Accepted：
{
"id": "任务 ID",
"status": "queued",
"status_url": "/api/panoramas/任务 ID"
}GET /api/panoramas/{id}完成后响应包含：
{
"status": "complete",
"progress": 100,
"result_url": "/api/panoramas/{id}/result"
}任务默认保留 24 小时。服务重启时，未完成任务会标记为失败，不会自动续跑。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
PANORAMA_PORT |
444 |
Docker Compose 暴露到宿主机的端口 |
ALICEVISION_BIN |
从 PATH 查找 |
AliceVision 可执行文件目录 |
PANORAMA_JOBS_DIR |
/tmp/6tovr-jobs |
上传文件、日志和结果目录 |
PANORAMA_WORKERS |
1 |
同时运行的拼接任务数 |
PANORAMA_MAX_FILES |
40 |
单任务最多照片数 |
PANORAMA_MAX_FILE_BYTES |
62914560 |
单张照片最大字节数 |
PANORAMA_MAX_TOTAL_BYTES |
419430400 |
单任务最大上传字节数 |
PANORAMA_MAX_WIDTH |
12000 |
输出全景最大宽度 |
PANORAMA_MAX_THREADS |
0 |
AliceVision/OpenMP 线程数，0 表示自动 |
PANORAMA_COMMAND_TIMEOUT_SECONDS |
3600 |
每个处理阶段的超时时间 |
PANORAMA_JOB_TTL_HOURS |
24 |
已完成和失败任务的保留时间 |
PANORAMA_KEEP_INTERMEDIATES |
空 | 设为 true 时保留 EXR、特征和匹配文件 |
测试使用模拟的 AliceVision 命令，不需要下载官方包：
pip install -r backend/requirements-dev.txt
pytest