> For the complete documentation index, see [llms.txt](https://docs.degirum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.degirum.com/degirum-tools/support/ui_support.md).

# UI Support

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

{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}

## UI Support Module Overview <a href="#ui-support-module-overview" id="ui-support-module-overview"></a>

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

## Functions <a href="#functions" id="functions"></a>

#### deduce\_text\_color(bg\_color) <a href="#deduce_text_color" id="deduce_text_color"></a>

`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) <a href="#color_complement" id="color_complement"></a>

`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) <a href="#rgb_to_bgr" id="rgb_to_bgr"></a>

`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, ...) <a href="#ipython_display" id="ipython_display"></a>

`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, ...) <a href="#put_text" id="put_text"></a>

`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, ...) <a href="#stack_images" id="stack_images"></a>

`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. |

## Classes <a href="#classes" id="classes"></a>

## CornerPosition <a href="#cornerposition" id="cornerposition"></a>

`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 <a href="#fpsmeter" id="fpsmeter"></a>

`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. |

### FPSMeter Methods <a href="#fpsmeter-methods" id="fpsmeter-methods"></a>

#### \_\_init\_\_(avg\_len=100) <a href="#init" id="init"></a>

`__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 <a href="#fps" id="fps"></a>

`fps()`

Return current average FPS.

#### record <a href="#record" id="record"></a>

`record()`

Record timestamp and update average duration.

Returns current average FPS.

#### reset <a href="#reset" id="reset"></a>

`reset()`

Reset accumulators.

## Display <a href="#display" id="display"></a>

`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 <a href="#attributes" id="attributes"></a>

#### window\_name: str <a href="#window_name-str" id="window_name-str"></a>

`window_name: str`

`property`

Get the window name.

Returns:

| Type  | Description                 |
| ----- | --------------------------- |
| `str` | Name of the display window. |

### Display Methods <a href="#display-methods" id="display-methods"></a>

#### \_\_init\_\_(capt='', ...) <a href="#init" id="init"></a>

`__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, ...) <a href="#show" id="show"></a>

`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) <a href="#show_image" id="show_image"></a>

`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 <a href="#timer" id="timer"></a>

`Timer`

Simple timer class.

### Timer Methods <a href="#timer-methods" id="timer-methods"></a>

#### \_\_call\_\_ <a href="#call" id="call"></a>

`__call__()`

Get elapsed time since timer creation.

Returns:

| Type    | Description                                        |
| ------- | -------------------------------------------------- |
| `float` | Time elapsed in seconds since object construction. |

#### \_\_init\_\_ <a href="#init" id="init"></a>

`__init__()`

Constructor. Records start time.

## Progress <a href="#progress" id="progress"></a>

`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 <a href="#attributes" id="attributes"></a>

#### step\_range: Optional\[tuple] <a href="#step_range-optionaltuple" id="step_range-optionaltuple"></a>

`step_range: Optional[tuple]`

`property`

Get start-end step range (if defined).

### Progress Methods <a href="#progress-methods" id="progress-methods"></a>

#### \_\_init\_\_(last\_step=None, ...) <a href="#init" id="init"></a>

`__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 <a href="#reset" id="reset"></a>

`reset()`

Reset the progress bar to its initial state.

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

#### step(steps=1, ...) <a href="#step" id="step"></a>

`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 <a href="#stdoutredirector" id="stdoutredirector"></a>

`stdoutRedirector`

Redirect stdout to another stream.

### stdoutRedirector Methods <a href="#stdoutredirector-methods" id="stdoutredirector-methods"></a>

#### \_\_init\_\_(stream=None) <a href="#init" id="init"></a>

`__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`  |