animation.add_repeating_overlay

animation.add_repeating_overlay(
    fig,
    overlay_text,
    first_start_frame,
    on_duration_frames,
    off_duration_frames,
    rect_color='grey',
    rect_opacity=0.5,
    text_size=40,
    text_font_color='white',
    relative_text_position_x=0.5,
    relative_text_position_y=0.5,
)

Add a repeating overlay (rectangle and text) to an animated Plotly figure using traces.

This function adds overlay elements as additional traces rather than layout shapes/annotations, which enables the overlay to work without requiring redraw=True during animation. The overlay follows a repeating on/off pattern starting from a specified frame.

Parameters

fig : plotly.graph_objects.Figure The animated Plotly figure object to modify. overlay_text : str The text to display in the overlay. first_start_frame : int The frame index where the overlay first appears. Must be >= 0. on_duration_frames : float The number of frames the overlay remains visible. Will be converted to int. off_duration_frames : float The number of frames the overlay is hidden between appearances. Will be converted to int. rect_color : str, default ‘grey’ The background color of the overlay rectangle. Accepts any valid CSS color string (e.g., ‘red’, ‘#FF0000’, ‘rgba(255,0,0,0.5)’). rect_opacity : float, default 0.5 The opacity of the overlay rectangle. Must be between 0 (transparent) and 1 (opaque). text_size : int, default 40 The font size of the overlay text in points. text_font_color : str, default ‘white’ The color of the overlay text. Accepts any valid CSS color string. relative_text_position_x : float, default 0.5 The horizontal position of the text within the overlay rectangle. 0.0 = left edge, 0.5 = center, 1.0 = right edge. relative_text_position_y : float, default 0.5 The vertical position of the text within the overlay rectangle. 0.0 = bottom edge, 0.5 = center, 1.0 = top edge.

Returns

plotly.graph_objects.Figure The modified Plotly figure object with the repeating overlay added as traces. The original figure is modified in-place and also returned.

Notes

  • The overlay uses secondary axes (x2, y2) to position elements in paper coordinates (0 to 1 range) independent of the main plot’s data coordinates.
  • The overlay pattern repeats with a cycle length of (on_duration_frames + off_duration_frames).
  • Frame indexing is 0-based, so first_start_frame=0 means the overlay starts from the first frame.
  • The condition i > start_frame ensures the overlay doesn’t appear on the initial frame unless explicitly specified.
  • This implementation works without requiring redraw=True in animation configurations, making it more efficient for complex animated plots.
  • returns UserWarning If the figure has no frames, a warning is printed and the figure is returned unchanged.
  • returns UserWarning If the sum of on_duration_frames and off_duration_frames is not positive, a warning is printed and the figure is returned unchanged.