ink-studio — ピクセルアート風Gaussian Splatsの造形と物理を扱うJSツールキット
siliconjungle/shapeshift-labs-ink-studio
★ 874 ・ JavaScript ・ MIT
概要
@shapeshift-labs/ink-studio は、符号付き距離関数(Signed Distance Field: SDF)を用いたソリッドの造形から、ピクセルアート風の Gaussian splat(ガウシアン・スプラット)へのベイク、そしてアニメーションや物理シミュレーションまでを一貫して扱うための JavaScript ツールキットです。
近年注目を集める 3D Gaussian Splatting の技術をピクセルアート表現と結びつけ、形状の生成だけでなく「動かす」「反応させる」「破壊する」「成長させる」「状態を記憶する」といったインタラクションを扱えるように設計されています。Node.js 環境のスクリプト、付属の ink-studio CLI、またはブラウザ環境の WebGL 2 キャンバス上など、用途に応じた複数の形態で実行できます。
独自のレトロスタイル 3D 表現を模索しているクリエイターや、ブラウザやヘッドレス環境で軽量かつ表現力豊かなパーティクル/スプラットベースの 3D シミュレーションを行いたい Web 開発者に向いています。
主な特徴
- SDF による立体造形とスプラットへのベイク: 球や直方体などの形状プリミティブを組み合わせたモデリングが可能で、解像度に応じたサンプリングとライティングを経てスプラットへ変換します。
- アニメーションと物理・パーティクルの統合: キャラクターのパペット制御やクロス(布)、ヘア(毛髪)、パーティクルプールの割り当て、アートディレクションに対応した影処理やライブリライティングをサポートします。
- 多彩な実行環境とレンダリング方式: Node.js や CLI を利用した CPU ベースのオフラインレンダリングに加え、ブラウザ上の WebGL 2 を用いたリアルタイム描画に対応しています。
- 外部 3D アセットとの連携機能: OBJ、glTF、GLB 形式のメッシュ読み込みやテクスチャ付き GLB のパース、デプスマップのインポート、さらに GLB 形式でのエクスポートやスプライトアトラス出力が可能です。
- ランタイム依存パッケージなしの設計: 外部の実行時依存パッケージ(runtime dependencies)を持たず、Node.js 18 以降の環境があれば単体で動作します。
使い方
動作要件とインストール
実行には Node.js 18 以降 が必要です。パッケージは GitHub から直接インストールして利用します。
# GitHub からプロジェクトへ直接インストール
npm install github:siliconjungle/shapeshift-labs-ink-studio
# CLI ヘルプの表示
npx ink-studio help
ローカルにリポジトリをクローンして試す場合は、リポジトリルートから CLI スクリプトを直接呼び出せます。
# リポジトリ内の CLI を直接実行
node cli/ink-studio.js help
node cli/ink-studio.js scenes
node cli/ink-studio.js render watcher --t 2.6 --colored
# テストの実行
npm test
シーンの作成とレンダリング
JavaScript でシーンを定義する場合、ツールキットを受け取り { id, name, seed, build(seed) } を返すモジュールを作成します。build 関数内でビルダーとスカルプターを初期化し、形状を配置してベイクします。
以下のコードは model.js として保存できる基本的なシーンの例です。
module.exports = ({ makeBuilder, makeSculpt, KIT: K }) => ({
id: 'sculpt-example',
name: 'Carved stone',
seed: 7,
build(seed) {
const palette = [0x080b10, 0x26313d, 0x566778, 0x9baeb8, 0xe5e9dc, 0x387548, 0x8fc75e];
const B = makeBuilder(seed, palette);
const S = K.sculpt(makeSculpt(B));
const stone = { r: [1, 2, 3, 4] };
S.ground({ r: [1, 1, 2] }, { rad: 4, res: 0.18 });
S.box([0, 1.2, 0], [1, 1.2, 1], stone, { res: 0.12 });
S.ball([0, 1.4, 0.9], 0.65, stone, { neg: true });
S.ball([0, 2.7, 0], 0.5, { r: [1, 5, 6] }, { res: 0.1 });
S.bake();
return B.finish({
cam: { target: [0, 1.4, 0], dist: 12, pitch: 0.2, yaw: 0.45 },
detail: 14,
dither: 0.25,
radius: 5
});
}
});
位置ベクトルは [x, y, z] 形式で Y 軸が上方向です。S.box に渡す寸法は中心からの半分の長さ(half-extents)であり、res は表面のサンプリング間隔を指定します。値を小さくするほどスプラット数が増加し、精密な表現になる一方で処理負荷が増えます。
定義したシーンは、ブラウザを介さずに CLI から直接画像として書き出せます。
# カラー画像としてレンダリング
npx ink-studio render model.js --colored
# 複数アングルのターンテーブル画像を生成(8枚)
npx ink-studio turn model.js --n 8
# シーンの統計情報を確認
npx ink-studio stats model.js
レンダリングされた画像はデフォルトで studio/out/ ディレクトリに出力されます。
Node.js スクリプトからの利用
ライブラリとしてインポートし、Node.js プログラム内部でスプラットデータを生成・検証することも可能です。
const studio = require('@shapeshift-labs/ink-studio');
const { makeBuilder, makeSculpt, KIT: K, SCENES } = studio.load();
const B = makeBuilder(7);
const S = K.sculpt(makeSculpt(B));
S.ball([0, 1, 0], 1, { r: [1, 2, 3, 4] }, { res: 0.15 });
S.bake();
const world = B.finish({
cam: { target: [0, 1, 0], dist: 10, pitch: 0.2, yaw: 0.4 },
detail: 14
});
console.log(world.count, world.data instanceof Float32Array);
console.log(SCENES.map(scene => scene.id));
技術的なポイント
1スプラットあたり16要素のフラットなデータ構造
生成されたワールドのコアデータは、JavaScript の Float32Array に保持されます。1つのスプラットにつき 16 個の 32bit 浮動小数点数(4x4 行列相当)が連続して並ぶ構造になっており、メモリレイアウトは以下のように定められています。
[x, y, z, density]
[c00, c01, c02, packedRGB]
[c11, c12, c22, kind]
[phase, speed, range, extra]
c00 から c22 はスプラットの形状を決定する対称共分散行列(covariance matrix)を表現しており、これによって各スプラットの広がりや向きが定義されます。さらに色情報をまとめた packedRGB、挙動の分類を表す kind、時間変化を扱う phase や speed などがコンパクトにまとめられています。
厳格なライフサイクル管理
シーンの構築フローには明確な順序が規定されています。
- 固定シード値とパレットを用いてビルダーとスカルプターを作成する。
- リグ(骨組み)や変形タグ、ライトキャプチャなどのフックを、ベイク対象の立体よりも前に登録する。
- ソリッドを追加し、
S.bake()を呼んで表面サンプリング、ライティング計算、スプラット書き込みを行う。 - パーティクルプール、布、毛髪など動的にスプラットを放出するシステムを、データ長を固定する
B.finish()の前に割り当てる。 - カメラ設定やディテール、ディザリングなどのレンダリングメタデータを渡してフィニッシュする。
- ステージやパペットなどのアニメーションドライバを生成されたワールドに接続する。
動かすオブジェクトによる不要な影の焼き込みや穴あきを防ぐため、静止背景を先にベイクしてから動的オブジェクトを追加するパターンなどが推奨されています。
キャッシュを伴うバンドル読み込み機構
Node.js 環境で studio.load() を呼び出すと、内部で依存関係順にスクリプトが連結され、パッケージ内の dist/standalone.js に CommonJS バンドルとしてコンパイルおよびキャッシュされます。そのため、ライブラリの初回実行時やソースコードの修正時には、パッケージディレクトリへの書き込み権限が必要となります。
注意点
- ライセンス: 本ソフトウェアは MIT ライセンスの下で公開されています。
- ランタイム要件: Node.js 18 以降が必須です。また、
load()実行時にdist/配下へバンドルファイルを書き出す仕様のため、コンテナや制限されたファイルシステムで実行する際は書き込み権限に注意が必要です。 - パッケージの公開設定:
package.jsonにprivate設定が施されており、npm レジストリへの誤公開を防ぐ構成となっています。そのため、依存関係として導入する場合は GitHub リポジトリ(github:siliconjungle/shapeshift-labs-ink-studio)やローカルパスから直接インストールする必要があります。 - 負荷とサンプリング間隔: SDF の表面サンプリング間隔(
res)を小さく設定しすぎると、生成されるスプラット数が急激に増加し、ベイクおよびレンダリング時の CPU/GPU コストが肥大化します。用途に応じたバランス調整が求められます。
まとめ
ink-studio は、SDF スカルプティングとピクセルアート調 Gaussian Splats を組み合わせ、アニメーションや物理シミュレーションまでをカバーするユニークな JavaScript ツールキットです。外部ランタイム依存を持たず、CLI・Node.js・WebGL 2 ブラウザ環境を柔軟に行き来できる設計が特徴です。レトロゲーム風の立体表現や、独自の 3D プロシージャルグラフィックスを Web 技術で構築したい開発者にとって興味深い選択肢となるでしょう。





