@luxonis/depthai-pipeline-lib 3.8.2 → 3.9.0

package/README.md

@@ -1,14 +1,90 @@
-# DepthAI Pipeline Library
+# DepthAI Pipeline Lib
 
-## Testing / Development
+React components and parsing utilities for rendering DepthAI pipeline graphs.
+
+## Purpose
+
+`@luxonis/depthai-pipeline-lib` converts DepthAI pipeline payloads into renderable graph data and provides a React Flow based canvas for displaying pipeline structure and runtime state.
+
+Use this package when an application needs to:
+
+- Parse raw pipeline graph payloads from a DepthAI backend.
+- Parse live node and handle runtime state.
+- Render an interactive pipeline canvas.
+- Display device/host nodes, grouped nodes, bridge edges, connected handles, and runtime timing/state overlays.
+
+## Installation
+
+```bash
+npm install @luxonis/depthai-pipeline-lib
+```
+
+The package expects the host application to provide compatible React and React DOM versions.
+
+## Imports
+
+```ts
+import {
+	PipelineCanvas,
+	parsePipeline,
+	parsePipelineState,
+} from '@luxonis/depthai-pipeline-lib';
+import '@luxonis/depthai-pipeline-lib/styles';
+```
+
+## Basic Usage
+
+```tsx
+import {
+	PipelineCanvas,
+	parsePipeline,
+	parsePipelineState,
+} from '@luxonis/depthai-pipeline-lib';
+import '@luxonis/depthai-pipeline-lib/styles';
+
+export function PipelineView({ rawPipeline, rawPipelineState }) {
+	const pipeline = rawPipeline ? parsePipeline(rawPipeline) : null;
+	const pipelineState = rawPipelineState
+		? parsePipelineState(rawPipelineState)
+		: null;
+
+	return (
+		<PipelineCanvas
+			pipeline={pipeline}
+			pipelineState={pipelineState}
+		/>
+	);
+}
+```
+
+## API Documentation
+
+TSDoc comments in `src/` are the source of truth for generated API reference documentation.
+
+Generate the TypeDoc JSON API model from the repository root:
+
+```bash
+npm run docs:api-json:pipelines
+```
+
+The generated JSON is written to:
+
+```text
+dist/docs-api/depthai-pipeline-lib.json
+```
+
+This file is an intermediate build artifact for the `docs-content` pipeline. Do not edit it manually.
+
+## Development
+
+From the repository root:
 
 ```bash
-$ npm run dev
+npm run build:depthai-pipeline-lib
 ```
 
-## Building / Publishing
+On Windows:
 
 ```bash
-$ npm run build
-$ npm publish
+npm run build:depthai-pipeline-lib:win
 ```

package/dist/src/components/PipelineCanvas.d.ts

@@ -1,10 +1,41 @@
 import React from 'react';
 import type { Pipeline } from '../services/pipeline.js';
 import type { PipelineState } from '../services/pipeline-state.js';
+/**
+ * Props for {@link PipelineCanvas}.
+ */
 export type PipelineCanvasProps = {
+    /**
+     * Parsed pipeline graph to render, or `null` while pipeline data is loading.
+     */
     pipeline: Pipeline | null;
+    /**
+     * Runtime state for nodes and IO handles, or `null` when live state is unavailable.
+     */
     pipelineState: PipelineState[] | null;
+    /**
+     * Optional content rendered in the top-center panel above the graph.
+     */
     header?: React.ReactNode;
+    /**
+     * Shows debugging-oriented legend entries when enabled.
+     *
+     * @defaultValue `false`
+     */
     isDebugging?: boolean;
 };
+/**
+ * Renders an interactive DepthAI pipeline graph.
+ *
+ * @remarks
+ * The component expects graph data produced by {@link parsePipeline} and can overlay
+ * runtime node/handle state produced by {@link parsePipelineState}. It wraps the graph
+ * in a React Flow provider, lays nodes out automatically until the user drags a node,
+ * and exposes a built-in legend panel.
+ *
+ * @example
+ * ```tsx
+ * <PipelineCanvas pipeline={pipeline} pipelineState={pipelineState} />
+ * ```
+ */
 export declare const PipelineCanvas: React.FC<PipelineCanvasProps>;

package/dist/src/components/PipelineCanvas.js

@@ -70,4 +70,18 @@ const PipelineCanvasBody = ({ pipeline, pipelineState: pipelineStateParsed, head
     }, [shouldFitAndResize]);
     return (_jsxs(Flex, { align: "center", justify: "center", full: true, className: "border border-border rounded-sm", children: [!pipeline && _jsx(Header, { text: "Loading pipeline..." }), pipeline && (_jsxs(ReactFlow, { nodes: nodes, edges: edges, onNodeDragStart: () => (autoArrangeRef.current = false), onNodesChange: onNodesChange, fitView: true, nodeTypes: nodeTypes, edgeTypes: edgeTypes, minZoom: 0.4, colorMode: colorMode, children: [header && _jsx(Panel, { position: "top-center", children: header }), _jsx(Panel, { position: "top-right", children: _jsxs(Flex, { gap: "xs", direction: "column", children: [_jsx(Button, { onClick: () => setOpenLegend(!openLegend), label: openLegend ? 'Collapse' : 'Legend' }), openLegend && _jsx(PipelineLegend, { isDebugging: isDebugging })] }) })] }))] }));
 };
+/**
+ * Renders an interactive DepthAI pipeline graph.
+ *
+ * @remarks
+ * The component expects graph data produced by {@link parsePipeline} and can overlay
+ * runtime node/handle state produced by {@link parsePipelineState}. It wraps the graph
+ * in a React Flow provider, lays nodes out automatically until the user drags a node,
+ * and exposes a built-in legend panel.
+ *
+ * @example
+ * ```tsx
+ * <PipelineCanvas pipeline={pipeline} pipelineState={pipelineState} />
+ * ```
+ */
 export const PipelineCanvas = (props) => (_jsx(ReactFlowProvider, { children: _jsx(PipelineCanvasBody, { ...props }) }));

package/dist/src/index.d.ts

@@ -1,7 +1,13 @@
+/**
+ * React components and parsing utilities for rendering DepthAI pipeline graphs.
+ *
+ * @packageDocumentation
+ */
 export type { PipelineCanvasProps } from './components/PipelineCanvas.js';
 export { PipelineCanvas } from './components/PipelineCanvas.js';
-export type { Pipeline, RawPipelinePayload } from './services/pipeline.js';
+export type { ParsedNode, Pipeline, RawPipeline, RawPipelineEdge, RawPipelineNode, RawPipelineNodeIO, RawPipelinePayload, } from './services/pipeline.js';
 export { parsePipeline } from './services/pipeline.js';
-export type { PipelineState, RawPipelineStatePayload, } from './services/pipeline-state.js';
+export type { ParsedHandle } from './services/pipeline-handles.js';
+export type { GPSTTimingsType, IONodeState, IOStates, NodeExtras, NodeState, NodeStateRaw, PipelineState, PipelineStateDotColor, RawPipelineState, RawPipelineStatePayload, Timing, TimingWithFps, } from './services/pipeline-state.js';
 export { parsePipelineState } from './services/pipeline-state.js';
 export { PACKAGE_VERSION } from './version.js';

package/dist/src/index.js

@@ -1,3 +1,8 @@
+/**
+ * React components and parsing utilities for rendering DepthAI pipeline graphs.
+ *
+ * @packageDocumentation
+ */
 export { PipelineCanvas } from './components/PipelineCanvas.js';
 export { parsePipeline } from './services/pipeline.js';
 export { parsePipelineState } from './services/pipeline-state.js';

package/dist/src/services/pipeline-handles.d.ts

@@ -1,16 +1,49 @@
 import type { Edge } from '@xyflow/react';
 import type { ParsedNode, RawPipelineNodeIO } from './pipeline';
 import type { PipelineStateDotColor } from './pipeline-state';
+/**
+ * Raw bridge connection between two node ids.
+ */
 export type RawPipelineBridge = [number, number];
+/**
+ * Parsed input or output handle rendered on a pipeline node.
+ */
 export type ParsedHandle = {
+    /**
+     * Numeric handle id from the raw pipeline payload.
+     */
     id: number;
+    /**
+     * Handle name used as the React Flow handle id.
+     */
     name: string;
+    /**
+     * Direction of the handle on the node.
+     */
     type: 'input' | 'output';
+    /**
+     * Indicates whether this handle blocks when its queue is full or empty.
+     */
     blocking: boolean;
+    /**
+     * Current queue size configured for the handle.
+     */
     queueSize: number;
+    /**
+     * Whether the handle participates in at least one rendered edge.
+     */
     connected: boolean;
+    /**
+     * Maximum observed queue size from runtime state, when available.
+     */
     maxQueueSize?: number;
+    /**
+     * Frames-per-second value from runtime state, when available.
+     */
     fps?: number;
+    /**
+     * Runtime status color rendered next to the handle.
+     */
     dotColor?: PipelineStateDotColor;
 };
 export declare function parseHandles(handles: RawPipelineNodeIO[]): {
@@ -22,24 +55,72 @@ export declare function filterNodesHandles(nodes: ParsedNode[], edges: Edge[]):
         handles: {
             input: {
                 connected: boolean;
+                /**
+                 * Numeric handle id from the raw pipeline payload.
+                 */
                 id: number;
+                /**
+                 * Handle name used as the React Flow handle id.
+                 */
                 name: string;
+                /**
+                 * Direction of the handle on the node.
+                 */
                 type: "input" | "output";
+                /**
+                 * Indicates whether this handle blocks when its queue is full or empty.
+                 */
                 blocking: boolean;
+                /**
+                 * Current queue size configured for the handle.
+                 */
                 queueSize: number;
+                /**
+                 * Maximum observed queue size from runtime state, when available.
+                 */
                 maxQueueSize?: number;
+                /**
+                 * Frames-per-second value from runtime state, when available.
+                 */
                 fps?: number;
+                /**
+                 * Runtime status color rendered next to the handle.
+                 */
                 dotColor?: PipelineStateDotColor;
             }[];
             output: {
                 connected: boolean;
+                /**
+                 * Numeric handle id from the raw pipeline payload.
+                 */
                 id: number;
+                /**
+                 * Handle name used as the React Flow handle id.
+                 */
                 name: string;
+                /**
+                 * Direction of the handle on the node.
+                 */
                 type: "input" | "output";
+                /**
+                 * Indicates whether this handle blocks when its queue is full or empty.
+                 */
                 blocking: boolean;
+                /**
+                 * Current queue size configured for the handle.
+                 */
                 queueSize: number;
+                /**
+                 * Maximum observed queue size from runtime state, when available.
+                 */
                 maxQueueSize?: number;
+                /**
+                 * Frames-per-second value from runtime state, when available.
+                 */
                 fps?: number;
+                /**
+                 * Runtime status color rendered next to the handle.
+                 */
                 dotColor?: PipelineStateDotColor;
             }[];
         };

package/dist/src/services/pipeline-state.d.ts

@@ -1,65 +1,233 @@
+/**
+ * Top-level raw runtime-state payload accepted by {@link parsePipelineState}.
+ */
 export type RawPipelineStatePayload = {
+    /**
+     * Raw state tuples keyed by node id.
+     */
     nodeStates: RawPipelineState[];
 };
-type IONodeState = 0 | 1 | 2;
+/**
+ * Raw IO state value reported for a node input or output.
+ *
+ * @remarks
+ * `0` maps to green, `1` maps to yellow, `2` maps to red, and any missing or
+ * unknown value maps to gray.
+ */
+export type IONodeState = 0 | 1 | 2;
+/**
+ * Runtime state indexed by input or output handle name.
+ */
 export type IOStates = {
     [key: string]: {
+        /**
+         * Number of queued messages for this handle.
+         */
         numQueued: number;
+        /**
+         * Timing and FPS statistics reported for this handle.
+         */
         timing: TimingWithFps;
+        /**
+         * Raw IO state value from the runtime.
+         */
         state?: IONodeState;
+        /**
+         * UI color derived from the raw state value by {@link parsePipelineState}.
+         */
         dotColor?: PipelineStateDotColor;
     };
 };
-type Timing = {
+/**
+ * Duration statistics reported in microseconds.
+ */
+export type Timing = {
+    /**
+     * Recent average duration in microseconds.
+     */
     averageMicrosRecent: number;
+    /**
+     * Maximum duration across the observed window in microseconds.
+     */
     maxMicros: number;
+    /**
+     * Recent maximum duration in microseconds.
+     */
     maxMicrosRecent: number;
+    /**
+     * Recent median duration in microseconds.
+     */
     medianMicrosRecent: number;
+    /**
+     * Minimum duration across the observed window in microseconds.
+     */
     minMicros: number;
+    /**
+     * Recent minimum duration in microseconds.
+     */
     minMicrosRecent: number;
+    /**
+     * Recent duration standard deviation in microseconds.
+     */
     stdDevMicrosRecent: number;
 };
-type TimingWithFps = {
+/**
+ * Timing statistics with the observed frames-per-second value.
+ */
+export type TimingWithFps = {
+    /**
+     * Duration statistics for this timing bucket.
+     */
     durationStats: Timing;
+    /**
+     * Frames-per-second rate reported for this timing bucket.
+     */
     fps: number;
 };
-type NodeStateRaw = 0 | 1 | 2 | 3;
-type NodeState = 'IDLE' | 'GETTING_INPUTS' | 'PROCESSING' | 'SENDING_OUTPUTS';
+/**
+ * Raw node state value reported by the runtime.
+ *
+ * @remarks
+ * `0` is idle, `1` is getting inputs, `2` is processing, and `3` is sending outputs.
+ */
+export type NodeStateRaw = 0 | 1 | 2 | 3;
+/**
+ * Normalized node state label used by parsed pipeline state.
+ */
+export type NodeState = 'IDLE' | 'GETTING_INPUTS' | 'PROCESSING' | 'SENDING_OUTPUTS';
+/**
+ * Raw runtime-state tuple for one pipeline node.
+ */
 export type RawPipelineState = [
+    /**
+     * Numeric node id.
+     */
     number,
+    /**
+     * Runtime state payload for the node.
+     */
     {
+        /**
+         * Raw event list reserved for runtime diagnostics.
+         */
         events: unknown[];
+        /**
+         * Raw input handle states.
+         */
         inputStates: IOStates;
+        /**
+         * Timing for collecting node inputs.
+         */
         inputsGetTiming: TimingWithFps;
+        /**
+         * Timing for the node main loop.
+         */
         mainLoopTiming: TimingWithFps;
+        /**
+         * Additional runtime timing buckets not currently rendered by the canvas.
+         */
         otherTimings: object;
+        /**
+         * Raw output handle states.
+         */
         outputStates: IOStates;
+        /**
+         * Timing for sending node outputs.
+         */
         outputsSendTiming: TimingWithFps;
+        /**
+         * Raw node execution state.
+         */
         state?: NodeStateRaw;
     }
 ];
+/**
+ * Dot color used by the canvas legend and node handles.
+ */
 export type PipelineStateDotColor = 'gray' | 'green' | 'yellow' | 'red';
+/**
+ * Average node timing breakdown in microseconds.
+ *
+ * @remarks
+ * `G` is time spent getting inputs, `P` is processing time, `S` is time spent
+ * sending outputs, and `T` is the total main-loop time.
+ */
 export type GPSTTimingsType = {
+    /**
+     * Average time spent getting inputs.
+     */
     G: number;
+    /**
+     * Average processing time.
+     */
     P: number;
+    /**
+     * Average time spent sending outputs.
+     */
     S: number;
+    /**
+     * Average total main-loop time.
+     */
     T: number;
 };
+/**
+ * Additional runtime metadata attached to a parsed pipeline node.
+ */
 export type NodeExtras = {
+    /**
+     * Parsed timing breakdown for the node.
+     */
     gpstTimings?: GPSTTimingsType;
+    /**
+     * Parsed node execution state and display labels.
+     */
     stateInfo?: {
+        /**
+         * Normalized execution state.
+         */
         state: NodeState;
+        /**
+         * Human-readable state label.
+         */
         label: string;
+        /**
+         * Short state letter rendered in compact UI.
+         */
         letter: string;
     };
 };
+/**
+ * Parsed runtime state for one pipeline node.
+ */
 export type PipelineState = {
+    /**
+     * Numeric node id matching the raw pipeline node id.
+     */
     id: number;
+    /**
+     * Parsed input handle states.
+     */
     inputs: IOStates;
+    /**
+     * Parsed output handle states.
+     */
     outputs: IOStates;
 } & NodeExtras;
+/**
+ * Converts raw runtime-state payloads into canvas-friendly node state.
+ *
+ * @param rawPayload - Runtime-state payload returned by the backend pipeline service.
+ * @returns Parsed node states with handle colors, timing breakdowns, and state labels.
+ *
+ * @remarks
+ * Timing values are kept in microseconds so the renderer can decide how to format them.
+ *
+ * @example
+ * ```ts
+ * const pipelineState = parsePipelineState(rawPipelineStatePayload);
+ * ```
+ */
 export declare function parsePipelineState(rawPayload: RawPipelineStatePayload): PipelineState[];
 export declare function stateToLabel(state: NodeState): string;
 export declare function stateToLetter(state: NodeState): string;
 export declare function formatTiming(time: number): string;
-export {};

package/dist/src/services/pipeline-state.js

@@ -36,6 +36,20 @@ function formatIOStates(values) {
     }
     return returnObj;
 }
+/**
+ * Converts raw runtime-state payloads into canvas-friendly node state.
+ *
+ * @param rawPayload - Runtime-state payload returned by the backend pipeline service.
+ * @returns Parsed node states with handle colors, timing breakdowns, and state labels.
+ *
+ * @remarks
+ * Timing values are kept in microseconds so the renderer can decide how to format them.
+ *
+ * @example
+ * ```ts
+ * const pipelineState = parsePipelineState(rawPipelineStatePayload);
+ * ```
+ */
 export function parsePipelineState(rawPayload) {
     const { nodeStates } = rawPayload;
     const parsedNodeStates = [];

package/dist/src/services/pipeline.d.ts

@@ -1,53 +1,178 @@
 import type { Edge, Node } from '@xyflow/react';
 import { type ParsedHandle } from './pipeline-handles';
 import type { NodeExtras } from './pipeline-state';
+/**
+ * Raw IO metadata for one pipeline node input or output.
+ *
+ * @remarks
+ * This tuple mirrors the compact payload emitted by the backend before it is converted
+ * into React Flow handles.
+ */
 export type RawPipelineNodeIO = [
+    /**
+     * Raw socket identity tuple emitted by the backend.
+     */
     [
         string,
         string
     ],
+    /**
+     * Queue and direction metadata for the socket.
+     */
     {
+        /**
+         * Numeric IO id.
+         */
         id: number;
+        /**
+         * IO name used to connect edges to handles.
+         */
         name: string;
+        /**
+         * Raw IO direction where `3` represents an input and `0` represents an output.
+         */
         type: 0 | 3;
+        /**
+         * Indicates whether the IO queue blocks.
+         */
         blocking: boolean;
+        /**
+         * Configured queue size for this IO.
+         */
         queueSize: number;
     }
 ];
+/**
+ * Raw node metadata as received from the pipeline service.
+ */
 export type RawPipelineNode = {
+    /**
+     * Numeric node id from the backend payload.
+     */
     id: number;
+    /**
+     * Raw input and output metadata for this node.
+     */
     ioInfo: RawPipelineNodeIO[];
+    /**
+     * Display name for the node.
+     */
     name: string;
+    /**
+     * Parent node id, if the backend groups this node under another node.
+     */
     parentId?: number;
+    /**
+     * Indicates whether the node runs on the device or host when that information is known.
+     */
     deviceNode?: boolean;
 };
+/**
+ * Raw connection between two pipeline node handles.
+ */
 export type RawPipelineEdge = {
+    /**
+     * Source node id.
+     */
     node1Id: number;
+    /**
+     * Source output handle name.
+     */
     node1Output: string;
+    /**
+     * Target node id.
+     */
     node2Id: number;
+    /**
+     * Target input handle name.
+     */
     node2Input: string;
 };
+/**
+ * Top-level raw payload accepted by {@link parsePipeline}.
+ */
 export type RawPipelinePayload = {
+    /**
+     * Raw pipeline graph payload.
+     */
     pipeline: RawPipeline;
 };
+/**
+ * Raw pipeline graph before it is normalized for rendering.
+ */
 export type RawPipeline = {
+    /**
+     * Raw node-to-node connections.
+     */
     connections: RawPipelineEdge[];
+    /**
+     * Raw nodes keyed by numeric node id.
+     */
     nodes: [number, RawPipelineNode][];
+    /**
+     * Optional bridge edges rendered as animated connections between node groups.
+     */
     bridges?: [number, number][];
 };
+/**
+ * Parsed pipeline graph ready for {@link PipelineCanvas}.
+ */
 export type Pipeline = {
+    /**
+     * React Flow nodes rendered by {@link PipelineCanvas}.
+     */
     nodes: ParsedNode[];
+    /**
+     * React Flow edges rendered by {@link PipelineCanvas}.
+     */
     edges: Edge[];
 };
+/**
+ * React Flow node used by the pipeline canvas.
+ */
 export type ParsedNode = Node<{
+    /**
+     * String node id used by React Flow.
+     */
     id: string;
+    /**
+     * Parent group node id, if this node is rendered inside a group.
+     */
     parentId?: string;
+    /**
+     * Display name rendered in the node.
+     */
     name: string;
+    /**
+     * Parsed input and output handles.
+     */
     handles: {
         input: ParsedHandle[];
         output: ParsedHandle[];
     };
+    /**
+     * Runtime placement of the node when known.
+     */
     nodeType?: 'device' | 'host';
+    /**
+     * Parsed runtime metadata overlaid onto the graph.
+     */
     extras?: NodeExtras;
 }>;
+/**
+ * Converts a raw DepthAI pipeline payload into a renderable graph.
+ *
+ * @param rawPayload - Pipeline payload returned by the backend pipeline service.
+ * @returns A normalized graph with React Flow nodes, normal edges, and optional bridge edges.
+ *
+ * @remarks
+ * The parser filters out disconnected nodes, creates placeholder parent nodes when a
+ * grouped child references a missing parent, and marks handles as connected or
+ * disconnected based on the generated edge list.
+ *
+ * @example
+ * ```ts
+ * const pipeline = parsePipeline(rawPipelinePayload);
+ * ```
+ */
 export declare function parsePipeline(rawPayload: RawPipelinePayload): Pipeline;

package/dist/src/services/pipeline.js

@@ -20,6 +20,22 @@ function addFakeNode(id) {
         },
     ];
 }
+/**
+ * Converts a raw DepthAI pipeline payload into a renderable graph.
+ *
+ * @param rawPayload - Pipeline payload returned by the backend pipeline service.
+ * @returns A normalized graph with React Flow nodes, normal edges, and optional bridge edges.
+ *
+ * @remarks
+ * The parser filters out disconnected nodes, creates placeholder parent nodes when a
+ * grouped child references a missing parent, and marks handles as connected or
+ * disconnected based on the generated edge list.
+ *
+ * @example
+ * ```ts
+ * const pipeline = parsePipeline(rawPipelinePayload);
+ * ```
+ */
 export function parsePipeline(rawPayload) {
     const { pipeline } = rawPayload;
     // Set all nodes as generic nodes

package/dist/src/version.d.ts

@@ -1 +1,4 @@
-export declare const PACKAGE_VERSION = "3.8.2";
+/**
+ * Package version injected during the library build.
+ */
+export declare const PACKAGE_VERSION = "3.9.0";

package/dist/src/version.js

@@ -1,2 +1,5 @@
 // Do not edit it manually.
-export const PACKAGE_VERSION = '3.8.2';
+/**
+ * Package version injected during the library build.
+ */
+export const PACKAGE_VERSION = '3.9.0';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@luxonis/depthai-pipeline-lib",
-	"version": "3.8.2",
+	"version": "3.9.0",
 	"type": "module",
 	"license": "UNLICENSED",
 	"main": "./dist/src/index.js",
@@ -15,7 +15,7 @@
 	},
 	"dependencies": {
 		"@dagrejs/dagre": "^1.1.3",
-		"@luxonis/ui-components": "^1.3.7",
+		"@luxonis/ui-components": "^1.3.8",
 		"@xyflow/react": "^12.0.4",
 		"postcss-import": "^16.1.0",
 		"postcss-nested": "^6.2.0",