diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000000000000000000000000000000000..06b96dda4f94f9c4ae2136846b04223d95fbe46d --- /dev/null +++ b/.gitattributes @@ -0,0 +1,6 @@ +* text=auto eol=lf + +*.gif filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text +*.mp4 filter=lfs diff=lfs merge=lfs -text +*.png filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..a7c3a4504ee5b87d6d90f3358c6f1eee49b83b3d --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +node_modules/ +dist/ +.DS_Store +*.log +*.tsbuildinfo + +# Local publishing plans; not part of the public repository. +publishing/huggingface-article/ diff --git a/ASSETS.md b/ASSETS.md new file mode 100644 index 0000000000000000000000000000000000000000..155062784f84ea8d3ad9deeecf0112ff2c18c751 --- /dev/null +++ b/ASSETS.md @@ -0,0 +1,31 @@ +# Demo media + +The sample image and video in `public/demo/` were created by the repository owner with Jimeng AI and are included so the interactive work can be experienced immediately. + +They are made available under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/), to the extent the repository owner holds rights in the generated media: + +- `public/demo/poster.png` +- `public/demo/video_01.mp4` + +Suggested attribution: **“Orbit Comic demo artwork, created with Jimeng AI.”** + +The MIT software license and the CC BY 4.0 media license are separate. You may replace both files with your own media; your replacement media keeps whatever license you choose for it. + +## README media + +The current README preview and its reproducible recording sources were created from Jimeng AI media supplied by the repository owner. They follow the same CC BY 4.0 terms, to the extent the repository owner holds rights in the generated media: + +- `recording-comic/assets/shot.png` +- `recording-comic/assets/impact.png` +- `recording-comic/output/orbit-comic-demo.gif` +- `recording-comic/output/orbit-comic-demo.mp4` + +The following concept images were generated for this repository with OpenAI ImageGen and are also offered under CC BY 4.0, to the extent the repository owner holds rights in them: + +- `docs/assets/concepts/product-viewer.jpg` +- `docs/assets/concepts/game-item-inspection.jpg` +- `docs/assets/concepts/interactive-comic.jpg` + +They illustrate possible uses only. They are not screenshots of completed bundled applications. + +The exact generation prompts are recorded in [`docs/assets/concepts/PROMPTS.md`](docs/assets/concepts/PROMPTS.md). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..56cf1b4480778c12f168c53cb78403e576fb4682 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Orbit Panel Viewer contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.huggingface.md b/README.huggingface.md new file mode 100644 index 0000000000000000000000000000000000000000..a45bd29509a7d848fd4b973e97d16cbe80de6033 --- /dev/null +++ b/README.huggingface.md @@ -0,0 +1,64 @@ +--- +title: Orbit Comic Demo +emoji: 🎞️ +colorFrom: gray +colorTo: red +sdk: static +app_file: dist/index.html +app_build_command: npm run build:demo +fullWidth: true +header: mini +short_description: A live demo of the Orbit Video Viewer library. +--- + +# Orbit Video Viewer + +**Turn pre-rendered orbit videos into interactive, drag-controlled views. No 3D models required.** + +Orbit Comic is the live demonstration above. Drag horizontally across the artwork to browse the viewpoints encoded in the MP4. Use **Change video** to try your own local MP4; the file stays in your browser and is not uploaded by this app. + +The reusable open-source project provides `OrbitViewer`, browser-side MP4 processing, a public control API, an integration Skill for AI coding agents, and a standalone consumer example. + +> **Technique credit:** This project studies an interaction technique shared by [monoradio (@monoradio102)](https://x.com/monoradio102) through a Claude Artifact. The code was independently implemented with Codex and does not copy the Artifact's source. + +## Source and local use + +The canonical source is [boryzoo/orbit-video-viewer on GitHub](https://github.com/boryzoo/orbit-video-viewer). Use GitHub for the editable source, installation documentation, version history, and [issue tracking](https://github.com/boryzoo/orbit-video-viewer/issues). This Space is the live demonstration of the same project. + +For a local source checkout: + +```bash +pnpm install +pnpm dev +``` + +The verified release target is Chromium with H.264 MP4. Safari and Firefox support remains pending the same manual interaction matrix. This is controlled viewpoint playback rather than real 3D; it cannot reveal angles absent from the source video. + +--- + +# Orbit Video Viewer（中文） + +**把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。** + +上方的 Orbit Comic 是在线演示。请在画面中水平拖动，浏览 MP4 已经包含的不同观察视角。使用 **Change video** 可以尝试自己的本地 MP4；文件只在浏览器内处理，不会由这个应用上传。 + +可复用的开源项目包含 `OrbitViewer`、浏览器端 MP4 处理、公开控制 API、供 AI 编程工具使用的接入 Skill，以及一个独立消费示例。 + +> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。 + +## 源码与本地运行 + +项目的唯一源码基准是 GitHub 上的 [boryzoo/orbit-video-viewer](https://github.com/boryzoo/orbit-video-viewer)。可编辑源码、安装说明和版本历史以 GitHub 为准；问题可提交到 [GitHub Issues](https://github.com/boryzoo/orbit-video-viewer/issues)。这个 Space 是同一项目的在线演示入口。 + +本地源码运行方式： + +```bash +pnpm install +pnpm dev +``` + +当前已经验证的发布目标是 Chromium + H.264 MP4；Safari 与 Firefox 尚待完成同等手动交互测试。这是受控的视角回放，不是真实 3D，不能生成源视频中不存在的角度。 + +## License / 许可 + +Software is MIT licensed. Demo media has separate terms documented in `ASSETS.md`. 技术代码使用 MIT License；演示媒体的独立条款见 `ASSETS.md`。 diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..a45bd29509a7d848fd4b973e97d16cbe80de6033 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +--- +title: Orbit Comic Demo +emoji: 🎞️ +colorFrom: gray +colorTo: red +sdk: static +app_file: dist/index.html +app_build_command: npm run build:demo +fullWidth: true +header: mini +short_description: A live demo of the Orbit Video Viewer library. +--- + +# Orbit Video Viewer + +**Turn pre-rendered orbit videos into interactive, drag-controlled views. No 3D models required.** + +Orbit Comic is the live demonstration above. Drag horizontally across the artwork to browse the viewpoints encoded in the MP4. Use **Change video** to try your own local MP4; the file stays in your browser and is not uploaded by this app. + +The reusable open-source project provides `OrbitViewer`, browser-side MP4 processing, a public control API, an integration Skill for AI coding agents, and a standalone consumer example. + +> **Technique credit:** This project studies an interaction technique shared by [monoradio (@monoradio102)](https://x.com/monoradio102) through a Claude Artifact. The code was independently implemented with Codex and does not copy the Artifact's source. + +## Source and local use + +The canonical source is [boryzoo/orbit-video-viewer on GitHub](https://github.com/boryzoo/orbit-video-viewer). Use GitHub for the editable source, installation documentation, version history, and [issue tracking](https://github.com/boryzoo/orbit-video-viewer/issues). This Space is the live demonstration of the same project. + +For a local source checkout: + +```bash +pnpm install +pnpm dev +``` + +The verified release target is Chromium with H.264 MP4. Safari and Firefox support remains pending the same manual interaction matrix. This is controlled viewpoint playback rather than real 3D; it cannot reveal angles absent from the source video. + +--- + +# Orbit Video Viewer（中文） + +**把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。** + +上方的 Orbit Comic 是在线演示。请在画面中水平拖动，浏览 MP4 已经包含的不同观察视角。使用 **Change video** 可以尝试自己的本地 MP4；文件只在浏览器内处理，不会由这个应用上传。 + +可复用的开源项目包含 `OrbitViewer`、浏览器端 MP4 处理、公开控制 API、供 AI 编程工具使用的接入 Skill，以及一个独立消费示例。 + +> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。 + +## 源码与本地运行 + +项目的唯一源码基准是 GitHub 上的 [boryzoo/orbit-video-viewer](https://github.com/boryzoo/orbit-video-viewer)。可编辑源码、安装说明和版本历史以 GitHub 为准；问题可提交到 [GitHub Issues](https://github.com/boryzoo/orbit-video-viewer/issues)。这个 Space 是同一项目的在线演示入口。 + +本地源码运行方式： + +```bash +pnpm install +pnpm dev +``` + +当前已经验证的发布目标是 Chromium + H.264 MP4；Safari 与 Firefox 尚待完成同等手动交互测试。这是受控的视角回放，不是真实 3D，不能生成源视频中不存在的角度。 + +## License / 许可 + +Software is MIT licensed. Demo media has separate terms documented in `ASSETS.md`. 技术代码使用 MIT License；演示媒体的独立条款见 `ASSETS.md`。 diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000000000000000000000000000000000000..f8907ee2d55111f17ecce1f1b730dd8abb4d3fe6 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,153 @@ +

English · 简体中文

+ +

+ 三格漫画演示：拖动指示器移动时，主画面的观察视角随之变化 +

+ +

Orbit Video Viewer

+ +

把预先生成的环绕视频变成可拖动控制视角的网页交互，不需要 3D 模型。

+ +

+ 体验 Demo · + 使用 Skill · + 使用 SDK +

+ +Orbit Comic 是仓库内附的演示作品；这个开源项目的主体是其下方可复用的交互能力：载入一段环绕 MP4，让用户通过拖动浏览不同视角，读取或设置当前角度，并把它嵌入自己的产品。 + +> **技术灵感署名：** 本项目研究了 [monoradio（@monoradio102）](https://x.com/monoradio102) 通过 Claude Artifact 分享的交互思路。代码由 Codex 独立实现，没有复制该 Artifact 的源码。 + +## 可以用它做什么？ + + + + + + + + + + + + +
可拖动商品查看器概念图游戏道具多视角检查概念图互动漫画视角探索概念图
商品查看器游戏道具检查互动漫画
+ +这些图片只用于说明可能的应用方向，不是仓库内已经完成的独立产品。同一种交互也可以用于展览、角色展示、教育、建筑和互动艺术。 + +## 开始使用 + +### 通过 AI 编程工具使用 Skill + +[`integrate-orbit-video` Skill](skills/integrate-orbit-video/SKILL.md) 会指导 AI 编程工具把 SDK 和你的 MP4 接入现有网页项目，同时尽量保留原项目的视觉设计。 + +最简单的使用方式是下载本仓库，在 AI 编程工具中打开你自己的项目，并向工具提供三个路径：你的项目、你的 MP4 和这个 Skill 文件。然后输入： + +```text +使用 integrate-orbit-video Skill，把我的环绕 MP4 接入这个项目。 +``` + +如果需要反复使用，可以把整个 `skills/integrate-orbit-video` 文件夹安装到工具的 Skill 目录。Claude Code 项目级 Skill 可放在 `.claude/skills/integrate-orbit-video/`；兼容 Codex 的工具可以使用其本地或项目 Skill 目录，也可以直接读取仓库中的 `SKILL.md`。 + +这个 Skill 采用 OpenAI 与 Claude Code 所描述的开放 `SKILL.md` Agent Skills 格式。它已经在 Codex 工作流中完成真实接入测试；其他工具是否能自动发现和调用，取决于其具体版本与配置。详见 [Skill 验证记录](docs/SKILL_VALIDATION.md)。 + +### 直接使用 SDK + +npm 包尚未公开发布。当前可先构建本仓库，再通过本地文件依赖安装： + +```bash +pnpm install +pnpm build:library +pnpm add /absolute/path/to/orbit-panel-viewer +``` + +```html +
+``` + +```css +#orbit-view { + aspect-ratio: 16 / 9; + overflow: hidden; + cursor: grab; + touch-action: pan-y; + user-select: none; +} + +#orbit-view canvas { display: block; width: 100%; height: 100%; } +``` + +```ts +import { OrbitViewer, createMp4Source } from 'orbit-video-viewer'; + +const element = document.querySelector('#orbit-view'); +if (!element) throw new Error('Missing orbit view.'); + +const viewer = new OrbitViewer({ element, initialAngle: 0 }); +await viewer.load(createMp4Source('/assets/orbit.mp4')); + +viewer.setAngle(90, { animate: true }); +viewer.reset(); +``` + +更多内容见[接入指南](docs/INTEGRATION.md)、[公开 API](#公开-api)和独立的 [`basic-integration`](examples/basic-integration) 消费项目。 + +## 公开 API + +| API | 用途 | +|---|---| +| `createMp4Source(urlOrFile)` | 载入 MP4 URL、`File` 或 `Blob` | +| `load(source, options?)` | 准备并显示素材 | +| `getAngle()` / `getState()` | 读取当前视图状态 | +| `setAngle(degrees, options?)` | 移动到指定视角 | +| `rotateBy(degrees, options?)` | 相对当前视角旋转 | +| `reset(options?)` | 回到当前视频的初始视角 | +| `setInteractionEnabled(boolean)` | 启用或禁用用户输入 | +| `destroy()` | 释放资源和事件监听 | + +通用 `OrbitSource` 接口把 Viewer 与解码逻辑分开。当前版本只实现浏览器端 MP4 处理，不包含预处理工具。 + +## 源视频要求 + +建议使用 H.264 MP4：画面应是一段连续的水平环绕运动，主体大小和相机高度保持稳定，不要切镜；如果希望首尾循环，结束视角应尽量接近开场视角。 + +这是一种受控的视角回放，不是真实 3D。它不能生成视频中不存在的角度、改变几何结构、提供碰撞或重新打光。MP4 中的音频会被忽略。 + +## 体验 Demo + +不要直接双击 `index.html`。请启动开发服务器： + +```bash +pnpm install +pnpm dev +``` + +然后打开 Vite 输出的本地地址。使用 **Change video** 可以尝试自己的 MP4；**Reset view** 会回到当前已载入视频的初始视角。 + +## 项目结构 + +```text +src/core/ 内部运动、帧、缓存和素材契约 +src/library/ 对外 OrbitViewer SDK +src/demo/ Orbit Comic 展示界面 +skills/integrate-orbit-video AI 辅助接入流程 +examples/basic-integration 独立 SDK 消费项目 +public/demo/ 内置 Orbit Comic 媒体 +``` + +## 文档 + +- [English README](README.md) +- [接入指南](docs/INTEGRATION.md) +- [技术报告](docs/TECHNICAL_REPORT.md) +- [浏览器兼容性](docs/COMPATIBILITY.md) +- [来源与署名](docs/ORIGIN_AND_ATTRIBUTION.md) +- [验证记录](VALIDATION.md) +- [发布清单](docs/RELEASE_CHECKLIST.md) +- [发布执行手册](docs/PUBLISHING_RUNBOOK.zh-CN.md) +- [产品与发布决策](docs/PROJECT_AND_PUBLISHING.zh-CN.md) +- [Hugging Face Space README 模板](README.huggingface.md) + +## 许可 + +Library、Demo 源码和 Skill 使用 [MIT License](LICENSE)。Demo 与 README 媒体采用单独条款，见 [ASSETS.md](ASSETS.md)；第三方软件见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000000000000000000000000000000000000..67635bb11ec581fb88879d249981522c0b677ee8 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,17 @@ +# Third-party notices + +The distributed Library has one runtime dependency: + +| Package | Version checked | License | Purpose | +|---|---:|---|---| +| `mp4box` | 2.4.1 | BSD-3-Clause | MP4 parsing and encoded sample extraction | + +Development and validation use: + +| Package | Version checked | License | +|---|---:|---| +| `vite` | 8.3.4 | MIT | +| `vitest` | 5.0.3 | MIT | +| `typescript` | 7.0.2 | Apache-2.0 | + +These entries were checked against the installed packages' own `package.json` metadata on 2026-10-12. Their licenses remain their authors' licenses; the repository's MIT License does not replace them. diff --git a/VALIDATION.md b/VALIDATION.md new file mode 100644 index 0000000000000000000000000000000000000000..633137f1fb50200b970d1ea71719dbded1a410d5 --- /dev/null +++ b/VALIDATION.md @@ -0,0 +1,82 @@ +# V0.3 验证记录 + +验证日期：2026-10-12（Asia/Shanghai） + +## 本次验收范围 + +- Core、Library、Demo 已明确分层； +- Orbit Comic 改为通过公开 Library API 运行； +- Library 可以生成独立 ES Module 和 TypeScript 类型声明； +- 独立项目通过本地包依赖安装 Library，没有直接引用主项目 `src/`； +- 没有实现预处理工具或其他超出范围的扩展。 +- 新增基于同一 Library 的 `integrate-orbit-video` Skill； +- 完成 Skill 驱动的全新临时项目接入验收； +- README 已按“作品效果 → 使用想象 → Skill / SDK”重新组织； +- 完成依赖许可、参考来源和浏览器支持范围检查。 + +## 测试素材 + +- `public/demo/video_01.mp4`； +- H.264，852 × 480，约 10.05 秒，约 14 MB； +- 视频包含 AAC 音轨，但 Library 只使用视频轨； +- 内容经过正面、侧面、背面、另一侧并返回正面。 + +## 自动检查 + +- TypeScript 严格检查：通过； +- Vitest：1 个文件、4 个用例通过； +- Orbit Comic Demo 生产构建：通过； +- Library ES Module 构建：通过； +- Library TypeScript 类型声明构建：通过； +- npm tarball 内容检查：通过； +- `examples/basic-integration` 独立项目 TypeScript 检查与 Vite 构建：通过。 +- Skill 官方结构验证器：通过； +- Skill 临时消费项目安装、TypeScript 与 Vite 生产构建：通过。 + +Library 构建结果： + +- `dist/library/orbit-viewer.js`：约 15.8 KB，gzip 后约 5.1 KB； +- `dist/types/`：公开 API 及其依赖类型声明。 + +## 独立项目浏览器实测 + +独立项目位于 `examples/basic-integration`，拥有自己的 `package.json`，通过 `file:../..` 安装构建后的 `orbit-video-viewer` 包。 + +实测结果： + +- MP4 成功加载并显示第 0 帧； +- `onChange` 正确报告 `0° · frame 0`； +- `setAngle(90)` 到达 `90° · frame 31`； +- `setAngle(180)` 到达 `180° · frame 62`； +- `reset()` 返回 `0° · frame 0`； +- 鼠标拖动后角度与帧持续变化； +- 浏览器控制台无 warning、无 error。 + +## Orbit Comic 回归实测 + +- 默认沙漠作品成功加载； +- 原页面视觉、标题、署名、Change video 和 Reset view 保留； +- 拖动正常； +- Reset view 返回当前视频的初始视角； +- 浏览器控制台无 warning、无 error。 + +## Skill 独立接入实测 + +- 在系统临时目录新建了独立 Vite / TypeScript 项目； +- 项目从 npm tarball 安装 `orbit-video-viewer@0.1.0`，没有引用主仓库 `src/`； +- 页面采用与 Orbit Comic 不同的“Relic Study”视觉，不复制 Demo UI； +- MP4 加载成功，拖动后角度发生变化； +- Reset view 返回当前视频的 `0°` 初始视角； +- 控制台无 warning、无 error； +- 详细步骤见 `docs/SKILL_VALIDATION.md`。 + +## 已知边界 + +- 已验证的快速路径是 H.264 MP4，不代表所有 MP4 编码都已验证； +- `video fallback` 已保留，但本轮没有强制关闭 WebCodecs 单独覆盖该路径； +- 当前只实现浏览器即时处理 MP4； +- 已添加通用 `OrbitSource` 接口，但没有实现预处理工具或图片清单加载； +- 首尾连续性和角色一致性仍由源视频决定； +- Library 尚未发布到 npm，本轮验证使用本地构建包。 +- Skill 使用开放的 `SKILL.md` 格式并通过结构验证，但目前只在 Codex 执行流程中完成真实接入测试；Claude Code 的目录兼容性有官方依据，尚未在本机 Claude Code 中运行同一验收。 +- Safari 和 Firefox 尚未完成与 Chromium 相同的手动交互矩阵，因此 README 不宣称它们已经完整验证。 diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md new file mode 100644 index 0000000000000000000000000000000000000000..ff4164a623de18f76d3bc945d5d52e23b17d92b1 --- /dev/null +++ b/docs/COMPATIBILITY.md @@ -0,0 +1,19 @@ +# Browser compatibility + +## What has been verified + +- The Demo and independent integration project were exercised in a Chromium-based browser. +- The WebCodecs H.264 path loaded the bundled 852 × 480 MP4, supported dragging, angle controls, reset, and cleanup without console errors. +- The package build and TypeScript declarations were consumed by a separate Vite project. + +## Runtime requirements + +The Viewer needs JavaScript modules, Canvas, Pointer Events, `fetch`, `Blob`, and normal browser media support. The fast path also needs WebCodecs and H.264 decoding. + +The code feature-detects the fast path and includes an offscreen `