Server-side rendering
Export static SVG and PNG images for six 2D chart families and World Map without a browser.
Server-side SVG and PNG
Render six 2D families and World Map without a browser using the shared Rust renderer in Node.js or FastPlotPy. SVG and PNG use the same prepared geometry; SVG text is embedded as glyph outlines and is not normally selectable. The server contract is a static, serializable document, separate from interactive browser PlotOptions.
Node requires the native addon; Python requires its native library. The published Node package contains Windows x64 and Linux x64 native addons; installed exports were checked on both. The Python release provides Windows x64 and Linux x64 wheels, with the Linux wheel tagged for glibc 2.38 or newer. Installed wheel behavior was verified on CPython 3.12 on Windows x64 and Linux x86-64; other Python versions and platforms have not been verified for this release. Linux Node addon validation used glibc 2.39; its newest required symbol is GLIBC_2.38. macOS, arm64 and musl Linux are outside the published native binary set. Source builds need the platform toolchain described by each package. Runtime does not require system ICU data or an ICU DLL. Check the npm and PyPI release files for platform availability.
Fourteen image export functions
Import these names from fastplotjs or fastplotpy. Each takes its family’s options object. Node returns a Promise of SVG string or PNG Uint8Array; Python returns str or bytes.
| Family | SVG | PNG |
|---|---|---|
| Line | renderLineToSVG | renderLineToPNG |
| Bar | renderBarToSVG | renderBarToPNG |
| Pie / Donut | renderPieToSVG | renderPieToPNG |
| Polar / Windrose | renderPolarToSVG | renderPolarToPNG |
| Heatmap | renderHeatmapToSVG | renderHeatmapToPNG |
| Wonderplot | renderWonderplotToSVG | renderWonderplotToPNG |
| World Map | renderMapToSVG | renderMapToPNG |
Errors expose ServerLineExportError.code. The older renderToPNG() remains unchanged and returns UTF-8 JSON scene bytes, not a PNG image. Use the new family-specific method for real image bytes.
Run an export
Install fastplotjs@0.7.0 or fastplotpy==0.5.0a2 and run with the native runtime available. These are standalone examples using the Line contract; other families use their own document shapes below.
JavaScript
import { writeFile } from "node:fs/promises";
import { renderLineToSVG, renderLineToPNG } from "fastplotjs";
const options = {
width: 900, height: 520, title: "Temperature",
xLabel: "Time", yLabel: "Value",
traces: [{ name: "Sensor", color: "#2563eb", lineWidth: 2,
points: [[0, 3], [2, 7], null, [6, 8], [8, 6]] }]
};
await writeFile("line.svg", await renderLineToSVG(options));
await writeFile("line.png", await renderLineToPNG(options));TypeScript
Use the same example in a TypeScript module, adding import type { ServerLineOptions } from "fastplotjs"; and annotating the document as const options: ServerLineOptions = .... This preserves the coordinate tuple type.
Python
from pathlib import Path
from fastplotpy import renderLineToSVG, renderLineToPNG
options = {
"width": 900, "height": 520, "title": "Temperature",
"xLabel": "Time", "yLabel": "Value",
"traces": [{"name": "Sensor", "color": "#2563eb", "lineWidth": 2,
"points": [[0, 3], [2, 7], None, [6, 8], [8, 6]]}],
}
Path("line.svg").write_text(renderLineToSVG(options), encoding="utf-8")
Path("line.png").write_bytes(renderLineToPNG(options))Export a World Map
The server Map accepts a separate serializable document. Omit map.regions for the point-only land basemap; provide { id, value } entries to color bundled country areas. Region IDs are Natural Earth ADM0_A3 codes rather than ISO codes. Unknown and duplicate IDs fail. The shared value scale includes regions and visible points.
Node.js
import { renderMapToSVG, renderMapToPNG } from "fastplotjs";
const map = { schemaVersion: 1, width: 800, height: 500,
map: { regions: [{ id: "FRA", value: 68 }] },
traces: [{ points: [{ longitude: 2.3522, latitude: 48.8566, value: 68 }] }] };
const svg = await renderMapToSVG(map);
const png = await renderMapToPNG(map);Python
from fastplotpy import renderMapToSVG, renderMapToPNG
map_document = {"schemaVersion": 1, "width": 800, "height": 500,
"map": {"regions": [{"id": "FRA", "value": 68}]},
"traces": [{"points": [{"longitude": 2.3522, "latitude": 48.8566, "value": 68}]}]}
svg = renderMapToSVG(map_document)
png = renderMapToPNG(map_document)These static methods need the native runtime and do not accept browser callbacks or interactive chart options.
Family contracts and constraints
Use plain JSON data, finite numbers, explicit nulls for missing values and supported fields only. Unknown fields fail. Callback formatters, custom fonts and browser interaction are not supported. Colors are #RRGGBB or #RRGGBBAA; bundled Noto glyph outlines are used. Unsupported glyphs can fail. Labels may be suppressed when they do not fit or collide; unsupported scripts and complex text layouts are not generally guaranteed.
- Line: numeric linear axes;
traces[].pointsare finite[x,y]pairs or null gaps. Optional domains, labels, color, width and area fill; no dates, logarithmic or category axes, markers or subplots. - Bar: grouped, stacked or normalized; vertical or horizontal; numeric, category or datetime coordinates; trace styling, value labels and non-overlapping rectangular subplots. A non-linear value axis needs an explicit base; stacked and normalized require a linear value axis and no base. Datetime labels use UTC.
- Pie / Donut: data or traces with label/value, sector colors and borders, inner and outer radius ratios, labels and legend. Null values are missing. At most 32 traces, 100,000 data items and 4,096 visible sectors; no subplots.
- Polar / Windrose: grouped or stacked sectors, linear or logarithmic radius, grid, labels, vectors, legend and per-trace style. At most 32 traces, 100,000 points and 4,096 visible sectors; no subplots.
- Heatmap:
x,yand row-majorvalues; row zero is the lowest y and drawn at the bottom. Numeric coordinates are strictly increasing; categories are unique nonempty strings. Cells are equal rank-grid widths. Up to 2,048 coordinates per axis and 1,000,000 values; 32 MiB input. Supports missing cells, color scales, guides, labels and legend; each enabled axis label list is limited to 128 entries. No subplots. - Wonderplot: up to 32 traces, 100,000 points, 16 panels and 8 MiB input; linear, logarithmic, datetime and categorical axes; named axes, marker shapes, size/opacity/color scales, labels, error bars, references, legends and explicit or weighted subplots. At most one used axis per side of a panel. When marker labels are enabled, at most 4,096 candidate points across visible traces are allowed, including null or missing-coordinate points.
Images have a minimum of 200 × 150 pixels, maximum 8,192 per edge and 16,777,216 pixels in total. The renderer admits two concurrent jobs; excess requests fail BUSY; Node additionally limits queued/running tasks to eight. Limits are safety bounds, not performance promises. Each family has further validation, including label and layout limits; invalid documents fail rather than becoming browser options.
Wonderplot date and time formatting
Named datetime axes accept epoch milliseconds or RFC 3339 strings. The server uses pinned ICU 78.2 with fixed en-US locale. An omitted or browser outer dateTime.timeZone means UTC; explicit IANA zones and UTC are supported. The outer timezone overrides format.timeZone. Both basic and best fit format matchers use ICU best fit. Supported data-only dateTime.format fields are:
localeMatcher, calendar, numberingSystem, era, dayPeriod, hourCycle, formatMatcher, dateStyle, timeStyle, timeZone, year, month, day, weekday, hour, minute, second, fractionalSecondDigits, hour12, timeZoneName.
Options are validated, including invalid style/component combinations. Bounded visual and glyph checks do not prove every bidi or layout permutation.
Measured examples
Single bounded observations on Windows x64 using Node 24.15.0 and Python 3.12.1; elapsed time is the public API observation, not a benchmark guarantee or SLA. Input, environment and measurement scope affect results.
| Dataset | Node PNG / SVG | Python PNG / SVG | PNG / vector SVG size |
|---|---|---|---|
| Heatmap, 1,000,000 cells | 7.668 / 7.414 s | 6.700 / 18.944 s | 6,667 / 159,680,423 bytes |
| Wonderplot, 100,000 points | 0.664 / 0.771 s | 0.916 / 1.146 s | 196,584 / 56,924,458 bytes |
Each dataset produced byte-identical Node and Python outputs. The dense SVGs contain one million cell paths or 100,000 marker paths respectively; fully vector output can be large.
Server option fields
These field summaries describe the static document types; helper types may be shared between sections. Import public option types from the package root. Python uses the same JSON-shaped field names. Validation and limits above still apply; optional fields do not imply arbitrary browser options.
Line
export type ServerLineOptions = {
schemaVersion?: 1;
width?: number;
height?: number;
title?: string;
xLabel?: string;
yLabel?: string;
tickCount?: number;
xDomain?: [number, number];
yDomain?: [number, number];
background?: string;
traces: {
name?: string;
color?: string;
lineWidth?: number;
areaFill?: string;
points: ([number, number] | null)[];
}[];
};Bar
export type ServerBarAxis = { scale?: "linear" | "logarithmic" | "datetime"; domain?: [number, number]; categories?: string[]; label?: string };
export type ServerBarLabels = boolean | { show?: boolean; color?: string; position?: "center" | "inside-end" | "outside-end"; offset?: number; decimals?: number; prefix?: string; suffix?: string; minBarWidth?: number; minBarHeight?: number };
export type ServerBarOptions = {
schemaVersion?: 1; width?: number; height?: number; title?: string; background?: string; tickCount?: number;
mode?: "grouped" | "stacked" | "normalized"; orientation?: "vertical" | "horizontal"; barWidthRatio?: number;
xAxis?: ServerBarAxis; yAxis?: ServerBarAxis; valueLabels?: ServerBarLabels;
subplots?: { id: string; left: number; top: number; width: number; height: number; title?: string; xAxis?: ServerBarAxis; yAxis?: ServerBarAxis }[];
traces: { name?: string; color?: string; borderColor?: string; borderWidth?: number; cornerRadius?: number; valueLabels?: ServerBarLabels; subplot?: string; points: ({ x: number | string | null; y: number | string | null; base?: number | string | null } | null)[] }[];
};Pie
type PieDatum = { label?: string; value: number | null };
type PieLabels = boolean | { show?: boolean; position?: "inside" | "outside"; content?: "label" | "value" | "fraction" | "label-value" | "label-fraction"; color?: string; decimals?: number; prefix?: string; suffix?: string; minSectorAngleDegrees?: number; radiusRatio?: number; offset?: number; collisionPadding?: number };
export type ServerPieOptions = {
schemaVersion?: 1; width?: number; height?: number; title?: string; background?: string;
data?: PieDatum[]; traces?: { name?: string; visible?: boolean; color?: string; hiddenDataIndexes?: number[]; data: PieDatum[] }[]; hiddenDataIndexes?: number[];
startAngleDegrees?: number; clockwise?: boolean; sectorGapDegrees?: number; sectorOpacity?: number; borderColor?: string; borderWidth?: number;
innerRadiusRatio?: number; outerRadiusRatio?: number; colors?: string[]; labels?: PieLabels; legend?: boolean;
};Polar
type SectorLabels = boolean | { show?: boolean; color?: string; decimals?: number; prefix?: string; suffix?: string; minSectorRadius?: number; minSectorAngleDegrees?: number; radiusRatio?: number; collisionPadding?: number };
type VectorDirection = number | { direction?: number; directionDegrees?: number; color?: string; lineWidth?: number; headSize?: number; headAngleDegrees?: number };
type Vectors = { show?: boolean; directions?: VectorDirection[]; color?: string; lineWidth?: number; headSize?: number; headAngleDegrees?: number };
export type ServerPolarOptions = {
schemaVersion?: 1; width?: number; height?: number; title?: string; background?: string;
mode?: "windrose"; radialScale?: "linear" | "logarithmic"; sectorMode?: "grouped" | "stacked"; angleCategories?: string[];
sectorWidthDegrees?: number; sectorGapDegrees?: number; sectorOpacity?: number; startAngleDegrees?: number; clockwise?: boolean;
innerRadiusRatio?: number; outerRadiusRatio?: number; minRadius?: number; maxRadius?: number; borderColor?: string; borderWidth?: number; sectorLabels?: SectorLabels;
grid?: { show?: boolean; rings?: number; ringValues?: number[]; spokes?: number; ringColor?: string; spokeColor?: string; ringLineWidth?: number; spokeLineWidth?: number;
labels?: boolean | { show?: boolean; color?: string; decimals?: number; angleDegrees?: number; offset?: number; prefix?: string; suffix?: string };
angleLabels?: boolean | { show?: boolean; color?: string; decimals?: number; offset?: number; labels?: string[]; prefix?: string; suffix?: string } };
vectors?: Vectors; legend?: boolean;
traces: { name?: string; color?: string; visible?: boolean; sectorGapDegrees?: number; sectorOpacity?: number; borderColor?: string; borderWidth?: number; sectorLabels?: SectorLabels; polarVector?: boolean | Vectors; points: ({ angle: number | string | null; value: number | null } | null)[] }[];
};Heatmap
type AxisLabels = boolean | string[] | { show?: boolean; labels?: string[]; color?: string };
export type ServerHeatmapOptions = {
schemaVersion?: 1; width?: number; height?: number; title?: string; background?: string;
x: number[] | string[]; y: number[] | string[]; values: (number | null)[];
valueScale?: "linear" | "logarithmic"; minValue?: number; maxValue?: number;
lowColor?: string; highColor?: string; colorStops?: { offset: number; color: string }[];
cellGap?: number; cornerRadius?: number; borderWidth?: number; borderColor?: string;
missingCells?: boolean | { show?: boolean; fillColor?: string; borderColor?: string; borderWidth?: number };
cellLabels?: boolean | { show?: boolean; color?: string; autoContrast?: boolean; decimals?: number; prefix?: string; suffix?: string; padding?: number; minCellWidth?: number; minCellHeight?: number };
xLabels?: AxisLabels; yLabels?: AxisLabels;
guides?: boolean | { show?: boolean; color?: string; lineWidth?: number };
colorScaleLegend?: boolean | { show?: boolean; position?: "left" | "right" | "top" | "bottom"; title?: string; tickValues?: number[]; tickCount?: number; decimals?: number; labelPrefix?: string; labelSuffix?: string; color?: string; width?: number; height?: number; offset?: number; tickSize?: number; labelGap?: number; titleGap?: number; borderColor?: string; borderWidth?: number; fontSize?: number; lineHeight?: number };
};Wonderplot
type Shape = "circle" | "square" | "diamond" | "triangle" | "pentagon" | "hexagon";
type Coordinate = number | string;
type ErrorValue = number | { minus: number; plus: number };
type ErrorBars = boolean | { show?: boolean; x?: boolean; y?: boolean; color?: string; lineWidth?: number; capSize?: number };
type MarkerLabels = boolean | { show?: boolean; color?: string; fontSize?: number; lineHeight?: number; decimals?: number; prefix?: string; suffix?: string; offsetY?: number; collisionPadding?: number };
type Scale = boolean | { enabled?: boolean; minValue?: number; maxValue?: number; minSize?: number; maxSize?: number; minOpacity?: number; maxOpacity?: number };
type TextStyle = { color?: string; fontSize?: number; lineHeight?: number };
type NamedAxis<Side extends string> = ServerBarAxis & { show?: boolean; side?: Side; title?: string; range?: { min: Coordinate; max: Coordinate }; ticks?: number; tickValues?: Coordinate[]; tickLength?: number; tickDirection?: "inside" | "outside" | "cross"; labelPrefix?: string; labelSuffix?: string; decimals?: number; padding?: number | { start?: number; end?: number }; labelRotationDegrees?: number; labelCollision?: "allow" | "hide"; grid?: boolean; gridStyle?: { color?: string; lineWidth?: number }; lineStyle?: { color?: string; lineWidth?: number }; labelStyle?: TextStyle; titleStyle?: TextStyle; minor?: { show?: boolean; ticks?: "inside" | "outside"; ticklen?: number; grid?: boolean }; minorLogLabels?: "none" | "small" | "complete"; dateTime?: { timeZone?: string; format?: Intl.DateTimeFormatOptions } };
type Legend = boolean | { show?: boolean; position?: "left" | "right" | "top" | "bottom"; title?: string; tickValues?: number[]; tickCount?: number; decimals?: number; labelPrefix?: string; labelSuffix?: string; color?: string; fontSize?: number; lineHeight?: number; width?: number; height?: number; offset?: number; tickSize?: number; labelGap?: number; titleGap?: number; borderColor?: string; borderWidth?: number };
type Style = { markerSize?: number; markerOpacity?: number; markerShape?: Shape; borderColor?: string; borderWidth?: number; markerLabels?: MarkerLabels; errorBars?: ErrorBars };
type TraceLegend = boolean | { show?: boolean; position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "outside-bottom"; layout?: "row" | "column"; groupBy?: "none" | "subplot"; groups?: { label?: string; entries: { label: string; traceIndexes: number[] }[] }[]; backgroundColor?: string; borderColor?: string; borderWidth?: number; padding?: number; textStyle?: TextStyle; groupTitleStyle?: TextStyle; style?: { text?: TextStyle; groupTitle?: TextStyle; backgroundColor?: string; borderColor?: string; borderWidth?: number; padding?: number }; itemGap?: number; groupGap?: number; itemTextGap?: number; itemLineLength?: number; itemLineWidth?: number; itemMarkerSize?: number; outsideGap?: number };
export type ServerWonderplotOptions = Style & {
schemaVersion?: 1; width?: number; height?: number; title?: string; subtitle?: string; titleStyle?: TextStyle; subtitleStyle?: TextStyle; background?: string; backgroundColor?: string; plotAreaBackgroundColor?: string; margin?: { l?: number; r?: number; t?: number; b?: number }; tickCount?: number;
xAxis?: ServerBarAxis; yAxis?: ServerBarAxis; xAxes?: Record<string, NamedAxis<"top" | "bottom">>; yAxes?: Record<string, NamedAxis<"left" | "right">>;
colorScale?: { valueScale?: "linear" | "logarithmic"; lowColor?: string; highColor?: string; colorStops?: { offset: number; color: string }[]; minValue?: number; maxValue?: number };
colorScaleLegend?: Legend; sizeScale?: Scale; opacityScale?: Scale; legend?: TraceLegend;
references?: { lines?: { axis: "x" | "y"; value: Coordinate; color?: string; lineWidth?: number; pattern?: "solid" | "dashed" | "dotted" | "dash-dot"; label?: string; labelStyle?: TextStyle; subplot?: string; axisId?: string }[]; bands?: { axis: "x" | "y"; from: Coordinate; to: Coordinate; fillColor?: string; label?: string; labelStyle?: TextStyle; subplot?: string; axisId?: string }[] };
subplots?: { id: string; left: number; top: number; width: number; height: number; xAxis?: ServerBarAxis; yAxis?: ServerBarAxis; title?: string; xAxisId?: string; yAxisId?: string }[];
subplotLayout?: { rows: { weight?: number }[]; columns: { weight?: number }[]; rowGap?: number; columnGap?: number; items: { id: string; row: number; column: number; rowSpan?: number; columnSpan?: number; title?: string; xAxisId?: string; yAxisId?: string }[] };
traces: (Style & { name?: string; color?: string; visible?: boolean; subplot?: string; xAxisId?: string; yAxisId?: string; points: ({ x: Coordinate | null; y: Coordinate | null; value?: number | null; z?: number | null; size?: number | null; opacity?: number | null; xError?: ErrorValue | null; yError?: ErrorValue | null } | null)[] })[];
};