@react-opencv/fiber 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,7 @@
 # react-opencv-fiber
 
+[![npm version](https://img.shields.io/npm/v/@react-opencv/fiber.svg)](https://www.npmjs.com/package/@react-opencv/fiber)
+
 A React renderer for OpenCV.js. Write image-processing pipelines as JSX — each element maps to an OpenCV operation, and the tree executes bottom-up through a custom React reconciler.
 
 [**Live demo**](https://erasta.github.io/react-opencv-fiber/)
@@ -52,13 +54,19 @@ Renders a `<canvas>` and executes the CV pipeline defined by its children.
 <CvCanvas
   style={{ maxWidth: "100%" }}
   className="my-canvas"
-  onResult={(mat) => { /* final Mat before display */ }}
+  onResult={(mat) => { /* cloned Mat of the final result */ }}
 >
   {/* CV operation tree */}
 </CvCanvas>
 ```
 
-Supports `ref` forwarding to the underlying canvas element.
+| Prop | Type | Description |
+|---|---|---|
+| `style` | `CSSProperties` | CSS styles for the canvas element |
+| `className` | `string` | CSS class for the canvas element |
+| `headless` | `boolean` | When `true`, runs the pipeline without rendering a canvas (returns `null`). Useful for producing intermediate results via `onResult`. |
+| `onResult` | `(mat: Mat) => void` | Called with a **cloned** Mat after each pipeline run. The clone stays valid across re-runs — you own it. |
+| `ref` | `Ref<HTMLCanvasElement>` | Forwarded to the underlying canvas element |
 
 ### CV operation elements
 
@@ -89,22 +97,92 @@ Operations are nested inside-out — the innermost element runs first:
 
 Props map directly to OpenCV function parameters. Array values are coerced to the appropriate OpenCV types (`Size`, `Point`, `Scalar`).
 
-### `<cvImage>`
+#### `__srcParam` / `__dstParam`
 
-Special element that loads an image (URL or data URI) into a `Mat`.
+By default, each operation is called as `cv.op(src, dst, ...params)` — matching the OpenCV.js convention of `src` at position 0 and `dst` at position 1. Some functions use a different argument order. Use `__srcParam` and `__dstParam` to override the position:
+
+```tsx
+{/* applyColorMap expects cv.applyColorMap(src, colormap, dst) */}
+<cvApplyColorMap colormap={2} __dstParam={2}>
+  <cvCvtColor code={11}>
+    <cvImage src="photo.jpg" />
+  </cvCvtColor>
+</cvApplyColorMap>
+```
+
+### Special leaf elements
+
+These are leaf nodes that provide input to the pipeline (they have no children).
+
+#### `<cvImage>`
+
+Loads an image (URL or data URI) into a `Mat`.
 
 ```tsx
 <cvImage src="https://example.com/photo.jpg" />
 ```
 
-## Demo
+#### `<cvMat>`
+
+Accepts an existing `Mat` as pipeline input. The mat is **cloned internally**, so the original stays valid and is never disposed by the pipeline.
+
+```tsx
+<cvMat mat={someMatFromState} />
+```
+
+Use this to share the output of one pipeline as input to another (see [Sharing results between pipelines](#sharing-results-between-pipelines)).
+
+### Sharing results between pipelines
+
+Use `headless` mode to run a pipeline without a canvas, capture its result with `onResult`, and feed it into other pipelines via `<cvMat>`:
+
+```tsx
+const [blurredMat, setBlurredMat] = useState<Mat | null>(null);
+
+{/* Headless pipeline: blur and share result */}
+<CvCanvas headless onResult={setBlurredMat}>
+  <cvGaussianBlur ksize={[5, 5]} sigmaX={0}>
+    <cvImage src="photo.jpg" />
+  </cvGaussianBlur>
+</CvCanvas>
+
+{/* Display the blurred intermediate */}
+<CvCanvas>
+  <cvMat mat={blurredMat} />
+</CvCanvas>
+
+{/* Apply further operations on the shared result */}
+<CvCanvas>
+  <cvCanny threshold1={50} threshold2={150}>
+    <cvMat mat={blurredMat} />
+  </cvCanny>
+</CvCanvas>
+```
+
+Both `onResult` and `<cvMat>` clone the Mat, so there are no ownership conflicts — each pipeline manages its own memory.
+
+## Examples
+
+The `examples/` directory contains interactive demos with different filter combinations. [**Live demo**](https://erasta.github.io/react-opencv-fiber/)
+
+<p>
+  <img src="gifs/canny-gaussian.gif" width="400" />
+  <img src="gifs/adaptive-threshold-blur.gif" width="400" />
+</p>
+<p>
+  <img src="gifs/edge-preserving-canny.gif" width="400" />
+  <img src="gifs/laplacian-blur.gif" width="400" />
+</p>
+<p>
+  <img src="gifs/median-equalize.gif" width="400" />
+</p>
 
-The `demo/` directory contains a small app with a slider-driven pipeline (blur + grayscale + Canny edge detection). To run it:
+To run locally:
 
 ```sh
 npm install
-cd demo && npm install
-npm run dev
+npm run build
+cd examples && npm install && npx vite
 ```
 
 ## Acknowledgements

package/dist/components/OpenCvProvider.d.ts

@@ -1,8 +1,8 @@
-import type { OpenCVContextValue } from "../types";
+import type { CvDebugConfig, OpenCVContextValue } from "../types";
 export declare function useOpenCv(): OpenCVContextValue;
-export declare const OpenCvProvider: ({ openCvVersion, openCvPath, verbose, children, }: {
+export declare const OpenCvProvider: ({ openCvVersion, openCvPath, debug, children, }: {
     openCvVersion?: string;
     openCvPath?: string;
-    verbose?: boolean;
+    debug?: CvDebugConfig;
     children: any;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/fiber/CvCanvas.d.ts

@@ -4,6 +4,7 @@ export interface CvCanvasProps {
     children?: ReactNode;
     style?: CSSProperties;
     className?: string;
+    headless?: boolean;
     onResult?: (mat: Mat) => void;
 }
 export declare const CvCanvas: import("react").ForwardRefExoticComponent<CvCanvasProps & import("react").RefAttributes<HTMLCanvasElement>>;

package/dist/fiber/CvNode.d.ts

@@ -12,5 +12,6 @@ export declare class CvNode {
     insertBefore(child: CvNode, before: CvNode): void;
     propagateNotify(notify: (() => void) | null): void;
     dispose(): void;
+    cloneMat(_cv: CV): Mat | null;
     loadImage(cv: CV): Promise<Mat>;
 }

package/dist/fiber/executePipeline.d.ts

@@ -1,3 +1,3 @@
-import type { CV, Mat } from "../types";
+import type { CV, Mat, CvDebugConfig } from "../types";
 import { CvNode } from "./CvNode";
-export declare function executePipeline(cv: CV, node: CvNode): Promise<Mat | null>;
+export declare function executePipeline(cv: CV, node: CvNode, missingOps?: Set<string>, debug?: CvDebugConfig): Promise<Mat | null>;

package/dist/fiber/matDebug.d.ts

@@ -0,0 +1,2 @@
+import type { Mat } from "../types";
+export declare const descMat: (m: Mat) => string;

package/dist/fiber/types.d.ts

@@ -14,6 +14,8 @@ type CvElements = {
 } & {
     cvImage: CvOpProps;
     cv_image: CvOpProps;
+    cvMat: CvOpProps;
+    cv_mat: CvOpProps;
 };
 declare module "react" {
     namespace JSX {

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { CvCanvas } from "./fiber/CvCanvas";
 export type { CvCanvasProps } from "./fiber/CvCanvas";
 export type { CvOpProps } from "./fiber/types";
 import "./fiber/types";
-export type { CV, Mat, OpenCVContextValue, ParamConfig, SignatureParam, SignatureOverload, SignatureEntry, } from "./types";
+export type { CV, Mat, CvDebugConfig, OpenCVContextValue, ParamConfig, SignatureParam, SignatureOverload, SignatureEntry, } from "./types";