全景图高清原图下载：瓦片金字塔抓取与拼接实践

1. 右键另存为拿到的只是一张缩略图：全景图的分发逻辑

上个月帮一个项目组收拾尾巴，甲方把展厅全景的拍摄和上线都验收完了，最后提了一个很朴素的需求：把平台上那套成品拷一份归档，将来官网改版还要用。项目组的新同事打开页面，右键、图片另存为，得到一张 1024×512 的小图，放大两倍糊得像隔着毛玻璃看世界。他以为是浏览器的问题，换了三个浏览器，又试了手机端，结果一样。

这就是全景图高清下载这件事最容易被误解的地方：你在网页上看到的那张图，从来就不是"一张图"。全景播放器在屏幕上铺开的画面，是浏览器实时从服务器拉回来的一堆小方块，用 WebGL 贴到球面上渲染出来的。你右键点中的那个<img>标签，多半只是加载遮罩、logo 或者一张模糊的占位预览图，真正的画面内容在 Canvas 里，压根没有对应的图片文件。

所以想把一张 8K 甚至 16K 的全景原图完整拿下来，靠右键是没有出路的，得换个思路——不去"保存图片"，而是去"复现服务器发图的方式"。服务器怎么切，你就怎么收；服务器按什么规则命名，你就按什么规则拼。这件事的技术门槛其实不高，但它有一个很硬的前提：你得先看懂全景图的投影方式和分片规则，否则拿到几百个碎片也不知道该往哪放。

下面要聊的内容，适合三类人：手里有自己拍摄、自己账号下的全景素材需要本地备份的；做展厅、房产、文旅项目需要把成品交付给客户存档的；以及对全景图渲染管线好奇、想搞明白"为什么网页上的全景能转动"的技术同学。完全零基础也能跟上，我会把每个概念拆到能画在纸上的程度。文中涉及的具体平台一律用类型代称，因为不同平台的规则会随版本变化，讲清类型比记住某个名字有用得多。

提示：本文讨论的所有操作，前提都是你对素材拥有处置权——自己拍摄的、自己账号上传的、或者已获得明确授权的。平台用户协议里关于"是否允许导出原始资源"的条款，动手前请先读一遍，这条线比任何技术细节都重要。

2. 一张 2:1 的图被切成了几百块：全景图的两种投影底子

2.1 等距圆柱投影：把地球摊平成一张 2:1 的纸

要理解切片，先得理解全景图的"底片"长什么样。绝大多数全景播放器吃的是一种叫等距圆柱投影（Equirectangular Projection）的图，通俗说法就是"展开的世界地图"。它把水平方向 360 度的经度均匀映射到图像的宽度上，把垂直方向 180 度的纬度均匀映射到图像的高度上。

这个映射带来一个直接的数学结果：宽高比必须是 2:1。因为水平 360 度对应宽，垂直 180 度对应高，360/180 = 2。所以你看到的所有标准全景底图，尺寸都是 4096×2048、8192×4096、16384×8192 这样的比例。如果哪天你拼出来的图是 8000×4000，那说明瓦片尺寸或者层级算错了一点点，横向少了一列。

等距圆柱投影有个明显的副作用：越靠近两极（图的上下边缘，也就是全景里的天顶和地面正下方），像素被拉伸得越厉害。同一块面积的画面，在赤道附近占的像素少，在两极占的像素多。这就是为什么很多全景图的天顶部分看起来糊、噪点多——不是渲染问题，是投影本身把那一小块像素摊大了一圈。理解这一点很关键，后面判断"这张图是不是被插值放大了"，就要看极区的像素密度。

2.2 立方体贴图：六个正方形面的另一条路线

还有一派用立方体贴图（Cubemap），把整个球面内容投影到一个立方体的六个面上，每个面是 90 度 × 90 度的正方形视野。这种格式在 GPU 渲染时效率更高，因为立方体面的采样是均匀的，不需要在极点做特殊处理。

立方体路线对下载拼接的影响很直接：你拿到的不是一张 2:1 的长图，而是六张正方形图（通常命名成 front、back、left、right、up、down 或者 0 到 5 的编号）。拼的时候不能简单横着接，得按立方体的展开图（常见是十字形或者 T 字形）摆放，再用工具转成等距圆柱，或者干脆六面一起打包成播放器认的格式。

判断你面对的是哪一种，有个土办法：看瓦片的宽高比。如果单个瓦片是正方形（比如 512×512），且整体拼出来是 2:1，那大概率是等距圆柱切分；如果发现瓦片集合天然分成六组、每组内部是个正方形网格，那多半是立方体路线。这一步判断错了，后面所有的坐标计算都会错位。

2.3 瓦片金字塔：为什么要分级，而不是一刀切

一张 16384×8192 的全景图，原始文件轻松超过 20MB。如果用户打开页面就下载完整一张，加载时间长、内存占用高，手机端直接卡死。所以几乎所有平台都用瓦片金字塔（Tile Pyramid）的方案。

金字塔的意思是：同一张图，服务端预先切出多个分辨率层级。层级 0 是最粗的，往往只有一两张瓦片，够你快速看到一张模糊的全局预览；层级 1 是它的两倍宽、两倍高；一直往上翻，最高层级就是原始分辨率。播放器根据当前视口大小、缩放程度、以及用户的网络状况，动态决定拉哪一层的哪些瓦片。

具体切法通常是这样的（以 512 像素瓦片、等距圆柱投影为例）：

看懂这张表，你就掌握了整件事的核心："下载高清原图"翻译过来，就是把最高层级的所有瓦片全部拉下来，按行列顺序拼回去。128 张或者 512 张，听起来多，但对脚本来说就是两层循环的事。

3. 三类平台的分片规则并不一样

3.1 全景托管类：最标准的 z/x/y 瓦片金字塔

全景托管平台和作品展示站是规则最规整的一类。它们的核心业务就是把用户上传的全景图切成瓦片、分发给播放器，所以路径结构往往是教科书式的：

/tiles/{场景ID}/{层级}/{行}/{列}.jpg

或者干脆对齐地图行业的惯例，用 z（层级）、x（列）、y（行）三个整数：

/tiles/{z}/{x}/{y}.jpg

这类平台通常还会提供一个场景配置文件（JSON 格式，或者一个被压缩过的 JS 变量），里面写着这个场景的总分辨率、瓦片尺寸、层级范围、初始视角。有些平台会把这个配置藏得比较深，但只要有播放器在工作，配置文件就一定会在网络请求里出现——没有它，播放器不知道去哪儿取图。

这类平台的另一个特征是：最高层级往往是完整切好的。因为服务端切片是离线批量跑的任务，不是实时生成，所以理论上每一个 (层级, 行, 列) 组合都对应一个真实文件。这对我们是好消息，意味着脚本不需要处理"某些瓦片 404"的复杂情况（除了边界情况，后面会讲）。

3.2 云设计类：先渲染出图，再打包分发

在线云设计工具（做户型、做样板间、做展厅效果的那一类）走的是另一条路。全景图不是用户直接上传的，而是软件根据三维场景实时渲染出来的。渲染完成后，服务端会把结果存成一张大图，然后再走切片流程。

这类平台的特征是：中间产物会以任务结果的形式暴露。你会看到类似/render/task/{任务ID}/result这样的请求，返回一个 JSON，里面有成品图的地址、分辨率、文件大小。如果这个地址直链可用，那是最省事的，直接下载一张完整的图就完事，根本不用拼。

如果没有直链、只有切片，那规则往往和 3.1 类似，但路径里会多带一层任务 ID 或者版本号。这类平台的坑在于：同一个场景反复渲染会生成多个版本的产物，你得确认自己拉的是最新那次、分辨率最高的那次，别把上周的预览版当成最终稿。

3.3 街景与地图类：多分辨率层级叠加空间索引

街景地图服务的复杂度最高。它不只是"把一张图切开"，还要处理连续移动、多段拼接、深度信息、以及全球范围的空间索引。请求参数里通常同时带着经纬度、朝向、层级，服务端根据这些参数返回当前视野最合适的那几张瓦片。

这类服务的路径往往不遵循简单的 z/x/y，而是带一堆 query 参数，比如x、y、level、scene之类的整数对。技术上讲依然可以按"层级 + 行列"的模型去理解，但你需要先确认三件事：一是层级编号是递增还是递减（有些服务 level 数字越大越模糊），二是瓦片是固定像素尺寸还是按视口动态变化，三是同一个位置是否有多套采集数据（不同年份的街景）。

街景类还有一个特殊之处：它的"原图"往往是多张鱼眼或者广角相机拼出来的，边缘有重叠区，平台做过融合。你想拿到"原始的那几张相机图"基本不可能，能拿到的是平台融合后的成品瓦片。心理预期要放对。

3.4 素材库类：预览图和源文件是两套体系

还有一类是设计素材库，里面既有全景素材，也有贴图、模型。这类站点的特点是：预览区跑的是压缩过的低分辨率版本，源文件需要单独的下载权限或者积分。你在页面上抓到的高清瓦片，可能只是"预览高清版"，真正标称的 8K 源文件在另一套存储里，路径完全不同。

判断方法很简单：把最高层级的瓦片全拼起来，看看总分辨率和页面上标注的规格对不对得上。对不上，说明你抓的还不是最终稿。

4. 动手前的判断：先找到"最高层级"藏在哪

4.1 从网络面板读出一张瓦片的身份

打开目标页面，按 F12 进开发者工具，切到网络面板，筛选图片类型（或者直接筛 XHR，有些平台用接口返回 base64 或者二进制）。然后在页面上慢慢拖动全景画面，转一圈，再缩放几次。

这时候你会看到一批请求刷出来。挑其中一张看它的完整 URL，重点看三段信息：路径里的数字、文件名里的数字、以及响应头里的内容类型。路径里的数字通常就是层级、行、列。文件名可能是0_3_5.jpg这种下划线分隔，也可能是z3_x5_y2.webp这种带前缀的。

一个很实用的技巧：只转水平方向，观察哪一个数字在变；再只转垂直方向，观察另一个数字怎么变。水平转动时变化的是列号，垂直抬头低头时变化的是行号。这样你就能在没有文档的情况下，反推出哪个位置是 x、哪个是 y。

还有一个技巧是看请求的触发时机。层级 0 的那张瓦片，通常在页面刚加载、还没开始渲染时就已经请求完了（用于显示模糊预览）。层级越高的瓦片，越是在你放大或者盯着某个方向看的时候才懒加载。所以你只要疯狂放大（如果播放器支持）或者把窗口拉大，就能逼出最高层级。

4.2 用配置文件反推总分辨率

找到瓦片还不够，你得知道最高层级是多少，否则循环写不出来。三个办法，按可靠性排序：

第一个办法是找配置文件。在网络面板里搜json、config、scene、pano这些关键词，找到那个描述场景的响应，里面通常有width、height、levels、tileSize之类的字段。有些平台会把配置塞进页面的一个全局变量里，在控制台输入window.然后按 Tab 看提示，运气好能直接看到。

第二个办法是试探。从当前看到的层级开始，往上加一级，随便请求一个瓦片，看返回是 200 还是 404。200 就继续加，404 就说明到顶了。这个方法很直接，但要注意别请求太猛。

第三个办法是看播放器的行为。有些播放器在左上角或者设置菜单里会显示"当前画质"或者分辨率信息，点开看一眼，能省不少事。

拿到层级 L 和瓦片尺寸 S 之后，总分辨率就能算出来：宽 = S × 2^(L+1)，高 = S × 2^L（针对等距圆柱切分）。比如 S=512、L=4，就是 512×32=16384 宽，512×16=8192 高。这个公式建议记牢，它同时也是你拼接完成后校验尺寸的依据。

4.3 先小批量验证，再全量开跑

不要一上来就写全量循环。先挑最高层级的四个角（左上、右上、左下、右下）各请求一张，确认都能拿到，并且尺寸一致。再挑中间一张，用图片查看器打开，看看画面内容对不对——有些平台的瓦片是带水印的、带 logo 的，或者边缘做了羽化处理，这些都会影响最终成品的观感。

这一步花不了五分钟，但能帮你避开后面最难受的一类问题：跑了半小时、下载了几百张、拼出来发现有半边是黑的。先验证再开跑，是所有批量操作的基本纪律。

5. 批量抓取与拼接：一条能跑通的脚本链路

5.1 下载脚本：限速、重试、断点续传三件事

下面这段是通用骨架，改改 URL 模板就能用。关键不在于代码多花哨，而在于三个工程细节：并发别太高、失败要重试、已下载的要跳过。

import os import time import random import requests LEVEL = 4 TILE = 512 COLS = 2 ** (LEVEL + 1) # 32 ROWS = 2 ** LEVEL # 16 OUT = f"tiles/L{LEVEL}" # 模板里的 {z} {x} {y} 换成你实际观察到的参数位置 URL = "https://example.com/tiles/{z}/{x}/{y}.jpg" HEADERS = { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "Referer": "https://example.com/", # 很多平台校验来源 } os.makedirs(OUT, exist_ok=True) def fetch(z, x, y, tries=3): path = os.path.join(OUT, f"{x}_{y}.jpg") if os.path.exists(path) and os.path.getsize(path) > 0: return True # 断点续传 for i in range(tries): try: r = requests.get(URL.format(z=z, x=x, y=y), headers=HEADERS, timeout=15) if r.status_code == 200 and len(r.content) > 100: with open(path, "wb") as f: f.write(r.content) return True if r.status_code == 404: return False # 真没有，别重试 except Exception: time.sleep(1 + i * 2) # 退避 return False for y in range(ROWS): for x in range(COLS): ok = fetch(LEVEL, x, y) if not ok: print(f"missing {x},{y}") time.sleep(0.05 + random.random() * 0.05) # 礼貌间隔

几个必须注意的点。Referer 头：不少平台在服务端校验来源页，头里没有对应域名会直接返回 403 或者一张错误占位图。这类失败往往返回 200，内容是张灰图或者 logo，光看状态码发现不了，所以下载完最好抽查几张。并发：别一上来开 32 线程，大多数平台对单 IP 有频率限制，开 4 到 8 个并发、加上几十毫秒的间隔，是最稳妥的节奏。文件大小校验：正常的 512 瓦片 JPEG 一般不会小于 3KB，如果某张只有几百字节，大概率是错误响应，要当失败处理。

5.2 坐标映射：行号从上往下还是从下往上

这是整条链路上最容易翻车的地方，也是我踩过最多次的坑。同样叫y，不同平台的含义可能完全相反：

• 从上往下（也叫 XYZ 风格，地图行业常见）：y=0 是最上面一行，也就是天顶。
• 从下往上（也叫 TMS 风格）：y=0 是最下面一行，也就是地面正下方。

如果搞反了，拼出来的图会是上下颠倒的——天在上变成了地在上的效果，极其诡异：抬头看见地板，低头看见天空。判断方法我在第 7 节会详细讲，这里先记住：这个开关一定要做成参数，别硬编码。

from PIL import Image def build(level, tile=512, flip_y=False, out="pano.jpg"): cols = 2 ** (level + 1) rows = 2 ** level canvas = Image.new("RGB", (cols * tile, rows * tile), (0, 0, 0)) miss = 0 for y in range(rows): for x in range(cols): p = f"tiles/L{level}/{x}_{y}.jpg" if not os.path.exists(p): miss += 1 continue # 留黑，后面统一检查 img = Image.open(p) if img.size != (tile, tile): img = img.resize((tile, tile), Image.LANCZOS) row = rows - 1 - y if flip_y else y canvas.paste(img, (x * tile, row * tile)) print("missing:", miss, "size:", canvas.size) canvas.save(out, quality=95, subsampling=0) return canvas

注意subsampling=0这个参数。JPEG 默认会对色度通道做下采样（把 4:2:0 或者 4:2:2 的色度信息丢掉一半），这本身是为了减体积。但如果你是分块拼接、每块独立编码，色度下采样会让接缝处的颜色产生细微断差。存成 4:4:4 可以明显改善这个问题，代价是文件变大。

5.3 成品校验：三个必看的指标

拼完之后别急着交付，先做三件事。

第一，看尺寸。必须是 2:1，且等于你按公式算出来的值。差一点点，比如 16384×8190，那就是某些瓦片高度不标准，被 resize 拉过。

第二，看空洞。如果脚本报告 missing 大于 0，说明有位置没下到。这时候不要直接用黑块交付，先确认那几块是不是真的不存在。最常见的情况是：最后一列或者最后一行根本不存在。因为总像素数不一定能被瓦片尺寸整除，比如宽度 8190 像素、瓦片 512，最后一列只有 510 像素宽，有些平台会选择把最后一列裁掉不生成，播放器渲染时靠拉伸补齐。这种情况下的正确做法是把倒数第二列复制一点、或者做轻微放大，而不是留黑条。

第三，看颜色。把整张图缩到屏幕大小通览一遍，找有没有明显偏色的区块。如果有，通常是某个瓦片请求返回了错误内容，或者跨域请求被替换成了占位图。逐块对比 RGB 均值能快速定位。

6. 从相机到浏览器：画质到底在哪几层被削掉了

6.1 上传时的二次压缩与分块编码

很多人以为"下载平台原图"就等于"拿回拍摄时的原始画质"，这个预期需要修正。一条典型的链路是这样的：

拍摄阶段用多机位环形拍摄，或者鱼眼镜头拍三到六张，然后用软件做特征匹配、融合、投影变换，输出一张 8000×4000 左右的等距圆柱底图。这一步已经做过一次重采样了，因为多张鱼眼投到同一个圆柱面上，必须做插值。

上传到平台后，平台通常会再压一次。有些平台会限制上传文件大小，超过就自动降质；有些平台会统一转成特定质量参数的 JPEG；还有些平台会限制最大边长（比如强制压到 8192 以内）。这一步的损失往往是最隐蔽的，因为用户端看不出来。

切片阶段再做一次独立编码。每一张 512×512 的瓦片单独走 JPEG 编码，而 JPEG 是按 8×8 或者 16×16 的宏块做 DCT 变换的。瓦片边界上的宏块，它的邻域信息被切断了，压缩时只能靠自己那半边数据做预测，误差就体现在接缝上。这就是为什么你拼出来的图，在瓦片交界处偶尔能看出一条淡淡的竖线或者横线。

6.2 "高清"两个字的水分：怎么识别插值放大

不是所有标着高清的全景图都真的高清。有些平台因为存储成本，会把底图压到 4096×2048，但为了让放大后不至于太糊，在更上层的瓦片里做了插值放大——你拿到的 8192×4096 其实是 4096×2048 拉出来的，细节并不会增加。

识别方法有三个，都很实用。

看极区噪点。前面说过，等距圆柱投影在两极会把像素拉伸。如果底图本来只有 4K，拉到 8K 之后，天顶区域会呈现出一种特征性的"糊成一片"的效果——不是锐利的噪点，而是像被水彩晕开的团块。真正的 8K 底图，即使在天顶，也能看到相对清晰的纹理边界。

看高频细节。挑一张图里有密集纹理的区域（书脊、瓷砖缝、树叶、金属网格），放大到 100% 看。真高清会有清晰的边缘，伴随轻微但真实的锐度；插值放大的会有明显的振铃（边缘两侧出现亮暗环）和块效应。

比文件体积。同样 16384×8192 的图，真高清的 JPEG 往往在 20MB 以上，插值放大的可能只有 6 到 8MB。因为信息量少，压缩效率高。这个判断不绝对，但作为辅助很有效。

6.3 接缝处理的两种手法

如果你的成品要交付给客户、或者要印在展板上，瓦片接缝是需要处理的。两种思路，按需选。

一种是"以质换净"：拼接时不用平台给的 JPEG，而是先把瓦片解码成位图，做一次轻微的高斯模糊（半径 0.3 到 0.5 像素）让接缝两侧的量化误差被抹平，然后再统一编码成 PNG 或者高质量 JPEG。副作用是整体锐度会掉一点点，但接缝基本消失。适合对连续性要求高的场景，比如长走廊、纯色墙面。

另一种是"局部修补"：只针对检测到的接缝做处理，判断逻辑是——沿每一列（或行）的边界，计算两侧像素的亮度差，如果差值的绝对值连续超过阈值，就把这一列往两侧各扩 1 像素，做线性插值。这个方法保留了绝大部分区域的锐度，只修有问题的地方，实现起来稍复杂但效果好。

注意：不管用哪种方法，都要在无损或高质量格式下做，不要拿已经压过的 JPEG 反复解码编码。JPEG 是有损格式，每存一次都会掉一层质量，三五次之后画面会出现明显的色块和蚊状噪点。

7. 一次拼接错位的完整排查记录

说个真实遇到的情况，我觉得比任何教程都更能说明问题。某次帮一个团队处理一套室内全景，流程走得很顺，瓦片全下齐了，128 张一张不缺，脚本跑完生成的图尺寸也对，16384×8192，看着挺完美。打开一看，整张图上下颠倒了——天花板的灯槽在下面，地砖在头顶。

第一反应是 y 轴方向搞反了。改flip_y=True重跑，结果变成另一种错乱：图不颠倒了，但上下两半内容重复了。这就不是简单的翻转问题了。

第二步排查，怀疑是行数算错。重新数了一遍，rows=8、cols=16，跟公式对得上。又去页面里逐个观察请求，发现一个细节：当我把视角抬到最高（看天顶）时，请求的行号是 0；压到最低（看地面）时，请求的行号是 7。也就是说这个平台的 y 确实是从上往下的，不需要翻转。那为什么翻转和不翻转都出问题？

第三步，把不翻转的版本重新检查了一遍。这次学乖了，不是看整图，而是把每一行单独切出来看内容。结果发现：第 0 行和第 7 行的内容高度相似，都是天花板的纹理；第 3 行和第 4 行也都是地面附近的内容。这下清楚了——瓦片本身没问题，是我下载的时候把行号理解成了纵向坐标，而这个平台的 y 其实是"第几圈"，一圈里包含多个方向的瓦片。

第四步，重新读网络请求。仔细看 URL 结构，发现路径是/pano/{场景}/{层级}/{批次}/{序号}.jpg，四个数字。我一开始把前两个当成行列，实际是后两个才是。前面那个数字是"面"的编号（立方体六面），不是行号。

第五步，改成按面分组下载、每个面内部再按序号排布，拼成六个正方形，再用工具转成等距圆柱。这次出来的图完全正确，接缝也对得上。

这个坑给我的教训有三条，都很实在。一是别急着相信自己对参数含义的第一判断，路径里的数字顺序和实际含义没有必然关系，必须用"改变视角看哪个数字动"的方法验证。二是拼接前先按行、按列抽样看内容，不要整张拼完再看，那样很难定位。三是当翻转和不翻转都不对时，说明模型本身错了，不是参数错了，这时要退回去重新理解数据结构。

还有一个衍生的坑值得提一句：那套图的最后一列（第 15 列）请求全是 404。我一开始以为是权限或者限流，加了重试、换了 UA、试了 Referer，全没用。后来发现总宽度是 8160 而不是 8192，最后一列只有 480 像素，平台直接没生成。处理办法是把第 14 列的右边缘裁 32 像素宽的一条，拉伸补到第 15 列的位置——因为那 32 像素在几何上覆盖的角度，和缺失的 32 像素是一致的，拉伸基本看不出来。

8. 动手之前，先把这几条边界想清楚

技术上能做的事，和该做的事，中间隔着一条线。这条线在全景图这件事上特别需要说清楚，因为全景作品绝大多数是有明确归属的——要么是摄影师的作品，要么是甲方的商业空间，要么是平台的付费素材。

第一条，先确认你手里的素材归谁。自己拍摄、自己账号上传的，处置权在你，备份、转存、二次加工都没问题。给别人做的项目，交付条款里写没写"提供原始文件"、写没写"允许本地存档"，这些要提前对齐。没有明确约定的，先问一句，比事后解释省事得多。

第二条，平台的用户协议值得花十分钟读一遍。有些平台明确写了允许作者导出自己上传的原始文件，有些则规定所有上传内容的使用范围仅限于平台内展示。这两者的差别很大，而协议文本通常就在页脚，点两下就能看到。

第三条，别人的作品不要碰。这个不用多解释。全景图是有著作权的摄影作品，抓取他人作品用于任何用途，都不在"技术学习"的豁免范围内。

第四条，抓取行为本身要有节制。哪怕是自己账号下的内容，也别开几十个并发去轰服务器。限速不仅是为了不被封，也是基本的网络礼仪。几百张瓦片、每张间隔几十毫秒，几分钟就跑完了，没必要抢那几十秒。

我个人的习惯是：凡是这类批量操作，先在笔记里写一行"素材来源 + 授权情况 + 用途"，再动手。这行字花不了十秒钟，但将来有人问起来，或者在某个需要自证的场合，它能省掉很多麻烦。技术上的坑可以靠调试解决，归属上的坑一旦踩了，是没有回滚按钮的。