visualinspection.detection.yolox.resizeLetterbox

R2026b

Resize image for inference with YOLOX object detector

Since R2026b

collapse all in page

    Syntax

    [resizedImage,resizeFactor] = visualinspection.detection.yolox.resizeLetterbox(I,targetSize)
    [___] = visualinspection.detection.yolox.resizeLetterbox(___,PadValue=padValue)

    Description

    Resize an image while preserving the aspect ratio using the visualinspection.detection.yolox.resizeLetterbox function. This function is useful when you preprocess input images for YOLOX object detection in ONNX Runtime. Resizing an image while preserving the aspect ratio avoids distortion of objects in the image while still matching the size of the image to the input size of the object detector. This process is known as letterboxing.

    • Export a trained YOLOX object detector to an ONNX model file using the exportONNXNetwork function.

    • Preprocess test images for inference in ONNX Runtime using the visualinspection.detection.yolox.resizeLetterbox function.

    • Run the inference using the ONNX model externally or by simulating ONNX inference in MATLAB®.

    • Postprocess raw predictions from the ONNX inference using the visualinspection.detection.yolox.postprocess function.

    The detect object function of the yoloxObjectDetector object performs the preprocessing and postprocessing internally. If you do not need to run inference in ONNX Runtime, you can continue using the detect function.

    [resizedImage,resizeFactor] = visualinspection.detection.yolox.resizeLetterbox(I,targetSize) resizes the image I to the target size targetSize while applying constant value padding to preserve its aspect ratio. The function returns the resized image resizedImage and the resize factor resizeFactor. To accurately identify the locations of detected objects, you must use the same resize factor during postprocessing to convert the raw predictions to bounding boxes.

    example

    [___] = visualinspection.detection.yolox.resizeLetterbox(___,PadValue=padValue) specifies the constant value of the padding in addition to the arguments from the previous syntax.

    Examples

    collapse all

    This example uses:

    Open Live Script

    Create a pretrained YOLOX object detector.

    net = yoloxObjectDetector("small-coco")
    net = 
  yoloxObjectDetector with properties:

                 ClassNames: {80×1 cell}
                  InputSize: [640 640 3]
    NormalizationStatistics: [1×1 struct]
                  ModelName: 'small-coco'


    networkInputSize = net.InputSize(1:2)
    networkInputSize = 1×2

    640    640

    Export the YOLOX object detector to an ONNX model file.

    exportONNXNetwork(net,"yoloxSmallCoco.onnx")

    To simulate ONNX inference, import the ONNX model.

    netONNX = importNetworkFromONNX("yoloxSmallCoco.onnx",InputDataFormats="BCSS");

    Load a test image into the workspace.

    I = imread("visionteam.jpg");
inputImageSize = size(I)
    inputImageSize = 1×3

    413    800    3

    Resize the input image to match the input size of the ONNX model while preserving the aspect ratio.

    [resizedImage,resizeFactor] = visualinspection.detection.yolox.resizeLetterbox(I,networkInputSize);

    The import of the ONNX model follows the BCSS input data format. Because the ONNX input in BCSS format is equivalent to a dlarray with the SSCB format, convert the resized image to a dlarray of the SSCB format. For more information, see Conversion of ONNX Input Tensors into Deep Learning Toolbox Layers (Deep Learning Toolbox).

    resizedImage = dlarray(single(resizedImage),"SSCB");

    Obtain the raw predictions from the ONNX model. 

    rawPredictions = extractdata(predict(netONNX,resizedImage));

    Postprocess the raw predictions to obtain bounding boxes, scores, and labels.

    [bboxes,scores,labels] = visualinspection.detection.yolox.postprocess(net,rawPredictions,ResizeFactor=resizeFactor);

    Visualize the detected objects.

    detectedImg = insertObjectAnnotation(I,"Rectangle",bboxes,scores,LineWidth=4);
figure
imshow(detectedImg)

    Input Arguments

    collapse all

    Input image, specified as a numeric array of size H-by-W-by-C for a single image or H-by-W-by-C-by-B for a batch of images. Hand W are the number of rows and columns in the image, respectively. C is the number of channels in the image, and B is number of images in the batch.

    Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32

    Target size, specified as a two-element numeric vector of positive integers. The first element of the vector represents the target number of rows and the second element represents the target number of columns in the resized image. Specify the target size to match the input size dimensions of the YOLOX object detector.

    Constant value used to fill the padded region, specified as a numeric scalar. The function pads the resized image either on the right side with additional columns or on the bottom with additional rows depending on which dimension requires padding. To maintain edge continuity, you can specify the pad value as the mean or median intensity of the image.

    Output Arguments

    collapse all

    Resized image, returned as a numeric array of size targetH-by-targetW-by-C if I is a single image and of size targetH-by-targetW-by-C-by-B if I is a batch of images. targetH and targetW are the target number of rows and columns, respectively. C is the number of channels in the image, and B is number of images in the batch.

    The function calculates the aspect ratio of the input image I and evaluates two resize scenarios. The function selects the scenario that minimizes the amount of padding added to the image.

    • Resizing the image to match the target height without changing the aspect ratio, and then padding the resized width to match the target width.

    • Resizing the image to match the target width without changing the aspect ratio, and then padding the resized height to match the target height.

    If the input image is already of the target size, the function skips the resizing and returns the input image as the resized image with a resize factor of 1.0.

    Resize factor, returned as a numeric scalar.

    • If the image is resized to match the target height with padding added for columns, the resize factor is targetH/H, where H is the number of rows in the input image and targetH is the target number of rows.

    • If the image is resized to match the target width with padding added for rows, the resize factor is targetW/W, where W is the number of columns in the input image and targetW is the target number of columns.

    If the input image is already of the target size, the function skips the resizing and returns the input image as the resized image with a resize factor of 1.0. To accurately identify the locations of detected objects, you must use the returned resize factor during postprocessing to convert raw predictions to bounding boxes using the visualinspection.detection.yolox.postprocess function.

    Extended Capabilities

    expand all

    Version History

    Introduced in R2026b

    See Also

    Objects

    Functions

    Topics