> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencv/opencv/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript Bindings (opencv.js)
> Use OpenCV directly in web browsers with opencv.js compiled via Emscripten
## Overview
OpenCV.js brings OpenCV functionality to web browsers through WebAssembly (WASM). It's compiled from C++ using Emscripten and provides a JavaScript API that closely mirrors the C++ interface.
## Installation
### Using Pre-built opencv.js
The easiest way to get started:
```html CDN theme={null}
```
```html Local File theme={null}
```
The `async` attribute allows the page to load while opencv.js downloads. Use the `onRuntimeInitialized` callback to run code after OpenCV is ready.
### Waiting for OpenCV to Load
```html theme={null}
```
Or use the runtime callback:
```html theme={null}
```
### Building from Source
For custom builds with specific modules:
```bash theme={null}
# Install Emscripten
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
# Clone OpenCV
git clone https://github.com/opencv/opencv.git
cd opencv
# Build opencv.js
emcmake python ./platforms/js/build_js.py build_js \
--build_wasm \
--cmake_option="-DCMAKE_CXX_STANDARD=17"
# Output: build_js/bin/opencv.js
```
Emscripten 4.0.20+ requires C++17 or newer. The build process typically takes 5-10 minutes.
## Quick Start
### Basic HTML Template
```html theme={null}
OpenCV.js Example
OpenCV.js Demo
```
## Core Concepts
### Mat Objects
All images in OpenCV.js are represented by `cv.Mat`:
```javascript theme={null}
// Create Mat from canvas or image element
let img = cv.imread('imageId');
// Create empty Mat
let mat = new cv.Mat(rows, cols, cv.CV_8UC3);
// Create with specific values
let zeros = cv.Mat.zeros(480, 640, cv.CV_8UC1);
let ones = cv.Mat.ones(100, 100, cv.CV_8UC3);
let eye = cv.Mat.eye(3, 3, cv.CV_64FC1);
// IMPORTANT: Always delete Mat objects when done
mat.delete();
```
**Memory Management**: JavaScript garbage collection doesn't handle WebAssembly memory. Always call `.delete()` on Mat objects to prevent memory leaks.
### Reading Images
```javascript theme={null}
// From img element
let img = document.getElementById('myImage');
let mat = cv.imread(img);
// From canvas
let canvas = document.getElementById('myCanvas');
let mat = cv.imread(canvas);
// From video element (current frame)
let video = document.getElementById('myVideo');
let mat = cv.imread(video);
```
### Displaying Images
```javascript theme={null}
// Display Mat on canvas
cv.imshow('canvasOutputId', mat);
// Or get canvas element first
let canvas = document.getElementById('canvasOutput');
cv.imshow(canvas, mat);
```
## Code Examples
### Image Processing Pipeline
```html theme={null}
```
### Face Detection in Browser
```html theme={null}
Face Detection Demo
```
### Real-time Webcam Processing
```javascript theme={null}
let video = document.getElementById('videoInput');
let src = new cv.Mat(video.height, video.width, cv.CV_8UC4);
let dst = new cv.Mat(video.height, video.width, cv.CV_8UC1);
let cap = new cv.VideoCapture(video);
const FPS = 30;
function processVideo() {
let begin = Date.now();
// Capture frame
cap.read(src);
// Convert to grayscale
cv.cvtColor(src, dst, cv.COLOR_RGBA2GRAY);
// Display
cv.imshow('canvasOutput', dst);
// Schedule next frame
let delay = 1000/FPS - (Date.now() - begin);
setTimeout(processVideo, delay);
}
// Start camera
navigator.mediaDevices.getUserMedia({video: true, audio: false})
.then(stream => {
video.srcObject = stream;
video.onloadedmetadata = () => {
video.play();
processVideo();
};
})
.catch(err => {
console.error('Camera error:', err);
});
```
### Working with Data
```javascript theme={null}
// Access pixel values
let mat = cv.imread('imageId');
let row = 10, col = 20;
let pixel = mat.ucharPtr(row, col);
// pixel is Uint8Array with [R, G, B, A] values
// Modify pixels
pixel[0] = 255; // Red
pixel[1] = 0; // Green
pixel[2] = 0; // Blue
pixel[3] = 255; // Alpha
// Get Mat data as typed array
let data = mat.data; // Uint8Array
// Create Mat from array
let dataArray = new Uint8Array([255, 0, 0, 255, 0, 255, 0, 255]);
let mat2 = new cv.Mat(2, 1, cv.CV_8UC4);
mat2.data.set(dataArray);
```
### Image Transformations
```javascript theme={null}
function transformImage() {
let src = cv.imread('inputImage');
let dst = new cv.Mat();
// Resize
let dsize = new cv.Size(320, 240);
cv.resize(src, dst, dsize, 0, 0, cv.INTER_LINEAR);
// Rotate
let center = new cv.Point(src.cols/2, src.rows/2);
let M = cv.getRotationMatrix2D(center, 45, 1.0);
cv.warpAffine(src, dst, M, new cv.Size(src.cols, src.rows));
// Flip
cv.flip(src, dst, 1); // 1 = horizontal, 0 = vertical, -1 = both
// Crop (using ROI)
let rect = new cv.Rect(10, 10, 100, 100);
let cropped = src.roi(rect);
cv.imshow('canvasOutput', dst);
// Clean up
src.delete();
dst.delete();
M.delete();
cropped.delete();
}
```
## Advanced Features
### Using DNN Module
```javascript theme={null}
// Load ONNX model
let net = cv.readNet('model.onnx');
// Prepare input
let img = cv.imread('imageId');
let blob = cv.blobFromImage(
img,
1.0, // scale factor
new cv.Size(224, 224), // size
new cv.Scalar(0, 0, 0, 0), // mean
true, // swapRB
false // crop
);
// Set input and run inference
net.setInput(blob);
let output = net.forward();
console.log('Output shape:', output.size());
// Clean up
img.delete();
blob.delete();
output.delete();
net.delete();
```
### Performance Optimization
```javascript theme={null}
// Good: Clean up immediately
function process() {
let mat = cv.imread('img');
let result = new cv.Mat();
try {
cv.cvtColor(mat, result, cv.COLOR_RGBA2GRAY);
cv.imshow('output', result);
} finally {
mat.delete();
result.delete();
}
}
// Bad: Memory leak
function processLeaky() {
let mat = cv.imread('img');
let result = new cv.Mat();
cv.cvtColor(mat, result, cv.COLOR_RGBA2GRAY);
// Forgot to delete!
}
```
```javascript theme={null}
// Good: Reuse Mat objects
let src = new cv.Mat();
let dst = new cv.Mat();
function processFrame() {
cap.read(src);
cv.cvtColor(src, dst, cv.COLOR_RGBA2GRAY);
cv.imshow('output', dst);
}
// Call many times without recreating
setInterval(processFrame, 33);
// Clean up when done
// src.delete();
// dst.delete();
```
**Performance Tip**: Reuse Mat objects in loops instead of creating new ones. Only delete when completely done.
## Common Issues
### Memory Usage
```javascript theme={null}
// Check memory usage (Emscripten specific)
console.log('Memory:', cv.getBuildInformation());
// Force garbage collection (if available)
if (typeof gc === 'function') {
gc();
}
```
### Loading Files
OpenCV.js uses Emscripten's virtual filesystem:
```javascript theme={null}
// Create file in virtual FS
let utils = new Utils('');
utils.createFileFromUrl('model.xml', 'path/to/model.xml', () => {
// File loaded, can use it now
let cascade = new cv.CascadeClassifier();
cascade.load('model.xml');
});
```
## Build Configuration
Customize which modules to include:
```bash theme={null}
python ./platforms/js/build_js.py build_js \
--build_wasm \
--disable_single_file \
--cmake_option="-DBUILD_LIST=core,imgproc,objdetect,dnn"
```
Common build flags:
* `--build_wasm`: Build WebAssembly version
* `--disable_single_file`: Separate .wasm file
* `--enable_exception`: Enable C++ exceptions
* `--build_test`: Include test utilities
## Resources
* [OpenCV.js Tutorials](https://docs.opencv.org/4.x/d5/d10/tutorial_js_root.html)
* [OpenCV.js API Reference](https://docs.opencv.org/4.x/d5/d10/tutorial_js_root.html)
* [Building opencv.js](https://docs.opencv.org/4.x/d4/da1/tutorial_js_setup.html)
* [Sample Code](https://github.com/opencv/opencv/tree/4.x/samples/dnn)
* [Emscripten Documentation](https://emscripten.org/docs/)
## Next Steps
* Learn about [DNN Module](/modules/dnn) for deep learning
* Explore [Image Processing](/modules/imgproc) functions
* Try [Video Analysis](/modules/video) in the browser