docs/API.md

ONNX Model Explorer — API Reference

All modules are loaded as plain <script> tags and exposed on window. No import/export syntax is used at runtime.

---

ModelLoader

File: js/core/modelLoader.js
Global: window.ModelLoader

Loads the model registry from models/models.json and fetches individual .onnx files. Also handles file uploads from the user.

Constructor

const loader = new ModelLoader();

Methods

loadModelList(configPath?)

Fetches and parses models/models.json. Results are cached in memory after the first call.

Parameter	Type	Default	Description
configPath	string	CONFIG.MODELS_CONFIG_FILE	Path to the JSON registry file

Returns: Promise<ModelInfo[]>

const models = await loader.loadModelList();
// [{ id, name, description, path, category, version, size, labelsFile }, ...]

On error (network failure, invalid JSON), logs to console and returns [].

---

loadModelFile(filePath)

Fetches a .onnx file and returns its raw bytes.

Parameter	Type	Description
filePath	string	Relative or absolute URL to the .onnx file

Returns: Promise<ArrayBuffer>
Throws: Error if the HTTP request fails.

const buffer = await loader.loadModelFile('models/ppe/model.onnx');

---

handleFileUpload(file)

Validates and reads a File object (from <input type="file"> or drag-and-drop).

Parameter	Type	Description
file	File	Browser File object

Returns: Promise<{ success: boolean, data?: ArrayBuffer, error?: string }>

const result = await loader.handleFileUpload(file);
if (result.success) {
  // result.data is an ArrayBuffer
} else {
  console.error(result.error);
}

Validation rules (from CONFIG.FILE):

• Extension must be .onnx
• File size must not exceed CONFIG.FILE.MAX_FILE_SIZE

---

Types

interface ModelInfo {
  id: string;
  name: string;
  description: string;
  path: string;
  category: string;
  version: string;
  size: number;
  labelsFile: string | null;
}

---

ONNXParser

File: js/core/onnxParser.js
Global: window.ONNXParser

Parses an ONNX model ArrayBuffer using the ONNX.js library (must be loaded from CDN before use).

Constructor

const parser = new ONNXParser();

Methods

parseModel(modelBuffer, options?)

Decodes the protobuf and extracts all model information.

Parameter	Type	Description
modelBuffer	ArrayBuffer	Raw bytes of the .onnx file
options	object	Optional overrides (e.g. { fileName, fileSize })

Returns: Promise<ParsedModel>
Throws: Error if ONNX.js is not loaded, the buffer is empty, or parsing fails.

const parsed = await parser.parseModel(buffer, { fileName: 'model.onnx' });

---

Types

interface ParsedModel {
  metadata: ModelMetadata;
  graph: GraphStructure;
  inputs: TensorInfo[];
  outputs: TensorInfo[];
  initializers: InitializerInfo[];
}

interface ModelMetadata {
  producerName: string;
  producerVersion: string;
  opsetVersion: number;
  irVersion: number;
  customAttributes: Record<string, any>;
  fileName: string;
  fileSize: number;
  loadedAt: number;        // Unix timestamp (ms)
}

interface GraphStructure {
  name: string;
  nodes: NodeInfo[];
  edges: EdgeInfo[];
  initializers: InitializerInfo[];
}

interface NodeInfo {
  id: string;
  name: string;
  opType: string;
  attributes: Record<string, any>;
  inputs: string[];
  outputs: string[];
  domain: string;
}

interface EdgeInfo {
  source: string;   // node id
  target: string;   // node id
  label: string;    // tensor name
}

interface TensorInfo {
  name: string;
  shape: (number | string)[];
  dataType: string;
  description?: string;
  isOptional?: boolean;
}

interface InitializerInfo {
  name: string;
  shape: number[];
  dataType: string;
  size: number;         // bytes
  elementCount: number;
}

---

GraphProcessor

File: js/core/graphProcessor.js
Global: window.GraphProcessor

Converts a ParsedModel into Cytoscape.js element descriptors. Automatically clusters nodes by opType when the graph exceeds CONFIG.PERFORMANCE.LAZY_LOAD_THRESHOLD nodes.

Constructor

const processor = new GraphProcessor();

Methods

processGraph(parsedModel)

Builds the full list of Cytoscape elements (nodes + edges) from a parsed model.

Parameter	Type	Description
parsedModel	ParsedModel	Output of ONNXParser.parseModel()

Returns: { elements: CytoscapeElement[], stats: GraphStats }

const { elements, stats } = processor.processGraph(parsedModel);
// Pass elements directly to cytoscape({ elements })

Node classes assigned:

• input-node — model input tensors
• output-node — model output tensors
• initializer-node — constant weight tensors
• op-node — computation operators
• op-node cluster-node — clustered operators (large graphs)

---

Types

interface GraphStats {
  nodeCount: number;
  edgeCount: number;
  initializerCount: number;
  inputCount: number;
  outputCount: number;
  clusterCount?: number;   // present when isClustered is true
  isClustered?: boolean;
}

---

StateManager

File: js/state/stateManager.js
Global: window.StateManager

Singleton that holds all application state. Components read state via getters and react to changes via subscriptions.

State Shape

interface AppState {
  currentModel: ParsedModel | null;
  modelList: ModelInfo[];
  selectedNodeId: string | null;
  zoomLevel: number;
  viewMode: 'single' | 'comparison';
  comparisonModel: ParsedModel | null;
  searchQuery: string;
  filteredModelList: ModelInfo[];
  error: { message: string; type: 'error' | 'warning' | 'info'; timestamp: number } | null;
  isLoading: boolean;
  loadingProgress: number;   // 0–100
}

Getters

Method	Returns	Description
getState()	AppState	Shallow copy of the full state
getCurrentModel()	ParsedModel|null	Currently loaded model
getModelList()	ModelInfo[]	Full model registry
getFilteredModelList()	ModelInfo[]	Search-filtered model list
getSearchQuery()	string	Current search string
getSelectedNodeId()	string|null	Selected graph node id
getZoomLevel()	number	Current zoom level
getViewMode()	'single'|'comparison'	Current view mode
getComparisonModel()	ParsedModel|null	Second model in comparison mode
getError()	ErrorState|null	Current error, or null
isLoading()	boolean	Whether a load is in progress
getLoadingProgress()	number	Load progress 0–100

Setters

Each setter updates the corresponding state key and notifies subscribers.

Method	Parameter	Description
setCurrentModel(model)	ParsedModel|null	Set current model; persists id to localStorage
setModelList(list)	ModelInfo[]	Replace the full model list
setFilteredModelList(list)	ModelInfo[]	Replace the filtered list
setSearchQuery(query)	string	Update search query
setSelectedNodeId(id)	string|null	Update selected node
setZoomLevel(level)	number	Update zoom level
setViewMode(mode)	'single'|'comparison'	Switch view mode
setComparisonModel(model)	ParsedModel|null	Set comparison model
setError(message, type?)	string, string	Set error state (type defaults to 'error')
clearError()	—	Clear current error
setLoading(loading)	boolean	Toggle loading state
setLoadingProgress(n)	number	Update progress 0–100

Subscription

subscribe(key, callback)

Subscribe to changes on a specific state key. Use '*' to receive all changes.

Parameter	Type	Description
key	string	State key name, or '*' for all
callback	(newValue, oldValue, key) => void	Called on every change

Returns: Function — call it to unsubscribe.

const unsub = StateManager.subscribe('currentModel', (model) => {
  console.log('Model changed:', model);
});

// Later:
unsub();

unsubscribe(key, callback)

Remove a specific callback without using the returned unsubscribe function.

reset()

Resets all state to initial values. Primarily used in tests.

getPersistedSelectedModelId()

Returns the model id stored in localStorage from the previous session, or null.

---

EventBus

File: js/core/eventBus.js
Global: window.EventBus

Singleton pub/sub event bus for decoupled communication between components.

Methods

on(eventName, callback)

Subscribe to an event.

Parameter	Type	Description
eventName	string	Event name
callback	(data: any) => void	Handler

Returns: Function — unsubscribe function.

const off = EventBus.on('model:loaded', (model) => {
  console.log('Loaded:', model.metadata.fileName);
});

off(eventName, callback)

Remove a specific handler.

emit(eventName, data?)

Emit an event to all subscribers. Errors thrown inside handlers are caught and logged.

EventBus.emit('model:selected', { id: 'ppe' });

once(eventName, callback)

Subscribe for a single invocation, then auto-unsubscribe.

clear(eventName?)

Remove all listeners for eventName, or all listeners if omitted.

listenerCount(eventName)

Returns the number of active listeners for an event (useful for debugging).

Standard Events

Event	Payload	Description
model:loaded	ParsedModel	A model was successfully parsed
model:selected	ModelInfo	User selected a model from the list
node:selected	string (node id)	User clicked a graph node
search:updated	string (query)	Search field changed
error:occurred	{ message, type }	An error was raised
export:requested	ParsedModel	User clicked Export
comparison:started	ParsedModel	Comparison mode activated
comparison:ended	—	Comparison mode exited