Polar and radial geometry

Polar and radial geometry

Standalone Charts and Pivot share geometry controls for polarColumn, stackedPolarColumn, normalizedPolarColumn, radialColumn, radialBar and multiRingRadialBar. These are saved chartOptions, available in Pivot under Customize → Appearance.

const chart = await createChart({
  container,
  chartType: 'polarColumn',
  dataset: createChartDataset(rows, {
    category: { field: 'month' },
    series: [{ field: 'actual' }, { field: 'planned' }],
  }),
  chartOptions: {
    startAngle: -180,
    sweepAngle: 180,
    polarReverse: false,
    innerRadius: 0.3,
    outerRadius: 0.9,
    groupPadding: 0.2,
    barPadding: 0.15,
  },
});

Options and defaults

Field	Default	Contract
startAngle	-90	Integer -360–360 degrees. Zero points right; -90 points up.
sweepAngle	360	Integer 1–360 degrees. Restricts sectors and radial tracks to the same angular range.
polarReverse	false	Counterclockwise angular projection when true. Keeps canonical category/series order.
innerRadius	0; 0.25 for radialColumn	Fitted-radius ratio 0–0.95, with editor step 0.05. Defines the hole/radial baseline.
outerRadius	1	Fitted-radius ratio 0.05–1, with editor step 0.05. Defines the outer radial endpoint.
groupPadding	0.1 when configured	Gap ratio 0–0.95 of a category sector or radial ring slot, split equally between its two edges; editor step 0.05.
barPadding	0.1 when configured	Only polarColumn and radialColumn: gap ratio 0–0.95 inside each grouped series slot after category padding; editor step 0.05. Rejected on stacked sectors and angular radial bars.
radialStacking	false	Existing multiRingRadialBar option: accumulate series angularly in a category-owned ring.

With all geometry fields omitted, existing full-circle shapes and legacy pixel spacing remain unchanged. Authoring any of the seven geometry fields enables the common configurable frame and its ratio-based spacing defaults. Resetting all seven fields restores legacy spacing. radialStacking alone retains the legacy frame. The editor’s normal reset button removes an authored field.

The fitted radius comes from the available plot after ordinary title/legend layout. Ratios use that radius, so resizing scales the hole and endpoints consistently. If innerRadius exceeds outerRadius, the actual inner radius clamps to the outer radius; geometry can collapse to zero thickness without negative radii. The rectangular radialColumn uses radial endpoint distances and tangential rectangles, retaining its 24-pixel width cap. Authored narrow slots can produce widths below a pixel; no minimum width overrides their gaps.

Sector and ring layouts

For polar columns, the sweep is divided into category sectors. groupPadding insets those sectors. Grouped polarColumn and rectangular radialColumn then partition the remaining angle into series slots and apply barPadding. Stacked/normalized columns share the same category angles and accumulate along the radius above the hole. Normalized columns fill the available radial span for each category. Grid arcs, spokes and category labels follow the same rotation, sweep, direction and fitted radii; partial sweeps leave an open gap.

For radialBar, each positive category value owns a ring. For unstacked multiRingRadialBar, each positive category/series entry owns a ring. With radialStacking: true, series share a category ring and accumulate along the configured sweep. groupPadding separates those radial ring slots. Tracks use the full authored sweep; values use their ordinary shared maximum (or shared maximum category total when stacked). Category labels move to the authored start angle on the open side of the sweep, while value labels follow the directed value endpoint.

These changes retain existing positive-value contracts: null, zero and negative cells do not invent a visible bar, and ordinary chart-type validation still applies. Raw values are never converted into geometry ratios in the dataset, tooltips, activation callbacks or CSV. Large finite values use bounded weights before accumulation, preserving relative geometry without summing overflowing raw totals. Categories marked as subtotal/grand total remain excluded.

Shared lifecycle and Pivot

Settings survive model saving/restoration and work with server SVG, in-place hydration, resize and image/SVG/PDF export. Invalid types or out-of-range fields reject before committing a new frame. Rendering uses one shared Charts owner; Pivot consumes the same option schema and renderer. Gallery changes retain supported fields and remove unsupported ones (for example barPadding when switching to stacked polar columns).

Localize the normal localeText.chartOptions.labels and descriptions entries for the field names above. The new captions are polarReverse and barPadding. UI-policy IDs are chartOptions.<field>, including each field’s reset control.

This implements polar geometry authoring. Arbitrary placement callbacks, automatic multi-axis gutters, polar navigation/gestures and mixed polar composition remain separate capabilities. See radar metric axes for the distinct radarLine/radarArea contract. MUI’s radial bars and radial axes describe the related rotation/radius and spacing capabilities; the contracts above are our public API.

See polar numeric value axes for radial/angular scale, bounds, ticks and clipping.