simple-cv
Asynchronous OpenCV bindings for Node.js with a simple promise based API
and good documentation.
simple-cv
replicates the good parts of the OpenCV API but replaces the really crappy ones with something
better. For example instead of a flip
method that takes a number literal -1, 0 or 1 to indicate flip direction
simple-cv
has flipLeftRight
and flipUpDown
methods.
All heavy operations are performed in a worker thread pool and the results a returned back asynchronously using
promises.
All methods have a synchronous equivalent. Just append Sync
to the function name.
The documentation is full of examples but here's one to get you started:
const cv = require('simple-cv');
const example = async () => {
let image = await cv.readImage('/path/to/some/image.png');
image = await cv.rotate(image, 20);
image = await cv.resize(image, {width: 400});
return image;
};
example().then(image => {
cv.showImage("example", image);
cv.waitKey();
});
This project is still in its infancy and only a small part of the OpenCV API is wrapped.
More stuff is added all the time.
Install
macOS
brew tap homebrew/science
brew install opencv3
npm install simple-cv
Ubuntu
apt-get install libopencv-dev
npm install simple-cv
Windows
figure-out yourself || install ubuntu || buy mac
API documentation
Matrix
The basic data type used to represent images, transformation matrices etc. Wraps an instance of OpenCV Mat
.
Constructors
cv.Matrix(width, height, type)
argument |
type |
description |
width |
number |
The width of the matrix. |
height |
number |
The height of the matrix. |
type |
ImageType |
The type of the matrix. Default = ImageType.Gray . |
let matrix = new cv.Matrix(10, 20, cv.ImageType.Float);
// The same using the cv.matrix shorthand:
matrix = cv.matrix(10, 20, cv.ImageType.Float);
cv.Matrix({width, height, type?, data?})
property |
type |
description |
width |
number |
The width of the matrix. |
height |
number |
The height of the matrix. |
type |
ImageType |
The type of the matrix. |
data |
Array
|
The data in a row-major order. |
let matrix = new cv.Matrix({
width: 3,
height: 2,
type: cv.ImageType.Float,
data: [
1, 2, 3,
4, 5, 6
]
});
// The same using the cv.matrix shorthand:
matrix = cv.matrix({
width: 3,
height: 2,
type: cv.ImageType.Float,
data: [
1, 2, 3,
4, 5, 6
]
});
cv.Matrix(rows)
Creates a cv.ImageType.Float
matrix.
property |
type |
description |
rows |
Array<Array
|
The values as a list of rows |
let matrix = new cv.Matrix([
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]);
// The same using the cv.matrix shorthand:
matrix = cv.matrix([
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]);
Methods
array = matrix.toArray()
Returns an array with the matrice's values in row-major order.
return value |
type |
description |
array |
Array
|
The matrix values in row-major order. |
const array = matrix.toArray();
promise = matrix.crop(rect)
Cuts a rectangular piece of the matrix and returns it as a new matrix. The original matrix is not modified.
argument |
type |
description |
rect |
Rectangle |
The rectangle to crop. |
return value |
type |
description |
promise |
Promise<Matrix > |
The cropped matrix. |
const cropped = await matrix.crop({x: 10, y: 10, width: 10, height: 10});
promise = matrix.set(source, point)
Copies the values of a matrix to another matrix.
argument |
type |
description |
source |
Matrix |
The source matrix |
point |
Point |
Where to copy the values in the target matrix |
return value |
type |
description |
promise |
Promise<Matrix > |
The target matrix. |
const source = cv.matrix([
[2, 3],
[4, 5]
]);
const target = cv.matrix([
[1, 1, 1, 1],
[1, 1, 1, 1],
[1, 1, 1, 1],
[1, 1, 1, 1]
])
await target.set(source, {x: 1, y: 2});
// target is now:
//
// [1, 1, 1, 1],
// [1, 1, 1, 1],
// [1, 2, 3, 1],
// [1, 4, 5, 1]
buffers = matrix.toBuffers()
Returns all the matrices channels as Buffers
. The returned array contains {channel: Channel, data: Buffer}
objects.
return value |
type |
description |
buffers |
Array<ChannelData > |
Each channel's data as a Buffer. |
const buffers = matrix.toBuffers();
const redData = buffers.find(it => it.channel == cv.Channel.Red).data;
Properties
The Matrix
class has the following instance properties.
property |
type |
description |
width |
number |
The width of the matrix. |
height |
number |
The height of the matrix. |
type |
ImageType |
The type of the matrix. |
Functions
matrix = cv.matrix(...args)
Shorthand for new cv.Matrix(...args)
.
promise = cv.readImage(filePath, imageType)
Read an image from a file.
argument |
type |
description |
filePath |
string |
Path to the image file to read. All image formats supported by OpenCV are supported. |
imageType |
ImageType |
Optional image type. If omitted the image is read as-is. By providing cv.ImageType.Gray the image can be read as a gray scale image. |
return value |
type |
description |
promise |
Promise<Matrix > |
The image |
const colorImage = await cv.readImage('/path/to/some/color-image.png');
const grayImage = await cv.readImage('/path/to/some/color-image.png', cv.ImageType.Gray);
promise = cv.decodeImage(buffer, imageType)
Decode an image from a buffer of data.
argument |
type |
description |
buffer |
Buffer |
Image data. All image formats supported by OpenCV are supported. |
imageType |
ImageType |
Optional image type. If omitted the decoded is read as-is. By providing cv.ImageType.Gray the image can be decoded as a gray scale image. |
return value |
type |
description |
promise |
Promise<Matrix > |
The image |
const colorImage = await cv.decodeImage(colorImageData);
const grayImage = await cv.decodeImage(colorImageData, cv.ImageType.Gray);
promise = cv.writeImage(image, filePath)
Encode and write an image to a file.
argument |
type |
description |
image |
Matrix |
The image to write to the file. |
filePath |
string |
Where to write the file. The image type is derived from the extension. |
return value |
type |
description |
promise |
Promise
|
Empty promise that is resolved after the image has been written. |
await cv.writeFile(image, filePath);
promise = cv.encodeImage(image, encodeType)
Encode an image and return the data as a buffer.
argument |
type |
description |
image |
Matrix |
The image to encode |
encodeType |
EncodeType |
The wanted image format |
return value |
type |
description |
promise |
Promise
|
The encoded image data |
const jpegData = await cv.encodeImage(matrix, cv.EncodeType.JPEG);
cv.showImage(matrix)
Shows an image (or any matrix) using OpenCV's cv::imshow
.
argument |
type |
description |
windowName |
string |
name of the window |
matrix |
Matrix |
The matrix to show |
cv.showImage('Pretty picture', image);
cv.waitKey();
cv.drawRectangle(matrix, rect, color, lineWidth)
Draws a rectagle to a matrix using cv::rectangle
.
argument |
type |
description |
matrix |
Matrix |
The canvas |
rect |
Rectangle |
The rectangle to draw |
color |
Color |
The color |
lineWidth |
number |
The line width (optional, defaults to 1) |
cv.drawRectangle(image, {x: 1, y: 10, width: 15, height: 30}, {red: 255, green: 0, blue: 0});
cv.drawLine(matrix, point1, point2, color, lineWidth)
Draws a line to a matrix using cv::line
.
argument |
type |
description |
matrix |
Matrix |
The canvas |
point1 |
Point |
Starting point of the line |
point2 |
Point |
Ending point of the line |
color |
Color |
The color |
lineWidth |
number |
The line width (optional, defaults to 1) |
cv.drawLine(image, {x: 1, y: 1}, {x: 10, y: 10}, {red: 255, green: 0, blue: 0});
keyCode = cv.waitKey(delay)
Waits for a key using OpenCV's waitKey
. Note that this function blocks and should only be used
for debugging and testing with showImage
.
argument |
type |
description |
delay |
number |
How many milliseconds to wait for the key press. |
return value |
type |
description |
keyCode |
number |
The code of the pressed key |
// Wait forever.
const key = cv.waitKey(0);
promise = cv.resize(matrix, resizeParams)
High quality image resize.
argument |
type |
description |
matrix |
Matrix |
The matrix to resize |
resizeParams |
ResizeParams or number |
The resize parameters or a number. If a number is given it will become the width of the image while keeping the aspect ratio. See ResizeParams for other options. |
return value |
type |
description |
promise |
Promise
|
The resized image |
// Resize the image to have width 400 while preserving aspect ratio.
let resized = await cv.resize(image, 400);
// This does exactly the same as the previous example.
resized = await cv.resize(image, {width: 400});
// Resize the image to have height 400 while preserving aspect ratio.
resized = await cv.resize(image, {height: 400});
// Resize the image half the width and height.
resized = await cv.resize(image, {scale: 0.5});
// Resize the image to 320x200
resized = await cv.resize(image, {width: 320, height: 200});
// Create a truly weird image.
resized = await cv.resize(image, {xScale: 0.5, yScale: 20.0});
promise = cv.warpAffine(matrix, transformation, options)
Applies an affine transformation to a matrix.
argument |
type |
description |
matrix |
Matrix |
The matrix to transform |
transformation |
Matrix |
A 3x2 affine transformation matrix |
options |
WarpParams |
Optional extra options. See WarpParams
|
return value |
type |
description |
promise |
Matrix |
The transformed image |
const transpose = cv.matrix([
[0, 1, 0],
[1, 0, 0]
]);
const transposed = await cv.warpAffine(image, transpose);
promise = cv.rotate(matrix, opt)
Rotates the image around a point.
argument |
type |
description |
matrix |
Matrix |
The matrix to rotate |
opt |
RotateParams or number |
The rotation angle as degrees or options object. See RotateParams
|
return value |
type |
description |
promise |
Matrix |
The rotated matrix |
// Rotate 20 degrees around the center of the image.
let rotated = await cv.rotate(image, 20);
// Rotate 30 degrees around point (10, 20)
rotated = await cv.rotate(image, {x: 10, y: 20, angle: 30});
promise = cv.flipLeftRight(matrix)
Flips the matrix around the y-axis.
argument |
type |
description |
matrix |
Matrix |
The matrix to flip |
return value |
type |
description |
promise |
Matrix |
The flipped matrix |
const flipped = await cv.flipLeftRight(image);
promise = cv.flipUpDown(matrix)
Flips the matrix around the x-axis.
argument |
type |
description |
matrix |
Matrix |
The matrix to flip |
return value |
type |
description |
promise |
Matrix |
The flipped matrix |
const flipped = await cv.flipUpDown(image);
Enums
ImageType
value |
description |
Gray |
Gray scale image. The underlying OpenCV data type is CV_8UC1 . |
BGR |
BGR color image. The underlying OpenCV data type is CV_8UC3 . |
BGRA |
BGRA color image with an alpha channel. The underlying OpenCV data type is CV_8UC4 . |
Float |
Floating point matrix. The underlying OpenCV data type is CV_64FC1
|
const Gray = cv.ImageType.Gray;
EncodeType
value |
description |
PNG |
PNG format. |
JPEG |
JPEG format. |
const JPEG = cv.EncodeType.JPEG;
BorderType
Describes how to fill the empty space created by some operations like rotate
.
value |
description |
Replicate |
`aaaaaa |
Reflect |
`fedcba |
Reflect101 |
`gfedcb |
Wrap |
`cdefgh |
Constant |
`iiiiii |
const Replicate = cv.BorderType.Replicate;
Channel
value |
description |
Gray |
Gray channel |
Red |
Red channel |
Green |
Green channel |
Blue |
Blue channel |
Alpha |
Alpha channel |
Float |
Floating point channel |
const Gray = cv.Channel.Gray;
Types
Rectangle
Any javascript object with properties x
, y
, width
and height
. Note that the Rect
class
instances have these properties and can be passed as Rectangles
.
property |
type |
description |
x |
number |
x-coordinate |
y |
number |
y-coordinate |
width |
number |
width |
height |
number |
height |
const rect = {
x: 10,
y: 20,
width: 100,
height: 100
};
Point
A javascript object with properties x
and y
.
property |
type |
description |
x |
number |
x-coordinate |
y |
number |
y-coordinate |
const point = {
x: 10,
y: 20
};
Color
A javascript object with properties red
, green
, blue
and optionally alpha
.
property |
type |
description |
red |
integer |
red component |
green |
integer |
green component |
blue |
integer |
blue component |
alpha |
integer |
alpha component (optional) |
const color = {
red: 0,
green: 255,
blue: 128,
alpha: 255
};
ChannelData
A javascript object with properties data
and channel
.
property |
type |
description |
data |
Buffer |
channel data in row-major order |
channel |
Channel |
channel type |
const channelData = {
data: new Buffer(100),
channel: cv.Channel.Gray
};
ResizeParams
property |
type |
description |
width |
number |
wanted result width |
height |
number |
wanted result height |
scale |
number |
size multiplier |
xScale |
number |
width multiplier |
yScale |
number |
height multiplier |
let resizeParams = {
width: 200,
height: 300
};
resizeParams = {
scale: 2
};
resizeParams = {
xScale: 0.5,
yScale: 1.5
};
WarpParams
property |
type |
description |
borderType |
BorderType |
How to fill the empty space the transformation causes |
borderValue |
number |
The constant value for BorderType.Constant
|
RotateParams
property |
type |
description |
x |
number |
The x-coordinate if the point around which the image will be rotated |
y |
number |
The y-coordinate if the point around which the image will be rotated |
angle |
number |
Rotation angle (degrees) |
borderType |
BorderType |
How to fill the empty space the rotation causes |
borderValue |
number |
The constant value for BorderType.Constant
|