From 34f2905c5777121cbd62de8c19377f9612d264b9 Mon Sep 17 00:00:00 2001
From: Shoumik Sharar Chowdhury <shoumikchow@gmail.com>
Date: Fri, 27 Jun 2025 01:50:27 -0400
Subject: [PATCH] docs: enhance documentation with quick start guide, usage
 examples, and troubleshooting tips

---
 docs/index.rst | 30 ++++++++++++++++
 docs/usage.rst | 96 ++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 124 insertions(+), 2 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index f60732e..548d4a4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,29 @@ The package is organized into several modules for different visualization needs:
 * **Label Drawing**: Functions for adding text labels to boxes
 * **Special Labels**: T-shaped and flag-style label visualizations
 
+Quick Start
+----------
+
+Get started with bbox-visualizer in just a few lines:
+
+.. code-block:: python
+
+    import bbox_visualizer as bbv
+    import cv2
+    import numpy as np
+
+    # Create a sample image
+    image = np.ones((400, 600, 3), dtype=np.uint8) * 255
+    
+    # Draw a bounding box with label
+    bbox = (100, 100, 300, 200)
+    image = bbv.draw_rectangle(image, bbox, bbox_color=(0, 255, 0))
+    image = bbv.add_label(image, "Object", bbox)
+    
+    # Display the result
+    cv2.imshow('Result', image)
+    cv2.waitKey(0)
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -16,6 +39,13 @@ The package is organized into several modules for different visualization needs:
    usage
    api
 
+Examples
+--------
+
+Check out the Jupyter notebook examples in the `examples/` directory:
+* `single_object_example.ipynb` - Basic usage with single objects
+* `multiple_objects_example.ipynb` - Working with multiple bounding boxes
+
 Indices and tables
 ==================
 * :ref:`genindex`
diff --git a/docs/usage.rst b/docs/usage.rst
index 6c95aec..b44c592 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -41,7 +41,7 @@ Basic rectangle drawing:
 .. code-block:: python
 
     # Single rectangle
-    bbox = (100, 100, 200, 200)
+    bbox = (100, 100, 200, 200)  # (x1, y1, x2, y2) format
     image = bbv.draw_rectangle(image, bbox)
 
     # Multiple rectangles
@@ -136,4 +136,96 @@ All functions support customization of colors and styles:
     # Display the result
     cv2.imshow('Image with bounding boxes', image)
     cv2.waitKey(0)
-    cv2.destroyAllWindows() 
\ No newline at end of file
+    cv2.destroyAllWindows()
+
+Common Use Cases
+--------------
+
+Object Detection Visualization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import bbox_visualizer as bbv
+    import cv2
+    import numpy as np
+
+    # Simulate object detection results
+    detections = [
+        {"bbox": (50, 50, 150, 150), "label": "Person", "confidence": 0.95},
+        {"bbox": (200, 100, 300, 200), "label": "Car", "confidence": 0.87},
+        {"bbox": (350, 150, 450, 250), "label": "Dog", "confidence": 0.92}
+    ]
+
+    # Load image
+    image = cv2.imread('detection_image.jpg')
+    
+    # Visualize each detection
+    for det in detections:
+        bbox = det["bbox"]
+        label = f"{det['label']} ({det['confidence']:.2f})"
+        
+        # Draw rectangle and label
+        image = bbv.draw_rectangle(image, bbox, bbox_color=(0, 255, 0))
+        image = bbv.add_label(image, label, bbox)
+
+Multiple Object Classes
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # Define color scheme for different classes
+    class_colors = {
+        "person": (0, 255, 0),    # Green
+        "car": (255, 0, 0),       # Blue
+        "dog": (0, 0, 255),       # Red
+        "cat": (255, 255, 0)      # Cyan
+    }
+
+    # Process detections with class-specific colors
+    for det in detections:
+        bbox = det["bbox"]
+        label = det["label"]
+        color = class_colors.get(label.lower(), (128, 128, 128))
+        
+        image = bbv.draw_rectangle(image, bbox, bbox_color=color)
+        image = bbv.add_label(image, label, bbox)
+
+Troubleshooting
+-------------
+
+Common Issues
+~~~~~~~~~~~~
+
+**Bounding box format errors**
+    Make sure your bounding boxes are in (x1, y1, x2, y2) format where:
+    - x1, y1: top-left corner coordinates
+    - x2, y2: bottom-right corner coordinates
+
+**Color format issues**
+    OpenCV uses BGR color format, not RGB. For example:
+    - Red: (0, 0, 255) in BGR
+    - Green: (0, 255, 0) in BGR
+    - Blue: (255, 0, 0) in BGR
+
+**Image not displaying**
+    Ensure you have a display environment or use cv2.imwrite() to save the image:
+    
+    .. code-block:: python
+    
+        cv2.imwrite('output.jpg', image)
+
+Performance Tips
+~~~~~~~~~~~~~~
+
+- For multiple objects, use the batch functions (e.g., `draw_multiple_rectangles`) instead of loops
+- Pre-allocate image arrays when possible
+- Use appropriate image formats (uint8 for most cases)
+- Consider downsampling large images for faster processing
+
+Getting Help
+-----------
+
+- Check the `examples/` directory for complete working examples
+- Review the API documentation for detailed parameter descriptions
+- Open an issue on GitHub for bugs or feature requests 
\ No newline at end of file