koskimas / simple-cv

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

About

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


Languages

Language:JavaScript 55.2%Language:C++ 35.5%Language:C 7.8%Language:Python 0.8%Language:CMake 0.7%