API reference
Engine namespaces
Every operation of the engine, grouped by namespace.
datasets
| Name | Type | Description |
|---|---|---|
importFiles(sources, options?) | (sources: (File | FolderEntry)[], options?: ImportOptions) => Promise<ImportResult> | Import files in order: delimited text and binary formats; { ids, errors, cancelled? }. Large files go out of core. options: signal (cancel), chooseChannels (asked for files with > 2,000 channels or an ambiguous structure), pickChannels (ask for every binary file). |
warmImport(options?) | (options?: { formats?: string[] }) => void | Get the next import ready: its worker starts now and, with 'hdf5' or 'mat' in formats, loads the HDF5 reader (4.8 MB, fetched once), so a small file imports without the ~170 ms cold start. One-shot: the next import uses it, and another is prepared when the page is idle again. Call it on idle, or when the user shows import intent (drag over, file picker); skip it when navigator.connection.saveData is set. |
splitByRate(id) | (id: string) => Promise<string[]> | A combined multi-rate import as one dataset per group (read again from its file). |
combine(id) | (id: string) => Promise<string> | Datasets split from one file, combined again. |
chooseChannels(id, chooser) | (id: string, chooser: ChannelChooser) => Promise<string[] | null> | A binary import read again with the channels chooser returns (it starts from what was read); null when it cancels. |
addColumns(input) | (input: ColumnsInput) => string | Add numeric columns as a dataset; returns its id. |
replaceColumns(id, columns) | (id: string, columns: Record<string, ArrayLike<number>>) => void | New data for a dataset added with addColumns, in place: the columns passed are replaced (or added), the others kept. Same id, selection, colour, offset and laps; charts redraw on the next frame. |
addText(text, name?) | (text: string, name?: string) => Promise<string> | Parse delimited text like an imported file. name defaults to 'dataset.csv'. |
remove(id) | (id: string) => void | Remove a dataset, its laps, colours and offsets. |
clear() | () => void | Remove every dataset; worksheets and charts stay. |
configure(id, change) | (id, { parseConfig?, beacon?, selectCycles?: 'all' | 'best' }) => Promise<void> | Re-parse (in memory only) and/or split into cycles (beacon: BeaconConfig | null). selectCycles 'best' plots only the cycle with the lowest value (partial cycles ignored) instead of all. |
setColor(id, color) | (id: string, color: string | null) => void | Colour of a dataset or lap; null restores the palette colour. |
setOffset(id, x) | (id: string, x: number) => void | X shift of a dataset or lap. |
resetOffsets() | () => void | Clear every offset. |
select(ids) | (ids: string[]) => void | Replace the plotted ids (datasets, laps, live connections). |
toggle(id) | (id: string) => void | Toggle one id; a dataset with laps toggles all of them. |
selectAll() / deselectAll() | () => void | Select every dataset (laps included) / nothing. |
raw(id) | (id: string) => { rawText, data, parseConfig, kind, beacon } | The parsed content of a dataset, for configuration dialogs and previews. For an imported file, rawText is only its first 256 KB. |
columnBounds(column) | (column: string) => Promise<{ min, max } | null> | Min and max of a column across the plotted data (out-of-core, live and math channels included). |
folders
| Name | Type | Description |
|---|---|---|
canPick() | () => boolean | Whether the native directory picker exists (Chrome, Edge). |
pick() | () => Promise<FolderEntry[] | null> | Open the native directory picker; null when cancelled. |
fromFileList(files) | (files: FileList | File[]) => FolderEntry[] | Entries from <input type="file" webkitdirectory>. |
fromDataTransfer(dt) | (dt: DataTransfer) => Promise<FolderEntry[]> | Entries from a drop; folders are walked recursively. |
tree(entries, rootName?) | (entries: FolderEntry[], rootName?: string) => DirNode | A directory tree for a file picker. |
isImportable(name) | (name: string) => boolean | True for delimited text, every binary format (MF4/MDF, EDF/BDF, XDF, TDMS, HDF5, MAT, COMTRADE) and their companion files (.dbc, .tdms_index, .dat). |
worksheets
| Name | Type | Description |
|---|---|---|
add(name?) | (name?: string) => string | Add and activate a worksheet. Limit: worksheets. |
rename(id, name) | (id: string, name: string) => void | Rename. |
remove(id) | (id: string) => void | Remove; the last worksheet cannot be removed (invalid_argument). |
reorder(from, to) | (from: number, to: number) => void | Move a worksheet by index. |
activate(id) | (id: string) => void | Make it the active worksheet and reset its zoom. |
setXKey(id, key) | (id: string, key: string) => void | Change the shared X column. Drops series on that column and clears zoom, offsets and colours. |
charts
| Name | Type | Description |
|---|---|---|
add(kind, options?) | (kind: ChartKind, { worksheetId?, title?, settings?, layout? }) => string | Create a chart model. Limit: charts-per-worksheet. |
update(id, patch) | (id: string, patch: ChartSettingsPatch) => void | Merge settings; the kind cannot change. |
replaceSettings(id, settings) | (id: string, settings: PanelChartSettings) => void | Replace settings of the same kind. |
rename(id, title) | (id: string, title: string | null) => void | Set or clear the title. |
setBackground(id, color) | (id: string, color: string | null) => void | Plot background; null follows the theme. |
remove(id) | (id: string) => void | Remove the model; mounted views of it go blank. |
get(id) / list(worksheetId?) | ChartModel / ChartModel[] | Read models. |
setLayout, setLayouts, autoLayout | see Worksheets and charts | Store or re-flow layout rectangles. |
dragLayout(kind, rect, mode, dx, dy, board) | (kind, rect, 'move' | 'resize', dxPx, dyPx, { width, height }) => rect | Exported helper, not a charts method: the layout rectangle after dragging a chart to move or resize it on your grid. Store the result with setLayout. |
openWindow(id, options?) | (id, { title?, width?, height?, mount? }) => ChartWindow | Show the chart in its own browser window. Call it from a click. Returns { window, controls, view, close(), on("close") }. Throws popup_blocked. |
addSeries(id, column?) | (id: string, column?: string) => Promise<string | null> | Multi-band only. Adds a series and fits its scale. Limit: channels-per-chart. |
updateSeries(id, seriesId, patch) | (id, seriesId, patch: Partial<PlotSeries>) => Promise<void> | Patch a series; a new column re-fits the scale. |
removeSeries, reorderSeries, autoScaleSeries | (id, …) => … | Remove, reorder (by series ids) or re-fit series. |
mount(id, element, options?) | (id: string, element: HTMLElement, options?: MountOptions) => ChartView | Render the chart. See ChartView. |
setFonts(fonts) | ({ sans?, mono? }) => void | Font families for chart text; redraws mounted charts. |
kinds() / label(kind) | ChartKindInfo[] / string | Chart kinds with labels, in menu order. |
view
| Name | Type | Description |
|---|---|---|
setXRange(range, worksheetId?) | (range: [number, number] | null, worksheetId?: string) => void | Linked X zoom of a worksheet (default: active). |
resetZoom(worksheetId?) | (worksheetId?: string) => void | Full range. |
setLiveWindow(seconds) | (seconds: number | null) => void | Scrolling window of live charts on a time axis. Default 30. |
mathChannels
| Name | Type | Description |
|---|---|---|
create(input) | (input: Partial<MathChannel> & { name, formula }) => MathChannel | Create a channel. Limit: math-channels. |
update(id, patch) | (id: string, patch: MathChannelPatch) => void | Patch name, units, formula, enabled or description. |
remove(id) | (id: string) => void | Delete. |
importMany(channels) | (channels: MathChannel[]) => Promise<MathChannel[]> | Add several; returns those that fit within the limit. |
importFile(file) | (file: File) => Promise<{ channels, errors }> | Import a JSON export. |
exportBlob() | () => Blob | Every channel as a JSON file. |
preview(channel, worksheetId?) | (channel: MathChannel, worksheetId?: string) => EvalResult | null | Evaluate against the plotted data; null when nothing is plotted. |
sync(channels) | (channels: MathChannel[]) => void | Replace the list with your store’s authoritative one. |
live
| Name | Type | Description |
|---|---|---|
openLocal(name) | (name: string) => LocalLiveStream | A stream fed by your page. |
connect(stream, password) | (stream: LiveStreamDescriptor, password: string) => Promise<void> | Join an encrypted relay stream. Rejects with relay_unavailable or wrong_password. |
disconnect(id) | (id: string) => void | Leave a relay stream or close a local one. |
rowCount(id) | (id: string) => number | Samples buffered right now. |
io
| Name | Type | Description |
|---|---|---|
exportWorkspace() | () => Exported | { json, blob, filename }: envelope v2 (worksheets, active worksheet, the math channels they use, live window, lap settings; never data). Limit: workspaces-io. |
exportWorkspaceEncrypted(password) | (password: string) => Promise<Exported> | A password-protected .kymo file (PBKDF2-SHA256 600k → AES-256-GCM). Limit: workspaces-io. |
exportWorksheet(id?) / exportChart(id) | (…) => Exported | One worksheet or chart, as json and blob. |
parseFile(file) | (file: File) => Promise<ParsedFile> | What a file contains: type 'workspace' | 'worksheet' | 'chart' | 'encrypted' | 'error'. |
importWorkspace(src, { password }?) | (src, options?: { password?: string }) => Promise<{ worksheets: number; errors: string[] }> | Replace every worksheet with a v1, v2 or encrypted (.kymo) file. Errors: password_required, wrong_password, bad_workspace. |
toWorkbook() | () => WorkbookBody | Envelope v2 of the current analysis, for your own storage (not limited by workspaces-io). |
openWorkbook(body) | (body: unknown) => { worksheets: number; errors: string[] } | Apply a v1/v2 body over the loaded data: its math channels join the session (renamed " (workbook)" on a clash). |
importWorksheet(src) | (src) => Promise<string> | Append and activate a worksheet. |
importChart(src, worksheetId?) | (src, worksheetId?) => Promise<string> | Add a chart to a worksheet. |
hasWork() | () => boolean | Whether a workspace import would replace charts. |
snapshot() / restore(snap) | Snapshot | Datasets, worksheets and selection, for rebuilding state in the same page. |
reset() | () => void | No datasets, one blank worksheet. Live connections stay. |
data
| Name | Type | Description |
|---|---|---|
merged(worksheetId?) | (worksheetId?: string) => Dataset | null | The plotted datasets and live streams merged into one table, math channels materialised. For tables, previews and custom renderers. |