> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/spanish/function-blocks/blocks-reference/detections-shapes/draw/write-text-on-image.md).

# Write Text On Image

Esta función añade superposiciones de texto personalizables sobre imágenes. Escala el texto en relación con el tamaño de la imagen, permite posicionarlo usando coordenadas normalizadas y, opcionalmente, dibuja un fondo semitransparente detrás del texto para mejorar la legibilidad.

## 📥 Entradas <a href="#inputs" id="inputs"></a>

`Image Any` Acepta la imagen sobre la que se dibujará el texto.

`String` Entrada de texto opcional. Si se deja vacía, el bloque dibujará una cadena vacía (sin texto visible).

## 📤 Salidas <a href="#outputs" id="outputs"></a>

`Image Any` La imagen con la superposición de texto aplicada.

## 🕹️ Controles <a href="#controls" id="controls"></a>

`Text Position Horizontal` Mueve el texto a la izquierda/derecha usando un valor normalizado (0.0 = izquierda, 1.0 = derecha).

`Text Position Vertical` Mueve el texto arriba/abajo usando un valor normalizado (0.0 = arriba, 1.0 = abajo).

`Font Scale` Ajusta el tamaño general del texto en relación con la imagen.

`Font Thickness` Ajusta el grosor del trazo del texto.

`Font` Elige el estilo de fuente entre las opciones disponibles.

`Color` Selecciona el color del texto.

`Background Enabled` Activa un rectángulo de fondo semitransparente detrás del texto para mejorar el contraste.

## 🎨 Características <a href="#features" id="features"></a>

* Escalado automático para que el tamaño del texto se adapte a las dimensiones de la imagen y mantenga una apariencia coherente entre distintas resoluciones.
* Posicionamiento normalizado que facilita colocar el texto proporcionalmente, independiente del tamaño de la imagen.
* Opción de fondo semitransparente para mejorar la legibilidad en imágenes con mucho contenido.
* Funciona con entradas de texto dinámicas para mostrar contenido variable (por ejemplo, IDs, etiquetas, lecturas de sensores).

## 📊 Cómo funciona <a href="#evaluation" id="evaluation"></a>

Al ejecutarse, el bloque lee la imagen entrante y los valores actuales de los controles, calcula una escala de fuente y una posición apropiadas según las dimensiones de la imagen, dibuja el rectángulo de fondo opcional (si está habilitado), renderiza el texto con la fuente, color y grosor seleccionados, y emite la imagen resultante para los bloques posteriores.

## 📝 Instrucciones de uso <a href="#usage" id="usage"></a>

1. Conecta una fuente que proporcione la imagen a `Image Any`.
2. Proporciona el texto a la entrada `String` o déjala vacía para usar el texto interno del bloque.
3. Ajusta `Font`, `Color`, `Font Scale` y `Font Thickness` para obtener la apariencia deseada.
4. Usa `Text Position Horizontal` y `Text Position Vertical` para colocar el texto.
5. Habilita `Background Enabled` si necesitas mayor contraste en imágenes complejas.
6. Previsualiza la salida conectando este bloque a un bloque de visualización como `Show Image` o guarda el resultado con `Image Write` / `Image Logger`.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* Para estampar una marca temporal en tiempo real, alimenta la entrada `String` desde el bloque `Date-Time` o `Date-Time List` y combina el formato en un bloque `String Merge` antes de enviarlo.
* Para previsualización en vivo mientras ajustas posición y escala, conecta la salida al bloque `Show Image`.
* Si solo necesitas escribir etiquetas dentro de un área específica, recorta primero con `Image ROI` o `Image ROI Select` y luego aplica este bloque.
* Usa `Image Resize` antes de escribir texto si quieres un tamaño de texto final consistente en imágenes con resoluciones muy distintas.
* Para guardar fotogramas anotados, conecta la salida a `Image Logger` o `Image Write`.
* Para superponer resultados de detección, combínalo con bloques de detección como `Find Object` u `Object Detection` y alimenta las etiquetas o conteos detectados en la entrada `String`.
* Al dibujar textos de estado condicional (por ejemplo, OK / NOK), utiliza bloques lógicos (por ejemplo `Logic Input` o bloques de comparación) y un `String Merge` para ensamblar el texto antes de enviarlo a este bloque.

## 🛠️ Resolución de problemas <a href="#troubleshooting" id="troubleshooting"></a>

* El texto aparece demasiado pequeño o demasiado grande: ajusta `Font Scale` o redimensiona la imagen de entrada con `Image Resize` para obtener resultados consistentes.
* El texto no se lee en fondos muy cargados: activa `Background Enabled` o cambia `Color` por un valor de alto contraste.
* La posición del texto parece desalineada en distintas imágenes: usa los valores normalizados de `Text Position Horizontal` y `Text Position Vertical` y verifica la colocación en una imagen representativa con `Show Image`.