# pano-multires-preview

**Repository Path**: qxd-space/pano-multires-preview

## Basic Information

- **Project Name**: pano-multires-preview
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# my-pano-project · 瓦片全景预览

把一张 **2:1 等距柱状全景图** 做成可拖拽、可缩放的 720° 球面预览。项目提供**两种方式**，
方便对比加载速度：

| 方式                         | 生成脚本                                          | 预览页                        | 加载特点                                              |
| ---------------------------- | ------------------------------------------------- | ----------------------------- | ----------------------------------------------------- |
| **瓦片版**（multires） | [`script/slice_tiles.py`](script/slice_tiles.py) | [`index.html`](index.html)   | 切成多层级瓦片，按视角/缩放**渐进加载**，首屏快 |
| **单图版**（降采样）   | [`script/downsample.py`](script/downsample.py)   | [`single.html`](single.html) | 整张降采样图**一次性加载**，简单但首屏慢        |

两个页面右上角都会显示「加载耗时 X.XX s」，页头也有互相跳转的链接，可直接对比。

---

## 目录结构

```
my-pano-project/
├── input/                     # 源图（2:1 等距柱状全景：宽 = 2 × 高）
│   └── pano.jpeg
├── output/                    # 生成结果（运行脚本后才有，初始为空）
│   ├── pano01/                # ← 瓦片版：script/slice_tiles.py 生成
│   │   ├── 1/ 2/ 3/ …         #   各层级瓦片
│   │   ├── fallback/          #   6 张整面兜底图
│   │   └── config.json        #   Pannellum 配置
│   └── single/                # ← 单图版：script/downsample.py 生成
│       └── pano01.jpg         #   降采样后的整图
├── script/
│   ├── slice_tiles.py         # 切瓦片（多层级）
│   └── downsample.py          # 降采样 + 压缩成单图
├── index.html                 # 瓦片版预览页
├── single.html                # 单图版预览页
└── pyproject.toml             # 依赖：numpy、pillow
```

---

## 第 1 步：安装依赖

```powershell
uv sync
```

> - 所有命令都在**项目根目录**运行（脚本里的 `input/`、`output/` 是相对当前目录的）。
> - Windows PowerShell 不支持 `&&`，多条命令用 `;` 分隔。
> - `python` 一律用虚拟环境里的 `.\.venv\Scripts\python.exe`（系统 `python` 可能只是商店存根）。

---

## 第 2 步：生成预览资源

### 方式 A · 瓦片版（渐进加载）

```powershell
.\.venv\Scripts\python.exe script/slice_tiles.py input/pano.jpeg --name pano01
```

结果生成到 `output/pano01/`。参数：

| 参数                  | 默认       | 说明                                 |
| --------------------- | ---------- | ------------------------------------ |
| `input`（位置参数） | —         | 源图路径（必填）                     |
| `--name`            | —         | 输出目录名`output/<name>/`（必填） |
| `-o, --out-root`    | `output` | 输出根目录                           |
| `-s, --tile-size`   | `512`    | 每块瓦片边长（像素）                 |
| `-q, --quality`     | `85`     | JPEG 质量（1–95）                   |

### 方式 B · 单图版（降采样）

```powershell
.\.venv\Scripts\python.exe script/downsample.py input/pano.jpeg --name pano01
```

结果生成到 `output/single/pano01.jpg`。参数：

| 参数                  | 默认       | 说明                                           |
| --------------------- | ---------- | ---------------------------------------------- |
| `input`（位置参数） | —         | 源图路径（必填）                               |
| `--name`            | —         | 输出文件名`output/single/<name>.jpg`（必填） |
| `-o, --out-root`    | `output` | 输出根目录                                     |
| `--width`           | `6144`   | 目标宽度（高度自动 = 宽 / 2）；不会放大源图    |
| `-q, --quality`     | `85`     | JPEG 质量（1–95）                             |

> 两种方式都要求源图是 **2:1 等距柱状全景图**（宽 = 2 × 高），否则脚本报错。
> 同名输出会被覆盖，但不影响 `output/` 下的其他全景。

---

## 第 3 步：预览 & 对比加载速度

在项目根目录起本地服务器：

```powershell
.\.venv\Scripts\python.exe -m http.server 8765
```

- 瓦片版：**http://localhost:8765/index.html**
- 单图版：**http://localhost:8765/single.html**

两页右上角的「加载耗时」= 从**发起本次加载**（页面自动触发或点击「本地 / 远程」）到全景首次可见的时间，
含 `config.json` 请求、图片 / 瓦片下载与解码；**不含** Pannellum 自身 CDN 的下载时间（它对各页是固定偏移，计入会稀释对比）。

> ⚠️ 必须用 `http://` 打开，**不能双击 html**：`file://` 下浏览器会拦截读取 `config.json` / 图片的请求。

**怎么理解对比结果：**

- **瓦片版**先加载低分辨率层级并立刻显示，再按需补充清晰瓦片 → 首屏「加载耗时」通常明显更小，
  放大时才逐步加载更清晰的块。
- **单图版**要等整张图下载 + 解码完才显示 → 首屏更慢，但实现简单、没有瓦片对齐问题。
- 想比得更公平：两页都用 `Ctrl+Shift+R` 硬刷新绕过缓存，各测几次取稳定值；Pannellum 的
  CDN 文件第二次会命中浏览器缓存，此时差异主要就落在「瓦片 vs 整图」上。

---

## 常见问题

- **页面空白 / 加载失败**：确认已跑过第 2 步对应脚本（`output/pano01/config.json` 或
  `output/single/pano01.jpg` 存在），且用 `http://localhost:8765/` 打开而非 `file://`。
- **重切后画面没变化**：文件名没变会走缓存，按 `Ctrl + Shift + R` 硬刷新。
- **画面像"盒子内壁"、能看到棱边**：多半是源图不是标准 2:1 等距柱状图，或切图中途失败没切完。
- **换别的全景**：切图 / 降采样时用不同 `--name`，再改 `index.html` 里的 `PANO_DIR`
  或 `single.html` 里的 `PANO_IMG` 指向对应文件。

---

## 工作原理（简述）

```
等距柱状图 (2:1) ─┬─ 瓦片版：立方体投影 → 6 面 → 多层级瓦片 → config.json → index.html 按视角渐进加载
                  └─ 单图版：整图降采样 + 压缩 → 单张 JPG ─────────────────→ single.html 一次性加载
```

- **瓦片版**：把等距柱状图投影到立方体 6 个面，每面按多级分辨率切成小瓦片，并写出记录
  层级 / 尺寸的 `config.json`；Pannellum 依当前视角与缩放级别，只加载视野内、清晰度刚好的瓦片。
- **单图版**：不切分，直接把整图等比缩小并压缩成一张 JPG；Pannellum 用 `equirectangular`
  模式一次性加载整图渲染。