SheetCharts
Charting engine of ORIX Sheet: a pure model + drawing package (Swift 6, macOS 14+). It depends on SheetCore,
CoreGraphics, CoreText, ImageIO and UniformTypeIdentifiers — no SwiftUI/AppKit, no third-party code — so it runs
headless and is fully testable.
Design rule: every mark derives from data. Nothing decorative is drawn; a value that cannot be represented (missing, non-positive on a log axis, negative in a pie) is left out and never replaced by zero.
var spec = ChartSpec(kind: .column, title: "Sales")
spec.categories = .range(sheet: "Data", range: RangeRef(a1: "A2:A13")!)
spec.series = [SeriesSpec(nameRef: .range(sheet: "Data", range: RangeRef(a1: "B1")!),
values: .range(sheet: "Data", range: RangeRef(a1: "B2:B13")!))]
let source = WorkbookDataSource(workbook: workbook)
let pdf = ChartRenderer.pdfData(spec, source: source, size: CGSize(width: 480, height: 300))
sheet.meta.objects.append(try spec.sheetObject(x: 40, y: 40, width: 480, height: 300)) // kind "chart"Layout of the package
| Directory | Content |
|---|---|
Model/ |
ChartSpec, SeriesSpec, AxisSpec, LegendSpec, Annotation, ChartOptions, ChartTheme, JSON coding |
Data/ |
ChartDataSource, WorkbookDataSource, LiteralDataSource, ChartData (resolved numbers) |
Stats/ |
quantiles, box statistics, binning, KDE, stacking, regression, marching squares, treemap, decimation, colour maps |
Scales/ |
tick generation (linear, log, calendar), AxisScaleMap, built-in axis formatter |
Canvas/ |
ChartCanvas protocol, CGChartCanvas, SVGChartCanvas, CoreText measurement |
Render/ |
scene builder, frame (title / legend), Cartesian layout and axes, ChartLayout, ChartRenderer |
Marks/ |
one file per family of marks (XY, bars, distributions, grids, pie, radar/treemap, surface, decorations) |
Figure/ |
ORIX Figure Studio: FigureSpec, FigureTemplates, FigureRenderer |
Suggest/ |
ChartSuggest (default charts for a selection) |
Samples/ |
deterministic synthetic sample charts (gallery, previews, tests) |
chart-gallery <dir> (executable target) writes a PNG (2x), SVG and PDF per chart kind, dark PNGs, option
variants and multi-panel figures, and prints timings.
Spec model
ChartSpec is Codable, Sendable, Hashable, versioned (schema, currently 1). encoded() /
ChartSpec.decoded(from:) give the SheetObject payload. Decoding is tolerant: the stored JSON is overlaid on
the defaults of the current model, so payloads that lack keys (older schema, hand-written JSON) still load.
FigureSpec works the same way (SheetObject.kind == "figure").
kind— 21 kinds: line, bar (horizontal), column, area, scatter, bubble, histogram, boxPlot, violin, heatmap, waterfall, candlestick, pie, donut, radar, treemap, surface3D, contour, density, timeSeries, combo.series[]—name/nameRef, and the references used by the kind:values,x,size,open/high/low/close,lower/upper(confidence band), per-seriescategories;style(colour, line width, dash, marker, fill opacity);axis(primary / secondary);kind(mark override in a combo chart: line, column, area, scatter);trendline;errorBars;showDataLabels.DataRef—.range(sheet:range:)(sheet addressed by name),.literal([Double]),.labels([String]).categories,rowLabels— band labels, pie / treemap labels, radar spokes, matrix column / row coordinates.xAxis,yAxis,y2Axis— title, unit, min / max, major step, minor ticks, scale (linear, log10, log2, date), number-format code, gridlines, reversed, label rotation,includeZero.xAxisis always the independent axis: for horizontal bars it is the one drawn on the left.legend,annotations(text, arrow, reference line, band — in data coordinates),theme,options.
What each kind reads:
| Kind | Data |
|---|---|
| line, area, column, bar, combo, radar | categories + series[].values |
| scatter, timeSeries | series[].x + values (x falls back to numeric categories, then 1, 2, 3…) |
| bubble | x, values, size |
| histogram, density, boxPlot, violin | each series' values is one sample |
| pie, donut, treemap, waterfall | first series + categories |
| candlestick | first series' open/high/low/close + categories; further series with values are line overlays |
| heatmap, contour, surface3D | one series whose values is a 2-D range, or one series per matrix row; categories / rowLabels are the column / row labels (numeric, strictly monotonic labels become coordinates for contour and surface) |
A line or area chart uses a category axis unless a series has x or xAxis.scale is log / date.
Data resolution and the missing-value rule
ChartData.resolve(spec, source:) turns references into numbers through a ChartDataSource.
WorkbookDataSource(workbook:) reads computed values, clips open-ended references (A:A) to the stored
extent, and takes an optional synchronize closure (or a lock / unlock pair) because Workbook is not
thread-safe.
Only numeric cells holding a finite number are data. Blank cells, text (including text that looks like a number), booleans, error values and NaN / ±∞ are missing. Missing values are never plotted as zero: line-type marks break (unless
options.connectGaps), bar-type marks leave the slot empty, stacks do not move, statistics exclude the value.ChartData.skippedCellscounts the non-blank cells that were skipped.
Further rules: values ≤ 0 are skipped on log axes; pie / donut / treemap draw strictly positive values only
(ChartLayout.notes reports dropped negatives); a candle needs all four prices; bubbles need a size > 0. When a
chart has nothing to draw it shows a short note ("No numeric data") instead of an empty frame.
Statistical conventions
| Topic | Convention | Reference used in tests |
|---|---|---|
| Linear ticks | steps 1-2-5 × 10^k, at least two ticks inside the range, automatic ends extended to the enclosing ticks (a bound passing a tick by < 15 % of a step does not add an interval) | matplotlib.ticker.MaxNLocator(steps=[1,2,5,10]) |
| Log ticks | integer powers of the base, regular stride when crowded, 2…9 minors; 1-2-5 multiples under one decade | numpy |
| Calendar ticks | seconds → years from serial dates through DateSerial (1900 and 1904 systems); months and years on the first day, weeks on Mondays |
Python datetime |
| Histogram bins | auto, freedmanDiaconis, sturges, scott, fixedCount, fixedWidth; bins are [a, b) with the last one closed; auto = min(max(FD, range / 2√n), Sturges); at most 2000 bins |
numpy.histogram_bin_edges / numpy.histogram (2.4) |
| Normalisation | count, density (count / (n · width)), probability | numpy density=True |
| Quartiles | Hyndman–Fan type 7 inclusive (default; Excel QUARTILE.INC), type 6 exclusive, type 2 averaged, type 8 medianUnbiased |
numpy.quantile methods linear, weibull, averaged_inverted_cdf, median_unbiased |
| Box plot | box Q1–Q3, median line, whiskers to the most extreme observation within 1.5 · IQR (Tukey) or to min / max, the rest are outliers; optional mean | matplotlib.cbook.boxplot_stats |
| KDE (violin, density) | Gaussian kernel; bandwidth silverman = 0.9 · min(s, IQR / 1.34) · n^(−1/5) (default), scott = s · n^(−1/5), or fixed; s is the sample standard deviation. No estimate (nothing drawn) for n < 2 or zero spread. Density curves extend 3 bandwidths beyond the data; violins are trimmed to the data range and all scaled to the same maximum width |
scipy.stats.gaussian_kde |
| Stacking | positive values stack upward from zero, negative values downward; 100 % mode divides by the sum of absolute values of the category | numpy cumulative sums |
| Trendlines | least squares: linear, polynomial (degree ≤ 8, solved by Householder QR on centred / scaled x), exponential (ln y on x, y > 0), logarithmic (y on ln x, x > 0), power (ln y on ln x), trailing moving average. R² is computed in the space of the fit (Excel's convention). On category axes x = 1, 2, 3… | numpy.polyfit |
| Error bars | fixed, percent of the value, k · sample standard deviation of the series, k · standard error (s / √n), custom ranges | closed forms |
| Contours | marching squares on grid nodes (inside = value ≥ level, saddles resolved by the cell mean), segments joined into polylines; filled bands are exact polygon clips of the same piecewise-linear surface | matplotlib / contourpy iso-line lengths, analytic circle |
| Treemap | squarified (Bruls, Huizing & van Wijk); areas exactly proportional to values | property tests |
| Bubbles | area proportional to size (diameter ∝ √size) | closed form |
| Waterfall | values are deltas; indices in waterfallTotals show the running sum from zero (index 0 as a total is the opening balance) |
closed form |
| Colour maps | viridis, magma, plasma, inferno, cividis, RdBu, coolwarm, BrBG, Blues, Greys — 65 anchors each, linearly interpolated; diverging maps are centred on zero unless bounds are given | matplotlib (within 4 / 255) |
| 3D surface | static orthographic projection (azimuth, elevation), quads painted far-to-near by mean depth; no perspective, lighting or interaction | — |
Reference numbers are generated by Tests/SheetChartsTests/Generators/gen_fixtures.py and gen_colormaps.py
(/opt/homebrew/bin/python3, numpy 2.4.4, scipy 1.17.1, matplotlib) into Tests/SheetChartsTests/Fixtures/.
Decimation
- Lines longer than 2000 points are reduced per horizontal bucket of 0.5 pt to at most four points — first,
lowest, highest, last, in order (
Decimation.minMaxIndices). Every bucket keeps its exact vertical extent, so the drawn envelope is unchanged while the path is bounded by the plot width. Disable withoptions.decimation = false; smoothed and area series are not decimated. - Scatter series above 20 000 opaque markers skip a marker that falls on an already occupied 0.5 pt cell (identical markers on top of each other are indistinguishable). Markers are emitted in chunks of 64 per path.
- Hit-test data always contains every point.
Measured on this machine (release build, 640 × 400 pt, best of three; resolve + layout + draw + encode):
| 100 000 points | PNG 2x | SVG | |
|---|---|---|---|
| line (decimated) | 40–45 ms | 8–9 ms | 5–6 ms |
| line, decimation off | 1.4–1.7 s | — | — |
| scatter | 0.26–0.57 s | 0.29–0.85 s | 0.10–0.18 s |
(Two runs; the machine was shared with other builds, hence the ranges.)
Drawing, layout and interaction
ChartRenderer.scene(spec, data:size:measure:viewport:formatter:) builds a ChartScene: a ChartLayout plus a
display list. scene.draw(in:) replays it into any ChartCanvas; ChartRenderer.draw / pngData / pdfData / svgString are conveniences. Cache the scene and replay it for redraws.
ChartLayout exposes the plot rectangle, axis scales and ticks (with label frames), legend entries, colour-bar
frame, every text frame, and hit-test data:
hitTest(point)→ the mark under the point, else the nearest anchor within a distance;items(alignedWith:)→ all series at the nearest x (shared tooltip);item(series:point:);dataPoint(at:)andposition(x:y:axis:)convert between canvas and data coordinates;viewport+ChartViewport.zoomed(by:aroundX:y:)/panned(dx:dy:)→ pass the result back asviewport:to zoom and pan (category axes use the category index as coordinate).
Number formatting: axes and labels use a small built-in formatter (automatic decimals from the tick step,
thousands separators from 10 000, ×10ⁿ beyond 10⁹ / below 10⁻⁴, and a subset of format codes: 0.00, #,##0,
0%, 0.00E+00, literal prefix / suffix, date-time tokens). Pass a ChartValueFormatter closure
((value, formatCode) -> String?) to delegate format codes to SheetFormat.
Themes: ChartTheme.presets — Light, Dark, Okabe–Ito (colour-blind-safe) and its dark variant, Publication,
Minimal, Financial, Presentation (light / dark), Monochrome. theme.variant(dark:) switches surfaces and palette.
ChartPalette also carries Tol "bright" and Tableau 10.
Concurrency: scenes can be built on any thread. Font matching goes through a process-wide, locked cache
(FontCache), because concurrent first-time font lookups from many threads can stall in the system font
service.
Export formats
| Format | API | Notes |
|---|---|---|
| PNG | pngData(…scale:) |
sRGB, scale pixels per point, DPI metadata |
pdfData |
single page, vector; text is text. Only heatmaps above 4096 cells embed a raster (one pixel per cell) | |
| SVG | svgString |
standalone SVG 1.1, real <text> elements, groups named series-N, grid, axes, legend… Fonts are referenced by family name, not embedded |
Coordinates are points with the origin at the top-left. CGChartCanvas(context:height:flipped:) draws into any
CGContext (views, printing).
Figure Studio
FigureSpec places FigurePanels (a ChartSpec + row / column / spans + label) on a rows × cols grid of a
figure sized in points (widthMM / heightMM convert). One FigureTypography (family + base size, from which
the whole size ladder derives) and one ChartTheme are applied to every panel; panel titles move to a header line
next to the panel label ("(a)", "A"…). shareX / shareY unify the automatic domains of continuous axes per
column / row and keep the axis title on the outer panels only. FigureRenderer offers scene, draw, pngData,
pdfData, svgString, exportData (format of the exportPreset).
FigureTemplates.all: Academic paper single column (89 mm) and double column (183 mm), Scientific publication
(174 mm, serif), Financial report (170 mm), Business presentation (16:9), Dashboard. Templates are size, grid and
typography presets only. They do not claim compliance with the requirements of any journal or publisher.
Suggestions
ChartSuggest.suggest(for:in:) trims the selection to its content, detects a header row (text over numbers) and a
category column (text, date-formatted numbers, years or 1, 2, 3…), then proposes charts best-first: time series for
dates, column / bar / pie for one measure, grouped and stacked columns for several, histogram / box plot / density
for a single long numeric column, scatter / bubble for two / three numeric columns, heatmap / contour / surface for
a bare numeric matrix, candlestick for Open / High / Low / Close headers, series-in-rows for wide tables.
ChartSuggest.analyze returns what was detected.
Known limitations
- The 3D surface is a static projection; the painter's algorithm can mis-order quads on steep, self-occluding surfaces, and its hit test returns the smallest containing quad.
- Contour charts have no in-line level labels (levels are read on the colour bar). Heatmap / contour colour bars have no title.
- A legend for bubble sizes is not drawn. One legend per chart; long legends are truncated to the available space.
- Markers of one series are filled as compound paths: with
fillOpacity < 1overlapping markers of the same series do not darken each other. - Automatic tick labels are English / invariant ("Jan", "," grouping, "." decimals). Localised output needs the
ChartValueFormatterand explicit format codes. - Text is single-line, left-to-right; long labels are truncated with an ellipsis. No rich text or line wrapping.
- SVG and PDF reference fonts by family; a viewer without the font substitutes it.
- Ranges are addressed by sheet name and are not adjusted automatically by structural edits: after a sheet
rename or an insertion / deletion of rows or columns the owner of the
SheetObjectmust callChartSpec.mapRanges(andFigureSpec.mapRanges).referencedRangeslists the dependencies. - Histograms of several series share the bin edges of the pooled data and are overlaid, not dodged or stacked.
- Stacking applies to columns, bars, areas and category-axis lines; not to continuous-x series.
- Error-bar kind
stddevdraws ± k·s around each point (not around the series mean as Excel does). shareX/shareYunify domains only; panels keep their own tick labels.
Tests
swift test — 43 test functions (three of them parameterised over the 21 kinds):
numeric algorithms against the Python references; every kind × {normal, empty, single point, all blank, negative,
1e-12…1e12, dirty (errors / text / NaN / booleans)} rendered to SVG (parsed with XMLParser), PDF and PNG; every
kind in every theme and at extreme sizes; scales × stacking × decorations on difficult data; structural checks
(marks per datum, positions through the axis scale within 0.5 pt, stack sums, bin geometry, wedge angles, bubble
areas); no clipped or overlapping text on the gallery charts at three sizes; vector-PDF heuristics (fonts present,
no image XObject except dense heatmaps); JSON round trips and tolerant decoding; data-source rules; suggestions;
figures.