Introduction

Detecting objects that are not aligned with the image axes—such as vehicles in aerial imagery or text in scanned documents—presents a significant challenge for standard object detection frameworks. Most traditional detectors use axis-aligned bounding boxes, which lead to imprecise localization and high background noise when objects are rotated. MMRotate is an open-source rotated object detection toolbox based on PyTorch, part of the OpenMMLab ecosystem, that solves these issues by providing a coherent framework for training, inferring, and evaluating oriented bounding boxes. With its modular design and support for state-of-the-art algorithms, it allows researchers and developers to move beyond the limitations of horizontal boxes to achieve high-precision localization in complex scenes.

What Is MMRotate?

MMRotate is a PyTorch-based open-source toolbox designed specifically for rotated object detection. It provides a unified platform for implementing and benchmarking various rotated object detection algorithms, allowing users to define objects using rotated rectangles, quadrilaterals, or even arbitrary shapes. Unlike standard detectors, MMRotate increases the degrees of freedom in regression to include an angle parameter, redefining the object representation from (x, y, w, h) to (x, y, w, h, theta).

Maintained by the OpenMMLab organization, the project is licensed under the Apache License 2.0, making it highly accessible for both academic research and commercial applications. It integrates seamlessly with other OpenMMLab libraries like MMCV and MMDetection, leveraging their foundational components to provide a robust and flexible environment for computer vision tasks.

Why MMRotate Matters

In many real-world scenarios, horizontal bounding boxes are insufficient. For example, in remote sensing (aerial imagery), objects like ships or aircraft are often densely packed and oriented in various directions. Using a horizontal box to enclose a diagonal object results in a box that covers a large area of the background, leading to poor overlap (IoU) and imprecise localization. This “background leakage” is a primary failure mode of standard detectors.

MMRotate fills this gap by providing a standardized way to handle oriented bounding boxes (OBB). It eliminates the need for developers to implement complex rotation-aware loss functions and angle definitions from scratch. By offering a benchmark of 15+ state-of-the-art algorithms, it allows users to quickly compare different methods and find the optimal model for their specific dataset, such as DOTA or HRSCNet.

The project’s significance is further amplified by its modularity. Because it follows the OpenMMLab design philosophy, users can easily swap backbones, detection heads, and loss functions without rewriting the entire pipeline. This makes it the most comprehensive tool for anyone needing to detect non-axis-aligned objects with high precision.

Key Features

• Gaussian Wasserstein Distance (GWD) Loss: Models rotated bounding boxes as 2D Gaussian distributions to approximate the indifferentiable rotational IoU loss. This resolves the “boundary discontinuity” and “square-like” problems common in angle regression.
• Modular Architecture: Decomposes the detection framework into interchangeable components (backbones, necks, heads), allowing for rapid prototyping of new models.
• Comprehensive Algorithm Suite: Implements a wide array of SOTA rotated object detection algorithms, providing strong baselines for researchers.
• Multiple Angle Representations: Supports three mainstream angle definition methods to ensure compatibility with various research papers and datasets.
• Integrated Benchmarking: Provides a coherent framework for training, reasoning, and evaluation, making it easy to compare the performance of different algorithms on standard benchmarks.
• OpenMMLab Ecosystem Integration: Leverages MMCV and MMDetection for efficient tensor operations and foundational detection logic, reducing redundant code.

How MMRotate Compares

When compared to general-purpose object detection frameworks, MMRotate is specialized for orientation. While frameworks like MMDetection or Detectron2 can be extended to support rotated boxes, MMRotate is built from the ground up to handle the unique geometric challenges of rotation.

The primary differentiator for MMRotate is its specialized loss functions, such as Gaussian Wasserstein Distance (GWD). Standard detectors struggle with the periodicity of angles (e.g., 0 and 180 degrees can look identical for some boxes), which causes a jump in loss values—the boundary discontinuity problem. MMRotate’s GWD loss transforms boxes into Gaussian distributions, treating the distance between them as a Wasserstein distance, which is smooth and differentiable, effectively eliminating these jumps.

While MMDetection is an excellent choice for standard axis-aligned detection, MMRotate is the correct choice when the target objects have a clear orientation and are densely packed, as it significantly reduces false positives and improves the mean Average Precision (mAP) on oriented datasets.

Getting Started: Installation

MMRotate requires a specific environment setup because it depends on MMCV and MMDetection. It is highly recommended to use a Conda environment to avoid dependency conflicts.

Prerequisites

Ensure you have Python 3.7+, PyTorch 1.6+, and CUDA 9.2+ installed. You will also need GCC 5+ for compiling CUDA operators.

Installation via MIM (Recommended)

MIM is the OpenMMLab package manager that simplifies the installation of their toolboxes.

pip install -U openmim
mim install mmengine
mim install "mmcv>=2.0.0rc2"
mim install "mmdet>=3.0.0rc2"
mim install mmrotate

Installation from Source

If you plan to modify the code or develop new algorithms, install from source:

git clone https://github.com/open-mmlab/mmrotate.git
cd mmrotate
pip install -r requirements/build.txt
pip install -v -e .

To verify the installation, you can import the library in Python and check the version:

import mmrotate
print(mmrotate.__version__)

How to Use MMRotate

The workflow in MMRotate follows the standard OpenMMLab pattern: configuration files define the model, dataset, and training hyperparameters, and a runner script executes the training or inference.

The first step is to select a configuration file from the configs/ directory. These files are Python-based and allow you to customize every part of the model, such as the backbone (e.g., ResNet-50) and the detection head. Once a config is selected, you can download the pre-trained weights (checkpoints) provided in the repository.

To run a simple inference demo on an image, you can use the provided demo script:

python demo/image_demo.py demo/demo.jpg

This script loads the model, applies the selected config, and saves the result as an image with oriented bounding boxes drawn on the target objects.

Code Examples

The following examples demonstrate how to interact with MMRotate’s API for inference and model initialization.

Basic Inference

This snippet shows how to initialize a detector and perform inference on a single image using the provided APIs.

from mmrotate.apis import init_detector, inference_detector

# Initialize the model with a config file and a checkpoint
model = init_detector('configs/oriented_rcnn_r50_fpn_1x_dota.py', 'checkpoints/oriented_rcnn_r50_fpn_1x_dota.pth')

# Perform inference on an image
result = inference_detector(model, 'demo/demo.jpg')
print(result)

Customizing the Loss Function

In the configuration file, you can easily switch the regression loss to GWD (Gaussian Wasserstein Distance) to improve accuracy for small, rotated objects.

# Example snippet from a config file
model = dict(
    roi_head = dict(
        bbox_head = dict(
            loss_bbox = dict(
                type='GaussianWassersteinDistLoss',
                loss_weight=2.0
            )
        )
    )
)

Real-World Use Cases

MMRotate is particularly effective in domains where objects are not axis-aligned and are densely packed.

• Aerial and Satellite Imagery: Detecting ships in harbors, aircraft on runways, or vehicles in parking lots. These objects have a fixed aspect ratio but vary wildly in orientation.
• Scene Text Detection: Identifying slanted or curved text lines in natural scenes (e.g., signs, labels on packaging). Oriented boxes provide a cleaner extraction for subsequent OCR pipelines.
• Industrial Inspection: In production lines, the orientation of a component can signal whether a part is assembled correctly or if a defect is present. Orientation-aware detection reduces ambiguity in object state.
• Medical Imaging: Detecting cells or blood vessels in microscopy images where biological structures are oriented randomly across the slide.

Contributing to MMRotate

MMRotate is an open-source project that welcomes contributions from the community. You can contribute by implementing new rotated object detection algorithms, adding new datasets, or improving the documentation.

To contribute, start by reporting bugs via GitHub Issues. If you have a new feature or a feature request, please follow the project’s contribution guidelines. When submitting a Pull Request, ensure that your code follows the project’s coding style and includes tests to verify the new functionality. Since MMRotate is part of the OpenMMLab ecosystem, it follows the general contributing guidelines of the OpenMMLab project.

Community and Support

MMRotate is supported by a robust community of computer vision researchers and developers. Support can be found through several official channels:

• GitHub Discussions: The primary hub for general questions, troubleshooting, and feature requests.
• GitHub Issues: For reporting technical bugs and requesting specific feature improvements.
• Official GitHub Repository: The source of truth for all code, releases, and pre-trained models.
• Official Documentation: Detailed guides on installation, getting started, and user tutorials.

The project maintains a high level of activity, with frequent updates to ensure compatibility with the latest PyTorch and MMCV versions.

Conclusion

MMRotate is the most comprehensive toolbox for rotated object detection, providing a bridge between academic research and industrial application. By solving the critical challenges of boundary discontinuity and background leakage, it allows developers to achieve high-precision localization of oriented objects in complex scenes.

If your project involves aerial imagery, scene text, or industrial inspection, MMRotate is the right choice. It is a powerful alternative to standard detectors that provides the specialized tools needed for orientation-aware detection. Star the repo, try the quickstart, and join the community to start detecting rotated objects with precision.

Resources

• Official MMRotate GitHub Repository
• MMRotate Installation Guide