Script TOP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】

※当サイトにはプロモーションリンクが含まれます。

Script TOP の Python コールバックによる画像生成機能を示すサムネイル

記事更新の通知はXでアナウンス٩(๑❛ᴗ❛๑)
→ @maru6o6をフォロー

概要 📖 – Python で画像を生成

Script TOPは、Python のコールバック関数から numpy 配列で TOP テクスチャを生成・編集できる TOPです。Callbacks DAT に定義した onCook 関数で出力イメージを numpy 配列として書き換え、setupParameters() でカスタム UI パラメータを宣言できます。

主な用途 🎯

  • Python コールバックによる独自テクスチャの手続き的生成
  • numpy 配列演算をリアルタイムで TOP イメージとして出力
  • カスタムパラメータを持つ独自 TOP コンポーネントの作成
  • 外部スクリプト・センサーデータからのテクスチャ書き換え (Modify Outside of Cook)
  • 独自画像処理アルゴリズム・実験的フィルタのプロトタイピング

データフロー 🔄

入力: 任意の TOP / なし
 ↓
Callbacks DAT の onCook 関数を呼び出し
 ↓
Python / numpy で出力配列を計算
 ↓
出力: 指定解像度・フォーマットのテクスチャ

Tips

初心者の方は、以下日本語書籍も手元にあると安心です。

まる。
まる。

実際の案件事例まで踏み込んで紹介されていて、効率よくスキルアップするなら必携の二冊です！

パラメータ解説 ⚙️

Script Page 📋

Callbacks DAT .callbacks 📜

コールバック関数を保持する Text DAT の指定:

  • Callbacks DAT: callbacks (コールバック DAT) — onCook / onPulse / setupParameters などのコールバック関数を記述した Text DAT のパスを指定します。空にするとデフォルト動作のみ

Setup Parameters .setuppars 🎛️

カスタムパラメータ定義の再構築ボタン:

  • Setup Parameters: setuppars (パラメータ再構築ボタン) — Callbacks DAT 内の setupParameters(scriptOp) 関数を実行し、Script TOP にユーザー定義のカスタムパラメータページを動的に追加します。コールバック側で scriptOp.appendCustomPage() などを呼ぶ

Modify Outside of Cook .modoutsidecook 🔓

クック外からのテクスチャ書き込み許可:

  • Modify Outside of Cook: modoutsidecook (クック外書き込み許可) — オンにすると TOP をロック (Lock) しなくても外部スクリプトや Execute DAT から scriptOp.copyNumpyArray() でテクスチャを書き換え可能になります

Common Page 🔧

Output Resolution .outputresolution 🖼️

出力解像度の決定方式

項目 内部名 説明
Use Input .useinput 入力 TOP の解像度をそのまま継承
Eighth .eighth 入力解像度の 1/8
Quarter .quarter 入力解像度の 1/4
Half .half 入力解像度の 1/2
2X .2x 入力解像度の 2 倍
4X .4x 入力解像度の 4 倍
8X .8x 入力解像度の 8 倍
Fit Resolution .fit 指定解像度に縦横比を保持して収める
Limit Resolution .limit 指定解像度を上限としてクランプ
Custom Resolution .custom Resolution パラメータで任意指定

Resolution .resolution 📐

カスタム解像度の幅・高さ指定 (Output Resolution = Custom 等の時のみ有効):

  • Resolution W: 出力幅 (ピクセル単位)。Output Resolution が Custom Resolution / Fit Resolution / Limit Resolution の時に有効
  • Resolution H: 出力高 (ピクセル単位)。同上

Resolution Menu .resmenu 📋

よく使う解像度プリセットのドロップダウン:

  • Resolution Menu: NTSC / PAL / HDTV 720 / HDTV 1080 / 4K UHD 等のプリセットから選択すると Resolution W / Resolution H が自動セットされる

Use Global Res Multiplier .resmult 🔢

プロジェクト全体の解像度倍率の適用:

  • Use Global Res Multiplier: Project Settings の Global Resolution Multiplier をこの TOP に適用するかどうか。プロトタイプを低解像度で動かしつつ最終出力で一括フル解像度化する運用に便利

Output Aspect .outputaspect 📏

出力アスペクト比の決定方式

項目 内部名 説明
Use Input .useinput 入力 TOP のアスペクトを継承 (伝播事故の元、非推奨)
Resolution .resolution 解像度から自動導出 (推奨デフォルト)
Custom Aspect .custom Aspect1 / Aspect2 で手動指定

Aspect .aspect 📐

カスタムアスペクト比の指定 (Output Aspect = Custom Aspect の時のみ有効):

  • Aspect1: 横方向アスペクト値 (Output Aspect = Custom Aspect の時のみ有効)
  • Aspect2: 縦方向アスペクト値 (同上)

Input Smoothness .inputfiltertype 🎚️

入力テクスチャのサンプリング方式

項目 内部名 説明
Nearest Pixel .nearest 最近傍ピクセルサンプリング (ピクセルアート向け、ジャギーが残る)
Interpolate Pixels .linear バイリニア補間 (滑らか、デフォルト)
Mipmap Pixels .mipmap ミップマップ補間 (縮小時のモアレ抑制、わずかにコスト高)

Fill Viewer .fillmode 🖥️

ビューア内でのテクスチャの収め方

項目 内部名 説明
Use Input .useinput 入力 TOP の Fill Viewer 設定を継承
Fill .fill ビューアいっぱいに引き伸ばす (アスペクト無視)
Fit Horizontal .width 横幅に合わせて収める (上下に余白)
Fit Vertical .height 縦幅に合わせて収める (左右に余白)
Fit Best .best アスペクト保持で内側に収まる最大サイズ
Fit Outside .outside アスペクト保持で外側まで覆う最小サイズ (はみ出しあり)
Native Resolution .nativeres テクスチャのネイティブ解像度のまま等倍表示

Viewer Smoothness .filtertype 🎛️

ビューア表示時のサンプリング方式

項目 内部名 説明
Nearest Pixel .nearest 最近傍ピクセルサンプリング (ピクセル単位での確認向け)
Interpolate Pixels .linear バイリニア補間 (滑らか、デフォルト)
Mipmap Pixels .mipmap ミップマップ補間 (縮小ビュー時のモアレ抑制)

Passes .npasses 🔁

オペレータの反復実行回数:

  • Passes: TOP の処理を何パス繰り返すかの整数値。前回パスの結果が次回パスの入力になる。ブラー反復やフィードバック処理に利用

Channel Mask .chanmask 🎨

処理対象のチャンネルマスク (R/G/B/A 個別トグル):

  • Channel Mask: R / G / B / A 各チャンネルのオン/オフトグル。オフのチャンネルは TOP の処理を受けず入力値がそのまま通過

Pixel Format .format 🎨

出力テクスチャのピクセルフォーマット (ビット深度・チャンネル構成)

項目 内部名 説明
Use Input .useinput 入力 TOP のフォーマットを継承
8-bit fixed (RGBA) .rgba8fixed 標準 8 ビット固定小数 RGBA (デフォルト、軽量)
sRGB 8-bit fixed (RGBA) .srgba8fixed sRGB ガンマ補正済 8 ビット RGBA
16-bit float (RGBA) .rgba16float 16 ビット浮動小数 RGBA (HDR・中間処理向け)
32-bit float (RGBA) .rgba32float 32 ビット浮動小数 RGBA (最高精度、メモリ大)
10-bit RGB with 2-bit Alpha .rgb10a2fixed 10-10-10-2 ビット固定小数 (バンディング抑制)
16-bit fixed (RGBA) .rgba16fixed 16 ビット固定小数 RGBA
11-bit float (RGB) .rgb11float 11-11-10 ビット浮動小数 RGB (アルファなし、HDR 軽量)
16-bit float (RGB) .rgb16float 16 ビット浮動小数 RGB (アルファなし)
32-bit float (RGB) .rgb32float 32 ビット浮動小数 RGB (アルファなし)
8-bit fixed (Mono) .mono8fixed 8 ビット固定小数モノクロ
16-bit fixed (Mono) .mono16fixed 16 ビット固定小数モノクロ
16-bit float (Mono) .mono16float 16 ビット浮動小数モノクロ
32-bit float (Mono) .mono32float 32 ビット浮動小数モノクロ
8-bit fixed (RG) .rg8fixed 8 ビット固定小数 R+G 2 チャンネル
16-bit fixed (RG) .rg16fixed 16 ビット固定小数 R+G
16-bit float (RG) .rg16float 16 ビット浮動小数 R+G
32-bit float (RG) .rg32float 32 ビット浮動小数 R+G
8-bit fixed (A) .a8fixed 8 ビット固定小数アルファ単体
16-bit fixed (A) .a16fixed 16 ビット固定小数アルファ単体
16-bit float (A) .a16float 16 ビット浮動小数アルファ単体
32-bit float (A) .a32float 32 ビット浮動小数アルファ単体
8-bit fixed (Mono+Alpha) .monoalpha8fixed 8 ビット固定小数モノクロ+アルファ
16-bit fixed (Mono+Alpha) .monoalpha16fixed 16 ビット固定小数モノクロ+アルファ
16-bit float (Mono+Alpha) .monoalpha16float 16 ビット浮動小数モノクロ+アルファ
32-bit float (Mono+Alpha) .monoalpha32float 32 ビット浮動小数モノクロ+アルファ

実践アイデア 💡

Example 1: numpyグラデーション生成 🎨

Text DAT (callbacks) → Script TOP (onCook) → 出力テクスチャ

Callbacks DAT の onCook(scriptOp) 関数内で numpy の linspace を使い水平方向グラデーションを計算し、scriptOp.copyNumpyArray() で出力テクスチャに転送する基本フロー。

  1. Text DAT を作成し def onCook(scriptOp): 内で numpy 配列を生成 (例: np.linspace(0, 1, 1280) を縦に複製して 2D 化)
  2. RGBA 4 チャンネル分の (H, W, 4) 形状 float32 配列を組み立てる
  3. Script TOP の Callbacks DAT パラメータに Text DAT のパスを指定
  4. 出力解像度を Common Page の Custom Resolution + 1280×720 等に合わせて確認

Example 2: 外部センサーから画像書き込み 📡

Execute DAT (フレーム毎) → Script TOP (Modify Outside of Cook) → 後段 Composite TOP

Modify Outside of Cook をオンにした Script TOP に対し、別の Execute DAT から取得した外部センサーデータ (深度カメラ・OpenCV 解析結果など) を numpy 配列として直接書き込み、TOP ネットワークの一部として合成する。

  1. Script TOP の Modify Outside of Cook をオンに設定
  2. Execute DAT の onFrameStart で OpenCV / RealSense からフレームを取得
  3. op('script1').copyNumpyArray(frame_uint8) で TOP のテクスチャに直接書き込み
  4. Composite TOP や Render TOP の入力として後段に流す

Example 3: カスタムパラメータ追加 🎛️

Text DAT (setupParameters + onCook) → Script TOP (カスタムパラメータ反映)

Callbacks DAT に setupParameters(scriptOp) を定義してカスタムページに Slider / Toggle / RGB / Menu を宣言し、onCook 側で scriptOp.par.Customval を参照することで、独自パラメータで挙動を制御できる再利用可能な TOP コンポーネントに仕立てる。

  1. Text DAT 内で def setupParameters(scriptOp): page = scriptOp.appendCustomPage('Custom') でカスタムページを追加
  2. page.appendFloat('Threshold', label='しきい値') 等で Slider を追加
  3. Script TOP の Setup Parameters ボタンを押して UI を再構築
  4. onCook 内で thresh = scriptOp.par.Threshold.eval() 等で値を取り出して numpy 演算に反映

関連オペレータ 🔗

類似機能OP 🔍

  • Script CHOP — Python コールバックで CHOP チャンネルを生成する CHOP 版
  • Script SOP — Python コールバックでジオメトリを生成する SOP 版
  • GLSL TOP — GPU シェーダで手続き的にテクスチャを生成 (高速、numpy 不要)

組み合わせ推奨OP 🔄

  • Script DAT — Callbacks DAT として組み合わせ、コールバックロジックを保持
  • Execute DAT — クック外イベントから Script TOP のテクスチャを直接書き換え
  • Composite TOP — Script TOP の出力を他レイヤと合成
  • CHOP to TOP — CHOP の値を Script TOP のパラメータ駆動に利用
  • Render TOP — Script TOP で生成したテクスチャを 3D マテリアルに渡す

前処理・後処理TOP 🎯

Info CHOP情報 📊

Script TOPは Info CHOP による詳細情報取得に対応しています。

TOP固有情報 🖼️

  • resx: TOP の出力解像度 X (ピクセル単位)
  • resy: TOP の出力解像度 Y (ピクセル単位)
  • aspectx: アスペクト比 X
  • aspecty: アスペクト比 Y
  • depth: 3D テクスチャ / テクスチャ配列の深度 (2D テクスチャでは 1)
  • gpu_memory_used: TOP が消費している GPU メモリ量 (MB 単位)

汎用オペレータ情報 🔄

  • total_cooks: プロセス開始からのクック回数
  • cook_time: 最後のクック時間 (ミリ秒)
  • cook_frame: 最後にクックされたフレーム番号
  • warnings: 警告数
  • errors: エラー数

トラブルシューティング ⚠️

よくある問題と解決策 🔧

❌ Problem: 出力が真っ黒のままで画像が出ない
✅ Solution:

  • Callbacks DAT のパスが正しく Text DAT を指しているか確認
  • Text DAT 内の関数名が onCook(scriptOp) と完全一致しているか確認 (タイポ・大文字小文字の差で呼ばれない)
  • scriptOp.copyNumpyArray(arr) に渡す配列の dtype と Common Page の Pixel Format が一致しているか確認 (例: rgba8fixed なら uint8、rgba32float なら float32)

❌ Problem: Modify Outside of Cook が効かず外部書き込みが反映されない
✅ Solution:

  • Modify Outside of Cook パラメータがオンになっているか確認
  • 外部から op('script1').copyNumpyArray(arr) を呼び出した直後にビューアが更新されているか確認 (必要なら scriptOp.cook(force=True))
  • 後段 TOP が古いフレームを掴んでいる場合は Feedback TOP や Null TOP でフレーム同期を整理

❌ Problem: カスタムパラメータが UI に表示されない
✅ Solution:

  • setupParameters(scriptOp) 関数を Callbacks DAT 内に定義しているか確認
  • Script TOP の Setup Parameters ボタンを 1 度押して再構築をトリガしているか確認
  • scriptOp.appendCustomPage('Page名') の戻り値ページに対して appendFloat / appendToggle 等で項目を追加しているか確認

❌ Problem: フレームレートが低下する / クックが重い
✅ Solution:

  • Common Page の Output Resolution を下げて演算量を削減
  • numpy 演算をベクトル化 (Python ループを避け、np.where / ブロードキャストで一括処理)
  • GPU で完結する処理であれば GLSL TOP への置き換えを検討
  • 毎フレーム再計算が不要なら scriptOp.cook(force=False) で必要時のみ更新

参考資料 📚

その他 🔗

公式リソース 📖

この記事はLLMと共に内容を執筆、更新しています。
最新バージョンとの項目差異など、情報の不一致を見つけた心優しい方はXもしくはInsta、メールなどよりサイト管理者までご連絡ください😎


まる。

お仕事のご依頼はDM又はメールにて。
━━━━━━━━━━━━━━━━━
Python/Touchdesigner/M5Stackをこよなく愛すフルスタックエンジニア。
専門は生理心理学、趣味はヨガやサウナ、EMS電気風呂などヘルスケア全般。
脳波や筋電、心拍を中心とした生体情報のセンシング＆インタラクティブアートづくりがライフワーク。

普段はワントゥーテンという会社で空間演出エンジニアをしています。
リファラル採用お繋ぎできますので、我こそはという尖った方は経歴と希望職種添えてDMください(エンジニア以外、営業職等もOK)。
ご飯行きましょう。

↓日常垢
Instagram：＠malmal0v0

まる。をフォローする
その他の記事はこちら
Math Combine POP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】
ZED Select TOP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】
ZED POP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】
Window COMP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】
Widget COMP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】

タイトルとURLをコピーしました