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

> Documentación del formato de salida PNG

# PNG

| Entrada | Salida | Alias |
| ------- | ------ | ----- |
| ✗       | ✔      | ✗     |

<div id="description">
  ## Descripción
</div>

Representa el resultado de una consulta como una imagen PNG. Resulta útil como herramienta de visualización integrada.

El tamaño de la imagen de salida viene determinado por los ajustes
[`output_format_image_width`](/docs/es/reference/settings/formats/output-format#output_format_image_width) y
[`output_format_image_height`](/docs/es/reference/settings/formats/output-format#output_format_image_height)
(ambos con un valor predeterminado de 1024). Los píxeles no cubiertos por el resultado se rellenan de negro
(en los modos `RGB` y escala de grises) o de negro transparente (en modo `RGBA`).

El modo de color se determina automáticamente a partir de los nombres y tipos de las columnas del resultado:

| Columnas             | Modo                                                                |
| -------------------- | ------------------------------------------------------------------- |
| `r`, `g`, `b`        | RGB de 8 bits                                                       |
| `r`, `g`, `b`, `a`   | RGBA de 8 bits                                                      |
| `v` de tipo entero   | escala de grises de 8 bits                                          |
| `v` de tipo `Float*` | escala de grises de 8 bits (valores de `[0, 1]` → `[0, 255]`)       |
| `v` de tipo `Bool`   | Binario (representado como escala de grises de 8 bits: `0` o `255`) |

Los nombres de las columnas se comparan sin distinguir entre mayúsculas y minúsculas. Si el modo de color no puede
determinarse de forma inequívoca (por ejemplo, por nombres de columna desconocidos, `v` mezclado con `r`/`g`/`b`/`a`, o por faltar uno de `r`/`g`/`b`),
la consulta genera una excepción.

Para los canales de píxel, los valores enteros se limitan a `[0, 255]` y los valores de coma flotante
se limitan a `[0, 1]` y luego se escalan a `[0, 255]`.

La posición de cada registro en la imagen se determina mediante uno de estos dos modos:

* **Implícito** (el predeterminado — cuando no está presente ni `x` ni `y`). Cada registro corresponde
  a un único píxel; los píxeles se rellenan en orden de barrido: de izquierda a derecha y de arriba abajo.
* **Explícito** (cuando están presentes las columnas `x` e `y`, ambas de tipo entero).
  Las columnas `x` e `y` indican las coordenadas del píxel. Los registros con coordenadas fuera
  de la imagen se ignoran silenciosamente. Si hay varios registros con las mismas coordenadas,
  prevalece el último (algoritmo del pintor).

<div id="example-usage">
  ## Ejemplo de uso
</div>

<div id="implicit-rgb">
  ### Coordenadas implícitas (una fila por píxel), 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">
  ### Coordenadas explícitas, escala de grises
</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="animation">
  ## Animación
</div>

Si el resultado tiene una columna `t` de tipo entero, el formato genera un PNG animado (`APNG`) en lugar de una
imagen estática. Los registros se agrupan en fotogramas según el valor de `t`, que representa el desfase temporal relativo del
fotograma. Cada fotograma es una imagen independiente: el lienzo está vacío al inicio de cada fotograma y, en el
modo de coordenadas implícitas, el cursor vuelve a empezar desde la esquina superior izquierda. La columna `t` se puede combinar con
cualquiera de los modos de coordenadas.

La unidad de `t` viene dada por
[`output_format_image_time_multiplier_seconds`](/docs/es/reference/settings/formats/output-format#output_format_image_time_multiplier_seconds)
y
[`output_format_image_time_divisor_seconds`](/docs/es/reference/settings/formats/output-format#output_format_image_time_divisor_seconds):
una unidad de `t` equivale a `output_format_image_time_multiplier_seconds / output_format_image_time_divisor_seconds`
segundos. Con los valores predeterminados (`1` y `60`), una unidad de `t` equivale a 1/60 de segundo.

Un fotograma se muestra hasta que comienza el siguiente, por lo que su duración es la diferencia entre dos valores consecutivos
de `t`. El último fotograma se muestra durante el mismo tiempo que el anterior. La animación se repite indefinidamente.

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

<div id="streaming-animation">
  ### Transmisión de fotogramas
</div>

De forma predeterminada, todos los fotogramas se recopilan en memoria y se escriben al final de la consulta, lo que mantiene un búfer de imagen
por cada valor distinto de `t` y permite que `t` llegue en cualquier orden.

La configuración
[`output_format_image_streaming_animation`](/docs/es/reference/settings/formats/output-format#output_format_image_streaming_animation)
escribe cada fotograma en cuanto se detecta el siguiente valor de `t`. Solo se mantiene un búfer de imagen en memoria y los
fotogramas llegan a la salida mientras la consulta aún se está ejecutando, por lo que un visor puede mostrarlos a medida que se generan.
A cambio:

* `t` debe ser no decreciente; de lo contrario, la consulta genera una excepción. Añada `ORDER BY t` si es necesario.
* Se desconoce el número de fotogramas cuando debe escribirse la cabecera, por lo que el fragmento `acTL` declara un límite
  superior en lugar del recuento exacto. Los navegadores reproducen este tipo de archivo, pero los decodificadores que se basan en el recuento declarado
  (por ejemplo, `Pillow` y algunas herramientas `APNG` de línea de comandos) informan de un error después del último fotograma real.
  Una animación de un solo fotograma es la excepción: para cuando se escribe ese fotograma, se ha leído todo el resultado,
  por lo que el recuento se declara exactamente y la salida cumple la especificación.

Dado que un protocolo de imágenes de terminal en línea transporta todo el flujo de datos como una única carga útil, los fotogramas no pueden
llegar antes al terminal y esta configuración solo afecta a la cantidad de memoria utilizada. El recuento exacto de fotogramas se
corrige en la carga útil almacenada temporalmente en el búfer antes de enviarla, por lo que no se aplica la salvedad sobre el límite superior.

Una animación solo se muestra en el modo de terminal `iterm`. El protocolo `sixel` no puede representar
animaciones, y el protocolo de gráficos Kitty solo anima mediante un flujo independiente de comandos por fotograma,
no mediante un flujo de datos animado, por lo que mostraría únicamente el primer fotograma; ambos modos rechazan un resultado con
una columna `t`.

<div id="terminal-mode">
  ## Mostrar imágenes en la terminal
</div>

De forma predeterminada, el formato `PNG` escribe los bytes sin procesar de la imagen. La configuración
[`output_format_image_terminal_mode`](/docs/es/reference/settings/formats/output-format#output_format_image_terminal_mode)
hace que el formato muestre la imagen directamente en la terminal mediante un protocolo de imagen en línea:

| Valor        | Comportamiento                                                                                                                                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \`\` (vacío) | Escribe los bytes sin procesar de la imagen (comportamiento predeterminado).                                                                                           |
| `iterm`      | Usa el protocolo de imagen en línea de iTerm2.                                                                                                                         |
| `kitty`      | Usa el protocolo de gráficos de Kitty. No puede mostrar animaciones.                                                                                                   |
| `sixel`      | Usa el protocolo Sixel. La imagen se reduce a una paleta fija de 6×6×6 y el canal alfa, si existe, se compone sobre un fondo negro.                                    |
| `auto`       | Si la salida es una terminal, detecta sus capabilities y usa `iterm`, `kitty` o `sixel` (en este orden); de lo contrario, escribe los bytes sin procesar de la imagen. |

```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">
  ## Configuración del formato
</div>

| Configuración                                 | Descripción                                                        | Predeterminado |
| --------------------------------------------- | ------------------------------------------------------------------ | -------------- |
| `output_format_image_width`                   | Ancho de la imagen de salida en píxeles.                           | `1024`         |
| `output_format_image_height`                  | Altura de la imagen de salida en píxeles.                          | `1024`         |
| `output_format_image_terminal_mode`           | Protocolo de imagen de terminal en línea (ver arriba).             | \`\` (vacío)   |
| `output_format_image_time_multiplier_seconds` | Numerador de la unidad de tiempo de la columna `t`, en segundos.   | `1`            |
| `output_format_image_time_divisor_seconds`    | Denominador de la unidad de tiempo de la columna `t`, en segundos. | `60`           |
| `output_format_image_streaming_animation`     | Escriba cada fotograma en cuanto avance `t` (ver arriba).          | `0`            |