toxi.video.capture
Class LibCV

java.lang.Object
  toxi.video.capture.LibCV

public class LibCV
extends java.lang.Object

LibCV is a basic video capture wrapper and computer vision library for Processing. Internally it is only working with 8 bit images, but can be used with any Java based capture approach implementing the SimpleCapture interface via an wrapper.

LibCV automatically handles basic computer vision tasks like background subtraction and the computation of difference frames for obtaining motion data. You can choose to only analyze parts of the camera image by defining a quad outlining the area to be examined.

All image buffers used internally and exposed via getBackground(), getBuffer() and getDeltaBuffer() will only contain 8bit data, but will be displayed in colour by Processing's image() method. In order to display these images correctly, the alpha channel is set to 100%. So you'll have to make sure to mask the blue channel where the real data is stored when doing any further analysis:

PImage buf=libcvInstance.getBuffer();
for(int i=0; i < buf.pixels.length; i++) {
int val=buf.pixels[i] & 0xff;
...
}

The SimpleCapture interface is used to ensure a relative independence from various capture backends. It should be very straightforward to write a wrapper for the existing Processing Capture object making use of this interface and to enable its use with this library.

Version:

0.1

Author:

Karsten Schmidt < i n f o [ a t ] t o x i . co . u k >

Nested Class Summary

class

LibCV.Quad Utility datatype for storing a set of four 2D coordinates

Constructor Summary

LibCV(processing.core.PApplet a, SimpleCapture c)
Constructor for the library

Method Summary

void	accumulateBackground(processing.core.PImage img) Mixes the passed image with the currently used background.
processing.core.PImage	getBackground() Retrieves the currently used background buffer.
processing.core.PImage	getBuffer() Returns the buffer containing the most recent frame (depending on when this method has been called, in either processed or unprocessed form)
LibCV.Quad	getCorrectionQuad() Returns the currently used quad for stretching/correcting images.
processing.core.PImage	getDeltaBuffer() Returns the buffer containing the difference to the previous frame
java.lang.String	getError() String description of a capture error occured previously.
processing.core.PImage	getFrame() Calling this method will trigge reading a new frame and to return it.
int	getHeight() Retrieves the pixel height of the buffers
int	getWidth() Retrieves the pixel width of the buffers
boolean	hasBackground() Returns status of the library's background processing setting.
void	hasBackground(boolean s) Tells the library if background subtraction should be used when processing frames
boolean	isCorrected() Returns the status of the library's pixel correction setting
void	processFrame(processing.core.PImage img) Performs background subtraction on the passed image (if enabled) and updates the delta buffer containing movement information.
void	setBackground(processing.core.PImage img) Uses the passed in image as background.
void	setCorrectionPointID(int id, int x, int y) Updates the coordinate of one of the points of the correction quad.
void	stop()
void	useCorrection(boolean state) Enables/disable the trapezoid correction of incoming frames based on the quad defined via setCorrectionPointID(int, int, int)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LibCV

public LibCV(processing.core.PApplet a,
             SimpleCapture c)

Constructor for the library

Parameters:

a - host Processing applet/application

c - capture object

Method Detail

accumulateBackground

public void accumulateBackground(processing.core.PImage img)
                          throws toxi.video.capture.IncompatibleSizeException

Mixes the passed image with the currently used background. This is helpful when "learning" the background by forming an average image over period of time (e.g. average of 100 frames).

Parameters:

img - image to be mixed with existing background

Throws:

IncompatibleSizeException, - if image has different size than buffers.

toxi.video.capture.IncompatibleSizeException

getBackground

public processing.core.PImage getBackground()

Retrieves the currently used background buffer.

Returns:

background as PImage.

getBuffer

public processing.core.PImage getBuffer()

Returns the buffer containing the most recent frame (depending on when this method has been called, in either processed or unprocessed form)

Returns:

the most recent captured buffer

getCorrectionQuad

public LibCV.Quad getCorrectionQuad()

Returns the currently used quad for stretching/correcting images.

Returns:

quad

getDeltaBuffer

public processing.core.PImage getDeltaBuffer()

Returns the buffer containing the difference to the previous frame

Returns:

delta buffer as PImage

getError

public java.lang.String getError()

String description of a capture error occured previously.

Returns:

string with error message or null if all is ok

getFrame

public processing.core.PImage getFrame()

Calling this method will trigge reading a new frame and to return it. To save CPU resources this library is using a polling approach to acquire new frames from the capture object.

Returns:

most recent captured frame

getHeight

public int getHeight()

Retrieves the pixel height of the buffers

Returns:

image width

getWidth

public int getWidth()

Retrieves the pixel width of the buffers

Returns:

image width

hasBackground

public boolean hasBackground()

Returns status of the library's background processing setting.

Returns:

true, if background subtraction is enabled

hasBackground

public void hasBackground(boolean s)

Tells the library if background subtraction should be used when processing frames

Parameters:

s - true, if background is used

isCorrected

public boolean isCorrected()

Returns the status of the library's pixel correction setting

Returns:

true, if trapezoid correction is enabled

processFrame

public void processFrame(processing.core.PImage img)
                  throws toxi.video.capture.IncompatibleSizeException

Performs background subtraction on the passed image (if enabled) and updates the delta buffer containing movement information.

Parameters:

img - image to be processed as frame

Throws:

IncompatibleSizeException, - if image size differs from buffer's

toxi.video.capture.IncompatibleSizeException

setBackground

public void setBackground(processing.core.PImage img)
                   throws toxi.video.capture.IncompatibleSizeException

Uses the passed in image as background. Automatically enables background subtraction for processFrame(PImage)

Parameters:

img - image to be used as background buffer

Throws:

toxi.video.capture.IncompatibleSizeException - if image has different size than buffers.

setCorrectionPointID

public void setCorrectionPointID(int id,
                                 int x,
                                 int y)

Updates the coordinate of one of the points of the correction quad. The quad is used to only consider points located within the shape for the processing of frames. If correction is used, this quad will be stretched to form a rectangle and so eliminating all pixels outside the shape. This is very helpful if you only want to analyze a part of the camera image, or if your camera is skewed it will also automatically perform some kind of perspective correction.

Parameters:

id - index of the point to be set (0 = top-left, 1 = top-right, 2 = bottom - right, 3 = bottom - left)

x - point's x coordinate

y - point's y coordinate

stop

public void stop()

useCorrection

public void useCorrection(boolean state)

Enables/disable the trapezoid correction of incoming frames based on the quad defined via setCorrectionPointID(int, int, int)

Parameters:

state - true, if frames are to be stretched