CoralNet-Toolbox 🪸🧰

AI-Powered Annotation for Coral Reef Analysis. An unofficial toolkit to supercharge your CoralNet workflows.

Marine imaging technology is advancing rapidly, capturing more data than ever before. To keep pace, the instinct of the tech industry is often to build entirely new, fully automated pipelines that disrupt how scientists naturally work. However, this ignores the reality of ecological research: laboratories already rely on stringent standards, deeply established protocols, and decades of domain expertise. CoralNet-Toolbox recognizes that the goal shouldn't be to force a new way of working, but to respect and protect the processes that already yield rigorous scientific results.

⚡ Get Started

1. Create Conda Environment (Recommended)

# Create and activate custom environment
conda create --name coralnet12 python=3.12 -y
conda activate coralnet12

# Install uv
pip install uv

Python version: 3.12 is recommended, and 3.11 is fully supported. Python 3.10 still installs but is deprecated: it reaches end-of-life in October 2026, and newer releases of several dependencies already require 3.11 or 3.12. Python 3.13 and later are not supported yet.

Already on an older environment (for example coralnet10)? Python cannot be upgraded in place — see Moving an Existing Environment to Python 3.12 for the steps.

2. (Optional) GPU Acceleration If you have an NVIDIA GPU with CUDA, install PyTorch with CUDA support for full acceleration.

# Example for CUDA 12.8 for a NVIDIA 5090 (blackwell); use your version of CUDA
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

3. Install

# Use UV for the fastest installation
uv pip install coralnet-toolbox

Fallback: If UV fails, use regular pip: pip install coralnet-toolbox

4. Launch

coralnet-toolbox

🎯 GPU Status Indicators

• 🐢 CPU only
• 🐇 Single GPU
• 🚀 Multiple GPUs
• 🍎 Mac Metal (Apple Silicon)

Click the icon in the bottom-left to see available devices

⚠️ Platform-Specific Notes

macOS Users

Version 1.0.0 and greater relies heavily on a package (PyQtADS) that cannot be installed on your operating system. Please do not upgrade from 0.0.105 until this is resolved. Instead, use Docker for installation — see the Installation Guide for details.

🔧 Running into Issues?

Upgrading

# Upgrade coralnet-toolbox only (without upgrading other packages)
uv pip install --upgrade coralnet-toolbox

Note: Using -U or --upgrade-all upgrades all packages, which may trigger a regression to the CPU version of torch. To avoid this, use the command above to upgrade only coralnet-toolbox. If you do experience a regression, use pip to uninstall torch and torchvision, then re-install the CUDA version.

Removing Packages

To remove a problematic package, type the following:

uv pip uninstall package-name-here

Starting Fresh (New Environment)

To delete an old environment and create a fresh one:

# Deactivate if already in the environment
conda deactivate

# Delete the old environment (coralnet10 is the old Python 3.10 one)
conda env remove --name coralnet10

# Confirm when prompted
y

# Create a new environment (see "Get Started" section above for details)
conda create --name coralnet12 python=3.12 -y
conda activate coralnet12
pip install uv
uv pip install coralnet-toolbox

📚 Resources & Advanced Details

• Installation Guide: Detailed setup for CUDA, Windows, and Mac.
• User Manual: A complete guide to all tools and features.
• Hot Keys: Keyboard shortcuts to accelerate your workflow.
• AI Tutorial: Learn to train your own classification models.

📺 Watch the Demo Videos

🎬 Complete playlist covering all major features and workflows

From Bottleneck to Pipeline

Traditional benthic imagery analysis is time-consuming. Manual annotation, data management, and model training are often separate, complex tasks. CoralNet-Toolbox unifies this process, turning a research bottleneck into an integrated, AI-accelerated pipeline.

📝 Core Annotation Tools

🎯 Patch Annotation	📐 Rectangle Annotation	🔷 Multi-Polygon Annotation

🤖 AI-Powered Analysis

🧠 Image Classification	🎯 Object Detection	🎭 Instance Segmentation

🔬 Advanced Capabilities

🪸 Segment Anything (SAM)	🔍 Polygon Classification	📍 Region-based Detection

✂️ Editing & Processing Tools

✂️ Cut	🔗 Combine	🎨 Simplify

🌊 Success Stories

Using CoralNet-Toolbox in your research?

We'd love to feature your work! Share your success stories to help others learn and get inspired.

🌍 About CoralNet

Coral reefs are among Earth's most biodiverse ecosystems, supporting marine life and coastal communities worldwide. However, they face unprecedented threats from climate change, pollution, and human activities.

CoralNet is a revolutionary platform enabling researchers to:

• Upload and analyze coral reef photographs
• Create detailed species annotations
• Build AI-powered classification models
• Collaborate with the global research community

The CoralNet-Toolbox extends this mission by providing advanced AI tools that accelerate research and improve annotation quality.

📄 Citation

If you use CoralNet-Toolbox in your research, please cite:

@misc{CoralNet-Toolbox,
  author = {Pierce, Jordan and Battista, Tim and Sandin, Stuart and Kuester, Falko},
  title = {CoralNet-Toolbox: Human-in-the-Loop Annotation and Model Development for Benthic Imagery},
  year = {2025},
  howpublished = {\url{https://github.com/Jordan-Pierce/CoralNet-Toolbox}},
  note = {GitHub repository}
}

⚖️ Legal & Licensing