gab.opencv
Class OpenCV

java.lang.Object
  extended by gab.opencv.OpenCV

public class OpenCV
extends Object

OpenCV is the main class for using OpenCV for Processing. Most of the documentation is found here. OpenCV for Processing is a computer vision library for the Processing creative coding toolkit. It's based on OpenCV, which is widely used throughout industry and academic research. OpenCV for Processing provides friendly, Processing-style functions for doing all of the most common tasks in computer vision: loading images, filtering them, detecting faces, finding contours, background subtraction, optical flow, calculating histograms etc. OpenCV also provides access to all native OpenCV data types and functions. So advanced users can do anything described in the OpenCV java documentation: http://docs.opencv.org/java/ A text is also underway to provide a narrative introduction to computer vision for beginners using OpenCV for Processing: https://github.com/atduskgreg/opencv-processing-book/blob/master/book/toc.md


Field Summary
static int BOTH
           
static String CASCADE_CLOCK
           
static String CASCADE_EYE
           
static String CASCADE_FRONTALFACE
           
static String CASCADE_FULLBODY
           
static String CASCADE_LOWERBODY
           
static String CASCADE_MOUTH
           
static String CASCADE_NOSE
           
static String CASCADE_PEDESTRIAN
           
static String CASCADE_PEDESTRIANS
           
static String CASCADE_PROFILEFACE
           
static String CASCADE_RIGHT_EAR
           
static String CASCADE_UPPERBODY
           
 CascadeClassifier classifier
           
 int colorSpace
           
 Flow flow
           
 int height
           
static int HORIZONTAL
           
 Mat matA
           
 Mat matB
           
 Mat matBGRA
           
 Mat matG
           
 Mat matGray
           
 Mat matH
           
 Mat matHSV
           
 Mat matR
           
 Mat matROI
           
 Mat matS
           
 Mat matV
           
 Mat nonROImat
           
static String VERSION
           
static int VERTICAL
           
 int width
           
 
Constructor Summary
OpenCV(PApplet theParent, int width, int height)
          Initialize OpenCV with a width and height.
OpenCV(PApplet theParent, PImage img)
          Initialize OpenCV with an image.
OpenCV(PApplet theParent, PImage img, boolean useColor)
          Initialize OpenCV with an image.
OpenCV(PApplet theParent, String pathToImg)
          Initialize OpenCV with the path to an image.
OpenCV(PApplet theParent, String pathToImg, boolean useColor)
          Initialize OpenCV with the path to an image.
 
Method Summary
 void adaptiveThreshold(int blockSize, int c)
          Apply an adaptive threshold to an image.
static void ARGBtoBGRA(Mat rgba, Mat bgra)
           
 void blur(int blurSize)
          Blur an image symetrically by a given number of pixels.
 void blur(int blurW, int blurH)
          Blur an image assymetrically by a different number of pixels in x- and y-directions.
 void brightness(int amt)
          Adjust the brightness of the image.
 void calculateOpticalFlow()
          Calculate the optical flow of the current image relative to a running series of images (typically frames from video).
 void contrast(float amt)
          Adjust the contrast of the image.
 Rectangle[] detect()
          Detect objects using the cascade classifier.
 Rectangle[] detect(double scaleFactor, int minNeighbors, int flags, int minSize, int maxSize)
          Detect objects using the cascade classifier.
static void diff(Mat mat1, Mat mat2)
          A helper function that diffs two Mats using absdiff.
 void diff(PImage img)
          Calculate the difference between the current image loaded into OpenCV and a second image.
 void dilate()
          Dilate the image.
 void drawOpticalFlow()
           
 void equalizeHistogram()
          Normalize the histogram of the image.
 void erode()
          Erode the image.
 void findCannyEdges(int lowThreshold, int highThreshold)
          Find edges in the image using Canny edge detection.
 ArrayList<PVector> findChessboardCorners(int patternWidth, int patternHeight)
           
 ArrayList<Contour> findContours()
           
 ArrayList<Contour> findContours(boolean findHoles, boolean sort)
           
 Histogram findHistogram(Mat mat, int numBins)
           
 Histogram findHistogram(Mat mat, int numBins, boolean normalize)
           
 ArrayList<Line> findLines(int threshold, double minLineLength, double maxLineGap)
           
 void findScharrEdges(int direction)
           
 void findSobelEdges(int dx, int dy)
           
 void flip(int direction)
          Flip the current image.
 Mat getA()
           
 PVector getAverageFlow()
           
 PVector getAverageFlowInRegion(int x, int y, int w, int h)
           
 Mat getB()
           
 Mat getColor()
           
 int getColorSpace()
          Get the colorSpace of the current color image.
 PVector getFlowAt(int x, int y)
           
 Mat getG()
           
 Mat getGray()
           
 Mat getH()
           
 PImage getInput()
           
 PImage getOutput()
           
 Mat getR()
           
 Mat getROI()
           
 Mat getS()
           
 int getSize()
           
 PImage getSnapshot()
           
 PImage getSnapshot(Mat m)
           
 PVector getTotalFlow()
           
 PVector getTotalFlowInRegion(int x, int y, int w, int h)
           
 boolean getUseColor()
          Checks whether OpenCV is currently using the color version of the image or the grayscale version.
 Mat getV()
           
 void gray()
           
static Mat gray(Mat src)
           
static Mat imitate(Mat m)
          Helper to create a new OpenCV Mat whose channels and bit-depth mask an existing Mat.
 void inRange(int lowerBound, int upperBound)
          Filter the image for values between a lower and upper bound.
 void invert()
          Invert the image.
 void loadCascade(String cascadeFileName)
          Load a cascade file for face or object detection.
 void loadCascade(String cascadeFilePath, boolean absolute)
          Load a cascade file for face or object detection.
 void loadImage(PImage img)
           
 void loadImage(String imgPath)
          Load an image from a path.
 int[] matToARGBPixels(Mat m)
          Convert a 4 channel OpenCV Mat object into pixels to be shoved into a 4 channel ARGB PImage's pixel array.
static ArrayList<PVector> matToPVectors(MatOfPoint mat)
           
static ArrayList<PVector> matToPVectors(MatOfPoint2f mat)
           
 String matToS(Mat mat)
           
 PVector max()
          Get the x-y location of the maximum value in the current image.
 PVector min()
          Get the x-y location of the minimum value in the current image.
static PVector pointToPVector(Point p)
          Helper function to convert an OpenCV Point into a Processing PVector
 void releaseROI()
           
 void setColor(Mat m)
           
 void setGray(Mat m)
           
 boolean setROI(int x, int y, int w, int h)
          Set a Region of Interest within the image.
 void startBackgroundSubtraction(int history, int nMixtures, double backgroundRatio)
          Setup background subtraction.
 void threshold(int threshold)
          Apply a global threshold to an image.
static void toCv(PImage img, Mat m)
          Convert a Processing PImage to an OpenCV Mat.
 void toPImage(Mat m, PImage img)
          Convert an OpenCV Mat object into a PImage to be used in other Processing code.
static Rectangle[] toProcessing(Rect[] rects)
          Convert an array of OpenCV Rect objects into an array of java.awt.Rectangle rectangles.
 void updateBackground()
          Update the running background for background subtraction based on the current image loaded into OpenCV.
 void useColor()
          Apply subsequent image processing to the color version of the loaded image.
 void useColor(int colorSpace)
          Set the main working image to be the color version of the imported image.
 void useGray()
          Set OpenCV to do image processing on the grayscale version of the loaded image.
static String version()
          return the version of the library.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

public int width

height

public int height

matBGRA

public Mat matBGRA

matR

public Mat matR

matG

public Mat matG

matB

public Mat matB

matA

public Mat matA

matHSV

public Mat matHSV

matH

public Mat matH

matS

public Mat matS

matV

public Mat matV

matGray

public Mat matGray

matROI

public Mat matROI

nonROImat

public Mat nonROImat

colorSpace

public int colorSpace

classifier

public CascadeClassifier classifier

flow

public Flow flow

VERSION

public static final String VERSION
See Also:
Constant Field Values

CASCADE_FRONTALFACE

public static final String CASCADE_FRONTALFACE
See Also:
Constant Field Values

CASCADE_PEDESTRIANS

public static final String CASCADE_PEDESTRIANS
See Also:
Constant Field Values

CASCADE_EYE

public static final String CASCADE_EYE
See Also:
Constant Field Values

CASCADE_CLOCK

public static final String CASCADE_CLOCK
See Also:
Constant Field Values

CASCADE_NOSE

public static final String CASCADE_NOSE
See Also:
Constant Field Values

CASCADE_MOUTH

public static final String CASCADE_MOUTH
See Also:
Constant Field Values

CASCADE_UPPERBODY

public static final String CASCADE_UPPERBODY
See Also:
Constant Field Values

CASCADE_LOWERBODY

public static final String CASCADE_LOWERBODY
See Also:
Constant Field Values

CASCADE_FULLBODY

public static final String CASCADE_FULLBODY
See Also:
Constant Field Values

CASCADE_PEDESTRIAN

public static final String CASCADE_PEDESTRIAN
See Also:
Constant Field Values

CASCADE_RIGHT_EAR

public static final String CASCADE_RIGHT_EAR
See Also:
Constant Field Values

CASCADE_PROFILEFACE

public static final String CASCADE_PROFILEFACE
See Also:
Constant Field Values

HORIZONTAL

public static final int HORIZONTAL
See Also:
Constant Field Values

VERTICAL

public static final int VERTICAL
See Also:
Constant Field Values

BOTH

public static final int BOTH
See Also:
Constant Field Values
Constructor Detail

OpenCV

public OpenCV(PApplet theParent,
              String pathToImg)
Initialize OpenCV with the path to an image. The image will be loaded and prepared for processing.

Parameters:
theParent - - A PApplet representing the user sketch, i.e "this"
pathToImg - - A String with a path to the image to be loaded

OpenCV

public OpenCV(PApplet theParent,
              String pathToImg,
              boolean useColor)
Initialize OpenCV with the path to an image. The image will be loaded and prepared for processing.

Parameters:
theParent - - A PApplet representing the user sketch, i.e "this"
pathToImg - - A String with a path to the image to be loaded
useColor - - (Optional) Set to true if you want to use the color version of the image for processing.

OpenCV

public OpenCV(PApplet theParent,
              PImage img)
Initialize OpenCV with an image. The image's pixels will be copied and prepared for processing.

Parameters:
theParent - A PApplet representing the user sketch, i.e "this"
img - A PImage to be loaded

OpenCV

public OpenCV(PApplet theParent,
              PImage img,
              boolean useColor)
Initialize OpenCV with an image. The image's pixels will be copiedd and prepared for processing.

Parameters:
theParent - A PApplet representing the user sketch, i.e "this"
img - A PImage to be loaded
useColor - (Optional) Set to true if you want to use the color version of the image for processing.

OpenCV

public OpenCV(PApplet theParent,
              int width,
              int height)
Initialize OpenCV with a width and height. You will need to load an image in before processing. See copy(PImage img).

Parameters:
theParent - A PApplet representing the user sketch, i.e "this"
width - int
height - int
Method Detail

useColor

public void useColor()
Apply subsequent image processing to the color version of the loaded image. Note: Many OpenCV functions require a grayscale image. Those functions will raise an exception if attempted on a color image.


getColorSpace

public int getColorSpace()
Get the colorSpace of the current color image. Will be either RGB or HSB.

Returns:
The color space of the color mats. Either PApplet.RGB or PApplet.HSB

useColor

public void useColor(int colorSpace)
Set the main working image to be the color version of the imported image. Subsequent image-processing functions will be applied to the color version of the image. Image is assumed to be HSB or RGB based on the argument

Parameters:
colorSpace - The color space of the image to be processed. Either RGB or HSB.

useGray

public void useGray()
Set OpenCV to do image processing on the grayscale version of the loaded image.


getUseColor

public boolean getUseColor()
Checks whether OpenCV is currently using the color version of the image or the grayscale version.

Returns:
True if OpenCV is currently using the color version of the image.

loadCascade

public void loadCascade(String cascadeFileName)
Load a cascade file for face or object detection. Expects one of:
 OpenCV.CASCADE_FRONTALFACE
 OpenCV.CASCADE_PEDESTRIANS
 OpenCV.CASCADE_EYE                     
 OpenCV.CASCADE_CLOCK           
 OpenCV.CASCADE_NOSE            
 OpenCV.CASCADE_MOUTH           
 OpenCV.CASCADE_UPPERBODY       
 OpenCV.CASCADE_LOWERBODY       
 OpenCV.CASCADE_FULLBODY        
 OpenCV.CASCADE_PEDESTRIANS
 OpenCV.CASCADE_RIGHT_EAR       
 OpenCV.CASCADE_PROFILEFACE
 
To pass your own cascade file, provide an absolute path and a second argument of true, thusly:
 opencv.loadCascade("/path/to/my/custom/cascade.xml", true)
 
(NB: ant build scripts copy the data folder outside of the jar so that this will work.)

Parameters:
cascadeFileName - The name of the cascade file to be loaded form within OpenCV for Processing. Must be one of the constants provided by this library

loadCascade

public void loadCascade(String cascadeFilePath,
                        boolean absolute)
Load a cascade file for face or object detection. If absolute is true, cascadeFilePath must be an absolute path to a cascade xml file. If it is false then cascadeFilePath must be one of the options provided by OpenCV for Processing as in the single-argument version of this function.

Parameters:
cascadeFilePath - A string. Either an absolute path to a cascade XML file or one of the constants provided by this library.
absolute - Whether or not the cascadeFilePath is an absolute path to an XML file.

toProcessing

public static Rectangle[] toProcessing(Rect[] rects)
Convert an array of OpenCV Rect objects into an array of java.awt.Rectangle rectangles. Especially useful when working with classifier.detectMultiScale().

Parameters:
Rect[] - rects
Returns:
A Rectangle[] of java.awt.Rectangle

detect

public Rectangle[] detect(double scaleFactor,
                          int minNeighbors,
                          int flags,
                          int minSize,
                          int maxSize)
Detect objects using the cascade classifier. loadCascade() must already have been called to setup the classifier. See the OpenCV documentation for details on the arguments: http://docs.opencv.org/java/org/opencv/objdetect/CascadeClassifier.html#detectMultiScale(org.opencv.core.Mat, org.opencv.core.MatOfRect, double, int, int, org.opencv.core.Size, org.opencv.core.Size) A simpler version of detect() that doesn't need these arguments is also available.

Parameters:
scaleFactor -
minNeighbors -
flags -
minSize -
maxSize -
Returns:
An array of java.awt.Rectangle objects with the location, width, and height of each detected object.

detect

public Rectangle[] detect()
Detect objects using the cascade classifier. loadCascade() must already have been called to setup the classifier.

Returns:
An array of java.awt.Rectnangle objects with the location, width, and height of each detected object.

startBackgroundSubtraction

public void startBackgroundSubtraction(int history,
                                       int nMixtures,
                                       double backgroundRatio)
Setup background subtraction. After calling this function, updateBackground() must be called with each new frame you want to add to the running background subtraction calculation. For details on the arguments, see: http://docs.opencv.org/java/org/opencv/video/BackgroundSubtractorMOG.html#BackgroundSubtractorMOG(int, int, double)

Parameters:
history -
nMixtures -
backgroundRatio -

updateBackground

public void updateBackground()
Update the running background for background subtraction based on the current image loaded into OpenCV. startBackgroundSubtraction() must have been called before this to setup the background subtractor.


calculateOpticalFlow

public void calculateOpticalFlow()
Calculate the optical flow of the current image relative to a running series of images (typically frames from video). Optical flow is useful for detecting what parts of the image are moving and in what direction.


getTotalFlowInRegion

public PVector getTotalFlowInRegion(int x,
                                    int y,
                                    int w,
                                    int h)

getAverageFlowInRegion

public PVector getAverageFlowInRegion(int x,
                                      int y,
                                      int w,
                                      int h)

getTotalFlow

public PVector getTotalFlow()

getAverageFlow

public PVector getAverageFlow()

getFlowAt

public PVector getFlowAt(int x,
                         int y)

drawOpticalFlow

public void drawOpticalFlow()

flip

public void flip(int direction)
Flip the current image.

Parameters:
direction - One of: OpenCV.HORIZONTAL, OpenCV.VERTICAL, or OpenCV.BOTH

contrast

public void contrast(float amt)
Adjust the contrast of the image. Works on color or black and white images.

Parameters:
amt - Amount of contrast to apply. 0-1.0 reduces contrast. Above 1.0 increases contrast.

max

public PVector max()
Get the x-y location of the maximum value in the current image.

Returns:
A PVector with the location of the maximum value.

min

public PVector min()
Get the x-y location of the minimum value in the current image.

Returns:
A PVector with the location of the minimum value.

pointToPVector

public static PVector pointToPVector(Point p)
Helper function to convert an OpenCV Point into a Processing PVector

Parameters:
p - A Point
Returns:
A PVector

brightness

public void brightness(int amt)
Adjust the brightness of the image. Works on color or black and white images.

Parameters:
amt - The amount to brighten the image. Ranges -255 to 255.

imitate

public static Mat imitate(Mat m)
Helper to create a new OpenCV Mat whose channels and bit-depth mask an existing Mat.

Parameters:
m - The Mat to match
Returns:
A new Mat

diff

public void diff(PImage img)
Calculate the difference between the current image loaded into OpenCV and a second image. The result is stored in the loaded image in OpenCV. Works on both color and grayscale images.

Parameters:
img - A PImage to diff against.

diff

public static void diff(Mat mat1,
                        Mat mat2)
A helper function that diffs two Mats using absdiff. Places the result back into mat1

Parameters:
mat1 - The destination Mat
mat2 - The Mat to diff against

threshold

public void threshold(int threshold)
Apply a global threshold to an image. Produces a binary image with white pixels where the original image was above the threshold and black where it was below.

Parameters:
threshold - An int from 0-255.

adaptiveThreshold

public void adaptiveThreshold(int blockSize,
                              int c)
Apply an adaptive threshold to an image. Produces a binary image with white pixels where the original image was above the threshold and black where it was below. See: http://docs.opencv.org/java/org/opencv/imgproc/Imgproc.html#adaptiveThreshold(org.opencv.core.Mat, org.opencv.core.Mat, double, int, int, int, double)

Parameters:
blockSize - The size of the pixel neighborhood to use.
c - A constant subtracted from the mean of each neighborhood.

equalizeHistogram

public void equalizeHistogram()
Normalize the histogram of the image. This will spread the image's color spectrum over the full 0-255 range. Only works on grayscale images. See: http://docs.opencv.org/java/org/opencv/imgproc/Imgproc.html#equalizeHist(org.opencv.core.Mat, org.opencv.core.Mat)


invert

public void invert()
Invert the image. See: http://docs.opencv.org/java/org/opencv/core/Core.html#bitwise_not(org.opencv.core.Mat, org.opencv.core.Mat)


dilate

public void dilate()
Dilate the image. Dilation is a morphological operation (i.e. it affects the shape) often used to close holes in contours. It expands white areas of the image. See: http://docs.opencv.org/java/org/opencv/imgproc/Imgproc.html#dilate(org.opencv.core.Mat, org.opencv.core.Mat, org.opencv.core.Mat)


erode

public void erode()
Erode the image. Erosion is a morphological operation (i.e. it affects the shape) often used to close holes in contours. It contracts white areas of the image. See: http://docs.opencv.org/java/org/opencv/imgproc/Imgproc.html#erode(org.opencv.core.Mat, org.opencv.core.Mat, org.opencv.core.Mat)


blur

public void blur(int blurSize)
Blur an image symetrically by a given number of pixels.

Parameters:
blurSize - int - the amount to blur by in x- and y-directions.

blur

public void blur(int blurW,
                 int blurH)
Blur an image assymetrically by a different number of pixels in x- and y-directions.

Parameters:
blurW - amount to blur in the x-direction
blurH - amount to blur in the y-direction

findCannyEdges

public void findCannyEdges(int lowThreshold,
                           int highThreshold)
Find edges in the image using Canny edge detection.

Parameters:
lowThreshold -
highThreshold -

findSobelEdges

public void findSobelEdges(int dx,
                           int dy)

findScharrEdges

public void findScharrEdges(int direction)

findContours

public ArrayList<Contour> findContours()

findContours

public ArrayList<Contour> findContours(boolean findHoles,
                                       boolean sort)

findLines

public ArrayList<Line> findLines(int threshold,
                                 double minLineLength,
                                 double maxLineGap)

findChessboardCorners

public ArrayList<PVector> findChessboardCorners(int patternWidth,
                                                int patternHeight)

findHistogram

public Histogram findHistogram(Mat mat,
                               int numBins)
Parameters:
mat - The mat from which to calculate the histogram. Get this from getGray(), getR(), getG(), getB(), etc.. By default this will normalize the histogram (scale the values to 0.0-1.0). Pass false as the third argument to keep values unormalized.
numBins - The number of bins into which divide the histogram should be divided.
normalize - (optional) Whether or not to normalize the histogram (scale the values to 0.0-1.0). Defaults to true.
Returns:
A Histogram object that you can call draw() on.

findHistogram

public Histogram findHistogram(Mat mat,
                               int numBins,
                               boolean normalize)

inRange

public void inRange(int lowerBound,
                    int upperBound)
Filter the image for values between a lower and upper bound. Converts the current image into a binary image with white where pixel values were within bounds and black elsewhere.

Parameters:
lowerBound -
upperBound -

gray

public static Mat gray(Mat src)
Parameters:
src - A Mat of type 8UC4 with channels arranged as BGRA.
Returns:
A Mat of type 8UC1 in grayscale.

gray

public void gray()

setROI

public boolean setROI(int x,
                      int y,
                      int w,
                      int h)
Set a Region of Interest within the image. Subsequent image processing functions will apply to this ROI rather than the full image. Full image will display be included in output.

Returns:
False if requested ROI exceed the bounds of the working image. True if ROI was successfully set.

releaseROI

public void releaseROI()

loadImage

public void loadImage(String imgPath)
Load an image from a path.

Parameters:
imgPath - String with the path to the image

loadImage

public void loadImage(PImage img)

ARGBtoBGRA

public static void ARGBtoBGRA(Mat rgba,
                              Mat bgra)

getSize

public int getSize()

matToARGBPixels

public int[] matToARGBPixels(Mat m)
Convert a 4 channel OpenCV Mat object into pixels to be shoved into a 4 channel ARGB PImage's pixel array.

Parameters:
m - An RGBA Mat we want converted
Returns:
An int[] formatted to be the pixels of a PImage

toPImage

public void toPImage(Mat m,
                     PImage img)
Convert an OpenCV Mat object into a PImage to be used in other Processing code. Copies the Mat's pixel data into the PImage's pixel array. Iterates over each pixel in the Mat, i.e. expensive. (Mainly used internally by OpenCV. Inspired by toCv() from KyleMcDonald's ofxCv.)

Parameters:
m - A Mat you want converted
img - The PImage you want the Mat converted into.

toCv

public static void toCv(PImage img,
                        Mat m)
Convert a Processing PImage to an OpenCV Mat. (Inspired by Kyle McDonald's ofxCv's toOf())

Parameters:
img - The PImage to convert.
m - The Mat to receive the image data.

matToPVectors

public static ArrayList<PVector> matToPVectors(MatOfPoint mat)

matToPVectors

public static ArrayList<PVector> matToPVectors(MatOfPoint2f mat)

matToS

public String matToS(Mat mat)

getInput

public PImage getInput()

getOutput

public PImage getOutput()

getSnapshot

public PImage getSnapshot()

getSnapshot

public PImage getSnapshot(Mat m)

getR

public Mat getR()

getG

public Mat getG()

getB

public Mat getB()

getA

public Mat getA()

getH

public Mat getH()

getS

public Mat getS()

getV

public Mat getV()

getGray

public Mat getGray()

setGray

public void setGray(Mat m)

setColor

public void setColor(Mat m)

getColor

public Mat getColor()

getROI

public Mat getROI()

version

public static String version()
return the version of the library.

Returns:
String


Processing library opencv_processing by Greg Borenstein. (c) 2013