Charts¶

Actions¶

Supported Chart Types¶

chart_type is a plain string: "bar", "line", or "pie". There is no doughnut, scatter, area, or 3D variant in this tool surface — pick the closest of the three:

Multi-Series Charts¶

chart(action: "add-chart", ...) always creates the chart with exactly one series. To add more series (e.g., "Revenue" and "Cost" side by side), call chart(action: "add-series", ...) once per additional series against the shape returned by add-chart:

chart(action: "add-chart", session_id: ..., slide_index: ..., chart_type: "bar",
  left: 60, top: 120, width: 500, height: 300,
  categories: ["Q1", "Q2", "Q3", "Q4"],
  series_name: "Revenue",
  values: [120.0, 150.0, 170.0, 210.0])
## → shapeIndex from the result above

chart(action: "add-series", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  series_name: "Cost", values: [80.0, 95.0, 110.0, 130.0])

Each add-series call's values array length must match the chart's existing category count (from the original add-chart call) — a mismatch returns Success=false without throwing.

Replacing Chart Data¶

Unlike add-series (which appends one more series to the existing category count), chart(action: "replace-chart-data", ...) wholesale-replaces an existing chart's categories, series names, and values in a single call — including changing the number of categories. This avoids the delete-shape-and-recreate workaround mentioned above.

series_values is a flat, series-major array: all values for series_names[0] first, then all values for series_names[1], etc. Its length must equal categories.length * series_names.length.

chart(action: "replace-chart-data", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  categories: ["Jan", "Feb", "Mar", "Apr"],
  series_names: ["Revenue", "Cost"],
  # Revenue: 100, 200, 300, 400 — then Cost: 50, 60, 70, 80
  series_values: [100.0, 200.0, 300.0, 400.0, 50.0, 60.0, 70.0, 80.0])

A mismatched series_values length or an invalid/non-chart shape_index returns Success=false without throwing.

Pie Charts¶

For "pie", categories become the slice labels and values the slice sizes — keep to 6 or fewer categories so labels stay legible once rendered. add-series is rarely useful on a pie chart (pie charts render only their first series).

Titles and Legend¶

Use set-chart-title/set-axis-title to label the chart and its axes directly, instead of (or in addition to) a nearby text-box callout:

chart(action: "set-chart-title", session_id: ..., slide_index: ..., shape_index: ..., title: "Quarterly Revenue")
chart(action: "set-axis-title", session_id: ..., slide_index: ..., shape_index: ..., axis_type: "category", title: "Quarter")
chart(action: "set-axis-title", session_id: ..., slide_index: ..., shape_index: ..., axis_type: "value", title: "USD (thousands)")
chart(action: "set-legend-visibility", session_id: ..., slide_index: ..., shape_index: ..., visible: true)

set-legend-visibility with visible: true is recommended whenever a chart has more than one series — without a visible legend, a multi-series chart's colors are unlabeled.

Quick Formatting¶

Use the paired style, color-style, and data-table actions to make a chart visually consistent and then verify the saved state:

chart(action: "set-style", session_id: ..., slide_index: ..., shape_index: ..., style: 10)
chart(action: "get-style", session_id: ..., slide_index: ..., shape_index: ...)
chart(action: "set-color-style", session_id: ..., slide_index: ..., shape_index: ..., color_style: 4)
chart(action: "get-color-style", session_id: ..., slide_index: ..., shape_index: ...)
chart(action: "set-data-table", session_id: ..., slide_index: ..., shape_index: ..., visible: true)
chart(action: "get-data-table", session_id: ..., slide_index: ..., shape_index: ...)

Direct PIA characterization tests verify that installed PowerPoint accepts style 48 and color style 26, then rejects the first following values (49 and 27) without changing the chart. Range tests exercise every accepted value. Commands return Success=false before PowerPoint is called for values outside those observed ranges, so invalid input does not change the chart or destabilize the presentation session.

Sizing and Placement¶

• Keep charts within the slide's safe area (see deck-builder.md positioning reference).
• Leave room beside or below the chart for a text-box callout describing the key takeaway, unless you've already used set-chart-title/set-axis-title to label it directly.
• Minimum practical size: width ≥ 300, height ≥ 200 — smaller charts render illegibly once exported.

Reading Back Chart Data¶

chart(action: "get-chart-data", ...) only reports categoryCount/seriesCount — it does not return the actual category labels or values. Use it to confirm a chart was created with the expected shape (e.g., 4 categories, 1 series) after add-chart, not to recover the original data for editing. To change the category labels or values, use replace-chart-data (see "Replacing Chart Data" above) rather than deleting and recreating the shape.

Verify Visually¶

Charts are the highest-value target for export(action: "export-slide-to-image", ...) — data-entry mistakes (wrong values, mismatched category count) are invisible from a get-chart-data call alone but obvious in the rendered image. Always export and inspect after add-chart/add-series (see export-and-verify.md).