insta360-3dgs 0.1.0__tar.gz

insta360_3dgs-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv
+.venv/
+
+# 输出产物
+output/
+out/
+*.ply
+*.log

insta360_3dgs-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

insta360_3dgs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FemtoRhythm
+
+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.

insta360_3dgs-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: insta360-3dgs
+Version: 0.1.0
+Summary: Insta360 .insv -> 全景 3D Gaussian Splatting 点云流水线 (MediaSDK 拼接 + 等矩形 SfM + 3DGS)
+Project-URL: Homepage, https://github.com/FemtoRhythm/insta360-3dgs
+Project-URL: Repository, https://github.com/FemtoRhythm/insta360-3dgs
+Author: FemtoRhythm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3dgs,colmap,gaussian-splatting,insta360,panorama,point-cloud
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: plyfile>=0.8
+Requires-Dist: scipy>=1.10
+Requires-Dist: tqdm>=4.64
+Description-Content-Type: text/markdown
+
+# insta360-3dgs
+
+把 Insta360 拍出来的 `.insv` 双鱼眼视频，自动重建成全景 3D Gaussian Splatting，最后导出一个标准的 `x,y,z + rgb` 点云（PLY），可以直接扔进 CloudCompare、MeshLab 这类工具看。
+
+## 它做了什么
+
+Insta360 的双镜头是两颗鱼眼分开存的（`_00_` 前镜头、`_10_` 后镜头），要变成能用的 3D 结果，得一路处理：
+
+1. 用官方 MediaSDK 把两颗鱼眼拼成一张 360° 等矩形视频
+2. 抽帧
+3. 用 COLMAP 的等矩形相机模型做位姿重建
+4. 把每帧全景展开成 6 个共光心的透视面，喂给 3DGS
+5. 训练高斯模型
+6. 导出标准点云
+
+### 为什么先做等矩形 SfM
+
+全景图每个像素对应一个方向，光心在球心。如果图省事直接把 6 个 cube 面当成独立相机去做 SfM，共光心的面会被误当成自由相机，凭空多出伪基线，位姿会乱。所以先在等矩形空间用 EQUIRECTANGULAR 相机模型跑一遍 SfM 拿到平滑的相机轨迹，再基于这个轨迹展开 6 个透视面，保证每一帧的 6 个面光心都重合在同一点。
+
+## 依赖
+
+分两类：轻量依赖交给 uv 装，重型依赖复用机器上已经配好的环境。
+
+| 依赖 | 用途 | 说明 |
+| --- | --- | --- |
+| `uv` | Python 环境管理 | `uv sync` 装轻量依赖 |
+| `ffmpeg` | 抽帧 | 系统 PATH 里可用即可 |
+| Insta360 MediaSDK | 拼接 `.insv` | 官方 SDK，手动放好 `MediaSDKTest.exe` |
+| gaussian-splatting | 训练 | 复用已有 `.venv`（含 torch CUDA + 编译好的 `diff-gaussian-rasterization` / `simple-knn`） |
+| `pycolmap`（cp311） | 等矩形 SfM | 预编译包目录 |
+
+## 安装
+
+```bash
+git clone https://github.com/FemtoRhythm/insta360-3dgs
+cd insta360-3dgs
+uv sync
+```
+
+## 配置外部依赖
+
+项目通过环境变量找重型依赖，默认路径都假设它们和仓库同级（`../`）。对不上的话用环境变量覆盖：
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `INSTA360_3DGS_MEDIASDK_EXE` | `../sdk/MediaSDK/bin/MediaSDKTest.exe` | MediaSDK 拼接程序 |
+| `INSTA360_3DGS_GS_DIR` | `../20260823_1/gaussian-splatting` | gaussian-splatting 目录 |
+| `INSTA360_3DGS_PYLIBS` | `../20260823_1/pylibs` | pycolmap 预编译包 |
+| `INSTA360_3DGS_RUNTIME_PYTHON` | `<GS_DIR>/.venv/Scripts/python.exe` | 跑重型阶段的解释器 |
+
+## 使用
+
+一条命令跑完，输入可以是单个 `.insv` 文件，也可以是装了一堆 `.insv` 的目录：
+
+```bash
+uv run insta360-3dgs run --input VID_20260823_215314_00_006.insv --output out/
+# 或整个目录，训练完顺手做质量评估
+uv run insta360-3dgs run --input ./raw_clips --output out/ --verify
+```
+
+想单独跑某一步也行，每个子命令都是幂等的（产物已存在就直接跳过）：
+
+```bash
+uv run insta360-3dgs stitch  --input ./raw_clips --output out/stitched
+uv run insta360-3dgs extract --input out/stitched/xxx.mp4 --output out/
+uv run insta360-3dgs sfm     --output out/ --threads 8
+uv run insta360-3dgs cubemap --output out/
+uv run insta360-3dgs train   --output out/ --iterations 30000
+uv run insta360-3dgs export  --output out/ --iteration 30000
+```
+
+另外两个可选的子命令：`verify` 算 PSNR/SSIM/L1，`preview` 渲染全景图和原图对比。
+
+## 常用参数
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--stitch-type` | `optflow` | 拼接算法：`template` / `optflow` / `dynamicstitch` / `aistitch` |
+| `--output-size` | `3840x1920` | 拼接分辨率 `WxH` |
+| `--fps` | `0.5` | 抽帧频率 |
+| `--width` | `2880` | 全景帧宽度（高度 = 宽度 / 2） |
+| `--iterations` | `30000` | 3DGS 训练迭代数 |
+| `--threads` | `8` | SfM 线程数 |
+
+## 输出结构
+
+```
+<output>/
+  stitched/         拼接出的等矩形 mp4
+  frames/           抽出的全景帧
+  sfm/              等矩形 SfM（结果在 sfm/0/）
+  cubemap/          cube 面训练数据（images/ + sparse/0/）
+  model/            3DGS 训练输出
+  pointcloud.ply    最终点云（x,y,z + rgb）
+```
+
+## 已知问题
+
+- 双镜头文件必须成对（`_00_` 前 + `_10_` 后），只传一个会拼不完整；传目录时会自动配对。
+- 训练阶段内部会切到 gaussian-splatting 目录，`--output` 记得传绝对路径（CLI 已经帮你处理了）。
+- 想重跑某一步，删掉对应的输出子目录就行，比如 `rm -rf out/model` 再跑一次 train。

insta360_3dgs-0.1.0/README.md

@@ -0,0 +1,101 @@
+# insta360-3dgs
+
+把 Insta360 拍出来的 `.insv` 双鱼眼视频，自动重建成全景 3D Gaussian Splatting，最后导出一个标准的 `x,y,z + rgb` 点云（PLY），可以直接扔进 CloudCompare、MeshLab 这类工具看。
+
+## 它做了什么
+
+Insta360 的双镜头是两颗鱼眼分开存的（`_00_` 前镜头、`_10_` 后镜头），要变成能用的 3D 结果，得一路处理：
+
+1. 用官方 MediaSDK 把两颗鱼眼拼成一张 360° 等矩形视频
+2. 抽帧
+3. 用 COLMAP 的等矩形相机模型做位姿重建
+4. 把每帧全景展开成 6 个共光心的透视面，喂给 3DGS
+5. 训练高斯模型
+6. 导出标准点云
+
+### 为什么先做等矩形 SfM
+
+全景图每个像素对应一个方向，光心在球心。如果图省事直接把 6 个 cube 面当成独立相机去做 SfM，共光心的面会被误当成自由相机，凭空多出伪基线，位姿会乱。所以先在等矩形空间用 EQUIRECTANGULAR 相机模型跑一遍 SfM 拿到平滑的相机轨迹，再基于这个轨迹展开 6 个透视面，保证每一帧的 6 个面光心都重合在同一点。
+
+## 依赖
+
+分两类：轻量依赖交给 uv 装，重型依赖复用机器上已经配好的环境。
+
+| 依赖 | 用途 | 说明 |
+| --- | --- | --- |
+| `uv` | Python 环境管理 | `uv sync` 装轻量依赖 |
+| `ffmpeg` | 抽帧 | 系统 PATH 里可用即可 |
+| Insta360 MediaSDK | 拼接 `.insv` | 官方 SDK，手动放好 `MediaSDKTest.exe` |
+| gaussian-splatting | 训练 | 复用已有 `.venv`（含 torch CUDA + 编译好的 `diff-gaussian-rasterization` / `simple-knn`） |
+| `pycolmap`（cp311） | 等矩形 SfM | 预编译包目录 |
+
+## 安装
+
+```bash
+git clone https://github.com/FemtoRhythm/insta360-3dgs
+cd insta360-3dgs
+uv sync
+```
+
+## 配置外部依赖
+
+项目通过环境变量找重型依赖，默认路径都假设它们和仓库同级（`../`）。对不上的话用环境变量覆盖：
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `INSTA360_3DGS_MEDIASDK_EXE` | `../sdk/MediaSDK/bin/MediaSDKTest.exe` | MediaSDK 拼接程序 |
+| `INSTA360_3DGS_GS_DIR` | `../20260823_1/gaussian-splatting` | gaussian-splatting 目录 |
+| `INSTA360_3DGS_PYLIBS` | `../20260823_1/pylibs` | pycolmap 预编译包 |
+| `INSTA360_3DGS_RUNTIME_PYTHON` | `<GS_DIR>/.venv/Scripts/python.exe` | 跑重型阶段的解释器 |
+
+## 使用
+
+一条命令跑完，输入可以是单个 `.insv` 文件，也可以是装了一堆 `.insv` 的目录：
+
+```bash
+uv run insta360-3dgs run --input VID_20260823_215314_00_006.insv --output out/
+# 或整个目录，训练完顺手做质量评估
+uv run insta360-3dgs run --input ./raw_clips --output out/ --verify
+```
+
+想单独跑某一步也行，每个子命令都是幂等的（产物已存在就直接跳过）：
+
+```bash
+uv run insta360-3dgs stitch  --input ./raw_clips --output out/stitched
+uv run insta360-3dgs extract --input out/stitched/xxx.mp4 --output out/
+uv run insta360-3dgs sfm     --output out/ --threads 8
+uv run insta360-3dgs cubemap --output out/
+uv run insta360-3dgs train   --output out/ --iterations 30000
+uv run insta360-3dgs export  --output out/ --iteration 30000
+```
+
+另外两个可选的子命令：`verify` 算 PSNR/SSIM/L1，`preview` 渲染全景图和原图对比。
+
+## 常用参数
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--stitch-type` | `optflow` | 拼接算法：`template` / `optflow` / `dynamicstitch` / `aistitch` |
+| `--output-size` | `3840x1920` | 拼接分辨率 `WxH` |
+| `--fps` | `0.5` | 抽帧频率 |
+| `--width` | `2880` | 全景帧宽度（高度 = 宽度 / 2） |
+| `--iterations` | `30000` | 3DGS 训练迭代数 |
+| `--threads` | `8` | SfM 线程数 |
+
+## 输出结构
+
+```
+<output>/
+  stitched/         拼接出的等矩形 mp4
+  frames/           抽出的全景帧
+  sfm/              等矩形 SfM（结果在 sfm/0/）
+  cubemap/          cube 面训练数据（images/ + sparse/0/）
+  model/            3DGS 训练输出
+  pointcloud.ply    最终点云（x,y,z + rgb）
+```
+
+## 已知问题
+
+- 双镜头文件必须成对（`_00_` 前 + `_10_` 后），只传一个会拼不完整；传目录时会自动配对。
+- 训练阶段内部会切到 gaussian-splatting 目录，`--output` 记得传绝对路径（CLI 已经帮你处理了）。
+- 想重跑某一步，删掉对应的输出子目录就行，比如 `rm -rf out/model` 再跑一次 train。

insta360_3dgs-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "insta360-3dgs"
+version = "0.1.0"
+description = "Insta360 .insv -> 全景 3D Gaussian Splatting 点云流水线 (MediaSDK 拼接 + 等矩形 SfM + 3DGS)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "FemtoRhythm" }]
+keywords = ["insta360", "3dgs", "gaussian-splatting", "colmap", "panorama", "point-cloud"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "pillow>=9.0",
+    "plyfile>=0.8",
+    "tqdm>=4.64",
+]
+
+[project.urls]
+Homepage = "https://github.com/FemtoRhythm/insta360-3dgs"
+Repository = "https://github.com/FemtoRhythm/insta360-3dgs"
+
+[project.scripts]
+insta360-3dgs = "insta360_3dgs.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/insta360_3dgs"]
+
+# 说明: torch(CUDA) / pycolmap / 已编译的 diff-gaussian-rasterization、simple-knn
+# 属于"重型运行时依赖", 默认复用已有的已编译环境 (见 config.py 与 README)。
+# 如需在 uv 环境内自行安装 torch(CUDA), 取消下面注释并按需选择 CUDA 索引:
+#
+# [tool.uv.sources]
+# torch = { index = "pytorch-cu128" }
+#
+# [[tool.uv.index]]
+# name = "pytorch-cu128"
+# url = "https://download.pytorch.org/whl/cu128"
+# explicit = true

insta360_3dgs-0.1.0/skill/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: insta360-3dgs
+description: 'Insta360 .insv 双鱼眼视频到全景 3D Gaussian Splatting 点云的重建流水线。基于 MediaSDK 拼接 + pycolmap 等矩形 SfM + 3DGS 训练。'
+license: MIT
+allowed-tools: Bash
+---
+
+# insta360-3dgs
+
+把 Insta360 的 `.insv` 双鱼眼视频重建为全景 3DGS 点云。源码单一真源在 GitHub 仓库 `FemtoRhythm/insta360-3dgs`，本 skill 用引导脚本定位/拉取源码并运行，不内嵌源码。
+
+## 用法
+
+```bash
+python <skill目录>/scripts/bootstrap.py check    # 诊断环境
+python <skill目录>/scripts/bootstrap.py setup    # 拉取源码 + uv sync
+python <skill目录>/scripts/bootstrap.py run --input <xx.insv或目录> --output <输出目录>
+```
+
+完整的流水线说明、环境变量、排错都在仓库的 README 里。

insta360_3dgs-0.1.0/skill/scripts/bootstrap.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""insta360-3dgs skill 引导脚本。
+
+职责：
+    check   诊断环境（源码 / uv / ffmpeg / MediaSDK / gaussian-splatting /
+            pycolmap / runtime python / GPU）
+    setup   准备源码（定位或 git clone）并 uv sync 安装轻量依赖
+    run     注入外部依赖路径后运行端到端流水线（.insv -> 全景 3DGS -> 点云）
+
+仅依赖 Python 标准库，可在 Python 3.8+ 直接运行。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+GITHUB_REPO = "https://github.com/FemtoRhythm/insta360-3dgs"
+
+# 本机已知部署位置，作为「自动识别」的候选路径；可自行增删。
+_KNOWN_PROJECT_CANDIDATES = [
+    Path(r"d:\Documents\WorkSpace\python\i2\20260828_3\insta360-3dgs"),
+]
+_KNOWN_MEDIASDK_CANDIDATES = [
+    Path(r"d:\Documents\WorkSpace\python\i2\20260828_3\sdk\MediaSDK\bin\MediaSDKTest.exe"),
+]
+_KNOWN_GS_DIR_CANDIDATES = [
+    Path(r"d:\Documents\WorkSpace\python\i2\20260828_3\20260823_1\gaussian-splatting"),
+]
+_KNOWN_PYLIBS_CANDIDATES = [
+    Path(r"d:\Documents\WorkSpace\python\i2\20260828_3\20260823_1\pylibs"),
+]
+
+
+# --------------------------------------------------------------------------- #
+# 定位
+# --------------------------------------------------------------------------- #
+def _is_project(path: Path) -> bool:
+    return (path / "pyproject.toml").is_file() and (path / "src" / "insta360_3dgs").is_dir()
+
+
+def find_project() -> Path | None:
+    """按优先级定位源码项目根：环境变量 -> cwd -> 已知候选。"""
+    env = os.environ.get("INSTA360_3DGS_PROJECT_DIR")
+    if env and _is_project(Path(env)):
+        return Path(env)
+
+    cwd = Path.cwd()
+    if _is_project(cwd):
+        return cwd
+
+    for p in _KNOWN_PROJECT_CANDIDATES:
+        if _is_project(p):
+            return p
+    return None
+
+
+def _first_existing(candidates: list[Path]) -> Path | None:
+    for p in candidates:
+        if p.exists():
+            return p
+    return None
+
+
+def _runtime_python_candidates(gs_dir: Path) -> list[Path]:
+    return [gs_dir / ".venv" / "Scripts" / "python.exe",   # Windows
+            gs_dir / ".venv" / "bin" / "python"]           # POSIX
+
+
+def resolve_deps(project: Path | None) -> dict[str, Path | None]:
+    """解析四个外部依赖路径。优先级：环境变量 > config 默认推导 > 已知候选。"""
+    parent = project.parent if project else Path.cwd().parent
+
+    def _pick(name: str, default: list[Path], known: list[Path]) -> Path | None:
+        env = os.environ.get(name)
+        if env:
+            return Path(env)
+        return _first_existing(default + known)
+
+    gs_dir = _pick(
+        "INSTA360_3DGS_GS_DIR",
+        [parent / "20260823_1" / "gaussian-splatting"],
+        _KNOWN_GS_DIR_CANDIDATES,
+    )
+    return {
+        "mediasdk_exe": _pick(
+            "INSTA360_3DGS_MEDIASDK_EXE",
+            [parent / "sdk" / "MediaSDK" / "bin" / "MediaSDKTest.exe"],
+            _KNOWN_MEDIASDK_CANDIDATES,
+        ),
+        "gs_dir": gs_dir,
+        "pylibs": _pick(
+            "INSTA360_3DGS_PYLIBS",
+            [parent / "20260823_1" / "pylibs"],
+            _KNOWN_PYLIBS_CANDIDATES,
+        ),
+        "runtime_python": (
+            Path(os.environ["INSTA360_3DGS_RUNTIME_PYTHON"])
+            if os.environ.get("INSTA360_3DGS_RUNTIME_PYTHON")
+            else _first_existing(_runtime_python_candidates(gs_dir) if gs_dir else [])
+        ),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# check
+# --------------------------------------------------------------------------- #
+def _ok(b: bool) -> str:
+    return "OK " if b else "MISS"
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    project = find_project()
+    deps = resolve_deps(project)
+
+    uv = shutil.which("uv")
+    ffmpeg = shutil.which("ffmpeg")
+    git = shutil.which("git")
+    nvidia_smi = shutil.which("nvidia-smi")
+
+    print("=== insta360-3dgs 环境诊断 ===")
+    print(f"[{_ok(project is not None)}] 项目源码        {project or '未找到'}")
+    print(f"[{_ok(uv is not None)}] uv               {uv or ''}")
+    print(f"[{_ok(ffmpeg is not None)}] ffmpeg           {ffmpeg or ''}")
+    print(f"[{_ok(git is not None)}] git              {git or ''}")
+    print(f"[{_ok(nvidia_smi is not None)}] NVIDIA GPU       {nvidia_smi or ''}")
+    print(f"[{_ok(deps['mediasdk_exe'] is not None)}] MediaSDKTest.exe {deps['mediasdk_exe'] or ''}")
+    print(f"[{_ok(deps['gs_dir'] is not None)}] gaussian-splatting {deps['gs_dir'] or ''}")
+    print(f"[{_ok(deps['pylibs'] is not None)}] pylibs(pycolmap) {deps['pylibs'] or ''}")
+    print(f"[{_ok(deps['runtime_python'] is not None)}] runtime python   {deps['runtime_python'] or ''}")
+
+    missing = [
+        ("项目源码", project is None),
+        ("uv", uv is None),
+        ("ffmpeg", ffmpeg is None),
+        ("MediaSDKTest.exe", deps["mediasdk_exe"] is None),
+        ("gaussian-splatting", deps["gs_dir"] is None),
+        ("pylibs(pycolmap)", deps["pylibs"] is None),
+        ("runtime python", deps["runtime_python"] is None),
+    ]
+    miss_list = [name for name, is_miss in missing if is_miss]
+    if miss_list:
+        print(f"\n缺失项: {', '.join(miss_list)}")
+        print("提示: 运行 `python bootstrap.py setup` 可自动准备源码与轻量依赖；"
+              "重型依赖(MediaSDK/gaussian-splatting/pycolmap)需预先放置并用环境变量指定。")
+        return 1
+    print("\n环境就绪，可运行: python bootstrap.py run --input <xx.insv> --output <out>")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# setup
+# --------------------------------------------------------------------------- #
+def cmd_setup(args: argparse.Namespace) -> int:
+    project = find_project()
+    if project is None:
+        dest = Path(os.environ.get("INSTA360_3DGS_PROJECT_DIR", Path.home() / "insta360-3dgs"))
+        if not shutil.which("git"):
+            print("错误: 未安装 git，无法 clone 源码。请先安装 git 或用 INSTA360_3DGS_PROJECT_DIR 指定已有源码。")
+            return 1
+        print(f"克隆源码: {GITHUB_REPO} -> {dest}")
+        subprocess.run(["git", "clone", GITHUB_REPO, str(dest)], check=True)
+        project = dest
+
+    print(f"项目目录: {project}")
+    uv = shutil.which("uv")
+    if not uv:
+        print("错误: 未安装 uv，无法同步依赖。请先安装 uv (https://docs.astral.sh/uv/)。")
+        return 1
+    print("同步轻量依赖: uv sync")
+    subprocess.run(["uv", "sync"], cwd=project, check=True)
+
+    # 校验外部依赖
+    deps = resolve_deps(project)
+    for key, label in [("mediasdk_exe", "MediaSDKTest.exe"),
+                       ("gs_dir", "gaussian-splatting"),
+                       ("pylibs", "pylibs(pycolmap)"),
+                       ("runtime_python", "runtime python")]:
+        if deps[key] is None:
+            print(f"警告: 未检测到 {label}，请放置后用对应 INSTA360_3DGS_* 环境变量指定。")
+    print("setup 完成。")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# run
+# --------------------------------------------------------------------------- #
+def cmd_run(args: argparse.Namespace) -> int:
+    project = find_project()
+    if project is None:
+        print("错误: 未找到项目源码。请先运行 `python bootstrap.py setup`。")
+        return 1
+
+    deps = resolve_deps(project)
+    env = os.environ.copy()
+    mapping = {
+        "INSTA360_3DGS_MEDIASDK_EXE": deps["mediasdk_exe"],
+        "INSTA360_3DGS_GS_DIR": deps["gs_dir"],
+        "INSTA360_3DGS_PYLIBS": deps["pylibs"],
+        "INSTA360_3DGS_RUNTIME_PYTHON": deps["runtime_python"],
+    }
+    for k, v in mapping.items():
+        if v is None:
+            print(f"错误: 依赖缺失 {k}，请先运行 `python bootstrap.py check` 诊断。")
+            return 1
+        env[k] = str(v)
+
+    argv = ["uv", "run", "insta360-3dgs", "run",
+            "--input", *args.input, "--output", str(Path(args.output).resolve())]
+    if args.iterations:
+        argv += ["--iterations", str(args.iterations)]
+    if args.verify:
+        argv += ["--verify"]
+
+    print("==>", " ".join(argv))
+    subprocess.run(argv, cwd=project, env=env, check=True)
+    print(f"\n完成! 点云输出: {Path(args.output).resolve() / 'pointcloud.ply'}")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# 入口
+# --------------------------------------------------------------------------- #
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bootstrap.py", description="insta360-3dgs skill 引导脚本")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("check", help="诊断环境").set_defaults(func=cmd_check)
+    sub.add_parser("setup", help="准备源码与轻量依赖").set_defaults(func=cmd_setup)
+
+    p_run = sub.add_parser("run", help="运行端到端流水线")
+    p_run.add_argument("--input", required=True, nargs="+", help="一个或多个 .insv 文件或目录")
+    p_run.add_argument("--output", required=True, help="输出目录")
+    p_run.add_argument("--iterations", type=int, default=None, help="3DGS 训练迭代数")
+    p_run.add_argument("--verify", action="store_true", help="训练后质量评估")
+    p_run.set_defaults(func=cmd_run)
+
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

insta360_3dgs-0.1.0/src/insta360_3dgs/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""Insta360 .insv -> 全景 3D Gaussian Splatting 点云流水线。"""
+
+__version__ = "0.1.0"

insta360_3dgs-0.1.0/src/insta360_3dgs/__main__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""支持 `python -m insta360_3dgs ...` 入口。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

insta360_3dgs-0.1.0/src/insta360_3dgs/_dispatch.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""重型阶段重执行。
+
+uv 环境只装轻量依赖，sfm/train 这些需要 torch/pycolmap 的阶段交给
+gaussian-splatting/.venv 里的解释器跑，并注入 PYTHONPATH 指向本项目 src/。
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import config
+
+# src/ 目录 (insta360_3dgs 包的父目录)
+_SRC_DIR = str(Path(__file__).resolve().parent.parent)
+
+
+def _absolutize(args: list[str]) -> list[str]:
+    """把 `--output <path>` 转成绝对路径。
+
+    train/verify 等阶段会在模块加载时 os.chdir 到 gaussian-splatting 目录,
+    若这里传相对路径, 后续 `output/cubemap` 会被解析到错误位置。统一转绝对路径规避。
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(args):
+        out.append(args[i])
+        if args[i] == "--output" and i + 1 < len(args):
+            out.append(str(Path(args[i + 1]).resolve()))
+            i += 1
+        i += 1
+    return out
+
+
+def run_stage(module: str, args: list[str]) -> None:
+    python = config.runtime_python()
+    if not Path(python).exists():
+        raise SystemExit(
+            f"运行时解释器不存在: {python}\n"
+            f"请检查 gaussian-splatting/.venv 是否已创建, 或用环境变量 "
+            f"INSTA360_3DGS_RUNTIME_PYTHON 指定含 torch(CUDA)+pycolmap 的解释器")
+
+    env = os.environ.copy()
+    env["PYTHONPATH"] = _SRC_DIR + os.pathsep + env.get("PYTHONPATH", "")
+
+    command = [python, "-m", f"insta360_3dgs.{module}", *_absolutize(args)]
+    print(f"\n==> {' '.join(command)}", flush=True)
+    subprocess.run(command, env=env, check=True)
+
+
+if __name__ == "__main__":
+    sys.exit("此模块不应直接运行, 请通过 cli 调用")