ContourRenderer
===============

Smooth contour rendering using marching squares.

Provides sub-pixel accurate contour extraction and visualization
using skimage.measure.find_contours.

Classes
-------

.. py:class:: ContourRenderer

   Render segmentation contours with multiple visualization modes.
   
   Supports two outline modes:
   - **Smooth**: Marching squares (skimage.measure.find_contours) for sub-pixel
     accurate contour extraction. Shows the interpolated boundary.
   - **Pixel**: Morphological dilation-erosion for jagged outlines that show
     the actual pixel boundaries of the segmentation.
   
   Both modes have their uses:
   - Smooth: Better for seeing true boundary shape, comparing curves
   - Pixel: Shows actual voxel boundaries, important for understanding
     what the algorithm actually segmented at pixel level

   **Methods:**

   .. py:method:: __init__()

      Initialize renderer.

   .. py:method:: get_morphological_outline()

      Get pixel-level outline using morphological operations.

   .. py:method:: find_contours()

      Find smooth sub-pixel contours using marching squares.

   .. py:method:: draw_contours()

      Draw smooth contour polylines on RGB image.

   .. py:method:: create_comparison_image()

      Create comparison image with both segmentations as outlines.

   .. py:method:: create_error_image()

      Create error analysis image with TP/FP/FN coloring.

   .. py:method:: create_combined_image()

      Create combined visualization with both contours and error regions.

   .. py:method:: clear_cache()

      Clear the contour cache.


Functions
---------

.. py:function:: get_morphological_outline()

   Get pixel-level outline using morphological operations.
   
   Creates a jagged outline that shows the actual pixel boundaries
   of the segmentation (dilation - erosion).
   
   Args:
       mask: 2D binary mask.
       iterations: Thickness of outline in pixels.
   
   Returns:
       Binary mask of outline pixels.

.. py:function:: find_contours()

   Find smooth sub-pixel contours using marching squares.
   
   Args:
       mask: 2D binary mask (any dtype, will be converted to bool).
   
   Returns:
       List of contour arrays, each with shape (N, 2) in (row, col) format.

.. py:function:: draw_contours()

   Draw smooth contour polylines on RGB image.
   
   Args:
       rgb: RGB image (H, W, 3) as float64 or uint8.
       contours: List of contour arrays from find_contours.
       color: RGB color tuple (0-255).
       thickness: Line thickness in pixels.
   
   Returns:
       RGB image with contours drawn.

.. py:function:: create_comparison_image()

   Create comparison image with both segmentations as outlines.
   
   Args:
       image_slice: 2D grayscale image (uint8)
       trial_slice: 2D binary trial segmentation mask
       gold_slice: 2D binary gold standard mask
       trial_color: RGB color for trial contour (default: green)
       gold_color: RGB color for gold contour (default: magenta)
       line_thickness: Contour line thickness in pixels
       mode: Outline mode - "smooth" (marching squares) or "pixel" (morphological)
   
   Returns:
       RGB image as uint8 array (H, W, 3)

.. py:function:: create_error_image()

   Create error analysis image with TP/FP/FN coloring.
   
   Color coding (assuming gold standard is truth):
   - Green: True Positive (both agree)
   - Red: False Positive (trial only - over-segmentation)
   - Blue: False Negative (gold only - under-segmentation)
   
   Args:
       image_slice: 2D grayscale image (uint8)
       trial_slice: 2D binary trial segmentation mask
       gold_slice: 2D binary gold standard mask
       tp_color: RGB for true positives (agreement)
       fp_color: RGB for false positives (over-segmentation)
       fn_color: RGB for false negatives (under-segmentation)
       alpha: Opacity of overlay
   
   Returns:
       RGB image as uint8 array (H, W, 3)

.. py:function:: create_combined_image()

   Create combined visualization with both contours and error regions.
   
   Args:
       image_slice: 2D grayscale image (uint8)
       trial_slice: 2D binary trial segmentation mask
       gold_slice: 2D binary gold standard mask
       show_contours: Whether to draw smooth contours
       show_error_regions: Whether to show TP/FP/FN regions
       error_alpha: Opacity of error regions
   
   Returns:
       RGB image as uint8 array (H, W, 3)

.. py:function:: clear_cache()

   Clear the contour cache.