coralnet-toolbox 0.0.72__py2.py3-none-any.whl → 0.0.74__py2.py3-none-any.whl

coralnet_toolbox/utilities.py

@@ -9,14 +9,14 @@ import requests
 import traceback
 from functools import lru_cache
 
+import cv2
 import torch
 import numpy as np
 
 import rasterio
 from rasterio.windows import Window
 
-from shapely.validation import make_valid
-from shapely.geometry import Polygon, MultiPolygon, LineString, GeometryCollection
+from shapely.geometry import Polygon
 
 from PyQt5.QtCore import Qt
 from PyQt5.QtGui import QImage
@@ -109,6 +109,19 @@ def rasterio_to_qimage(rasterio_src, longest_edge=None):
         QImage: Scaled image
     """
     try:
+        # Check if the dataset is closed
+        if not rasterio_src or getattr(rasterio_src, 'closed', True):
+            # Attempt to reopen the dataset if we can get the path
+            if hasattr(rasterio_src, 'name'):
+                try:
+                    rasterio_src = rasterio.open(rasterio_src.name)
+                except Exception as reopen_error:
+                    print(f"Error reopening dataset: {str(reopen_error)}")
+                    return QImage()
+            else:
+                print("Cannot read from closed dataset without path information")
+                return QImage()
+                
         # Get the original size of the image
         original_width = rasterio_src.width
         original_height = rasterio_src.height
@@ -190,7 +203,7 @@ def rasterio_to_qimage(rasterio_src, longest_edge=None):
             # Transpose to height, width, channels format
             image = np.transpose(image, (1, 2, 0))
 
-        # Convert to uint8 if not already
+        # Convert to uint8 if image is not already
         if image.dtype != np.uint8:
             if image.max() > 0:  # Avoid division by zero
                 image = image.astype(float) * (255.0 / image.max())
@@ -222,6 +235,19 @@ def rasterio_to_cropped_image(rasterio_src, window):
         QImage: Cropped image as a QImage
     """
     try:
+        # Check if the dataset is closed
+        if not rasterio_src or getattr(rasterio_src, 'closed', True):
+            # Attempt to reopen the dataset if we can get the path
+            if hasattr(rasterio_src, 'name'):
+                try:
+                    rasterio_src = rasterio.open(rasterio_src.name)
+                except Exception as reopen_error:
+                    print(f"Error reopening dataset: {str(reopen_error)}")
+                    return QImage()
+            else:
+                print("Cannot read from closed dataset without path information")
+                return QImage()
+
         # Check for single-band image with colormap
         has_colormap = False
         if rasterio_src.count == 1:
@@ -305,6 +331,19 @@ def rasterio_to_numpy(rasterio_src, longest_edge=None):
         numpy.ndarray: Image as a numpy array in format (h, w, c) for RGB or (h, w) for grayscale
     """
     try:
+        # Check if the dataset is closed
+        if not rasterio_src or getattr(rasterio_src, 'closed', True):
+            # Attempt to reopen the dataset if we can get the path
+            if hasattr(rasterio_src, 'name'):
+                try:
+                    rasterio_src = rasterio.open(rasterio_src.name)
+                except Exception as reopen_error:
+                    print(f"Error reopening dataset: {str(reopen_error)}")
+                    return np.zeros((100, 100, 3), dtype=np.uint8)
+            else:
+                print("Cannot read from closed dataset without path information")
+                return np.zeros((100, 100, 3), dtype=np.uint8)
+                
         # Get the original size of the image
         original_width = rasterio_src.width
         original_height = rasterio_src.height
@@ -412,6 +451,19 @@ def work_area_to_numpy(rasterio_src, work_area):
     """
     if not rasterio_src:
         return None
+        
+    # Check if the dataset is closed
+    if getattr(rasterio_src, 'closed', True):
+        # Attempt to reopen the dataset if we can get the path
+        if hasattr(rasterio_src, 'name'):
+            try:
+                rasterio_src = rasterio.open(rasterio_src.name)
+            except Exception as reopen_error:
+                print(f"Error reopening dataset: {str(reopen_error)}")
+                return None
+        else:
+            print("Cannot read from closed dataset without path information")
+            return None
 
     # If we got a WorkArea object, use its rect
     if hasattr(work_area, 'rect'):
@@ -542,50 +594,6 @@ def scale_pixmap(pixmap, max_size):
     return scaled_pixmap
 
 
-def attempt_download_asset(app, asset_name, asset_url):
-    """
-    Attempt to download an asset from the given URL.
-
-    :param app:
-    :param asset_name:
-    :param asset_url:
-    :return:
-    """
-    # Create a progress dialog
-    progress_dialog = ProgressBar(app, title=f"Downloading {asset_name}")
-
-    try:
-        # Get the asset name
-        asset_name = os.path.basename(asset_name)
-        asset_path = os.path.join(os.getcwd(), asset_name)
-
-        if os.path.exists(asset_path):
-            return
-
-        # Download the asset
-        response = requests.get(asset_url, stream=True)
-        total_size = int(response.headers.get('content-length', 0))
-        block_size = 1024  # 1 Kibibyte
-
-        # Initialize the progress bar
-        progress_dialog.start_progress(total_size // block_size)
-        progress_dialog.show()
-
-        with open(asset_path, 'wb') as f:
-            for data in response.iter_content(block_size):
-                if progress_dialog.wasCanceled():
-                    raise Exception("Download canceled by user")
-                f.write(data)
-                progress_dialog.update_progress()
-
-    except Exception as e:
-        QMessageBox.critical(app, "Error", f"Failed to download {asset_name}.\n{e}")
-
-    # Close the progress dialog
-    progress_dialog.set_value(progress_dialog.max_value)
-    progress_dialog.close()
-
-
 def simplify_polygon(xy_points, simplify_tolerance=0.1):
     """
     Filter a list of points to keep only the largest polygon and simplify it.
@@ -666,6 +674,88 @@ def densify_polygon(xy_points):
         return xy_points.tolist() if isinstance(xy_points, np.ndarray) else xy_points
 
 
+def polygonize_mask_with_holes(mask_tensor):
+    """
+    Converts a boolean mask tensor to an exterior polygon and a list of interior hole polygons.
+
+    Args:
+        mask_tensor (torch.Tensor): A 2D boolean tensor from the prediction results.
+
+    Returns:
+        A tuple containing:
+        - exterior (list of tuples): The (x, y) vertices of the outer boundary.
+        - holes (list of lists of tuples): A list where each element is a list of (x, y) vertices for a hole.
+    """
+    # Convert the tensor to a NumPy array format that OpenCV can use
+    mask_np = mask_tensor.squeeze().cpu().numpy().astype(np.uint8)
+
+    # Find all contours and their hierarchy
+    # cv2.RETR_CCOMP organizes contours into a two-level hierarchy: external boundaries and holes inside them.
+    contours, hierarchy = cv2.findContours(mask_np, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE)
+
+    if not contours or hierarchy is None:
+        return [], []
+
+    exterior = []
+    holes = []
+
+    # Process the hierarchy to separate the exterior from the holes
+    for i, contour in enumerate(contours):
+        # An external contour's parent in the hierarchy is -1
+        if hierarchy[0][i][3] == -1:
+            # Squeeze to convert from [[x, y]] to [x, y] format
+            exterior = contour.squeeze(axis=1).tolist()
+        else:
+            # Any other contour is treated as a hole
+            holes.append(contour.squeeze(axis=1).tolist())
+
+    return exterior, holes
+
+
+def attempt_download_asset(app, asset_name, asset_url):
+    """
+    Attempt to download an asset from the given URL.
+
+    :param app:
+    :param asset_name:
+    :param asset_url:
+    :return:
+    """
+    # Create a progress dialog
+    progress_dialog = ProgressBar(app, title=f"Downloading {asset_name}")
+
+    try:
+        # Get the asset name
+        asset_name = os.path.basename(asset_name)
+        asset_path = os.path.join(os.getcwd(), asset_name)
+
+        if os.path.exists(asset_path):
+            return
+
+        # Download the asset
+        response = requests.get(asset_url, stream=True)
+        total_size = int(response.headers.get('content-length', 0))
+        block_size = 1024  # 1 Kibibyte
+
+        # Initialize the progress bar
+        progress_dialog.start_progress(total_size // block_size)
+        progress_dialog.show()
+
+        with open(asset_path, 'wb') as f:
+            for data in response.iter_content(block_size):
+                if progress_dialog.wasCanceled():
+                    raise Exception("Download canceled by user")
+                f.write(data)
+                progress_dialog.update_progress()
+
+    except Exception as e:
+        QMessageBox.critical(app, "Error", f"Failed to download {asset_name}.\n{e}")
+
+    # Close the progress dialog
+    progress_dialog.set_value(progress_dialog.max_value)
+    progress_dialog.close()
+    
+
 def console_user(error_msg, parent=None):
     """
     Display an error message to the user via both terminal and GUI dialog.

coralnet_toolbox-0.0.74.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: coralnet-toolbox
+Version: 0.0.74
+Summary: Tools for annotating and developing ML models for benthic imagery
+Author-email: Jordan Pierce <jordan.pierce@noaa.gov>
+License: MIT License
+Project-URL: Homepage, https://github.com/Jordan-Pierce/CoralNet-Toolbox
+Keywords: CoralNet-Toolbox
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: <3.11,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: PyQt5>=5.15.11
+Requires-Dist: pyqtdarktheme
+Requires-Dist: pyqtgraph
+Requires-Dist: ultralytics>=8.3.152
+Requires-Dist: lap>=0.5.12
+Requires-Dist: open-clip-torch>=2.20.0
+Requires-Dist: supervision>=0.24.0
+Requires-Dist: scikit-learn
+Requires-Dist: umap-learn
+Requires-Dist: faiss-cpu
+Requires-Dist: pycocotools
+Requires-Dist: ujson
+Requires-Dist: timm==0.9.2
+Requires-Dist: autodistill
+Requires-Dist: transformers>=4.5.0
+Requires-Dist: x-segment-anything>=0.0.8
+Requires-Dist: yolo-tiling>=0.0.19
+Requires-Dist: roboflow
+Requires-Dist: rasterio
+Requires-Dist: requests
+Requires-Dist: selenium>=4.15.2
+Requires-Dist: beautifulsoup4>=4.12.2
+Requires-Dist: webdriver_manager
+Requires-Dist: dill
+Requires-Dist: seaborn
+Provides-Extra: all
+Requires-Dist: coralnet-toolbox[extra]; extra == "all"
+Dynamic: license-file
+
+# CoralNet-Toolbox 🪸🧰
+
+<div align="center">
+  <p>
+    <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/CoralNet_Toolbox.png" alt="CoralNet-Toolbox" width="400">
+  </p>
+  
+  <h3>🌊 <em>Empowering Coral Reef Research with AI-Powered Annotation Tools</em> 🌊</h3>
+  
+  <p><strong>An unofficial toolkit to supercharge your <a href="https://coralnet.ucsd.edu/">CoralNet</a> workflows with cutting-edge computer vision</strong></p>
+</div>
+
+---
+
+## 📊 Project Stats
+
+<div align="center">
+
+[![Python Version](https://img.shields.io/pypi/pyversions/CoralNet-Toolbox.svg?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/CoralNet-Toolbox)
+[![Version](https://img.shields.io/pypi/v/CoralNet-Toolbox.svg?style=for-the-badge&color=blue)](https://pypi.python.org/pypi/CoralNet-Toolbox)
+[![Downloads](https://img.shields.io/pepy/dt/coralnet-toolbox.svg?style=for-the-badge&color=brightgreen)](https://pepy.tech/project/coralnet-toolbox)
+
+[![PyPI Passing](https://img.shields.io/github/actions/workflow/status/Jordan-Pierce/CoralNet-Toolbox/pypi.yml?style=for-the-badge&label=PyPI%20Build&logo=github)](https://pypi.org/project/CoralNet-Toolbox)
+[![Windows](https://img.shields.io/github/actions/workflow/status/Jordan-Pierce/CoralNet-Toolbox/windows.yml?style=for-the-badge&label=Windows&logo=windows&logoColor=white)](https://pypi.org/project/CoralNet-Toolbox)
+[![macOS](https://img.shields.io/github/actions/workflow/status/Jordan-Pierce/CoralNet-Toolbox/macos.yml?style=for-the-badge&label=macOS&logo=apple&logoColor=white)](https://pypi.org/project/CoralNet-Toolbox)
+[![Ubuntu](https://img.shields.io/github/actions/workflow/status/Jordan-Pierce/CoralNet-Toolbox/ubuntu.yml?style=for-the-badge&label=Ubuntu&logo=ubuntu&logoColor=white)](https://pypi.org/project/CoralNet-Toolbox)
+
+</div>
+
+---
+
+## ✨ Why CoralNet-Toolbox?
+
+<div align="center">
+  
+| 🎯 **Smart Annotation** | 🤖 **AI-Powered** | 🚀 **Complete Pipeline** |
+|:---:|:---:|:---:|
+| Create patches, rectangles, and polygons with intelligent assistance | Leverage SAM, YOLO, and foundation models | From data collection to deployment |
+| *Precision meets efficiency* | *Cutting-edge AI at your fingertips* | *End-to-end workflow automation* |
+
+</div>
+
+---
+
+## ⚡ Quick Start
+
+Get up and running in seconds:
+
+```bash
+# 💻 Installation
+pip install coralnet-toolbox
+
+# 🚀 Launch
+coralnet-toolbox
+```
+
+> **🎉 That's it!** The toolbox will open and you're ready to start annotating! 
+
+For a complete installation guide (including CUDA setup), see the [Installation Documentation](https://jordan-pierce.github.io/CoralNet-Toolbox/installation).
+
+---
+
+## 📚 Documentation Hub
+
+<div align="center">
+
+| 📖 Guide | 🎯 Purpose | 🔗 Link |
+|:---:|:---:|:---:|
+| **Overview** | Get the big picture | [📋 Read More](https://jordan-pierce.github.io/CoralNet-Toolbox/overview) |
+| **Installation** | Detailed setup instructions | [⚙️ Setup Guide](https://jordan-pierce.github.io/CoralNet-Toolbox/installation) |
+| **Usage** | Learn the tools | [🛠️ User Manual](https://jordan-pierce.github.io/CoralNet-Toolbox/usage) |
+| **Classification** | Community tutorial | [🧠 AI Tutorial](https://jordan-pierce.github.io/CoralNet-Toolbox/classify) |
+
+</div>
+
+---
+
+## 🎥 Video Demonstrations
+
+<details open>
+<summary><h3>📺 <strong>Watch the Complete Tutorial Series</strong></h3></summary>
+
+<div align="center">
+  <a href="https://youtube.com/playlist?list=PLG5z9IbwhS5NQT3B2jrg3hxQgilDeZak9&feature=shared">
+    <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/toolbox_qt.PNG" alt="Video Tutorial Series" width="80%" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);">
+  </a>
+  
+  <p><strong>🎬 Complete playlist covering all major features and workflows</strong></p>
+</div>
+
+</details>
+
+---
+
+## 🤖 AI Model Arsenal
+
+The toolbox integrates state-of-the-art models for efficient annotation workflows:
+
+<div align="center">
+
+### 🏋️ **Trainable Models**
+
+| **YOLO Family** | **Versions Available** |
+|:---:|:---:|
+| 🦾 **Legacy** | YOLOv3 • YOLOv4 • YOLOv5 |
+| 🚀 **Modern** | YOLOv6 • YOLOv7 • YOLOv8 |
+| ⚡ **Latest** | YOLOv9 • YOLOv10 • YOLO11 • YOLO12 |
+
+*Powered by the [Ultralytics](https://ultralytics.com/) ecosystem*
+
+</div>
+
+<div align="center">
+
+### 🎯 **Segment Anything Models**
+
+| **Model** | **Specialty** | **Use Case** |
+|:---:|:---:|:---:|
+| 🪸 **SAM** | General segmentation | High-quality masks |
+| 🌊 **CoralSCOP** | Coral-specific | Marine biology focus |
+| ⚡ **FastSAM** | Speed optimized | Real-time annotation |
+| 📱 **MobileSAM** | Mobile-friendly | Edge deployment |
+| ✂️ **EdgeSAM** | Efficient | Resource-constrained |
+| 🔍 **RepViT-SAM** | Vision transformers | Advanced features |
+
+*Powered by our [xSAM](https://Github.com/Jordan-Pierce/xSAM) integration*
+
+</div>
+
+<div align="center">
+
+### 👁️ **Visual Prompting & Foundation Models**
+
+| **Framework** | **Models** | **Capability** |
+|:---:|:---:|:---:|
+| **YOLOE** | See Anything | Visual prompt detection |
+| **AutoDistill** | Grounding DINO • OWLViT • OmDetTurbo | Zero-shot detection |
+
+</div>
+
+---
+
+## 🛠️ Feature Showcase
+
+<div align="center">
+
+### 📝 **Core Annotation Tools**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Patches.gif" alt="Patch Annotation" width="250" style="border-radius: 8px;"/><br>**🎯 Patch Annotation** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Rectangles.gif" alt="Rectangle Annotation" width="250" style="border-radius: 8px;"/><br>**📐 Rectangle Annotation** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Polygons.gif" alt="Polygon Annotation" width="250" style="border-radius: 8px;"/><br>**🔷 Multi-Polygon Annotation** |
+|:---:|:---:|:---:|
+
+### 🤖 **AI-Powered Analysis**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Classification.gif" alt="Classification" width="250" style="border-radius: 8px;"/><br>**🧠 Image Classification** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Object_Detection.gif" alt="Object Detection" width="250" style="border-radius: 8px;"/><br>**🎯 Object Detection** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Instance_Segmentation.gif" alt="Instance Segmentation" width="250" style="border-radius: 8px;"/><br>**🎭 Instance Segmentation** |
+|:---:|:---:|:---:|
+
+### 🔬 **Advanced Capabilities**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Segment_Anything.gif" alt="SAM" width="250" style="border-radius: 8px;"/><br>**🪸 Segment Anything (SAM)** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Classifying_Polygons.gif" alt="Polygon Classification" width="250" style="border-radius: 8px;"/><br>**🔍 Polygon Classification** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Work_Areas.gif" alt="Work Areas" width="250" style="border-radius: 8px;"/><br>**📍 Region-based Detection** |
+|:---:|:---:|:---:|
+
+### ✂️ **Editing & Processing Tools**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Cut.gif" alt="Cut Tool" width="250" style="border-radius: 8px;"/><br>**✂️ Cut** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Combine.gif" alt="Combine Tool" width="250" style="border-radius: 8px;"/><br>**🔗 Combine** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Simplify.gif" alt="Simplify Tool" width="250" style="border-radius: 8px;"/><br>**🎨 Simplify** |
+|:---:|:---:|:---:|
+
+### 🌟 **Specialized Features**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/See_Anything.gif" alt="YOLOE" width="400" style="border-radius: 8px;"/><br>**👁️ See Anything (YOLOE)** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Classifying_Orthomosaics.gif" alt="LAI Classification" width="400" style="border-radius: 8px;"/><br>**🗺️ LAI Classification** |
+|:---:|:---:|
+
+### 📊 **Analysis & Exploration**
+
+| <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Analytics.gif" alt="Video Analysis" width="400" style="border-radius: 8px;"/><br>**🎬 Video Inference & Analytics** | <img src="https://raw.githubusercontent.com/Jordan-Pierce/CoralNet-Toolbox/refs/heads/main/figures/tools/Explorer.gif" alt="Data Explorer" width="400" style="border-radius: 8px;"/><br>**🔍 Data Explorer & Clustering** |
+|:---:|:---:|
+
+</div>
+
+---
+
+## 🔧 Complete Workflow Pipeline
+
+### 📥 **Data Input**
+- **🔥 CoralNet Download**: Retrieve source data and annotations
+- **🎬 Video Processing**: Extract frames from video files
+- **📸 Image Import**: Support for various image formats
+
+### ✏️ **Annotation & Labeling**
+- **👆 Manual Annotation**: Intuitive point, rectangle, and polygon tools
+- **🤖 AI-Assisted**: SAM, YOLO, and visual prompting models
+- **📐 Precision Editing**: Cut, combine, subtract, and simplify shapes
+
+### 🧠 **Machine Learning**
+- **🔬 Hyperparameter Tuning**: Optimize training conditions
+- **🚀 Model Training**: Build custom classifiers and detectors
+- **⚡ Model Optimization**: Production-ready deployment
+
+### 📊 **Analysis & Export**
+- **📈 Performance Evaluation**: Comprehensive model metrics
+- **🎯 Batch Inference**: Process multiple images automatically
+- **🎥 Video Analysis**: Real-time processing with analytics
+- **📋 Multi-format Export**: CoralNet, Viscore, TagLab, GeoJSON
+
+---
+
+## 📋 Roadmap
+
+*See the current tickets and planned features on the [GitHub Issues Page](https://github.com/Jordan-Pierce/CoralNet-Toolbox/issues)*
+
+---
+
+## 💻 Installation Guide
+
+### 🐍 **Step 1: Environment Setup**
+```bash
+# Create a dedicated environment (recommended)
+conda create --name coralnet10 python=3.10 -y
+conda activate coralnet10
+```
+
+### ⚡ **Step 2: Fast Installation with UV**
+```bash
+# Install UV for faster package management
+pip install uv
+
+# Install CoralNet-Toolbox
+uv pip install coralnet-toolbox
+```
+
+> **Fallback**: If UV fails, use regular pip: `pip install coralnet-toolbox`
+
+### 🚀 **Step 3: GPU Acceleration (Optional)**
+For CUDA-enabled systems:
+```bash
+# Example for CUDA 11.8
+conda install nvidia/label/cuda-11.8.0::cuda-nvcc -y
+conda install nvidia/label/cuda-11.8.0::cuda-toolkit -y
+
+# Install PyTorch with CUDA support
+uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 --upgrade
+```
+
+### 🏃‍♂️ **Step 4: Launch**
+```bash
+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*
+
+### 🔄 **Upgrading**
+```bash
+# When updates are available
+uv pip install -U coralnet-toolbox==[latest_version]
+```
+
+---
+
+### 🏗️ **Repository Structure**
+
+<div align="center">
+![Visualization of the codebase](./diagram.svg)
+</div>
+
+---
+
+## 🌊 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
+
+<div align="center">
+  <p><em>🪸 Protecting our oceans, one annotation at a time 🪸</em></p>
+</div>
+
+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](https://coralnet.ucsd.edu/)** 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:
+
+```bibtex
+@misc{CoralNet-Toolbox,
+  author = {Pierce, Jordan and Battista, Tim},
+  title = {CoralNet-Toolbox: AI-Powered Tools for Coral Reef Research},
+  year = {2025},
+  howpublished = {\url{https://github.com/Jordan-Pierce/CoralNet-Toolbox}},
+  note = {GitHub repository}
+}
+```
+
+---
+
+## ⚖️ Legal & Licensing
+
+<div align="center">
+
+### ⚠️ **Disclaimer**
+*This is a scientific product and not official communication of NOAA or the US Department of Commerce. All code is provided 'as is' - users assume responsibility for its use.*
+
+### 📋 **License**
+*Software created by US Government employees is not subject to copyright in the United States (17 U.S.C. §105). The Department of Commerce reserves rights to seek copyright protection in other countries.*
+
+</div>
+
+---
+
+<div align="center">
+  <p><strong>🌊 Built with ❤️ for coral reef conservation 🌊</strong></p>
+  <p><em>Empowering researchers • Protecting ecosystems • Advancing science</em></p>
+</div>