Introduction

When training object detection models, scalar metrics rarely tell the whole story. Seeing more annotated images in TensorBoard helps you catch bad labels, box misalignment, augmentation problems, and class confusion much earlier, and the key control is usually how many images you log with each image summary.

The Main Lever: max_outputs

If you only see a few images, your summary call is probably logging too few outputs. Increase max_outputs in tf.summary.image():

1import tensorflow as tf
2
3log_dir = "logs/train"
4writer = tf.summary.create_file_writer(log_dir)
5
6images = tf.random.uniform((16, 128, 128, 3))
7
8with writer.as_default():
9    tf.summary.image("train/images", images, step=1, max_outputs=12)
10
11writer.flush()

Two things matter here:

• 'max_outputs cannot exceed the batch size'
• you must flush or close the writer for summaries to appear promptly

Raw Images Are Less Useful Than Annotated Images

For object detection, the real value comes from images with ground-truth and predicted boxes drawn on them. A simplified example using tf.image.draw_bounding_boxes looks like this:

1import tensorflow as tf
2
3def draw_boxes(image, boxes, color):
4    image = tf.image.convert_image_dtype(image, tf.float32)
5    image_batch = tf.expand_dims(image, axis=0)
6    boxes_batch = tf.expand_dims(boxes, axis=0)
7    colors = tf.constant([color], dtype=tf.float32)
8    boxed = tf.image.draw_bounding_boxes(image_batch, boxes_batch, colors)
9    return tf.squeeze(boxed, axis=0)
10
11image = tf.random.uniform((128, 128, 3))
12boxes = tf.constant([[0.1, 0.1, 0.6, 0.7]], dtype=tf.float32)
13
14annotated = draw_boxes(image, boxes, [1.0, 0.0, 0.0])
15
16with writer.as_default():
17    tf.summary.image("debug/annotated", tf.expand_dims(annotated, 0), step=1, max_outputs=1)

That is much more informative than logging raw input images alone.

Compare Ground Truth and Predictions Side by Side

One practical debugging pattern is to place ground truth and prediction panels next to each other:

1def make_debug_panel(image, gt_boxes, pred_boxes):
2    left = draw_boxes(image, gt_boxes, [0.0, 1.0, 0.0])
3    right = draw_boxes(image, pred_boxes, [1.0, 0.0, 0.0])
4    return tf.concat([left, right], axis=1)

When you log a batch of these panels, TensorBoard becomes much more useful for diagnosing whether the model is missing objects, hallucinating boxes, or drifting during training.

Control Logging Frequency

Image summaries are expensive compared with scalar summaries. Logging high-resolution images every step can slow training and produce very large event files.

A better pattern is to log at intervals:

1LOG_EVERY = 200
2
3for step, (images, labels) in enumerate(train_dataset, start=1):
4    # train step here
5    if step % LOG_EVERY == 0:
6        with writer.as_default():
7            tf.summary.image("train/images", images, step=step, max_outputs=8)
8
9writer.flush()

This gives you useful visual checkpoints without turning TensorBoard logging into a storage problem.

Make Sure the Image Tensor Is Valid

A surprising amount of TensorBoard confusion comes from bad image formatting rather than the summary API itself. Confirm:

• shape is (batch, height, width, channels)
• values are in a sensible range
• dtype is appropriate for the summary

If the image looks washed out or clipped, normalize and convert the data before writing the summary.

Batch Size Still Limits What You See

Even with max_outputs=20, a batch of 4 images will only show 4. That means if you want more samples visible per step, you may need:

• a larger evaluation batch
• a separate debug batch
• or several summary calls across different steps

The summary function cannot log images that are not present in the tensor you give it.

Common Pitfalls

• Increasing max_outputs without noticing that the batch itself is smaller.
• Logging only raw images instead of useful annotated debug views.
• Writing image summaries every step and creating huge event files.
• Forgetting to flush the summary writer.
• Passing badly scaled or wrongly shaped image tensors into tf.summary.image().

Summary

• Increase max_outputs to show more images per TensorBoard image summary.
• For object detection, annotated images are much more useful than raw inputs.
• Side-by-side ground truth and prediction panels are a strong debugging pattern.
• Log images at intervals instead of every step to control cost.
• Verify batch size, tensor shape, dtype, and value range before blaming TensorBoard.