Mrpzx
977f97995a
覆盖文生 3D、图生 3D、多视图、批量生成，以及重拓扑、绑定、动画、智能分割、 纹理、PBR、智能 UV、部件补全、格式导出与下载。 代码组织：一个功能一个模块（tripo/features/），入口薄壳 tripocli.py。
145 lines
8.6 KiB
Markdown
145 lines
8.6 KiB
Markdown
---
|
||
name: tripo-3d
|
||
description: 用 Tripo AI 生成与加工 3D 模型资产：文生3D、图生3D、多视图、批量生成，以及重拓扑、绑定、动画、分割、纹理、PBR、UV、格式导出与下载。适用于需要 3D 模型、角色、道具、建筑或格式转换的场景。
|
||
---
|
||
|
||
# Tripo 3D 生成与加工技能
|
||
|
||
当用户需要生成 3D 模型、角色、道具、建筑，或对已有模型做重拓扑/绑定/动画/贴图/导出时使用本技能。
|
||
|
||
## 调用方式
|
||
|
||
本技能对应命令行工具 `tripocli`。按环境选择其一：
|
||
|
||
```bash
|
||
tripocli --version # 1) 已安装到 PATH（推荐）
|
||
<项目目录>/tripocli --version # 2) 直接用仓库里的入口（零依赖，无需安装）
|
||
```
|
||
|
||
若尚未安装，进到项目目录后安装（纯标准库，无第三方依赖）：
|
||
|
||
```bash
|
||
cd <项目目录>
|
||
pip install . # 用 pyenv 的话，装完执行一次 pyenv rehash
|
||
```
|
||
|
||
所有命令都支持 `--json`（放命令前或后都可以），Agent 调用时建议加上。
|
||
|
||
## 凭据（只需一次）
|
||
|
||
CLI 需要 Tripo 的 session cookie 才能换 JWT。**不需要浏览器常驻**：cookie 约 30 天有效，
|
||
CLI 每次调用会用 cookie 自动续期 15 分钟的 JWT。
|
||
|
||
```bash
|
||
tripocli account add --cookie "ory_kratos_session=..." # 添加账号（粘贴浏览器 cookie）
|
||
tripocli account list # 多账号查看/切换
|
||
tripocli serve --open # 网页版账号管理（看积分/有效期）
|
||
# 也可用环境变量：export TRIPO_COOKIE="ory_kratos_session=..."
|
||
```
|
||
|
||
cookie 获取：浏览器 DevTools → Network → 任意 `api.tripo3d.ai` 请求 → Request Headers → 整条 `Cookie`。
|
||
若命令报 `no-credentials`，按上面的 `account add` 提供 cookie 即可。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 账户
|
||
tripocli --json balance
|
||
tripocli --json quota
|
||
tripocli --json assets --size 10
|
||
|
||
# 文生图（参考图生成，默认 --amount 1 每次只出 1 张以节省额度；人形角色建议加 --t-pose）
|
||
tripocli --json img -p "<提示词>" --amount 1 --t-pose --wait -o /abs/path/refs
|
||
tripocli --json imgs --size 5
|
||
tripocli --json imgmv -i /abs/path/ref.png --wait -o /abs/path/views
|
||
|
||
# 文生 3D（⚠️ 游戏场景务必加 --face-limit 控制面数或用 --smart-mesh，避免默认 200 万面撑爆显存！）
|
||
tripocli --json text -p "<提示词>" --face-limit 15000 --wait -o /abs/path/out.glb
|
||
tripocli --json text -p "<提示词>" --smart-mesh --face-limit 20000 --wait -o /abs/path/out.glb
|
||
|
||
# 图生 3D / 导入模型
|
||
tripocli --json image -i /abs/path/photo.png --face-limit 25000 --wait -o /abs/path/out.glb
|
||
tripocli --json import -i /abs/path/my_model.glb --wait -o /abs/path/normalized.glb
|
||
|
||
# 多视角（必须 4 张：前/左/右/后）
|
||
tripocli --json multiview --front f.png --left l.png --right r.png --back b.png --wait -o /abs/path/mv.glb
|
||
|
||
# 批量图生 3D（多结果，-o 传目录）
|
||
tripocli --json batch -i a.png,b.png --wait -o /abs/path/outdir
|
||
|
||
# 后处理（作用于已有项目，需要 project_id）
|
||
tripocli --json remesh -p <project_id> --face-limit 10000 --wait -o low.glb
|
||
tripocli --json rig -p <project_id> --type biped --spec mixamo --wait -o hero_rigged.glb
|
||
tripocli --json animate --list
|
||
tripocli --json animate -p <project_id> --preset idle --wait -o anim_idle.glb
|
||
tripocli --json motion -p "让角色挥手打招呼" --duration 5 --project <project_id> --wait -o anim_wave.glb
|
||
tripocli --json segment -p <project_id> --wait
|
||
tripocli --json stylize -p <project_id> --style clay --wait
|
||
tripocli --json texture -p <project_id> --resolution 2K --wait
|
||
tripocli --json pbr -p <project_id> --wait
|
||
tripocli --json upscale -p <project_id> --wait
|
||
tripocli --json uv -p <project_id> --wait
|
||
tripocli --json fill -p <project_id> --parts all --wait
|
||
tripocli --json edit -p <project_id> --bbox "-1,-1,-1,1,1,1" --face-limit 8000 --wait
|
||
|
||
# 导出 / 下载 / 本地体检与减面 / 查询 / 取消 / 重命名
|
||
tripocli --json export -p <project_id> -f glb --wait -o model.glb
|
||
tripocli --json download --operator <operator_id> -o model.glb
|
||
tripocli --json inspect /abs/path/model.glb
|
||
tripocli --json optimize /abs/path/in.glb -o /abs/path/out.glb --faces 15000
|
||
tripocli --json optimize /abs/path/in.glb --lods
|
||
tripocli --json task status <operator_id>
|
||
tripocli --json project <project_id>
|
||
tripocli --json cancel --operator <operator_id> --type remesh
|
||
tripocli --json rename -p <project_id> --name "New Name"
|
||
```
|
||
|
||
## 生成类通用参数
|
||
|
||
- `-m/--model`：`P2.0` / `P1.0`（智能网格）、`H3.1` / `v3.0` / `v2.5`（高精度）
|
||
- `--face-limit`：面数上限（智能网格默认 25000，高精度默认 2000000）
|
||
- `--quad`：四边面（智能网格默认开启）
|
||
- `--count 1|2|4`：候选数量
|
||
- `--no-texture` / `--no-pbr` / `--no-delight`
|
||
- `--texture-quality standard|detailed`、`--geometry-quality standard|detailed`
|
||
- `--t-pose`、`--visibility shareable|private`
|
||
|
||
## 重要约束
|
||
|
||
1. **后处理算子会新建 operator**：同一项目必须等上一个算子 `success` 后才能做下一个，否则报
|
||
`2021 the status of task is not success`。用 `--wait`，或换项目。
|
||
2. **图片自动走「上传 S3 + 审核」**：`image` / `multiview` / `batch` 内部已处理，无需手工调用审核接口。
|
||
3. **智能 UV 需要低模**：模型须先 `remesh` 到 ≤8 万三角面才能使用。
|
||
4. 生成的模型 URL 带签名且有时效，需要长期保存时用 `--wait -o` 落盘。
|
||
|
||
## 游戏与 3D 大场景构建必读规范（防卡顿 / 防陷地 / 骨骼动画）
|
||
|
||
当用 `tripocli` 生成多个资产组装游戏场景（Three.js / Godot / Unity / Unreal）时，**必须遵守以下 5 条铁律**：
|
||
|
||
1. **严控面数（防止 6000 万面撑爆显存卡顿）**：
|
||
- 高精度模式（`v3.1`）默认 `face_limit=2,000,000`，单个建筑/树木可达 **70 万～95 万三角面**！若在主城里克隆几十份，总面数会突破 **6,000 万面** 导致严重掉帧。
|
||
- **源头控面（首选，省积分）**：生成建筑/树木/道具时直接传 `--face-limit 15000`（或加 `--smart-mesh` 走 P2.0 智能网格四边面低模）。
|
||
- **本地真减面（已有高模救火 / 生成多级 LOD，0 积分秒级完成）**：
|
||
入场前先用 `tripocli inspect *.glb` 检查面数，再用内置的 `tripocli optimize` 一键减面压缩（内部已自动区分静态模型 `--error 0.06` 与骨骼角色 `--error 0.02`，避免直接调 `gltf-transform optimize` 时默认 `--simplify-error 0.0001` 导致只压缩不减面的坑）：
|
||
```bash
|
||
tripocli inspect /abs/path/assets/*.glb
|
||
tripocli optimize in.glb -o out.glb --faces 15000
|
||
tripocli optimize in.glb --lods
|
||
```
|
||
2. **模型接地封装（防止建筑/树木半截埋入地下）**：
|
||
- Tripo 导出的 GLB 模型原点位于**几何中心**（`y ∈ [-H/2, +H/2]`），不在底部。
|
||
- 若直接修改模型自身的 `obj.position.y -= box.min.y` 后又在外部调用 `obj.position.set(x, 0, z)`，会把 `y` 重置回 `0`，导致所有房屋、城门、树木**整整下半截 50% 埋进地里**！
|
||
- **正确做法**：将缩放并偏移好底部高度（`rawObj.position.y = -box.min.y`）的模型包裹进一个外层 `const wrap = new THREE.Group()`，使 `wrap` 的 `(0,0,0)` 严格位于模型底部中心，外部只移动 `wrap.position.set(x, groundY, z)`。
|
||
3. **骨骼动画加载（本体 Mesh + 纯骨骼轨道分离架构）**：
|
||
- `tripocli rig` 产出的 GLB 含完整网格与 65 根骨骼（`SkinnedMesh`）；
|
||
- `tripocli animate`（`retarget_model`）产出的 GLB **仅含 65 根骨骼的动画轨道（约 100～500KB），不含任何 Mesh**！
|
||
- 在引擎中应以 `rig` 导出的 `hero.glb` 作为渲染网格，再加载各个 `anim_*.glb` 提取其中的 `gltf.animations` 挂到同一个 `AnimationMixer(heroModel)` 上播放。
|
||
4. **带骨骼角色（SkinnedMesh）的包围盒测量**：
|
||
- Three.js 的 `Box3.setFromObject()` 对 `SkinnedMesh` 默认按绑定初始网格算，不含骨骼根变换，会导致算出的角色高度翻倍或悬空。应遍历 `o.isBone` 的骨骼世界坐标 `o.getWorldPosition()` 计算角色真实高度与脚底 `min.y`。
|
||
5. **渲染管线与阴影减负**：
|
||
- 场景中有上百个建筑/道具时，只让主要建筑和角色开启 `castShadow = true`，**关闭复杂模型之间的 `receiveShadow`**（仅地面、广场、台阶开启 `receiveShadow = true`），并将高分屏像素比限制在 `Math.min(devicePixelRatio, 1.5)`，可让 WebGL 稳定跑满 **120 FPS**。
|
||
|
||
## 详细文档
|
||
|
||
命令全集与接口契约见 [README.md](./README.md) 与 [TRIPO_API_SPEC.md](./TRIPO_API_SPEC.md)。
|