Skip to content

[A] Add draw_detection func - #25

Merged
zephyr-sh merged 1 commit into
mainfrom
feat/add_draw_detection
Jul 8, 2025
Merged

[A] Add draw_detection func#25
zephyr-sh merged 1 commit into
mainfrom
feat/add_draw_detection

Conversation

@zephyr-sh

Copy link
Copy Markdown
Contributor

✨ Summary

This PR introduces a new utility draw_detection() to the capybara/vision/visualization/draw.py module for rendering detection results on images, along with minor cleanups and shared constant reuse.


✅ Major Changes

1. New API: draw_detection()

Adds a high-level utility to draw labeled detection boxes (with optional confidence score) onto images.

Features:

  • Box rendering:

    • Supports absolute and normalized box formats
    • Optional transparency via box_alpha
  • Label rendering:

    • Auto-formatted confidence score (e.g., label 92.3%)
    • Text with semi-transparent background rectangle
    • Dynamic font sizing (~10% of box height, with min cap)
  • Color selection:

    • Deterministic hashing for consistent per-class color
    • Based on golden ratio hue distribution
  • Other options:

    • Optional font_path, text_size, text_color, text_bg_alpha
    • Auto thickness scaling based on image resolution

Example usage:

draw_detection(img, box=[x1, y1, x2, y2], label="cat", score=0.923)

2. Shared Font Path Constant

  • Introduced DEFAULT_FONT_PATH as a shared constant
  • Replaced duplicated string literals with reference to the constant

3. Guard for Font Download

  • Updated logic to correctly check and download the font only if missing:

    if not (font_path := DIR / DEFAULT_FONT_PATH).exists():

🧠 Motivation

  • Previous APIs such as draw_box() and draw_text() were too low-level for rendering detection results in a single call.
  • This utility abstracts away box coordinate handling, color consistency, text layout, font sizing, and blending.
  • Provides an out-of-the-box tool to visualize detection results for debugging, demos, or evaluation.

🖼️ Visual Behavior

  • Consistent box color per label: ensures same class gets same hue
  • Readable text: white font with semi-transparent background
  • No overlap or cutoff: clamps background rectangle to image bounds
  • Sensible defaults: line thickness and font size scale with resolution

🧪 Test Coverage

This utility is self-contained and built upon existing well-tested primitives:

  • prepare_img, prepare_box
  • cv2.rectangle, ImageFont, ImageDraw

Optional follow-up PR can add unit tests using synthetic inputs to assert image output properties.


🔄 API Summary

def draw_detection(
    img: np.ndarray,
    box: _Box,
    label: str,
    score: float | None = None,
    color: tuple[int, int, int] | None = None,
    thickness: int | None = None,
    text_color: tuple[int, int, int] = (255, 255, 255),
    font_path: Union[str, Path] | None = None,
    text_size: int | None = None,
    box_alpha: float = 1.0,
    text_bg_alpha: float = 0.6,
) -> np.ndarray

✅ Checklist

  • draw_detection() implemented and documented
  • Color hashing via label for class-consistent visuals
  • Shared font path constant extracted
  • Compatible with normalized boxes
  • Layout clamped to avoid text overflow

@zephyr-sh
zephyr-sh requested a review from kunkunlin1221 July 8, 2025 02:34
@zephyr-sh zephyr-sh self-assigned this Jul 8, 2025
@zephyr-sh
zephyr-sh merged commit f555e29 into main Jul 8, 2025
2 of 3 checks passed
@zephyr-sh
zephyr-sh deleted the feat/add_draw_detection branch July 8, 2025 04:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants