Bounding Box Editor is a desktop application for annotating objects in images with rectangular and polygonal bounding boxes and pixel masks, e.g. to create training data for object detection and instance segmentation. It is written in Java with JavaFX and runs on Windows, macOS and Linux. Annotations can be imported and exported in the Pascal VOC, YOLO, COCO, JSON and CSV formats, and as PNG masks.

Demo screenshot of release v3.0.0.

Main Features

• Drawing and editing: rectangles and polygons (by clicking vertices or drawing freehand). Move and resize boxes, add, move and remove polygon vertices, and simplify polygons. Copy and paste bounding boxes (also to other images), and move the selected one with the arrow keys.

• Pixel masks for instance segmentation: paint and erase objects with a brush of adjustable size.

• Undo and redo for all changes to the bounding boxes, with a separate history per image.

• Nesting and tags: nest bounding boxes (e.g. a wheel inside a car), and tag them with the Pascal VOC tags (truncated, difficult, occluded, pose, action).

• Categories: color-coded and searchable object categories, created as you go. Select one of the first nine with the number keys, and optionally show each bounding box's category name next to it.

• Import and export:

  • Pascal VOC (XML) and JSON: rectangles and polygons, including nesting;
  • YOLO (TXT): rectangles, and polygons in YOLO's segmentation format;
  • CSV: rectangles;
  • COCO (JSON): rectangles, polygons and masks;
  • PNG masks (in the layout of Pascal VOC's segmentation data): masks and polygons.

  Invalid files or entries are listed in an error report, and everything else is imported.

• Image navigation: a side panel with thumbnails, search by file name, and a filter by annotation status (annotated or not) and by categories. Recently opened image folders are listed in the File menu.

• Predictions: connect a TorchServe or LitServe server and use its predicted bounding boxes as annotation hints (see Predictions in the wiki for the setup, including an example LitServe server). The settings are remembered between runs.

• Keyboard shortcuts for navigation, drawing modes, visibility and more.

Latest Release

Download the installer or the portable image (no installation required) of the latest release for your operating system. Both include the Java runtime, so no separate Java installation is needed. They are created with jpackage, the Badass JLink Gradle plugin and GitHub Actions.

OS	Installer	Portable	Stats
Linux (x86-64)	deb, rpm	image
Linux (ARM64)	deb, rpm	image
macOS (Apple Silicon)	dmg	image
macOS (Intel)	dmg	image
Windows (x64)	exe	image

Alternative installation methods

Windows

choco install boundingboxeditor

macOS (Apple Silicon and Intel)

brew install --cask mfl28/tap/boundingboxeditor

The app is not notarized by Apple, so the cask removes the quarantine attribute to allow opening it.

How to use the application

The User Manual in the wiki describes all functions of the application in detail (with screenshots and GIFs), and the Keyboard Shortcuts page lists all shortcuts.

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

You need a Java JDK version 25 or newer, e.g. Eclipse Temurin. The project is built with Gradle; the Gradle wrapper (gradlew) in the repository downloads the right Gradle version, so no separate installation is needed.

After cloning the repository, build the application from its root folder with:

gradlew build -x test # Without "-x test", the tests are run as well (see below).

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

• Linux & macOS: ./gradlew ...
• Windows:
  • Command Prompt: gradlew ...
  • PowerShell: .\gradlew ...

To create an installer for your operating system (in build/jpackage), use:

gradlew jpackage

How to run the application

To run the app using Gradle, use:

gradlew run

How to run the tests

The project has unit tests and UI tests, which use JUnit 5 and TestFX. The UI tests start the application and control it with the mouse and keyboard, so they need a display (they can't run headless). Don't use the mouse or keyboard while they run.

To run all tests, use:

gradlew test

To run only some tests, e.g. the ones of the model package (which don't need a display), use:

gradlew test --tests '*.model.*'

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: With Docker's BuildKit engine (the default since Docker 23), you can do the whole build with one command:

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, popovers and the image filter)
• Caffeine (used for caching of images)
• Gson (used for JSON serialization & deserialization)
• Jackson (used for reading and writing CSV files)
• Eclipse Jersey (used as the REST client for inference servers)
• JTS Topology Suite (used for simplifying polygons)
• metadata-extractor (used for reading the EXIF orientation of images)
• Apache Commons (used for ListOrderedMap data structure and String/Iterator utilities)
• TestFX (used for the tests)
• JUnit 5 (used for the tests)
• Mockito (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.