Skip to main content

Scripting Overview

ONE AI scripts are small JavaScript programs that run inside OneWare Studio. Use them to build your own inspection and operator workflows on top of ONE AI, without a separate application:

  • Capture training images from a camera with a simple capture dashboard.
  • Run your exported model on live camera frames or image files and decide pass/fail with your own rules.
  • Analyse a dataset, for example to count objects per class or to check annotations.
  • Measure and compare parts with image and mask processing such as thresholding, region analysis, alignment and template comparison.
  • Connect to other systems by sending results to an MES or REST endpoint, writing CSV logs or creating PDF reports.

Every script can show a fullscreen operator dashboard with live camera previews, images with overlays, buttons, inputs, tables and gauges.

Requirements

Scripting needs OneWare Studio with ONE AI extension 1.0.49 or newer.

Create your first script​

  1. Open your ONE AI project in OneWare Studio.

  2. In the Project Explorer, create a new file in the project folder whose name ends with .oneai.js, for example hello.oneai.js. The .oneai.js ending marks the file as a ONE AI script. Plain .js files are not ONE AI scripts.

  3. Paste this script:

    ui.title('Hello ONE AI');

    let presses = 0;
    ui.label('count', 'Not pressed yet');
    ui.button('press', 'Press me', () => {
        presses++;
        ui.label('count', `Pressed ${presses} times`);
        log.info(`Button pressed ${presses} times`);
    });

    // Keep the script alive until the operator closes the dashboard.
    while (app.isRunning) {
        await time.sleep(50);
    }

  4. Click Start UI in the toolbar above the editor.

The dashboard opens in fullscreen and the script starts immediately. Messages written with log appear in the Output window of OneWare Studio, prefixed with the script name.

Running scripts​

Start UI runs the script text currently in the editor, so you don't need to save before you try a change.

The dashboard has the following controls:

ControlAction
StopCancels the running script. The dashboard stays open.
Run againRestarts the script after it finished, failed or was stopped.
Exit / EscStops the script and closes the dashboard.

The status bar at the bottom shows whether the script is running, finished, stopped or failed. When a script fails, the dashboard shows the error message together with the line number, for example Line 12: image is not defined.

A script ends when its last line has run. Scripts that react to buttons or show a live camera must stay alive. Use a loop like the one above:

while (app.isRunning) {
    await time.sleep(30);
}

app.isRunning turns false when the operator presses Stop or the run times out. Always await time.sleep(...) inside loops. This lets the dashboard update and keeps the script stoppable.

Editor support​

When you open a .oneai.js file, ONE AI writes two files next to it:

  • oneai.d.ts: type definitions of the complete scripting API. They are refreshed whenever you open a script, so they always match your installed extension version.
  • jsconfig.json: tells the editor to type check your scripts against oneai.d.ts. It is only created once. You can customise it.

With these files, OneWare Studio and external editors such as VS Code show code completion, parameter documentation and type errors for every scripting function.

Script basics​

  • Scripts are modern JavaScript (ES2022) and run in strict mode.
  • Top-level await works. You can write await camera.capture() directly in the script without wrapping it in a function.
  • The scripting modules (ui, camera, image, mask, onnx and so on) are global. There is no import or require.
  • Node.js and browser APIs such as require('fs'), fetch or setTimeout are not available. Use the modules described in the API reference instead.
  • Images and masks stay in native memory. They are freed automatically at the end of a run. In long loops, call image.release(...) and mask.release(...) to keep memory flat.

File access​

Relative paths are resolved against the folder that contains the script. If your script is in the project root, Dataset/Train/... and Models/model.onnx work directly.

AccessRule
Reading files (image.load, mask.load, dataset.*, onnx.*, fs.readText, fs.list, camera.video, font.load)Allowed anywhere, including absolute paths and ..
Writing files (image.save, mask.save, fs.writeText, fs.appendText, fs.mkdir, report.savePdf, storage)Only inside the script folder and its subfolders. Symbolic links are rejected.
HTTP requestsOnly to the allowed hosts in the settings (see below)
caution

Never create or modify the .oneai project file from a script. To read a project, use the dataset module.

Settings​

You can change the limits for script runs under Settings → ONE AI → Scripting:

SettingDefaultDescription
Run Timeout (s)0Maximum duration of a run. 0 means no limit, which is what a permanently running inspection station needs.
Memory Limit (MB)1024Total memory a run may allocate over its whole lifetime. Releasing images does not lower this counter. 0 disables the limit.
Recursion Limit256Maximum function call depth.
HTTP Timeout (s)30Default timeout of a single HTTP request.
Allowed HTTP HostsemptyComma separated list of hosts that scripts may contact, for example mes.local, 192.168.1.10. Empty allows every host. Redirects are checked against this list, too.
tip

If a run fails with "The script used up its allocation budget", look for per-pixel JavaScript callbacks such as mask.map or image.pixels on full-size images inside loops. Replace them with the native mask and image operations, or raise the memory limit for long-running stations. See Performance.

Let the AI write scripts for you​

OneWare Agents know the complete scripting API. In Agent mode you can describe what you need, for example:

Write a script that captures 20 images from my USB camera into the Train split.

The agent creates the .oneai.js file in your project. It can test the script in a dashboard in testing mode, where it operates the controls itself. It then runs the script for you and waits until you finish. Before it runs or tests a script, the agent asks for your confirmation. You can stop a test at any time with Stop or Esc.

Next steps​