Introduction

TensorBoard can display image tensors very well, but it does not provide a built-in caption field for each image tile in the image grid. If you want labels to appear with the images, the usual solutions are to draw the label onto the image before logging it or to log the labels separately with tf.summary.text.

Understand What tf.summary.image Actually Logs

The tf.summary.image API expects a batch of image tensors with shape batch x height x width x channels. It stores the image data in the event file and TensorBoard renders those images later, but it does not attach a per-image text caption in the way a plotting library might.

That means two different goals require two different approaches:

• If you want visible text on top of the image, modify the pixels before logging.
• If you want the labels available beside the image summary, log a matching text summary.

Knowing this limitation early prevents a lot of time spent looking for a non-existent caption argument.

Draw Labels Onto the Image Before Logging

The most direct way to show labels in TensorBoard is to annotate the images first. The example below uses Pillow to draw a label strip on each image, then logs the annotated batch with TensorBoard.

1import numpy as np
2import tensorflow as tf
3from PIL import Image, ImageDraw
4
5def add_label(image_array, label):
6    image = Image.fromarray(image_array)
7    draw = ImageDraw.Draw(image)
8
9    draw.rectangle((0, 0, image.width, 16), fill=(0, 0, 0))
10    draw.text((4, 2), label, fill=(255, 255, 255))
11    return np.array(image)
12
13images = np.random.randint(0, 255, size=(3, 64, 64, 3), dtype=np.uint8)
14labels = ["cat", "dog", "bird"]
15
16annotated = np.stack(
17    [add_label(image, label) for image, label in zip(images, labels)],
18    axis=0,
19)
20
21writer = tf.summary.create_file_writer("logs/labeled_images")
22
23with writer.as_default():
24    tf.summary.image("predictions", annotated, step=0, max_outputs=len(labels))
25
26print("Run: tensorboard --logdir logs/labeled_images")

This approach works well for predicted classes, filenames, confidence scores, or dataset split markers because the information is literally embedded into the image TensorBoard renders.

Log Text Labels Beside the Image Summary

If you do not want to modify the image pixels, log a text summary alongside the image summary. The text will appear in TensorBoard's text dashboard rather than inside the image tile, but it is often good enough for debugging.

1import tensorflow as tf
2
3labels = tf.constant(["cat", "dog", "bird"])
4
5writer = tf.summary.create_file_writer("logs/labeled_images")
6
7with writer.as_default():
8    tf.summary.text("prediction_labels", labels, step=0)

This is useful when you want the raw image to remain untouched, such as in medical imaging or when exact pixel values matter.

A practical pattern is to log both:

• annotated images for quick visual review
• text summaries for machine-readable labels

That combination makes it much easier to compare predictions with ground truth during experiments.

Match Images and Labels Carefully

The hard part is not the logging call itself. It is keeping label order aligned with the image batch. If the image batch is shuffled, augmented, or batched dynamically, the label list must go through the same pipeline.

For example, if you log model predictions during validation, make sure the labels you draw are generated from the same batch and in the same order:

1predictions = model.predict(batch_images, verbose=0)
2predicted_ids = tf.argmax(predictions, axis=1).numpy()
3class_names = ["airplane", "automobile", "bird", "cat", "deer"]
4predicted_labels = [class_names[index] for index in predicted_ids]

Once you have predicted_labels, you can pass them into the annotation function shown earlier and log the resulting images.

Common Pitfalls

• Expecting tf.summary.image to support a per-image caption field. It does not, so labels must be embedded or logged separately.
• Forgetting to keep labels in the same order as the image batch. A mismatch makes debugging harder, not easier.
• Drawing text on float images without converting the value range first. Many image libraries expect integer pixel values.
• Logging too many large images every training step. TensorBoard event files can grow quickly and slow down the workflow.
• Using very small images and long labels. The text becomes unreadable unless you reserve space or enlarge the image.

Summary

• TensorBoard image summaries do not provide native per-tile captions.
• To show labels inside the image view, draw the text onto the image before calling tf.summary.image.
• To keep the original pixels unchanged, log matching labels with tf.summary.text.
• Make sure image order and label order stay synchronized throughout the pipeline.
• Keep image logging selective so experiment logs remain usable and reasonably small.