Visual Debugger for Computer Vision

A visual debugging toolkit for computer vision and image processing workflows. Annotate, visualize, and debug your image processing pipelines with ease.

🚀 Features

Features

• Multiple Annotation Types: Support for a variety of annotations such as points, labeled points, rectangles, circles, and orientation vectors based on pitch, yaw, and roll.
• Image Concatenation: Capability to concatenate multiple debugged images into a single composite image, facilitating easier visualization of sequential image processing steps.
• Dynamic Image Handling: Handles a wide range of image inputs including file paths, in-memory image arrays, base64 encoded images, and images from web links, integrating seamlessly with OpenCV.
• Customizable Debugging: Debugging can be turned on or off, and the module supports generating merged debug images for a sequence of operations.

Annotation Types

Category	Annotation Class	Description	Key Features
📍 Points	PointAnnotation	Single point marker	Customizable size and color
	LabeledPointAnnotation	Point with text label	Font size/thickness control
	PointsAnnotation	Multiple points	Uniform styling for all points
	LabeledPointsAnnotation	Multiple labeled points	Individual labels per point
🔷 Shapes	CircleAnnotation	Circle shape	Outline or filled
	LabeledCircleAnnotation	Circle with label	Text positioning options
	RectangleAnnotation	Rectangle shape	Corner or xywh specification
	AlphaRectangleAnnotation	Semi-transparent rectangle	Alpha blending (0.0-1.0)
📏 Lines	LineAnnotation	Straight line	Optional arrow heads
	LabeledLineAnnotation	Line with label	Midpoint text placement
	PolylineAnnotation	Connected segments	Open or closed path
📝 Text	TextAnnotation	Standalone text	Optional background, padding
📦 Complex	BoundingBoxAnnotation	Detection box	Label with background
	MaskAnnotation	Segmentation mask	Multiple colormaps
	OrientationAnnotation	3D axes visualization	Pitch, yaw, roll display
	InfoPanelAnnotation	Dashboard overlay	Composite of basic annotations

📊 Info Panel System

Flexible dashboard overlays with extensive customization:

• Positioning: 9 preset positions or custom coordinates
• Styling: Colors, borders, padding, fonts
• Content: Key-value pairs, separators, progress bars, tables
• Optimization: Optional title for space saving
• Themes: Dark, light, minimal, or custom styles

🖼️ Image Composition

Combine multiple images with:

• Horizontal/vertical concatenation
• Grid layouts with automatic sizing
• Before/after comparisons
• Customizable borders and labels

📦 Installation

pip install visual_debugger

🎯 Quick Start

Basic Usage

fromvisual_debuggerimportVisualDebuggerfromvisual_debugger.annotationsimport*# Initialize debuggervd=VisualDebugger(
tag="my_project",
debug_folder_path="./debug_output",
active=True,
output='save'# 'save', 'return', or 'both'
)
# Load your imageimportcv2img=cv2.imread("image.jpg")
# Create annotationsannotations= [
point(100, 200, color=(255, 0, 0), size=10),
circle(300, 300, 50, color=(0, 255, 0)),
bbox(50, 50, 200, 150, label="Person 95%"),
text("Debug Info", 10, 30, font_scale=1.0)
]
# Apply annotationsresult=vd.visual_debug(img, annotations, process_step="detection")

Using Info Panels

fromvisual_debugger.info_panelimportInfoPanel, PanelPosition# Create info panel (title is optional)panel=InfoPanel(
position=PanelPosition.TOP_LEFT,
title="System Status"# Can be None or omitted for compact display
)
# Or create a compact panel without title (saves space)panel_compact=InfoPanel(position=PanelPosition.TOP_RIGHT)
# Custom stylingfromvisual_debugger.info_panelimportPanelStylecustom_style=PanelStyle(
background_color=(40, 20, 80), # Dark bluebackground_alpha=0.7, # 70% opacity (30% transparent)text_color=(200, 220, 255), # Light blue texttitle_color=(255, 200, 100), # Orange titleborder_color=(100, 150, 255), # Blue borderborder_thickness=3,
padding=20,
font_scale=0.6,
show_background=True# Set False for no background
)
styled_panel=InfoPanel(
position=PanelPosition.BOTTOM_LEFT,
title="Custom Theme",
style=custom_style
)
# Add informationpanel.add("FPS", "30.0")
panel.add("Objects", "5")
panel.add_separator()
panel.add_progress("Processing", 0.75)
# Use with VisualDebugger - just pass the panel directly!result=vd.visual_debug(img, panel) # Simple and clean!# Or mix with other annotationsresult=vd.visual_debug(img, [
panel,
point(100, 100),
circle(200, 200, 50)
])

Image Composition

fromvisual_debugger.compositionimportImageCompositor, LayoutDirectioncompositor=ImageCompositor()
# Create image gridgrid=compositor.create_grid(
images=[img1, img2, img3, img4],
cols=2,
labels=["Step 1", "Step 2", "Step 3", "Step 4"]
)
# Create before/after comparisoncomparison=compositor.create_comparison(
before=original_img,
after=processed_img,
before_label="Original",
after_label="Enhanced"
)

🔧 Advanced Features

Type-Specific Annotations

Each annotation type is a dedicated class with only relevant parameters:

# No more generic dictionaries or enums!circle_ann=CircleAnnotation(
center=(100, 100),
radius=30,
color=(255, 0, 0),
thickness=2,
filled=False
)
# Bounding boxes with labelsbbox_ann=BoundingBoxAnnotation(
bbox=(x, y, width, height),
label="Car 92%", # Include any info in the labelcolor=(0, 255, 0)
)

Visitor Pattern Processing

The system uses a clean visitor pattern for extensibility:

classCustomProcessor(AnnotationProcessor):
defrender_custom(self, annotation):
# Your custom rendering logicpass

Boundary Detection

All annotations can calculate their visual footprint:

ann=CircleAnnotation(center=(100, 100), radius=30)
x_min, y_min, x_max, y_max=ann.get_bounding_box()
# Returns: (69, 69, 131, 131) accounting for thickness

Factory Functions

Convenient factory functions for quick annotation creation:

# Instead of: PointAnnotation(position=(100, 200), color=(255, 0, 0))# You can use: point(100, 200, color=(255, 0, 0))annotations= [
point(100, 200),
labeled_point(200, 200, "Target"),
circle(300, 300, 50),
rectangle(400, 400, 100, 100),
line(0, 0, 500, 500, arrow=True),
text("Status: OK", 10, 30),
bbox(50, 50, 200, 150, label="Detection")
]

🏗️ Architecture

visual_debugger/
├── visual_debugger.py # Main orchestrator
├── annotations.py # Type-specific annotation classes
├── annotation_processor.py # Visitor pattern renderer
├── info_panel.py # Dashboard overlay system
├── composition.py # Image layout and grids
├── image_processor.py # Core image operations
└── utils.py # Utilities and helpers

🧪 Testing

Comprehensive smoke tests are included:

# Run all smoke tests
python -m smoke_tests.test_01_type_specific_annotations
python -m smoke_tests.test_02_annotation_processor
python -m smoke_tests.test_03_image_composition
python -m smoke_tests.test_04_info_panel
python -m smoke_tests.test_05_visual_debugger_integration
# Visual showcase with sample image
python -m smoke_tests.test_08_visual_showcase

📊 Performance

• Optimized for real-time visualization
• Efficient numpy operations for masks
• Lazy evaluation where possible
• Minimal memory footprint

🔄 Migration from Legacy API

If upgrading from the enum-based API:

# Old style (deprecated)fromvisual_debuggerimportAnnotation, AnnotationTypeann=Annotation(type=AnnotationType.POINT, coordinates=(100, 100))
# New style (recommended)fromvisual_debugger.annotationsimportPointAnnotationann=PointAnnotation(position=(100, 100))
# Or use factory functionsfromvisual_debugger.annotationsimportpointann=point(100, 100)

🤝 Contributing

We welcome contributions! Areas of interest:

• New annotation types
• Performance optimizations
• Additional colormaps for masks
• Export formats (video, GIF)

📄 License

MIT License - see LICENSE file for details

🌟 Examples Gallery

Check out smoke_tests/test_08_outputs/ after running the visual showcase for examples of all annotation types in action.

💡 Tips & Best Practices

1. Use factory functions for cleaner code
2. Leverage type hints - all classes are fully typed
3. Check boundaries with get_bounding_box() before rendering
4. Compose views for side-by-side comparisons
5. Add info panels for professional debugging output
6. Use process steps for organized output naming

🔗 Related Projects

• OpenCV: Core image processing
• NumPy: Efficient array operations
• Pillow: Additional image format support

---

Built with ❤️ for the computer vision community