Utils¶
Bounding Box Utilities¶
bbox_iou¶
-
chainercv.utils.
bbox_iou
(bbox_a, bbox_b)[source]¶ Calculate the Intersection of Unions (IoUs) between bounding boxes.
IoU is calculated as a ratio of area of the intersection and area of the union.
This function accepts both
numpy.ndarray
andcupy.ndarray
as inputs. Please note that bothbbox_a
andbbox_b
need to be same type. The output is same type as the type of the inputs.- Parameters
bbox_a (array) – An array whose shape is \((N, 4)\). \(N\) is the number of bounding boxes. The dtype should be
numpy.float32
.bbox_b (array) – An array similar to
bbox_a
, whose shape is \((K, 4)\). The dtype should benumpy.float32
.
- Returns
An array whose shape is \((N, K)\). An element at index \((n, k)\) contains IoUs between \(n\) th bounding box in
bbox_a
and \(k\) th bounding box inbbox_b
.- Return type
array
non_maximum_suppression¶
-
chainercv.utils.
non_maximum_suppression
(bbox, thresh, score=None, limit=None)[source]¶ Suppress bounding boxes according to their IoUs.
This method checks each bounding box sequentially and selects the bounding box if the Intersection over Unions (IoUs) between the bounding box and the previously selected bounding boxes is less than
thresh
. This method is mainly used as postprocessing of object detection. The bounding boxes are selected from ones with higher scores. Ifscore
is not provided as an argument, the bounding box is ordered by its index in ascending order.The bounding boxes are expected to be packed into a two dimensional tensor of shape \((R, 4)\), where \(R\) is the number of bounding boxes in the image. The second axis represents attributes of the bounding box. They are \((y_{min}, x_{min}, y_{max}, x_{max})\), where the four attributes are coordinates of the top left and the bottom right vertices.
score
is a float array of shape \((R,)\). Each score indicates confidence of prediction.This function accepts both
numpy.ndarray
andcupy.ndarray
as an input. Please note that bothbbox
andscore
need to be the same type. The type of the output is the same as the input.- Parameters
bbox (array) – Bounding boxes to be transformed. The shape is \((R, 4)\). \(R\) is the number of bounding boxes.
thresh (float) – Threshold of IoUs.
score (array) – An array of confidences whose shape is \((R,)\).
limit (int) – The upper bound of the number of the output bounding boxes. If it is not specified, this method selects as many bounding boxes as possible.
- Returns
An array with indices of bounding boxes that are selected. They are sorted by the scores of bounding boxes in descending order. The shape of this array is \((K,)\) and its dtype is
numpy.int32
. Note that \(K \leq R\).- Return type
array
Download Utilities¶
cached_download¶
-
chainercv.utils.
cached_download
(url)[source]¶ Downloads a file and caches it.
This is different from the original
cached_download()
in that the download progress is reported. Note that this progress report can be disabled by setting the environment variable CHAINERCV_DOWNLOAD_REPORT to ‘OFF’.It downloads a file from the URL if there is no corresponding cache. After the download, this function stores a cache to the directory under the dataset root (see
set_dataset_root()
). If there is already a cache for the given URL, it just returns the path to the cache without downloading the same file.- Parameters
url (string) – URL to download from.
- Returns
Path to the downloaded file.
- Return type
string
download_model¶
-
chainercv.utils.
download_model
(url)[source]¶ Downloads a model file and puts it under model directory.
It downloads a file from the URL and puts it under model directory. For exmaple, if
url
is http://example.com/subdir/model.npz, the pretrained weights file will be saved to $CHAINER_DATASET_ROOT/pfnet/chainercv/models/model.npz. If there is already a file at the destination path, it just returns the path without downloading the same file.- Parameters
url (string) – URL to download from.
- Returns
Path to the downloaded file.
- Return type
string
extractall¶
-
chainercv.utils.
extractall
(file_path, destination, ext)[source]¶ Extracts an archive file.
This function extracts an archive file to a destination.
- Parameters
file_path (string) – The path of a file to be extracted.
destination (string) – A directory path. The archive file will be extracted under this directory.
ext (string) – An extension suffix of the archive file. This function supports
'.zip'
,'.tar'
,'.gz'
and'.tgz'
.
Image Utilities¶
read_image¶
-
chainercv.utils.
read_image
(file, dtype=<class 'numpy.float32'>, color=True, alpha=None)[source]¶ Read an image from a file.
This function reads an image from given file. The image is CHW format and the range of its value is \([0, 255]\). If
color = True
, the order of the channels is RGB.The backend used by
read_image()
is configured bychainer.global_config.cv_read_image_backend
. Two backends are supported: “cv2” and “PIL”. If this isNone
, “cv2” is used whenever “cv2” is installed, and “PIL” is used when “cv2” is not installed.- Parameters
file (string or file-like object) – A path of image file or a file-like object of image.
dtype – The type of array. The default value is
float32
.color (bool) – This option determines the number of channels. If
True
, the number of channels is three. In this case, the order of the channels is RGB. This is the default behaviour. IfFalse
, this function returns a grayscale image.alpha (None or {'ignore', 'blend_with_white', 'blend_with_black'}) –
Choose how RGBA images are handled. By default, an error is raised. Here are the other possible behaviors:
’ignore’: Ignore alpha channel.
’blend_with_white’: Blend RGB image multiplied by alpha on a white image.
’blend_with_black’: Blend RGB image multiplied by alpha on a black image.
- Returns
An image.
- Return type
read_label¶
-
chainercv.utils.
read_label
(file, dtype=<class 'numpy.int32'>)[source]¶ Read a label image from a file.
This function reads an label image from given file. If reading label doesn’t work collectly, try
read_image()
with a parametercolor=True
.- Parameters
file (string or file-like object) – A path of image file or a file-like object of image.
dtype – The type of array. The default value is
int32
.color (bool) – This option determines the number of channels. If
True
, the number of channels is three. In this case, the order of the channels is RGB. This is the default behaviour. IfFalse
, this function returns a grayscale image.
- Returns
An image.
- Return type
tile_images¶
-
chainercv.utils.
tile_images
(imgs, n_col, pad=2, fill=0)[source]¶ Make a tile of images
- Parameters
imgs (numpy.ndarray) – A batch of images whose shape is BCHW.
n_col (int) – The number of columns in a tile.
pad (int or tuple of two ints) –
pad_y, pad_x
. This is the amounts of padding in y and x directions. If this is an integer, the amounts of padding in the two directions are the same. The default value is 2.fill (float, tuple or ndarray) – The value of padded pixels. If it is
numpy.ndarray
, its shape should be \((C, 1, 1)\), where \(C\) is the number of channels ofimg
.
- Returns
An image array in CHW format. The size of this image is \(((H + pad_{y}) \times \lceil B / n_{n_{col}} \rceil, (W + pad_{x}) \times n_{col})\).
- Return type
write_image¶
-
chainercv.utils.
write_image
(img, file, format=None)[source]¶ Save an image to a file.
This function saves an image to given file. The image is in CHW format and the range of its value is \([0, 255]\).
- Parameters
image (ndarray) – An image to be saved.
file (string or file-like object) – A path of image file or a file-like object of image.
format (
{'bmp', 'jpeg', 'png'}
) – The format of image. Iffile
is a file-like object, this option must be specified.
Iterator Utilities¶
apply_to_iterator¶
-
chainercv.utils.
apply_to_iterator
(func, iterator, n_input=1, hook=None, comm=None)[source]¶ Apply a function/method to batches from an iterator.
This function applies a function/method to an iterator of batches.
It assumes that the iterator iterates over a collection of tuples that contain inputs to
func()
. Additionally, the tuples may contain values that are not used byfunc()
. For convenience, we allow the iterator to iterate over a collection of inputs that are not tuple. Here is an illustration of the expected behavior of the iterator. This behaviour is the same aschainer.Iterator
.>>> batch = next(iterator) >>> # batch: [in_val] or >>> # batch: [(in_val0, ..., in_val{n_input - 1})] or >>> # batch: [(in_val0, ..., in_val{n_input - 1}, rest_val0, ...)]
func()
should take batch(es) of data and return batch(es) of computed values. Here is an illustration of the expected behavior of the function.>>> out_vals = func([in_val0], ..., [in_val{n_input - 1}]) >>> # out_vals: [out_val] or >>> out_vals0, out_vals1, ... = func([in_val0], ..., [in_val{n_input - 1}]) >>> # out_vals0: [out_val0] >>> # out_vals1: [out_val1]
With
apply_to_iterator()
, users can get iterator(s) of values returned byfunc()
. It also returns iterator(s) of input values and values that are not used for computation.>>> in_values, out_values, rest_values = apply_to_iterator( >>> func, iterator, n_input) >>> # in_values: (iter of in_val0, ..., iter of in_val{n_input - 1}) >>> # out_values: (iter of out_val0, ...) >>> # rest_values: (iter of rest_val0, ...)
Here is an exmple, which applies a pretrained Faster R-CNN to PASCAL VOC dataset.
>>> from chainer import iterators >>> >>> from chainercv.datasets import VOCBBoxDataset >>> from chainercv.links import FasterRCNNVGG16 >>> from chainercv.utils import apply_to_iterator >>> >>> dataset = VOCBBoxDataset(year='2007', split='test') >>> # next(iterator) -> [(img, gt_bbox, gt_label)] >>> iterator = iterators.SerialIterator( ... dataset, 2, repeat=False, shuffle=False) >>> >>> # model.predict([img]) -> ([pred_bbox], [pred_label], [pred_score]) >>> model = FasterRCNNVGG16(pretrained_model='voc07') >>> >>> in_values, out_values, rest_values = apply_to_iterator( ... model.predict, iterator) >>> >>> # in_values contains one iterator >>> imgs, = in_values >>> # out_values contains three iterators >>> pred_bboxes, pred_labels, pred_scores = out_values >>> # rest_values contains two iterators >>> gt_bboxes, gt_labels = rest_values
- Parameters
func – A callable that takes batch(es) of input data and returns computed data.
iterator (iterator) – An iterator of batches. The first
n_input
elements in each sample are treated as input values. They are passed tofunc
. Ifcomm
is specified, only the iterator of the root worker is used.n_input (int) – The number of input data. The default value is
1
.hook – A callable that is called after each iteration.
in_values
,out_values
, andrest_values
are passed as arguments. Note that these values do not contain data from the previous iterations. Ifcomm
is specified, only the root worker executes this hook.comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this function scatters the iterator of root worker and gathers the results to the root worker.
- Returns
This function returns three tuples of iterators:
in_values
,out_values
andrest_values
.in_values
: A tuple of iterators. Each iterator returns a corresponding input value. For example, iffunc()
takes[in_val0], [in_val1]
,next(in_values[0])
andnext(in_values[1])
will bein_val0
andin_val1
.out_values
: A tuple of iterators. Each iterator returns a corresponding computed value. For example, iffunc()
returns([out_val0], [out_val1])
,next(out_values[0])
andnext(out_values[1])
will beout_val0
andout_val1
.rest_values
: A tuple of iterators. Each iterator returns a corresponding rest value. For example, if theiterator
returns[(in_val0, in_val1, rest_val0, rest_val1)]
,next(rest_values[0])
andnext(rest_values[1])
will berest_val0
andrest_val1
. If the input iterator does not give any rest values, this tuple will be empty.
- Return type
Three tuples of iterators
ProgressHook¶
unzip¶
-
chainercv.utils.
unzip
(iterable)[source]¶ Converts an iterable of tuples into a tuple of iterators.
This function converts an iterable of tuples into a tuple of iterators. This is an inverse function of
six.moves.zip()
.>>> from chainercv.utils import unzip >>> data = [(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')] >>> int_iter, str_iter = unzip(data) >>> >>> next(int_iter) # 0 >>> next(int_iter) # 1 >>> next(int_iter) # 2 >>> >>> next(str_iter) # 'a' >>> next(str_iter) # 'b' >>> next(str_iter) # 'c'
- Parameters
iterable (iterable) – An iterable of tuples. All tuples should have the same length.
- Returns
Each iterator corresponds to each element of input tuple. Note that each iterator stores values until they are popped. To reduce memory usage, it is recommended to delete unused iterators.
- Return type
tuple of iterators
Link Utilities¶
prepare_pretrained_model¶
-
chainercv.utils.
prepare_pretrained_model
(param, pretrained_model, models, default={})[source]¶ Select parameters based on the existence of pretrained model.
- Parameters
param (dict) – Map from the name of the parameter to values.
pretrained_model (string) – Name of the pretrained weight, path to the pretrained weight or
None
.models (dict) –
Map from the name of the pretrained weight to
model
, which is a dictionary containing the configuration used by the selected weight.model
has four keys:param
,overwritable
,url
andcv2
.param (dict): Parameters assigned to the pretrained weight.
overwritable (set): Names of parameters that are overwritable (i.e.,
param[key] != model['param'][key]
is accepted).url (string): Location of the pretrained weight.
cv2 (bool): If
True
, a warning is raised ifcv2
is not installed.
Mask Utilities¶
mask_iou¶
-
chainercv.utils.
mask_iou
(mask_a, mask_b)[source]¶ Calculate the Intersection of Unions (IoUs) between masks.
IoU is calculated as a ratio of area of the intersection and area of the union.
This function accepts both
numpy.ndarray
andcupy.ndarray
as inputs. Please note that bothmask_a
andmask_b
need to be same type. The output is same type as the type of the inputs.- Parameters
mask_a (array) – An array whose shape is \((N, H, W)\). \(N\) is the number of masks. The dtype should be
numpy.bool
.mask_b (array) – An array similar to
mask_a
, whose shape is \((K, H, W)\). The dtype should benumpy.bool
.
- Returns
An array whose shape is \((N, K)\). An element at index \((n, k)\) contains IoUs between \(n\) th mask in
mask_a
and \(k\) th mask inmask_b
.- Return type
array
mask_to_bbox¶
-
chainercv.utils.
mask_to_bbox
(mask)[source]¶ Compute the bounding boxes around the masked regions.
This function accepts both
numpy.ndarray
andcupy.ndarray
as inputs.- Parameters
mask (array) – An array whose shape is \((R, H, W)\). \(R\) is the number of masks. The dtype should be
numpy.bool
.- Returns
The bounding boxes around the masked regions. This is an array whose shape is \((R, 4)\). \(R\) is the number of bounding boxes. The dtype should be
numpy.float32
.- Return type
array
scale_mask¶
-
chainercv.utils.
scale_mask
(mask, bbox, size)[source]¶ Scale instance segmentation mask while keeping the aspect ratio.
This function exploits the sparsity of
mask
to speed up resize operation.The input image will be resized so that the shorter edge will be scaled to length
size
after resizing.- Parameters
mask (array) – An array whose shape is \((R, H, W)\). \(R\) is the number of masks. The dtype should be
numpy.bool
.bbox (array) – The bounding boxes around the masked region of
mask
. This is expected to be the value obtained bybbox = chainercv.utils.mask_to_bbox(mask)
.size (int) – The length of the smaller edge.
- Returns
An array whose shape is \((R, H, W)\). \(R\) is the number of masks. The dtype should be
numpy.bool
.- Return type
array
Testing Utilities¶
assert_is_bbox¶
-
chainercv.utils.
assert_is_bbox
(bbox, size=None)[source]¶ Checks if bounding boxes satisfy bounding box format.
This function checks if given bounding boxes satisfy bounding boxes format or not. If the bounding boxes do not satifiy the format, this function raises an
AssertionError
.- Parameters
bbox (ndarray) – Bounding boxes to be checked.
size (tuple of ints) – The size of an image. If this argument is specified, Each bounding box should be within the image.
assert_is_bbox_dataset¶
-
chainercv.utils.
assert_is_bbox_dataset
(dataset, n_fg_class, n_example=None)[source]¶ Checks if a dataset satisfies the bounding box dataset API.
This function checks if a given dataset satisfies the bounding box dataset API or not. If the dataset does not satifiy the API, this function raises an
AssertionError
.
assert_is_detection_link¶
-
chainercv.utils.
assert_is_detection_link
(link, n_fg_class)[source]¶ Checks if a link satisfies detection link APIs.
This function checks if a given link satisfies detection link APIs or not. If the link does not satifiy the APIs, this function raises an
AssertionError
.- Parameters
link – A link to be checked.
n_fg_class (int) – The number of foreground classes.
assert_is_image¶
-
chainercv.utils.
assert_is_image
(img, color=True, check_range=True)[source]¶ Checks if an image satisfies image format.
This function checks if a given image satisfies image format or not. If the image does not satifiy the format, this function raises an
AssertionError
.- Parameters
img (ndarray) – An image to be checked.
color (bool) – A boolean that determines the expected channel size. If it is
True
, the number of channels should be3
. Otherwise, it should be1
. The default value isTrue
.check_range (bool) – A boolean that determines whether the range of values are checked or not. If it is
True
, The values of image must be in \([0, 255]\). Otherwise, this function does not check the range. The default value isTrue
.
assert_is_instance_segmentation_dataset¶
-
chainercv.utils.
assert_is_instance_segmentation_dataset
(dataset, n_fg_class, n_example=None)[source]¶ Checks if a dataset satisfies instance segmentation dataset APIs.
This function checks if a given dataset satisfies instance segmentation dataset APIs or not. If the dataset does not satifiy the APIs, this function raises an
AssertionError
.
assert_is_label_dataset¶
-
chainercv.utils.
assert_is_label_dataset
(dataset, n_class, n_example=None, color=True)[source]¶ Checks if a dataset satisfies the label dataset API.
This function checks if a given dataset satisfies the label dataset API or not. If the dataset does not satifiy the API, this function raises an
AssertionError
.- Parameters
dataset – A dataset to be checked.
n_class (int) – The number of classes.
n_example (int) – The number of examples to be checked. If this argument is specified, this function picks examples ramdomly and checks them. Otherwise, this function checks all examples.
color (bool) – A boolean that determines the expected channel size. If it is
True
, the number of channels should be3
. Otherwise, it should be1
. The default value isTrue
.
assert_is_point¶
-
chainercv.utils.
assert_is_point
(point, visible=None, size=None, n_point=None)[source]¶ Checks if points satisfy the format.
This function checks if given points satisfy the format and raises an
AssertionError
when the points violate the convention.- Parameters
point (ndarray) – Points to be checked.
visible (ndarray) – Visibility of the points. If this is
None
, all points are regarded as visible.size (tuple of ints) – The size of an image. If this argument is specified, the coordinates of visible points are checked to be within the image.
n_point (int) – If specified, the number of points in each object is expected to be
n_point
.
assert_is_point_dataset¶
-
chainercv.utils.
assert_is_point_dataset
(dataset, n_point=None, n_example=None, no_visible=False)[source]¶ Checks if a dataset satisfies the point dataset API.
This function checks if a given dataset satisfies the point dataset API or not. If the dataset does not satifiy the API, this function raises an
AssertionError
.- Parameters
dataset – A dataset to be checked.
n_point (int) – The number of expected points per image. If this is
None
, the number of points per image can be arbitrary.n_example (int) – The number of examples to be checked. If this argument is specified, this function picks examples ramdomly and checks them. Otherwise, this function checks all examples.
no_visible (bool) – If
True
, we assume thatvisible
is always not contained. IfFalse
, :obj;`visible` may or may not be contained.
assert_is_semantic_segmentation_dataset¶
-
chainercv.utils.
assert_is_semantic_segmentation_dataset
(dataset, n_class, n_example=None)[source]¶ Checks if a dataset satisfies semantic segmentation dataset APIs.
This function checks if a given dataset satisfies semantic segmentation dataset APIs or not. If the dataset does not satifiy the APIs, this function raises an
AssertionError
.
assert_is_semantic_segmentation_link¶
-
chainercv.utils.
assert_is_semantic_segmentation_link
(link, n_class)[source]¶ Checks if a link satisfies semantic segmentation link APIs.
This function checks if a given link satisfies semantic segmentation link APIs or not. If the link does not satifiy the APIs, this function raises an
AssertionError
.- Parameters
link – A link to be checked.
n_class (int) – The number of classes including background.
ConstantStubLink¶
-
class
chainercv.utils.
ConstantStubLink
(outputs)[source]¶ A chainer.Link that returns constant value(s).
This is a
chainer.Link
that returns constantchainer.Variable
(s) whenforward()
method is called.- Parameters
outputs (ndarray or tuple or ndarray) – The value(s) of variable(s) returned by
forward()
. If an array is specified,forward()
returns achainer.Variable
. Otherwise, it returns a tuple ofchainer.Variable
.
-
forward
(*_)[source]¶ Returns value(s).
- Parameters
method can take any values as its arguments. (This) –
function returns values independent of the arguments. (This) –
- Returns
If
outputs
is an array, this method returns achainer.Variable
. Otherwise, this returns a tuple ofchainer.Variable
.- Return type
chainer.Variable or tuple of chainer.Variable
-
to_cpu
()[source]¶ Copies parameter variables and persistent values to CPU.
This method does not handle non-registered attributes. If some of such attributes must be copied to CPU, the link implementation should override
device_resident_accept()
to do so.Returns: self
-
to_gpu
(device=None)[source]¶ Copies parameter variables and persistent values to GPU.
This method does not handle non-registered attributes. If some of such attributes must be copied to GPU, the link implementation must override
device_resident_accept()
to do so.- Parameters
device – Target device specifier. If omitted, the current device is used.
Returns: self
generate_random_bbox¶
-
chainercv.utils.
generate_random_bbox
(n, img_size, min_length, max_length)[source]¶ Generate valid bounding boxes with random position and shape.
- Parameters
- Returns
Coordinates of bounding boxes. Its shape is \((R, 4)\). Here, \(R\) equals
n
. The second axis contains \(y_{min}, x_{min}, y_{max}, x_{max}\), where \(min\_length \leq y_{max} - y_{min} < max\_length\). and \(min\_length \leq x_{max} - x_{min} < max\_length\)- Return type