Node.js and Python · shared Rust core

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.

FamilySVGPNG
LinerenderLineToSVGrenderLineToPNG
BarrenderBarToSVGrenderBarToPNG
Pie / DonutrenderPieToSVGrenderPieToPNG
Polar / WindroserenderPolarToSVGrenderPolarToPNG
HeatmaprenderHeatmapToSVGrenderHeatmapToPNG
WonderplotrenderWonderplotToSVGrenderWonderplotToPNG
World MaprenderMapToSVGrenderMapToPNG

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[].points are 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, y and row-major values; 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.

DatasetNode PNG / SVGPython PNG / SVGPNG / vector SVG size
Heatmap, 1,000,000 cells7.668 / 7.414 s6.700 / 18.944 s6,667 / 159,680,423 bytes
Wonderplot, 100,000 points0.664 / 0.771 s0.916 / 1.146 s196,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)[] })[];
};