UI Support

DeGirum Tools API Reference Guide. Lightweight display, FPS meter, timer and image‑stack tools.

This API Reference is based on DeGirum Tools version 0.18.0.

UI Support Module Overview

This module provides a comprehensive set of utilities for user interface operations, including image display, text rendering, progress tracking, and performance monitoring. It supports both traditional GUI environments and Jupyter notebooks.

Key Features

• Image Display: Show images in GUI windows or Jupyter notebooks

• Text Rendering: Draw text with customizable fonts, colors, and positions

• Progress Tracking: Display progress bars with speed and percentage

• Performance Monitoring: Measure and display FPS

• Environment Detection: Auto-detect and adapt to different display environments

• Color Utilities: Convert between color spaces and compute complementary colors

Typical Usage

1. Use Display class for showing images in any environment

2. Draw text on images with put_text()

3. Track progress with Progress class

4. Monitor performance with FPSMeter

5. Stack images with stack_images()

Integration Notes

• Works in both GUI and Jupyter notebook environments

• Automatically detects and adapts to the display environment

• Supports both OpenCV and PIL image formats

• Handles video files in Jupyter notebooks

• Provides consistent interface across different platforms

Key Classes

• Display: Main class for showing images and videos

• Progress: Progress bar with speed and percentage display

• FPSMeter: Frames per second measurement

• Timer: Simple timing utility

• stdoutRedirector: Context manager for redirecting stdout

Configuration Options

• Font settings (face, scale, thickness)

• Color schemes (RGB/BGR)

• Progress bar appearance

• Display window properties

Classes

CornerPosition

CornerPosition

Bases: Enum

Enumeration of possible corner positions for text placement.

This enum defines the possible positions where text can be placed relative to a reference point in an image. The AUTO option will automatically choose the best corner based on the reference point's position.

Attributes:

Name	Type	Description
AUTO	int	Automatically choose the best corner position.
TOP_LEFT	int	Place text at the top-left corner.
TOP_RIGHT	int	Place text at the top-right corner.
BOTTOM_LEFT	int	Place text at the bottom-left corner.
BOTTOM_RIGHT	int	Place text at the bottom-right corner.

FPSMeter

FPSMeter

Frame rate measurement utility.

This class provides functionality to measure and track frames per second (FPS) over a configurable window of time. It's useful for monitoring performance in video processing and real-time applications.

Attributes:

Name	Type	Description
avg_len	int	Number of samples to use for FPS calculation.

Functions

__init__(avg_len=100)

__init__(avg_len=100)

Constructor.

Parameters:

Name	Type	Description	Default
avg_len	int	Number of samples to use for FPS calculation. Defaults to 100.	100

fps

fps()

Return current average FPS.

record

record()

Record timestamp and update average duration.

Returns current average FPS.

reset

reset()

Reset accumulators.

Display

Display

Display manager for showing images and videos in various environments.

This class provides a unified interface for displaying images and videos in both GUI windows and Jupyter notebooks. It automatically detects the display environment and adapts its behavior accordingly.

Attributes:

Name	Type	Description
window_name	str	Name of the display window in GUI mode.
show_fps	bool	Whether to show FPS counter on displayed images.
width	Optional[int]	Target width for displayed images.
height	Optional[int]	Target height for displayed images.

Attributes

window_name

window_name

property

Get the window name.

Returns:

Type	Description
str	Name of the display window.

Functions

__init__(capt='', ...)

__init__(capt='<image>', show_fps=True, w=None, h=None)

Constructor.

Parameters:

Name	Type	Description	Default
capt	str	Window title. Defaults to "".	'<image>'
show_fps	bool	Whether to show FPS counter. Defaults to True.	True
w	Optional[int]	Initial window width in pixels; None for autoscale. Defaults to None.	None
h	Optional[int]	Initial window height in pixels; None for autoscale. Defaults to None.	None

Raises:

Type	Description
Exception	If window title is empty.

show(img, ...)

show(img, waitkey_delay=1)

Show image or model result.

Parameters:

Name	Type	Description	Default
img	Any	Image to display. Can be a numpy array with valid OpenCV image, PIL image, or model result object.	required
waitkey_delay	int	Delay in ms for waitKey() call. Use 0 to show still images, use 1 for streaming video. Defaults to 1.	1

show_image(img)

show_image(img)

Show still image or model result.

Parameters:

Name	Type	Description	Default
img	Any	Image to display. Can be a numpy array with valid OpenCV image, PIL image, or model result object.	required

Timer

Timer

Simple timer class.

Functions

__call__

__call__()

Get elapsed time since timer creation.

Returns:

Type	Description
float	Time elapsed in seconds since object construction.

__init__

__init__()

Constructor. Records start time.

Progress

Progress

Progress bar with speed and percentage display.

This class provides a progress bar that shows completion percentage, speed, and optional messages. It works in both GUI and Jupyter notebook environments.

Attributes:

Name	Type	Description
last_step	Optional[int]	Total number of steps (None for indeterminate).
start_step	int	Starting step number.
bar_len	int	Length of the progress bar in characters.
speed_units	str	Units to display for speed (e.g., "FPS", "items/s").

Attributes

step_range

step_range

property

Get start-end step range (if defined).

Functions

__init__(last_step=None, ...)

__init__(last_step=None, *, start_step=0, bar_len=15, speed_units='FPS')

Constructor.

Parameters:

Name	Type	Description	Default
last_step	Optional[int]	Total number of steps (None for indeterminate). Defaults to None.	None
start_step	int	Starting step number. Defaults to 0.	0
bar_len	int	Progress bar length in symbols. Defaults to 15.	15
speed_units	str	Units to display for speed (e.g., "FPS", "items/s"). Defaults to "FPS".	'FPS'

reset

reset()

Reset the progress bar to its initial state.

This method resets the current step, message, and timing information.

step(steps=1, ...)

step(steps=1, *, message=None)

Update progress by given number of steps.

Parameters:

Name	Type	Description	Default
steps	int	Number of steps to advance.	1
message	Optional[str]	Optional message to display.	None

stdoutRedirector

stdoutRedirector

Redirect stdout to another stream.

Functions

__init__(stream=None)

__init__(stream=None)

Constructor.

Parameters:

Name	Type	Description	Default
stream	Optional[str]	Output stream to redirect to; None to redirect to null device. Defaults to None.	None

Functions

deduce_text_color(bg_color)

deduce_text_color(bg_color)

Return a readable text color.

Chooses black or white based on the luminance of bg_color so that text remains legible.

Parameters:

Name	Type	Description	Default
bg_color	tuple	Background color as an (R, G, B) tuple.	required

Returns:

Type	Description
Tuple[int, int, int]	(R, G, B) value for black or white text.

color_complement(color)

color_complement(color)

Return the complement of an RGB color.

Parameters:

Name	Type	Description	Default
color	tuple | list	Color specified as (R, G, B).	required

Returns:

Type	Description
Tuple[int, int, int]	Complementary color in (R, G, B) format.

rgb_to_bgr(color)

rgb_to_bgr(color)

Convert an RGB color tuple to BGR.

Parameters:

Name	Type	Description	Default
color	tuple	Color in (R, G, B) format.	required

Returns:

Type	Description
Tuple[int, int, int]	Color in (B, R, G) order for OpenCV functions.

ipython_display(obj, ...)

ipython_display(obj, clear=False, display_id=None)

Display an object in IPython notebooks.

Parameters:

Name	Type	Description	Default
obj	Any	Object to display. Supported types are PIL.Image, numpy.ndarray images, or a string path/URL to an image or video.	required
clear	bool	Whether to clear the previous output. Defaults to False.	False
display_id	Optional[str]	Custom display ID to update an existing output.	None

Raises:

Type	Description
Exception	If the object type is unsupported.

put_text(image, ...)

put_text(image, label, corner_xy, *, corner_position=CornerPosition.TOP_LEFT, font_color, bg_color=None, font_face=cv2.FONT_HERSHEY_PLAIN, font_scale=1, font_thickness=1, line_spacing=1)

Draw text on an image with customizable appearance and positioning.

This function draws text on an OpenCV image with support for multi-line text, background colors, and automatic positioning. The text can be placed relative to any corner of the image, and will automatically adjust to stay within image boundaries.

Parameters:

Name	Type	Description	Default
image	ndarray	Input image in OpenCV format (BGR).	required
label	str	Text to draw. Can contain newlines for multi-line text.	required
corner_xy	tuple	Base coordinates (x, y) for text placement.	required
corner_position	CornerPosition	Position of text relative to corner_xy. Defaults to TOP_LEFT.	TOP_LEFT
font_color	tuple	Text color in RGB format.	required
bg_color	Optional[tuple]	Background color in RGB format. If None, no background is drawn. Defaults to None.	None
font_face	int	OpenCV font face. Defaults to FONT_HERSHEY_PLAIN.	FONT_HERSHEY_PLAIN
font_scale	float	Font size multiplier. Defaults to 1.	1
font_thickness	int	Font thickness in pixels. Defaults to 1.	1
line_spacing	float	Multiplier for line spacing. Defaults to 1.	1

Returns:

Type	Description
ndarray	Image with text drawn on it.

stack_images(image1, ...)

stack_images(image1, image2, dimension='horizontal', downscale=None, labels=None, font_color=(255, 255, 255))

Stack two images either horizontally or vertically.

Parameters:

Name	Type	Description	Default
image1	ndarray | Image	First image.	required
image2	ndarray | Image	Second image.	required
dimension	str	"horizontal" or "vertical". Defaults to "horizontal".	'horizontal'
downscale	Optional[float]	Scaling factor for both images if less than 1.0.	None
labels	Optional[list]	Optional text labels for image1 and image2.	None
font_color	tuple	RGB color for labels. Defaults to white.	(255, 255, 255)

Returns:

Type	Description
Union[ndarray, Image]	Combined image with optional resizing and labels.