Utility Classes and Functions
BoundingBox
BoundingBox for displaying the height, width and position of objects identified on the screen.
Attributes:
| Name | Type | Description |
|---|---|---|
center |
2D pixel coordinates of the bounding box. |
|
box |
tuple[int, int, int, int]
|
Stores x, y, height, and width. |
width |
int
|
Width of bounding box. |
height |
int
|
Height of bounding box. |
size |
tuple[int, int]
|
Tuple containing width and height. |
origin |
tuple[int, int]
|
Top left corner of bounding box. |
opposite |
tuple[int, int]
|
Bottom right corner of bounding box. |
__init__
__init__(top_left_corner: tuple[int, int], bottom_right_corner: tuple[int, int])Initialize bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
top_left_corner
|
tuple[int, int]
|
|
required |
bottom_right_corner
|
tuple[int, int]
|
|
required |
draw
draw(image: ndarray, color: tuple[int, int, int] = (0, 127, 0), thickness: int = 2)Draw rectangle bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Image to draw bounding box on. |
required |
color
|
tuple[int, int, int]
|
BGR color of bounding box outline. |
(0, 127, 0)
|
thickness
|
int
|
Thickness of line in pixels. |
2
|
draw_corners
draw_corners(image: ndarray, length: int = 30, thickness: int = 5, stroke: tuple[int, int, int] = (0, 255, 0))Draw corners of the bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Image to draw bounding box on. |
required |
length
|
int
|
Length of corner lines in pixels. |
30
|
thickness
|
int
|
Thickness of line in pixels. |
5
|
stroke
|
tuple[int, int, int]
|
BGR color of corner lines. |
(0, 255, 0)
|
Connection
dataclass
Stores line points, colors, and z-index when drawing them for hand connections.
Attributes:
| Name | Type | Description |
|---|---|---|
start |
tuple[int, int]
|
The start point of the line in 2D pixel space. |
end |
tuple[int, int]
|
The end point of the line in 2D pixel space. |
z |
float
|
The average z-index of the line, used for sorting the order to draw them in. |
color |
tuple[int, int, int]
|
The color of the line. |
ConnectionStyle
dataclass
Stores connection style for stroke color and outline thickness.
Attributes:
| Name | Type | Description |
|---|---|---|
stroke |
tuple[int, int, int]
|
BGR stroke color of the connections. |
thickness |
int
|
Thickness of connection in pixels. |
Landmark
dataclass
Stores landmark points, colors, and z-index when drawing them for hand connections.
Attributes:
| Name | Type | Description |
|---|---|---|
pos |
tuple[int, int]
|
The position of the landmark in 2D pixel space. |
z |
int
|
The z-index of the landmark, used for sorting the order to draw them in. |
color |
tuple[int, int, int]
|
The color of the landmark. |
LandmarkStyle
dataclass
Stores landmark style fill color, stroke color, radius, and outline thickness.
Attributes:
| Name | Type | Description |
|---|---|---|
fill |
tuple[int, int, int]
|
BGR fill color of the landmarks. |
stroke |
tuple[int, int, int]
|
BGR stroke color of the landmarks. |
radius |
int
|
Radius of landmarks in pixels. |
thickness |
int
|
Thickness of outline of landmarks in pixels. |
Skeleton
Stub for upcoming features.
circle
circle(target: ndarray, center: tuple[int, int], radius: int, fill: tuple[int, int, int] | None = (255, 255, 255), outline: tuple[int, int, int] | None = (0, 0, 0), thickness: int = 1)Draws a circle with simple parameters and default values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
Target image to draw the shape on. |
required |
center
|
tuple[int, int]
|
(x,y) coordinate of center point. |
required |
radius
|
int
|
Radius of circle. |
required |
fill
|
tuple[int, int, int] | None
|
(B, G, R) color of fill. A value of None will remove the fill altogether |
(255, 255, 255)
|
outline
|
tuple[int, int, int] | None
|
(B, G, R) color of outline. A value of None will remove the outline altogether. |
(0, 0, 0)
|
thickness
|
int
|
Thickness of outline. A value less than 1 will remove the outline altogether. |
1
|
Returns:
| Type | Description |
|---|---|
|
None |
ellipse
ellipse(target: ndarray, center: tuple[int, int], radius: int, cross_radius: int | None = None, rotation: int = 0, start_angle: int = 0, end_angle: int = 360, fill: tuple[int, int, int] | None = (255, 255, 255), outline: tuple[int, int, int] | None = (0, 0, 0), thickness: int = 1, closed: bool = True)Draws an ellipse with simple parameters and default values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
Target image to draw the shape on. |
required |
center
|
tuple[int, int]
|
(x,y) coordinate of center point. |
required |
radius
|
int
|
Main radius of the ellipse. |
required |
cross_radius
|
int | None
|
Cross radius of the ellipse. None results in a perfect circle. |
None
|
rotation
|
int
|
Rotation of ellipse in degrees. |
0
|
start_angle
|
int
|
Starting angle of arc in degrees. |
0
|
end_angle
|
int
|
Ending angle of arc in degrees. |
360
|
fill
|
tuple[int, int, int] | None
|
(B, G, R) color of fill. A value of None will remove the fill altogether |
(255, 255, 255)
|
outline
|
tuple[int, int, int] | None
|
(B, G, R) color of outline. A value of None will remove the outline altogether. |
(0, 0, 0)
|
thickness
|
int
|
Thickness of outline. A value less than 1 will remove the outline altogether. |
1
|
closed
|
bool
|
If True, draws the outline along all edges of the arc. Otherwise, only draws the rounded section. |
True
|
Returns:
| Type | Description |
|---|---|
|
None |
line
line(target: ndarray, *points: tuple[int, int] | list[tuple, tuple], color: tuple[int, int, int] = (0, 0, 0), thickness: int = 2, closed: bool = False)Draws a line with simple parameters and default values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
Target image to draw the shape on. |
required |
points
|
tuple[int, int] | list[tuple, tuple]
|
List of points to draw the line along. Can include more than 2 points, but must be at least 2 points. |
()
|
color
|
tuple[int, int, int]
|
(B, G, R) color of outline. A value of None will remove the outline altogether. |
(0, 0, 0)
|
thickness
|
int
|
Thickness of outline. A value less than 1 will remove the outline altogether. |
2
|
closed
|
bool
|
When True, connects the last point to the first point. When False, leaves shape open. |
False
|
Returns:
| Type | Description |
|---|---|
|
None |
overlay_image
overlay_image(target: ndarray, image_path: str, origin: tuple[int, int], h_align: HAlign = HAlign.LEFT, v_align: VAlign = VAlign.TOP, scale: float = 1.0)Draw an image (png/jpg) onto a target image with alignment and transparency.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
BGR image to draw onto (modified in place) |
required |
image_path
|
str
|
path to png/jpg (png supports alpha) |
required |
origin
|
tuple[int, int]
|
(x,y) coordinate of image placement |
required |
h_align
|
HAlign
|
horizontal alignment relative to (x, y) |
LEFT
|
v_align
|
VAlign
|
vertical alignment relative to (x, y) |
TOP
|
scale
|
float
|
scaling factor (1.0 = original size) |
1.0
|
polygon
polygon(target: ndarray, *points, fill: tuple[int, int, int] | None = (255, 255, 255), outline: tuple[int, int, int] | None = (0, 0, 0), thickness: int = 2, closed: bool = True)Draws a polygon with simple parameters and default values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
Target image to draw the shape on. |
required |
points
|
List of points to draw the line along. Can include more than 3 points, but must be at least 3 points. |
()
|
|
fill
|
tuple[int, int, int] | None
|
(B, G, R) color of fill. A value of None will remove the fill altogether |
(255, 255, 255)
|
outline
|
tuple[int, int, int] | None
|
(B, G, R) color of outline. A value of None will remove the outline altogether. |
(0, 0, 0)
|
thickness
|
int
|
Thickness of outline. A value less than 1 will remove the outline altogether. |
2
|
closed
|
bool
|
When True, connects the last point to the first point. When False, leaves shape open. |
True
|
Returns:
| Type | Description |
|---|---|
|
None |
rectangle
rectangle(target: ndarray, top_left: tuple[int, int], bottom_right: tuple[int, int], fill: tuple[int, int, int] | None = (255, 255, 255), outline: tuple[int, int, int] | None = (0, 0, 0), thickness: int = 1)Draws a rectangle with simple parameters and default values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
ndarray
|
Target image to draw the shape on. |
required |
top_left
|
tuple[int, int]
|
(x,y) coordinate of top left corner. |
required |
bottom_right
|
tuple[int, int]
|
(x,y) coordinate of bottom right corner. |
required |
fill
|
tuple[int, int, int] | None
|
(B, G, R) color of fill. A value of None will remove the fill altogether |
(255, 255, 255)
|
outline
|
tuple[int, int, int] | None
|
(B, G, R) color of outline. A value of None will remove the outline altogether. |
(0, 0, 0)
|
thickness
|
int
|
Thickness of outline. A value less than 1 will remove the outline altogether. |
1
|
Returns:
| Type | Description |
|---|---|
|
None |
align_single_line
align_single_line(image: ndarray, text: str, origin: tuple[int, int], font=cv2.FONT_HERSHEY_PLAIN, font_scale: float = 1, thickness: int = 1, color=(255, 255, 255), h_align: HAlign = HAlign.LEFT, v_align: VAlign = VAlign.TOP, calculated_thickness=1)Display a single line of aligned text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Target image to display text |
required |
text
|
str
|
String value of text |
required |
origin
|
tuple[int, int]
|
(x,y) coordinates of text |
required |
font
|
Display font |
FONT_HERSHEY_PLAIN
|
|
font_scale
|
float
|
Display scale |
1
|
thickness
|
int
|
Display thickness |
1
|
color
|
Display color |
(255, 255, 255)
|
|
h_align
|
HAlign
|
Horizontal align setting |
LEFT
|
v_align
|
VAlign
|
Vertical align setting |
TOP
|
calculated_thickness
|
Thickness to use in size calculations (required for outlined text) |
1
|
Returns:
| Type | Description |
|---|---|
|
None |
get_single_line_size
get_single_line_size(text: str, font: int, font_scale: float, thickness: int) -> tuple[int, int]Get the width and height of a single line of text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
Text to measure |
required |
font
|
int
|
Font to measure |
required |
font_scale
|
float
|
Font scale to measure |
required |
thickness
|
int
|
Font thickness to measure |
required |
Returns:
| Type | Description |
|---|---|
tuple[int, int]
|
Width and height as integers |
get_text_block_size
get_text_block_size(lines: list[str], font: int, font_scale: float, thickness: int, margin=20) -> tuple[int, int, list]Get the width and height of a list of lines of text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lines
|
list[str]
|
List of text values as strings. |
required |
font
|
int
|
Font to measure |
required |
font_scale
|
float
|
Font scale to measure |
required |
thickness
|
int
|
Thickness to measure |
required |
margin
|
Margin to consider in measurement |
20
|
Returns:
| Type | Description |
|---|---|
tuple[int, int, list]
|
Width, height, and list of sizes for each line of text |
get_text_x_offset
get_text_x_offset(block_width, align: HAlign, margin=15) -> intGet the x offset for text based off of the horizontal alignment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
block_width
|
Width of text block |
required | |
align
|
HAlign
|
Alignment setting |
required |
margin
|
Distance between text |
15
|
Returns:
| Type | Description |
|---|---|
int
|
X offset for text |
get_text_y_offset
get_text_y_offset(block_height, align: VAlign, margin=15) -> intGet the y offset for text based off of the vertical alignment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
block_height
|
Height of text block |
required | |
align
|
VAlign
|
Alignment setting |
required |
margin
|
Distance between text |
15
|
Returns:
| Type | Description |
|---|---|
int
|
Y offset for text |
outline_text
outline_text(image: ndarray, text: str, origin: tuple[int, int], font=cv2.FONT_HERSHEY_PLAIN, font_scale: float = 1, thickness: int = 1, color=(255, 255, 255), h_align: HAlign = HAlign.LEFT, v_align: VAlign = VAlign.TOP, outline_color=(0, 0, 0), outline_thickness=5)Creates an outlined line of text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Target image to draw the text. |
required |
text
|
str
|
String value of text to display |
required |
origin
|
tuple[int, int]
|
(x,y) coordinates of text |
required |
font
|
Font to display |
FONT_HERSHEY_PLAIN
|
|
font_scale
|
float
|
Scale of text |
1
|
thickness
|
int
|
Thickness of inner text |
1
|
color
|
Fill color of text |
(255, 255, 255)
|
|
h_align
|
HAlign
|
Horizontal alignment |
LEFT
|
v_align
|
VAlign
|
Vertical alignment |
TOP
|
outline_color
|
Outline color |
(0, 0, 0)
|
|
outline_thickness
|
Outline thickness |
5
|
Returns:
| Type | Description |
|---|---|
|
None |
stack_text
stack_text(image: ndarray, lines: list[str], origin: tuple[int, int], font=cv2.FONT_HERSHEY_PLAIN, font_scale: float = 1, thickness: int = 1, color=(255, 255, 255), h_align: HAlign = HAlign.LEFT, v_align: VAlign = VAlign.TOP, margin=5)Add multiple strings as separate lines to the image
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Target image to place text. |
required |
lines
|
list[str]
|
List of strings, each element is put on its own line. |
required |
origin
|
tuple[int, int]
|
(x,y) Coordinates for the origin of the font. |
required |
font
|
Display font of text. |
FONT_HERSHEY_PLAIN
|
|
font_scale
|
float
|
Display scale of text. |
1
|
thickness
|
int
|
Display line thickness of text. |
1
|
color
|
Display color of text. Defaults to white. |
(255, 255, 255)
|
|
h_align
|
HAlign
|
Horizontal alignment of text. |
LEFT
|
v_align
|
VAlign
|
Vertical alignment of text. |
TOP
|
margin
|
Distance between lines of text in pixels. |
5
|
Returns:
| Type | Description |
|---|---|
|
None |
angle_3d
angle_3d(p1: Sequence[float], p2: Sequence[float]) -> tuple[float, float, float]Returns the normalized 3D vector of 2 points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
p1
|
Sequence[float]
|
The 3D coordinates of the origin point. |
required |
p2
|
Sequence[float]
|
The 3D coordinates of the offset point |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
Normalized 3D vector representing the angle between p1 and p2. |