Scripting API Reference

All modules are global objects, so no import is needed. This page lists every function with a short description. The complete typings with all option fields and result types are in the oneai.d.ts file that ONE AI writes next to your script. Your editor uses it for autocompletion and hover help.

Some general rules:

Relative paths resolve against the script folder. Reads are allowed anywhere, writes only inside the script folder. See File access.
Functions that return an Image or Mask always return a new object and never change their input. The only exceptions are the ...InPlace and setMany / set functions.
Functions that return a Promise must be awaited.
Colors can be written as '#rrggbb', as a color name such as 'red', as a grey level 0–255 or as { r, g, b, a }.

app

Member	Description
`app.isRunning`	`false` once the user pressed Stop or the run timed out. Use it as the loop condition.
`app.throwIfStopped()`	Aborts the script immediately when the run was stopped.

camera

Function	Description
`camera.list()`	Lists detected cameras and video cameras created during this run as `{ id, name, category, index }`.
`await camera.capture(camera?)`	Captures a single frame. Accepts a camera id, name or device index. Defaults to the first camera.
`camera.video(path, options?)`	Creates a looping camera from a video file. Options: `name`, `fps` (1–90). Returns the camera info.
`await camera.preview(id, camera?, options?)`	Shows a native live preview in the image widget `id`. Options: `fps` (1–120, default 30), `title` and layout options.
`await camera.stopPreview(id)`	Stops a preview and keeps its last frame visible.

dataset

Function	Description
`dataset.open(path)`	Opens a ONE AI project file, a project folder or a bare dataset folder. Use `'.'` for the project of the script.
`dataset.labels(ds)`	Lists the classes as `{ id, name, color }`.
`dataset.splits(ds)`	Lists the existing splits, for example `Train` and `Validation`.
`dataset.samples(ds, split)`	Lists the samples of a split as `{ name, split, group, imagePath, maskPath, labelPath, hasMask }`.
`dataset.loadImage(sample)`	Loads the image of a sample.
`dataset.loadMask(sample)`	Loads the segmentation mask of a sample. Fails when `hasMask` is `false`.

font

Function	Description
`font.list()`	Lists fonts in the script folder and its `Fonts` subfolder, loaded fonts and installed font families.
`font.load(path)`	Loads a `.ttf` or `.otf` file. Afterwards its family name can be used in `image.drawText` and `image.measureText`.

fs

Function	Description
`fs.list(path, options?)`	Lists a folder as `{ name, path, size, modified, isDirectory }`. Options: `pattern`, `recursive`, `sort` (`name`, `newest`, `oldest`, `size`), `filesOnly`, `limit`.
`fs.exists(path)`	Returns `true` when a file or folder exists.
`fs.mkdir(path)`	Creates a folder and missing parents.
`fs.readText(path)`	Reads a UTF-8 text file of up to 16 MB.
`fs.writeText(path, text)`	Writes a UTF-8 text file and creates missing folders.
`fs.appendText(path, text)`	Appends to a UTF-8 text file, for example a CSV log. Creates missing folders.

http

All functions return a Promise of { status, ok, body, contentType }. Options: headers, timeoutMs. Objects passed as body are sent as JSON. Requests are limited by the HTTP Timeout and Allowed HTTP Hosts settings.

Function	Description
`await http.get(url, options?)`	Sends a GET request.
`await http.post(url, body, options?)`	Sends a POST request.
`await http.put(url, body, options?)`	Sends a PUT request.
`await http.del(url, options?)`	Sends a DELETE request.

image

Basics

Function	Description
`image.load(path)`	Loads an image from disk.
`image.save(img, path)`	Saves an image as PNG. Creates missing folders.
`image.create(width, height, color?)`	Creates an image filled with one color.
`image.clone(img)`	Creates an independent copy.
`image.release(img)`	Frees an image early. Recommended for large frames in long loops.
`image.resize(img, width, height, options?)`	Scales an image. Option `interpolation`: `nearest`, `linear`, `cubic`, `area`, `lanczos`.
`image.crop(img, x, y, width, height)`	Cuts a rectangle out of an image, clamped to the image bounds.
`image.rotate(img, degrees)`	Rotates clockwise by 90, 180 or 270 degrees.
`image.grayscale(img)`	Converts to 8 bit grayscale.
`image.pad(img, width, height, options?)`	Places the image on a larger canvas without scaling. Options: `color`, `align`.
`image.padSquare(img, options?)`	Pads the image to a square.

Pixels and statistics

Function	Description
`image.pixel(img, x, y)`	Reads one pixel as `{ r, g, b, a }`.
`image.pixels(img, options?)`	Copies all pixels as a flat RGBA array. Pass `{ typed: true }` for a fast `Uint8Array`.
`image.fromPixels(data, width, height)`	Builds an image from a flat RGBA array.
`image.stats(img, options?)`	Mean, median and standard deviation per channel over the image, a box or a mask.

Alignment and comparison

Function	Description
`image.perspectiveTransform(source, target)`	Fits the 3×3 matrix that maps one quadrilateral onto another.
`image.warp(img, matrix, width, height, options?)`	Applies a perspective transform.
`image.warpAffine(img, matrix, width, height, options?)`	Applies a 2×3 affine transform.
`image.rotationMatrix(cx, cy, degrees, scale?)`	Builds a 2×3 rotation matrix around a center.
`image.transformPoints(matrix, points)`	Transforms points with a perspective matrix.
`image.register(reference, moving, options?)`	Aligns `moving` onto `reference`. Returns `{ matrix, inliers, residual, ok, mode, reason }`.
`image.capabilities()`	Reports which OpenCV modules are available for `register`.
`image.matchBrightness(reference, moving, options?)`	Corrects the brightness of `moving` to match `reference`.
`image.residual(first, second, options?)`	Mean absolute difference of two images as `{ mean, max, count }`. Options: `box`, `mask`, `labelId`, `channels`.
`image.applyMask(img, mask, options?)`	Fills everything outside (or inside, with `invert`) the mask with a color.
`image.matchTemplate(img, template, options?)`	Finds the best positions of a template in the image.

Drawing

All drawing functions return a copy. Options: color, opacity, antialias and thickness. Shapes are filled when thickness is omitted or 0.

Function	Description
`image.line(img, from, to, options?)`	Draws a line.
`image.rectangle(img, x, y, width, height, options?)`	Draws a filled or outlined rectangle.
`image.circle(img, cx, cy, radius, options?)`	Draws a circle.
`image.circles(img, centers, radius, options?)`	Draws many circles in one call.
`image.polygon(img, points, options?)`	Draws a filled or outlined polygon.
`image.drawText(img, text, x, y, options?)`	Draws text into the pixels.
`image.measureText(text, options?)`	Measures text without drawing it.
`image.composite(img, alpha, color, options?)`	Blends a color into the image, weighted by an alpha image or mask.
`image.blend(a, b, weight)`	Blends two images of equal size.

Filters and augmentation

Function	Description
`image.gaussianBlur(img, sigma, kernelSize?)`	Gaussian blur.
`image.motionBlur(img, length, angleDegrees)`	Directional motion blur.
`image.filter(img, kernel, width, height)`	Convolves the image with a custom kernel.
`image.addNoise(img, sigma, seed?)`	Adds Gaussian noise.

log

Messages appear in the Output pane of OneWare Studio.

Function	Description
`log.info(message)`	Writes an informational message.
`log.warn(message)`	Writes a warning.
`log.error(message)`	Writes an error.
`log.debug(message)`	Writes a message that is only shown with verbose output.

mask

A mask stores one class id per pixel. 0 is background.

Create and convert

Function	Description
`mask.load(path)`	Loads a segmentation mask.
`mask.save(m, path)`	Saves a mask as 8 bit grayscale PNG, the ONE AI format.
`mask.create(width, height)`	Creates an empty mask.
`mask.full(width, height, labelId)`	Creates a mask where every pixel has one class id.
`mask.clone(m)`	Creates an independent copy.
`mask.release(m)`	Frees a mask early.
`mask.fromImage(img, options?)`	Thresholds one channel of an image. Options: `channel`, `min` (default 128), `max`, `labelId`.
`mask.fromConfidence(prediction, labelId?, options?)`	Thresholds the raw confidence of a segmentation model at `min`.
`mask.fromArray(data, width, height)`	Builds a mask from one class id per pixel.
`mask.toArray(m)`	Copies the class ids into a `Uint8Array`.
`mask.toImage(m, options?)`	Renders the mask in color.
`mask.overlay(img, m, options?)`	Draws the mask on top of an image. Options: `colors`, `opacity` (default 0.5).

Pixels

Function	Description
`mask.get(m, x, y)`	Reads the class id of one pixel.
`mask.set(m, x, y, labelId)`	Writes the class id of one pixel.
`mask.setMany(m, xs, ys, labels)`	Writes many pixels in one call.
`mask.map(m, fn)`	Builds a new mask with a function per pixel. Slow on large masks.
`mask.count(m, labelId?)`	Counts the pixels of one class, or all non-background pixels.
`mask.labels(m)`	Lists the class ids in the mask with their pixel counts.

Combine and clean up

Function	Description
`mask.binary(m, labelId)`	Keeps one class as label 1.
`mask.and(a, b)`	Keeps `a` where `b` is set.
`mask.or(a, b)`	Keeps `a`, and `b` where `a` is background.
`mask.subtract(a, b)`	Clears `a` where `b` is set.
`mask.erode(m, radius)`	Shrinks every region.
`mask.dilate(m, radius)`	Grows every region.
`mask.open(m, radius)`	Removes speckle noise.
`mask.close(m, radius)`	Fills small gaps.
`mask.fillHoles(m, options?)`	Fills enclosed holes.
`mask.keepLargest(m, options?)`	Keeps only the largest regions. Options: `labelId`, `count`, `minArea`, `connectivity`.

Geometry and drawing

Function	Description
`mask.warp(m, matrix, width, height, options?)`	Applies a perspective transform without inventing class ids.
`mask.pad(m, width, height, options?)`	Pads a mask like `image.pad`.
`mask.fillPoly(m, points, options?)`	Draws a filled polygon.
`mask.fillPolys(m, polygons, options?)`	Draws many filled polygons.
`mask.fillPolyInPlace(m, points, options?)`	Draws a filled polygon directly into the mask.
`mask.fillCircles(m, centers, radius, options?)`	Draws many filled circles.
`mask.drawText(m, text, x, y, options?)`	Draws text as class ids.

onnx

See Image Analysis & Inference for examples.

Function	Description
`onnx.predict(path, images)`	Runs a ONE AI model on one image or an ordered group of images. Returns a prediction of type `classes`, `objects`, `segmentation` or `unknown`.
`onnx.load(path, options?)`	Loads a model in advance. Option `labels` overrides the class names. Optional.
`onnx.info(path)`	Returns the model contract: model type, input size, image count, inputs, outputs and metadata.
`onnx.list(options?)`	Lists the models in `Models` (or `folder`), newest export first, each with its `info`.
`onnx.latest(filter?, options?)`	Returns the newest model whose info matches the filter, or `null`.
`onnx.toTensor(images, options)`	Builds a float input tensor for custom models.
`onnx.run(path, inputs)`	Runs any ONNX model with named input tensors and returns all outputs.
`onnx.argmaxMask(tensor, options?)`	Turns a per-pixel score tensor into a class mask.

report

Function	Description
`report.savePdf(path, data)`	Writes a PDF report and returns its absolute path. `data` has `title`, `metadata`, `summary`, `overviewImages` and `findings`.

report.savePdf('Results/report.pdf', {
    title: 'Inspection',
    summary: [{ label: 'Verdict', value: 'FAIL' }],
    overviewImages: [{ image: frame, caption: 'Capture' }],
    findings: [{ title: 'Scratch', verdict: 'Defect', area: 120, geometry: { x: 10, y: 20, width: 30, height: 8 } }]
});

shape

Function	Description
`shape.components(m, options?)`	Finds and measures every connected region. Options: `labelId`, `labels`, `labelNames`, `connectivity`, `minArea`, `maxArea`, `image`.
`shape.count(m, options?)`	Counts the connected regions.
`shape.countByLabel(m, options?)`	Counts regions per class as `{ labelId, label, count, area }`.
`shape.instances(m, options?)`	Like `components`, but splits touching objects. Extra options: `minDistance`, `minDepth`.
`shape.countInstances(m, options?)`	Counts objects and splits touching ones.
`shape.toOverlays(components, options?)`	Converts components into overlays for `ui.image`.
`shape.contour(m, options?)`	Traces the outline of the largest region.
`shape.contours(m, options?)`	Traces every outline.
`shape.approxPoly(points, epsilon, closed?)`	Simplifies an outline.
`shape.convexHull(points)`	Computes the convex hull.
`shape.minAreaRect(source, options?)`	Fits the smallest rotated rectangle as `{ cx, cy, width, height, angle, corners }`.
`shape.quad(m, options?)`	Fits a quadrilateral and returns its corners, starting top-left and going clockwise.

A component has these fields: id, labelId, label, area, x, y, width, height, centroidX, centroidY, perimeter, circularity, aspectRatio, fillRatio, and with the image option also meanRed, meanGreen, meanBlue, meanHue, meanSaturation, meanValue.

storage

Values are saved in .oneai-storage.json next to the script and persist between runs.

Function	Description
`storage.get(key, fallback?)`	Reads a value, or returns the fallback.
`storage.set(key, value)`	Writes a value.
`storage.increment(key, amount)`	Adds to a number and returns the new value.
`storage.clear()`	Removes all values.

time

Function	Description
`await time.sleep(ms)`	Waits for the given number of milliseconds. Also lets the dashboard update.
`time.now()`	Milliseconds since the run started.
`time.timestamp()`	Current local time as ISO 8601 string.

ui

See Building Dashboards for examples. All widgets accept the layout options title, width, columnSpan and rowSpan. Calling a widget function again with the same id updates the widget.

Structure

Function	Description
`ui.title(text)`	Sets the headline of the run view.
`ui.columns(count)`	Sets the number of dashboard columns.
`ui.screen(id, options?)`	Declares a screen. New widgets are placed on it. Options: `title`, `description`, `columns` (1–6).
`ui.showScreen(id)`	Switches to a screen.
`ui.clear()`	Removes all screens and widgets.

Display

Function	Description
`ui.image(id, img, options?)`	Shows an image, or an empty placeholder for `null`. Options: `overlays`, `focus`.
`ui.busy(id, busy)`	Shows a progress indicator over an image widget. Pass a text, `true` or `false`.
`ui.label(id, text, options?)`	Shows a line of text. Options: `color`, `fontSize`.
`ui.gauge(id, value, options?)`	Shows a value as a bar. Options: `min`, `max`, `color`.
`ui.append(id, line, options?)`	Appends a line to a paginated text widget.
`ui.table(id, rows, options?)`	Shows rows of objects as a table. Option `columns` sets the column order.

Inputs

The onChange handlers are only called for changes by the user, not when the script updates the widget.

Function	Description
`ui.button(id, text, onPress, options?)`	Shows a button. Option `enabled`.
`ui.actions(id, buttons, options?)`	Shows several buttons in one cell. Buttons: `{ text, onPress, enabled, color }`.
`ui.input(id, value, onChange, options?)`	Text input. Options: `placeholder`, `multiline`, `validate`.
`ui.number(id, value, onChange, options?)`	Numeric input. Options: `min`, `max`, `step`, `decimals`.
`ui.slider(id, value, onChange, options?)`	Slider. Options: `min` (default 0), `max` (default 1), `step`.
`ui.checkbox(id, value, onChange, options?)`	Checkbox captioned with the `title`.
`ui.date(id, value, onChange, options?)`	Date picker with ISO `yyyy-MM-dd` values. Options: `format`, `min`, `max`.
`ui.select(id, items, onChange, options?)`	Dropdown. Items are strings or `{ value, label }`. Option `selected`.
`ui.list(id, items, onChange, options?)`	Compact list with previous and next buttons. Items: `{ value, label, detail, color, muted }`.

Overlays

ui.image draws overlays in image pixel coordinates:

Kind	Fields
`rectangle`	`x`, `y`, `width`, `height`, `label`, `color`
`point`	`x`, `y`, `radius`, `label`, `color`
`text`	`x`, `y`, `label`, `fontSize`, `color`

app​

camera​

dataset​

font​

fs​

http​

image​

log​

mask​

onnx​

report​

shape​

storage​

time​

ui​

app