拡張子別ディレクトリ (File Extension Directories)

file_extension_directories は、ファイルの拡張子を、ファイルの種類に応じてルーティングするためのフォルダフラグメント（パスの一部）に対応付けるプロジェクトテンプレートのマッピングです。シチュエーションマクロが派生変数 {file_extension_directory} を参照すると、プロジェクトシステムはこのテーブルでファイルの拡張子を検索し、関連付けられた値へと置換します。

代表的な用途: ファイルの種類ごとに個別のシチュエーションを作成することなく、画像、動画、音声、ドキュメントを outputs/ 配下の異なるサブフォルダに自動分類して整理できます。

簡単な設定例

project_template_schema_version: "0.3.0"
name: "My Project"

file_extension_directories:
  png: "images"
  jpg: "images"
  mp4: "videos"
  wav: "audio"

situations:
  save_node_output:
    macro: "{outputs}/{file_extension_directory?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}"

この設定により、以下のように解決されます：

file_extension="png" → outputs/images/Node_render.png
file_extension="mp4" → outputs/videos/Node_render.mp4
file_extension="xyz" → outputs/Node_render.xyz        (未マッピング: スロットが折りたたまれる)

{file_extension_directory?:/} の ?:/ は、このスロットをオプショナルにし、値が存在する場合に末尾に / を追加する指定です — これにより、マッピングされていない拡張子のファイルもエラーにならず、シチュエーションのディレクトリ直下に保存されます。

2 種類の値の形式

設定する値は、プレーンな名前 または マクロ のいずれかになります。

プレーンな名前 (Plain name)

file_extension_directories:
  png: "images"

文字列がそのまま使用されます。マクロ解決のオーバーヘッドがなく、最も一般的な指定方法です。

マクロ値 (Macro value)

file_extension_directories:
  mp4: "{outputs}/videos"
  wav: "{workspace_dir}/shared/audio"

{...} を含む値は、シチュエーションマクロに置換される前に、プロジェクトの組み込み変数、ディレクトリ定義、および呼び出し元から供給されたコンテキスト（node_name など）に対して事前に解決されます。

マクロ値を使用することで、ファイル種別ごとに個別のシチュエーションを書くことなく、単一の file_extension_directories テーブルで特定のファイル（例: 動画のみ共有ドライブへ保存）を全く異なるルートディレクトリへ振り分けることができます。

マクロ値が参照できる変数

ソース	例	利用可能？
組み込み変数	`{workspace_dir}`, `{workflow_dir}`, `{project_dir}`, `{project_name}`, `{static_files_dir}`	可能
ディレクトリ定義	`{outputs}`, `{inputs}`, `{temp}`, 任意のカスタムディレクトリ	可能
呼び出し元のコンテキスト	`{node_name}`, `{parameter_name}`, `{sub_dirs}`, `{_index}`	可能
ファイル名パーツ	`{file_name_base}`, `{file_extension}`	不可 — ルーティングはファイル名レイヤーではないため

ファイル名パーツは意図的に除外されています。file_extension_directories はファイルをどのフォルダに配置するかを決定するルーティングレイヤーです。ファイル名自体の構築はシチュエーションマクロのファイル名部分の責務です。

解決の仕組み

file_extension_directory は派生変数 (derived variable) です。組み込み変数ではなく、呼び出し元から直接渡される変数でもありません。シチュエーションのマクロテンプレートがこれを参照するたびに、プロジェクトシステムが以下の小さな導出ルールを実行します：

呼び出し元がシチュエーション名を指定し、変数群（file_extension を含む）を提供します。
シチュエーションマクロが解決される前に、導出ルールがトリガーされます：
- 呼び出し元によってすでに file_extension_directory が設定されている場合、ルールは介入しません（呼び出し元の値が優先）。
- そうでない場合、ルールは現在のプロジェクトの file_extension_directories テーブルで file_extension（大文字小文字を区別しない）を検索します。
- 値がプレーン文字列の場合、そのまま変数の値になります。
- 値がマクロの場合、まず具体的なパス文字列へと解決されます。
得られた値が変数バッグに注入され、通常通りシチュエーションマクロが解決されます。

検索に失敗した場合（拡張子が空、プロジェクト未ロード、未マッピングの拡張子、または解決エラー）、変数は単に未設定となります。オプショナル形式 {file_extension_directory?:/} を使用しているシチュエーションマクロはフォルダプレフィックスなしに安全にフォールバックし、必須形式 {file_extension_directory} を使用しているマクロは未設定変数エラーとして処理されます。

シチュエーションマクロとの相互作用

ルーティングプレフィックスを自動で先頭に付与したり親ディレクトリを付け替えたりするような特殊なエンジンロジックは存在しません。シチュエーションマクロテンプレートの記述どおりにそのまま構築されます。

シチュエーションマクロの形状	ルーティング動作
`{outputs}/{file_extension_directory?:/}{file_name_base}.{ext}`	ルーティングは `{outputs}` 配下のサブフォルダとなります。値は相対パスである必要があります。
`{file_extension_directory?:/}{file_name_base}.{ext}`	ルーティングがルートディレクトリを決定します。`{outputs}` から完全にリダイレクトするために絶対パスを使用できます。
`{outputs}/{file_extension_directory?:/}...` に絶対パスを指定した場合	単純な文字列連結（`outputs//Volumes/share/videos/foo.mp4` など）となり、意図しないパスになります。

必要とするルーティングの形式に応じたシチュエーションマクロを選択してください。

オーバーレイのマージ動作

file_extension_directories は、environment と全く同様にエントリごとにマージされます：

オーバーレイに存在しないキーは、ベースから継承されます。
オーバーレイに存在するキーは、その拡張子に対するベースのエントリを上書きします。
オーバーレイで null が設定されたキーは削除マーク（tombstone）され、ベースのエントリが破棄されます。

# ベースの画像ルーティングを継承し、mp4 は別の場所へ送り、csv のルーティングは削除する
file_extension_directories:
  mp4: "{workspace_dir}/shared/videos"
  csv: null

呼び出し元によるオーバーライド

任意の呼び出し元は、変数バッグ内の file_extension_directory を事前に設定しておくことができます。すでに設定されている場合、導出ルールは介入せず、呼び出し元の値がそのまま使用されます。UI レベルの設定（明示的な出力フォルダの上書きなど）が、同一のシチュエーションマクロに参加しながら拡張子テーブルをバイパスできるのはこの仕組みによるものです。

デフォルトで提供される内容

システムデフォルトには、一般的な画像、動画、音声、テキスト、および Python ソースの拡張子に対するエントリが用意されており、それぞれ images、videos、audio、text、および python サブフォルダへとルーティングされます。個々のエントリを上書きしたり、新しい拡張子を追加したり、不要なエントリを削除したりすることが可能です。