vrm-cli-viewer

完全にGPT 5.6 Solによる実装です。

glTF / GLB / VRM モデルをヘッドレス Chromium 上の Three.js で描画し、PNG に保存する CLI です。人間が GUI を操作しなくても、コーディングエージェントや CI からモデルの見た目を確認できます。

使い方

npx vrm-cli-viewer ./my-model.vrm -o out.png

ローカルで開発中のパッケージを使う場合:

npm install
npm run build
node dist/cli.js ./my-model.vrm -o out.png

オプション

-o, --output <file>       出力 PNG（必須）
-W, --width <pixels>      幅。64〜4096（既定: 1024）
-H, --height <pixels>     高さ。64〜4096（既定: 1024）
--view <preset>           front / back / left / right / top / bottom / isometric
--background <color>      CSS 色、または transparent（既定: #f2f2f2）
--padding <ratio>         モデル周囲の余白。0〜1（既定: 0.08）
-q, --quiet               完了メッセージを表示しない

例:

# 透過背景の背面図
npx vrm-cli-viewer avatar.vrm -o back.png --view back --background transparent

# 横長の等角投影風ビュー
npx vrm-cli-viewer scene.glb -o scene.png -W 1600 -H 900 --view isometric

# 複数方向をエージェントやシェルから確認
for view in front left right back; do
  npx vrm-cli-viewer avatar.vrm -o "avatar-${view}.png" --view "$view"
done

対応範囲

• glTF 2.0（.gltf）、GLB（.glb）、VRM 0.x / 1.0（.vrm）
• .gltf と同じディレクトリ以下にある外部バッファ・テクスチャ
• VRM 0.x の向きを three-vrm で補正
• モデルのバウンディングボックスに合わせた自動カメラ配置
• PNG 出力のみ

セキュリティ上、モデルからの外部 HTTP/HTTPS リクエストと、入力モデルのディレクトリより上にあるファイルへの参照は遮断します。

開発

npm run check
npm test
npm run test:smoke

npm run test:smoke は最小 glTF を生成し、実際に Chromium で PNG が作られるところまで検証します。

Chrome が見つからない場合

Puppeteer は通常 npm install 時に対応する Chrome を取得します。ignore-scripts=true などで install script を無効にしている環境では、次を一度実行してください。

npx puppeteer browsers install chrome

npm 公開

GitHub Actions の Publish ワークフローを手動実行すると、指定したバージョンへ更新して npm に公開し、作成されたコミットとタグをリポジトリへ push します。

初回のみ、npm にログインしてパッケージを公開してから npmjs.com のパッケージ設定で Trusted Publisher を登録してください。

npm login
npm publish

GitHub Actions を選び、次の値を指定します。

• Organization or user: 0b5vr
• Repository: vrm-cli-viewer
• Workflow filename: publish.yml
• Allowed actions: npm publish

以降は GitHub の Actions から Publish を選び、version（例: 0.1.1）と distTag（通常は latest）を入力して実行します。公開には npm トークンを使わず、GitHub Actions の OIDC を利用します。

ブランチ保護を有効にしている場合は、GitHub Actions がリリースブランチへコミットとタグを push できるように設定してください。