Skip to content
Shuang-suPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Metaflow

Metaflow 把基于 SuperSplat 的 Editor、资源索引和定制 Viewer 组合成一条 3D Gaussian Splatting 编辑、发布与分享链路。

Metaflow 是围绕 3D Gaussian Splatting(3DGS)的产品与工具体系,覆盖资产处理、模型编辑、场景编排、浏览分享和摄影成片,并延伸到原生客户端与研究内容。各产品按自己的成熟度提供入口,围绕适用资产、场景和机位协作。

在线 Viewer · 在线 Editor · ACG Director 实验 · 中文文档 · 开发与验证

产品全景

产品划分沿用 MF-100 八产品规划。下表区分正式发布、线上实验、本地成果与规划;详细职责见 项目概览。

产品 用途 当前状态 从哪里进入
Viewer 浏览、漫游、嵌入与分享 3DGS 场景 已发布 在线体验 · 快速开始
Editor 模型清理、裁剪、变换、调整与导出 已发布 在线编辑 · 使用与开发
Convert 转换、压缩、LOD 与体素/碰撞等处理 已有 CLI 与工具工作;独立产品入口尚未形成 工具仓库
Manage 资产引用、草稿、版本、标签与发布管理 规划中 首期定义 MF-98
Studio 标点、相机、动画、环境与展示编排 已有本地原型与内部交付;尚无正式公开入口 产品与原型 MF-58
Director 取景、镜头、景深、照片与视频输出 已上线限定 ACG 实验入口;完整摄影研究继续 摄影体验 · 范围 MF-106
App 原生设备上的场景浏览、输入与应用生命周期 HarmonyOS 阶段实现;完整发布验收未完成 NextNews 原生端 · 后续验收 MF-102
Daily 论文、工具与研究内容归档 内容仓库可用;门户建设另行推进 高斯日报 · 门户任务

扩展与插件方向

Nav、粒子开场、动态大气和 XR 是服务于产品的扩展方向。各方向分别推进研究、原型与接入;通用插件运行时、开发者 SDK 和分发机制仍待后续决策。App 是独立原生产品,扩展进入原生端时需要单独声明支持范围。

方向 目标职责 进展入口
Nav 导览 Studio 配置目的地与展示内容,Viewer 提供路线、地图与导览交互 MF-97
粒子开场 协调加载反馈、实时揭示与适用工具的确定性视频输出 MF-49 · MF-57
动态大气 分阶段研究天空、天气与场景光照响应 MF-52
XR 大空间 研究沉浸浏览、设备输入与碰撞协作,按真实设备验收 MF-70

产品如何协作

下图表示产品职责和目标交接关系;各条交接的实现与兼容范围以对应产品记录为准。虚线表示可选纳管、研究输入或仍需独立验收的交接。各工具可直接接收适用输入,Manage 和账号服务不是本地核心工作流的前置条件。

flowchart TB
    Edit["Editor / Convert"] --> Assets["模型与适用配置"]
    Assets --> Viewer["Viewer:浏览分享"]
    Assets --> Director["Director:摄影"]
    Director --> Media["照片 / 视频"]
    Assets -.-> Studio["Studio:展示编排"]
    Studio -.体验配置.-> Viewer
    Assets -.原生支持范围.-> App["App:原生浏览"]
    Studio -.体验配置.-> App
    Manage["Manage:资产与发布"] -.引用与版本.-> Assets
    Daily["Daily:研究内容"] -.研究输入.-> Edit
Loading

已落地的 Editor → 模型/settings → 资源索引 → Viewer 链路见 从 Editor 到 Viewer。跨产品资产、作者工程、体验与发布的责任由 MF-99 继续梳理;各工具保留自己的工程与支持范围。

项目入口

入口 用途
中文文档总入口 快速开始、操作指南、概念、参考与维护
Viewer 快速开始 本地运行 Viewer 与打开 route
Editor 快速开始 本地运行当前 Editor 源码
Editor 到 Viewer 导出模型/settings 并进入稳定路由
资源索引参考 data/index.json schema 与生成规则
兼容边界与版本事实源 Viewer、Editor、index、上游与发布事实从哪里读取
版本与发布 SemVer、Version History 与 Ledger 的更新边界
部署 Viewer、data 与 Editor 镜像怎样进入 Netlify publish 目录
仓库地图 活跃源码、生成物与历史快照边界

当前发布恢复基线

历史记录: 本节保留此前的恢复基线与发布过程,包含当时的版本和资源数量;最新发布值见下方当前版本。

产品 当前版本 上游基线 唯一事实来源
Viewer 5.21.10 / package 5.21.10 SuperSplat Viewer 1.35.2 / PlayCanvas 2.22.4 metadata/version-history.json
Editor 1.1 / app 1.1.0 SuperSplat Editor 2.28.0 metadata/editor-version-history.json
资源索引 schema 1.2 不适用 data/index.json

Viewer 源码在 metaflow-viewer/;Editor 源码在 supersplat-v2.28.0/,metaflow-editor/ 是发布构建。MF-30 的 v1.29.1 运行时产品 SHA 为 26e311c,5.19.2 analytics/release 修复 SHA 为 92d11b0。viewer-v5.19.0 的 prepare 在部署前失败且生产从未切换;viewer-v5.19.1 已通过 D2 Prepare、精确 D2 CLI/API 生产发布、真实浏览器 smoke 与 15 分钟观察;5.19.2 进一步恢复 production endpoint 并加入发布前/后校验,此前生产稳定版为 5.19.3,MF-81 已发布 3 组芒种和 9 组 SZTUCCF260919 ACG,索引共 99 项;见 发布核验。当前集成版本为 5.21.10;MF-139 修复 Safari 深层路由启动并调整加载信息,发布状态见 MF-139 核验。既有 ACG Director 实验入口见 MF-106。贡献与变更流程见 CONTRIBUTING.md 和 MCL v1.0 candidate。

下方保留原有 Viewer 快速参考,方便已有读者继续使用;新的分层手册和当前契约以 docs/README.md 为入口。

快速开始

在线体验

  • 浏览场景: 打开 Viewer 示例,或使用已登记的资源链接。
  • 编辑模型: 打开 Editor,操作与导出说明见 Editor 快速开始。
  • 拍摄与成片: 打开 缇宝 ACG Director。实验入口要求 WebGPU 和浮点渲染能力,仅支持已发布 ACG 单文件 SOG/PLY 及已声明环境;流式资源与任意远程模型地址不在该入口范围内。

本地运行 Viewer

在仓库根目录开始,使用 .nvmrc 指定的 Node.js 20.19.0 和 npm。运行实际资源前需准备对应 Git LFS 对象;模型下载前检查磁盘空间,只做界面开发无需拉取全部资源。

cd metaflow-viewer
npm ci
mkdir -p public
# 仅在没有文件、目录或符号链接时创建,保留已有 public/data
if [ ! -e public/data ] && [ ! -L public/data ]; then
  ln -s ../../data public/data
fi
npm run build
npx --no-install serve -s public -l 3000

然后打开 本地示例。-s 提供深层资源路径所需的 SPA fallback;若已有 public/data,请确认它指向所需数据,失效链接需单独处理。完整准备和持续构建见 Viewer 快速开始。Editor 与 Director 分别按 Editor 指南 和 Director 构建说明 运行。

原有 Viewer 启动步骤

上方为最小启动路径,下面为原有展开步骤,选择一套执行即可。

以下保留原有展开步骤;已有 public/data 时应跳过其中的 ln -s,或使用上方带存在性检查的命令。

# 进入 Viewer 包
cd metaflow-viewer

# 安装依赖
npm ci

# 首次需要读取仓库 data/ 时建立本地链接(public/data 不存在时执行)
mkdir -p public
ln -s ../../data public/data

# 构建项目
npm run build

# 用 SPA fallback 启动服务器,稳定 route 才不会直接 404
npx --no-install serve -s public -l 3000

服务器将在 http://localhost:3000 启动。

ACG Director 实验入口

本节保留早期入口说明与构建步骤;字体、依赖和渲染细节以 Director 当前说明 为准。

在符合条件的 ACG 单文件 SOG/PLY 资源主路由或别名后追加 /director,例如 /acg/szcaf15/honkai_star_rail-tribbie/director。页面按索引加载主模型与已声明环境;不支持流式资源,也不接受任意远程模型地址。需要 WebGPU 和浮点渲染能力。Viewer 同标签页的有效机位优先,直接打开则读取资源 JSON 初始机位。

完整站点构建和预览(先物化已登记的 Git LFS 资源):

npm --prefix metaflow-viewer ci
npm --prefix metaflow-viewer run build
npm --prefix metaflow-director ci
npm --prefix metaflow-director run build
node scripts/stage-director-site.mjs
node metaflow-director/preview.mjs

预览地址为 http://127.0.0.1:5207;所有模型、编码器和字体读取同站路径,不需要原实验服务。发布包使用自有界面、系统字体和许可登记的开源依赖,来源见 MF-106 Spec。

开发模式

稳定 route 的开发模式使用两个终端:

# 终端 1:自动重新构建
npm run watch

# 终端 2:为未知路径提供 index.html fallback
npx --no-install serve -s public -l 3000

当前 npm run develop 内部使用不带 -s 的 serve public,适合根路径或直接 query 调试,不能单独验证 /acg/... 之类的深层 route。完整说明见 Viewer 快速开始。

使用方式

1. URL 路由(推荐)

直接访问路由路径即可加载对应资源:

http://localhost:3000/acg/ad05/delta-force
http://localhost:3000/acg/ad05/frieren
http://localhost:3000/acg/yzx/yzx

路由信息来自 /data/index.json。本地服务器必须提供 SPA fallback;否则资源即使存在,直接打开深层路径也会先得到静态服务器 404。

2. URL 参数

也可以使用 URL 参数指定内容:

http://localhost:3000/?content=/data/path/to/model.sog&settings=/data/path/to/settings.json

支持的参数:

参数 说明
content 模型文件路径 (.sog / .compressed.ply)
settings 设置文件路径 (.json)
poster 加载时显示的图片
skybox 天空盒图片
noui 隐藏 UI
noanim 禁用动画

项目结构

metaflow-viewer/
├── src/                    # 源代码
│   ├── index.html          # HTML 模板(含路由配置)
│   ├── index.scss          # 样式
│   ├── index.ts            # 入口
│   └── ...                 # 其他模块
├── public/                 # 构建产物
│   ├── index.html
│   ├── index.css
│   ├── index.js            # 打包后的 JS (含 PlayCanvas 引擎)
│   ├── data -> ../../data  # 本地开发链接;部署时由 Netlify 同步副本
│   └── serve.json          # 服务器配置(SPA 路由)
├── package.json
├── rollup.config.mjs
└── tsconfig.json

数据目录

/data/index.json 包含所有资源的索引信息:

{
  "resources": [
    {
      "id": "delta-force",
      "title": "三角洲",
      "route": "/acg/ad05/delta-force",
      "files": {
        "model": "ACG/AD05/.../Delta Force.sog",
        "settings": "ACG/AD05/.../settings.json"
      }
    }
  ]
}

部署

当前完整站点还包含 ACG Director;其构建与暂存要求见 Director 说明。以下保留原有 Viewer/data/Editor 部署参考。

npm run build 生成 Viewer 文件;完整平台发布还要把仓库根 data/ 和 metaflow-editor/ 同步到 public/data/、public/editor/。当前 Netlify 命令已执行这一步,手工部署时也不能漏掉。Editor 源码的 dist/ 不会被 Netlify 自动采用;完整 staging 和发布步骤见 部署。

注意:需要配置服务器支持 SPA 路由(将所有路径重定向到 index.html,除了 /data/ 等静态资源)。

Nginx 配置示例:

location / {
    try_files $uri $uri/ /index.html;
}

当前版本

2026-11-14 发布候选: Viewer 5.23.2 保留线上 5.23.1 背景与捕获行为,为 Apple 移动 WebKit 默认选择 WebGL 2 并增加图片解码保护。上游仍为 SuperSplat Viewer 1.37.0 / PlayCanvas 2.23.0,100 项资源及索引 schema 1.2 保持。生产交付使用完整现有部署快照叠加 Viewer 文件,保留 Editor、Director 与 Horizon;最终发布身份和回读见 恢复与发布记录。

2026-10-19 文档快照(历史保留)

2026-10-19 更新: 线上与机器元数据均已确认为 Viewer 5.22.0,上游 SuperSplat Viewer 1.37.0 / PlayCanvas 2.23.0;Editor 仍为 1.1 / 1.1.0,资源索引仍为 schema 1.2、100 项。版本来源见 Viewer Version History,正式发布与验收见 MF-151 记录。

2026-10-18 文档快照(历史保留)

以下旧摘要与后续历史段落保留原文,其中“当前”“最新”均有当时语境;现行版本以上方 2026-10-19 更新为准。

以下为 2026-10-18 核对的发布摘要。各产品独立记录版本;线上实验和规划产品不据此获得统一发布版本。

对象 当前值 上游基线 事实来源
Viewer 展示/package 5.21.11 SuperSplat Viewer 1.35.2 / PlayCanvas 2.22.4 Version History · 发布核验
Editor 展示 1.1 / app 1.1.0 SuperSplat Editor 2.28.0 Version History · 运行时版本
资源索引 schema 1.2,100 项资源 — data/index.json

Viewer 源码位于 metaflow-viewer/;当前 Editor 可重建源码位于 supersplat-v2.28.0/,metaflow-editor/ 保存发布构建。Director 的产品定位独立,当前 ACG 入口随 Viewer 发布链路交付,实验依赖版本不能用作 Editor 正式版本。更多边界见 兼容与版本事实源。

原版本摘要(历史保留)

以下表格是此前阶段的版本快照;其中“当前”与“候选”指当时状态。现行发布值以上方带核对日期的摘要为准。

字段 值
展示版本 5.21.5 (MF-106,PR #123)
包版本 5.21.5
索引 schema 1.2
上游 SuperSplat Viewer v1.35.2
PlayCanvas 2.22.4
当前产品实现 commit 103afad3(候选)
发布控制修复 commit 92d11b0

当前 Editor

字段 值
Metaflow Editor 1.1
上游 SuperSplat Editor v2.28.0
当前源码目录 supersplat-v2.28.0
历史基线源码目录 references/supersplat-v2.18.1;其 v2.18.1 仅表示 lineage,内容身份见 metadata/reference-snapshots.json
/editor 运行时版本 metaflow-editor/version.json
版本历史 metadata/editor-version-history.json
三方审查快照登记 metadata/reference-snapshots.json:Viewer v1.26.2/v1.29.1、Editor v2.28.0/v2.32.3、Transform CLI v2.5.1/v3.3.0;执行中发布的前一候选 v1.28.0/v1.29.0/v3.2.0 仍作为不可变中间快照保留
三方审查结论 docs/history/upstream-reviews/2026-08-10/:Viewer Adopt、Editor Defer、Transform CLI Adopt(离线工具);均未在本轮发布

最近版本

Viewer 结构化版本历史与变更总账保存完整版本记录;Editor 版本历史与变更总账独立维护。历史发布恢复与阶段审计从历史资料入口查阅。

下表完整保留原有历史版本摘录;后续版本见上述结构化版本历史与总账。

版本 commit 摘要
5.19.3 f999471 MF-81:3 组芒种、9 组 SZTUCCF260919 ACG,原始镜头 4K WebP、99 项索引;最终生产状态见 Issue #81
5.19.2 92d11b0 analytics/release 修复:production/tagged build 缺少 Supabase endpoint 时直接失败,Netlify production context 注入 endpoint,release smoke 校验最终 HTML meta;不改变资源、路由或 schema
5.19.1 534b013 MF-30 正式生产发布:修复 release/CI sparse fixture 与 build-before-test 顺序;D2 controlled Prepare 通过后,因 Netlify Git build 再次停滞,经明确授权使用精确 D2 CLI/API 发布 deploy 6a7efc396f36c800cfa0702e;真实浏览器 smoke、15 分钟观察与 GitHub Release 均完成
5.19.0 26e311c MF-30 同步 Viewer v1.29.1 / PlayCanvas 2.21.3 并保留 Metaflow 合同;不可变 Tag 已建立,但 workflow run 31779246997 在 prepare 的 sparse/order 校验阶段失败,production job 未执行、没有 GitHub Release,生产从未切换到 5.19.0
5.18.1 578272c 发布 BitCity 260711 与第十五届深圳动漫节 27 条人物资源及默认 figure8 动画策略
5.18a c613a87 新增并对齐深圳笔架山动态 voxel 场景
5.18 7ce294a 优化移动端触控游戏控制
5.17 f371f48 对照支付宝式数据面板补齐全局筛选、指标口径、D30 留存、访问时长/时段画像、可信机型明细、机型质量排行和转化目标
5.16 e68d52b 新增 Metabase 看板汇总层:今日小时对比、留存 cohort、来源分析、保守机型统计和双语看板卡片
5.15 46b4ec2 为 SZTU 全部资源补齐中文域名短链 alias,包括 /top10-26 和 /fes/top10-26
5.14 7c52315 修复 深圳技术大学.com 根域跳转到 /sztu/c2-lib,并恢复 /c2-lib 短链 alias
5.13 4031c46 新增 /dashboard 和 /dashboard/* 到 Metabase 仪表盘子域的重定向
5.12 de75ce5 修复 analytics sendBeacon 跨域 credentials 上报失败,并关闭缺失 CSS sourcemap 引用
5.11 b06b13c 补充 UA/Client Hints、来源归因、Web Vitals、Resource Timing、聚合交互深度和设备/性能/用户/数据质量建模
5.10 8b37760 新增 Supabase 权威埋点链路、15 秒可见心跳、Metabase 建模表、可选 PostHog 精简镜像和多人同屏分析事件预留
5.9 1d9ab2b 调慢 SOG/流式 reveal、uRevealActive 藏点、流式主体提前高 LOD、环境不阻塞首帧、c2-lib 首次退出动画进 Orbit
5.8 4e848ac 按场景分档 reveal 点大小,修复流式 LOD 双波揭示,恢复 loading 后可见再播放
5.7 4114e8f 简化 reveal 振荡:去掉 lift 波前隆起,保留 sin 抖动,delay 缩至 1.0s
5.5 f4c4621 新增全站高斯点 reveal 粒子揭示效果,支持环境模型并提供 ?noreveal 逃生参数
5.3a 74c04c0 更新 Cyrene 初始构图和缩略图
5.3 7672825 修复 Netlify 发布目录的数据同步方式
5.2 99ffe6c 路由索引改为强制重新验证,避免旧缓存导致黑屏
5.1 6558254 恢复旧 SOG 排序完成或超时后的首帧兜底
5.0 f41f6de 同步 SuperSplat v1.26.2 架构并移植 Metaflow 定制
4.4 e47067b 发布 Dayun tiled voxel 与版本历史基础设施
4.3 8bc11d5 补充 Firefly 设置与包管理声明

完整审计资料:

5.18a / 5.18.0 是最后一个双轨历史版本,5.18.1 是此后的首个完整 SemVer 发布。5.19.0 是已合并但在部署前失败的 MINOR 发布尝试;5.19.1 是 release transport 的 PATCH 恢复,5.19.2 是 analytics endpoint 与发布校验的 PATCH 修复。旧字母版本保持原样,后续统一使用 SemVer PATCH/MINOR/MAJOR。

URL 查询参数详解

参数列表、编码方式和 route/query 的覆盖顺序见 Viewer URL 参数参考;settings 字段见 Viewer settings schema。

查询参数可以追加在资源路由或根路径之后。第一个参数使用 ?,后续参数使用 &:

http://localhost:3000/acg/fireflyfes38/cyrene?debug&ministats
http://localhost:3000/?content=/data/model.sog&settings=/data/settings.json

包含空格或中文的路径应进行 URL 编码。当前覆盖规则不是统一的“query 优先”:存在 content 时会完全跳过 route/index;route 命中后会覆盖 query 中的 settings;poster、environment、collision、voxel 和 voxelManifest 则保留显式 query 值。完整矩阵和当前实现来源见 Viewer URL 参数参考。

资源参数

参数 值 说明
content URL 主模型地址,支持 SOG、压缩 PLY 或流式 LOD JSON
settings URL Viewer 设置文件地址,支持 JSON 和现有 JSONC 兼容语法
poster URL 加载阶段显示的封面图片
skybox URL 环境天空盒图片
environment URL 独立环境 Gaussian Splat 模型
collision URL 碰撞资源地址;GLB 作为网格碰撞,voxel JSON 作为体素碰撞
voxel URL 单体 walk.voxel.json 地址;首帧后在后台加载对应 BIN
voxelManifest URL tiled voxel 清单地址;分块按照用户位置按需加载

界面与动画参数

参数 说明
noui 隐藏 Viewer UI,适合嵌入或纯画面输出
noanim 禁止默认动画自动播放;不会启动 figure8,也不会消耗首次动画退出策略

渲染参数

参数 值 说明
webgl 无 强制使用 WebGL;未设置时优先尝试 WebGPU
aa 无 启用 Gaussian Splat 抗锯齿
nofx 无 禁用 CameraFrame 后处理
noreveal 无 禁用高斯点首帧粒子揭示效果;不影响普通 loading UI
hpr 1、true、enable 或空值 强制启用高精度渲染;其他显式值表示禁用
budget 数字 覆盖 splat budget,单位为百万,例如 budget=3
fullload 无 等待完整 LOD 质量,适合截图或离线验收
colorize 无 使用颜色显示 LOD 层级
unified 无 保留的统一渲染兼容参数;当前加载器默认使用 unified 语义

调试参数

参数 说明
debug 自动打开相机调试面板,可查看/编辑位置与焦点并截图;也可按 Ctrl+Shift+D,macOS 可按 Cmd+Shift+D
ministats 显示实时性能仪表盘,包括帧率、显存和 splat 数量
heatmap 将可用的碰撞调试叠层初始化为热力图模式

Viewer 会忽略未识别的查询参数。例如 cb=时间戳 可以用于生成不同 URL 或辅助缓存排查,但不会改变 Viewer 行为。

文档与贡献

需要完成的事 文档入口
理解产品职责与选择工具 项目概览
查找使用、概念与维护文档 中文文档中心
将编辑结果接入 Viewer Editor 到 Viewer
配置场景、嵌入与分享 配置 Viewer · 嵌入与分享
了解源码位置与本地检查 仓库地图 · 开发与验证
维护发布与部署 版本与发布 · 部署
参与贡献与反馈 贡献指南 · Issues

产品方向以 八产品规划 MF-100 及各产品任务为入口。贡献时结合当前任务范围与 MCL v1.0 candidate 的适用边界;候选规范不代表已在全仓激活。

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages