kaiwinter / boundingboxeditor

A JavaFX desktop application for creating image-object-annotations with bounding boxes.

This is an image annotation desktop-application written in Java using the JavaFX application platform. It allows you to create bounding box annotations using rectangular and polygonal shapes. Annotations can be imported and saved from/to JSON files, Pascal VOC format XML-files or YOLO format TXT-files.

Demo screenshot of release v2.0.0.

Main Features

• Create rectangular and polygonal ("vertices-clicking" and "freehand-drawing" modes) bounding box annotations for objects in images
• Export and import rectangular and polygonal bounding box annotations to and from JSON and XML files (using Pascal VOC format)
• Export and import rectangular bounding box annotations using the YOLO format
• Connect your own Torch Serve prediction endpoint and use bounding box predictions as annotation hints
• Format validation and error reporting when importing annotations
• Nest bounding box labels (which is then reflected in the output XML-file if using Pascal VOC format)
• Easily and swiftly navigate and search the loaded image files via a side-panel with thumbnails
• Tag bounding boxes using tags defined in the Pascal VOC format (truncated, difficult, occluded, pose: *, action: *)
• Color-coded, searchable and fully dynamic object categories

Latest Release

Download the latest release installer or portable image (no installation required) of Bounding Box Editor for your operating system from the links below. These files were created using the jpackage packaging tool, the Badass JLink Gradle plugin and github-actions.

OS	Installer	Portable	Stats
Linux	deb, rpm	image
macOS	dmg	image
Windows	exe	image

Alternative installation methods

Windows

choco install boundingboxeditor

How to use the application

Please refer to the User Manual in the Wiki for a detailed usage guide and presentation (including gifs) of the application's main functions.

Using annotations for object detection

After having created annotations for your images, you can use the saved bounding boxes as ground-truths in the training and evaluation of neural networks in order to perform object-detection tasks. How this can be done for any kind of labeled objects using Python and the Pytorch deep learning library is shown exemplarily in the Humpback Whale Fluke Detection - Jupyter notebook which you can find in my Machine Learning repo.

How to build the application

The project uses Gradle as build-system. You will need to have Gradle version 5+ and a Java JDK version 11+ installed on your system, e.g. from OpenJDK. After cloning the repository into a folder on your machine you may build the application from the root folder by opening a command line and using:

gradlew build # Add "-x test" to skip the UI-tests.

Note: The concrete way of invoking gradlew depends on your OS and used command line:

• Linux & MacOs: ./gradlew ...
• Windows:
  • Command Prompt: gradlew ...
  • Powershell: .\gradlew ...

How to run the application

To run the app using Gradle, use:

gradlew run

How to run the tests

The project comes equipped with automatic UI-tests which use TestFX and the JUnit 5 testing frameworks. Due to some used functionality in the implemented tests it is (currently) not possible to run the tests in headless mode.

To run the tests, use :

gradlew test

How to build the latest Linux image and installers using Docker

First build the Docker image from the cloned repo's root directory using:

docker image build -t bbeditor .

Then create a writable container layer over the image (without starting a container):

docker container create --name bbeditor bbeditor

Finally, copy the directory containing the build artifacts to the host:

docker container cp bbeditor:/artifacts .

Alternative:
If you have a recent Docker version that supports BuildKit engine (version >= 19.03) you can do the whole build using a one-line command:

DOCKER_BUILDKIT=1 docker image build --target artifacts --output type=local,dest=. . 

Acknowledgements

• OpenJDK (open-source implementation of the Java platform)
• OpenJFX (open-source implementation of the JavaFX platform)
• ControlsFX (used for progress dialogs)
• Caffeine (used for caching of images)
• Gson (used for JSON serialization & deserialization)
• Apache Commons (used for ListOrderedMap data structure and String/Iterator utilities)
• TestFX (used for the tests)
• JUnit 5 (used for the tests)
• Jacoco (used for creating code coverage results)
• sass-gradle-plugin (used to compile .scss style-files into [JavaFX supported] .css files)
• Badass JLink Plugin (used to create modular runtime images of the application)
• Gradle Modules Plugin (used to run the tests on the classpath)
• Feather Icons
• Nord Color-Palette
• Unsplash (used as source for test- & demo-images)

License

This project is licensed under GPL v3. See LICENSE.