Tutorial Quick Start

WARNING: PARTS OF THIS PAGE ARE OUT OF DATE

To use BoofCV you first need to be familiar with programming in Java and know how to a jar. After you have obtained BoofCV's jar simply add it to your class path and you will be ready to go. The jar can either be obtained by downloading it or by compiling the source code.

Latest Official Release: Download Page

If you need the absolutely latest code it can be obtained by cloning the git repository at github. First make sure git is installed on your computer. In Linux follow the steps outlined below:

cd <project directory>
git clone https://github.com/lessthanoptimal/BoofCV.git
cd BoofCV
git submodule init
git submodule update

Ant scripts are provided for compiling the source code.

cd boofcv/main
ant
ls -lh ../lib/BoofCV.jar

The last command just shows you where the compiled jar is.

If you are building from the latest GIT source code and you get a lot of errors when using the ant script then it is likely that the included jars are out of date. Check out the latest version of EJML and GeoRegression, see links below, and build their respective jars. If those new jar's don't fix it, then post a message on the message board.

Dependencies

All dependencies are included with BoofCV's source code or files downloaded from sourceforge. Just look in the boofcv/lib directory to access the jar files. Below is a list of jar files it depends on.

Jar Name	Package Name and Website
EJML.jar	Efficient Java Matrix Library
GeoRegression.jar	Geometric Regression Library
libpja.jar	Various utility functions

HELP ME!!

Having trouble or have a suggestion? Post a message on the BoofCV message board! Don't worry it's a friendly place.

• message board

Definitions

Term	definition
single band	The image supports only one color
floating point	Image elements are of type float or double
unsigned	Image elements can only be positive integers
signed	Image elements can be either positive or negative integers
generics	Allows strong typing in abstracted code. Introduced in Java 1.5. Click here.

The Basics

ImageUInt8 image = new ImageUInt8 (100,150);

Creating an unsigned 8-bit integer single band image with width=100 and height=150.

ImageFloat32 image = new ImageFloat32(100,150);

Creating a floating point single band image with width=100 and height=150.

MultiSpectral<ImageUInt8> image = new MultiSpectral<ImageUInt8>(ImageUInt8.class,100,200,3);

Creates a color multi spectral image with 3 bands using ImageUInt8 for each band.

ImageFloat32 image = UtilImageIO.loadImage("test.png",ImageFloat32.class);

Loads a single band image of type ImageFloat32 from a file.

public static <T extends ImageBase> T generic( Class<T> imageType ) {
	T image = UtilImageIO.loadImage("test.png",imageType);

Loads an image with the specified type inside a function that uses Java generics.

BufferedImage out = ConvertBufferedImage.convertTo(image,null);

Converts an image into a BufferedImage to provide better integration with Java2D (display/saving). Pixel values must be in the range of 0 to 255.

BufferedImage out = VisualizeImageData.grayMagnitude(derivX,null,-1);

Renders a signed single band image into a gray intensity image.

BufferedImage out = VisualizeImageData.colorizeSign(derivX,null,-1);

Renders a signed single band image into a color intensity image.

BufferedImage out = ConvertBufferedImage.convertTo(image,null);
ShowImages.showWindow(out,"Output");

Displays an image in a window using Java swing.

Pixel Access

The image type must be known to access pixel information. The following show how to access pixels for different image types. For more information on the image data structure and direct access to the raw data array see Tutorial Images for more details

public static void function( ImageFloat32 image )
{
	float pixel = image.get(5,23);
	image.set(5,23,50.3);

Gets and sets the pixel at (5,23). Note that set() and get() functions are image type specific. In other words, you can't access pixel without knowing the image type.

public static void function( ImageUInt8 image )
{
	int pixel = image.get(5,23);
	image.set(5,23,50);

Similar to the above example but for an 8-bit unsigned integer image. Note the image.get() returns 'int' and not 'byte'.

public static void function( ImageInteger image )
{
	int pixel = image.get(5,23);
	image.set(5,23,50);

In fact the same code will work for all integer images, except SInt64 which uses longs and not ints. Internally UInt8 stores its pixels as a byte array, but set() and get() return int because Java internally does not use bytes on the register.

public static void function( MultiSpectral<ImageUInt8> image )
{
	int pixel = image.getBand(0).get(5,23);
	image.getBand(0).set(5,23,50);

MultiSpectral images are essentially arrays of ImageSingleBands. To set or get a pixel value first access the particular band that needs to be changed then use the standard accessors inside of ImageSingleBand.

Filters

public static void procedural( ImageUInt8 input )
{
	ImageUInt8 blurred = new ImageUInt8(input.width,input.height);
	BlurImageOps.gaussian(input,blurred,-1,blurRadius,null);

Applies Gaussian blur to an image using a type specific procedural interface.

public static <T extends ImageSingleBand, D extends ImageSingleBand>
void generalized( T input )
{
	Class<T> inputType = (Class<T>)input.getClass();

	T blurred = GeneralizedImageOps.createImage(inputType,input.width, input.height);
	GBlurImageOps.gaussian(input, blurred, -1, blurRadius, null);

Applies Gaussian blur to an image using an abstracted procedural interface. Note the G in front of BlurImageOps that indicates it contains generic functions.

public static <T extends ImageSingleBand, D extends ImageSingleBand>
void filter( T input )
{
	Class<T> inputType = (Class<T>)input.getClass();
	T blurred = GeneralizedImageOps.createImage(inputType, input.width, input.height);
	BlurFilter<T> filterBlur = FactoryBlurFilter.gaussian(inputType, -1, blurRadius);
	filterBlur.process(input,blurred);

Creates an image filter class for computing the Gaussian blur. Provides greater abstraction.

// type specific sobel
GradientSobel.process(blurred, derivX, derivY, FactoryImageBorder.extend(input));
// generic
GImageDerivativeOps.sobel(blurred, derivX, derivY, BorderType.EXTENDED);
// filter
ImageGradient<T,D> gradient = FactoryDerivative.sobel(inputType, derivType);
gradient.process(blurred,derivX,derivY);

Three ways to compute the image gradient using a Sobel kernel.

public static <T extends ImageSingleBand, D extends ImageSingleBand>
void example( T input , Class<D> derivType ) {
	AnyImageDerivative<T,D> deriv = GImageDerivativeOps.createDerivatives((Class<T>)input.getClass(),derivType);

	deriv.setInput(input);
	D derivX = deriv.getDerivative(true);
	D derivXXY = deriv.getDerivative(true,true,false);

Useful class for computing arbitrary image derivatives. Computes 1st order x-derive and then 3rd order xxy derivative.

Binary Images

ThresholdImageOps.threshold(image, binary, 23, true);

Creates a binary image by thresholding the input image. Binary must be of type ImageUInt8.

binary = BinaryImageOps.erode8(binary,null);

Apply an erode operation on the binary image, writing over the original image reference.

BinaryImageOps.erode8(binary,output);

Apply an erode operation on the binary image, saving results to the output binary image.

BinaryImageOps.erode4(binary,output);

Apply an erode operation with a 4-connect rule.

int numBlobs = BinaryImageOps.labelBlobs4(binary,blobs);

Detect and label blobs in the binary image using a 4-connect rule. blobs is an image of type ImageSInt32.

BufferedImage visualized = VisualizeBinaryData.renderLabeled(blobs, numBlobs, null);

Renders the detected blobs in a colored image.

BufferedImage visualized = VisualizeBinaryData.renderBinary(binary,null);

Renders the binary image as a black white image.