Video Frame Utils

Video-frame decoding and resizing helpers for analysis.

`abs_diff(first, second)`

Compute the elementwise absolute difference of two uint8 arrays.

This is the NumPy equivalent of cv2.absdiff and avoids unsigned subtraction overflow.

Parameters:

Name	Type	Description	Default
`first`	`ndarray`	First `uint8` array.	required
`second`	`ndarray`	Second array with the same shape.	required

Returns:

Type	Description
`ndarray`	np.ndarray: `\|first - second\|`, same dtype as the inputs.

`decode_bgr(data)`

Decode encoded image bytes to a contiguous BGR uint8 array.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Encoded image bytes in any format Pillow can open.	required

Returns:

Type	Description
`ndarray`	np.ndarray: A three-channel BGR `uint8` array.

`limit_size(frame, max_width, max_height)`

Downscale an image to fit within a bounding box while preserving its aspect ratio.

Parameters:

Name	Type	Description	Default
`frame`	`ndarray`	Non-empty grayscale `(height, width)` or BGR `(height, width, 3)` `uint8` image.	required
`max_width`	`int`	Maximum output width in pixels.	required
`max_height`	`int`	Maximum output height in pixels.	required

Returns:

Type	Description
`ndarray`	np.ndarray: The original frame when it already fits, otherwise an anti-aliased bilinear resize.

Raises:

Type	Description
`TypeError`	If `frame` is not a `numpy.ndarray`.
`ValueError`	If `max_width` or `max_height` is not positive, or `frame` has an unsupported shape, is empty, or is not `uint8`.

`resize_box(frame, size)`

Resize a two- or three-dimensional uint8 image with Pillow bilinear resampling.

Pillow widens the bilinear filter support when downscaling, so reduced images are anti-aliased. Every channel is resampled independently, so the channel order is preserved. A no-op whenever frame is already at size -- the common case when a caller has already resized the frame to a detector's preferred input size.

Parameters:

Name	Type	Description	Default
`frame`	`ndarray`	Source grayscale or BGR `uint8` image, any channel order.	required
`size`	`tuple[int, int]`	Target `(width, height)` in pixels.	required

Returns:

Type	Description
`ndarray`	np.ndarray: The resized, writable `uint8` image with the same rank and channel order.

`to_grayscale(frame)`

Convert a BGR analysis frame to a single-channel grayscale image.

Uses fixed-point BT.601 coefficients consistent with the analysis pipeline.

Parameters:

Name	Type	Description	Default
`frame`	`ndarray`	BGR `uint8` frame.	required

Returns:

Type	Description
`ndarray`	np.ndarray: A two-dimensional grayscale `uint8` image.

Raises:

Type	Description
`ValueError`	If the input is not a three-channel BGR image.