Skip to content

Config Module API Reference

The Config module manages ONNX Runtime (ORT) configuration for Visionary. Use it to set WASM asset paths and initialize ORT before running inference.

Table of Contents

Functions

setOrtWasmPaths(paths: string | string[]): void

Store one or more candidate WASM base paths.

Parameters: - paths – Either a single string or an array of strings. Trailing slashes are optional.

Behavior: - Single path: Stored as-is (e.g., '/src/ort/') - Multiple paths: Joined with commas (e.g., ['/path1/', '/path2/'] → '/path1/,/path2/') - The module keeps the value internally until ORT is ready - When multiple paths are provided, ORT tries each location in order until files resolve

Example: 

setOrtWasmPaths('/custom/ort/path/');
// or
setOrtWasmPaths(['https://cdn.example.com/ort/', '/local/ort/']);

getOrtWasmPaths(): string

Return the currently configured WASM paths.

Returns: - Current path string (comma-separated if multiple paths) - Default: '/src/ort/' if no paths have been set

Example: 

const paths = getOrtWasmPaths();
console.log(paths); // '/src/ort/' or '/path1/,/path2/'

getDefaultOrtWasmPaths(): string

Get the default WASM path used by the module.

Returns: - Default path string: '/src/ort/'

Use Case: - Used by App module during initialization - Provides sensible default for development

Example: 

const defaultPath = getDefaultOrtWasmPaths();
initOrtEnvironment(defaultPath);

initOrtEnvironment(wasmPaths?: string | string[]): void

Initialize ONNX Runtime with the configured paths.

Parameters: - wasmPaths – Optional path(s) to use. If provided, calls setOrtWasmPaths() first. If not provided, uses previously set paths or default.

Behavior: 1. Set paths (if provided) via setOrtWasmPaths() 2. Check ORT availability: - If ORT is loaded: Apply paths immediately via ort.env.wasm.wasmPaths and log success - If ORT not loaded: Start polling mechanism (50ms intervals) to apply paths when ORT becomes available 3. Logging: Logs configuration success or warning messages

Note: This function is synchronous (does not return a Promise). Delayed configuration happens automatically via polling.

Example: 

// With default paths
initOrtEnvironment();

// With custom path
initOrtEnvironment('/custom/ort/');

// With multiple paths
initOrtEnvironment(['/path1/', '/path2/']);

isOrtConfigured(): boolean

Check if ONNX Runtime is properly configured.

Returns: - true if ORT is loaded and ort.env.wasm.wasmPaths is set to a truthy value - false if ORT is not available or any part of the chain is missing - undefined if ORT is loaded but ort.env.wasm.wasmPaths is explicitly set to undefined

Note: Due to the implementation using logical AND (&&) operators, if wasmPaths is undefined, the function may return undefined instead of false. For type safety, consider using !!isOrtConfigured() or explicit boolean conversion when checking the result.

Implementation: 

return typeof window !== 'undefined' && 
       (window as any).ort && 
       (window as any).ort.env && 
       (window as any).ort.env.wasm && 
       (window as any).ort.env.wasm.wasmPaths;

Use Case: - Verify ORT is ready before loading ONNX models - Check configuration state in error handling

Example: 

// Recommended: Use boolean conversion for type safety
if (!!isOrtConfigured()) {
  console.log('ORT is ready');
  // Safe to load ONNX models
} else {
  console.warn('ORT configuration pending...');
  initOrtEnvironment();
}

// Or explicit check
const configured = isOrtConfigured();
if (configured === true) {
  console.log('ORT is ready');
} else {
  console.warn('ORT configuration pending...');
  initOrtEnvironment();
}

Usage Patterns

Basic Usage (App Module Pattern)

import { 
  initOrtEnvironment, 
  getDefaultOrtWasmPaths 
} from 'src/config';

// During app initialization
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);
console.log(`ORT environment initialized with paths: ${wasmPaths}`);

Custom Path Configuration

import { setOrtWasmPaths, initOrtEnvironment } from 'src/config';

// Set paths explicitly
setOrtWasmPaths('/custom/ort/path/');
initOrtEnvironment();

Multiple Fallback Paths

import { setOrtWasmPaths, initOrtEnvironment } from 'src/config';

setOrtWasmPaths([
  'https://cdn.example.com/ort/',  // Try CDN first
  '/local/cache/ort/',              // Fallback to local
  '/src/ort/'                       // Final fallback
]);
initOrtEnvironment();

Configuration Verification

import { 
  initOrtEnvironment, 
  isOrtConfigured,
  getOrtWasmPaths 
} from 'src/config';

// Initialize
initOrtEnvironment();

// Check if configured
if (isOrtConfigured()) {
  console.log('ORT ready:', getOrtWasmPaths());
} else {
  console.warn('ORT still initializing...');
  // Wait a bit for delayed configuration
  setTimeout(() => {
    if (isOrtConfigured()) {
      console.log('ORT now ready');
    }
  }, 100);
}

Integration with App Module

The App module automatically calls this during initialization:

// In App.init() - before WebGPU initialization
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);
console.log(`[App] Initialized ORT environment with paths: ${wasmPaths}`);

Important: Call initOrtEnvironment before: - Loading ONNX models - Initializing WebGPU (if using ORT device sharing) - Running ONNX inference

This ensures GPU buffers stay compatible with the renderer and ORT can find its WASM files.