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 |
- 解压并放置:解压后得到
aholo-reality-skill/目录,放入智能体读取的技能目录。Claude Code 全局~/.claude/skills/、项目级.claude/skills/;Codex 常用~/.codex/skills/。 - 安装依赖:需要 Python 3.9 或更新版本,以及
requests。如果使用自己的虚拟环境,先确认再安装。 - 检查连接:首次使用按下方命令登录开放平台,再运行
check。 - 开始使用:在对话里描述素材和目标,或直接运行
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/OSV | 5 | 可选 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 | 照片、普通视频、360 | 400 万 | 可选 400 / 800 / 1500 万,或 10–1500 万之间的整数。上限不是实际点数;增大可能增加耗时与文件大小。 |
--keep-people | 照片、普通视频、360 | 不启用 | 目标含雕像、人偶、画中人物时可选保留,避免目标被人物遮蔽处理误删。 |
|