koskimas/simple-cv

Asynchronous OpenCV bindings for Node.js with a simple promise based API and good documentation

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