> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> PNG画像の出力フォーマットに関するドキュメント
# PNG
| 入力 | 出力 | エイリアス |
| -- | -- | ----- |
| ✗ | ✔ | ✗ |
## 説明
クエリの結果を PNG イメージとしてレンダリングします。組み込みの可視化ツールとして利用できます。
出力イメージのサイズは、設定
[`output_format_image_width`](/docs/ja/reference/settings/formats/output-format#output_format_image_width) と
[`output_format_image_height`](/docs/ja/reference/settings/formats/output-format#output_format_image_height)
で固定されます
(どちらもデフォルトは 1024) 。結果でカバーされないピクセルは黒で塗りつぶされ
(`RGB` およびグレースケールモード) 、`RGBA` モードでは透明な黒で塗りつぶされます。
カラーモードは、結果のカラム名と型に基づいて自動的に決まります。
| カラム | モード |
| ------------------ | -------------------------------------------- |
| `r`, `g`, `b` | 8 ビット RGB |
| `r`, `g`, `b`, `a` | 8 ビット RGBA |
| 整数型の `v` | 8 ビットグレースケール |
| `Float*` 型の `v` | 8 ビットグレースケール (値を `[0, 1]` から `[0, 255]` に変換) |
| `Bool` 型の `v` | バイナリ (8 ビットグレースケールとしてレンダリング: `0` または `255`) |
カラム名の照合では大文字と小文字は区別されません。カラーモードを一意に
決定できない場合 (たとえば、不明なカラム名、`v` と `r`/`g`/`b`/`a` の混在、または `r`/`g`/`b` のいずれかが欠けている場合) 、
クエリは例外をスローします。
ピクセルチャンネルでは、整数値は `[0, 255]` の範囲にクランプされ、浮動小数点値は
`[0, 1]` の範囲にクランプされた後、`[0, 255]` にスケーリングされます。
イメージ内での各レコードの位置は、次の 2 つのモードのいずれかで決まります。
* **暗黙的** (デフォルト — `x` と `y` のどちらも存在しない場合) 。各レコードは
1 つのピクセルに対応します。ピクセルは走査線順、つまり左から右、上から下の順に埋められます。
* **明示的** (整数型の `x` カラムと `y` カラムが存在する場合) 。
`x` カラムと `y` カラムでピクセル座標を指定します。イメージの外側の座標を持つレコードは
何も通知されずに無視されます。同じ座標を持つ複数のレコードがある場合は、
最後のレコードが採用されます (painter's algorithm) 。
## 使用例
### 暗黙的な座標 (ピクセルごとに1行) 、RGB
```sql theme={null}
SELECT
toUInt8(x * 25) AS r,
toUInt8(y * 25) AS g,
toUInt8((x + y) * 12) AS b
FROM
(
SELECT number % 10 AS x, intDiv(number, 10) AS y FROM numbers(100)
)
INTO OUTFILE 'gradient.png'
FORMAT PNG
SETTINGS output_format_image_width = 10, output_format_image_height = 10;
```
### 明示的な座標指定 (グレースケール)
```sql theme={null}
SELECT
toInt32(x) AS x,
toInt32(y) AS y,
toUInt8(intensity) AS v
FROM points
INTO OUTFILE 'points.png'
FORMAT PNG
SETTINGS output_format_image_width = 512, output_format_image_height = 512;
```
## アニメーション
結果に整数型の `t` カラムが含まれる場合、このフォーマットは静止画ではなくアニメーション PNG (`APNG`) を生成します。レコードは、フレームの相対的な時間オフセットを表す `t` の値に基づいてフレームにグループ化されます。各フレームは独立したイメージです。各フレームの開始時にはキャンバスが空になり、暗黙的な座標モードではカーソルが左上隅から再開されます。`t` カラムは、いずれの座標モードとも組み合わせることができます。
`t` の単位は、
[`output_format_image_time_multiplier_seconds`](/docs/ja/reference/settings/formats/output-format#output_format_image_time_multiplier_seconds)
および
[`output_format_image_time_divisor_seconds`](/docs/ja/reference/settings/formats/output-format#output_format_image_time_divisor_seconds)
によって指定されます。`t` の 1 単位は `output_format_image_time_multiplier_seconds / output_format_image_time_divisor_seconds`
秒です。デフォルト値 (`1` および `60`) では、`t` の 1 単位は 1/60 秒です。
フレームは次のフレームが開始されるまで表示されるため、その表示時間は連続する 2 つの
`t` の値の差になります。最後のフレームは、その前のフレームと同じ時間表示されます。アニメーションは無限に繰り返されます。
```sql theme={null}
SELECT
number % 60 AS t,
toInt32(intDiv(number, 60) % 64) AS x,
toInt32((number * 7) % 64) AS y,
toUInt8(255) AS v
FROM numbers(60 * 64)
INTO OUTFILE 'animation.png'
FORMAT PNG
SETTINGS output_format_image_width = 64, output_format_image_height = 64;
```
### フレームのストリーミング
デフォルトでは、すべてのフレームがメモリに収集され、クエリの終了時に書き出されます。これにより、`t` の値ごとに 1 つのイメージ
バッファが保持され、`t` は任意の順序で到着できます。
設定
[`output_format_image_streaming_animation`](/docs/ja/reference/settings/formats/output-format#output_format_image_streaming_animation)
では、次の `t` の値が検出されるとすぐに各フレームが書き出されます。メモリに保持されるイメージバッファは 1 つだけで、
クエリの実行中にもフレームが出力に送られるため、ビューアは生成されたフレームを順次表示できます。
その代わり、次の制約があります。
* `t` は非減少でなければなりません。そうでない場合、クエリは例外をスローします。必要に応じて `ORDER BY t` を追加してください。
* ヘッダーを書き込む時点ではフレーム数が不明なため、`acTL` chunk には正確な数ではなく上限値が宣言されます。ブラウザはこのようなファイルを再生できますが、宣言された数を信頼するデコーダ
(たとえば `Pillow` や一部のコマンドライン `APNG` ツール) は、最後の実際のフレームの後にエラーを報告します。
ただし、単一フレームのアニメーションは例外です。そのフレームが書き込まれる時点で結果全体が読み取られているため、
正確な数が宣言され、出力は仕様に準拠します。
インライン端末イメージプロトコルはデータストリーム全体を単一のペイロードとして扱うため、フレームを端末へ早期に送ることはできず、
この設定は端末で使用されるメモリ量にのみ影響します。ペイロードの送信前に、正確なフレーム数がバッファリングされたペイロードに
反映されるため、上限値に関する注意事項は適用されません。
アニメーションが表示されるのは `iterm` 端末モードのみです。`sixel` プロトコルはアニメーションをまったく表現できず、
Kitty グラフィックスプロトコルはアニメーション化されたデータストリームではなく、フレームごとのコマンドからなる別個のフローでのみアニメーションを表示するため、最初のフレームだけが表示されます。どちらのモードも
`t` カラムを含む結果を拒否します。
## 端末で画像を表示する
デフォルトでは、`PNG` フォーマットは生の画像バイト列を書き出します。設定
[`output_format_image_terminal_mode`](/docs/ja/reference/settings/formats/output-format#output_format_image_terminal_mode)
を使用すると、代わりにインライン画像プロトコルを使って、このフォーマットで画像を端末に直接レンダリングできます。
| 値 | 動作 |
| -------- | --------------------------------------------------------------------------------------- |
| \`\` (空) | 生の画像バイト列を書き出します (デフォルト) 。 |
| `iterm` | iTerm2 のインライン画像プロトコルを使用します。 |
| `kitty` | Kitty グラフィックスプロトコルを使用します。アニメーションは表示できません。 |
| `sixel` | Sixel プロトコルを使用します。画像は固定の 6×6×6 パレットに縮小され、アルファチャネルがある場合は黒い背景に合成されます。 |
| `auto` | 出力先が端末の場合は、その機能を検出して `iterm`、`kitty`、`sixel` のいずれかを使用し (この順序) 、それ以外の場合は生の画像バイト列を書き出します。 |
```sql theme={null}
SELECT toUInt8(x * 25) AS r, toUInt8(y * 25) AS g, toUInt8((x + y) * 12) AS b
FROM (SELECT number % 10 AS x, intDiv(number, 10) AS y FROM numbers(100))
FORMAT PNG
SETTINGS output_format_image_width = 10, output_format_image_height = 10, output_format_image_terminal_mode = 'auto';
```
## フォーマット設定
| Setting | Description | Default |
| --------------------------------------------- | ----------------------------- | -------- |
| `output_format_image_width` | 出力イメージの幅 (ピクセル単位) 。 | `1024` |
| `output_format_image_height` | 出力イメージの高さ (ピクセル単位) 。 | `1024` |
| `output_format_image_terminal_mode` | インライン端末画像プロトコル (上記参照) 。 | \`\` (空) |
| `output_format_image_time_multiplier_seconds` | `t` カラムの時間単位の分子 (秒単位) 。 | `1` |
| `output_format_image_time_divisor_seconds` | `t` カラムの時間単位の分母 (秒単位) 。 | `60` |
| `output_format_image_streaming_animation` | `t` が進むたびに各フレームを書き込む (上記参照) 。 | `0` |