# Write Text On Image

This function block adds customizable text overlays onto images. It scales text relative to image size, lets you position the text using normalized coordinates, and optionally draws a semi-transparent background behind the text for better readability.

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

`Image Any` Accepts the image to draw text on.

`String` Optional text input. If left empty the block will draw an empty string (no visible text).

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

`Image Any` The image with the applied text overlay.

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

`Text Position Horizontal` Move text left/right using a normalized value (0.0 = left, 1.0 = right).

`Text Position Vertical` Move text up/down using a normalized value (0.0 = top, 1.0 = bottom).

`Font Scale` Adjust overall text size relative to the image.

`Font Thickness` Adjust the stroke thickness of the text.

`Font` Choose the font style from available options.

`Color` Select the text color.

`Background Enabled` Toggle a semi-transparent background rectangle behind the text for improved contrast.

## 🎨 Features <a href="#features" id="features"></a>

* Automatic scaling so text size adapts to image dimensions for consistent appearance across different resolutions.
* Normalized positioning makes it easy to place text proportionally, independent of image size.
* Semi-transparent background option improves legibility on busy images.
* Works with dynamic text inputs so overlays can display variable content (e.g., IDs, labels, sensor readings).

## 📊 How it runs <a href="#evaluation" id="evaluation"></a>

When the block runs it reads the incoming image and the current control values, computes an appropriate font scale and position based on the image dimensions, draws the optional background rectangle (if enabled), renders the text with the selected font, color and thickness, and outputs the resulting image for downstream blocks.

## 📝 Usage instructions <a href="#usage" id="usage"></a>

1. Connect a source that provides the image to `Image Any`.
2. Provide text to the `String` input or leave it empty to use the block’s internal text.
3. Adjust `Font`, `Color`, `Font Scale` and `Font Thickness` for desired appearance.
4. Use `Text Position Horizontal` and `Text Position Vertical` to place the text.
5. Enable `Background Enabled` if you need higher contrast on complex images.
6. Preview the output by connecting this block to a display block such as `Show Image` or save the result with `Image Write` / `Image Logger`.

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

* To stamp a running timestamp, feed the `String` input from the `Date-Time` or `Date-Time List` block and combine formatting in a `String Merge` block before feeding it in.
* For live preview while tuning position and scale, connect the output to the `Show Image` block.
* If you need to write labels only within a specific area, crop first with `Image ROI` or `Image ROI Select` and then apply this block.
* Use `Image Resize` before writing text if you want consistent final text size across images that vary widely in resolution.
* To save annotated frames, connect the output to `Image Logger` or `Image Write`.
* To overlay detection results, combine with detection blocks like `Find Object` or `Object Detection` and feed detected labels or counts into the `String` input.
* When drawing conditional status text (e.g., OK / NOK), use logical blocks (for example `Logic Input` or comparison blocks) and a `String Merge` to assemble the display text before sending it to this block.

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* Text appears too small or too large: adjust `Font Scale` or resize the input image with `Image Resize` for consistent results.
* Text is unreadable on busy backgrounds: enable `Background Enabled` or change `Color` to a high-contrast value.
* Text position seems off on different images: use normalized `Text Position Horizontal` and `Text Position Vertical` and verify placement on a representative image using `Show Image`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.augelab.com/function-blocks/detections-shapes/draw/write-text-on-image.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.