gluoncv.utils

We implemented a broad range of utility functions which cover visualization, file handler, download and training helpers.

Visualization

plot_image Visualize image.
get_color_pallete Visualize image.
plot_bbox Visualize bounding boxes.

Miscellaneous

download Download an given URL :param url: URL to download :type url: str :param path: Destination path to store downloaded file.
makedirs Create directory recursively if not exists.
random.seed Seed the generator for python builtin random, numpy.random, mxnet.random.

Training Helpers

LRScheduler Learning Rate Scheduler
set_lr_mult Reset lr_mult to new value for all parameters that match pattern

Bounding Box Utils

bbox_iou Calculate Intersection-Over-Union(IOU) of two bounding boxes.

API Reference

GluonCV Utility functions.

class gluoncv.utils.LRScheduler(mode, baselr, niters, nepochs, step=(30, 60, 90), step_factor=0.1, targetlr=0, power=0.9, warmup_epochs=0, warmup_lr=0, warmup_mode='linear')[source]

Learning Rate Scheduler

For mode=’step’, we multiply lr with step_factor at each epoch in step.

For mode=’poly’:

lr = targetlr + (baselr - targetlr) * (1 - iter / maxiter) ^ power

For mode=’cosine’:

lr = targetlr + (baselr - targetlr) * (1 + cos(pi * iter / maxiter)) / 2

If warmup_epochs > 0, a warmup stage will be inserted before the main lr scheduler.

For warmup_mode=’linear’:

lr = warmup_lr + (baselr - warmup_lr) * iter / max_warmup_iter

For warmup_mode=’constant’:

lr = warmup_lr
Parameters:
  • mode (str) – Modes for learning rate scheduler. Currently it supports ‘step’, ‘poly’ and ‘cosine’.
  • baselr (float) – Base learning rate, i.e. the starting learning rate.
  • niters (int) – Number of iterations in each epoch.
  • nepochs (int) – Number of training epochs.
  • step (list) – A list of epochs to decay the learning rate.
  • step_factor (float) – Learning rate decay factor.
  • targetlr (float) – Target learning rate for poly and cosine, as the ending learning rate.
  • power (float) – Power of poly function.
  • warmup_epochs (int) – Number of epochs for the warmup stage.
  • warmup_lr (float) – The base learning rate for the warmup stage.
  • warmup_mode (str) – Modes for the warmup stage. Currently it supports ‘linear’ and ‘constant’.
class gluoncv.utils.TrainingHistory(labels)[source]

Training History Record and Plot

Parameters:labels (list of str) – List of names of the labels in the history.
plot(labels=None, colors=None, y_lim=(0, 1), save_path=None, legend_loc='upper right')[source]

Update the training history

Parameters:
  • labels (list of str) – List of label names to plot.
  • colors (list of str) – List of line colors.
  • save_path (str) – Path to save the plot. Will plot to screen if is None.
  • legend_loc (str) – location of legend. upper right by default.
update(values)[source]

Update the training history

Parameters:values (list of float) – List of metric scores for each label.
gluoncv.utils.batch_intersection_union(output, target, nclass)[source]

mIoU

gluoncv.utils.batch_pix_accuracy(output, target)[source]

PixAcc

gluoncv.utils.bbox_iou(bbox_a, bbox_b, offset=0)[source]

Calculate Intersection-Over-Union(IOU) of two bounding boxes.

Parameters:
  • bbox_a (numpy.ndarray) – An ndarray with shape \((N, 4)\).
  • bbox_b (numpy.ndarray) – An ndarray with shape \((M, 4)\).
  • offset (float or int, default is 0) – The offset is used to control the whether the width(or height) is computed as (right - left + offset). Note that the offset must be 0 for normalized bboxes, whose ranges are in [0, 1].
Returns:

An ndarray with shape \((N, M)\) indicates IOU between each pairs of bounding boxes in bbox_a and bbox_b.

Return type:

numpy.ndarray

gluoncv.utils.download(url, path=None, overwrite=False, sha1_hash=None)[source]

Download an given URL :param url: URL to download :type url: str :param path: Destination path to store downloaded file. By default stores to the

current directory with same name as in url.
Parameters:
  • overwrite (bool, optional) – Whether to overwrite destination file if already exists.
  • sha1_hash (str, optional) – Expected sha1 hash in hexadecimal digits. Will ignore existing file when hash is specified but doesn’t match.
Returns:

The file path of the downloaded file.

Return type:

str

gluoncv.utils.freeze_bn(net, use_global_stats=True)[source]

Freeze BatchNorm layers by setting use_global_stats to True

Parameters:
  • net (mxnet.gluon.Block) – The network whose BatchNorm layers are going to be modified
  • use_global_stats (bool) – The value of use_global_stats to set for all BatchNorm layers
Returns:

Original network with BatchNorm layers modified.

Return type:

mxnet.gluon.Block

gluoncv.utils.makedirs(path)[source]

Create directory recursively if not exists. Similar to makedir -p, you can skip checking existance before this function.

Parameters:path (str) – Path of the desired dir
gluoncv.utils.recursive_visit(net, callback, **kwargs)[source]

Recursively visit and apply callback to a net and its sub-net

Parameters:
  • net (mxnet.gluon.Block) – The network to recursively visit
  • callback (function) – The callback function to apply to each net block. Its first argument needs to be the block
gluoncv.utils.set_lr_mult(net, pattern, mult=1.0, verbose=False)[source]

Reset lr_mult to new value for all parameters that match pattern

Parameters:
  • net (mxnet.gluon.Block) – The network whose parameters are going to be adjusted.
  • pattern (str) – Regex matching pattern for targeting parameters.
  • mult (float, default 1.0) – The new learning rate multiplier.
  • verbose (bool) – Print which parameters being modifed if set True.
Returns:

Original network with learning rate multipliers modified.

Return type:

mxnet.gluon.Block

Visualization tools

class gluoncv.utils.viz.DeNormalize(mean, std)[source]

Denormalize the image

hybrid_forward(F, x)[source]

Overrides to construct symbolic graph for this Block.

Parameters:
  • x (Symbol or NDArray) – The first input tensor.
  • *args (list of Symbol or list of NDArray) – Additional input tensors.
gluoncv.utils.viz.get_color_pallete(npimg, dataset='pascal_voc')[source]

Visualize image.

Parameters:
  • npimg (numpy.ndarray) – Single channel image with shape H, W, 1.
  • dataset (str, default: 'pascal_voc') – The dataset that model pretrained on. (‘pascal_voc’, ‘ade20k’)
Returns:

out_img – Image with color pallete

Return type:

PIL.Image

gluoncv.utils.viz.plot_bbox(img, bboxes, scores=None, labels=None, thresh=0.5, class_names=None, colors=None, ax=None, reverse_rgb=False, absolute_coordinates=True)[source]

Visualize bounding boxes.

Parameters:
  • img (numpy.ndarray or mxnet.nd.NDArray) – Image with shape H, W, 3.
  • bboxes (numpy.ndarray or mxnet.nd.NDArray) – Bounding boxes with shape N, 4. Where N is the number of boxes.
  • scores (numpy.ndarray or mxnet.nd.NDArray, optional) – Confidence scores of the provided bboxes with shape N.
  • labels (numpy.ndarray or mxnet.nd.NDArray, optional) – Class labels of the provided bboxes with shape N.
  • thresh (float, optional, default 0.5) – Display threshold if scores is provided. Scores with less than thresh will be ignored in display, this is visually more elegant if you have a large number of bounding boxes with very small scores.
  • class_names (list of str, optional) – Description of parameter class_names.
  • colors (dict, optional) – You can provide desired colors as {0: (255, 0, 0), 1:(0, 255, 0), …}, otherwise random colors will be substituded.
  • ax (matplotlib axes, optional) – You can reuse previous axes if provided.
  • reverse_rgb (bool, optional) – Reverse RGB<->BGR orders if True.
  • absolute_coordinates (bool) – If True, absolute coordinates will be considered, otherwise coordinates are interpreted as in range(0, 1).
Returns:

The ploted axes.

Return type:

matplotlib axes

gluoncv.utils.viz.plot_image(img, ax=None, reverse_rgb=False)[source]

Visualize image.

Parameters:
  • img (numpy.ndarray or mxnet.nd.NDArray) – Image with shape H, W, 3.
  • ax (matplotlib axes, optional) – You can reuse previous axes if provided.
  • reverse_rgb (bool, optional) – Reverse RGB<->BGR orders if True.
Returns:

The ploted axes.

Return type:

matplotlib axes

Examples

from matplotlib import pyplot as plt ax = plot_image(img) plt.show()

Custom evaluation metrics

class gluoncv.utils.metrics.COCODetectionMetric(dataset, save_prefix, use_time=True, cleanup=False, score_thresh=0.05, data_shape=None)[source]

Detection metric for COCO bbox task.

Parameters:
  • dataset (instance of gluoncv.data.COCODetection) – The validation dataset.
  • save_prefix (str) – Prefix for the saved JSON results.
  • use_time (bool) – Append unique datetime string to created JSON file name if True.
  • cleanup (bool) – Remove created JSON file if True.
  • score_thresh (float) – Detection results with confident scores smaller than score_thresh will be discarded before saving to results.
  • data_shape (tuple of int, default is None) – If data_shape is provided as (height, width), we will rescale bounding boxes when saving the predictions. This is helpful when SSD/YOLO box predictions cannot be rescaled conveniently. Note that the data_shape must be fixed for all validation images.
get()[source]

Get evaluation metrics.

reset()[source]

Resets the internal evaluation result to initial state.

update(pred_bboxes, pred_labels, pred_scores, *args, **kwargs)[source]

Update internal buffer with latest predictions. Note that the statistics are not available until you call self.get() to return the metrics.

Parameters:
  • pred_bboxes (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes with shape B, N, 4. Where B is the size of mini-batch, N is the number of bboxes.
  • pred_labels (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes labels with shape B, N.
  • pred_scores (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes scores with shape B, N.
class gluoncv.utils.metrics.VOC07MApMetric(*args, **kwargs)[source]

Mean average precision metric for PASCAL V0C 07 dataset

iou_thresh : float
IOU overlap threshold for TP
class_names : list of str
optional, if provided, will print out AP for each class
class gluoncv.utils.metrics.VOCMApMetric(iou_thresh=0.5, class_names=None)[source]

Calculate mean AP for object detection task

iou_thresh : float
IOU overlap threshold for TP
class_names : list of str
optional, if provided, will print out AP for each class
get()[source]

Get the current evaluation result.

Returns:
  • name (str) – Name of the metric.
  • value (float) – Value of the evaluation.
reset()[source]

Clear the internal statistics to initial state.

update(pred_bboxes, pred_labels, pred_scores, gt_bboxes, gt_labels, gt_difficults=None)[source]

Update internal buffer with latest prediction and gt pairs.

Parameters:
  • pred_bboxes (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes with shape B, N, 4. Where B is the size of mini-batch, N is the number of bboxes.
  • pred_labels (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes labels with shape B, N.
  • pred_scores (mxnet.NDArray or numpy.ndarray) – Prediction bounding boxes scores with shape B, N.
  • gt_bboxes (mxnet.NDArray or numpy.ndarray) – Ground-truth bounding boxes with shape B, M, 4. Where B is the size of mini-batch, M is the number of grount-truths.
  • gt_labels (mxnet.NDArray or numpy.ndarray) – Ground-truth bounding boxes labels with shape B, M.
  • gt_difficults (mxnet.NDArray or numpy.ndarray, optional, default is None) – Ground-truth bounding boxes difficulty labels with shape B, M.