Skip to main content
v2.2

Figures and Text

ChartXY has multiple types of figure series to draw 2D shapes within the chart.

These shapes include:

Figure SeriesFigure Series

Polygon Series​

Polygon series allow you to render closed shapes with multiple connected vertices.

Creating Polygon Series​

polygon_series = chart.add_polygon_series()

Adding a Polygon​

polygon = polygon_series.add([
    {'x': 0, 'y': 0},
    {'x': 4, 'y': 0},
    {'x': 2, 'y': 3}
])

Customizing Appearance​

Set stroke thickness and color:

polygon.set_stroke(thickness=2, color='#00bfff')

Set fill color:

polygon.set_color('#ffeecc')

Update polygon points:

polygon.set_dimensions([
    {'x': 1, 'y': 1},
    {'x': 3, 'y': 1},
    {'x': 2, 'y': 4}
])

Ellipse Series​

Ellipse series can draw ovals and circles at any position and size.

Creating Ellipse Series​

ellipse_series = chart.add_ellipse_series()

Adding an Ellipse​

ellipse = ellipse_series.add(x=5, y=3, radius_x=2, radius_y=1)

Customizing Appearance​

Set stroke thickness and color:

ellipse.set_stroke(1.5, '#aa22cc')

Set fill color:

ellipse.set_color('#cceeff')

Update position and size:

ellipse.set_dimensions(x=6, y=4, radius_x=2.5, radius_y=1.2)

Rectangle Series​

Rectangles are defined by two diagonal corners. This series is useful for bounding boxes or heatmap overlays.

Creating Rectangle Series​

rectangle_series = chart.add_rectangle_series()

Adding a Rectangle​

rectangle = rectangle_series.add(x1=2, y1=2, x2=6, y2=4)

Customizing Appearance​

Set stroke style:

rectangle.set_stroke(thickness=2, color='#000000')

Set fill color:

rectangle.set_color('#aaeeff')

Change size or position:

rectangle.set_dimensions(x1=1, y1=1, x2=3, y2=2)

Segment Series​

Segments are simple straight lines between two points — often used to annotate or draw bounds.

Creating Segment Series​

segment_series = chart.add_segment_series()

Adding a Segment​

segment = segment_series.add_segment(start_x=0, start_y=0, end_x=5, end_y=5)

Customizing Appearance​

Set stroke thickness and color:

segment.set_stroke(thickness=1, color='#dd4444')

Update segment coordinates:

segment.set_dimensions(start_x=1, start_y=2, end_x=4, end_y=3)

Hover Highlighting for All Figure Series​

Configure how figures respond to mouse hover interactions.

# Enable hover highlighting (default behavior)
series.set_highlight_on_hover(enabled=True)

# Disable all highlighting interactions
series.set_highlight_on_hover(enabled=False)

# Or equivalently
series.set_highlight_on_hover(enabled=True, highlight_mode='noHighlighting')

# Highlight entire series on hover
series.set_highlight_on_hover(enabled=True, highlight_mode='onHover')

# Highlight only individual figures on hover
series.set_highlight_on_hover(enabled=True, highlight_mode='onHoverIndividual')

Text Series​

Text series allow you to draw text labels at specific coordinates in the chart. This is useful for annotations, labels, or overlaying values directly on the chart.

Creating Text Series​

text_series = chart.add_text_series()

Adding Text​

text = text_series.add(x=5, y=3, text="Hello World", alignment_x=0.5, alignment_y=0.5)
  • x, y: Position of the text.
  • text: The text content.
  • alignment_x: Horizontal alignment.
  • alignment_y: Vertical alignment.

Customizing Appearance​

Change text content:

text.set_text("Updated Label")

Set location:

text.set_location(x=6, y=4)

Set alignment:

text.set_alignment(x=1, y=0)

Set font style:

text.set_font(size=16, family='Arial, Helvetica, sans-serif')

Set text color:

text.set_color('#ff0000')

Set margin around the text:

text.set_margin(5)  # uniform margin
# or individually
text.set_margin(left=10, top=15, right=20, bottom=25)

All Figure and Text Series Common Methods​

Series Utility Methods​

This section works the same as for Line, to avoid duplication of guides, please refer to the section under Line

Series Configuration​

Auto-scrolling with axes:

series.set_auto_scrolling_enabled(True)

Legend​

Please see common legend section.

Examples​

Link to the examples