> ## 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

| Ввод | Вывод | Псевдоним |
| ---- | ----- | --------- |
| ✗    | ✔     | ✗         |

<div id="description">
  ## Описание
</div>

Отображает результат запроса в виде PNG-изображения. Это удобно как встроенный инструмент визуализации.

Размер выходного изображения задаётся настройками
[`output_format_image_width`](/docs/ru/reference/settings/formats#output_format_image_width) и
[`output_format_image_height`](/docs/ru/reference/settings/formats#output_format_image_height)
(обе по умолчанию равны 1024). Пиксели, не покрытые результатом, заполняются чёрным цветом
(в режимах `RGB` и градаций серого) или прозрачным чёрным (в режиме `RGBA`).

Цветовой режим автоматически определяется по именам столбцов и типам результата:

| Столбцы                 | Режим                                                               |
| ----------------------- | ------------------------------------------------------------------- |
| `r`, `g`, `b`           | 8-битный RGB                                                        |
| `r`, `g`, `b`, `a`      | 8-битный RGBA                                                       |
| `v` целочисленного типа | 8-битные градации серого                                            |
| `v` типа `Float*`       | 8-битные градации серого (значения в `[0, 1]` → `[0, 255]`)         |
| `v` типа `Bool`         | Двоичный (отображается как 8-битные градации серого: `0` или `255`) |

Имена столбцов сопоставляются регистронезависимо. Если цветовой режим нельзя определить однозначно
(например, из-за неизвестных имён столбцов, смешения `v` с `r`/`g`/`b`/`a` или отсутствия одного из `r`/`g`/`b`),
запрос генерирует исключение.

Для пиксельных каналов целочисленные значения ограничиваются диапазоном `[0, 255]`, а значения с плавающей точкой —
диапазоном `[0, 1]`, после чего масштабируются до `[0, 255]`.

Положение каждой записи в изображении определяется одним из двух режимов:

* **Неявный** (по умолчанию — когда нет ни `x`, ни `y`). Каждая запись соответствует
  одному пикселю; пиксели заполняются в порядке сканирования: слева направо, сверху вниз.
* **Явный** (когда присутствуют столбцы `x` и `y`, оба целочисленного типа).
  Столбцы `x` и `y` задают координаты пикселя. Записи с координатами за пределами
  изображения молча игнорируются. Если несколько записей имеют одинаковые координаты,
  используется последняя из них (алгоритм художника).

<div id="example-usage">
  ## Пример использования
</div>

<div id="implicit-rgb">
  ### Неявные координаты (одна строка на пиксель), RGB
</div>

```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;
```

<div id="explicit-grayscale">
  ### Явные координаты, градации серого
</div>

```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;
```

<div id="terminal-mode">
  ## Отображение изображений в терминале
</div>

По умолчанию формат `PNG` выводит необработанные байты изображения. Параметр
[`output_format_image_terminal_mode`](/docs/ru/reference/settings/formats#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';
```

<div id="format-settings">
  ## Настройки формата
</div>

| Настройка                           | Описание                                                  | По умолчанию |
| ----------------------------------- | --------------------------------------------------------- | ------------ |
| `output_format_image_width`         | Ширина выходного изображения в пикселях.                  | `1024`       |
| `output_format_image_height`        | Высота выходного изображения в пикселях.                  | `1024`       |
| `output_format_image_terminal_mode` | Протокол вывода изображений прямо в терминале (см. выше). | \`\` (пусто) |