Add documentation and testing for Bounding Box mode (#396)

This PR adds documentation for bounding box mode now that it's enabled
for all users.

Also, it improves the testing coverage on bounding box mode. There were
some disabled tests that needed to be turned on now that the mode is
available for all users. Also, additional test coverage was added on
adding bbox labels.

---------

Co-authored-by: Auto-format Bot <autoformatbot@groundlight.ai>

Author: f-wright

docs/docs/answer-modes/4-bounding-box-detectors.md

@@ -0,0 +1,130 @@
+# Bounding Box Detectors
+
+Bounding box detectors are used to detect and localize objects in an image by returning bounding boxes around each detected object.
+
+```python notest
+from groundlight import ExperimentalApi
+gl = ExperimentalApi()
+
+# highlight-start
+detector = gl.create_bounding_box_detector(
+    name="dog-detector",
+    query="Draw a bounding box around each dog in the image",
+    class_name="dog",
+    max_num_bboxes=25,
+    confidence_threshold=0.6,
+)
+# highlight-end
+```
+
+Bounding box detectors should be provided with a query that asks the model to identify and localize objects in an image, such as "Draw a bounding box around each dog in the image".
+
+The `class_name` parameter specifies the type of object to detect, and this label will be assigned to each returned bounding box.
+
+The `max_num_bboxes` parameter sets the maximum number of bounding boxes that the detector will return (default: 10). If there are more objects in the image than the maximum, the result label will be `GREATER_THAN_MAX`.
+
+The `confidence_threshold` parameter sets the minimum confidence level required for the ML model's predictions. If the model's confidence falls below this threshold, the query will be sent for human review.
+
+:::note
+Bounding Box Detectors are currently in beta and available through the `ExperimentalApi`. They are available on [Business and Enterprise plans](https://www.groundlight.ai/pricing).
+:::
+
+## Submit an Image Query to a Bounding Box Detector
+
+Now that you have created a bounding box detector, you can submit an image query to it.
+
+```python notest
+from groundlight import ExperimentalApi
+gl = ExperimentalApi()
+
+detector = gl.get_detector_by_name("dog-detector")
+
+# highlight-start
+# Detect dogs in an image
+image_query = gl.submit_image_query(detector, "path/to/image.jpg")
+# highlight-end
+
+print(f"Label: {image_query.result.label}")
+print(f"Confidence: {image_query.result.confidence}")
+print(f"Bounding Boxes: {image_query.rois}")
+```
+
+For bounding box detectors, the `label` attribute of the result object will be one of:
+- `NO_OBJECTS`: No objects of the specified class were detected in the image
+- `BOUNDING_BOX`: Objects were detected and bounding boxes are available in `image_query.rois`
+- `GREATER_THAN_MAX`: More objects were detected than the `max_num_bboxes` limit
+- `UNCLEAR`: The result was unclear
+
+The `rois` (regions of interest) attribute contains the list of bounding boxes, each with:
+- `geometry`: Bounding box coordinates (`left`, `top`, `right`, `bottom`) as values between 0 and 1
+- `label`: The class name of the detected object
+- `score`: Confidence score for this specific object
+
+<!-- TODO: display an example image with bounding boxes -->
+
+:::tip Drawing Bounding Boxes
+You can visualize the bounding boxes returned by bounding box detectors using a library like OpenCV. Here's an example of how to draw bounding boxes on an image:
+
+```python notest
+import cv2
+import numpy as np
+
+def draw_bounding_boxes(image_path, rois):
+    """
+    Draw bounding boxes on an image based on ROIs returned from a bounding box detector.
+
+    Args:
+        image_path: Path to the image file
+        rois: List of ROI objects returned from image_query.rois
+    """
+    image = cv2.imread(image_path)
+    if image is None:
+        raise ValueError(f"Could not read image from {image_path}")
+    height, width = image.shape[:2]
+
+    # Draw bounding boxes
+    for roi in rois:
+        x1 = int(roi.geometry.left * width)
+        y1 = int(roi.geometry.top * height)
+        x2 = int(roi.geometry.right * width)
+        y2 = int(roi.geometry.bottom * height)
+        cv2.rectangle(image, (x1, y1), (x2, y2), (0, 255, 0), 2)
+        label_text = f"{roi.label}: {roi.score:.2f}"
+        cv2.putText(image, label_text, (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)
+
+    # Display the image
+    cv2.imshow("Image with Bounding Boxes", image)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+
+# Example usage:
+# image_query = gl.submit_image_query(detector, "path/to/image.jpg")
+# draw_bounding_boxes("path/to/image.jpg", image_query.rois)
+```
+:::
+
+## Add a Label to a Bounding Box Detector
+
+The Groundlight API allows you to add labels to image queries, including Region of Interest (ROI) data.
+When adding a label to a bounding box detector, you must include the ROIs that correspond to the objects in the image.
+
+```python notest
+from groundlight import ExperimentalApi
+gl = ExperimentalApi()
+
+# highlight-start
+# Add a bounding box label with corresponding ROIs to the image query from the previous example.
+#   ROIs are specified as (left, top) and (right, bottom) coordinates, with values
+#   between 0 and 1 representing the percentage of the image width and height.
+roi1 = gl.create_roi("dog", (0.1, 0.2), (0.3, 0.4))
+roi2 = gl.create_roi("dog", (0.5, 0.3), (0.7, 0.6))
+rois = [roi1, roi2]
+gl.add_label(image_query, label="BOUNDING_BOX", rois=rois)
+# highlight-end
+```
+
+Valid label values for bounding box detectors are:
+- `"NO_OBJECTS"`: Use when there are no objects of the target class in the image (no ROIs needed)
+- `"BOUNDING_BOX"`: Use when objects are present and you are providing ROIs
+- `"GREATER_THAN_MAX"`: Use when there are more objects than `max_num_bboxes`
+- `"UNCLEAR"`: Use when the image is unclear or the answer cannot be determined

docs/docs/answer-modes/answer-modes.md

@@ -6,6 +6,5 @@ Groundlight offers several detector modalities to suit different computer vision
 - **[Binary Detectors](1-binary-detectors.md)**: Learn how to create detectors that answer yes/no questions about images.
 - **[Multiple Choice (Choose One) Detectors](2-multi-choice-detectors.md)**: Create detectors that select one answer from a predefined list of options.
 - **[Count Detectors](3-counting-detectors.md)**: Use detectors to count the number of objects present in an image - and return bounding boxes around the counted objects.
-<!-- 4. [Text Recognition Detectors](4-text-recognition-detectors.md) -->
-
-<!-- TODO: object detection modes -->
+- **[Bounding Box Detectors](4-bounding-box-detectors.md)**: Detectors to identify and localize objects in an image.
+<!-- 5. [Text Recognition Detectors](4-text-recognition-detectors.md) -->

pyproject.toml

@@ -9,7 +9,7 @@ packages = [
     {include = "**/*.py", from = "src"},
 ]
 readme = "README.md"
-version = "0.23.3"
+version = "0.23.4"
 
 [tool.poetry.dependencies]
 # For certifi, use ">=" instead of "^" since it upgrades its "major version" every year, not really following semver

src/groundlight/client.py

@@ -1193,7 +1193,7 @@ def add_label(
         Provide a new label (annotation) for an image query. This is used to provide ground-truth labels
         for training detectors, or to correct the results of detectors.
 
-        **Example usage**::
+        **Example usage for binary detectors**::
 
             gl = Groundlight()
 
@@ -1208,12 +1208,15 @@ def add_label(
             rois = [ROI(x=100, y=100, width=50, height=50)]
             gl.add_label(image_query, "YES", rois=rois)
 
+        Examples for other answer modes can be found in the documentation for each of the modes.
+
         :param image_query: Either an ImageQuery object (returned from methods like
                           `ask_ml`) or an image query ID string starting with "iq_".
 
         :param label: The label value to assign, typically "YES" or "NO" for binary
                      classification detectors. For multi-class detectors, use one of
-                     the defined class names.
+                     the defined class names. See answer mode documentation for all
+                     possible label options for all modes.
 
         :param rois: Optional list of ROI objects defining regions of interest in the
                     image. Each ROI specifies a bounding box with x, y coordinates

test/unit/test_experimental.py

@@ -103,12 +103,6 @@ def test_text_recognition_detector(gl_experimental: ExperimentalApi):
     assert mc_iq.result.text is not None
 
 
-@pytest.mark.skip(
-    reason=(
-        "General users currently currently can't use bounding box detectors. If you have questions, reach out"
-        " to Groundlight support, or upgrade your plan."
-    )
-)
 def test_bounding_box_detector(gl_experimental: ExperimentalApi):
     """
     Verify that we can create and submit to a bounding box detector
@@ -123,12 +117,6 @@ def test_bounding_box_detector(gl_experimental: ExperimentalApi):
     assert bbox_iq.rois is not None
 
 
-@pytest.mark.skip(
-    reason=(
-        "General users currently currently can't use bounding box detectors. If you have questions, reach out"
-        " to Groundlight support, or upgrade your plan."
-    )
-)
 def test_bounding_box_detector_async(gl_experimental: ExperimentalApi):
     """
     Verify that we can create and submit to a bounding box detector with ask_async

test/unit/test_labels.py

@@ -66,6 +66,24 @@ def test_multiclass_labels(gl_experimental: ExperimentalApi):
         gl_experimental.add_label(iq1, "MAYBE")
 
 
+def test_bounding_box_labels(gl_experimental: ExperimentalApi):
+    name = f"Test bounding box labels{datetime.utcnow()}"
+    det = gl_experimental.create_bounding_box_detector(name, "test_query", "test_class")
+    iq1 = gl_experimental.submit_image_query(det, "test/assets/cat.jpeg")
+    gl_experimental.add_label(iq1, "NO_OBJECTS")
+    iq1 = gl_experimental.get_image_query(iq1.id)
+    assert iq1.result.label == "NO_OBJECTS"
+    gl_experimental.add_label(
+        iq1,
+        "BOUNDING_BOX",
+        rois=[gl_experimental.create_roi(label="test_class", top_left=(0.1, 0.1), bottom_right=(0.6, 0.6))],
+    )
+    iq1 = gl_experimental.get_image_query(iq1.id)
+    assert iq1.result.label == "BOUNDING_BOX"
+    with pytest.raises(ApiException) as _:
+        gl_experimental.add_label(iq1, "MAYBE")
+
+
 def test_text_recognition_labels(gl_experimental: ExperimentalApi):
     name = f"Test text recognition labels{datetime.utcnow()}"
     det = gl_experimental.create_text_recognition_detector(name, "test_query")