CoralNet-Toolbox

💾 How to Install

🐍 Create Conda Environment (Recommended)

It’s recommended to use Anaconda to create an environment for the toolbox:

# Create and activate an environment
conda create --name coralnet10 python=3.10 -y
conda activate coralnet10

# Install uv first
pip install uv

⚡ GPU Acceleration (Optional)

If you have an NVIDIA GPU with CUDA, you can install the corresponding versions of CUDA and PyTorch for full GPU acceleration.

Below is an example for CUDA 12.9:

# Install CUDA toolkit and compiler
conda install nvidia/label/cuda-12.9.0::cuda-nvcc -y
conda install nvidia/label/cuda-12.9.0::cuda-toolkit -y

# Install PyTorch with CUDA 12.9
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu129

For other CUDA versions and detailed installation, see:

📦 Install

Once this has finished, install the toolbox using uv:

# Install with uv (fastest)
uv pip install coralnet-toolbox

Fallback: If uv fails, simply fall back to using pip:

# Install with pip
pip install coralnet-toolbox

▶️ Run

Finally, you can run the toolbox from the command line:

coralnet-toolbox

🎯 GPU Status Indicators

If CUDA is installed and PyTorch was built with it properly, you’ll see a device indicator in the bottom-left corner of the toolbox:

Click the icon to see available device details

🔄 Upgrade

When opening the toolbox, you will be notified if there is an update available. To upgrade to a specific version, run:

# Upgrade to latest version
uv pip install -U coralnet-toolbox

Or upgrade to a specific version:

uv pip install -U coralnet-toolbox==[version_number]

Fallback: If uv fails, use pip instead: pip install -U coralnet-toolbox

Note: If you have torch installed with CUDA, adding -U may trigger a regression to the CPU version. If this occurs, uninstall torch and torchvision, and reinstall the CUDA versions.

🐍 Install from Source (GitHub Repository)

If you prefer to clone the repository and run the toolbox from the source code:

# Create and activate an environment
conda create --name coralnet10 python=3.10 -y
conda activate coralnet10

# Install git via conda (if not already installed)
conda install git -y

# Change to your desired directory
cd Documents

# Clone and enter the repository
git clone https://github.com/Jordan-Pierce/CoralNet-Toolbox.git
cd CoralNet-Toolbox

# Install CUDA requirements (if applicable)
conda install nvidia/label/cuda-12.9.0::cuda-nvcc -y
conda install nvidia/label/cuda-12.9.0::cuda-toolkit -y

# Install PyTorch with CUDA support
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu129

# Install the toolbox in development mode
pip install -e .

# Run
coralnet-toolbox

Updating Your Repository

To update your repository to match the current version on main:

# Navigate to repository directory
cd CoralNet-Toolbox

# Fetch latest changes
git fetch

# Pull updates from main
git pull

# Update your environment
pip install -e . -U

Install from GitHub Directly

You can also install the toolbox from the GitHub repo without cloning:

# Install from main branch
pip install git+https://github.com/Jordan-Pierce/CoralNet-Toolbox.git@main -U

# Or install from a different branch (e.g., for testing experimental features)
pip install git+https://github.com/Jordan-Pierce/CoralNet-Toolbox.git@branch-name -U

🧹 Cleanup

Remove a Package

To remove a problematic package:

uv pip uninstall package-name-here

Delete and Reset Environment

To delete an old environment and start fresh:

# Deactivate the environment first
conda deactivate

# Delete the environment by name
conda env remove --name coralnet10

# Confirm when prompted
y

⚠️ MacOS Users

Version 1.0.0 and later rely heavily on PyQtADS, which cannot be installed on macOS. Do not upgrade from version 0.0.105 until this is resolved.

🐳 Docker

To run the toolbox in a Docker container:

# Build the Docker image
docker build -t coralnet-vnc .

# Run the container with VNC access
docker run -d -p 6901:6901 -p 5901:5901 --name coralnet-app coralnet-vnc
This site is open source. Improve this page.