Difference between revisions of "Manual"

From BoofCV
Jump to navigationJump to search
 
(152 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Development with BoofCV =
Welcome to BoofCV!  BoofCV is an open source Java computer vision library intended for developers.  The following manual provides an introduction to development with BoofCV.  It is assumed that the reader is familiar with development in the Java programming language and the basics of computer vision. This manual primarily takes the form of example code and tutorials.


The following manual provides an introduction to development with BoofCV.  It is assumed that the reader is familiar with development in the Java programming language and the basics of computer vision. This manual primarily takes the form of tutorials.  However, before going through the tutorials one should be familiar with coding standards use in BoofCV.  Once these are understood one will be able to efficiently search the library or even guess the names of classes which are needed.
= Getting Started =


== Coding Standards ==
Before you can do anything with BoofCV you will need to download it.  The [[Download:BoofCV|download]] page provides instructions on how to download pre-compiled jars, source code, add a Maven dependency, and checkout the latest source code. After you obtain the jar files browse through the examples below to get ideas on how you can use BoofCV.


One of the primary reasons Java was selected as a programming language for this library are the set of development tools available for Java.  Less restrictive and structured languages such as C/C++ essentially allow the developer to redefine much of the language on the fly.  While at first this sounds like a positive characteristic, it has hindered the ability to create development tools which allow [http://en.wikipedia.org/wiki/Code_refactoring refactoring] and other modern techniques.  BoofCV's API has been designed to take full advantage of integrated development environments (IDE) such as [http://www.jetbrains.com/idea/ IntelliJ] and [http://www.eclipse.org/ Eclipse].
* [https://youtu.be/qcJ6iBBEnKo Video tutorial on creating a new Desktop project]


Unfortunately Java does not provide templates.  For example, if two classes are identical in every respect except that they use different primitive data structures internally in Java you need to create to classes.  In languages such as C++ you can create one template class.  The later is easier to maintain and requires less code.  To get around this issue auto code generation is extensively used throughout the library.
== Pre-Build Applications ==


A common pitfall which developers fall into is over abstraction.  This leads to code which is difficult to use or develop because of its complexity and layers of abstraction.  Computer vision has many complex algorithms and competing ideologies on how to catalog these algorithms together.  To mitigate this issue the code in BoofCV has been divided into algorithms and abstractions.  Code inside of algorithms has minimal abstraction and is implemented in whichever way makes the most sense to that particular algorithm.  Abstraction containers generalized interfaced and wrappers around the algorithms so that they fit that particular formalism.  This also greatly reduces unnecessary dependencies between the code allowing pieces of BoofCV to be cut off and used independently.
Want to try out BoofCV without needing to build it? [[Applications|Check out the available applications!]]


PROCEDURAL VS OOP.
== Building ==


<h3>Packages</h3>
To use BoofCV in your project you do NOT need to build it. The best way to add BoofCV to you project is by using the jars uploaded to Maven Central and referencing them in your Gradle or Maven project. See [[Download]] for more instructions on adding BoofCV to your project.


Each project module (e.g. image processing) has a standardized package structure.
Building BoofCV is very easy. The only bit that's tricky is knowing that you need to first run the auto code generator as is shown below. Note that it can take a minute or two the first time you build to download all the dependencies.
<syntaxhighlight lang="bash">
cd boofcv
git clean -fd main
./gradlew autogenerate
./gradlew publishToMavenLocal
</syntaxhighlight>
The latest build script should even download the latest JDK for you. If there are any issues please post a question to the [https://groups.google.com/group/boofcv?pli=1 message board]. If you are building from an IDE such as IntelliJ or Eclipse you will probably need to point it towards the correct JDK manually. The [https://github.com/lessthanoptimal/BoofCV/blob/SNAPSHOT/README.md readme.md] will have the latest info on JDK compatibility, but Java 15 is what it needs to be built with.


{| style="width: 640px;" border="1"
== Support ==
! Java Package
 
! Description
Support is provided in the form of the documentation on this website and through its message board.  See the left navigation board for a link to the message board.  Please read through the documentation and FAQ (see below) first before posting a question there.  You are much more likely to get a good response if you demonstrate due diligence.
|-
 
| boofcv.abst
http://boofcv.org/index.php?title=FAQ
| Contains abstracted interfaces or wrappers for algorithms in the same family or to enforce different formalismsSometimes to conform to these algorithms performance or unique capabilities are lost but added flexibility is gained by making it easier to switch algorithms.
 
|-
If you find any mistakes in the documentation or library itself please submit a bug report or post a message about it!  If you don't let us know about it we can't fix it.
| boofcv.alg
 
| Bare algorithms which minimal abstractionUsing algorithms directly allows for greater performance and or for a developer to wrap inside their own interface/frame work.
== Propaganda ==
|-
 
| boofcv.factory
Did you find BoofCV useful and use it on your project/work/research/thesis?  Well let others know about it through your blog, twitter, or status message! Academics, please cite BoofCV in your papers and checkout the papers page to see if the specific algorithm you are using is mentioned there.
| Contains factories for creating raw algorithms or abstracted implementations of algorithms easily. Using a factory makes it easier to get started but the simplicity comes at the cost of flexibility. Flexibility is lost because factories hard code some parameters.
 
|}
<center> [[Papers and Reports|BoofCV Papers and Tech Report]] </center>
<h3>Directory Structure</h3>
 
= Examples and Tutorial =
 
A few tutorials and examples are provided to provide the basic concepts of development with BoofCVData files used in these examples are stored in a separate GIT repository from the main code.  See [https://github.com/lessthanoptimal/BoofCV/blob/master/examples/readme.txt boofcv/examples/readme.txt] or https://github.com/lessthanoptimal/BoofCV-Data
 
Want to quickly explore all the examples and run all the demonstrations? Checkout the source code and run the following applications:
<pre>
cd boofcv
./gradlew examples
java -jar examples/examples.jar
./gradlew demonstrations
java -jar demonstrations/demonstrations.jar
</pre>
 
 
[https://youtu.be/qMTtdiujAtQ?t=107 YouTube Video] showing the above applications being built and run.
 
Alternatively you can just download a pre-compiled application and explore these examples that way. See [[Applications]].


Each project module also has a standardized directory structure.
== Tutorials ==


{| style="width: 640px;" border="1"
{| class="wikitable"
! Directory
! Topics
! Description
! Languages
|-
|-
| src/
|
| Contains library source code.
# [[Tutorial Quick Start|Quick Start]]
# [[Tutorial Images|Images in BoofCV]]
# [[Tutorial_Image_Segmentation| Image Segmentation]]
# [[Tutorial_Fiducials|Fiducials]]
# [[Tutorial_QRCodes|QR Codes]]
# [[Tutorial Videos and Webcams|Videos and Webcams]]
# [[Tutorial_Camera_Calibration| Camera Calibration ]]
# [[Tutorial Geometric Vision| 3D Computer Vision / Structure from Motion]]
# [[3D_Reconstruction_on_Desktop_Tutorial|Photogrammetry / 3D Reconstruction]]
# [[Tutorial Kinect| Kinect RGB-D Sensor]]
# [[Concurrency | Concurrency / Multi Threading]]
# [[Visualization| Visualization]]
|
# [[Kotlin | Kotlin]]
# [https://github.com/lessthanoptimal/PyBoof PyBoof (Python)]
# [[Tutorial_Processing | Processing]]
|-
|-
| test/
! Devices
| Contains unit tests for source code.
!
|-
|-
| generate/
|
| Source code for auto-generating source code in "src/".  The package of the generator corresponds to the package the output should be placed inside.
# [[Android_support|Android Support]]
|-
# [[Raspberry_PI | Raspberry PI]]
| benchmark/
|
| Contains simple codes for testing runtime performance of different algorithms.  Used during development to ensure efficiency.
|}
|}  


<h3>Class Name Standards</h3>
== Example Code ==
List of simple examples which demonstrate a single capability of BoofCV.


The following standard prefixes and suffices are used throughout the code base.
{| class="wikitable"
 
|
{| style="width: 640px;" border="1"
* Image Processing
! name
*# [[Example Binary Image|Binary Images]]
! Description
*# [[Example Color Space| Color Space]]
*# [[Example Convolution|Convolution]]
*# [[Example Discrete Fourier Transform| Discrete Fourier Transform]]
*# [[Example Image Blur|Image Blur]]
*# [[Example Image Convert|Converting Images]]
*# [[Example_Image_Derivative|Image Derivative]]
*# [[Example Image Filter|Image Filters]]
*# [[Example_Interpolation|Interpolation]]
*# [[Example_Morphological_Thinning|Morphological Thinning]]
*# [[Example Planar Image|Using Planar Images]]
*# [[Example_Key_Point_Based_Deformation|Point Based Deformation]]
*# [[Example Image Pyramid| Image Pyramid]]
*# [[Example RGB to Gray| Rgb To Gray]]
*# [[Example Simulate Motion Blur| Simulate Motion Blur]]
*# [[Example Threads| Multi Threading]]
|
* Feature
*# [[Example Associate Interest Points| Associate Interest Points]]
*# [[Example_Associate_Three_View| Associate Three Views]]
*# [[Example Canny Edge| Canny Edge Detector]]
*# [[Example_Detect_Corners| Corner Features]]
*# [[Example Dense Image Features| Dense Image Features]]
*# [[Example Dense Optical Flow| Dense Optical Flow]]
*# [[Example_Detect_Black_Ellipses| Detecting Black Ellipses]]
*# [[Example_Detect_Black_Polygons| Detecting Black Polygons]]
*# [[Example_Detect_Describe_Interface| Detect Describe Interface]]
*# [[Example_Feature_Selector_Limit| Feature Selector Limit]]
*# [[Example SURF Feature| Computing SURF Features]]
*# [[Example_Fit_Ellipse| Fitting Ellipses]]
*# [[Example_Fit_Polygon| Fitting Polygons]]
*# [[Example Detect Interest Points| Detecting Interest Points]]
*# [[Example Detect Lines|Detecting Lines and Line Segments]]
*# [[Example Non Maximum Suppression|Non Maximum Suppression]]
|-
|-
| Impl* || Is a low level (often auto-generated image type specific) implementation of an algorithm.  Directly accessing these class is rarely required and discouraged.
|
* Image Enhancement
*# [[Example Image Enhancement| Image Enhancement]]
*# [[Example Wavelet Noise Removal| Wavelet Noise Removal]]
|
* Segmentation
*# [[Example Color Segmentation| Color Segmentation]]
*# [[Example Superpixels| Superpixels]]
*# [[Example Thresholding|Thresholding]]
*# [[Example Watershed with Seeds| Watershed with Seeds]]
|-
|-
| Wrap* || Wrapper around an algorithm for a specific interface.  These classes are found inside the boofcv.abst package and its children.
|
* Stereo Vision
*# [[Example Rectification Calibrated| Rectify Calibrated Stereo]]
*# [[Example Stereo Disparity| Stereo Disparity Fully Calibrated]]
*# [[Example Stereo Disparity 3D| Disparity to 3D Cloud]]
*# [[Example Disparity Smoothing| Disparity Smoothing]]
*# [[Example_Stereo_Mesh| Disparity to Mesh]]
*# [[Example Stereo Single Camera| Stereo Calibrated Single Camera]]
*# [[Example Stereo Uncalibrated| Stereo Uncalibrated Single Camera]]
*# [[Example Three View Stereo Uncalibrated| Stereo Uncalibrated 3 Views]]
|
* Geometry
*# [[Example_Point_Cloud_Depth_Image| Point Cloud from Depth/RGB-D]]
*# [[Example Image Stitching| Image Stitching]]
*# [[Example Overhead View| Image to Overhead View]]
*# [[Example Remove Perspective Distortion| Remove Perspective Distortion]]
*# [[Example Video Mosaic| Video Mosaic]]
*# [[Example Video Stabilization| Video Stabilization]]
|-
|-
| Factory* || Factory for creating abstracted algorithms.
|
* Structure from Motion
*# [[Example_Sparse_Bundle_Adjustment| Sparse Bundle Adjustment]]
*# [[Example_Bundle_Adjustment_Graph| Bundle Adjustment Graph]]
*# [[Example Fundamental Matrix| Computing Fundamental Matrix]]
*# [[ExampleComputeTrifocalTensor| Computing Trifocal Tensor]]
*# [[Example_PnP| Perspective-n-Point ]]
*# [[ExampleTrifocalTensorUses| Using Trifocal Tensor]]
*# [[Example_Visual_Odometry_Depth| Visual Odometry: Depth/RGB-D]]
*# [[Example_Visual_Odometry_Monocular_Plane| Visual Odometry: Monocular Plane]]
*# [[Example_Stereo_Visual_Odometry| Visual Odometry: Stereo]]
|
* Calibration
*# [[Example Calibrate Planar Fisheye| Calibrate Fisheye Camera]]
*# [[Example Calibrate Planar Mono| Calibrate Monocular Camera]]
*# [[Example_Calibrate_Planar_Multi| Calibrate Multi Cameras]]
*# [[Example Calibrate Planar Stereo| Calibrate Stereo Camera]]
*# [[Example Detect Calibration Target| Detecting Calibration Targets]]
*# [[Example Equirectangular To Pinhole| Equirectangular To Pinhole ]]
*# [[Example Fisheye To Equirectangular| Fisheye To Equirectangular ]]
*# [[Example Fisheye To Pinhole| Fisheye To Pinhole ]]
*# [[Example Remove Lens Distortion| Remove Lens Distortion]]
|-
|-
| Factory*Alg || Factory for creating a raw algorithms.
|
* Tracking
*# [[Example_Background_Moving_Camera| Background Moving Camera]]
*# [[Example_Background_Stationary_Camera| Background Stationary Camera]]
*# [[Example Track Point Features| Track Point Features]]
*# [[Example Tracker Mean Shift| Mean Shift Likelihood Tracker]]
*# [[Example Tracker Object| Object Tracker]]
|
* Reconstruction
*# [[Example_Loop_Closure| Loop Closure]]
*# [[Example_Multi_Baseline_Stereo| Multi Baseline Stereo]]
*# [[Example_Multiview_Reconstruction_Dense| Multiview Dense Reconstruction]]
*# [[Example_Multiview_Uncalibrated_Reconstruction_Sparse| Uncalibrated Multiview Sparse]]
|-
|-
| *_F32, *_F64 || Implementation for 32-bit/64-bit floating point images or data structures, respectively.
|
* Fiducials
*# [[Example_Detect_Aztec_Code|Aztec Code Detector]]
*# [[Example_Detect_Micro_QR_Code|Micro QR Code Detector]]
*# [[Example_Detect_QR_Code|QR Code Detector]]
*# [[Example_Fiducial_Square_Binary| Square Binary]]
*# [[Example_Fiducial_Square_Hamming| Square Hamming]]
*# [[Example_Fiducial_Square_Image| Square Image]]
*# [[Example_Fiducial_Random_Dots| Random Dots]]
*# [[Example Calibration Target Pose| Calibration Target]]
*# [[Example_QR_Code_Binary_Data| QR Code with Binary Data]]
*# [[Example_Render_Aztec_Code|Aztec Code Rendering]]
*# [[Example_Render_Micro_QR_Code|Micro QR Code Rendering]]
*# [[Example_Render_QR_Code|QR Code Rendering]]
|
* Recognition
*# [[Example_Scene_Classification| KNN Classification]]
*# [[Example Color Histogram Lookup| Color Histogram Lookup]]
*# [[Example Image Classification| Image Classification]]
*# [[Example Scene Recognition| Scene Recognition]]
*# [[Example_Template_Matching| Template Matching]]
|-
|-
| *_S32 || Implementation for signed 32-bit integer images or data structures.
|
|-
* Point Clouds
| *_U16, *_S16 || Implementation for unsigned/signed 16-bit integer images or data structures, respectively.
*# [[Example Load and Save Point Clouds| Load and Save Clouds]]
|-
*# [[Example View Point Cloud| View Point Cloud]]
| *_U8, *_S8 || Implementation for unsigned/signed 8-bit integer images or data structures, respectively.
|
* Integration
*# [[Example_Android_Video| Android Video (Old)]]
*# [[Example_Android_Fragment_Gradient | Android Fragment]]
*# [[Example Webcam Capture| Webcam Capture]]
|}
|}
= List of Tutorial =
= Building BoofCV =
The easiest way to build the library from source is using the provided ant scripts.
# Download source code.
# Run the ant script inside the boofcv/main directory.
# Copy the BoofCV.jar from boofcv/lib.
In Linux this looks something like this:
<pre>
$ cd boofcv/main/
$ ant
---- lots of text -----
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
    [javac] 15 warnings
jar:
      [jar] Building jar: /home/pja/projects/boofcv/main/jar/BoofCV_IO.jar
main:
      [jar] Building jar: /home/pja/projects/boofcv/lib/BoofCV.jar
main:
BUILD SUCCESSFUL
Total time: 7 seconds
</pre>

Latest revision as of 15:17, 15 July 2023

Welcome to BoofCV! BoofCV is an open source Java computer vision library intended for developers. The following manual provides an introduction to development with BoofCV. It is assumed that the reader is familiar with development in the Java programming language and the basics of computer vision. This manual primarily takes the form of example code and tutorials.

Getting Started

Before you can do anything with BoofCV you will need to download it. The download page provides instructions on how to download pre-compiled jars, source code, add a Maven dependency, and checkout the latest source code. After you obtain the jar files browse through the examples below to get ideas on how you can use BoofCV.

Pre-Build Applications

Want to try out BoofCV without needing to build it? Check out the available applications!

Building

To use BoofCV in your project you do NOT need to build it. The best way to add BoofCV to you project is by using the jars uploaded to Maven Central and referencing them in your Gradle or Maven project. See Download for more instructions on adding BoofCV to your project.

Building BoofCV is very easy. The only bit that's tricky is knowing that you need to first run the auto code generator as is shown below. Note that it can take a minute or two the first time you build to download all the dependencies.

cd boofcv
git clean -fd main
./gradlew autogenerate
./gradlew publishToMavenLocal

The latest build script should even download the latest JDK for you. If there are any issues please post a question to the message board. If you are building from an IDE such as IntelliJ or Eclipse you will probably need to point it towards the correct JDK manually. The readme.md will have the latest info on JDK compatibility, but Java 15 is what it needs to be built with.

Support

Support is provided in the form of the documentation on this website and through its message board. See the left navigation board for a link to the message board. Please read through the documentation and FAQ (see below) first before posting a question there. You are much more likely to get a good response if you demonstrate due diligence.

http://boofcv.org/index.php?title=FAQ

If you find any mistakes in the documentation or library itself please submit a bug report or post a message about it! If you don't let us know about it we can't fix it.

Propaganda

Did you find BoofCV useful and use it on your project/work/research/thesis? Well let others know about it through your blog, twitter, or status message! Academics, please cite BoofCV in your papers and checkout the papers page to see if the specific algorithm you are using is mentioned there.

BoofCV Papers and Tech Report

Examples and Tutorial

A few tutorials and examples are provided to provide the basic concepts of development with BoofCV. Data files used in these examples are stored in a separate GIT repository from the main code. See boofcv/examples/readme.txt or https://github.com/lessthanoptimal/BoofCV-Data

Want to quickly explore all the examples and run all the demonstrations? Checkout the source code and run the following applications:

cd boofcv
./gradlew examples
java -jar examples/examples.jar
./gradlew demonstrations
java -jar demonstrations/demonstrations.jar


YouTube Video showing the above applications being built and run.

Alternatively you can just download a pre-compiled application and explore these examples that way. See Applications.

Tutorials

Topics Languages
  1. Quick Start
  2. Images in BoofCV
  3. Image Segmentation
  4. Fiducials
  5. QR Codes
  6. Videos and Webcams
  7. Camera Calibration
  8. 3D Computer Vision / Structure from Motion
  9. Photogrammetry / 3D Reconstruction
  10. Kinect RGB-D Sensor
  11. Concurrency / Multi Threading
  12. Visualization
  1. Kotlin
  2. PyBoof (Python)
  3. Processing
Devices
  1. Android Support
  2. Raspberry PI

Example Code

List of simple examples which demonstrate a single capability of BoofCV.