Skip to content

Add annotation support (text labels, arrows, horizontal/vertical lines) #9

Description

@MoonFlowww

Summary

Add an annotation API for adding callout text, reference lines, and arrows to plots — matching matplotlib's ax.annotate(), ax.axhline(), and ax.axvline().

Motivation

Performance plots often need annotations: marking the SLA threshold with a horizontal line, labeling the fastest implementation directly on the chart, or drawing an arrow to a regression point. Without annotations, these must be added in post-processing.

Proposed API

// Horizontal/vertical reference lines (in data coordinates)
figure.axhline(100.0)                          // y = 100 ns SLA threshold
      .color(sepia::Color{255, 60, 60})
      .style(sepia::LineStyle::Dashed)
      .label("SLA limit");

figure.axvline(512.0)                          // x = 512 (input size boundary)
      .color(sepia::Color{120, 120, 120});

// Text annotation at a data coordinate
figure.annotate("peak throughput", /*x=*/3.5, /*y=*/142.0)
      .font_size(10)
      .color(sepia::Color{40, 40, 40})
      .offset_px(5, -8);                       // pixel offset from anchor point

// Arrow annotation (from label position to data point)
figure.annotate("bottleneck", /*label_x=*/2.0, /*label_y=*/50.0)
      .arrow_to(/*data_x=*/3.5, /*data_y=*/120.0)
      .color(sepia::Color{200, 60, 60});

Implementation Notes

  • axhline / axvline: Store a y (or x) value + style. During render(), draw a full-width line at the transformed coordinate using existing draw_line(). Add to legend if .label() is set.
  • annotate (text only): Transform data coords to pixel coords, call text_renderer.draw_text() at (px + offset_x, py + offset_y).
  • annotate with arrow: Draw the text, then a line from the text anchor to the data point. Arrow head = small filled triangle using fill_rect approximation or two short lines.
  • Annotations stored as a separate std::vector<AnnotationEntry> in Figure, rendered last (on top of data).

Acceptance Criteria

  • axhline() and axvline() draw correctly across the full plot area
  • axhline/axvline entries appear in legend when .label() is set
  • annotate() places text at correct data-space coordinates
  • Arrow variant draws a line+arrowhead from text to target point
  • Annotations render on top of plot data
  • Example: examples/annotations.cpp showing an SLA line + labeled peak

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions