🚀 feat: prepare auditable open-source alpha and launch media
Some checks are pending
Core checks / backend (push) Waiting to run
Core checks / frontend (push) Waiting to run

This commit is contained in:
eust-w 2026-10-26 17:38:24 +08:00
parent f4cc3cfe6f
commit d13e06907b
21 changed files with 1017 additions and 447 deletions

40
.github/workflows/checks.yml vendored Normal file
View File

@ -0,0 +1,40 @@
name: Core checks
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
permissions:
contents: read
jobs:
backend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- run: python -m pip install -r backend/requirements-dev.txt pip-audit
- run: python -m pytest
working-directory: backend
- run: python scripts/synthetic_demo.py
- run: pip-audit -r backend/requirements-dev.txt
frontend:
runs-on: ubuntu-latest
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: '24'
cache: npm
cache-dependency-path: frontend/package-lock.json
- run: npm ci
- run: npm test
- run: npm run build
- run: npm audit

8
.gitignore vendored
View File

@ -1,5 +1,13 @@
.DS_Store
.venv/
.venv-*/
.env
.env.*
!.env.example
!**/.env.example
*.p12
*.mobileprovision
artifacts/
__pycache__/
*.pyc
.pytest_cache/

35
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,35 @@
# Contributing
Real2Motrix welcomes reproducible bug reports, small fixes and real-device test
results. Read [the roadmap](docs/ROADMAP.md) and [security policy](SECURITY.md) first.
## Development
Use Python 3.12 and Node 24. Follow the README setup, then run:
```bash
cd backend
../.venv/bin/python -m pytest
cd ../frontend
npm ci
npm test
npm run build
npm audit
```
For a PR, describe the problem, the smallest reproducible input, the change and
the checks actually run. Add a regression test for changed behavior. Keep runtime
data and generated media out of Git. Contributions are made under Apache-2.0;
only submit code and assets you have permission to license.
## Evidence matters
- Label original synthetic fixtures as synthetic. Do not present them as scans.
- Report capture device, LiDAR availability, lighting, input duration, dependency
versions, processing hardware and elapsed time for reconstruction experiments.
- Separate API/unit-test results, browser tests, real-device capture and actual
simulator execution. Passing one does not establish the others.
- Compare visual fidelity and collision geometry separately. Provide a scale
reference and permitted source footage when claiming reconstruction quality.
- Check recordings for faces, addresses, confidential screens and private rooms
before sharing. Prefer a minimal original fixture for public issues.

View File

@ -14,6 +14,11 @@
A local toolchain for ARKit capture, mesh processing and MJCF / URDF scene packaging. Start with an original synthetic mesh, then add reconstruction tools as your input type requires.
**Alpha, local-only.** This is not a production scanning service. Phone capture is
experimental; trajectory coverage is not surface completeness. There is no 3DGS
training/rendering pipeline. See [the roadmap](docs/ROADMAP.md) for acceptance
criteria and [SECURITY.md](SECURITY.md) before using a network connection.
| Capability | What it provides |
| :--- | :--- |
| **Native capture** | SwiftUI / ARKit source; real devices require Xcode and signing. |
@ -29,6 +34,9 @@ A local toolchain for ARKit capture, mesh processing and MJCF / URDF scene packa
<a id="quick-start"></a>
## Quick start
Tested toolchain: Python 3.12 and Node 24. Native reconstruction dependencies are
not required for the synthetic mesh demo.
```bash
git clone https://github.com/eust-w/Real2Motrix.git
cd Real2Motrix
@ -74,6 +82,9 @@ Recorded environment and executed checks: [validation notes](docs/readme/validat
- [Pipeline / 流水线](backend/app/pipeline/full_pipeline.py)
- [Backend tests / 后端测试](backend/tests/)
- [iOS release / iOS 发布](docs/ios-release.md)
- [Contributing](CONTRIBUTING.md)
- [Roadmap and known limitations](docs/ROADMAP.md)
- [Launch evidence and video](docs/launch/README.md)
## License and provenance

View File

@ -14,6 +14,10 @@
本地 ARKit 采集、网格处理与 MJCF / URDF 场景包工具链。先运行自产合成网格,再按输入类型安装重建工具。
**当前为本地 Alpha 版本。** 手机采集属于实验能力;轨迹网格覆盖率不等于表面扫描完整度。
当前没有 3DGS 训练与渲染流水线,也不是可直接部署的生产扫描服务。
验收标准见[路线图](docs/ROADMAP.md),联网使用前请阅读[安全说明](SECURITY.md)。
| 能力 | 内容 |
| :--- | :--- |
| **原生采集** | SwiftUI / ARKit 源码;真机使用需要 Xcode 和签名。 |
@ -29,6 +33,8 @@
<a id="quick-start"></a>
## 快速开始
验证环境为 Python 3.12、Node 24。合成网格演示不依赖 COLMAP / OpenMVS。
```bash
git clone https://github.com/eust-w/Real2Motrix.git
cd Real2Motrix
@ -74,6 +80,9 @@ cd ../frontend && npm test && npm run build
- [Pipeline / 流水线](backend/app/pipeline/full_pipeline.py)
- [Backend tests / 后端测试](backend/tests/)
- [iOS release / iOS 发布](docs/ios-release.md)
- [贡献指南](CONTRIBUTING.md)
- [路线图与已知限制](docs/ROADMAP.md)
- [介绍视频与验证证据](docs/launch/README.md)
## 许可证与来源

25
SECURITY.md Normal file
View File

@ -0,0 +1,25 @@
# Security
Real2Motrix is an experimental, single-user local workbench, not a hosted service.
Use Python 3.12 and Node 24 for the tested development environment.
- Keep both servers bound to loopback by default. The API has no authentication,
per-user isolation, upload quotas or archive expansion quotas. Do not expose it
to the public Internet, shared Wi-Fi or untrusted uploads.
- Phone capture requires a deliberately configured trusted private network.
Restrict access with a firewall or authenticated tunnel. Transport security and
access control must be provided separately; CORS is not authentication.
- Process only trusted input. Native mesh/reconstruction tools parse complex
formats and are not sandboxed. Review their licenses and security updates.
- Never commit recordings of private spaces, credentials, signing certificates,
provisioning profiles, databases or generated capture archives.
- Run `npm audit` in `frontend` and `pip-audit -r backend/requirements-dev.txt`
before distributing a build. A clean scan is not a complete security audit.
Report vulnerabilities using the repository's private security reporting feature
when available. Do not post exploit details, recordings or credentials in public
issues. If private reporting is unavailable, first open an issue asking for a
private contact without including the vulnerability itself.
Only the current main branch receives fixes. No production-security guarantee is
provided for the Alpha release.

View File

@ -2,4 +2,21 @@
The root Apache-2.0 license applies to original repository code and newly created SVG/demo assets. It does not relicense third-party dependencies, model weights, datasets, imported user assets, or externally referenced material.
Dependency versions are recorded in the repository's package lockfiles, Go modules and/or Python requirements. Retain upstream copyright and license notices when redistributing dependencies. No external model weights are added by this release.
Dependency versions are recorded in `frontend/package-lock.json` and Python requirements. Retain upstream copyright and license notices when redistributing dependencies. No external model weights are added by this release.
Optional tools are installed separately and are not relicensed by this repository:
| Component | Upstream license / source |
| --- | --- |
| COLMAP | BSD-3-Clause: https://github.com/colmap/colmap |
| OpenMVS | AGPL-3.0: https://github.com/cdcseacave/openMVS |
| Open3D | MIT: https://github.com/isl-org/Open3D |
| Blender | GPL: https://www.blender.org/about/license/ |
Review the exact versions and their dependencies before bundling executables,
containers or hosted services. Subprocess invocation does not change an upstream
license. This table is not a complete transitive license audit or legal opinion.
`discoverse-dev/gs_playground` was studied as a reference; Real2Motrix does not
claim its results or ship its Gaussian Splatting implementation. Demo geometry
created by the repository scripts is synthetic, not reconstructed footage.

View File

@ -1,4 +1,4 @@
-r requirements.txt
pytest==8.3.4
pytest==9.1.1
pytest-cov==6.0.0

View File

@ -1,10 +1,10 @@
fastapi==0.128.8
fastapi==0.162.0
httpx==0.28.1
numpy==2.0.2
pillow==11.1.0
pillow==13.0.0
pydantic-settings==2.7.1
python-multipart==0.0.20
python-multipart==0.0.32
scikit-learn==1.6.1
starlette==0.49.3
starlette==1.10.0
trimesh==4.5.3
uvicorn[standard]==0.34.0

40
docs/ROADMAP.md Normal file
View File

@ -0,0 +1,40 @@
# Roadmap and acceptance criteria
Real2Motrix is an Alpha local capture and asset-processing workbench. The goal is
a reproducible path from captured geometry to inspectable simulation assets.
This roadmap is not a claim that the following work is already complete.
## Available in source
- Native iOS ARKit capture client and live upload endpoints.
- Desktop task management, Chinese/English UI, 3D visual/collision preview.
- Mesh cleanup, geometric object candidates, MJCF/URDF packaging and validation.
- Optional COLMAP/OpenMVS image/video reconstruction path.
## Before a wider launch
1. **Real-device acceptance:** record a consented phone-to-desktop capture,
reconnect, resume, finish and export session. Retain device/version evidence.
2. **Coverage quality:** replace trajectory-grid occupancy with observed-surface
coverage and uncertainty. Current percentages are not scene completeness.
3. **Reconstruction benchmark:** publish licensed indoor-scene and object inputs,
camera calibration, scale error, failure cases, timings and memory usage.
4. **Simulation acceptance:** load exported packages into the target runtime and
test contacts, units, object transforms and physical parameters. Format
validation alone does not establish physics correctness.
5. **Network hardening:** authentication, authorization, upload/archive limits,
session expiry and resource isolation before supporting shared deployments.
## Research track
- Treat scene reconstruction and object reconstruction as distinct pipelines.
- Improve alignment using calibration, pose/depth confidence and scale anchors.
- Evaluate 3D Gaussian Splatting for appearance separately from collision meshes.
The current code does not train or render Gaussian splats.
- Track reconstruction quality, not stars, as the primary technical metric.
## Useful first contributions
Small reproducible failing meshes; iOS device compatibility reports; collision
quality regression cases; documentation fixes; test coverage for interrupted jobs.
Open an issue describing the intended change before starting a large redesign.

81
docs/launch/README.md Normal file
View File

@ -0,0 +1,81 @@
# Real2Motrix Alpha launch
Positioning: an open-source local capture and asset-processing workbench for
robotics simulation. The initial audience is reconstruction and robotics
developers, not consumers expecting a production phone scanner.
## Demonstration provenance
The video shows the real React/Three.js frontend and an actual HTTP API/worker
mesh job. Its input is original geometry produced by `scripts/launch_demo.py`.
It is **not a phone scan, video reconstruction, 3DGS result or physics benchmark**.
No private recordings, external models, music or signing material are included.
Chinese narration is synthesized with macOS `say` (Tingting).
The local launch directory is ignored by Git:
| File | Purpose |
| --- | --- |
| `Real2Motrix-intro-landscape-1080p.mp4` | Horizontal introduction |
| `Real2Motrix-intro-portrait-1080p.mp4` | Vertical introduction |
| `Real2Motrix.zh-CN.srt` | Chinese subtitles |
| `cover-landscape.png`, `cover-portrait.png` | Original covers |
| `original-geometry-motrix.zip` | Validated synthetic asset package |
| `evidence.json`, `browser-evidence.json` | API/worker and browser evidence |
## Reproduce
Use an isolated database and output directory. Do not point a recording run at
your personal capture library. Set these variables in both backend terminals:
```bash
export REAL2MOTRIX_DATABASE_PATH="$PWD/artifacts/launch/runtime/database.sqlite3"
export REAL2MOTRIX_DATA_DIR="$PWD/artifacts/launch/runtime/data"
export REAL2MOTRIX_OUTPUT_DIR="$PWD/artifacts/launch/runtime/outputs"
export REAL2MOTRIX_PORT=8010
export REAL2MOTRIX_CORS_ORIGINS='["http://127.0.0.1:5174"]'
```
Start the API and worker as described in the root README. Start the frontend
with `VITE_API_BASE_URL=http://127.0.0.1:8010 npm run dev -- --port 5174`.
From the repository root:
```bash
.venv/bin/python scripts/launch_demo.py
# Requires Playwright and its Chromium browser in your Node environment.
node scripts/record_launch.cjs
# macOS, FFmpeg/FFprobe, Pillow and a Chinese font are required.
.venv/bin/python scripts/render_launch_video.py
```
Inspect the entire video before publishing. Check audio, subtitle timing,
overlap, any machine-local paths and all capability claims. The renderer only
distributes a cropped fullscreen section of the raw browser recording; raw
recordings and runtime databases are not release assets.
## Verified on 2026-10-26
- Python 3.12: 17 backend tests passed after dependency updates.
- Node 24: 17 frontend tests passed, including 4 path-display regression tests.
- `npm audit` and requirements-based `pip-audit`: no known vulnerabilities.
- Gitleaks: 10 fetched history commits scanned; no detected credentials.
- Original geometry passed the actual HTTP API/worker path and package validation:
3 object candidates, XML/URDF/JSON/ZIP files. This demonstrates packaging only.
- Browser: fullscreen preview rendered, orbit changed pixels, no page errors.
The first recorded HTTP run used the pre-existing Python 3.9 development
environment; upgraded requirements were checked separately under Python 3.12.
Optional COLMAP/OpenMVS/Open3D dependencies, true surface coverage, real iPhone
capture, app signing and physical simulation acceptance were not validated by
this launch run. Do not interpret format checks as target-runtime acceptance.
## Launch strategy
1. Publish an honest Alpha with a reproducible example and failure boundaries.
2. Gather real-device reports with licensed inputs and measurable quality.
3. Publish comparison videos only after scene/object benchmarks are reproducible.
4. Invite focused contributions through the roadmap; do not promise star counts.
Platform descriptions: [publishing copy](platform-copy.md). Uploading, processing,
approval and public availability are distinct states; only a verified public
link establishes that a platform publication is complete.

View File

@ -0,0 +1,28 @@
# Real2Motrix v0.1.0-alpha.1
A local capture and asset-processing workbench for robotics simulation.
## Included
- React/Three.js task management and visual/collision previews, Chinese/English UI.
- FastAPI/SQLite worker, mesh processing and validated MJCF/URDF scene packages.
- Experimental native ARKit capture source and live upload endpoints.
- Original synthetic demo, reproducible launch scripts, contribution and security
guidelines, roadmap and core CI checks.
- Updated audited dependencies and relative asset paths in the UI.
## Evidence and boundaries
17 backend tests and 17 frontend tests passed locally. Dependency audits found
no known vulnerabilities in the audited requirements and frontend lockfile.
The attached geometry package was produced by the real API/worker and validated.
See `docs/launch/README.md` for exact scope and reproduction.
The videos use original synthetic geometry, real application recording and
synthetic narration. They do not demonstrate real-phone scan quality, 3DGS or
physical simulation correctness. Real-device capture, signing and simulator
acceptance remain separate work. No signed iOS app is included in this release.
Local/trusted input only: the API is not authenticated or resource-isolated.
Read SECURITY.md before networking. Optional native dependencies retain their
upstream licenses; this release does not bundle them or private capture data.

View File

@ -0,0 +1,59 @@
# Publishing copy
## Bilibili / YouTube
Title: 3D 模型进仿真,还差哪一步?Real2Motrix 开源 Alpha
Description:
从可视化模型到仿真资产,需要的不止一个网格文件。
Real2Motrix 是一个本地采集与资产处理工作台:任务管理、3D 预览、视觉/碰撞网格与 MJCF / URDF 场景包导出。
代码:https://github.com/eust-w/Real2Motrix
Gitea 镜像:https://gitea.d-robotics.cc/longtao.wu/Real2Motrix
本片展示真实软件界面和真实后端处理;输入是原创合成几何,不是手机扫描或视频重建效果。
手机 ARKit 采集与上传代码已提供,但真机效果仍需验收。轨迹覆盖率不等于表面扫描完整度;当前没有 3DGS 训练/渲染功能。
Alpha 版本仅面向可信本地环境。合成配音,无第三方音乐。
欢迎运行可复现示例、提交失败案例,或参与表面覆盖与仿真验证。
Tags: 开源, 机器人仿真, 三维重建, ARKit, MJCF, URDF
## Douyin / WeChat Channels
Title: 3D 模型进仿真,还差哪一步?
Real2Motrix 开源 Alpha:本地任务管理、3D 预览、视觉/碰撞资产与 MJCF/URDF 导出。
真实软件录屏+原创几何测试素材+合成配音,非实拍重建;手机扫描为实验能力。
源码:GitHub eust-w/Real2Motrix。欢迎用真实测试一起改进。
#开源 #机器人仿真 #三维重建
## Xiaohongshu
Title: 3D模型进仿真,还差哪一步?
不是能转着看,就能直接放进机器人仿真。
我把 Real2Motrix 作为 Alpha 开源了,先把本地资产处理这条链路做成可检查的工作台:
任务管理、3D 预览、视觉/碰撞网格、MJCF/URDF 和元数据导出。
视频是实际软件录屏,输入为原创合成几何,不是手机实拍重建;配音为合成语音。
手机采集仍是实验能力,轨迹覆盖率也不等于场景完整度。
下一步想认真做好:场景/物体分流、表面覆盖反馈、真实数据集与仿真器验证。
GitHub 搜索 eust-w/Real2Motrix,欢迎带着失败案例来一起改。
#开源项目 #机器人 #三维重建
## X
Real2Motrix is open source: a local 3D asset workbench for robotics simulation.
Visual/collision meshes, MJCF/URDF export, inspectable packages.
Alpha. Real UI + original synthetic geometry, not a scan-quality demo. Phone capture is experimental.
https://github.com/eust-w/Real2Motrix
## Disclosure
Use the platform's AI/synthetic-content declaration where applicable. No human
identity is impersonated. Do not classify this technical explainer as content
made for children or a paid promotion. No paid distribution is authorized.

File diff suppressed because it is too large Load Diff

View File

@ -4,27 +4,28 @@
"private": true,
"type": "module",
"scripts": {
"dev": "vite --host 0.0.0.0",
"dev": "vite --host 127.0.0.1",
"build": "tsc -b && vite build",
"preview": "vite preview --host 0.0.0.0",
"preview": "vite preview --host 127.0.0.1",
"test": "vitest run"
},
"dependencies": {
"@vitejs/plugin-react": "latest",
"lucide-react": "latest",
"three": "latest",
"vite": "latest",
"react": "latest",
"react-dom": "latest"
"@vitejs/plugin-react": "6.0.2",
"lucide-react": "1.17.0",
"three": "0.184.0",
"vite": "8.3.5",
"react": "19.2.7",
"react-dom": "19.2.7"
},
"devDependencies": {
"@testing-library/jest-dom": "latest",
"@testing-library/react": "latest",
"@types/react": "latest",
"@types/react-dom": "latest",
"@types/three": "latest",
"typescript": "latest",
"vitest": "latest"
}
"@testing-library/jest-dom": "6.9.1",
"@testing-library/react": "16.3.2",
"@types/react": "19.2.16",
"@types/react-dom": "19.2.3",
"@types/three": "0.184.1",
"typescript": "6.0.3",
"vitest": "5.0.5"
},
"engines": { "node": ">=22.12.0" }
}

View File

@ -2,6 +2,7 @@ import { Eye, FileArchive, FileText } from "lucide-react";
import type { Translator } from "../lib/i18n";
import type { Asset } from "../lib/types";
import type { PreviewMode } from "./MeshPreview";
import { displayAssetPath } from "../lib/assetPath";
export function AssetTree({
assets,
@ -39,7 +40,7 @@ export function AssetTree({
<FileText size={16} />
<div>
<strong>{assetLabel(asset, t)}</strong>
<span>{asset.path}</span>
<span>{displayAssetPath(asset.path)}</span>
</div>
{previewMode ? (
<button

View File

@ -0,0 +1,5 @@
export function displayAssetPath(path: string): string {
const parts = path.replace(/\\/g, "/").split("/").filter(Boolean);
const packageIndex = parts.lastIndexOf("motrix_scene");
return packageIndex >= 0 ? parts.slice(packageIndex).join("/") : parts[parts.length - 1] ?? "";
}

View File

@ -0,0 +1,21 @@
import { describe, expect, it } from "vitest";
import { displayAssetPath } from "../lib/assetPath";
describe("displayAssetPath", () => {
it("shows package-relative paths without a user's home directory", () => {
expect(displayAssetPath("/Users/private/work/output/task/motrix_scene/meshes/object.obj"))
.toBe("motrix_scene/meshes/object.obj");
});
it("normalizes Windows paths", () => {
expect(displayAssetPath("C:\\Users\\private\\motrix_scene\\scene.xml"))
.toBe("motrix_scene/scene.xml");
});
it("only shows a filename for files outside a scene package", () => {
expect(displayAssetPath("/home/private/captures/motrix_scene.zip")).toBe("motrix_scene.zip");
expect(displayAssetPath("/home/private/motrix_scene_backup/mesh.obj")).toBe("mesh.obj");
});
it("accepts relative and empty paths", () => {
expect(displayAssetPath("motrix_scene/scene.xml")).toBe("motrix_scene/scene.xml");
expect(displayAssetPath("")).toBe("");
});
});

94
scripts/launch_demo.py Normal file
View File

@ -0,0 +1,94 @@
"""Run original synthetic geometry through the real HTTP API and worker.
Start an isolated API/worker first; this script never replaces application data
or simulates a capture session. Output is expressly not a reconstruction demo.
"""
import argparse
import hashlib
import io
import json
import time
import zipfile
from pathlib import Path
import httpx
import trimesh
def geometry() -> trimesh.Trimesh:
base = trimesh.creation.box(extents=(2.8, 2.0, 0.18))
base.apply_translation((0, 0, 0.09))
ring = trimesh.creation.torus(major_radius=0.50, minor_radius=0.16)
ring.apply_translation((-0.65, 0, 0.34))
sphere = trimesh.creation.icosphere(subdivisions=3, radius=0.40)
sphere.apply_translation((0.65, 0.25, 0.58))
post = trimesh.creation.cylinder(radius=0.22, height=0.70, sections=48)
post.apply_translation((0.60, -0.60, 0.53))
return trimesh.util.concatenate([base, ring, sphere, post])
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--api", default="http://127.0.0.1:8010")
parser.add_argument("--output", type=Path, default=Path("artifacts/launch"))
args = parser.parse_args()
args.output.mkdir(parents=True, exist_ok=True)
source = args.output / "original-geometry.obj"
geometry().export(source)
started = time.monotonic()
with httpx.Client(base_url=args.api, timeout=30) as client:
response = client.post("/api/projects", json={
"name": "原创几何测试资产",
"description": "Synthetic geometry; not a phone scan or video reconstruction",
"source_type": "mesh",
})
response.raise_for_status()
project = response.json()
prefix = f"/api/projects/{project['id']}"
with source.open("rb") as stream:
response = client.post(prefix + "/upload", data={"source_type": "mesh"},
files={"files": (source.name, stream, "text/plain")})
response.raise_for_status()
uploads = response.json()["files"]
response = client.post(prefix + "/run", json={
"source_type": "mesh", "uploaded_file_ids": [item["id"] for item in uploads],
})
response.raise_for_status()
job = response.json()
deadline = time.monotonic() + 120
while job["status"] in {"queued", "running"} and time.monotonic() < deadline:
time.sleep(0.5)
response = client.get(f"/api/jobs/{job['id']}")
response.raise_for_status()
job = response.json()
if job["status"] != "completed":
raise RuntimeError(f"Real worker did not complete: {job}")
response = client.post(prefix + "/validate")
response.raise_for_status()
validation = response.json()
if not validation["valid"]:
raise RuntimeError(f"Invalid package: {validation}")
response = client.get(prefix + "/download")
response.raise_for_status()
package = response.content
with zipfile.ZipFile(io.BytesIO(package)) as archive:
if archive.testzip() is not None:
raise RuntimeError("Corrupt archive")
entries = archive.namelist()
if any(Path(name).is_absolute() or ".." in Path(name).parts for name in entries):
raise RuntimeError("Unsafe archive path")
(args.output / "original-geometry-motrix.zip").write_bytes(package)
evidence = {
"provenance": "original synthetic trimesh geometry; not reconstructed",
"project_id": project["id"], "job_id": job["id"], "status": job["status"],
"elapsed_seconds": round(time.monotonic() - started, 2),
"validation": validation, "package_entries": entries,
"package_sha256": hashlib.sha256(package).hexdigest(),
}
(args.output / "evidence.json").write_text(json.dumps(evidence, indent=2), encoding="utf-8")
print(json.dumps(evidence, indent=2))
if __name__ == "__main__":
main()

62
scripts/record_launch.cjs Normal file
View File

@ -0,0 +1,62 @@
// Record the actual local application; no injected scene or mocked responses.
const { chromium } = require('playwright');
const fs = require('node:fs/promises');
const path = require('node:path');
async function main() {
const output = path.resolve(process.argv[2] || 'artifacts/launch');
await fs.mkdir(output, { recursive: true });
const browser = await chromium.launch({ headless: true });
try {
const context = await browser.newContext({
viewport: { width: 1920, height: 1080 },
recordVideo: { dir: path.join(output, 'recordings'), size: { width: 1920, height: 1080 } },
});
const page = await context.newPage();
const errors = [];
page.on('pageerror', error => errors.push(error.message));
await page.goto('http://127.0.0.1:5174');
await page.getByRole('button', { name: '全屏预览', exact: true }).waitFor();
await page.waitForFunction(() => document.querySelector('.asset-stats')?.textContent.includes('12'));
await page.locator('.preview-message').waitFor({ state: 'hidden' });
await page.waitForTimeout(1500);
await page.screenshot({ path: path.join(output, 'desktop.png') });
await page.getByRole('button', { name: '全屏预览', exact: true }).click();
await page.locator('.preview-message').waitFor({ state: 'hidden' });
await page.waitForTimeout(1800);
const canvas = page.locator('.mesh-preview canvas');
const box = await canvas.boundingBox();
const before = await page.screenshot({ clip: box });
await page.screenshot({ path: path.join(output, 'scene.png') });
for (let pass = 0; pass < 2; pass += 1) {
await page.mouse.move(box.x + box.width * 0.60, box.y + box.height * 0.55);
await page.mouse.down();
for (let step = 0; step < 45; step += 1) {
await page.mouse.move(box.x + box.width * (0.60 - step * 0.0015), box.y + box.height * 0.55);
await page.waitForTimeout(35);
}
await page.mouse.up();
}
const after = await page.screenshot({ clip: box });
if (before.equals(after)) throw new Error('3D viewport did not respond to orbit input');
await page.getByRole('button', { name: '退出全屏', exact: true }).click();
await page.getByRole('button', { name: '验证', exact: true }).click();
await page.waitForTimeout(500);
await page.locator('.panel').filter({ has: page.getByRole('button', { name: '验证', exact: true }) })
.screenshot({ path: path.join(output, 'validation.png') });
await fs.writeFile(path.join(output, 'browser-evidence.json'), JSON.stringify({
pageErrors: errors, orbitFramesDiffer: true, viewport: { width: 1920, height: 1080 },
}, null, 2));
if (errors.length) throw new Error(errors.join('\n'));
const video = page.video();
await page.goto('about:blank');
await page.close();
await context.close();
await video.saveAs(path.join(output, 'desktop-recording.webm'));
console.log('Recorded real UI and orbit interaction:', output);
} finally {
await browser.close();
}
}
main().catch(error => { console.error(error); process.exitCode = 1; });

View File

@ -0,0 +1,202 @@
"""Compose a narrated launch explainer from the real, locally recorded UI.
Requires macOS say, FFmpeg/FFprobe and Pillow. No private capture footage or
third-party music is used. Pass a CJK font file with --font on other setups.
"""
import argparse
import json
import re
import subprocess
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont, ImageOps
SCENES = [
("3D 模型进仿真,还差哪一步?", "VISUAL / COLLISION / STRUCTURE",
"把三维模型带进机器人仿真,不只是能看。还需要碰撞几何、场景结构,以及可检查的输出。", "motion"),
("Real2Motrix", "本地采集与资产处理工作台 / ALPHA",
"这是 Real2Motrix,一个开源的本地采集与资产处理工作台。目前处于 Alpha 阶段。", "desktop"),
("真实处理,不伪装成扫描", "原创几何测试资产 / 非实拍重建",
"你现在看到的是原创几何测试资产,不是实拍重建。它通过真实后端处理,在桌面端交互预览。", "motion"),
("不止一个模型文件", "MJCF / URDF / MESH / METADATA",
"视觉网格与碰撞网格分别管理,输出 MJCF、URDF 和元数据。导出包还会进行结构校验。", "package"),
("手机采集:实验能力", "轨迹覆盖率 ≠ 表面完整度",
"项目提供手机原生采集和在线上传代码。但真机效果还需要验收,轨迹覆盖率也不等于扫描完整度。", "boundary"),
("把下一步,变成可验收的结果", "RECONSTRUCTION / COVERAGE / SIMULATION",
"接下来重点是表面覆盖反馈、物体和场景分流,以及真实数据集上的重建与仿真验证。", "roadmap"),
("从可复现,走向可信赖", "github.com/eust-w/Real2Motrix",
"代码已经开放。如果你在做机器人仿真、三维重建或移动采集,欢迎运行示例,用真实测试一起改进。", "motion"),
]
def run(command):
subprocess.run([str(value) for value in command], check=True, stdout=subprocess.DEVNULL)
def duration(path):
return float(subprocess.check_output([
"ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(path)
], text=True).strip())
def wrap(draw, text, font, width):
lines, line = [], ""
for char in text:
if line and draw.textlength(line + char, font=font) > width:
lines.append(line)
line = ""
line += char
if line:
lines.append(line)
return lines
def timestamp(seconds):
millis = round(seconds * 1000)
return f"{millis // 3600000:02}:{millis // 60000 % 60:02}:{millis // 1000 % 60:02},{millis % 1000:03}"
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, default=Path("artifacts/launch"))
parser.add_argument("--font", type=Path, default=Path("/System/Library/Fonts/Hiragino Sans GB.ttc"))
parser.add_argument("--voice", default="Tingting")
parser.add_argument("--orbit", type=Path, help="Optional already-trimmed fullscreen orbit recording")
args = parser.parse_args()
out = args.output.resolve()
build = out / "render"
build.mkdir(parents=True, exist_ok=True)
evidence = json.loads((out / "evidence.json").read_text())
if not evidence["validation"]["valid"]:
raise RuntimeError("Do not render a successful-demo claim without validation evidence")
audio_durations = []
subtitles = []
elapsed = 0
for index, (_, _, narration, _) in enumerate(SCENES):
voice = build / f"voice-{index}.aiff"
run(["say", "-v", args.voice, "-r", "205", "-o", voice, narration])
spoken = duration(voice)
audio_durations.append(spoken + 0.65)
chunks = [part for part in re.split(r"[。!?]", narration) if part]
weights = [len(part) for part in chunks]
cursor = 0
for part, weight in zip(chunks, weights):
end = cursor + spoken * weight / sum(weights)
subtitles.append((elapsed + cursor, elapsed + end, part))
cursor = end
elapsed += spoken + 0.65
(out / "Real2Motrix.zh-CN.srt").write_text("\n\n".join(
f"{i + 1}\n{timestamp(start)} --> {timestamp(end)}\n{text}"
for i, (start, end, text) in enumerate(subtitles)
) + "\n", encoding="utf-8")
# The raw capture includes setup. Only the fullscreen orbit is distributed.
motion = args.orbit.resolve() if args.orbit else build / "orbit.mp4"
if not args.orbit:
run(["ffmpeg", "-y", "-v", "error", "-ss", "8", "-i", out / "desktop-recording.webm",
"-t", "10", "-an", "-c:v", "libx264", "-crf", "18", "-pix_fmt", "yuv420p", motion])
font = lambda size: ImageFont.truetype(str(args.font), size)
bg, fg, muted, teal, amber = "#171b1c", "#f4f6f5", "#acb8b7", "#53d5bc", "#ffce71"
for orientation, (width, height) in {"landscape": (1920, 1080), "portrait": (1080, 1920)}.items():
vertical = orientation == "portrait"
margin = 64
media = (64, 490, 952, 720) if vertical else (64, 275, 1792, 640)
chapter_start = 0
clips = []
for index, (title, subhead, narration, kind) in enumerate(SCENES):
seconds = audio_durations[index]
plate = Image.new("RGB", (width, height), bg)
draw = ImageDraw.Draw(plate)
draw.text((margin, 50), "REAL2MOTRIX / OPEN-SOURCE ALPHA", font=font(25), fill=teal)
title_lines = wrap(draw, title, font(64 if vertical else 62), width - margin * 2)
y = 130
for line in title_lines:
draw.text((margin, y), line, font=font(64 if vertical else 62), fill=fg)
y += 90
draw.text((margin, y + 15), subhead, font=font(27), fill=muted)
mx, my, mw, mh = media
if kind in {"motion", "desktop"}:
screenshot = Image.open(out / ("desktop.png" if kind == "desktop" else "scene.png"))
if kind == "motion":
screenshot = screenshot.crop((330, 260, 1590, 1000))
screenshot = ImageOps.contain(screenshot, (mw, mh))
plate.paste(screenshot, (mx + (mw - screenshot.width) // 2, my + (mh - screenshot.height) // 2))
else:
if kind == "package":
lines = [("01", "scene.xml / scene.urdf"), ("02", "视觉网格 + 碰撞网格"),
("03", "物体清单 + 重建元数据"), ("04", "结构校验:通过")]
elif kind == "boundary":
lines = [("有源码", "iOS / ARKit 原生采集"), ("有接口", "帧与网格的在线上传"),
("待验收", "真机采集与补扫效果"), ("需区分", "轨迹覆盖 ≠ 表面覆盖")]
else:
lines = [("01", "真实采集基准与失败案例"), ("02", "场景 / 物体分别处理"),
("03", "表面覆盖与不确定性反馈"), ("04", "目标仿真器内的物理验证")]
for row, (label, value) in enumerate(lines):
row_y = my + 35 + row * 145
draw.line((mx, row_y - 15, mx + mw, row_y - 15), fill="#3b4546", width=2)
draw.text((mx, row_y), label, font=font(27), fill=teal)
draw.text((mx if vertical else mx + 170, row_y + 49 if vertical else row_y), value,
font=font(38 if vertical else 46), fill=fg)
draw = ImageDraw.Draw(plate)
label_y = 1265 if vertical else 934
draw.text((margin, label_y), "原创几何测试资产 · 非实拍重建", font=font(26), fill=amber)
if vertical:
draw.text((margin, 1340), "本地处理 / 可检查输出 / 实验性手机采集", font=font(25), fill=muted)
draw.text((margin, height - 38), f"{index + 1:02} / 07 真实软件录屏 + 合成配音", font=font(19), fill=muted)
image_path = build / f"{orientation}-{index}.png"
plate.save(image_path)
if index == 0:
plate.save(out / f"cover-{orientation}.png")
inputs = ["ffmpeg", "-y", "-v", "error", "-loop", "1", "-framerate", "30", "-i", image_path]
filters = []
current = "0:v"
next_input = 1
if kind == "motion":
inputs.extend(["-stream_loop", "-1", "-i", motion])
filters.append(f"[1:v]crop=1260:740:330:260,scale={mw}:{mh}:force_original_aspect_ratio=decrease,pad={mw}:{mh}:(ow-iw)/2:(oh-ih)/2:color=0x171b1c[screen]")
filters.append(f"[0:v][screen]overlay={mx}:{my}[media]")
current = "media"
next_input += 1
for caption_index, (start, end, text) in enumerate(subtitles):
if start < chapter_start - 0.01 or start >= chapter_start + seconds:
continue
subtitle = Image.new("RGBA", (width, 180), (0, 0, 0, 0))
painter = ImageDraw.Draw(subtitle)
lines = wrap(painter, text, font(40 if vertical else 38), width - 128)
for line_index, line in enumerate(lines):
x = (width - painter.textlength(line, font=font(40 if vertical else 38))) // 2
painter.text((x, line_index * 58), line, font=font(40 if vertical else 38), fill=fg)
subtitle_path = build / f"caption-{orientation}-{caption_index}.png"
subtitle.save(subtitle_path)
inputs.extend(["-loop", "1", "-framerate", "30", "-i", subtitle_path])
label = f"sub{caption_index}"
filters.append(f"[{current}][{next_input}:v]overlay=0:{1510 if vertical else 986}:enable='between(t,{start-chapter_start:.3f},{end-chapter_start:.3f})'[{label}]")
current = label
next_input += 1
inputs.extend(["-i", build / f"voice-{index}.aiff"])
filters.append(f"[{current}]fade=t=in:st=0:d=0.22,fade=t=out:st={seconds-.22:.3f}:d=0.22,format=yuv420p[video]")
clip = build / f"{orientation}-{index}.mp4"
run(inputs + ["-filter_complex", ";".join(filters), "-map", "[video]", "-map", f"{next_input}:a",
"-af", "apad,loudnorm=I=-16:TP=-1.5:LRA=11", "-t", f"{seconds:.3f}",
"-r", "30", "-c:v", "libx264", "-preset", "veryfast", "-crf", "19",
"-threads", "4", "-c:a", "aac", "-b:a", "192k", "-ar", "48000", clip])
clips.append(clip)
chapter_start += seconds
concat = build / f"{orientation}.txt"
concat.write_text("\n".join(f"file '{p}'" for p in clips) + "\n")
target = out / f"Real2Motrix-intro-{orientation}-1080p.mp4"
run(["ffmpeg", "-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", concat,
"-c", "copy", "-movflags", "+faststart", target])
print(f"Rendered {target.name}: {duration(target):.2f}s", flush=True)
(out / "media-provenance.json").write_text(json.dumps({
"source": "real application recording of original synthetic geometry",
"not_demonstrated": ["real phone scan", "video reconstruction fidelity", "physics runtime", "3DGS"],
"voice": f"macOS say {args.voice}; synthetic narration", "music": "none",
"narration": [scene[2] for scene in SCENES], "package_sha256": evidence["package_sha256"],
}, ensure_ascii=False, indent=2), encoding="utf-8")
if __name__ == "__main__":
main()