Math Support
DeGirum Tools API Reference Guide. Geometry, NMS, tiling and FIR filter helper functions.
Math Support Module Overview
This module provides mathematical utilities for geometric operations and signal processing. It includes functions for bounding box manipulation, non-maximum suppression, image tiling, and a lightweight FIR low-pass filter implementation.
Key Features
Bounding Box Operations: Area calculation, IoU computation, coordinate conversions
Non-maximum Suppression: Multiple selection policies for detection filtering
Edge Box Fusion: Handling overlapping detections with configurable thresholds
Image Tiling: Utilities for fixed size or aspect ratio tiling
FIR Filter: Lightweight low-pass filter implementation for signal smoothing
Typical Usage
Import required functions from the module
Use bounding box operations for detection processing
Apply NMS or box fusion for post-processing detections
Generate image tiles for processing large images
Use FIRFilterLP for smoothing numeric sequences
Integration Notes
Built on NumPy for efficient array operations
Compatible with various bounding box formats (xyxy, xywh)
Provides consistent results across platforms
Includes comprehensive error handling
Key Functions
area(): Calculate bounding box areasintersection(): Compute intersection area of bounding boxesnms(): Apply non-maximum suppressionedge_box_fusion(): Fuse overlapping edge detectionsgenerate_tiles_fixed_size(): Generate overlapping image tiles
Configuration Options
NMS selection policies
Box fusion thresholds
Tile overlap parameters
Filter coefficients
Classes
NmsBoxSelectionPolicy
NmsBoxSelectionPolicy
Bases: Enum
Bounding box selection policy for non-maximum suppression.
This enum defines different strategies for selecting which bounding box to keep when multiple overlapping boxes are detected. Each policy has different use cases and trade-offs.
Attributes:
MOST_PROBABLE
int
Traditional NMS approach that keeps the box with highest confidence score. Best for high-confidence detections where false positives are costly.
LARGEST_AREA
int
Keeps the box with the largest area. Useful when larger detections are more likely to be correct or when object size is important.
AVERAGE
int
Averages the coordinates of all overlapping boxes. Good for reducing jitter in tracking applications.
MERGE
int
Merges all overlapping boxes into a single box. Useful when multiple detections of the same object are expected.
AnchorPoint
AnchorPoint
Bases: Enum
Position of a point of interest within the bounding box.
FIRFilterLP
FIRFilterLP
Low-pass Finite Impulse Response (FIR) filter implementation.
This class implements a low-pass FIR filter for smoothing signals. It uses convolution with designed filter coefficients (FIR kernel) with configurable cutoff frequency and number of taps.
Attributes:
normalized_cutoff
float
Normalized cutoff frequency (0 to 1).
taps_cnt
int
Number of filter taps (order of the filter).
dimension
int
Number of dimensions in the input signal.
Functions
__call__(sample)
__call__(sample)
Update the filter with a new sample and return the filtered value.
This is a convenience method that calls update().
Parameters:
sample
Union[float, ndarray]
New input sample. Can be a scalar or an array of length equal to the filter's dimension.
required
Returns:
ndarray
Filtered output value with the same shape as the input sample.
__init__(normalized_cutoff, ...)
__init__(normalized_cutoff, taps_cnt, dimension=1)
Initialize the FIR filter with specified parameters.
Parameters:
normalized_cutoff
float
Normalized cutoff frequency between 0 and 1. A value of 1 corresponds to the Nyquist frequency.
required
taps_cnt
int
Number of filter taps (order of the filter). Higher values provide better frequency response but increase computational cost and delay.
required
dimension
int
Number of dimensions in the input signal. Defaults to 1 for scalar signals.
1
Raises:
ValueError
If normalized_cutoff is not between 0 and 1.
ValueError
If taps_cnt is less than 1.
ValueError
If dimension is less than 1.
get
get()
Get the current filtered value without updating the filter.
Returns:
Current filtered value based on the samples in the buffer.
update(sample)
update(sample)
Update the filter with a new sample and return the filtered value.
This method adds a new sample to the filter's buffer and computes the filtered output by convolving the input samples with the FIR filter coefficients.
Parameters:
sample
Union[float, ndarray]
New input sample. Can be a scalar or an array of length equal to the filter's dimension.
required
Returns:
ndarray
Filtered output value with the same shape as the input sample.
Raises:
ValueError
If the input sample's shape doesn't match the filter's dimension.
Functions
area(box)
area(box)
Compute bounding box areas.
Parameters:
box
ndarray
Single box (x1, y1, x2, y2) or an array of such boxes with shape (N, 4).
required
Returns:
ndarray
Area of each input box.
intersection(boxA, ...)
intersection(boxA, boxB)
Compute intersection area of bounding boxes.
Parameters:
boxA
ndarray
First set of boxes (x1, y1, x2, y2).
required
boxB
ndarray
Second set of boxes (x1, y1, x2, y2).
required
Returns:
Union[float, ndarray]
Intersection area for each pair of boxes.
xyxy2xywh(x)
xyxy2xywh(x)
Convert (x1, y1, x2, y2) boxes to (x, y, w, h) format.
tlbr2allcorners(x)
tlbr2allcorners(x)
Convert (x1, y1, x2, y2) boxes to all four corner points.
xywh2xyxy(x)
xywh2xyxy(x)
Convert (x, y, w, h) boxes to (x1, y1, x2, y2) format.
box_iou_batch(boxes_true, ...)
box_iou_batch(boxes_true, boxes_detection)
Compute pairwise IoU between two sets of boxes.
Parameters:
boxes_true
ndarray
Ground-truth boxes (N, 4).
required
boxes_detection
ndarray
Detection boxes (M, 4).
required
Returns:
ndarray
IoU matrix of shape (N, M).
nms(detections, ...)
nms(detections, iou_threshold=0.3, use_iou=True, box_select=NmsBoxSelectionPolicy.MOST_PROBABLE, max_wh=10000, agnostic=False)
Apply non-maximum suppression to detection results.
Parameters:
detections
Iterable of detection dictionaries containing bbox, score and class fields.
required
iou_threshold
float
IoU/IoS threshold. Defaults to 0.3.
0.3
use_iou
bool
If True use IoU, otherwise IoS.
True
box_select
NmsBoxSelectionPolicy
Box selection strategy.
MOST_PROBABLE
max_wh
int
Maximum image dimension for class separation.
10000
agnostic
bool
If True perform class-agnostic NMS.
False
Returns:
None
detections is modified in place with the filtered results.
edge_box_fusion(detections, ...)
edge_box_fusion(detections, iou_threshold=0.55, skip_threshold=0.0, destructive=True)
Perform box fusion on a set of edge detections. Edge detections are detections within a certain threshold of an edge.
Parameters:
detections
results
A list of dictionaries that contain detection results as defined in PySDK.
required
iou_threshold
float
1D-IoU threshold used for selecting boxes for fusion.
0.55
skip_threshold
float
Score threshold for which boxes to fuse.
0.0
destructive
bool
Keep skipped boxes (underneath the score_threshold) in the results.
True
Returns:
results
A list of dictionaries that contain detection results as defined in PySDK. Boxes that are not fused are kept if destructive is False, otherwise they are discarded.
get_anchor_coordinates(xyxy, ...)
get_anchor_coordinates(xyxy, anchor)
Get coordinates of an anchor point inside bounding boxes.
Parameters:
xyxy
ndarray
Array of boxes (N, 4).
required
anchor
AnchorPoint
Desired anchor location.
required
Returns:
ndarray
Array (N, 2) with [x, y] coordinates.
Raises:
ValueError
If anchor is unsupported.
get_image_anchor_point(w, ...)
get_image_anchor_point(w, h, anchor)
Return coordinates of an anchor point inside an image.
intersect(a, ...)
intersect(a, b, c, d)
Return True if two line segments intersect.
generate_tiles_fixed_size(tile_size, ...)
generate_tiles_fixed_size(tile_size, image_size, min_overlap_percent)
Generate overlapping tiles with fixed size.
Parameters:
tile_size
Union[ndarray, Sequence]
Tile size (w, h).
required
image_size
Union[ndarray, Sequence]
Image size (w, h).
required
min_overlap_percent
Union[ndarray, Sequence]
Minimum overlap in percent.
required
Returns:
ndarray
Array of shape (N, M, 4) containing tile coordinates, where N is the number of rows in the tile grid, M is the number of columns in the tile grid, and 4 represents the coordinates (x1, y1, x2, y2) for each tile.
generate_tiles_fixed_ratio(tile_aspect_ratio, ...)
generate_tiles_fixed_ratio(tile_aspect_ratio, grid_size, image_size, min_overlap_percent)
Generate overlapping tiles with fixed aspect ratio.
Parameters:
tile_aspect_ratio
Union[float, ndarray, Sequence]
Desired aspect ratio.
required
grid_size
Union[ndarray, Sequence]
Grid size (x, y).
required
image_size
Union[ndarray, Sequence]
Image size (w, h).
required
min_overlap_percent
Union[ndarray, Sequence, float]
Minimum overlap percent.
required
Returns:
ndarray
Array of shape (N, M, 4) containing tile coordinates, where N is the number of rows in the tile grid, M is the number of columns in the tile grid, and 4 represents the coordinates (x1, y1, x2, y2) for each tile.
Last updated
Was this helpful?