跳到主要内容

Reality

Reality Skill 把拍摄素材上传到云端,重建为 3D 高斯模型。不必懂参数:说清素材和目标就能开始;想控效果,也能在提交前调帧率、分辨率、训练量与高斯上限。效果不理想时有人带着调,调不动还能把问题反馈给 Aholo 团队。

输入与输出 · 用户优势 · 下载与安装 · 使用说明 · 常见问题

输入与输出​

照片适合静物与空间;普通视频适合边走边拍;360 视频一次覆盖更大范围。上传后都在同一个项目页里看进度、看模型。

入口格式数量 / 抽帧适用
照片目录JPEG / PNG / WebP / HEIC / HEIF≥ 12 张,典型 50–300场景 / 物体
普通视频MP4 / MOV / MKV 等默认 5 fps(0.5–60)室内 / 室外 / 物体
360 视频.insv / .osv镜头边长默认 2560 px仅场景任务
禾赛扫描工程Kosmo One 完整工程目录单个或多个有重叠的工程扫描仪采集的场景
  • 照片:同一场景或物体的重叠照片,直接放进一个目录。物体任务加 --mode object。若某张 HEIC/HEIF 提示暂时无法解码(held),将该照片导出为 JPEG 后替换目录里的原图。素材变更后,用新的 --out 提交。
  • 普通视频:按 --fps 抽帧后重建。同一地点的多段素材可重复 --video 一起提交。
  • 360 视频:Insta360 .insv 或 DJI Osmo 360 .osv 原始素材,服务端自动解码与标定。
  • 禾赛:用 --hesai 工程目录 导入完整的 Kosmo One 工程。多个工程可用 --hesai 工程A 工程B 一起导入,使用扫描仪的训练配置。

输出:scene.spz(Web 查看器优先)、point_cloud.ply(标准 3DGS PLY),以及在线项目页(进度与模型都在这里)。多个禾赛工程的分块成果为 scene.zip 和 point_cloud.zip。

原始 INSV/OSV 只支持场景;若目标是单个物体,请先导出透视视频或多视角照片。模型是高斯特征,不是三角网格;仅凭图像得到的尺度是相对的。

用户优势​

从第一次上手到最后一版交付,Skill 在每一步都给出可解释的选择和可回退的路径,也把真实使用中的问题实时回流给团队。

  • 不懂参数也能开始:先说明素材和拍摄目标;不选参数就使用默认值,减少启动门槛。
  • 有经验可以提前控效果:重建前可选择帧率、分辨率、训练量、高斯上限等,并了解各自的用途和代价。
  • 物体与场景更清楚:提供室内 / 室外 / 物体入口,明确不同素材支持的重建方式,不把 360 原始素材误当物体任务。
  • 效果不好有人带:从主体缺块、边缘重影、纹理模糊、中心位置异常等现象出发,给出适用的检查与调参方案,而不是丢一句“重跑一次”。
  • 减少盲目重跑:先检查原任务的蒙版与相机信息;需要重训时每轮只改一项,更容易判断哪项真正有效(见效果调优)。
  • 反馈重建结果:经你同意后,Skill 可以提交问题描述、关联任务和你选定的截图,并返回反馈编号和查看回复的入口(见反馈团队)。

下载与安装​

以下两种方式均安装 OpenAPI v2 版 Skill。

方式 A(推荐):把这段话发给你的 AI 助手​

它会读取安装说明,下载并解压安装包、检查 Python 依赖、完成连接测试。如果没收到 .md,提示词里也带了安装包地址。

请阅读 install.md,按说明帮我安装或更新 aholo-reality-skill。
如果没收到这个文件,请直接下载并解压下面的安装包,阅读其中的 SKILL.md 后完成安装:
https://www.aholo.cn/holo-web-scan/skill-preview/aholo-reality-skill.zip
用开放平台 API Key 连接,网关为 https://api.aholo.cn/web-scan/v2。安装包所在目录就是登录命令的 --package-source。

下载安装说明 .md 下载后把 .md 拖进对话,或直接发送上面的提示词。

方式 B:手动安装 / 更新​

项目说明
安装包aholo-reality-skill.zip
版本见安装包中的 VERSION
包含SKILL.md · VERSION · scripts/
依赖Python 3.9+ · requests

下载 OpenAPI Skill 包 (.zip)

  1. 解压并放置:解压后得到 aholo-reality-skill/ 目录,放入智能体读取的技能目录。Claude Code 全局 ~/.claude/skills/、项目级 .claude/skills/;Codex 常用 ~/.codex/skills/。
  2. 安装依赖:需要 Python 3.9 或更新版本,以及 requests。如果使用自己的虚拟环境,先确认再安装。
  3. 检查连接:首次使用按下方命令登录开放平台,再运行 check。
  4. 开始使用:在对话里描述素材和目标,或直接运行 run 命令。技能只在启动时加载的客户端,下个会话生效。

在 管理 › API keys 创建平台 API Key。

# macOS / Linux:安装依赖,首次登录时按提示输入密钥,再检查连接
python3 -m pip install requests
python3 ~/.claude/skills/aholo-reality-skill/scripts/aholo_reality.py login --site https://reality.aholo.cn/holo-web-scan --api-base https://api.aholo.cn/web-scan/v2 --package-source https://www.aholo.cn/holo-web-scan/skill-preview
python3 ~/.claude/skills/aholo-reality-skill/scripts/aholo_reality.py check
# Windows PowerShell
py -m pip install requests
py "$HOME\.claude\skills\aholo-reality-skill\scripts\aholo_reality.py" login --site https://reality.aholo.cn/holo-web-scan --api-base https://api.aholo.cn/web-scan/v2 --package-source https://www.aholo.cn/holo-web-scan/skill-preview
py "$HOME\.claude\skills\aholo-reality-skill\scripts\aholo_reality.py" check

登录凭证只保存在本机 ~/.aholo-reality/ 下的登录文件,不会写入页面或仓库。

使用说明​

下面按真实使用顺序展开。命令里的技能路径按你的安装目录替换;所有示例都可以直接交给智能体执行。

1. 先连接,之后复用同一份登录​

每个对话的第一次重建前运行 check。已有有效登录会直接复用,不要求每次调用或每个对话重填 API Key;它会验证网络、凭证和客户端版本。发现官方更新时会先问你是否更新,不会直接覆盖你的定制。

# 已连接时输出示例
$ python3 scripts/aholo_reality.py check
Connected to https://reality.aholo.cn/holo-web-scan (aholo-reality-skill <VERSION>).

首次连接开放平台时,到 管理 › API keys 创建平台 API Key。登录方式由你选择。

  • 你在终端登录:在用户自己的终端运行下方登录命令,通过隐藏提示输入密钥,不需要把 key 发到对话里。
  • 授权 Agent 代登录:你在聊天里明确提供 key 并要求连接时,Agent 可以代为登录;优先通过 --key-stdin 从标准输入传入,避免放在命令行参数里。
# 用户在终端登录(隐藏输入)
python3 scripts/aholo_reality.py login --site https://reality.aholo.cn/holo-web-scan --api-base https://api.aholo.cn/web-scan/v2 --package-source https://www.aholo.cn/holo-web-scan/skill-preview

# Agent 代登录:用户明确提供 key 后,由标准输入传入
python3 scripts/aholo_reality.py login --site https://reality.aholo.cn/holo-web-scan --api-base https://api.aholo.cn/web-scan/v2 --package-source https://www.aholo.cn/holo-web-scan/skill-preview --key-stdin

登录后,平台密钥保存在当前系统用户的 ~/.aholo-reality/openapi-credentials.json。同一个操作系统账号会共享默认登录,多人共用时请各自使用自己的账号,或用 --credentials 指定独立的凭证位置。

**真实密钥不要写进 SKILL.md、脚本、反馈内容、ZIP 或仓库。**聊天和工具历史可能已记录你发过的 key,不要声称标准输入不会留日志;代登录产生的临时文件完成后及时清理,但不要删除需要复用的凭证文件。

2. 选择素材入口,提交第一版​

照片用目录;普通视频用 --video,可以重复传同一地点的多段;360 原始素材用 --insv。视频任务用 --preset indoor 或 --preset outdoor 选择场景预设;普通视频物体用 --mode object。

照片

python3 scripts/aholo_reality.py run ~/Pictures/living-room \
--name "客厅" --out ~/aholo/living-room

物体照片加 --mode object;需要指定主体时,用 --object-image 与归一化 --object-box 配套选框。

普通视频

python3 scripts/aholo_reality.py run \
--video clip1.mp4 --video clip2.mp4 \
--preset outdoor --name "花园" --out ~/aholo/garden

普通视频支持物体入口:--mode object。单段最大 64 GiB;多段视频会一起参与同一次重建。

360 视频

python3 scripts/aholo_reality.py run \
--insv VID_0001.insv --preset indoor \
--name "客厅 360" --out ~/aholo/hall-360

原始 INSV/OSV 只支持场景。若目标是单个物体,先导出透视视频或多视角照片,再走普通视频 / 照片路径。

3. 参数:不选就用默认,想控再展开​

首轮不需要逐项回答。下面这些项只在当前素材支持时出现;你指定了就用你的值,没指定就按默认。Skill 不会把参数表变成问卷。

下表列出未指定预设时的默认值。使用 --preset 时按所选预设取值,显式传入的参数优先。

参数适用输入默认可选项与说明
--fps普通视频、INSV/OSV5可选 2 / 5 / 10 或自定义 0.5–60;更密抽帧会增加输入数量。360 素材单位为每秒帧对。
--image-size普通视频 / INSV、OSV源分辨率 / 2560视频:最长边 480–8192,不能超过源尺寸;360:镜头边长 2560 / 3840 或 480–8192 偶数,实际不超过源尺寸。
--steps / --epochs照片、普通视频、360服务自动自定义步数 1000–1,440,000,或轮数 1–1,440,000;两项互斥。增加训练量通常耗时更多。
--max-gaussians照片、普通视频、360400 万可选 400 / 800 / 1500 万,或 10–1500 万之间的整数。上限不是实际点数;增大可能增加耗时与文件大小。
--keep-people照片、普通视频、360不启用目标含雕像、人偶、画中人物时可选保留,避免目标被人物遮蔽处理误删。
对象选框物体照片自动选主体提供 --object-image 与归一化 --object-box 配套选框;视频不提供这项。

**提交前会复述本轮最终参数。**例如普通视频:“本轮默认 5 fps、源分辨率、服务自动训练、400 万高斯上限。你也可以指定帧率、分辨率、训练量或高斯上限;未指定项保持默认。”

后续调优仍遵循“每轮只改一项”;首轮同时指定多个启动参数可以一并采用并记录,但比较实验时只动一个变量。

4. 提交后:先看预计时间,再在线验收​

创建项目后立即给出 Scene page: 链接。优先读取该任务线上页面显示的“预计还需”和排队估时,转述成具体分钟 / 秒;两者不相加,也不把轮询超时、已用时间或训练步数当成估时。

情况Skill 会这样说
有剩余估时“Aholo 后台预计还需 8 分 20 秒。”这是剩余时间,不是从提交起的总耗时。
只有排队时间“预计排队等待 3 分钟。”明确标注是排队,不冒充重建耗时。
读不到估时按任务实际状态报告,例如“正在训练,后台暂无剩余时间估计”。

完成后仍在同一项目页验收:从固定视角看主体是否缺块、边缘是否重影、纹理是否清楚、中心位置是否异常。物体在 Look / Orbit(转向 / 环绕)切到“环绕”,再拖动旋转、滚轮缩放。不要为了观看先下载模型或打开本地 HTML。

5. 用截图描述问题​

截图由当前 AI 助手查看。能否分析图片取决于该会话的图像输入能力。助手无法查看时,请用文字描述观察视角、问题位置和期望效果。你也可以只提交文字反馈。

6. 效果不理想:先检查,再一项一项改​

首轮交付后,Skill 会先问“这版可以交付了吗?如果要改,最想改善哪一处?”,不会根据任务成功状态推断画质,也不会自动开始第二轮。之后的顺序是:描述一个现象 → 先查蒙版 / 相机 → 每轮只改一项 → 同视角对比 → 保留 / 回退 / 结束。

缺块、主体选错时,先复用原任务加 --include masks 检查蒙版;怀疑位姿问题,检查 --include cameras。能靠诊断解决就不重训,检查本身也不算一轮调优。

  • 增加训练量:输入和目标正确后,纹理或边缘仍不理想:在上一版实际步数基础上增加,例如 40,000 → 60,000 步。训练更久,不保证更好;--steps 与 --epochs 二选一。实际步数未知时,用服务预算和训练图片数估算并标明是估算。
  • 提高高斯上限:保持已选训练预算和输入不变,把容量上限从 400 万提到 800 万,再按需试到 1500 万。上限是允许的容量,不是实际数量;未用满时可能没有变化,耗时和模型大小可能增加。

两项都想试时,先只增加训练量,比较并选定版本后,下一轮才只提高上限。每次训练用新的 --out,例如 trial-01-fps10;调整无效就先退回,再试下一项。

7. 仍不满意:把问题反馈给团队​

需要团队协助时,把问题出现的位置、视角、已尝试的设置告诉助手。你同意提交后,Skill 会将问题描述与项目和任务编号一起发送,返回反馈编号和查看回复的页面。可以仅发文字,或附上你选定的最多 6 张 PNG、JPEG 或 WebP 截图。

要先审核正文和附件,可像下面的示例一样明确要求助手先展示草稿,等你确认后再发送。提交和补充消息需要写权限。

可以把下面这段话发给智能体。它会按已安装包的 SKILL.md 使用该版本的反馈命令。

帮我给团队反馈:书架右侧缺了一层。先把草稿和要附的截图给我看,等我确认再发。发送后把反馈编号和查看回复的链接给我。

补充同一问题时,把反馈编号和补充内容交给智能体,确认后回复原反馈。也可以在网页「意见反馈」查看进度和回复。

8. 对比候选,由你定版​

对实际完成的候选版本列一张简表:版本、相对保留版改了什么、同一视角的观察、已知耗时或大小、预览入口。首轮也列入候选;无法观察或未测量的写明“未知”。你可以保留新版、退回旧版或停止调优。Skill 根据你的优先级给出理由,再由你选择交付哪个版本;交付所选版本的在线链接、文件与复现参数,其他实验保留。

OUT/<reconstruction>/<job>/
├── scene.spz # 紧凑,适合 Web 查看器
├── point_cloud.ply # 标准 3D 高斯 PLY
├── scale.json
└── receipt.json

模型是高斯特征,不是网格;需要网格时应在下游另行处理。仅凭图像得到的尺度是相对的,需要绝对尺寸时应在拍摄或下游环节补充参照。

常见问题​

先看这里能否解决;仍然卡住时,把终端报错原文和当前任务的项目页链接一起发给智能体。

需要本地显卡吗?

不需要。重建在 Reality 云端完成;本机只运行 Python 客户端,负责上传、轮询进度和下载结果。网络稳定比显卡更重要。

模型是什么格式?能直接进建模软件吗?

输出是 3D 高斯 Splatting:scene.spz 适合 Web 查看器,point_cloud.ply 是标准高斯 PLY,不是三角网格。仅凭图像得到的尺度是相对的;需要绝对尺寸时,应在下游补充参照。

360 原始视频能重建物体吗?

不能。原始 INSV/OSV 只支持场景任务。物体请先导出透视视频或多视角照片,再走普通视频或照片入口;不要把 360 原始素材静默提交成场景。

API Key 放在哪里?安全吗?

平台密钥保存在本机 ~/.aholo-reality/openapi-credentials.json。你在聊天中明确提供 key 并要求连接时,Agent 可以代登录,优先通过 --key-stdin 从标准输入传入;聊天和工具历史可能已记录密钥,不要重复粘贴。不要把 key 写进 SKILL.md、脚本、反馈内容、ZIP 或仓库;泄漏后到 管理 › API keys 重新创建。

更新 Skill 会覆盖配置吗?

只会替换 aholo-reality-skill/ 目录;API Key 在 ~/.aholo-reality/ 下,不受影响。check 发现官方更新时会先询问,不会直接覆盖你的定制;更新后重新运行 check 验证连接和版本。

Skill 能直接看我的截图吗?

请先确认当前助手能否查看图片。它无法查看时,用文字描述问题部位和观察视角;提交反馈时只附你选定的截图。

效果一直不好怎么办?

先按参数路线检查蒙版 / 相机、帧率 / 分辨率、训练量与高斯上限。仍无改善,或你明确要求时,可以让 Skill 把问题反馈给 Aholo 团队:可以要求助手先展示正文、截图和关联任务。你同意后再提交;提交需要写权限,成功后返回反馈编号,可在网页“意见反馈”查看团队回复。

任务中断或超时怎么办?

用完全相同的命令和原 --out 重跑:会从断点续传,不会重复上传或新开任务。只有新的实验才使用新目录。

为什么页面上没有“预计还需”?

后台并非每个任务都提供可读取的估时。此时 Skill 会明确说明不确定性,并继续按任务进度更新,不会把轮询超时、已用时间或训练步数当成估时。

安装后智能体没发现 Skill?

多数客户端只在启动时加载技能;安装后开一个新会话。确认目录结构是 <技能目录>/aholo-reality-skill/SKILL.md,而不是多套了一层解压目录。

排错速查​

提示处理
401 / 密钥无效或过期重新创建平台 API Key,并用第 1 步的 OpenAPI 登录命令再登录一次。
403 / 访问被拒绝确认平台 API Key 对应的站点和接口权限。
输出目录属于不同输入换一个新的 --out 目录;旧的续传状态不能复用。
有效图片不足 12 张增加照片,或对短视频提高 --fps。
提示更新客户端先征得你同意,再按安装说明更新技能。
反馈发送 401 / 403确认所选连接的密钥与目标环境;保留草稿,重新连接后再发。
反馈 404 / 405反馈接口尚未发布或站点不支持;保留草稿,走网页“意见反馈”。
反馈截图超过 6 张或格式不符最多 6 张 PNG / JPEG / WebP;也可仅提交文字。
网络错误 / 超时用原命令、原 --out 重跑,自动续传。

开发指南 · Reality 接口参考