Tutorial Quick Start
The following tutorial is intended to provide just enough information for you to quickly set up and start development with BoofCV. If you are not familiar with the Java programming language or its associated development tools, you must fix that first because BoofCV is written entirely in Java. It is highly recommended that you use a tool like Gradle or Maven to build your own project and have it download the jars for you. If you enjoy doing things the slow and tedious way we are there for you and provide all the jars.
Step One: Obtaining
The first step in using BoofCV is either adding it to your dependency list, downloading the precompiled Jars, or building it from Source.
Latest Official Release:
- Source Code Download Page
- Jars Download Page
- Maven and Gradle Download Page
Step Two: Running Examples
For this step you must have the source code checked out from github or downloaded. Just having the jars is not enough. Do that now if you haven't already.
Before you try to run the examples make sure you have all the data they use! The data is stored in a submodule in boofcv/data, which is initially empty if you pulled the source code from Github. If you download the source code then you should have the entire data directory. The easiest way to get the data directory is to pull it from git:
cd boofcv/
git submodule init
git submodule update
Once you do that you are almost ready to run the examples.
BoofCV is built using Gradle. Gradle can be imported into IntelliJ or Eclipse. For instructions on how to do that see the project README.md document. Then in your IDE you can navigate to the examples directory, right click and select run.
If you have Gradle installed in your system, then it's very easy to run examples. For full instructions see examples/readme.txt
gradle exampleRun -Pwhich=boofcv.examples.imageprocessing.ExampleBinaryOps
You can now explore all the example. I recommend trying them out on your own images/data as well as changing parameters and seeing what happens.
HELP ME!!
Having trouble or have a suggestion? Post a message on the BoofCV message board! Don't worry it's a friendly place.
Quick Reference
The remainder of this tutorial is intended to act as a quick reference of low level image processing routines in BoofCV.
| 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
GrayU8 image = new GrayU8(100,150);
Creating an unsigned 8-bit integer single band image with width=100 and height=150.
GrayF32 image = new GrayF32(100,150);
Creating a floating point single band image with width=100 and height=150.
Planar<GrayU8> image = new Planar<GrayU8>(GrayU8.class,100,200,3);
Creates a color planar image with 3 bands using GrayU8 for each band.
GrayF32 image = UtilImageIO.loadImage("test.png",GrayF32.class);
Loads a single band image of type GrayF32 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( GrayF32 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( GrayU8 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( GrayI 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( Planar<GrayU8> image )
{
int pixel = image.getBand(0).get(5,23);
image.getBand(0).set(5,23,50);
Planar images are essentially arrays of ImageGray. 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( GrayU8 input )
{
GrayU8 blurred = new GrayU8(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 ImageGray, D extends ImageGray>
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 ImageGray, D extends ImageGray>
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 ImageGray, D extends ImageGray>
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 GrayS32.
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.
