ChainerCV Documentation
Release 0.13.1

Preferred Networks, inc.

Jun 13, 2019

CONTENTS

1

Installation Guide

3

2

ChainerCV Tutorial

53

ChainerCV Reference Manual

17

4

Naming Conventions

143

5

License147

6

Indices and tables

149

Bibliography

151

Python Module Index

153

Index

155

i

ii

ChainerCV Documentation, Release 0.13.1

ChainerCV is a deep learning based computer vision library built on top of Chainer.

CONTENTS

1ChainerCV Documentation, Release 0.13.1

2

CONTENTSCHAPTERONEINSTALLATION GUIDE

1.1 Pip
You can install ChainerCV using pip.
pip install -U numpy
pip install chainercv

1.2 Anaconda
Build instruction using Anaconda is as follows.
# For python 3# wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O
˓→miniconda.shwget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh -O
˓→miniconda.sh
bash miniconda.sh -b -p $HOME/miniconda
export PATH="$HOME/miniconda/bin:$PATH"
conda config --set always_yes yes --set changeps1 noconda update -q conda# Download ChainerCV and go to the root directory of ChainerCV
git clone https://github.com/chainer/chainercv
cd chainercv
conda env create -f environment.yml
source activate chainercv# Install ChainerCV
pip install -e .
# Try our demos at examples/* !

3

ChainerCV Documentation, Release 0.13.1

4

Chapter 1. Installation Guide

CHAPTERTWOCHAINERCV TUTORIAL

2.1 Object Detection Tutorial
This tutorial will walk you through the features related to object detection that ChainerCV supports. We assume
that readers have a basic understanding of Chainer framework (e.g. understand chainer.Link). For users new toChainer, please first read Introduction to Chainer.
In ChainerCV, we define the object detection task as a problem of, given an image, bounding box based localizationand categorization of objects. ChainerCV supports the task by providing the following features:• Visualization• BboxDataset• Detection Link
• DetectionEvaluator• Training script for various detection models
Here is a short example that conducts inference and visualizes output. Please download an image froma link below, and name it as sample.jpg. https://cloud.githubusercontent.com/assets/2062128/26187667/
9cb236da-3bd5-11e7-8bcf-7dbd4302e2dc.jpg# In the rest of the tutorial, we assume that the `plt`# is imported before every code snippet.
import matplotlib.pyplot as plt
from chainercv.datasets import voc_bbox_label_names
from chainercv.links import SSD300
from chainercv.utils import read_image
from chainercv.visualizations import vis_bbox# Read an RGB image and return it in CHW format.
img = read_image('sample.jpg')
model = SSD300(pretrained_model='voc0712')
bboxes, labels, scores = model.predict([img])
vis_bbox(img, bboxes[0], labels[0], scores[0],label_names=voc_bbox_label_names)
plt.show()

2.1.1 Bounding boxes in ChainerCV
Bounding boxes in an image are represented as a two-dimensional array of shape (𝑅, 4), where 𝑅 is the number ofbounding boxes and the second axis corresponds to the coordinates of bounding boxes. The coordinates are ordered
5ChainerCV Documentation, Release 0.13.1

in the array by (y_min, x_min, y_max, x_max), where (y_min, x_min) and (y_max, x_max) arethe (y, x) coordinates of the top left and the bottom right vertices. Notice that ChainerCV orders coordinates inyx order, which is the opposite of the convention used by other libraries such as OpenCV. This convention is adopted
because it is more consistent with the memory order of an image that follows row-column order. Also, the dtype ofbounding box array is numpy.float32.
Here is an example with a simple toy data.
from chainercv.visualizations import vis_bbox
import numpy as np
img = np.zeros((3, 224, 224), dtype=np.float32)# We call a variable/array of bounding boxes as `bbox` throughout the library
bbox = np.array([[10, 10, 20, 40], [150, 150, 200, 200]], dtype=np.float32)
vis_bbox(img, bbox)
plt.show()6

Chapter 2. ChainerCV Tutorial

ChainerCV Documentation, Release 0.13.1

In this example, two bounding boxes are displayed on top of a black image. vis_bbox() is a utility function thatvisualizes bounding boxes and an image together.

2.1.2 Bounding Box Dataset
ChainerCV supports dataset loaders, which can be used to easily index examples with list-like interfaces. Dataset
classes whose names end with BboxDataset contain annotations of where objects locate in an image and which
categories they are assigned to. These datasets can be indexed to return a tuple of an image, bounding boxes and labels.
The labels are stored in an np.int32 array of shape (𝑅, ). Each element corresponds to a label of an object in thecorresponding bounding box.
A mapping between an integer label and a category differs between datasets. This mapping can be obtained from objects whose names end with label_names, such as voc_bbox_label_names. These mappings become helpfulwhen bounding boxes need to be visualized with label names. In the next example, the interface of BboxDataset
and the functionality of vis_bbox() to visualize label names are illustrated.
from chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
from chainercv.visualizations import vis_bbox
dataset = VOCBboxDataset(year='2012')
img, bbox, label = dataset[0]print(bbox.shape) # (2, 4)
print(label.shape) # (2,)
vis_bbox(img, bbox, label, label_names=voc_bbox_label_names)
plt.show()

Note that the example downloads VOC 2012 dataset at runtime when it is used for the first time on the machine.

2.1.3 Detection Link
ChainerCV provides several network implementations that carry out object detection. For example, Single Shot MultiBox Detector (SSD) [Liu16] and Faster R-CNN [Ren15] are supported. Despite the difference between the models
in how prediction is carried out internally, they support the common method for prediction called predict(). Thismethod takes a list of images and returns prediction result, which is a tuple of lists bboxes, labels, scores.
The more description can be found here (predict()). Inference on these models runs smoothly by downloadingnecessary pre-trained weights from the internet automatically.
from chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
from chainercv.links import SSD300
from chainercv.visualizations import vis_bbox
dataset = VOCBboxDataset(year='2007', split='test')
img_0, _, _ = dataset[0]img_1, _, _ = dataset[1]model = SSD300(pretrained_model='voc0712')# Note that `predict` takes a list of images.
bboxes, labels, scores = model.predict([img_0, img_1])# Visualize output of the first image on the left and# the second image on the right.
fig = plt.figure()ax1 = fig.add_subplot(1, 2, 1)
ax2 = fig.add_subplot(1, 2, 2)(continues on next page)2.1. Object Detection Tutorial

7

ChainerCV Documentation, Release 0.13.1

8Chapter 2. ChainerCV Tutorial

ChainerCV Documentation, Release 0.13.1(continued from previous page)vis_bbox(img_0, bboxes[0], labels[0], scores[0],label_names=voc_bbox_label_names, ax=ax1)
vis_bbox(img_1, bboxes[1], labels[1], scores[1],label_names=voc_bbox_label_names, ax=ax2)
plt.show()

The above example puts together functionality of detection link. It instantiates SSD300 model with weights trainedon VOC 2007 and VOC 2012 datasets. The model runs prediction using predict(), and the outputs are visualizedusing vis_bbox(). Note that in this case, confidence scores are visualized together with other data.
Many detection algorithms post-process bounding box proposals calculated from the output of neural networks byremoving unnecessary ones. Faster R-CNN and SSD use non-maximum suppression to remove overlapping bounding boxes. Also, they remove bounding boxes with low confidence scores. These two models have attributes
nms_thresh and score_thresh, which configure the post-processing. In the following example, the algorithm
runs with a very low score_thresh so that bounding boxes with low scores are kept. It is known that lower
score_thresh produces higher mAP.
from chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
from chainercv.links import SSD300
from chainercv.visualizations import vis_bbox
dataset = VOCBboxDataset(year='2007', split='test')
img, _, _ = dataset[0]model = SSD300(pretrained_model='voc0712')# Alternatively, you can use predefined parameters by# model.use_preset('evaluate')model.score_thresh = 0.01
bboxes, labels, scores = model.predict([img])
vis_bbox(img, bboxes[0], labels[0], scores[0],label_names=voc_bbox_label_names)
plt.show()

2.1. Object Detection Tutorial

9ChainerCV Documentation, Release 0.13.1

2.1.4 Detection Evaluator
ChainerCV provides functionalities that make evaluating detection links easy. They are provided at two levels: evaluator extensions and evaluation functions.
Evaluator extensions such as DetectionVOCEvaluator inherit from Evaluator, and have similar interface.
They are initialized by taking an iterator and a network that carries out prediction with method predict(). When
this class is called (i.e. __call__() of DetectionVOCEvaluator), several actions are taken. First, it iterates
over a dataset based on an iterator. Second, the network makes prediction using the images collected from the dataset.
Last, an evaluation function is called with the ground truth annotations and the prediction results.
In contrast to evaluators that hide details, evaluation functions such as eval_detection_voc() are provided for
those who need a finer level of control. These functions take the ground truth annotations and prediction results asarguments and return measured performance.
Here is a simple example that uses a detection evaluator.
from chainer.iterators import SerialIterator
from chainer.datasets import SubDataset
from chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
from chainercv.extensions import DetectionVOCEvaluatorfrom chainercv.links import SSD300# Only use subset of dataset so that evaluation finishes quickly.
dataset = VOCBboxDataset(year='2007', split='test')
dataset = dataset[:6]it = SerialIterator(dataset, 2, repeat=False, shuffle=False)model = SSD300(pretrained_model='voc0712')
evaluator = DetectionVOCEvaluator(it, model,
label_names=voc_bbox_label_names)# result is a dictionary of evaluation scores. Print it and check it.
result = evaluator()

10

Chapter 2. ChainerCV Tutorial

ChainerCV Documentation, Release 0.13.1

2.1.5 Training Detection Links
By putting together all the functions and utilities, training scripts can be easily written. Please check training scripts
contained in the examples. Also, ChainerCV posts the performance achieved through running the training script in
README.
• Faster R-CNN examples• SSD examples

2.1.6 References

2.2 Tips using Links
2.2.1 Fine-tuning
Models in ChainerCV support the argument pretrained_model to load pretrained weights. This functionality islimited in the case when fine-tuning pretrained weights. In that circumstance, the layers specific to the classes of theoriginal dataset may need to be randomly initialized. In this section, we give a procedure to cope with this problem.
Copying a subset of weights in a chain can be done in few lines of code. Here is a block of code that does this.
# src is a model with pretrained weights# dst is a model randomly initialized# ignore_names is the name of parameters to skip
# For the case of VGG16, this should be ['/fc7/W', '/fc7/b']
ignore_names = []src_params = {p[0]: p[1] for p in src.namedparams()}
for dst_named_param in dst.namedparams():name = dst_named_param[0]if name not in ignore_names:
dst_named_param[1].array[:] = src_params[name].array[:]

Fine-tuning to a dataset with a different number of classes
When the number of classes of the target dataset is different from the source dataset during fine-tuning, the names of
the weights to skip can be found automatically with the following method.
def get_shape_mismatch_names(src, dst):# all parameters are assumed to be initialized
mismatch_names = []src_params = {p[0]: p[1] for p in src.namedparams()}
for dst_named_param in dst.namedparams():name = dst_named_param[0]dst_param = dst_named_param[1]src_param = src_params[name]if src_param.shape != dst_param.shape:
mismatch_names.append(name)return mismatch_names

Finally, this is a complete example using SSD300.

2.2. Tips using Links

11

ChainerCV Documentation, Release 0.13.1

from chainercv.links import SSD300
import numpy as np
src = SSD300(pretrained_model='voc0712')# the number of classes in VOC is different from 50
dst = SSD300(n_fg_class=50)# initialized weights
dst(np.zeros((1, 3, dst.insize, dst.insize), dtype=np.float32))# the method described above
ignore_names = get_shape_mismatch_names(src, dst)
src_params = {p[0]: p[1] for p in src.namedparams()}
for dst_named_param in dst.namedparams():name = dst_named_param[0]if name not in ignore_names:
dst_named_param[1].array[:] = src_params[name].array[:]# check that weights are transferednp.testing.assert_equal(dst.extractor.conv1_1.W.data,
src.extractor.conv1_1.W.data)# the names of the weights that are skipped
print(ignore_names)

2.3 Sliceable Dataset
This tutorial will walk you through the features related to sliceable dataset. We assume that readers have a basic
understanding of Chainer dataset (e.g. understand chainer.dataset.DatasetMixin).
In ChainerCV, we introduce sliceable feature to datasets. Sliceable datasets support slice() that returns a view ofthe dataset.
This example that shows the basic usage.
# VOCBboxDataset supports sliceable featurefrom chainercv.datasets import VOCBboxDataset
dataset = VOCBboxDataset()# keys returns the names of data
print(dataset.keys) # ('img', 'bbox', 'label')# we can get an example by []img, bbox, label = dataset[0]# get a view of the first 100 examples
view = dataset.slice[:100]
print(len(view)) # 100# get a view of image and labelview = dataset.slice[:, ('img', 'label')]# the view also supports sliceable, so that we can call keys
print(view.keys) # ('img', 'label')# we can get an example by []img, label = view[0]12Chapter 2. ChainerCV Tutorial

ChainerCV Documentation, Release 0.13.1

2.3.1 Motivation
slice() returns a view of the dataset without conducting data loading, where DatasetMixin.__getitem__()conducts get_example() for all required examples. Users can write efficient code by this view.
This example counts the number of images that contain dogs. With the sliceable feature, we can access the label
information without loading images from disk.. Therefore, the first case becomes faster.
import timefrom chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
dataset = VOCBboxDataset()
dog_lb = voc_bbox_label_names.index('dog')# with slicet = time.time()count = 0
# get a view of labelview = dataset.slice[:, 'label']for i in range(len(view)):# we can focus on label
label = view[i]if dog_lb in label:count += 1
print('w/ slice: {} secs'.format(time.time() - t))print('{} images contain dogs'.format(count))
print()# without slicet = time.time()count = 0
for i in range(len(dataset)):# img and bbox are loaded but not needed
img, bbox, label = dataset[i]if dog_lb in label:count += 1
print('w/o slice: {} secs'.format(time.time() - t))print('{} images contain dogs'.format(count))
print()

2.3.2 Usage: slice along with the axis of examples
slice() takes indices of examples as its first argument.
from chainercv.datasets import VOCBboxDataset
dataset = VOCBboxDataset()# the view of the first 100 examples
view = dataset.slice[:100]# the view of the last 100 examples
view = dataset.slice[-100:]# the view of the 3rd, 5th, and 7th examples(continues on next page)2.3. Sliceable Dataset

13

ChainerCV Documentation, Release 0.13.1(continued from previous page)view = dataset.slice[3:8:2]# the view of the 3rd, 1st, and 4th examples
view = dataset.slice[[3, 1, 4]]Also, it can take a list of booleans as its first argument. Note that the length of the list should be the same aslen(dataset).
from chainercv.datasets import VOCBboxDataset
dataset = VOCBboxDataset()# make booleans
bboxes = dataset.slice[:, 'bbox']
booleans = [len(bbox) >= 3 for bbox in bboxes]# a collection of samples that contain at least three bounding boxes
view = dataset.slice[booleans]

2.3.3 Usage: slice along with the axis of dataslice() takes names or indices of data as its second argument. keys returns all available names.
from chainercv.datasets import VOCBboxDataset
dataset = VOCBboxDataset()# the view of image# note that : of the first argument means all examples
view = dataset.slice[:, 'img']
print(view.keys) # 'img'
img = view[0]# the view of image and labelview = dataset.slice[:, ('img', 'label')]print(view.keys) # ('img', 'label')img, label = view[0]# the view of image (returns a tuple)
view = dataset.slice[:, ('img',)]print(view.keys) # ('img',)
img, = view[0]# use an index instead of a nameview = dataset.slice[:, 1]
print(view.keys) # 'bbox'
bbox = view[0]# mixture of names and indicesview = dataset.slice[:, (1, 'label')]print(view.keys) # ('bbox', 'label')
bbox, label = view[0]# use booleans# note that the number of booleans should be the same as len(dataset.keys)
view = dataset.slice[:, (True, True, False)](continues on next page)

14

Chapter 2. ChainerCV Tutorial

ChainerCV Documentation, Release 0.13.1(continued from previous page)

print(view.keys) # ('img', 'bbox')
img, bbox = view[0]2.3.4 Usage: slice along with both axes
from chainercv.datasets import VOCBboxDataset
dataset = VOCBboxDataset()# the view of the labels of the first 100 examples
view = dataset.slice[:100, 'label']

2.3.5 Concatenate and transform
ChainerCV provides ConcatenatedDataset and TransformDataset. The difference from chainer.
datasets.ConcatenatedDataset and chainer.datasets.TransformDataset is that they takesliceable dataset(s) and return a sliceable dataset.
from chainercv.chainer_experimental.datasets.sliceable import ConcatenatedDataset
from chainercv.chainer_experimental.datasets.sliceable import TransformDataset
from chainercv.datasets import VOCBboxDataset
from chainercv.datasets import voc_bbox_label_names
dataset_07 = VOCBboxDataset(year='2007')
print('07:', dataset_07.keys, len(dataset_07))# 07: ('img', 'bbox', 'label') 2501

dataset_12 = VOCBboxDataset(year='2012')
print('12:', dataset_12.keys, len(dataset_12))# 12: ('img', 'bbox', 'label') 5717

# concatenate
dataset_0712 = ConcatenatedDataset(dataset_07, dataset_12)
print('0712:', dataset_0712.keys, len(dataset_0712)) # 0712: ('img', 'bbox', 'label
˓→') 8218# transformdef transform(in_data):
img, bbox, label = in_data
dog_lb = voc_bbox_label_names.index('dog')
bbox_dog = bbox[label == dog_lb]
return img, bbox_dog# we need to specify the names of data that the transform function returns
dataset_0712_dog = TransformDataset(dataset_0712, ('img', 'bbox_dog'), transform)
print('0712_dog:', dataset_0712_dog.keys, len(dataset_0712_dog)) # 0712_dog: ('img',
˓→'bbox_dog') 8218

2.3.6 Make your own dataset
ChainerCV provides GetterDataset to construct a new sliceable dataset.
This example implements a sliceable bounding box dataset.

2.3. Sliceable Dataset

15

ChainerCV Documentation, Release 0.13.1

import numpy as np
from chainercv.chainer_experimental.datasets.sliceable import GetterDataset
from chainercv.utils import generate_random_bbox
class SampleBboxDataset(GetterDataset):
def __init__(self):
super(SampleBboxDataset, self).__init__()# register getter method for image
self.add_getter('img', self.get_image)# register getter method for bbox and label
self.add_getter(('bbox', 'label'), self.get_annotation)
def __len__(self):
return 20
def get_image(self, i):print('get_image({})'.format(i))# generate dummy image
img = np.random.uniform(0, 255, size=(3, 224, 224)).astype(np.float32)
return img
def get_annotation(self, i):print('get_annotation({})'.format(i))# generate dummy annotations
bbox = generate_random_bbox(10, (224, 224), 10, 224)
label = np.random.randint(0, 9, size=10).astype(np.int32)
return bbox, label
dataset = SampleBboxDataset()
img, bbox, label = dataset[0]# get_image(0) and get_annotation(0)view = dataset.slice[:, 'label']label = view[1] # get_annotation(1)If you have arrays of data, you can use TupleDataset.
import numpy as np
from chainercv.chainer_experimental.datasets.sliceable import TupleDataset
from chainercv.utils import generate_random_bbox
n = 20imgs = np.random.uniform(0, 255, size=(n, 3, 224, 224)).astype(np.float32)
bboxes = [generate_random_bbox(10, (224, 224), 10, 224) for _ in range(n)]labels = np.random.randint(0, 9, size=(n, 10)).astype(np.int32)
dataset = TupleDataset(('img', imgs), ('bbox', bboxes), ('label', labels))
print(dataset.keys) # ('img', 'bbox', 'label')view = dataset.slice[:, 'label']label = view[1]16Chapter 2. ChainerCV Tutorial

CHAPTER

THREE

CHAINERCV REFERENCE MANUAL

3.1 Chainer Experimental
This module contains WIP modules of Chainer. After they are merged into chainer, these modules will be removed
from ChainerCV.

3.1.1 Datasets
Sliceable
Sliceable
This module support sliceable feature. Please note that this module will be removed after Chainer implements sliceablefeature.
See also:
https://github.com/chainer/chainercv/pull/454
ConcatenatedDataset
class chainercv.chainer_experimental.datasets.sliceable.ConcatenatedDataset(*datasets)
A sliceable version of chainer.datasets.ConcatenatedDataset.
Here is an example.
>>> dataset_a = TupleDataset([0, 1, 2], [0, 1, 4])>>> dataset_b = TupleDataset([3, 4, 5], [9, 16, 25])>>>>>> dataset = ConcatenatedDataset(dataset_a, dataset_b)>>> dataset.slice[:, 0][:] # [0, 1, 2, 3, 4, 5]

Parameters datasets – The underlying datasets.
Sliceabledataset and should have the same keys.

Eachdatasetshouldinheritget_example_by_keys(index, key_indices)
Return data of an example by keys
Parameters• index (int) – An index of an example.

17

ChainerCV Documentation, Release 0.13.1• key_indices (tuple of ints) – A tuple of indices of requested keys.
Returns tuple of data
property keys
Return names of all keys
Returns string or tuple of strings
GetterDataset
class chainercv.chainer_experimental.datasets.sliceable.GetterDataset
A sliceable dataset class that is defined with getters.
This is a dataset class with getters. Please refer to the tutorial for more detailed explanation.
Here is an example.
>>> class SliceableLabeledImageDataset(GetterDataset):>>>
def __init__(self, pairs, root='.'):>>>
super(SliceableLabeledImageDataset, self).__init__()>>>with open(pairs) as f:>>>
self._pairs = [l.split() for l in f]>>>
self._root = root>>>>>>
self.add_getter('img', self.get_image)>>>self.add_getter('label', self.get_label)>>>>>>
def __len__(self):>>>
return len(self._pairs)>>>>>>
def get_image(self, i):>>>path, _ = self._pairs[i]>>>return read_image(os.path.join(self._root, path))>>>>>>
def get_label(self, i):>>>_, label = self._pairs[i]>>>return np.int32(label)>>>>>> dataset = SliceableLabeledImageDataset('list.txt')>>>>>> # get a subset with label = 0, 1, 2>>> # no images are loaded>>> indices = [i for i, label in...
enumerate(dataset.slice[:, 'label']) if label in {0, 1, 2}]>>> dataset_012 = dataset.slice[indices]

add_getter(keys, getter)
Register a getter function
Parameters• keys (string or tuple of strings) – The name(s) of data that the getter function returns.
• getter (callable) – A getter function that takes an index and returns data of thecorresponding example.
get_example_by_keys(index, key_indices)
Return data of an example by keys

18

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• index (int) – An index of an example.
• key_indices (tuple of ints) – A tuple of indices of requested keys.
Returns tuple of data
property keys
Return names of all keys
Returns string or tuple of strings
TupleDataset
class chainercv.chainer_experimental.datasets.sliceable.TupleDataset(*datasets)
A sliceable version of chainer.datasets.TupleDataset.
Here is an example.
>>> # omit keys>>> dataset = TupleDataset([0, 1, 2], [0, 1, 4])>>> dataset.keys # (None, None)>>> dataset.slice[:, 0][:] # [0, 1, 2]>>>>>> dataset_more = TupleDataset(dataset, [0, 1, 8])>>> dataset_more.keys # (None, None, None)>>> dataset_more.slice[:, [1, 2]][:] # [(0, 0), (1, 1), (4, 8)]>>>>>> # specify the name of a key>>> named_dataset = TupleDataset(('feat0', [0, 1, 2]), [0, 1, 4])>>> named_dataset.keys # ('feat0', None)>>> # slice takes both key and index (or their mixture)>>> named_dataset.slice[:, ['feat0', 1]][:] # [(0, 0), (1, 1), (2, 4)]

Parameters datasets – The underlying datasets. The following datasets are acceptable.
• An inheritance of :class:~chainer.datasets.sliceable.SliceableDataset‘.
• A tuple of a name and a data array. The data array should be list or numpy.ndarray.
• A data array. In this case, the name of key is None.
get_example_by_keys(index, key_indices)
Return data of an example by keys
Parameters• index (int) – An index of an example.
• key_indices (tuple of ints) – A tuple of indices of requested keys.
Returns tuple of data
property keys
Return names of all keys
Returns string or tuple of strings

3.1. Chainer Experimental

19

ChainerCV Documentation, Release 0.13.1

TransformDataset
class chainercv.chainer_experimental.datasets.sliceable.TransformDataset(dataset,
keys,
transform=None)
A sliceable version of chainer.datasets.TransformDataset.
Note that it reuqires keys to determine the names of returned values.
Here is an example.
>>> def transfrom(in_data):>>>
img, bbox, label = in_data
>>>
...
>>>
return new_img, new_label>>>>>> dataset = TramsformDataset(dataset, ('img', 'label'), transform)>>> dataset.keys # ('img', 'label')Parameters• dataset – The underlying dataset.
__getitem__().

This dataset should have __len__() and• keys (string or tuple of strings) – The name(s) of data that the transformfunction returns. If this parameter is omitted, __init__() fetches a sample from theunderlying dataset to determine the number of data.
• transform (callable) – A function that is called to transform values returned by theunderlying dataset’s __getitem__().

3.1.2 Training
Extensions
Extensions
make_shift
chainercv.chainer_experimental.training.extensions.make_shift(attr,
optimizer=None)
Decorator to make shift extensions.
This decorator wraps a function and makes a shift extension. Base function should take trainer and return a
new value of attr.
Here is an example.
>>> # define an extension that updates 'lr' attribute>>> @make_shift('lr')>>> def warmup(trainer):>>>
base_lr = 0.01>>>
rate = 0.1>>>>>>
iteration = trainer.updater.iteration(continues on next page)

20

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1(continued from previous page)>>>
if iteration < 1000:>>>
return base_lr * (rate + (1 - rate) * iteraion / 1000)
>>>
else:
>>>
return base_lr>>>>>> # use the extension>>> trainer.extend(warmup)

Parameters• attr (str) – Name of the attribute to shift.
• optimizer (Optimizer) – Target optimizer to adjust the attribute. If it is None, themain optimizer of the updater is used.

3.2 Datasets
3.2.1 General datasets
DirectoryParsingLabelDataset
class chainercv.datasets.DirectoryParsingLabelDataset(root, check_img_file=None,
color=True,
numerical_sort=False)
A label dataset whose label names are the names of the subdirectories.
The label names are the names of the directories that locate a layer below the root directory. All images locating under the subdirectoies will be categorized to classes with subdirectory names. An image is parsed
only when the function check_img_file returns True by taking the path to the image as an argument. If
check_img_file is None, the path with any image extensions will be parsed.
ExampleA directory structure should be one like below.
root|-- class_0||-- img_0.png||-- img_1.png|--- class_1|-- img_0.png>>> from chainercv.datasets import DirectoryParsingLabelDataset>>> dataset = DirectoryParsingLabelDataset('root')>>> dataset.img_paths['root/class_0/img_0.png', 'root/class_0/img_1.png','root_class_1/img_0.png']>>> dataset.labels
array([0, 0, 1])

Parameters3.2. Datasets

21

ChainerCV Documentation, Release 0.13.1• root (string) – The root directory.
• check_img_file (callable) – A function to determine if a file should be included in
the dataset.
• color (bool) – If True, this dataset read images as color images. The default value isTrue.
• numerical_sort (bool) – Label names are sorted numerically. This means that label 2
is before label 10, which is not the case when string sort is used. Regardless of this option,
string sort is used for the order of files with the same label. The default value is False.
This dataset returns the following data.
name
img
label

shape
(3, 𝐻, 𝑊 )1
scalardtype
float32
int32

format
RGB, [0, 255]
[0, #𝑐𝑙𝑎𝑠𝑠 − 1]

directory_parsing_label_names
chainercv.datasets.directory_parsing_label_names(root, numerical_sort=False)
Get label names from the directories that are named by them.
The label names are the names of the directories that locate a layer below the root directory.
The label names can be used together with DirectoryParsingLabelDataset. The index of a label namecorresponds to the label id that is used by the dataset to refer the label.
Parameters• root (string) – The root directory.
• numerical_sort (bool) – Label names are sorted numerically. This means that label
2 is before label 10, which is not the case when string sort is used. The default value isFalse.
Returns Sorted names of classes.
Return type list of strings
MixUpSoftLabelDataset
class chainercv.datasets.MixUpSoftLabelDataset(dataset, n_class, alpha=1.0)
Dataset which returns mixed images and labels for mixup learning2 .
MixUpSoftLabelDataset mixes two pairs of labeled images fetched from the base dataset.
Unlike LabeledImageDatasets, label is a one-dimensional float array with at most two nonnegative weights (i.e.
soft label). The sum of the two weights is one.
ExampleWe construct a mixup dataset from MNIST.
1 (1, 𝐻, 𝑊 ) if color= False.

2 Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz. mixup: Beyond Empirical Risk Minimization. arXiv 2017.

22

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1>>> from chainer.datasets import get_mnist>>> from chainercv.datasets import SiameseDataset>>> from chainercv.datasets import MixUpSoftLabelDataset>>> mnist, _ = get_mnist()>>> base_dataset = SiameseDataset(mnist, mnist)>>> dataset = MixUpSoftLabelDataset(base_dataset, 10)>>> mixed_image, mixed_label = dataset[0]>>> mixed_label.shape(10,)>>> mixed_label.dtype
dtype('float32')

Parameters• dataset – The underlying dataset. The dataset returns img_0, label_0, img_1,
label_1, which is a tuple containing two pairs of an image and a label. Typically, dataset
is SiameseDataset.
The shapes of images and labels should be constant.
• n_class (int) – The number of classes in the base dataset.
• alpha (float) – A hyperparameter of Beta distribution. mix_ratio is sampled from𝐵(𝛼, 𝛼). The default value is 1.0 meaning that the distribution is the same as Uniform
distribution with lower boundary of 0.0 and upper boundary of 1.0.
This dataset returns the following data.
name
img
label

shape

dtype

format3

33(#𝑐𝑙𝑎𝑠𝑠, )float32[0, 1]

SiameseDataset
class chainercv.datasets.SiameseDataset(dataset_0,
dataset_1,
pos_ratio=None,
length=None, labels_0=None, labels_1=None)
A dataset that returns samples fetched from two datasets.
The dataset returns samples from the two base datasets. If pos_ratio is not None, SiameseDataset
can be configured to return positive pairs at the ratio of pos_ratio and negative pairs at the ratio of 1 pos_ratio. In this mode, the base datasets are assumed to be label datasets that return an image and a label
as a sample.
ExampleWe construct a siamese dataset from MNIST.
>>> from chainer.datasets import get_mnist>>> from chainercv.datasets import SiameseDataset>>> mnist, _ = get_mnist()>>> dataset = SiameseDataset(mnist, mnist, pos_ratio=0.3)# The probability of the two samples having the same label(continues on next page)3 Same as dataset.

3.2. Datasets

23

ChainerCV Documentation, Release 0.13.1(continued from previous page)# is 0.3 as specified by pos_ratio.
>>> img_0, label_0, img_1, label_1 = dataset[0]# The returned examples may change in the next
# call even if the index is the same as before# because SiameseDataset picks examples randomly# (e.g., img_0_new may differ from img_0).
>>> img_0_new, label_0_new, img_1_new, label_1_new = dataset[0]Parameters• dataset_0 – The first base dataset.
• dataset_1 – The second base dataset.
• pos_ratio (float) – If this is not None, this dataset tries to construct positive pairs at
the given rate. If None, this dataset randomly samples examples from the base datasets.
The default value is None.
• length (int) – The length of this dataset. If None, the length of the first base dataset isthe length of this dataset.
• labels_0 (numpy.ndarray) – The labels associated to the first base dataset. The
length should be the same as the length of the first dataset. If this is None, the labels are automatically fetched using the following line of code: [ex[1] for ex indataset_0]. By setting labels_0 and skipping the fetching iteration, the computation
cost can be reduced. Also, if pos_ratio is None, this value is ignored. The default
value is None. If labels_1 is spcified and dataset_0 and dataset_1 are the same,labels_0 can be skipped.
• labels_1 (numpy.ndarray) – The labels associated to the second base dataset. Iflabels_0 is spcified and dataset_0 and dataset_1 are the same, labels_1 canbe skipped. Please consult the explanation for labels_0.
This dataset returns the following data.
name
img_0
label_0
img_1
label_1

shape

dtype

format4

4

4scalarint32[0, #𝑐𝑙𝑎𝑠𝑠 − 1]

5

5

5

scalarint32[0, #𝑐𝑙𝑎𝑠𝑠 − 1]

3.2.2 ADE20K
ADE20KSemanticSegmentationDataset
class chainercv.datasets.ADE20KSemanticSegmentationDataset(data_dir=’auto’,split=’train’)
Semantic segmentation dataset for ADE20K.
This is ADE20K dataset distributed in MIT Scene Parsing Benchmark website. It has 20,210 training images
and 2,000 validation images.
4 Same as dataset_0.
5 Same as dataset_1.

24

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• data_dir (string) – Path to the dataset directory. The directory should contain the
ADEChallengeData2016 directory. And that directory should contain at least images
and annotations directries. If auto is given, the dataset is automatically downloaded
into $CHAINER_DATASET_ROOT/pfnet/chainercv/ade20k.
• split ({'train', 'val'}) – Select from dataset splits used in MIT Scene Parsing
Benchmark dataset (ADE20K).
This dataset returns the following data.
name
img
label

shape
(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

ADE20KTestImageDataset
class chainercv.datasets.ADE20KTestImageDataset(data_dir=’auto’)
Image dataset for test split of ADE20K.
This is an image dataset of test split in ADE20K dataset distributed at MIT Scene Parsing Benchmark website.
It has 3,352 test images.
Parameters data_dir (string) – Path to the dataset directory. The directory should contain the release_test dir. If auto is given, the dataset is automatically downloaded into
$CHAINER_DATASET_ROOT/pfnet/chainercv/ade20k.
This dataset returns the following data.
name
img

shape
(3, 𝐻, 𝑊 )dtype
float32

format
RGB, [0, 255]

3.2.3 CamVid
CamVidDataset
class chainercv.datasets.CamVidDataset(data_dir=’auto’, split=’train’)
Semantic segmentation dataset for CamVid.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/camvid.
• split ({'train', 'val', 'test'}) – Select from dataset splits used in CamVid
Dataset.
This dataset returns the following data.
name
img
label

3.2. Datasets

shape(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]25

ChainerCV Documentation, Release 0.13.1

3.2.4 Cityscapes
CityscapesSemanticSegmentationDataset
class chainercv.datasets.CityscapesSemanticSegmentationDataset(data_dir=’auto’,label_resolution=None,
split=’train’, ignore_labels=True)
Semantic segmentation dataset for Cityscapes dataset.
Note: Please manually download the data because it is not allowed to re-distribute Cityscapes dataset.

Parameters• data_dir (string) – Path to the dataset directory. The directory should contain at least
two directories, leftImg8bit and either gtFine or gtCoarse. If auto is given, it
uses $CHAINER_DATSET_ROOT/pfnet/chainercv/cityscapes by default.
• label_resolution ({'fine', 'coarse'}) – The resolution of the labels. It
should be either fine or coarse.
• split ({'train', 'val'}) – Select from dataset splits used in Cityscapes dataset.
• ignore_labels (bool) – If True, the labels marked ignoreInEval defined in theoriginal cityscapesScripts will be replaced with -1 in the get_example() method. The
default value is True.
This dataset returns the following data.
name
img
label

shape
(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

CityscapesTestImageDataset
class chainercv.datasets.CityscapesTestImageDataset(data_dir=’auto’)
Image dataset for test split of Cityscapes dataset.
Note: Please manually download the data because it is not allowed to re-distribute Cityscapes dataset.

Parameters data_dir (string) – Path to the dataset directory. The directory should contain theleftImg8bit directory. If auto is given, it uses $CHAINER_DATSET_ROOT/pfnet/
chainercv/cityscapes by default.
This dataset returns the following data.
name
img

26

shape
(3, 𝐻, 𝑊 )dtype
float32

format
RGB, [0, 255]

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

3.2.5 CUB
CUBLabelDataset
class chainercv.datasets.CUBLabelDataset(data_dir=’auto’,return_bbox=False,
prob_map_dir=’auto’, return_prob_map=False)
Caltech-UCSD Birds-200-2011 dataset with annotated class labels.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/cub.
• return_bbox (bool) – If True, this returns a bounding box around a bird. The default
value is False.
• prob_map_dir (string) – Path to the root of the probability maps. If this is auto,
this class will automatically download data for you under $CHAINER_DATASET_ROOT/
pfnet/chainercv/cub.
• return_prob_map (bool) – Decide whether to include a probability map of the bird in
a tuple served for a query. The default value is False.
This dataset returns the following data.
name
img
label
bbox6
prob_map7

shape(3, 𝐻, 𝑊 )scalar
(1, 4)(𝐻, 𝑊 )

dtype
float32
int32
float32
float32

format
RGB, [0, 255]
[0, #𝑐𝑙𝑎𝑠𝑠 − 1](𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, 1]

CUBKeypointDataset
class chainercv.datasets.CUBKeypointDataset(data_dir=’auto’,return_bbox=False,
prob_map_dir=’auto’,return_prob_map=False)
Caltech-UCSD Birds-200-2011 dataset with annotated points.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/cub.
• return_bbox (bool) – If True, this returns a bounding box around a bird. The default
value is False.
• prob_map_dir (string) – Path to the root of the probability maps. If this is auto,
this class will automatically download data for you under $CHAINER_DATASET_ROOT/
pfnet/chainercv/cub.
• return_prob_map (bool) – Decide whether to include a probability map of the bird in
a tuple served for a query. The default value is False.
6 bb indicates the location of a bird. It is available if return_bbox= True.

7 prob_map indicates how likey a bird is located at each the pixel. It is available if return_prob_map

3.2. Datasets= True.

27

ChainerCV Documentation, Release 0.13.1

This dataset returns the following data.
name
img
point
visiblebbox8
prob_map9

shape(3, 𝐻, 𝑊 )(1, 15, 2)(1, 15)(1, 4)(𝐻, 𝑊 )

dtype
float32
float32bool
float32
float32

format
RGB, [0, 255]
(𝑦, 𝑥)–(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, 1]

3.2.6 MS COCO
COCOBboxDataset
class chainercv.datasets.COCOBboxDataset(data_dir=’auto’, split=’train’, year=’2017’,
use_crowded=False, return_area=False, return_crowded=False)
Bounding box dataset for MS COCO.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/coco.
• split ({'train', 'val', 'minival', 'valminusminival'}) – Select asplit of the dataset.
• year ({'2014', '2017'}) – Use a dataset released in year. Splits minival andvalminusminival are only supported in year 2014.
• use_crowded (bool) – If true, use bounding boxes that are labeled as crowded in theoriginal annotation. The default value is False.
• return_area (bool) – If true, this dataset returns areas of masks around objects. The
default value is False.
• return_crowded (bool) – If true, this dataset returns a boolean array that indicates
whether bounding boxes are labeled as crowded or not. The default value is False.
This dataset returns the following data.
nameimg
bbox10label10
area1011
crowded12

shape(3, 𝐻, 𝑊 )(𝑅, 4)
(𝑅, )
(𝑅, )
(𝑅, )

dtype
float32
float32
int32
float32bool

format
RGB, [0, 255]
(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––

When there are more than ten objects from the same category, bounding boxes correspond to crowd of instances
instead of individual instances. Please see more detail in the Fig. 12 (e) of the summary paper13 .
8 bb indicates the location of a bird. It is available if return_bbox= True.

9 prob_map indicates how likey a bird is located at each the pixel. It is available if return_prob_map= True.
= True, bbox, label and area contain crowded instances.
11 area is available if return_area = True.
12 crowded is available if return_crowded = True.
13 Tsung-Yi Lin, Michael Maire, Serge Belongie, Lubomir Bourdev, Ross Girshick, James Hays, Pietro Perona, Deva Ramanan, C. Lawrence

10 If use_crowded

28

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

COCOInstanceSegmentationDataset
class chainercv.datasets.COCOInstanceSegmentationDataset(data_dir=’auto’,split=’train’,
year=’2017’,
use_crowded=False,
return_crowded=False,
return_area=False,
return_bbox=False)
Instance segmentation dataset for MS COCO.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/coco.
• split ({'train', 'val', 'minival', 'valminusminival'}) – Select asplit of the dataset.
• year ({'2014', '2017'}) – Use a dataset released in year. Splits minival andvalminusminival are only supported in year 2014.
• use_crowded (bool) – If true, use masks that are labeled as crowded in the original
annotation.
• return_crowded (bool) – If true, this dataset returns a boolean array that indicates
whether masks are labeled as crowded or not. The default value is False.
• return_area (bool) – If true, this dataset returns areas of masks around objects.
• return_bbox (bool) – If true, this dataset returns bounding boxes arround objects.
This dataset returns the following data.
nameimg
mask14label14
area1415
crowded16
bbox10shape(3, 𝐻, 𝑊 )(𝑅, 𝐻, 𝑊 )
(𝑅, )
(𝑅, )
(𝑅, )
(𝑅, 4)

dtype
float32
bool
int32
float32bool
float32

format
RGB, [0, 255]–
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )When there are more than ten objects from the same category, masks correspond to crowd of instances insteadof individual instances. Please see more detail in the Fig. 12 (e) of the summary paper17 .
COCOSemanticSegmentationDataset
class chainercv.datasets.COCOSemanticSegmentationDataset(data_dir=’auto’,split=’train’)
Semantic segmentation dataset for MS COCO.
Semantic segmentations are generated from panoptic segmentations as done in the official toolkit.
Zitnick, Piotr Dollar. Microsoft COCO: Common Objects in Context. arXiv 2014.
14 If use_crowded = True, mask, label, area and bbox contain crowded instances.
15 area is available if return_area = True.
16 crowded is available if return_crowded = True.
17 Tsung-Yi Lin, Michael Maire, Serge Belongie, Lubomir Bourdev, Ross Girshick, James Hays, Pietro Perona, Deva Ramanan, C. Lawrence
Zitnick, Piotr Dollar. Microsoft COCO: Common Objects in Context. arXiv 2014.

3.2. Datasets

29

ChainerCV Documentation, Release 0.13.1

Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/coco.
• split ({'train', 'val'}) – Select a split of the dataset.
This dataset returns the following data.
name
img
label

shape
(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

3.2.7 OnlineProducts
OnlineProductsDataset
class chainercv.datasets.OnlineProductsDataset(data_dir=’auto’, split=’train’)
Dataset class for Stanford Online Products Dataset.
The split selects train and test split of the dataset as done in18 . The train split contains the first 11318 classes
and the test split contains the remaining 11316 classes.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/online_products.
• split ({'train', 'test'}) – Select a split of the dataset.
This dataset returns the following data.
name
img
label
super_label

shape(3, 𝐻, 𝑊 )scalarscalardtype
float32
int32
int32

format
RGB, [0, 255]
[0, #𝑐𝑙𝑎𝑠𝑠 − 1]
[0, #𝑠𝑢𝑝𝑒𝑟_𝑐𝑙𝑎𝑠𝑠 − 1]

3.2.8 PASCAL VOC
VOCBboxDataset
class chainercv.datasets.VOCBboxDataset(data_dir=’auto’,split=’train’,
year=’2012’,
use_difficult=False, return_difficult=False)
Bounding box dataset for PASCAL VOC.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/voc.
• split ({'train', 'val', 'trainval', 'test'}) – Select a split of thedataset. test split is only available for 2007 dataset.
18 Hyun Oh Song, Yu Xiang, Stefanie Jegelka, Silvio Savarese. Deep Metric Learning via Lifted Structured Feature Embedding. arXiv 2015.

30

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• year ({'2007', '2012'}) – Use a dataset prepared for a challenge held in year.
• use_difficult (bool) – If True, use images that are labeled as difficult in the original
annotation.
• return_difficult (bool) – If True, this dataset returns a boolean array that indicates
whether bounding boxes are labeled as difficult or not. The default value is False.
This dataset returns the following data.
nameimg
bbox19label19difficult (optional20 )shape(3, 𝐻, 𝑊 )(𝑅, 4)
(𝑅, )
(𝑅, )

dtype
float32
float32
int32
boolformat
RGB, [0, 255]
(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–

VOCInstanceSegmentationDataset
class chainercv.datasets.VOCInstanceSegmentationDataset(data_dir=’auto’,split=’train’)
Instance segmentation dataset for PASCAL VOC2012.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/voc.
• split ({'train', 'val', 'trainval'}) – Select a split of the dataset.
This dataset returns the following data.
name
img
mask
label

shape
(3, 𝐻, 𝑊 )(𝑅, 𝐻, 𝑊 )
(𝑅, )

dtype
float32
bool
int32

format
RGB, [0, 255]–
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]

VOCSemanticSegmentationDataset
class chainercv.datasets.VOCSemanticSegmentationDataset(data_dir=’auto’,split=’train’)
Semantic segmentation dataset for PASCAL VOC2012.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/voc.
• split ({'train', 'val', 'trainval'}) – Select a split of the dataset.
This dataset returns the following data.
19 If use_difficult= True, bbox and label contain difficult instances.
= True.

20 difficult is available if return_difficult

3.2. Datasets

31

ChainerCV Documentation, Release 0.13.1

name
img
label

shape
(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

3.2.9 Semantic Boundaries Dataset
SBDInstanceSegmentationDataset
class chainercv.datasets.SBDInstanceSegmentationDataset(data_dir=’auto’,split=’train’)
Instance segmentation dataset for Semantic Boundaries Dataset SBD.
Parameters• data_dir (string) – Path to the root of the training data. If this is auto, this classwill automatically download data for you under $CHAINER_DATASET_ROOT/pfnet/
chainercv/sbd.
• split ({'train', 'val', 'trainval'}) – Select a split of the dataset.
This dataset returns the following data.
name
img
mask
label

shape
(3, 𝐻, 𝑊 )(𝑅, 𝐻, 𝑊 )
(𝑅, )

dtype
float32
bool
int32

format
RGB, [0, 255]–
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]

3.3 Evaluations
3.3.1 Detection COCO
eval_detection_coco
chainercv.evaluations.eval_detection_coco(pred_bboxes,
pred_labels,
pred_scores,
gt_bboxes,
gt_labels,
gt_areas=None,
gt_crowdeds=None)
Evaluate detections based on evaluation code of MS COCO.
This function evaluates predicted bounding boxes obtained from a dataset by using average precision for eachclass. The code is based on the evaluation code used in MS COCO.
Parameters• pred_bboxes (iterable of numpy.ndarray) – See the table below.
• pred_labels (iterable of numpy.ndarray) – See the table below.
• pred_scores (iterable of numpy.ndarray) – See the table below.
• gt_bboxes (iterable of numpy.ndarray) – See the table below.
• gt_labels (iterable of numpy.ndarray) – See the table below.
• gt_areas (iterable of numpy.ndarray) – See the table below. If None, somescores are not returned.

32

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• gt_crowdeds (iterable of numpy.ndarray) – See the table below.
namepred_bboxes
pred_labels
pred_scores
gt_bboxes
gt_labels
gt_areas
gt_crowdeds

shape[(𝑅, 4)][(𝑅, )][(𝑅, )][(𝑅, 4)][(𝑅, )][(𝑅, )][(𝑅, )]

dtype
float32
int32
float32
float32
int32
float32bool

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––

All inputs should have the same length. For more detailed explanation of the inputs, please refer tochainercv.datasets.COCOBboxDataset.
See also:
chainercv.datasets.COCOBboxDataset.
Returns
The keys, value-types and the description of the values are listed below. The APs and ARs calculated with different iou thresholds, sizes of objects, and numbers of detections per image. For
more details on the 12 patterns of evaluation metrics, please refer to COCO’s official evaluation
page.
key
type
ap/iou=0.50:0.95/area=all/max_dets=100numpy.ndarray
ap/iou=0.50/area=all/max_dets=100
numpy.ndarray
ap/iou=0.75/area=all/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=small/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=medium/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=large/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=all/max_dets=1 numpy.ndarray
ar/iou=0.50/area=all/max_dets=10
numpy.ndarray
ar/iou=0.75/area=all/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=small/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=medium/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=large/max_dets=100
numpy.ndarray
map/iou=0.50:0.95/area=all/max_dets=100
float
map/iou=0.50/area=all/max_dets=100 float
map/iou=0.75/area=all/max_dets=100 float
map/iou=0.50:0.95/area=small/max_dets=100
float
map/iou=0.50:0.95/area=medium/max_dets=100
float
map/iou=0.50:0.95/area=large/max_dets=100
float
mar/iou=0.50:0.95/area=all/max_dets=1 float
mar/iou=0.50/area=all/max_dets=10
float
mar/iou=0.75/area=all/max_dets=100 float
mar/iou=0.50:0.95/area=small/max_dets=100
float
mar/iou=0.50:0.95/area=medium/max_dets=100
float
mar/iou=0.50:0.95/area=large/max_dets=100
float
coco_eval
pycocotools.cocoeval.COCOeval
existent_labels
numpy.ndarray

3.3. Evaluations

description
1
1
1
15
15
15
2
2
2
25
25
25
3
3
3
35
35
35
4
4
4
45
45
45

resultfrompycocotools
used labels

33

ChainerCV Documentation, Release 0.13.1

Return type dict

3.3.2 Detection VOC
eval_detection_voc
chainercv.evaluations.eval_detection_voc(pred_bboxes,
pred_labels,
pred_scores,
gt_bboxes,
gt_labels,
gt_difficults=None,
iou_thresh=0.5, use_07_metric=False)
Calculate average precisions based on evaluation code of PASCAL VOC.
This function evaluates predicted bounding boxes obtained from a dataset which has 𝑁 images by using average
precision for each class. The code is based on the evaluation code used in PASCAL VOC Challenge.
Parameters• pred_bboxes (iterable of numpy.ndarray) – See the table below.
• pred_labels (iterable of numpy.ndarray) – See the table below.
• pred_scores (iterable of numpy.ndarray) – See the table below.
• gt_bboxes (iterable of numpy.ndarray) – See the table below.
• gt_labels (iterable of numpy.ndarray) – See the table below.
• gt_difficults (iterable of numpy.ndarray) – See the table below. By default, this is None. In that case, this function considers all bounding boxes to be not difficult.
• iou_thresh (float) – A prediction is correct if its Intersection over Union with theground truth is above this value.
• use_07_metric (bool) – Whether to use PASCAL VOC 2007 evaluation metric for
calculating average precision. The default value is False.
namepred_bboxes
pred_labels
pred_scores
gt_bboxes
gt_labels
gt_difficults

shape[(𝑅, 4)][(𝑅, )][(𝑅, )][(𝑅, 4)][(𝑅, )][(𝑅, )]

dtype
float32
int32
float32
float32
int32
boolformat(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–

Returns
The keys, value-types and the description of the values are listed below.
• ap (numpy.ndarray): An array of average precisions. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels or gt_labels,
the corresponding value is set to numpy.nan.
• map (float): The average of Average Precisions over classes.
1 An array of average precisions. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels

or gt_labels, the corresponding value is set to numpy.nan.
5 Skip if gt_areas is None.
2 An array of average recalls. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels
or gt_labels, the corresponding value is set to numpy.nan.
3 The average of average precisions over classes.
4 The average of average recalls over classes.

34

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Return type dictcalc_detection_voc_ap
chainercv.evaluations.calc_detection_voc_ap(prec, rec, use_07_metric=False)
Calculate average precisions based on evaluation code of PASCAL VOC.
This function calculates average precisions from given precisions and recalls. The code is based on the evaluation code used in PASCAL VOC Challenge.
Parameters• prec (list of numpy.array) – A list of arrays. prec[l] indicates precision forclass 𝑙. If prec[l] is None, this function returns numpy.nan for class 𝑙.
• rec (list of numpy.array) – A list of arrays. rec[l] indicates recall for class 𝑙.
If rec[l] is None, this function returns numpy.nan for class 𝑙.
• use_07_metric (bool) – Whether to use PASCAL VOC 2007 evaluation metric for
calculating average precision. The default value is False.
Returns This function returns an array of average precisions. The 𝑙-th value corresponds to theaverage precision for class 𝑙. If prec[l] or rec[l] is None, the corresponding value is set
to numpy.nan.
Return type ndarraycalc_detection_voc_prec_rec
chainercv.evaluations.calc_detection_voc_prec_rec(pred_bboxes,
pred_labels,
pred_scores,
gt_bboxes,
gt_labels,
gt_difficults=None,
iou_thresh=0.5)
Calculate precision and recall based on evaluation code of PASCAL VOC.
This function calculates precision and recall of predicted bounding boxes obtained from a dataset which has 𝑁
images. The code is based on the evaluation code used in PASCAL VOC Challenge.
Parameters• pred_bboxes (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_detection_voc().
• pred_labels (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_detection_voc().
• pred_scores (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_detection_voc().
• gt_bboxes (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_detection_voc().
• gt_labels (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_detection_voc().
• gt_difficults (iterable of numpy.ndarray) – See the table inchainercv.evaluations.eval_detection_voc().
By default, this isNone. In that case, this function considers all bounding boxes to be not difficult.
• iou_thresh (float) – A prediction is correct if its Intersection over Union with theground truth is above this value..
3.3. Evaluations

35

ChainerCV Documentation, Release 0.13.1

Returns
This function returns two lists: prec and rec.
• prec: A list of arrays. prec[l] is precision for class 𝑙. If class 𝑙 does not exist in either
pred_labels or gt_labels, prec[l] is set to None.
• rec: A list of arrays. rec[l] is recall for class 𝑙. If class 𝑙 that is not marked as difficult
does not exist in gt_labels, rec[l] is set to None.
Return type tuple of two lists

3.3.3 Instance Segmentation COCO
eval_instance_segmentation_coco
chainercv.evaluations.eval_instance_segmentation_coco(pred_masks,
pred_labels,
pred_scores,
gt_masks,
gt_labels,
gt_areas=None,
gt_crowdeds=None)
Evaluate instance segmentations based on evaluation code of MS COCO.
This function evaluates predicted instance segmentations obtained from a dataset by using average precision foreach class. The code is based on the evaluation code used in MS COCO.
Parameters• pred_masks (iterable of numpy.ndarray) – See the table below.
• pred_labels (iterable of numpy.ndarray) – See the table below.
• pred_scores (iterable of numpy.ndarray) – See the table below.
• gt_masks (iterable of numpy.ndarray) – See the table below.
• gt_labels (iterable of numpy.ndarray) – See the table below.
• gt_areas (iterable of numpy.ndarray) – See the table below. If None, somescores are not returned.
• gt_crowdeds (iterable of numpy.ndarray) – See the table below.
namepred_masks
pred_labels
pred_scores
gt_masks
gt_labels
gt_areas
gt_crowdeds

shape[(𝑅, 𝐻, 𝑊 )][(𝑅, )][(𝑅, )][(𝑅, 𝐻, 𝑊 )][(𝑅, )][(𝑅, )][(𝑅, )]

dtype
bool
int32
float32
bool
int32
float32bool

format–[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––

All inputs should have the same length. For more detailed explanation of the inputs, please refer tochainercv.datasets.COCOInstanceSegmentationDataset.
See also:
chainercv.datasets.COCOInstanceSegmentationDataset.
Returns

36

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

The keys, value-types and the description of the values are listed below. The APs and ARs calculated with different iou thresholds, sizes of objects, and numbers of detections per image. For
more details on the 12 patterns of evaluation metrics, please refer to COCO’s official evaluation
page.
key
type
ap/iou=0.50:0.95/area=all/max_dets=100numpy.ndarray
ap/iou=0.50/area=all/max_dets=100
numpy.ndarray
ap/iou=0.75/area=all/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=small/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=medium/max_dets=100
numpy.ndarray
ap/iou=0.50:0.95/area=large/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=all/max_dets=1 numpy.ndarray
ar/iou=0.50/area=all/max_dets=10
numpy.ndarray
ar/iou=0.75/area=all/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=small/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=medium/max_dets=100
numpy.ndarray
ar/iou=0.50:0.95/area=large/max_dets=100
numpy.ndarray
map/iou=0.50:0.95/area=all/max_dets=100
float
map/iou=0.50/area=all/max_dets=100 float
map/iou=0.75/area=all/max_dets=100 float
map/iou=0.50:0.95/area=small/max_dets=100
float
map/iou=0.50:0.95/area=medium/max_dets=100
float
map/iou=0.50:0.95/area=large/max_dets=100
float
mar/iou=0.50:0.95/area=all/max_dets=1 float
mar/iou=0.50/area=all/max_dets=10
float
mar/iou=0.75/area=all/max_dets=100 float
mar/iou=0.50:0.95/area=small/max_dets=100
float
mar/iou=0.50:0.95/area=medium/max_dets=100
float
mar/iou=0.50:0.95/area=large/max_dets=100
float
coco_eval
pycocotools.cocoeval.COCOeval
existent_labels
numpy.ndarraydescription
6
6
6
610
610
610
7
7
7
710
710
710
8
8
8
810
810
810
9
9
9
910
910
910

resultfrompycocotools
used labels

Return type dict

3.3.4 Instance Segmentation VOC
eval_instance_segmentation_voc
chainercv.evaluations.eval_instance_segmentation_voc(pred_masks,
pred_labels,
pred_scores,
gt_masks,
gt_labels,
iou_thresh=0.5,
use_07_metric=False)
Calculate average precisions based on evaluation code of PASCAL VOC.
6 An array of average precisions. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels
or gt_labels, the corresponding value is set to numpy.nan.
10 Skip if gt_areas is None.
7 An array of average recalls. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels
or gt_labels, the corresponding value is set to numpy.nan.
8 The average of average precisions over classes.
9 The average of average recalls over classes.

3.3. Evaluations

37

ChainerCV Documentation, Release 0.13.1

This function evaluates predicted masks obtained from a dataset which has 𝑁 images by using average precision
for each class. The code is based on the evaluation code used in FCIS.
Parameters• pred_masks (iterable of numpy.ndarray) – See the table below.
• pred_labels (iterable of numpy.ndarray) – See the table below.
• pred_scores (iterable of numpy.ndarray) – See the table below.
• gt_masks (iterable of numpy.ndarray) – See the table below.
• gt_labels (iterable of numpy.ndarray) – See the table below.
• iou_thresh (float) – A prediction is correct if its Intersection over Union with theground truth is above this value.
• use_07_metric (bool) – Whether to use PASCAL VOC 2007 evaluation metric for
calculating average precision. The default value is False.
namepred_masks
pred_labels
pred_scores
gt_masks
gt_labels

shape[(𝑅, 𝐻, 𝑊 )][(𝑅, )][(𝑅, )][(𝑅, 𝐻, 𝑊 )][(𝑅, )]

dtype
bool
int32
float32
bool
int32

format–[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]––
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]

Returns
The keys, value-types and the description of the values are listed below.
• ap (numpy.ndarray): An array of average precisions. The 𝑙-th value corresponds to the average precision for class 𝑙. If class 𝑙 does not exist in either pred_labels or gt_labels,
the corresponding value is set to numpy.nan.
• map (float): The average of Average Precisions over classes.
Return type dictcalc_instance_segmentation_voc_prec_rec
chainercv.evaluations.calc_instance_segmentation_voc_prec_rec(pred_masks,
pred_labels,
pred_scores,
gt_masks,
gt_labels,
iou_thresh)
Calculate precision and recall based on evaluation code of PASCAL VOC.
This function calculates precision and recall of predicted masks obtained from a dataset which has 𝑁 images.
The code is based on the evaluation code used in FCIS.
Parameters• pred_masks (iterable of numpy.ndarray) – An iterable of 𝑁 sets of masks. Its
index corresponds to an index for the base dataset. Each element of pred_masks is anobject mask and is an array whose shape is (𝑅, 𝐻, 𝑊 ), where 𝑅 corresponds to the numberof masks, which may vary among images.

38

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• pred_labels (iterable of numpy.ndarray) – An iterable of labels. Similar topred_masks, its index corresponds to an index for the base dataset. Its length is 𝑁 .
• pred_scores (iterable of numpy.ndarray) – An iterable of confidence scoresfor predicted masks. Similar to pred_masks, its index corresponds to an index for thebase dataset. Its length is 𝑁 .
• gt_masks (iterable of numpy.ndarray) – An iterable of ground truth masks
whose length is 𝑁 . An element of gt_masks is an object mask whose shape is (𝑅, 𝐻, 𝑊 ).
Note that the number of masks 𝑅 in each image does not need to be same as the number ofcorresponding predicted masks.
• gt_labels (iterable of numpy.ndarray) – An iterable of ground truth labels
which are organized similarly to gt_masks. Its length is 𝑁 .
• iou_thresh (float) – A prediction is correct if its Intersection over Union with theground truth is above this value.
Returns
This function returns two lists: prec and rec.
• prec: A list of arrays. prec[l] is precision for class 𝑙. If class 𝑙 does not exist in either
pred_labels or gt_labels, prec[l] is set to None.
• rec: A list of arrays. rec[l] is recall for class 𝑙. If class 𝑙 that is not marked as difficult
does not exist in gt_labels, rec[l] is set to None.
Return type tuple of two lists

3.3.5 Semantic Segmentation IoU
eval_semantic_segmentation
chainercv.evaluations.eval_semantic_segmentation(pred_labels, gt_labels)
Evaluate metrics used in Semantic Segmentation.
This function calculates Intersection over Union (IoU), Pixel Accuracy and Class Accuracy for the task ofsemantic segmentation.
The definition of metrics calculated by this function is as follows, where 𝑁𝑖𝑗 is the number of pixels that arelabeled as class 𝑖 by the ground truth and class 𝑗 by the prediction.
𝑁𝑖𝑖
∑︀
𝑘

• IoU of the i-th class = ∑︀𝑘𝑗=1 𝑁𝑖𝑗 +∑︀𝑘
1• mIoU = 𝑘•

𝑖=1

𝑗=1 𝑁𝑗𝑖 −𝑁𝑖𝑖

𝑁𝑖𝑖
∑︀
𝑘

∑︀𝑘

𝑗=1 𝑁𝑖𝑗 +𝑗=1 𝑁𝑗𝑖 −𝑁𝑖𝑖∑︀𝑘𝑁∑︀𝑘 𝑖𝑖
Pixel Accuracy = ∑︀𝑘 𝑖=1
𝑖=1
𝑗=1 𝑁𝑖𝑗• Class Accuracy = ∑︀𝑘𝑁𝑖𝑖𝑁
𝑗=1

•

𝑖𝑗

Mean Class Accuracy = 𝑘1

∑︀𝑘

𝑖=1

∑︀𝑘𝑁𝑖𝑖𝑗=1 𝑁𝑖𝑗

The more detailed description of the above metrics can be found in a review on semantic segmentation11 .
The number of classes 𝑛_𝑐𝑙𝑎𝑠𝑠 is 𝑚𝑎𝑥(𝑝𝑟𝑒𝑑_𝑙𝑎𝑏𝑒𝑙𝑠, 𝑔𝑡_𝑙𝑎𝑏𝑒𝑙𝑠) + 1, which is the maximum class id of the
inputs added by one.
11 Alberto Garcia-Garcia, Sergio Orts-Escolano, Sergiu Oprea, Victor Villena-Martinez, Jose Garcia-Rodriguez. A Review on Deep Learning
Techniques Applied to Semantic Segmentation. arXiv 2017.

3.3. Evaluations

39

ChainerCV Documentation, Release 0.13.1

Parameters• pred_labels (iterable of numpy.ndarray) – See the table below.
• gt_labels (iterable of numpy.ndarray) – See the table below.
namepred_labels
gt_labels

shape[(𝐻, 𝑊 )][(𝐻, 𝑊 )]

dtype
int32
int32

format[0, #𝑐𝑙𝑎𝑠𝑠 − 1][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

Returns
The keys, value-types and the description of the values are listed below.
• iou (numpy.ndarray): An array of IoUs for the 𝑛_𝑐𝑙𝑎𝑠𝑠 classes. Its shape is (𝑛_𝑐𝑙𝑎𝑠𝑠, ).
• miou (float): The average of IoUs over classes.
• pixel_accuracy (float): The computed pixel accuracy.
• class_accuracy (numpy.ndarray): An array of class accuracies for the 𝑛_𝑐𝑙𝑎𝑠𝑠 classes. Its
shape is (𝑛_𝑐𝑙𝑎𝑠𝑠, ).
• mean_class_accuracy (float): The average of class accuracies.
Return type dictcalc_semantic_segmentation_confusion
chainercv.evaluations.calc_semantic_segmentation_confusion(pred_labels,
gt_labels)
Collect a confusion matrix.
The number of classes 𝑛_𝑐𝑙𝑎𝑠𝑠 is 𝑚𝑎𝑥(𝑝𝑟𝑒𝑑_𝑙𝑎𝑏𝑒𝑙𝑠, 𝑔𝑡_𝑙𝑎𝑏𝑒𝑙𝑠) + 1, which is the maximum class id of the
inputs added by one.
Parameters• pred_labels (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_semantic_segmentation().
• gt_labels (iterable of numpy.ndarray) – See the table in chainercv.
evaluations.eval_semantic_segmentation().
Returns A confusion matrix. Its shape is (𝑛_𝑐𝑙𝑎𝑠𝑠, 𝑛_𝑐𝑙𝑎𝑠𝑠). The (𝑖, 𝑗) th element corresponds tothe number of pixels that are labeled as class 𝑖 by the ground truth and class 𝑗 by the prediction.
Return type numpy.ndarraycalc_semantic_segmentation_iou
chainercv.evaluations.calc_semantic_segmentation_iou(confusion)
Calculate Intersection over Union with a given confusion matrix.
The definition of Intersection over Union (IoU) is as follows, where 𝑁𝑖𝑗 is the number of pixels that are labeled
as class 𝑖 by the ground truth and class 𝑗 by the prediction.
• IoU of the i-th class = ∑︀𝑘

𝑁𝑖𝑖
∑︀
𝑘

𝑗=1 𝑁𝑖𝑗 +40

𝑗=1 𝑁𝑗𝑖 −𝑁𝑖𝑖

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters confusion (numpy.ndarray) – A confusion matrix.
Its shape is(𝑛_𝑐𝑙𝑎𝑠𝑠, 𝑛_𝑐𝑙𝑎𝑠𝑠). The (𝑖, 𝑗) th element corresponds to the number of pixels that arelabeled as class 𝑖 by the ground truth and class 𝑗 by the prediction.
Returns An array of IoUs for the 𝑛_𝑐𝑙𝑎𝑠𝑠 classes. Its shape is (𝑛_𝑐𝑙𝑎𝑠𝑠, ).
Return type numpy.ndarray

3.4 Experimental
3.4.1 Links
Detection
Detection links share a common method predict() to detect objects in images.
YOLO
Object Detection Link
YOLOv2Tiny
class chainercv.experimental.links.model.yolo.YOLOv2Tiny(n_fg_class=None, pretrained_model=None)YOLOv2 tiny.
This is a model of YOLOv2 tiny a.k.a. Tiny YOLO. This model uses DarknetExtractor as its feature
extractor.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded.
'voc0712', filepath or None. The default value is None.

This can take– 'voc0712': Load weights trained on trainval split of PASCAL VOC 2007 and 2012.
The weight file is downloaded and cached automatically. n_fg_class must be 20 orNone. These weights were converted from the darknet model provided by the original
implementation. The conversion code is chainercv/examples/yolo/darknet2npz.py.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
Utility
DarknetExtractor
class chainercv.experimental.links.model.yolo.DarknetExtractor
A Darknet based feature extractor for YOLOv2Tiny.
This is a feature extractor for YOLOv2Tiny

3.4. Experimental

41

ChainerCV Documentation, Release 0.13.1

forward(x)Compute a feature map from a batch of images.
Parameters x (ndarray) – An array holding a batch of images. The images should be resized
to 416 × 416.
Returns
Return type Variable
Semantic Segmentation
Semantic segmentation links share a common method predict() to conduct semantic segmentation of images.
PSPNetSemantic Segmentation Link
PSPNetResNet101
class chainercv.experimental.links.model.pspnet.PSPNetResNet101(n_class=None,
pretrained_model=None,
input_size=None,
initialW=None)
PSPNet with Dilated ResNet101 as the feature extractor.
See also:
chainercv.experimental.links.model.pspnet.PSPNet
PSPNetResNet50
class chainercv.experimental.links.model.pspnet.PSPNetResNet50(n_class=None,
pretrained_model=None,
input_size=None,
initialW=None)
PSPNet with Dilated ResNet50 as the feature extractor.
See also:
chainercv.experimental.links.model.pspnet.PSPNet
Utility
convolution_crop
chainercv.experimental.links.model.pspnet.convolution_crop(img, size, stride, return_param=False)
Strided cropping.
42

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

This extracts cropped images from the input. The cropped images are extracted from the entire image, while
taking a constant steps between neighboring patches.
Parameters• img (ndarray) – An image array to be cropped. This is in CHW format.
• size (tuple) – The size of output image after cropping. This value is (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
• stride (tuple) – The stride between crops. This contains two values: stride in thevertical and horizontal directions.
• return_param (bool) – If True, this function returns information of slices.
Returns
If return_param = False, returns an array crop_imgs that is a stack of cropped images.
If return_param = True, returns a tuple whose elements are crop_imgs, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• y_slices (list slices): Slices used to crop the input image. The relation below holds together
with x_slices.
• x_slices (list of slices): Similar to y_slices.
• crop_y_slices (list of slices): This indicates the region of the cropped image that is actually
extracted from the input. This is relevant only when borders of the input are cropped.
• crop_x_slices (list of slices): Similar to crop_y_slices.
crop_img = crop_imgs[i][:, crop_y_slices[i], crop_x_slices[i]]crop_img == img[:, y_slices[i], x_slices[i]]Return type ndarray or (ndarray, dict)
Examples>>> import numpy as np>>> from chainercv.datasets import VOCBboxDataset>>> from chainercv.transforms import resize>>> from chainercv.experimental.links.model.pspnet import...
˓→convolution_crop>>>>>> img, _, _ = VOCBboxDataset(year='2007')[0]>>> img = resize(img, (300, 300))>>> imgs, param = convolution_crop(>>>
img, (128, 128), (96, 96), return_param=True)>>> # Restore the original image from the cropped images.
>>> output = np.zeros((3, 300, 300))>>> count = np.zeros((300, 300))>>> for i in range(len(imgs)):>>>
crop_y_slice = param['crop_y_slices'][i]>>>crop_x_slice = param['crop_x_slices'][i]>>>y_slice = param['y_slices'][i]>>>x_slice = param['x_slices'][i]>>>output[:, y_slice, x_slice] +=...
imgs[i][:, crop_y_slice,
˓→ crop_x_slice]>>>
count[y_slice, x_slice] += 1
(continues on next page)

3.4. Experimental

43

ChainerCV Documentation, Release 0.13.1(continued from previous page)>>> output = output / count[None]>>> np.testing.assert_equal(output, img)>>>>>> # Visualization of the cropped images>>> import matplotlib.pyplot as plt>>> from chainercv.utils import tile_images>>> from chainercv.visualizations import vis_image>>> v_imgs = tile_images(imgs, 5, fill=122.5)>>> vis_image(v_imgs)>>> plt.show()

PSPNetclass chainercv.experimental.links.model.pspnet.PSPNet(n_class=None,
pretrained_model=None,
input_size=None,
initialW=None)
Pyramid Scene Parsing Network.
This is a PSPNet1 model for semantic segmentation. This is based on the implementation found here.
Parameters• n_class (int) – The number of channels in the last convolution layer.
• pretrained_model (string) – The weight file to be loaded. This can take'cityscapes', filepath or None. The default value is None. * 'cityscapes': Loadweights trained on the train split of Cityscapes dataset. n_class must be 19 or None. *'ade20k': Load weights trained on the train split of ADE20K dataset. n_class mustbe 150 or None. * 'imagenet': Load ImageNet pretrained weights for the extractor. *filepath: A path of npz file. In this case, n_class must be specified properly. * None: Do
not load weights.
• input_size (tuple) – The size of the input. This value is (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
• initialW (callable) – Initializer for the weights of convolution kernels.
predict(imgs)
Conduct semantic segmentation from images.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their values are [0, 255].
Returns List of integer labels predicted from each image in the input list.
Return type list of numpy.ndarray
Instance Segmentation
Instance segmentation share a common method predict() to detect objects in images. For more details, please
read FCIS.predict().
1 Hengshuang Zhao, Jianping Shi, Xiaojuan Qi, Xiaogang Wang Jiaya Jia “Pyramid Scene Parsing Network” CVPR, 2017

44

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

FCIS
Instance Segmentation Link
FCISResNet101
class chainercv.experimental.links.model.fcis.FCISResNet101(n_fg_class=None,
pretrained_model=None,min_size=600,
max_size=1000,
roi_size=21,
group_size=7,
ratios=[0.5, 1, 2],anchor_scales=[8,16,32],
loc_normalize_mean=(0.0,
0.0,
0.0,
0.0),
loc_normalize_std=(0.2,
0.2,
0.5,
0.5),
iter2=True,
resnet_initialW=None,
rpn_initialW=None,
head_initialW=None,
proposal_creator_params=None)
FCIS based on ResNet101.
When you specify the path of a pre-trained chainer model serialized as a npz file in the constructor, this chain
model automatically initializes all the parameters with it. When a string in prespecified set is provided, apretrained model is loaded from weights distributed on the Internet. The list of pretrained models supported are
as follows:• sbd: Loads weights trained with the trainval split of Semantic Boundaries Dataset.
For descriptions on the interface of this model, please refer to FCIS.
FCISResNet101 supports finer control on random initializations of weights by arguments
resnet_initialW, rpn_initialW and head_initialW. It accepts a callable that takes an array and edits its values. If None is passed as an initializer, the default initializer is used.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (str) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• min_size (int) – A preprocessing paramter for prepare().
• max_size (int) – A preprocessing paramter for prepare().
• roi_size (int) – Height and width of the feature maps after Position Sensitive RoI
pooling.
• group_size (int) – Group height and width for Position Sensitive ROI pooling.
3.4. Experimental

45

ChainerCV Documentation, Release 0.13.1• ratios (list of floats) – This is ratios of width to height of the anchors.
• anchor_scales (list of numbers) – This is areas of anchors. Those areas will be
the product of the square of an element in anchor_scales and the original area of thereference window.
• loc_normalize_mean (tuple of four floats) – Mean values of localization
estimates.
• loc_normalize_std (tupler of four floats) – Standard deviation of localization estimates.
• iter2 (bool) – if the value is set True, Position Sensitive ROI pooling is executed twice.
In the second time, Position Sensitive ROI pooling uses improved ROIs by the localization
parameters calculated in the first time.
• resnet_initialW (callable) – Initializer for the layers corresponding to the
ResNet101 layers.
• rpn_initialW (callable) – Initializer for Region Proposal Network layers.
• head_initialW (callable) – Initializer for the head layers.
• proposal_creator_params
ProposalCreator.

(dict)–

Key

valuedparamtersfor

Utility
FCIS
class chainercv.experimental.links.model.fcis.FCIS(extractor,
rpn,
mean,
min_size,
loc_normalize_mean,
loc_normalize_std)
Base class for FCIS.

head,
max_size,This is a base class for FCIS links supporting instance segmentation API1 . The following three stages constitute
FCIS.
1. Feature extraction: Images are taken and their feature maps are calculated.
2. Region Proposal Networks: Given the feature maps calculated in the previous stage, produce set of RoIs
around objects.
3. Localization, Segmentation and Classification Heads: Using feature maps that belong to the proposed
RoIs, segment regions of the objects, classify the categories of the objects in the RoIs and improve localizations.
Each stage is carried out by one of the callable chainer.Chain objects feature, rpn and head. There
are two functions predict() and forward() to conduct instance segmentation. predict() takes images
and returns masks, object labels and their scores. forward() is provided for a scnerario when intermediate
outputs are needed, for instance, for training and debugging.
Links that support instance segmentation API have method predict() with the same interface. Please referto predict() for further details.
Parameters
1 Yi Li, Haozhi Qi, Jifeng Dai, Xiangyang Ji, Yichen Wei. Fully Convolutional Instance-aware Semantic Segmentation. CVPR 2017.

46

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• extractor (callable Chain) – A callable that takes a BCHW image array and returns feature maps.
• rpn (callable Chain) – A callable that has the same interface
RegionProposalNetwork. Please refer to the documentation found there.

as• head (callable Chain) – A callable that takes a BCHW array, RoIs and batch indices for RoIs. This returns class-agnostic segmentation scores, class-agnostic localization
parameters, class scores, improved RoIs and batch indices for RoIs.
• mean (numpy.ndarray) – A value to be subtracted from an image in prepare().
• min_size (int) – A preprocessing parameter for prepare(). Please refer to a docstring found for prepare().
• max_size (int) – A preprocessing parameter for prepare().
• loc_normalize_mean (tuple of four floats) – Mean values of localization
estimates.
• loc_normalize_std (tupler of four floats) – Standard deviation of localization estimates.
forward(x, scales=None)
Forward FCIS.
Scaling paramter scale is used by RPN to determine the threshold to select small objects, which aregoing to be rejected irrespective of their confidence scores.
Here are notations used.
• 𝑁 is the number of batch size
• 𝑅′ is the∑︀𝑁total number of RoIs produced across batches. Given 𝑅𝑖 proposed RoIs from the 𝑖 th image,𝑅′ = 𝑖=1 𝑅𝑖 .
• 𝐿 is the number of classes excluding the background.
• 𝑅𝐻 is the height of pooled image by Position Sensitive ROI pooling.
• 𝑅𝑊 is the height of pooled image by Position Sensitive ROI pooling.
Classes are ordered by the background, the first class, . . . , and the 𝐿 th class.
Parameters• x (Variable) – 4D image variable.
• scales (tuple of floats) – Amount of scaling applied to each input image during
preprocessing.
Returns
Returns tuple of five values listed below.
• roi_ag_seg_scores: Class-agnostic clipped mask scores for the proposed ROIs. Its shapeis (𝑅′ , 2, 𝑅𝐻, 𝑅𝑊 )• ag_locs: Class-agnostic offsets and scalings for the proposed RoIs. Its shape is (𝑅′ , 2, 4).
• roi_cls_scores: Class predictions for the proposed RoIs. Its shape is (𝑅′ , 𝐿 + 1).
• rois: RoIs proposed by RPN. Its shape is (𝑅′ , 4).
• roi_indices: Batch indices of RoIs. Its shape is (𝑅′ , ).
Return type Variable, Variable, Variable, array, array

3.4. Experimental

47

ChainerCV Documentation, Release 0.13.1

predict(imgs)
Segment object instances from images.
This method predicts instance-aware object regions for each image.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images of shape(𝐵, 𝐶, 𝐻, 𝑊 ). All images are in CHW and RGB format and the range of their value is[0, 255].
Returns
This method returns a tuple of three lists, (masks, labels, scores).
• masks: A list of boolean arrays of shape (𝑅, 𝐻, 𝑊 ), where 𝑅 is the number of masks ina image. Each pixel holds value if it is inside the object inside or not.
• labels : A list of integer arrays of shape (𝑅, ). Each value indicates the class of the masks.
Values are in range [0, 𝐿 − 1], where 𝐿 is the number of the foreground classes.
• scores : A list of float arrays of shape (𝑅, ). Each value indicates how confident theprediction is.
Return type tuple of lists
prepare(img)
Preprocess an image for feature extraction.
The length of the shorter edge is scaled to self.min_size. After the scaling, if the length of the longer
edge is longer than self.max_size, the image is scaled to fit the longer edge to self.max_size.
After resizing the image, the image is subtracted by a mean image value self.mean.
Parameters img (ndarray) – An image. This is in CHW and RGB format. The range of its
value is [0, 255].
Returns A preprocessed image.
Return type ndarray
use_preset(preset)
Use the given preset during prediction.
This method changes values of self.nms_thresh, self.score_thresh, self.
mask_merge_thresh,
self.binary_thresh,
self.binary_thresh and self.
min_drop_size. These values are a threshold value used for non maximum suppression, athreshold value to discard low confidence proposals in predict(), a threshold value to merge maskin predict(), a threshold value to binalize segmentation scores in predict(), a limit number ofpredicted masks in one image and a threshold value to discard small bounding boxes respectively.
If the attributes need to be changed to something other than the values provided in the presets, pleasemodify them by directly accessing the public attributes.
Parameters preset ({'visualize', 'evaluate') – A string to determine the preset
to use.

48

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

FCISResNet101Headclass chainercv.experimental.links.model.fcis.FCISResNet101Head(n_class,roi_size,group_size,
spatial_scale,
loc_normalize_mean,
loc_normalize_std,
iter2,
initialW=None)
FCIS Head for ResNet101 based implementation.
This class is used as a head for FCIS. This outputs class-agnostice segmentation scores, class-agnostic localizations and classification based on feature maps in the given RoIs.
Parameters• n_class (int) – The number of classes possibly including the background.
• roi_size (int) – Height and width of the feature maps after Position Sensitive RoI
pooling.
• group_size (int) – Group height and width for Position Sensitive ROI pooling.
• spatial_scale (float) – Scale of the roi is resized.
• loc_normalize_mean (tuple of four floats) – Mean values of localization
estimates.
• loc_normalize_std (tupler of four floats) – Standard deviation of localization estimates.
• iter2 (bool) – if the value is set True, Position Sensitive ROI pooling is executed twice.
In the second time, Position Sensitive ROI pooling uses improved ROIs by the localization
parameters calculated in the first time.
• initialW (callable) – Initializer for the layers.
mask_voting
chainercv.experimental.links.model.fcis.mask_voting(seg_prob, bbox, cls_prob, size,score_thresh,
nms_thresh,mask_merge_thresh,binary_thresh,
limit=100,
bg_label=0)
Refine mask probabilities by merging multiple masks.
First, this function discard invalid masks with non maximum suppression. Then, it merges masks with weightcalculated from class probabilities and iou. This function improves the mask qualities by merging overlappedmasks predicted as the same object class.
Here are notations used. * 𝑅 is the total number of RoIs produced in one image. * 𝐿 is the number of classes
excluding the background. * 𝑅𝐻 is the height of pooled image. * 𝑅𝑊 is the height of pooled image.
Parameters• seg_prob (array) – A mask probability array whose shape is (𝑅, 𝑅𝐻, 𝑅𝑊 ).
• bbox (array) – A bounding box array whose shape is (𝑅, 4).
• cls_prob (array) – A class probability array whose shape is (𝑅, 𝐿 + 1).

3.4. Experimental

49

ChainerCV Documentation, Release 0.13.1• size (tuple of int) – Original image size.
• score_thresh (float) – A threshold value of the class score.
• nms_thresh (float) – A threshold value of non maximum suppression.
• mask_merge_thresh (float) – A threshold value of the bounding box iou for mask
merging.
• binary_thresh (float) – A threshold value of mask score for mask merging.
• limit (int) – The maximum number of outputs.
• bg_label (int) – The id of the background label.
Returns• v_seg_prob: Merged mask probability. Its shapes is (𝑁, 𝑅𝐻, 𝑅𝑊 ).
• v_bbox: Bounding boxes for the merged masks. Its shape is (𝑁, 4).
• v_label: Class labels for the merged masks. Its shape is (𝑁, ).
• v_score: Class probabilities for the merged masks. Its shape is (𝑁, ).
Return type array, array, array, array
ResNet101Extractor
class chainercv.experimental.links.model.fcis.ResNet101Extractor(initialW=None)
ResNet101 Extractor for FCIS ResNet101 implementation.
This class is used as an extractor for FCISResNet101. This outputs feature maps. Dilated convolution is used in
the C5 stage.
Parameters initialW – Initializer for ResNet101 extractor.
Train-only Utility
FCISTrainChainclass chainercv.experimental.links.model.fcis.FCISTrainChain(fcis,
rpn_sigma=3.0,
roi_sigma=1.0, anchor_target_creator=<chainercv.links.mode
object>,proposal_target_creator=<chainercv.experimen
object>)Calculate losses for FCIS and report them.
This is used to train FCIS in the joint training scheme2 .
The losses include:• rpn_loc_loss: The localization loss for Region Proposal Network (RPN).
• rpn_cls_loss: The classification loss for RPN.
• roi_loc_loss: The localization loss for the head module.
2 Yi Li, Haozhi Qi, Jifeng Dai, Xiangyang Ji, Yichen Wei. Fully Convolutional Instance-aware Semantic Segmentation. CVPR 2017.

50

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• roi_cls_loss: The classification loss for the head module.
• roi_mask_loss: The mask loss for the head module.
Parameters• fcis (FCIS) – A FCIS model for training.
• rpn_sigma (float) – Sigma parameter for the localization loss of Region Proposal Network (RPN). The default value is 3, which is the value used in2 .
• roi_sigma (float) – Sigma paramter for the localization loss of the head. The default
value is 1, which is the value used in2 .
• anchor_target_creator – An instantiation of AnchorTargetCreator.
• proposal_target_creator – An instantiation of ProposalTargetCreator.
forward(imgs, masks, labels, bboxes, scale)
Forward FCIS and calculate losses.
Here are notations used.
• 𝑁 is the batch size.
• 𝑅 is the number of bounding boxes per image.
• 𝐻 is the image height.
• 𝑊 is the image width.
Currently, only 𝑁 = 1 is supported.
Parameters• imgs (Variable) – A variable with a batch of images.
• masks (Variable) – A batch of masks. Its shape is (𝑁, 𝑅, 𝐻, 𝑊 ).
• labels (Variable) – A batch of labels. Its shape is (𝑁, 𝑅). The background is excluded from the definition, which means that the range of the value is [0, 𝐿 − 1]. 𝐿 is thenumber of foreground classes.
• bboxes (Variable) – A batch of bounding boxes. Its shape is (𝑁, 𝑅, 4).
• scale (float or Variable) – Amount of scaling applied to the raw image during
preprocessing.
Returns Scalar loss variable. This is the sum of losses for Region Proposal Network and thehead module.
Return type chainer.Variable
ProposalTargetCreatorclass chainercv.experimental.links.model.fcis.ProposalTargetCreator(n_sample=128,
pos_ratio=0.25,
pos_iou_thresh=0.5,
neg_iou_thresh_hi=0.5,
neg_iou_thresh_lo=0.1,
binary_thresh=0.4)
Assign ground truth classes, bounding boxes and masks to given RoIs.

3.4. Experimental

51

ChainerCV Documentation, Release 0.13.1

The __call__() of this class generates training targets for each object proposal. This is used to train FCIS3 .
Parameters• n_sample (int) – The number of sampled regions.
• pos_ratio (float) – Fraction of regions that is labeled as a foreground.
• pos_iou_thresh (float) – IoU threshold for a RoI to be considered as a foreground.
• neg_iou_thresh_hi (float) – RoI is considered to be the background if IoU is in[neg_iou_thresh_hi, neg_iou_thresh_hi).
• neg_iou_thresh_lo (float) – See above.
• binary_thresh (float) – Threshold for resized mask.
__call__(roi, mask, label, bbox, loc_normalize_mean=(0.0, 0.0, 0.0, 0.0), loc_normalize_std=(0.2,
0.2, 0.5, 0.5), mask_size=(21, 21))
Assigns ground truth to sampled proposals.
This function samples total of self.n_sample RoIs from the combination of roi, mask, label and:obj: bbox. The RoIs are assigned with the ground truth class labels as well as bounding box offsets andscales to match the ground truth bounding boxes. As many as pos_ratio * self.n_sample RoIs
are sampled as foregrounds.
Offsets and scales of bounding boxes are calculated using chainercv.links.model.
faster_rcnn.bbox2loc(). Also, types of input arrays and output arrays are same.
Here are notations.
• 𝑆 is the total number of sampled RoIs, which equals self.n_sample.
• 𝐿 is number of object classes possibly including the background.
• 𝐻 is the image height.
• 𝑊 is the image width.
• 𝑅𝐻 is the mask height.
• 𝑅𝑊 is the mask width.
Parameters• roi (array) – Region of Interests (RoIs) from which we sample. Its shape is (𝑅, 4)• mask (array) – The coordinates of ground truth masks. Its shape is (𝑅′ , 𝐻, 𝑊 ).
• label (array) – Ground truth bounding box labels. Its shape is (𝑅′ , ). Its range is[0, 𝐿 − 1], where 𝐿 is the number of foreground classes.
• bbox (array) – The coordinates of ground truth bounding boxes. Its shape is (𝑅′ , 4).
• loc_normalize_mean (tuple of four floats) – Mean values to normalize
coordinates of bounding boxes.
• loc_normalize_std (tuple of four floats) – Standard deviation of the coordinates of bounding boxes.
• mask_size (tuple of int or int) – Generated mask size, which is equal to(𝑅𝐻, 𝑅𝑊 ).
Returns• sample_roi: Regions of interests that are sampled. Its shape is (𝑆, 4).
3 Yi Li, Haozhi Qi, Jifeng Dai, Xiangyang Ji, Yichen Wei. Fully Convolutional Instance-aware Semantic Segmentation. CVPR 2017.

52

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• gt_roi_mask: Masks assigned to sampled RoIs. Its shape is (𝑆, 𝑅𝐻, 𝑅𝑊 ).
• gt_roi_label: Labels assigned to sampled RoIs. Its shape is (𝑆, ). Its range is [0, 𝐿]. The
label with value 0 is the background.
• gt_roi_loc: Offsets and scales to match the sampled RoIs to the ground truth boundingboxes. Its shape is (𝑆, 4).
Return type (array, array, array, array)

3.5 Extensions
3.5.1 Evaluator
DetectionCOCOEvaluator
class chainercv.extensions.DetectionCOCOEvaluator(iterator, target, label_names=None,
comm=None)
An extension that evaluates a detection model by MS COCO metric.
This extension iterates over an iterator and evaluates the prediction results. The results consist of average
precisions (APs) and average recalls (ARs) as well as the mean of each (mean average precision and mean
average recall). This extension reports the following values with keys. Please note that if label_names is not
specified, only the mAPs and mARs are reported.
The underlying dataset of the iterator is assumed to return img, bbox, label or img, bbox, label,area, crowded.
key
ap/iou=0.50:0.95/area=all/max_dets=100/<label_names[l]>ap/iou=0.50/area=all/max_dets=100/<label_names[l]>ap/iou=0.75/area=all/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=small/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=medium/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=large/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=all/max_dets=1/<label_names[l]>ar/iou=0.50/area=all/max_dets=10/<label_names[l]>ar/iou=0.75/area=all/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=small/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=medium/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=large/max_dets=100/<label_names[l]>map/iou=0.50:0.95/area=all/max_dets=100
map/iou=0.50/area=all/max_dets=100
map/iou=0.75/area=all/max_dets=100
map/iou=0.50:0.95/area=small/max_dets=100
map/iou=0.50:0.95/area=medium/max_dets=100
map/iou=0.50:0.95/area=large/max_dets=100
ar/iou=0.50:0.95/area=all/max_dets=1
ar/iou=0.50/area=all/max_dets=10
ar/iou=0.75/area=all/max_dets=100
ar/iou=0.50:0.95/area=small/max_dets=100
ar/iou=0.50:0.95/area=medium/max_dets=100
ar/iou=0.50:0.95/area=large/max_dets=100

3.5. Extensions

description
1
1
1
15
15
15
2
2
2
25
25
25
3
3
3
35
35
35
4
4
4
45
45
45

53

ChainerCV Documentation, Release 0.13.1

Parameters• iterator (chainer.Iterator) – An iterator. Each sample should be following tuple
img, bbox, label, area, crowded.
• target (chainer.Link) – A detection link. This link must have predict() methodthat takes a list of images and returns bboxes, labels and scores.
• label_names (iterable of strings) – An iterable of names of classes. If thisvalue is specified, average precision and average recalls for each class are reported.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this extension scatters the iterator of root worker and gathers the results to the root worker.
DetectionVOCEvaluator
class chainercv.extensions.DetectionVOCEvaluator(iterator,
target,use_07_metric=False,label_names=None, comm=None)
An extension that evaluates a detection model by PASCAL VOC metric.
This extension iterates over an iterator and evaluates the prediction results by average precisions (APs) and meanof them (mean Average Precision, mAP). This extension reports the following values with keys. Please note that'ap/<label_names[l]>' is reported only if label_names is specified.
• 'map': Mean of average precisions (mAP).
• 'ap/<label_names[l]>': Average precision for class label_names[l], where 𝑙 is the index of the class. For example, this evaluator reports 'ap/aeroplane', 'ap/bicycle', etc.
if label_names is voc_bbox_label_names. If there is no bounding box assigned to classlabel_names[l] in either ground truth or prediction, it reports numpy.nan as its average precision.
In this case, mAP is computed without this class.
Parameters• iterator (chainer.Iterator) – An iterator. Each sample should be following
tuple img, bbox, label or img, bbox, label, difficult. img is an image, bbox is coordinates of bounding boxes, label is labels of the bounding boxes anddifficult is whether the bounding boxes are difficult or not. If difficult is returned,
difficult ground truth will be ignored from evaluation.
• target (chainer.Link) – A detection link. This link must have predict() methodthat takes a list of images and returns bboxes, labels and scores.
• use_07_metric (bool) – Whether to use PASCAL VOC 2007 evaluation metric for
calculating average precision. The default value is False.
• label_names (iterable of strings) – An iterable of names of classes. If thisvalue is specified, average precision for each class is also reported with the key 'ap/<label_names[l]>'.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this extension scatters the iterator of root worker and gathers the results to the root worker.
1 Average precision for class label_names[l], where 𝑙 is the index of the class. If class 𝑙 does not exist in either pred_labels or
gt_labels, the corresponding value is set to numpy.nan.
5 Skip if gt_areas is None.
2 Average recall for class label_names[l], where 𝑙 is the index of the class. If class 𝑙 does not exist in either pred_labels or
gt_labels, the corresponding value is set to numpy.nan.
3 The average of average precisions over classes.
4 The average of average recalls over classes.

54

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

InstanceSegmentationCOCOEvaluator
class chainercv.extensions.InstanceSegmentationCOCOEvaluator(iterator, target, label_names=None,
comm=None)
An extension that evaluates a instance segmentation model by MS COCO metric.
This extension iterates over an iterator and evaluates the prediction results. The results consist of average
precisions (APs) and average recalls (ARs) as well as the mean of each (mean average precision and mean
average recall). This extension reports the following values with keys. Please note that if label_names is not
specified, only the mAPs and mARs are reported.
The underlying dataset of the iterator is assumed to return img, mask, label or img, mask, label,area, crowded.
key
ap/iou=0.50:0.95/area=all/max_dets=100/<label_names[l]>ap/iou=0.50/area=all/max_dets=100/<label_names[l]>ap/iou=0.75/area=all/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=small/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=medium/max_dets=100/<label_names[l]>ap/iou=0.50:0.95/area=large/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=all/max_dets=1/<label_names[l]>ar/iou=0.50/area=all/max_dets=10/<label_names[l]>ar/iou=0.75/area=all/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=small/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=medium/max_dets=100/<label_names[l]>ar/iou=0.50:0.95/area=large/max_dets=100/<label_names[l]>map/iou=0.50:0.95/area=all/max_dets=100
map/iou=0.50/area=all/max_dets=100
map/iou=0.75/area=all/max_dets=100
map/iou=0.50:0.95/area=small/max_dets=100
map/iou=0.50:0.95/area=medium/max_dets=100
map/iou=0.50:0.95/area=large/max_dets=100
ar/iou=0.50:0.95/area=all/max_dets=1
ar/iou=0.50/area=all/max_dets=10
ar/iou=0.75/area=all/max_dets=100
ar/iou=0.50:0.95/area=small/max_dets=100
ar/iou=0.50:0.95/area=medium/max_dets=100
ar/iou=0.50:0.95/area=large/max_dets=100

description
6
6
6
610
610
610
7
7
7
710
710
710
8
8
8
810
810
810
9
9
9
910
910
910

Parameters• iterator (chainer.Iterator) – An iterator. Each sample should be following tuple
img, mask, label, area, crowded.
• target (chainer.Link) – A detection link. This link must have predict() methodthat takes a list of images and returns masks, labels and scores.
6 Average precision for class label_names[l], where 𝑙 is the index of the class. If class 𝑙 does not exist in either pred_labels or
gt_labels, the corresponding value is set to numpy.nan.
10 Skip if gt_areas is None.
7 Average recall for class label_names[l], where 𝑙 is the index of the class. If class 𝑙 does not exist in either pred_labels or
gt_labels, the corresponding value is set to numpy.nan.
8 The average of average precisions over classes.
9 The average of average recalls over classes.

3.5. Extensions

55

ChainerCV Documentation, Release 0.13.1• label_names (iterable of strings) – An iterable of names of classes. If thisvalue is specified, average precision and average recalls for each class are reported.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this extension scatters the iterator of root worker and gathers the results to the root worker.
InstanceSegmentationVOCEvaluator
class chainercv.extensions.InstanceSegmentationVOCEvaluator(iterator,
target,
iou_thresh=0.5,
use_07_metric=False,label_names=None,
comm=None)
An evaluation extension of instance-segmentation by PASCAL VOC metric.
This extension iterates over an iterator and evaluates the prediction results by average precisions (APs) and meanof them (mean Average Precision, mAP). This extension reports the following values with keys. Please note that'ap/<label_names[l]>' is reported only if label_names is specified.
• 'map': Mean of average precisions (mAP).
• 'ap/<label_names[l]>': Average precision for class label_names[l], where 𝑙 is the index of the class. For example, this evaluator reports 'ap/aeroplane', 'ap/bicycle', etc. iflabel_names is sbd_instance_segmentation_label_names. If there is no bounding box
assigned to class label_names[l] in either ground truth or prediction, it reports numpy.nan as its
average precision. In this case, mAP is computed without this class.
Parameters• iterator (chainer.Iterator) – An iterator. Each sample should be following
tuple img, bbox, label or img, bbox, label, difficult. img is an image, bbox is coordinates of bounding boxes, label is labels of the bounding boxes anddifficult is whether the bounding boxes are difficult or not. If difficult is returned,
difficult ground truth will be ignored from evaluation.
• target (chainer.Link) – An instance-segmentation link. This link must havepredict() method that takes a list of images and returns bboxes, labels andscores.
• iou_thresh (float) – Intersection over Union (IoU) threshold for calulating average
precision. The default value is 0.5.
• use_07_metric (bool) – Whether to use PASCAL VOC 2007 evaluation metric for
calculating average precision. The default value is False.
• label_names (iterable of strings) – An iterable of names of classes. If thisvalue is specified, average precision for each class is also reported with the key 'ap/<label_names[l]>'.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this extension scatters the iterator of root worker and gathers the results to the root worker.
SemanticSegmentationEvaluator
class chainercv.extensions.SemanticSegmentationEvaluator(iterator,
target,bel_names=None,
comm=None)
An extension that evaluates a semantic segmentation model.

56

la-

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

This extension iterates over an iterator and evaluates the prediction results of the model by common evaluation metrics for semantic segmentation. This extension reports values with keys below. Please notethat 'iou/<label_names[l]>' and 'class_accuracy/<label_names[l]>' are reported only
if label_names is specified.
• 'miou': Mean of IoUs (mIoU).
• 'iou/<label_names[l]>': IoU for class label_names[l], where 𝑙 is the index of the class.
For example, if label_names is camvid_label_names, this evaluator reports 'iou/Sky', 'ap/
Building', etc.
• 'mean_class_accuracy': Mean of class accuracies.
• 'class_accuracy/<label_names[l]>': Class accuracy for class label_names[l], where 𝑙is the index of the class.
• 'pixel_accuracy': Pixel accuracy.
If there is no label assigned to class label_names[l] in the ground truth, values corresponding to keys
'iou/<label_names[l]>' and 'class_accuracy/<label_names[l]>' are numpy.nan. In
that case, the means of them are calculated by excluding them from calculation.
For details on the evaluation metrics, please see the documentation for chainercv.evaluations.
eval_semantic_segmentation().
See also:
chainercv.evaluations.eval_semantic_segmentation().
Parameters• iterator (chainer.Iterator) – An iterator. Each sample should be following tuple
img, label. img is an image, label is pixel-wise label.
• target (chainer.Link) – A semantic segmentation link. This link should havepredict() method that takes a list of images and returns labels.
• label_names (iterable of strings) – An iterable of names of classes. If thisvalue is specified, IoU and class accuracy for each class are also reported with the keys
'iou/<label_names[l]>' and 'class_accuracy/<label_names[l]>'.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, this extension scatters the iterator of root worker and gathers the results to the root worker.

3.5.2 Visualization Report
DetectionVisReportclass chainercv.extensions.DetectionVisReport(iterator, target, label_names=None, filename=’detection_iter={iteration}_idx={index}.jpg’)
An extension that visualizes output of a detection model.
This extension visualizes the predicted bounding boxes together with the ground truth bounding boxes.
Internally, this extension takes examples from an iterator, predict bounding boxes from the images in the examples, and visualizes them using chainercv.visualizations.vis_bbox(). The process can beillustrated in the following code.

3.5. Extensions

57

ChainerCV Documentation, Release 0.13.1

batch = next(iterator)# Convert batch -> imgs, gt_bboxes, gt_labels
pred_bboxes, pred_labels, pred_scores = target.predict(imgs)# Visualization codefor img, gt_bbox, gt_label, pred_bbox, pred_label, pred_score \in zip(imgs, gt_boxes, gt_labels,
pred_bboxes, pred_labels, pred_scores):# the ground truth
vis_bbox(img, gt_bbox, gt_label)# the prediction
vis_bbox(img, pred_bbox, pred_label, pred_score)Note: gt_bbox and pred_bbox are float arrays of shape (𝑅, 4), where 𝑅 is the number of bounding boxesin the image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second axis.
gt_label and pred_label are intenger arrays of shape (𝑅, ). Each label indicates the class of the boundingbox.
pred_score is a float array of shape (𝑅, ). Each score indicates how confident the prediction is.

Parameters• iterator – Iterator object that produces images and ground truth.
• target – Link object used for detection.
• label_names (iterable of strings) – Name of labels ordered according to label
ids. If this is None, labels will be skipped.
• filename (str) – Basename for the saved image. It can contain two keywords,'{iteration}' and '{index}'. They are replaced with the iteration of the trainer
and the index of the sample when this extension save an image. The default value is'detection_iter={iteration}_idx={index}.jpg'.

3.6 Functions
3.6.1 Spatial Poolingps_roi_average_align_2d
chainercv.functions.ps_roi_average_align_2d(x, rois, roi_indices, outsize, spatial_scale,group_size, sampling_ratio=None)
Position Sensitive Region of Interest (ROI) Average align function.
This function computes position sensitive average of input spatial patch with the given region of interests. Each
ROI is splitted into (𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒, 𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒) regions, and position sensitive values in each region is computed.
Parameters• x (Variable) – Input variable. The shape is expected to be 4 dimentional: (n: batch, c:channel, h, height, w: width).
• rois (array) – Input roi. The shape is expected to be (𝑅, 4), and each datum is set as
below: (y_min, x_min, y_max, x_max). The dtype is numpy.float32.

58

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• roi_indices (array) – Input roi indices. The shape is expected to be (𝑅, ). The dtype
is numpy.int32.
• outsize ((int, int, int) or (int, int) or int) – Expected output size
after pooled: (channel, height, width) or (height, width) or outsize. outsize=o andoutsize=(o, o) are equivalent. Channel parameter is used to assert the input shape.
• spatial_scale (float) – Scale of the roi is resized.
• group_size (int) – Position sensitive group size.
• sampling_ratio ((int, int) or int) – Sampling step for the alignment. It
must be an integer over 1 or None, and the value is automatically decided when Noneis passed. Use of different ratio in height and width axis is also supported by passing tuple of int as (sampling_ratio_h, sampling_ratio_w). sampling_ratio=s
and sampling_ratio=(s, s) are equivalent.
Returns Output variable.
Return type Variable
See the original paper proposing PSROIPooling: R-FCN. See the original paper proposing ROIAlign: Mask
R-CNN.
ps_roi_average_pooling_2d
chainercv.functions.ps_roi_average_pooling_2d(x, rois, roi_indices, outsize, spatial_scale,group_size)
Position Sensitive Region of Interest (ROI) Average pooling function.
This function computes position sensitive average of input spatial patch with the given region of interests. Each
ROI is splitted into (𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒, 𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒) regions, and position sensitive values in each region is computed.
Parameters• x (Variable) – Input variable. The shape is expected to be 4 dimentional: (n: batch, c:channel, h, height, w: width).
• rois (array) – Input roi. The shape is expected to be (𝑅, 4), and each datum is set as
below: (y_min, x_min, y_max, x_max). The dtype is numpy.float32.
• roi_indices (array) – Input roi indices. The shape is expected to be (𝑅, ). The dtype
is numpy.int32.
• outsize ((int, int, int) or (int, int) or int) – Expected output size
after pooled: (channel, height, width) or (height, width) or outsize. outsize=o andoutsize=(o, o) are equivalent. Channel parameter is used to assert the input shape.
• spatial_scale (float) – Scale of the roi is resized.
• group_size (int) – Position sensitive group size.
Returns Output variable.
Return type Variable
See the original paper proposing PSROIPooling: R-FCN.

3.6. Functions

59

ChainerCV Documentation, Release 0.13.1

ps_roi_max_align_2d
chainercv.functions.ps_roi_max_align_2d(x, rois, roi_indices, outsize, spatial_scale,group_size, sampling_ratio=None)
Position Sensitive Region of Interest (ROI) Max align function.
This function computes position sensitive max value of input spatial patch with the given region of interests.
Each ROI is splitted into (𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒, 𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒) regions, and position sensitive values in each region iscomputed.
Parameters• x (Variable) – Input variable. The shape is expected to be 4 dimentional: (n: batch, c:channel, h, height, w: width).
• rois (array) – Input roi. The shape is expected to be (𝑅, 4), and each datum is set as
below: (y_min, x_min, y_max, x_max). The dtype is numpy.float32.
• roi_indices (array) – Input roi indices. The shape is expected to be (𝑅, ). The dtype
is numpy.int32.
• outsize ((int, int, int) or (int, int) or int) – Expected output size
after pooled: (channel, height, width) or (height, width) or outsize. outsize=o andoutsize=(o, o) are equivalent. Channel parameter is used to assert the input shape.
• spatial_scale (float) – Scale of the roi is resized.
• group_size (int) – Position sensitive group size.
• sampling_ratio ((int, int) or int) – Sampling step for the alignment. It
must be an integer over 1 or None, and the value is automatically decided when Noneis passed. Use of different ratio in height and width axis is also supported by passing tuple of int as (sampling_ratio_h, sampling_ratio_w). sampling_ratio=s
and sampling_ratio=(s, s) are equivalent.
Returns Output variable.
Return type Variable
See the original paper proposing PSROIPooling: R-FCN. See the original paper proposing ROIAlign: Mask
R-CNN.
ps_roi_max_pooling_2d
chainercv.functions.ps_roi_max_pooling_2d(x, rois, roi_indices, outsize, spatial_scale,group_size)
Position Sensitive Region of Interest (ROI) Max pooling function.
This function computes position sensitive max of input spatial patch with the given region of interests. Each ROI
is splitted into (𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒, 𝑔𝑟𝑜𝑢𝑝_𝑠𝑖𝑧𝑒) regions, and position sensitive values in each region is computed.
Parameters• x (Variable) – Input variable. The shape is expected to be 4 dimentional: (n: batch, c:channel, h, height, w: width).
• rois (array) – Input roi. The shape is expected to be (𝑅, 4), and each datum is set as
below: (y_min, x_min, y_max, x_max). The dtype is numpy.float32.
• roi_indices (array) – Input roi indices. The shape is expected to be (𝑅, ). The dtype
is numpy.int32.

60

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• outsize ((int, int, int) or (int, int) or int) – Expected output size
after pooled: (channel, height, width) or (height, width) or outsize. outsize=o andoutsize=(o, o) are equivalent. Channel parameter is used to assert the input shape.
• spatial_scale (float) – Scale of the roi is resized.
• group_size (int) – Position sensitive group size.
Returns Output variable.
Return type Variable
See the original paper proposing PSROIPooling: R-FCN.

3.7 Links
3.7.1 Model
General Chain
General Chain
FeaturePredictor
class chainercv.links.FeaturePredictor(extractor,
crop_size,
crop=’center’, mean=None)
Wrapper that adds a prediction method to a feature extraction link.

scale_size=None,

The predict() takes three steps to make a prediction.
1. Preprocess input images
2. Forward the preprocessed images to the network
3. Average features in the case when more than one crops are extracted.
Example>>> from chainercv.links import VGG16>>> from chainercv.links import FeaturePredictor>>> base_model = VGG16()>>> model = FeaturePredictor(base_model, 224, 256)>>> prob = model.predict([img])# Predicting multiple features>>> model.extractor.pick = ['conv5_3', 'fc7']>>> conv5_3, fc7 = model.predict([img])

When self.crop == 'center', predict() extracts features from the center crop of the input images.
When self.crop == '10', predict() extracts features from patches that are ten-cropped from the
input images.
When extracting more than one crops from an image, the output of predict() returns the average of thefeatures computed from the crops.
Parameters3.7. Links

61

ChainerCV Documentation, Release 0.13.1• extractor – A feature extraction link. This is a callable chain that takes a batch of images
and returns a variable or a tuple of variables.
• crop_size (int or tuple) – The height and the width of an image after cropping in
preprocessing. If this is an integer, the image is cropped to (𝑐𝑟𝑜𝑝_𝑠𝑖𝑧𝑒, 𝑐𝑟𝑜𝑝_𝑠𝑖𝑧𝑒).
• scale_size (int or tuple) – If scale_size is None, neither scaling nor resizing
is conducted during preprocessing. This is the default behavior. If this is an integer, an image
is resized so that the length of the shorter edge is equal to scale_size. If this is a tuple(height, width), the image is resized to (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
• crop ({'center', '10'}) – Determines the style of cropping.
• mean (numpy.ndarray) – A mean value. If this is None, extractor.mean is usedas the mean value.
predict(imgs)
Predict features from images.
Given 𝑁 input images, this method outputs a batched array with batchsize 𝑁 .
Parameters imgs (iterable of numpy.ndarray) – Array-images. All images are in
CHW format and the range of their value is [0, 255].
Returns A batch of features or a tuple of them.
Return type numpy.ndarray or tuple of numpy.ndarray
PickableSequentialChainclass chainercv.links.PickableSequentialChain
A sequential chain that can pick intermediate layers.
Callable objects, such as chainer.Link and chainer.Function, can be registered to this chain with
init_scope(). This chain keeps the order of registrations and forward() executes callables in that order.
A chainer.Link object in the sequence will be added as a child link of this link.
forward() returns single or multiple layers that are picked up through a stream of computation. These layers
can be specified by pick, which contains the names of the layers that are collected. When pick is a string,
single layer is returned. When pick is an iterable of strings, a tuple of layers is returned. The order of thelayers is the same as the order of the strings in pick. When pick is None, the last layer is returned.
Examples>>> import chainer.functions as F>>> import chainer.links as L>>> model = PickableSequentialChain()>>> with model.init_scope():>>>model.l1 = L.Linear(None, 1000)>>>
model.l1_relu = F.relu>>>
model.l2 = L.Linear(None, 1000)>>>
model.l2_relu = F.relu>>>
model.l3 = L.Linear(None, 10)>>> # This is layer l3>>> layer3 = model(x)>>> # The layers to be collected can be changed.
>>> model.pick = ('l2_relu', 'l1_relu')(continues on next page)

62

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1(continued from previous page)>>> # These are layers l2_relu and l1_relu.
>>> layer2, layer1 = model(x)Parameters• pick (string or iterable of strings) – Names of layers that are collectedduring the forward pass.
• layer_names (iterable of strings) – Names of layers that can be collected fromthis chain. The names are ordered in the order of computation.
copy(*args, **kargs)
Copies the link hierarchy to new one.
The whole hierarchy rooted by this link is copied. There are three modes to perform copy. Please see thedocumentation for the argument mode below.
The name of the link is reset on the copy, since the copied instance does not belong to the original parent
chain (even if exists).
Parameters mode (str) – It should be either init, copy, or share. init means parametervariables under the returned link object is re-initialized by calling their initialize()method, so that all the parameters may have different initial values from the original link.
copy means that the link object is deeply copied, so that its parameters are not re-initialized
but are also deeply copied. Thus, all parameters have same initial values but can be changed
independently. share means that the link is shallowly copied, so that its parameters’ arrays
are shared with the original one. Thus, their values are changed synchronously. The default
mode is share.
Returns Copied link object.
Return type Link
forward(x)Forward this model.
Parameters x (chainer.Variable or array) – Input to the model.
Returns The returned layers are determined by pick.
Return type chainer.Variable or tuple of chainer.Variable
remove_unused()
Delete all layers that are not needed for the forward pass.
Feature Extraction
Feature extraction links extract feature(s) from given images.
ResNetFeature Extraction Link

3.7. Links

63

ChainerCV Documentation, Release 0.13.1

ResNetclass chainercv.links.model.resnet.ResNet(n_layer,
n_class=None,
trained_model=None,
mean=None,
tialW=None, fc_kwargs={}, arch=’fb’)
Base class for ResNet architecture.

preini-This is a pickable sequential link. The network can choose output layers from set of all intermediate layers.
The attribute pick is the names of the layers that are going to be picked by __call__(). The attribute
layer_names is the names of all layers that can be picked.
Examples>>> model = ResNet50()# By default, __call__ returns a probability score (after Softmax).
>>> prob = model(imgs)>>> model.pick = 'res5'# This is layer res5>>> res5 = model(imgs)>>> model.pick = ['res5', 'fc6']>>> # These are layers res5 and fc6.
>>> res5, fc6 = model(imgs)

See also:
chainercv.links.model.PickableSequentialChain
When pretrained_model is the path of a pre-trained chainer model serialized as a npz file in the constructor, this chain model automatically initializes all the parameters with it. When a string in the prespecified set isprovided, a pretrained model is loaded from weights distributed on the Internet. The list of pretrained models
supported are as follows:• imagenet: Loads weights trained with ImageNet. When arch=='he', the weights distributed atModel Zoo are used.
Parameters• n_layer (int) – The number of layers.
• n_class (int) – The number of classes. If None, the default values are used. If a
supported pretrained model is used, the number of classes used to train the pretrained modelis used. Otherwise, the number of classes in ILSVRC 2012 dataset is used.
• pretrained_model (string) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• mean (numpy.ndarray) – A mean value. If None, the default values are used. If a
supported pretrained model is used, the mean value used to train the pretrained model isused. Otherwise, the mean value calculated from ILSVRC 2012 dataset is used.
• initialW (callable) – Initializer for the weights of convolution kernels.
• fc_kwargs (dict) – Keyword arguments passed to initialize the chainer.links.
Linear.

64

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• arch (string) – If fb, use Facebook ResNet architecture. When he, use the architecture presented by the original ResNet paper. This option changes where to apply strided
convolution. The default value is fb.
ResNet50
class chainercv.links.model.resnet.ResNet50(n_class=None,
pretrained_model=None,
mean=None, initialW=None, fc_kwargs={},arch=’fb’)
ResNet-50 Network.
Please consult the documentation for ResNet.
See also:
chainercv.links.model.resnet.ResNet
ResNet101
class chainercv.links.model.resnet.ResNet101(n_class=None, pretrained_model=None,
mean=None,
initialW=None,
fc_kwargs={}, arch=’fb’)
ResNet-101 Network.
Please consult the documentation for ResNet.
See also:
chainercv.links.model.resnet.ResNet
ResNet152
class chainercv.links.model.resnet.ResNet152(n_class=None, pretrained_model=None,
mean=None,
initialW=None,
fc_kwargs={}, arch=’fb’)
ResNet-152 Network.
Please consult the documentation for ResNet.
See also:
chainercv.links.model.resnet.ResNet
Utility
Bottleneckclass chainercv.links.model.resnet.Bottleneck(in_channels, mid_channels, out_channels,
stride=1, dilate=1, groups=1, initialW=None,bn_kwargs={},residual_conv=False,
stride_first=False,
add_seblock=False)
A bottleneck layer.
Parameters3.7. Links

65

ChainerCV Documentation, Release 0.13.1• in_channels (int) – The number of channels of the input array.
• mid_channels (int) – The number of channels of intermediate arrays.
• out_channels (int) – The number of channels of the output array.
• stride (int or tuple of ints) – Stride of filter application.
• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• groups (int) – The number of groups to use grouped convolution in the second layer.
The default is one, where grouped convolution is not used.
• initialW (callable) – Initial weight value used in the convolutional layers.
• bn_kwargs (dict) – Keyword arguments passed to initialize chainer.links.
BatchNormalization.
• residual_conv (bool) – If True, apply a 1x1 convolution to the residual.
• stride_first (bool) – If True, apply strided convolution with the first convolution
layer. Otherwise, apply strided convolution with the second convolution layer.
• add_seblock (bool) – If True, apply a squeeze-and-excitation block to each residual
block.
ResBlockclass chainercv.links.model.resnet.ResBlock(n_layer,
in_channels,
mid_channels,
out_channels,
stride,dilate=1,
groups=1, initialW=None, bn_kwargs={},stride_first=False, add_seblock=False)
A building block for ResNets.
in –> Bottleneck with residual_conv –> Bottleneck * (n_layer - 1) –> out
Parameters• n_layer (int) – The number of layers used in the building block.
• in_channels (int) – The number of channels of the input array.
• mid_channels (int) – The number of channels of intermediate arrays.
• out_channels (int) – The number of channels of the output array.
• stride (int or tuple of ints) – Stride of filter application.
• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• groups (int) – The number of groups to use grouped convolution in the second layer of
each bottleneck. The default is one, where grouped convolution is not used.
• initialW (callable) – Initial weight value used in the convolutional layers.
• bn_kwargs (dict) – Keyword arguments passed to initialize chainer.links.
BatchNormalization.
• stride_first (bool) – This determines the behavior of the bottleneck with a shortcut.
If True, apply strided convolution with the first convolution layer. Otherwise, apply strided
convolution with the second convolution layer.

66

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• add_seblock (bool) – If True, apply a squeeze-and-excitation block to each residual
block.
SEResNet
Feature Extraction Link
SEResNet
class chainercv.links.model.senet.SEResNet(n_layer,
n_class=None,
trained_model=None,
mean=None,
tialW=None, fc_kwargs={})Base class for SE-ResNet architecture.

preini-This architecture is based on ResNet. A squeeze-and-excitation block is applied at the end of each non-identity
branch of residual block. Please refer to the original paper for a detailed description of network architecture.
Similar to chainercv.links.model.resnet.ResNet, ImageNet pretrained weights are downloaded
when pretrained_model argument is imagenet, originally distributed at the Github repository by one ofthe paper authors.
See also:
chainercv.links.model.resnet.ResNet chainercv.links.connection.SEBlock
Parameters• n_layer (int) – The number of layers.
• n_class (int) – The number of classes. If None, the default values are used. If a
supported pretrained model is used, the number of classes used to train the pretrained modelis used. Otherwise, the number of classes in ILSVRC 2012 dataset is used.
• pretrained_model (string) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• mean (numpy.ndarray) – A mean value. If None, the default values are used. If a
supported pretrained model is used, the mean value used to train the pretrained model isused. Otherwise, the mean value calculated from ILSVRC 2012 dataset is used.
• initialW (callable) – Initializer for the weights of convolution kernels.
• fc_kwargs (dict) – Keyword arguments passed to initialize the chainer.links.
Linear.
SEResNet50
class chainercv.links.model.senet.SEResNet50(n_class=None,
mean=None,
fc_kwargs={})
SE-ResNet-50 Network.

pretrained_model=None,
initialW=None,

Please consult the documentation for SEResNet.
See also:
3.7. Links

67

ChainerCV Documentation, Release 0.13.1

chainercv.links.model.senet.SEResNet
SEResNet101
class chainercv.links.model.senet.SEResNet101(n_class=None, pretrained_model=None,
mean=None,
initialW=None,
fc_kwargs={})
SE-ResNet-101 Network.
Please consult the documentation for SEResNet.
See also:
chainercv.links.model.senet.SEResNet
SEResNet152
class chainercv.links.model.senet.SEResNet152(n_class=None, pretrained_model=None,
mean=None,
initialW=None,
fc_kwargs={})
SE-ResNet-152 Network.
Please consult the documentation for SEResNet.
See also:
chainercv.links.model.senet.SEResNet
SEResNeXt
class chainercv.links.model.senet.SEResNeXt(n_layer,
n_class=None,
trained_model=None, mean=None,
tialW=None, fc_kwargs={})Base class for SE-ResNeXt architecture.

preini-ResNeXt is a ResNet-based architecture, where grouped convolution is adopted to the second convolution layerof each bottleneck block. In addition, a squeeze-and-excitation block is applied at the end of each non-identity
branch of residual block. Please refer to Aggregated Residual Transformations for Deep Neural Networks andSqueeze-and-Excitation Networks for detailed description of network architecture.
Similar to chainercv.links.model.resnet.ResNet, ImageNet pretrained weights are downloaded
when pretrained_model argument is imagenet, originally distributed at the Github repository by one ofthe paper authors of SENet.
See also:
chainercv.links.model.resnet.ResNet
chainercv.links.connection.SEBlockchainercv.links.model.senet.SEResNet

Parameters• n_layer (int) – The number of layers.
• n_class (int) – The number of classes. If None, the default values are used. If a
supported pretrained model is used, the number of classes used to train the pretrained modelis used. Otherwise, the number of classes in ILSVRC 2012 dataset is used.

68

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• pretrained_model (string) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• mean (numpy.ndarray) – A mean value. If None, the default values are used. If a
supported pretrained model is used, the mean value used to train the pretrained model isused. Otherwise, the mean value calculated from ILSVRC 2012 dataset is used.
• initialW (callable) – Initializer for the weights of convolution kernels.
• fc_kwargs (dict) – Keyword arguments passed to initialize the chainer.links.
Linear.
SEResNeXt50
class chainercv.links.model.senet.SEResNeXt50(n_class=None, pretrained_model=None,
mean=None,
initialW=None,
fc_kwargs={})
SE-ResNeXt-50 Network
Please consult the documentation for SEResNeXt.
See also:
chainercv.links.model.senet.SEResNeXt
SEResNeXt101
class chainercv.links.model.senet.SEResNeXt101(n_class=None,
pretrained_model=None,
mean=None,
initialW=None, fc_kwargs={})
SE-ResNeXt-101 Network
Please consult the documentation for SEResNeXt.
See also:
chainercv.links.model.senet.SEResNeXt
VGG
VGG16
class chainercv.links.model.vgg.VGG16(n_class=None,
pretrained_model=None,
mean=None, initialW=None, initial_bias=None)
VGG-16 Network.
This is a pickable sequential link. The network can choose output layers from set of all intermediate layers.
The attribute pick is the names of the layers that are going to be picked by forward(). The attribute
layer_names is the names of all layers that can be picked.

3.7. Links

69

ChainerCV Documentation, Release 0.13.1

Examples>>> model = VGG16()# By default, forward returns a probability score (after Softmax).
>>> prob = model(imgs)>>> model.pick = 'conv5_3'# This is layer conv5_3 (after ReLU).
>>> conv5_3 = model(imgs)>>> model.pick = ['conv5_3', 'fc6']>>> # These are layers conv5_3 (after ReLU) and fc6 (before ReLU).
>>> conv5_3, fc6 = model(imgs)

See also:
chainercv.links.model.PickableSequentialChain
When pretrained_model is the path of a pre-trained chainer model serialized as a npz file in the constructor, this chain model automatically initializes all the parameters with it. When a string in the prespecified set isprovided, a pretrained model is loaded from weights distributed on the Internet. The list of pretrained models
supported are as follows:• imagenet: Loads weights trained with ImageNet and distributed at Model Zoo.
Parameters• n_class (int) – The number of classes. If None, the default values are used. If a
supported pretrained model is used, the number of classes used to train the pretrained modelis used. Otherwise, the number of classes in ILSVRC 2012 dataset is used.
• pretrained_model (string) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• mean (numpy.ndarray) – A mean value. If None, the default values are used. If a
supported pretrained model is used, the mean value used to train the pretrained model isused. Otherwise, the mean value calculated from ILSVRC 2012 dataset is used.
• initialW (callable) – Initializer for the weights.
• initial_bias (callable) – Initializer for the biases.
Detection
Detection links share a common method predict() to detect objects in images. For more details, please read
FasterRCNN.predict().
Faster R-CNN
Detection Link

70

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

FasterRCNNVGG16class chainercv.links.model.faster_rcnn.FasterRCNNVGG16(n_fg_class=None,
pretrained_model=None,min_size=600,
max_size=1000,
ratios=[0.5, 1, 2], anchor_scales=[8,16,32], vgg_initialW=None,
rpn_initialW=None,
loc_initialW=None,score_initialW=None, proposal_creator_params={})Faster R-CNN based on VGG-16.
When you specify the path of a pre-trained chainer model serialized as a npz file in the constructor, this chain
model automatically initializes all the parameters with it. When a string in prespecified set is provided, apretrained model is loaded from weights distributed on the Internet. The list of pretrained models supported are
as follows:• voc07: Loads weights trained with the trainval split of PASCAL VOC2007 Detection Dataset.
• imagenet: Loads weights trained with ImageNet Classfication task for the feature extractor and the head
modules. Weights that do not have a corresponding layer in VGG-16 will be randomly initialized.
For descriptions on the interface of this model, please refer to FasterRCNN .
FasterRCNNVGG16 supports finer control on random initializations of weights by arguments
vgg_initialW, rpn_initialW, loc_initialW and score_initialW. It accepts a callable thattakes an array and edits its values. If None is passed as an initializer, the default initializer is used.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The destination of the pre-trained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• min_size (int) – A preprocessing paramter for prepare().
• max_size (int) – A preprocessing paramter for prepare().
• ratios (list of floats) – This is ratios of width to height of the anchors.
• anchor_scales (list of numbers) – This is areas of anchors. Those areas will be
the product of the square of an element in anchor_scales and the original area of thereference window.
• vgg_initialW (callable) – Initializer for the layers corresponding to the VGG-16
layers.
• rpn_initialW (callable) – Initializer for Region Proposal Network layers.
• loc_initialW (callable) – Initializer for the localization head.
• score_initialW (callable) – Initializer for the score head.
• proposal_creator_params
ProposalCreator.

3.7. Links(dict)–

Key

valuedparamtersfor71ChainerCV Documentation, Release 0.13.1

Utility
bbox2loc
chainercv.links.model.faster_rcnn.bbox2loc(src_bbox, dst_bbox)
Encodes the source and the destination bounding boxes to “loc”.
Given bounding boxes, this function computes offsets and scales to match the source bounding boxes to thetarget bounding boxes. Mathematcially, given a bounding box whose center is (𝑦, 𝑥) = 𝑝𝑦 , 𝑝𝑥 and size 𝑝ℎ , 𝑝𝑤
and the target bounding box whose center is 𝑔𝑦 , 𝑔𝑥 and size 𝑔ℎ , 𝑔𝑤 , the offsets and scales 𝑡𝑦 , 𝑡𝑥 , 𝑡ℎ , 𝑡𝑤 can becomputed by the following formulas.
• 𝑡𝑦 =(𝑔𝑦 −𝑝𝑦 )𝑝ℎ𝑥)• 𝑡𝑥 = (𝑔𝑥𝑝−𝑝𝑤• 𝑡ℎ = log( 𝑝𝑔ℎℎ )• 𝑡𝑤 = log( 𝑝𝑔𝑤𝑤 )The output is same type as the type of the inputs. The encoding formulas are used in works such as R-CNN1 .
Parameters• src_bbox (array) – An image coordinate array whose shape is (𝑅, 4). 𝑅 is the numberof bounding boxes. These coordinates are 𝑝𝑦𝑚𝑖𝑛 , 𝑝𝑥𝑚𝑖𝑛 , 𝑝𝑦𝑚𝑎𝑥 , 𝑝𝑥𝑚𝑎𝑥 .
• dst_bbox (array) – An image coordinate array whose shape is (𝑅, 4). These coordinates are 𝑔𝑦𝑚𝑖𝑛 , 𝑔𝑥𝑚𝑖𝑛 , 𝑔𝑦𝑚𝑎𝑥 , 𝑔𝑥𝑚𝑎𝑥 .
Returns Bounding box offsets and scales from src_bbox to dst_bbox. This has shape (𝑅, 4).
The second axis contains four values 𝑡𝑦 , 𝑡𝑥 , 𝑡ℎ , 𝑡𝑤 .
Return type array
FasterRCNN
class chainercv.links.model.faster_rcnn.FasterRCNN(extractor, rpn, head, mean,
min_size=600, max_size=1000,
loc_normalize_mean=(0.0, 0.0,
0.0, 0.0), loc_normalize_std=(0.1,
0.1, 0.2, 0.2))
Base class for Faster R-CNN.
This is a base class for Faster R-CNN links supporting object detection API2 . The following three stages constitute Faster R-CNN.
1. Feature extraction: Images are taken and their feature maps are calculated.
2. Region Proposal Networks: Given the feature maps calculated in the previous stage, produce set of RoIs
around objects.
3. Localization and Classification Heads: Using feature maps that belong to the proposed RoIs, classify
the categories of the objects in the RoIs and improve localizations.
1 Ross Girshick, Jeff Donahue, Trevor Darrell, Jitendra Malik. Rich feature hierarchies for accurate object detection and semantic segmentation.
CVPR 2014.
2 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.
NIPS 2015.

72

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Each stage is carried out by one of the callable chainer.Chain objects feature, rpn and head.
There are two functions predict() and forward() to conduct object detection. predict() takes images
and returns bounding boxes that are converted to image coordinates. This will be useful for a scenario when
Faster R-CNN is treated as a black box function, for instance. forward() is provided for a scnerario whenintermediate outputs are needed, for instance, for training and debugging.
Links that support obejct detection API have method predict() with the same interface. Please refer topredict() for further details.
Parameters• extractor (callable Chain) – A callable that takes a BCHW image array and returns feature maps.
• rpn (callable Chain) – A callable that has the same interface
RegionProposalNetwork. Please refer to the documentation found there.

as• head (callable Chain) – A callable that takes a BCHW array, RoIs and batch indicesfor RoIs. This returns class dependent localization paramters and class scores.
• mean (numpy.ndarray) – A value to be subtracted from an image in prepare().
• min_size (int) – A preprocessing paramter for prepare(). Please refer to a docstring
found for prepare().
• max_size (int) – A preprocessing paramter for prepare().
• loc_normalize_mean (tuple of four floats) – Mean values of localization
estimates.
• loc_normalize_std (tupler of four floats) – Standard deviation of localization estimates.
forward(x, scales=None)
Forward Faster R-CNN.
Scaling paramter scales is used by RPN to determine the threshold to select small objects, which aregoing to be rejected irrespective of their confidence scores.
Here are notations used.
• 𝑁 is the number of batch size
• 𝑅′ is the∑︀𝑁total number of RoIs produced across batches. Given 𝑅𝑖 proposed RoIs from the 𝑖 th image,𝑅′ = 𝑖=1 𝑅𝑖 .
• 𝐿 is the number of classes excluding the background.
Classes are ordered by the background, the first class, . . . , and the 𝐿 th class.
Parameters• x (Variable) – 4D image variable.
• scales (tuple of floats) – Amount of scaling applied to each input image during
preprocessing.
Returns
Returns tuple of four values listed below.
• roi_cls_locs: Offsets and scalings for the proposed RoIs. Its shape is (𝑅′ , (𝐿 + 1) × 4).
• roi_scores: Class predictions for the proposed RoIs. Its shape is (𝑅′ , 𝐿 + 1).
• rois: RoIs proposed by RPN. Its shape is (𝑅′ , 4).

3.7. Links

73

ChainerCV Documentation, Release 0.13.1• roi_indices: Batch indices of RoIs. Its shape is (𝑅′ , ).
Return type Variable, Variable, array, array
predict(imgs)
Detect objects from images.
This method predicts objects for each image.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their value is [0, 255].
Returns
This method returns a tuple of three lists, (bboxes, labels, scores).
• bboxes: A list of float arrays of shape (𝑅, 4), where 𝑅 is the number of bounding boxes
in a image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second
axis.
• labels : A list of integer arrays of shape (𝑅, ). Each value indicates the class of thebounding box. Values are in range [0, 𝐿 − 1], where 𝐿 is the number of the foregroundclasses.
• scores : A list of float arrays of shape (𝑅, ). Each value indicates how confident theprediction is.
Return type tuple of lists
prepare(img)
Preprocess an image for feature extraction.
The length of the shorter edge is scaled to self.min_size. After the scaling, if the length of the longer
edge is longer than self.max_size, the image is scaled to fit the longer edge to self.max_size.
After resizing the image, the image is subtracted by a mean image value self.mean.
Parameters img (ndarray) – An image. This is in CHW and RGB format. The range of its
value is [0, 255].
Returns A preprocessed image.
Return type ndarray
use_preset(preset)
Use the given preset during prediction.
This method changes values of self.nms_thresh and self.score_thresh. These values area threshold value used for non maximum suppression and a threshold value to discard low confidence
proposals in predict(), respectively.
If the attributes need to be changed to something other than the values provided in the presets, pleasemodify them by directly accessing the public attributes.
Parameters preset ({'visualize', 'evaluate') – A string to determine the preset
to use.
generate_anchor_basechainercv.links.model.faster_rcnn.generate_anchor_base(base_size=16, ratios=[0.5,1, 2], anchor_scales=[8, 16,
32])
Generate anchor base windows by enumerating aspect ratio and scales.

74

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Generate anchors that are scaled and modified to the given aspect ratios. Area of a scaled anchor is preserved
when modifying to the given aspect ratio.
R = len(ratios) * len(anchor_scales) anchors are generated by this function. The i *len(anchor_scales) + j th anchor corresponds to an anchor generated by ratios[i] andanchor_scales[j].
For example, if the scale is 8 and the ratio is 0.25, the width and the height of the base window will be stretchedby 8. For modifying the anchor to the given aspect ratio, the height is halved and the width is doubled.
Parameters• base_size (number) – The width and the height of the reference window.
• ratios (list of floats) – This is ratios of width to height of the anchors.
• anchor_scales (list of numbers) – This is areas of anchors. Those areas will be
the product of the square of an element in anchor_scales and the original area of thereference window.
Returns An array of shape (𝑅, 4). Each element is a set of coordinates of a bounding box. The
second axis corresponds to (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) of a bounding box.
Return type ndarray
loc2bbox
chainercv.links.model.faster_rcnn.loc2bbox(src_bbox, loc)
Decode bounding boxes from bounding box offsets and scales.
Given bounding box offsets and scales computed by bbox2loc(), this function decodes the representation tocoordinates in 2D image coordinates.
Given scales and offsets 𝑡𝑦 , 𝑡𝑥 , 𝑡ℎ , 𝑡𝑤 and a bounding box whose center is (𝑦, 𝑥) = 𝑝𝑦 , 𝑝𝑥 and size 𝑝ℎ , 𝑝𝑤 , thedecoded bounding box’s center 𝑔ˆ𝑦 , 𝑔ˆ𝑥 and size 𝑔ˆℎ , 𝑔ˆ𝑤 are calculated by the following formulas.
• 𝑔ˆ𝑦 = 𝑝ℎ 𝑡𝑦 + 𝑝𝑦
• 𝑔ˆ𝑥 = 𝑝𝑤 𝑡𝑥 + 𝑝𝑥
• 𝑔ˆℎ = 𝑝ℎ exp(𝑡ℎ )• 𝑔ˆ𝑤 = 𝑝𝑤 exp(𝑡𝑤 )The decoding formulas are used in works such as R-CNN3 .
The output is same type as the type of the inputs.
Parameters• src_bbox (array) – A coordinates of bounding boxes. Its shape is (𝑅, 4). These coordinates are 𝑝𝑦𝑚𝑖𝑛 , 𝑝𝑥𝑚𝑖𝑛 , 𝑝𝑦𝑚𝑎𝑥 , 𝑝𝑥𝑚𝑎𝑥 .
• loc (array) – An array with offsets and scales. The shapes of src_bbox and loc
should be same. This contains values 𝑡𝑦 , 𝑡𝑥 , 𝑡ℎ , 𝑡𝑤 .
Returns Decoded bounding box coordinates. Its shape is (𝑅, 4). The second axis contains four
values 𝑔ˆ𝑦𝑚𝑖𝑛 , 𝑔ˆ𝑥𝑚𝑖𝑛 , 𝑔ˆ𝑦𝑚𝑎𝑥 , 𝑔ˆ𝑥𝑚𝑎𝑥 .
Return type array
3 Ross Girshick, Jeff Donahue, Trevor Darrell, Jitendra Malik. Rich feature hierarchies for accurate object detection and semantic segmentation.
CVPR 2014.

3.7. Links

75

ChainerCV Documentation, Release 0.13.1

ProposalCreatorclass chainercv.links.model.faster_rcnn.ProposalCreator(nms_thresh=0.7,
n_train_pre_nms=12000,
n_train_post_nms=2000,
n_test_pre_nms=6000,
n_test_post_nms=300,
force_cpu_nms=False,
min_size=16)
Proposal regions are generated by calling this object.
The __call__() of this object outputs object detection proposals by applying estimated bounding box offsets
to a set of anchors.
This class takes parameters to control number of bounding boxes to pass to NMS and keep after NMS. If theparamters are negative, it uses all the bounding boxes supplied or keep all the bounding boxes returned by NMS.
This class is used for Region Proposal Networks introduced in Faster R-CNN4 .
Parameters• nms_thresh (float) – Threshold value used when calling NMS.
• n_train_pre_nms (int) – Number of top scored bounding boxes to keep before passing to NMS in train mode.
• n_train_post_nms (int) – Number of top scored bounding boxes to keep after passing
to NMS in train mode.
• n_test_pre_nms (int) – Number of top scored bounding boxes to keep before passing
to NMS in test mode.
• n_test_post_nms (int) – Number of top scored bounding boxes to keep after passing
to NMS in test mode.
• force_cpu_nms (bool) – If this is True, always use NMS in CPU mode. If False,
the NMS mode is selected based on the type of inputs.
• min_size (int) – A paramter to determine the threshold on discarding bounding boxes
based on their sizes.
__call__(loc, score, anchor, img_size, scale=1.0)
Propose RoIs.
Inputs loc, score, anchor refer to the same anchor when indexed by the same index.
On notations, 𝑅 is the total number of anchors. This is equal to product of the height and the width of animage and the number of anchor bases per pixel.
Type of the output is same as the inputs.
Parameters• loc (array) – Predicted offsets and scaling to anchors. Its shape is (𝑅, 4).
• score (array) – Predicted foreground probability for anchors. Its shape is (𝑅, ).
• anchor (array) – Coordinates of anchors. Its shape is (𝑅, 4).
• img_size (tuple of ints) – A tuple height, width, which contains image
size after scaling.
4 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.

NIPS 2015.

76

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• scale (float) – The scaling factor used to scale an image after reading it from a file.
Returns An array of coordinates of proposal boxes. Its shape is (𝑆, 4). 𝑆 is less than self.
n_test_post_nms in test time and less than self.n_train_post_nms in train time.
𝑆 depends on the size of the predicted bounding boxes and the number of bounding boxes
discarded by NMS.
Return type array
RegionProposalNetworkclass chainercv.links.model.faster_rcnn.RegionProposalNetwork(in_channels=512,
mid_channels=512,
ratios=[0.5,1,2],anchor_scales=[8,16,32],feat_stride=16,
initialW=None,
proposal_creator_params={})Region Proposal Network introduced in Faster R-CNN.
This is Region Proposal Network introduced in Faster R-CNN5 . This takes features extracted from images andpropose class agnostic bounding boxes around “objects”.
Parameters• in_channels (int) – The channel size of input.
• mid_channels (int) – The channel size of the intermediate tensor.
• ratios (list of floats) – This is ratios of width to height of the anchors.
• anchor_scales (list of numbers) – This is areas of anchors. Those areas will be
the product of the square of an element in anchor_scales and the original area of thereference window.
• feat_stride (int) – Stride size after extracting features from an image.
• initialW (callable) – Initial weight value. If None then this function uses Gaussian
distribution scaled by 0.1 to initialize weight. May also be a callable that takes an array andedits its values.
• proposal_creator_params
ProposalCreator.

(dict)–

Key

valuedparamtersfor

See also:
ProposalCreator
forward(x, img_size, scales=None)
Forward Region Proposal Network.
Here are notations.
• 𝑁 is batch size.
• 𝐶 channel size of the input.
5 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.
NIPS 2015.

3.7. Links

77

ChainerCV Documentation, Release 0.13.1• 𝐻 and 𝑊 are height and witdh of the input feature.
• 𝐴 is number of anchors assigned to each pixel.
Parameters• x (Variable) – The Features extracted from images. Its shape is (𝑁, 𝐶, 𝐻, 𝑊 ).
• img_size (tuple of ints) – A tuple height, width, which contains image
size after scaling.
• scales (tuple of floats) – The amount of scaling done to each input image during preprocessing.
Returns
This is a tuple of five following values.
• rpn_locs: Predicted bounding box offsets and scales for anchors.
(𝑁, 𝐻𝑊 𝐴, 4).

Its shape is• rpn_scores: Predicted foreground scores for anchors. Its shape is (𝑁, 𝐻𝑊 𝐴, 2).
• rois: A bounding box array containing coordinates of proposal boxes. This is a concatenation of bounding box arrays from multiple images in the batch. Its shape is (𝑅′ , 4). Given∑︀𝑁
𝑅𝑖 predicted bounding boxes from the 𝑖 th image, 𝑅′ = 𝑖=1 𝑅𝑖 .
• roi_indices: An array containing indices of images to which RoIs correspond to. Its shapeis (𝑅′ , ).
• anchor: Coordinates of enumerated shifted anchors. Its shape is (𝐻𝑊 𝐴, 4).
Return type (Variable, Variable, array, array, array)
VGG16RoIHead
class chainercv.links.model.faster_rcnn.VGG16RoIHead(n_class,roi_size,spatial_scale, vgg_initialW=None,
loc_initialW=None,score_initialW=None)
Faster R-CNN Head for VGG-16 based implementation.
This class is used as a head for Faster R-CNN. This outputs class-wise localizations and classification based onfeature maps in the given RoIs.
Parameters• n_class (int) – The number of classes possibly including the background.
• roi_size (int) – Height and width of the feature maps after RoI-pooling.
• spatial_scale (float) – Scale of the roi is resized.
• vgg_initialW (callable) – Initializer for the layers corresponding to the VGG-16
layers.
• loc_initialW (callable) – Initializer for the localization head.
• score_initialW (callable) – Initializer for the score head.

78

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Train-only Utility
AnchorTargetCreatorclass chainercv.links.model.faster_rcnn.AnchorTargetCreator(n_sample=256,
pos_iou_thresh=0.7,
neg_iou_thresh=0.3,
pos_ratio=0.5)
Assign the ground truth bounding boxes to anchors.
Assigns the ground truth bounding boxes to anchors for training Region Proposal Networks introduced in Faster
R-CNN6 .
Offsets and scales to match anchors to the ground truth are calculated using the encoding scheme ofbbox2loc().
Parameters• n_sample (int) – The number of regions to produce.
• pos_iou_thresh (float) – Anchors with IoU above this threshold will be assigned as
positive.
• neg_iou_thresh (float) – Anchors with IoU below this threshold will be assigned as
negative.
• pos_ratio (float) – Ratio of positive regions in the sampled regions.
__call__(bbox, anchor, img_size)
Assign ground truth supervision to sampled subset of anchors.
Types of input arrays and output arrays are same.
Here are notations.
• 𝑆 is the number of anchors.
• 𝑅 is the number of bounding boxes.
Parameters• bbox (array) – Coordinates of bounding boxes. Its shape is (𝑅, 4).
• anchor (array) – Coordinates of anchors. Its shape is (𝑆, 4).
• img_size (tuple of ints) – A tuple H, W, which is a tuple of height and width of
an image.
Returns• loc: Offsets and scales to match the anchors to the ground truth bounding boxes. Its shapeis (𝑆, 4).
• label: Labels of anchors with values (1=positive, 0=negative, -1=ignore).
Its shape is (𝑆, ).
Return type (array, array)
6 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.
NIPS 2015.

3.7. Links

79

ChainerCV Documentation, Release 0.13.1

FasterRCNNTrainChainclass chainercv.links.model.faster_rcnn.FasterRCNNTrainChain(faster_rcnn,
rpn_sigma=3.0,
roi_sigma=1.0, anchor_target_creator=<chainercv.links.mode
object>,proposal_target_creator=<chainercv.links.mod
object>)Calculate losses for Faster R-CNN and report them.
This is used to train Faster R-CNN in the joint training scheme7 .
The losses include:• rpn_loc_loss: The localization loss for Region Proposal Network (RPN).
• rpn_cls_loss: The classification loss for RPN.
• roi_loc_loss: The localization loss for the head module.
• roi_cls_loss: The classification loss for the head module.
Parameters• faster_rcnn (FasterRCNN) – A Faster R-CNN model that is going to be trained.
• rpn_sigma (float) – Sigma parameter for the localization loss of Region Proposal Network (RPN). The default value is 3, which is the value used in7 .
• roi_sigma (float) – Sigma paramter for the localization loss of the head. The default
value is 1, which is the value used in7 .
• anchor_target_creator – An instantiation of AnchorTargetCreator.
• proposal_target_creator – An instantiation of ProposalTargetCreator.
forward(imgs, bboxes, labels, scales)
Forward Faster R-CNN and calculate losses.
Here are notations used.
• 𝑁 is the batch size.
• 𝑅 is the number of bounding boxes per image.
Currently, only 𝑁 = 1 is supported.
Parameters• imgs (Variable) – A variable with a batch of images.
• bboxes (Variable) – A batch of bounding boxes. Its shape is (𝑁, 𝑅, 4).
• labels (Variable) – A batch of labels. Its shape is (𝑁, 𝑅). The background is excluded from the definition, which means that the range of the value is [0, 𝐿 − 1]. 𝐿 is thenumber of foreground classes.
• scales (Variable) – Amount of scaling applied to each input image during preprocessing.
7 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.
NIPS 2015.

80

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Returns Scalar loss variable. This is the sum of losses for Region Proposal Network and thehead module.
Return type chainer.Variable
ProposalTargetCreatorclass chainercv.links.model.faster_rcnn.ProposalTargetCreator(n_sample=128,
pos_ratio=0.25,
pos_iou_thresh=0.5,
neg_iou_thresh_hi=0.5,
neg_iou_thresh_lo=0.0)
Assign ground truth bounding boxes to given RoIs.
The __call__() of this class generates training targets for each object proposal. This is used to train Faster
RCNN8 .
Parameters• n_sample (int) – The number of sampled regions.
• pos_ratio (float) – Fraction of regions that is labeled as a foreground.
• pos_iou_thresh (float) – IoU threshold for a RoI to be considered as a foreground.
• neg_iou_thresh_hi (float) – RoI is considered to be the background if IoU is in[neg_iou_thresh_lo, neg_iou_thresh_hi).
• neg_iou_thresh_lo (float) – See above.
__call__(roi, bbox, label, loc_normalize_mean=(0.0, 0.0, 0.0, 0.0), loc_normalize_std=(0.1, 0.1, 0.2,
0.2))
Assigns ground truth to sampled proposals.
This function samples total of self.n_sample RoIs from the combination of roi and bbox. The
RoIs are assigned with the ground truth class labels as well as bounding box offsets and scales to matchthe ground truth bounding boxes. As many as pos_ratio * self.n_sample RoIs are sampled as
foregrounds.
Offsets and scales of bounding boxes are calculated using chainercv.links.model.
faster_rcnn.bbox2loc(). Also, types of input arrays and output arrays are same.
Here are notations.
• 𝑆 is the total number of sampled RoIs, which equals self.n_sample.
• 𝐿 is number of object classes possibly including the background.
Parameters• roi (array) – Region of Interests (RoIs) from which we sample. Its shape is (𝑅, 4)• bbox (array) – The coordinates of ground truth bounding boxes. Its shape is (𝑅′ , 4).
• label (array) – Ground truth bounding box labels. Its shape is (𝑅′ , ). Its range is[0, 𝐿 − 1], where 𝐿 is the number of foreground classes.
• loc_normalize_mean (tuple of four floats) – Mean values to normalize
coordinates of bounding boxes.
8 Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks.
NIPS 2015.

3.7. Links

81

ChainerCV Documentation, Release 0.13.1• loc_normalize_std (tuple of four floats) – Standard deviation of the coordinates of bounding boxes.
Returns• sample_roi: Regions of interests that are sampled. Its shape is (𝑆, 4).
• gt_roi_loc: Offsets and scales to match the sampled RoIs to the ground truth boundingboxes. Its shape is (𝑆, 4).
• gt_roi_label: Labels assigned to sampled RoIs. Its shape is (𝑆, ). Its range is [0, 𝐿]. The
label with value 0 is the background.
Return type (array, array, array)
SSD (Single Shot Multibox Detector)
Detection Links
SSD300class chainercv.links.model.ssd.SSD300(n_fg_class=None, pretrained_model=None)
Single Shot Multibox Detector with 300x300 inputs.
This is a model of Single Shot Multibox Detector1 . This model uses VGG16Extractor300 as its feature
extractor.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded.
'voc0712', filepath or None. The default value is None.

This can take– 'voc0712': Load weights trained on trainval split of PASCAL VOC 2007 and 2012.
The weight file is downloaded and cached automatically. n_fg_class must be 20 orNone. These weights were converted from the Caffe model provided by the original
implementation. The conversion code is chainercv/examples/ssd/caffe2npz.py.
– 'imagenet': Load weights of VGG-16 trained on ImageNet. The weight file is downloaded and cached automatically. This option initializes weights partially and the rests
are initialized randomly. In this case, n_fg_class can be set to any number.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
SSD512class chainercv.links.model.ssd.SSD512(n_fg_class=None, pretrained_model=None)
Single Shot Multibox Detector with 512x512 inputs.
This is a model of Single Shot Multibox Detector2 . This model uses VGG16Extractor512 as its feature
extractor.
1 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.
2 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

82

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded.
'voc0712', filepath or None. The default value is None.

This can take– 'voc0712': Load weights trained on trainval split of PASCAL VOC 2007 and 2012.
The weight file is downloaded and cached automatically. n_fg_class must be 20 orNone. These weights were converted from the Caffe model provided by the original
implementation. The conversion code is chainercv/examples/ssd/caffe2npz.py.
– 'imagenet': Load weights of VGG-16 trained on ImageNet. The weight file is downloaded and cached automatically. This option initializes weights partially and the rests
are initialized randomly. In this case, n_fg_class can be set to any number.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
UtilityMultibox
class chainercv.links.model.ssd.Multibox(n_class, aspect_ratios,
tial_bias=None)
Multibox head of Single Shot Multibox Detector.

initialW=None,

ini-

This is a head part of Single Shot Multibox Detector3 . This link computes mb_locs and mb_confs fromfeature maps. mb_locs contains information of the coordinates of bounding boxes and mb_confs contains
confidence scores of each classes.
Parameters• n_class (int) – The number of classes possibly including the background.
• aspect_ratios (iterable of tuple or int) – The aspect ratios of default
bounding boxes for each feature map.
• initialW – An initializer used in chainer.links.Convolution2d.
__init__(). The default value is chainer.initializers.LeCunUniform.
• initial_bias – An initializer used in chainer.links.Convolution2d.
__init__(). The default value is chainer.initializers.Zero.
forward(xs)Compute loc and conf from feature maps
This method computes mb_locs and mb_confs from given feature maps.
Parameters xs (iterable of chainer.Variable) – An iterable of feature maps. The
number of feature maps must be same as the number of aspect_ratios.
Returns
This method returns two chainer.Variable: mb_locs and mb_confs.
• mb_locs: A variable of float arrays of shape (𝐵, 𝐾, 4), where 𝐵 is the number of samples
in the batch and 𝐾 is the number of default bounding boxes.
3 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox

Detector. ECCV 2016.

3.7. Links

83

ChainerCV Documentation, Release 0.13.1• mb_confs: A variable of float arrays of shape (𝐵, 𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 + 1).
Return type tuple of chainer.Variable
MultiboxCoderclass chainercv.links.model.ssd.MultiboxCoder(grids, aspect_ratios, steps, sizes, variance)
A helper class to encode/decode bounding boxes.
This class encodes (bbox, label) to (mb_loc, mb_label) and decodes (mb_loc, mb_conf) to(bbox, label, score). These encoding/decoding are used in Single Shot Multibox Detector4 .
• mb_loc: An array representing offsets and scales from the default bounding boxes. Its shape is(𝐾, 4), where 𝐾 is the number of the default bounding boxes. The second axis is composed by(∆𝑦, ∆𝑥, ∆ℎ, ∆𝑤). These values are computed by the following formulas.
– ∆𝑦 = (𝑏𝑦 − 𝑚𝑦 )/(𝑚ℎ * 𝑣0 )– ∆𝑥 = (𝑏𝑥 − 𝑚𝑥 )/(𝑚𝑤 * 𝑣0 )– ∆ℎ = 𝑙𝑜𝑔(𝑏ℎ /𝑚ℎ )/𝑣1
– ∆𝑤 = 𝑙𝑜𝑔(𝑏𝑤 /𝑚𝑤 )/𝑣1
(𝑚𝑦 , 𝑚𝑥 ) and (𝑚ℎ , 𝑚𝑤 ) are center coodinates and size of a default bounding box. (𝑏𝑦 , 𝑏𝑥 ) and(𝑏ℎ , 𝑏𝑤 ) are center coodinates and size of a given bounding boxes that is assined to the default
bounding box. (𝑣0 , 𝑣1 ) are coefficients that can be set by argument variance.
• mb_label: An array representing classes of ground truth bounding boxes. Its shape is (𝐾, ).
• mb_conf: An array representing classes of predicted bounding boxes. Its shape is (𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 + 1).
Parameters• grids (iterable of ints) – An iterable of integers. Each integer indicates the sizeof a feature map.
• aspect_ratios (iterable of tuples of ints) – An iterable of tuples of integers used to compute the default bounding boxes. Each tuple indicates the aspect ratiosof the default bounding boxes at each feature maps. The length of this iterable should belen(grids).
• steps (iterable of floats) – The step size for each feature map. The length of
this iterable should be len(grids).
• sizes (iterable of floats) – The base size of default bounding boxes for eachfeature map. The length of this iterable should be len(grids) + 1.
• variance (tuple of floats) – Two coefficients for encoding/decoding the locationsof bounding boxes. The first value is used to encode/decode coordinates of the centers. The
second value is used to encode/decode the sizes of bounding boxes.
decode(mb_loc, mb_conf, nms_thresh=0.45, score_thresh=0.6)
Decodes back to coordinates and classes of bounding boxes.
This method decodes mb_loc and mb_conf returned by a SSD network back to bbox, label andscore.
4 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

84

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• mb_loc (array) – A float array whose shape is (𝐾, 4), 𝐾 is the number of default
bounding boxes.
• mb_conf (array) – A float array whose shape is (𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 + 1).
• nms_thresh (float) – The threshold value for non_maximum_suppression().
The default value is 0.45.
• score_thresh (float) – The threshold value for confidence score. If a bounding box
whose confidence score is lower than this value, the bounding box will be suppressed. The
default value is 0.6.
Returns
This method returns a tuple of three arrays, (bbox, label, score).
• bbox: A float array of shape (𝑅, 4), where 𝑅 is the number of bounding boxes in a image.
Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second axis.
• label : An integer array of shape (𝑅, ). Each value indicates the class of the bounding box.
• score : A float array of shape (𝑅, ). Each value indicates how confident the prediction is.
Return type tuple of three arrays
encode(bbox, label, iou_thresh=0.5)
Encodes coordinates and classes of bounding boxes.
This method encodes bbox and label to mb_loc and mb_label, which are used to compute multibox
loss.
Parameters• bbox (array) – A float array of shape (𝑅, 4), where 𝑅 is the number of bounding boxes
in an image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second
axis.
• label (array) – An integer array of shape (𝑅, ). Each value indicates the class of thebounding box.
• iou_thresh (float) – The threshold value to determine a default bounding box isassigned to a ground truth or not. The default value is 0.5.
Returns
This method returns a tuple of two arrays, (mb_loc, mb_label).
• mb_loc: A float array of shape (𝐾, 4), where 𝐾 is the number of default bounding boxes.
• mb_label: An integer array of shape (𝐾, ).
Return type tuple of two arrays
Normalize
class chainercv.links.model.ssd.Normalize(n_channel, initial=0, eps=1e-05)
Learnable L2 normalization5 .
This link normalizes input along the channel axis and scales it. The scale factors are trained channel-wise.
Parameters
5 Wei Liu, Andrew Rabinovich, Alexander C. Berg. ParseNet: Looking Wider to See Better. ICLR 2016.

3.7. Links

85

ChainerCV Documentation, Release 0.13.1• n_channel (int) – The number of channels.
• initial – A value to initialize the scale factors.
It is pased to chainer.
initializers._get_initializer(). The default value is 0.
• eps (float) – A small value to avoid zero-division. The default value is 1𝑒 − 5.
forward(x)Normalize input and scale it.
Parameters x (chainer.Variable) – A variable holding 4-dimensional array. Its dtype
is numpy.float32.
Returns The shape and dtype are same as those of input.
Return type chainer.Variable
SSD
class chainercv.links.model.ssd.SSD(extractor, multibox, steps, sizes, variance=(0.1, 0.2),
mean=0)Base class of Single Shot Multibox Detector.
This is a base class of Single Shot Multibox Detector6 .
Parameters• extractor – A link which extracts feature maps. This link must have insize, grids
and forward().
– insize: An integer which indicates the size of input images. Images are resized to thissize before feature extraction.
– grids: An iterable of integer. Each integer indicates the size of feature map. This value
is used by MultiBboxCoder.
– __call_(): A method which computes feature maps. It must take a batched images
and return batched feature maps.
• multibox – A link which computes mb_locs and mb_confs from feature maps. This
link must have n_class, aspect_ratios and forward().
– n_class: An integer which indicates the number of classes. This value should include
the background class.
– aspect_ratios: An iterable of tuple of integer. Each tuple indicates the aspect ratiosof default bounding boxes at each feature maps. This value is used by MultiboxCoder.
– forward(): A method which computes mb_locs and mb_confs. It must take abatched feature maps and return mb_locs and mb_confs.
• steps (iterable of float) – The step size for each feature map. This value is usedby MultiboxCoder.
• sizes (iterable of float) – The base size of default bounding boxes for each feature map. This value is used by MultiboxCoder.
• variance (tuple of floats) – Two coefficients for decoding the locations ofbounding boxes. This value is used by MultiboxCoder. The default value is (0.1,
0.2).
6 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

86

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• nms_thresh (float) – The threshold value for non_maximum_suppression().
The default value is 0.45.
This value can be changed directly or by using
use_preset().
• score_thresh (float) – The threshold value for confidence score. If a bounding box
whose confidence score is lower than this value, the bounding box will be suppressed. The
default value is 0.6. This value can be changed directly or by using use_preset().
forward(x)Compute localization and classification from a batch of images.
This method computes two variables, mb_locs and mb_confs. self.coder.decode() converts
these variables to bounding box coordinates and confidence scores. These variables are also used in training SSD.
Parameters x (chainer.Variable) – A variable holding a batch of images. The images
are preprocessed by _prepare().
Returns
This method returns two variables, mb_locs and mb_confs.
• mb_locs: A variable of float arrays of shape (𝐵, 𝐾, 4), where 𝐵 is the number of samples
in the batch and 𝐾 is the number of default bounding boxes.
• mb_confs: A variable of float arrays of shape (𝐵, 𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 + 1).
Return type tuple of chainer.Variablepredict(imgs)
Detect objects from images.
This method predicts objects for each image.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their value is [0, 255].
Returns
This method returns a tuple of three lists, (bboxes, labels, scores).
• bboxes: A list of float arrays of shape (𝑅, 4), where 𝑅 is the number of bounding boxes
in a image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second
axis.
• labels : A list of integer arrays of shape (𝑅, ). Each value indicates the class of thebounding box. Values are in range [0, 𝐿 − 1], where 𝐿 is the number of the foregroundclasses.
• scores : A list of float arrays of shape (𝑅, ). Each value indicates how confident theprediction is.
Return type tuple of lists
to_cpu()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)
Copies parameter variables and persistent values to GPU.

3.7. Links

87

ChainerCV Documentation, Release 0.13.1

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
use_preset(preset)
Use the given preset during prediction.
This method changes values of nms_thresh and score_thresh. These values are a thresholdvalue used for non maximum suppression and a threshold value to discard low confidence proposals in
predict(), respectively.
If the attributes need to be changed to something other than the values provided in the presets, pleasemodify them by directly accessing the public attributes.
Parameters preset ({'visualize', 'evaluate'}) – A string to determine the preset
to use.
VGG16class chainercv.links.model.ssd.VGG16
An extended VGG-16 model for SSD300 and SSD512.
This is an extended VGG-16 model proposed in7 . The differences from original VGG-168 are shown below.
• conv5_1,
conv5_2
andDilatedConvolution2d.

conv5_3

arechangedfrom

Convolution2dto• Normalize is inserted after conv4_3.
• The parameters of max pooling after conv5_3 are changed.
• fc6 and fc7 are converted to conv6 and conv7.
VGG16Extractor300
class chainercv.links.model.ssd.VGG16Extractor300
A VGG-16 based feature extractor for SSD300.
This is a feature extractor for SSD300. This extractor is based on VGG16.
forward(x)Compute feature maps from a batch of images.
This method extracts feature maps from conv4_3, conv7, conv8_2, conv9_2, conv10_2, andconv11_2.
Parameters x (ndarray) – An array holding a batch of images. The images should be resized
to 300 × 300.
Returns Each variable contains a feature map.
Return type list of Variable
7 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.
8 Karen Simonyan, Andrew Zisserman. Very Deep Convolutional Networks for Large-Scale Image Recognition. ICLR 2015.

88

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

VGG16Extractor512
class chainercv.links.model.ssd.VGG16Extractor512
A VGG-16 based feature extractor for SSD512.
This is a feature extractor for SSD512. This extractor is based on VGG16.
forward(x)Compute feature maps from a batch of images.
This method extracts feature maps from conv4_3, conv7, conv8_2, conv9_2, conv10_2,
conv11_2, and conv12_2.
Parameters x (ndarray) – An array holding a batch of images. The images should be resized
to 512 × 512.
Returns Each variable contains a feature map.
Return type list of Variable
Train-only Utility
GradientScalingclass chainercv.links.model.ssd.GradientScaling(rate)
Optimizer/UpdateRule hook function for scaling gradient.
This hook function scales gradient by a constant value.
Parameters rate (float) – Coefficient for scaling.
Variables rate (float) – Coefficient for scaling.
multibox_loss
chainercv.links.model.ssd.multibox_loss(mb_locs, mb_confs, gt_mb_locs, gt_mb_labels, k,
comm=None)
Computes multibox losses.
This is a loss function used in9 . This function returns loc_loss and conf_loss. loc_loss is a loss
for localization and conf_loss is a loss for classification. The formulas of these losses can be found in theequation (2) and (3) in the original paper.
Parameters• mb_locs (chainer.Variable or array) – The offsets and scales for predictedbounding boxes. Its shape is (𝐵, 𝐾, 4), where 𝐵 is the number of samples in the batch and𝐾 is the number of default bounding boxes.
• mb_confs (chainer.Variable or array) – The classes of predicted boundingboxes. Its shape is (𝐵, 𝐾, 𝑛_𝑐𝑙𝑎𝑠𝑠). This function assumes the first class is background(negative).
• gt_mb_locs (chainer.Variable or array) – The offsets and scales for groundtruth bounding boxes. Its shape is (𝐵, 𝐾, 4).
9 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

3.7. Links

89

ChainerCV Documentation, Release 0.13.1• gt_mb_labels (chainer.Variable or array) – The classes of ground truth
bounding boxes. Its shape is (𝐵, 𝐾).
• k (float) – A coefficient which is used for hard negative mining. This value determines
the ratio between the number of positives and that of mined negatives. The value used in theoriginal paper is 3.
• comm (CommunicatorBase) – A ChainerMN communicator. If it is specified, the number of positive examples is computed among all GPUs.
Returns This function returns two chainer.Variable: loc_loss and conf_loss.
Return type tuple of chainer.Variablerandom_crop_with_bbox_constraints
chainercv.links.model.ssd.random_crop_with_bbox_constraints(img,bbox,
min_scale=0.3,
max_scale=1,
max_aspect_ratio=2,
constraints=None,
max_trial=50,
return_param=False)
Crop an image randomly with bounding box constraints.
This data augmentation is used in training of Single Shot Multibox Detector10 . More details can be found indata augmentation section of the original paper.
Parameters• img (ndarray) – An image array to be cropped. This is in CHW format.
• bbox (ndarray) – Bounding boxes used for constraints. The shape is (𝑅, 4). 𝑅 is thenumber of bounding boxes.
• min_scale (float) – The minimum ratio between a cropped region and the original
image. The default value is 0.3.
• max_scale (float) – The maximum ratio between a cropped region and the original
image. The default value is 1.
• max_aspect_ratio (float) – The maximum aspect ratio of cropped region. The default value is 2.
• constaraints (iterable of tuples) – An iterable of constraints. Each constraint
should be (min_iou, max_iou) format. If you set min_iou or max_iou to None, itmeans not limited. If this argument is not specified, ((0.1, None), (0.3, None),(0.5, None), (0.7, None), (0.9, None), (None, 1)) will be used.
• max_trial (int) – The maximum number of trials to be conducted for each constraint.
If this function can not find any region that satisfies the constraint in 𝑚𝑎𝑥_𝑡𝑟𝑖𝑎𝑙 trials, thisfunction skips the constraint. The default value is 50.
• return_param (bool) – If True, this function returns information of intermediate values.
Returns
If return_param = False, returns an array img that is cropped from the input array.
10 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

90

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

If return_param = True, returns a tuple whose elements are img, param. param is adictionary of intermediate parameters whose contents are listed below with key, value-type andthe description of the value.
• constraint (tuple): The chosen constraint.
• y_slice (slice): A slice in vertical direction used to crop the input image.
• x_slice (slice): A slice in horizontal direction used to crop the input image.
Return type ndarray or (ndarray, dict)random_distort
chainercv.links.model.ssd.random_distort(img, brightness_delta=32, contrast_low=0.5,
contrast_high=1.5, saturation_low=0.5, saturation_high=1.5, hue_delta=18)
A color related data augmentation used in SSD.
This function is a combination of four augmentation methods: brightness, contrast, saturation and hue.
• brightness: Adding a random offset to the intensity of the image.
• contrast: Multiplying the intensity of the image by a random scale.
• saturation: Multiplying the saturation of the image by a random scale.
• hue: Adding a random offset to the hue of the image randomly.
This data augmentation is used in training of Single Shot Multibox Detector11 .
Note that this function requires cv2.
Parameters• img (ndarray) – An image array to be augmented. This is in CHW and RGB format.
• brightness_delta (float) – The offset for saturation will be drawn from[−𝑏𝑟𝑖𝑔ℎ𝑡𝑛𝑒𝑠𝑠_𝑑𝑒𝑙𝑡𝑎, 𝑏𝑟𝑖𝑔ℎ𝑡𝑛𝑒𝑠𝑠_𝑑𝑒𝑙𝑡𝑎]. The default value is 32.
• contrast_low (float) – The scale for contrast[𝑐𝑜𝑛𝑡𝑟𝑎𝑠𝑡_𝑙𝑜𝑤, 𝑐𝑜𝑛𝑡𝑟𝑎𝑠𝑡_ℎ𝑖𝑔ℎ]. The default value is 0.5.

will

be

drawn

from

• contrast_high (float) – See contrast_low. The default value is 1.5.
• saturation_low (float) – The scale for saturation will be drawn from[𝑠𝑎𝑡𝑢𝑟𝑎𝑡𝑖𝑜𝑛_𝑙𝑜𝑤, 𝑠𝑎𝑡𝑢𝑟𝑎𝑡𝑖𝑜𝑛_ℎ𝑖𝑔ℎ]. The default value is 0.5.
• saturation_high (float) – See saturation_low. The default value is 1.5.
• hue_delta (float) – The offset for hue will be drawn from [−ℎ𝑢𝑒_𝑑𝑒𝑙𝑡𝑎, ℎ𝑢𝑒_𝑑𝑒𝑙𝑡𝑎].
The default value is 18.
Returns An image in CHW and RGB format.
resize_with_random_interpolation
chainercv.links.model.ssd.resize_with_random_interpolation(img,size,return_param=False)
Resize an image with a randomly selected interpolation method.
11 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.

3.7. Links

91

ChainerCV Documentation, Release 0.13.1

This function is similar to chainercv.transforms.resize(), but this chooses the interpolation method
randomly.
This data augmentation is used in training of Single Shot Multibox Detector12 .
Note that this function requires cv2.
Parameters• img (ndarray) – An array to be transformed. This is in CHW format and the type should
be numpy.float32.
• size (tuple) – This is a tuple of length 2. Its elements are ordered as (height, width).
• return_param (bool) – Returns information of interpolation.
Returns
If return_param = False, returns an array img that is the result of rotation.
If return_param = True, returns a tuple whose elements are img, param. param is adictionary of intermediate parameters whose contents are listed below with key, value-type andthe description of the value.
• interpolatation: The chosen interpolation method.
Return type ndarray or (ndarray, dict)
YOLO
Detection Links
YOLOv2class chainercv.links.model.yolo.YOLOv2(n_fg_class=None, pretrained_model=None)YOLOv2.
This is a model of YOLOv21 . This model uses Darknet19Extractor as its feature extractor.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded.
'voc0712', filepath or None. The default value is None.

This can take– 'voc0712': Load weights trained on trainval split of PASCAL VOC 2007 and 2012.
The weight file is downloaded and cached automatically. n_fg_class must be 20 orNone. These weights were converted from the darknet model provided by the original
implementation. The conversion code is chainercv/examples/yolo/darknet2npz.py.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
12 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox
Detector. ECCV 2016.
1 Joseph Redmon, Ali Farhadi. YOLO9000: Better, Faster, Stronger. CVPR 2017.

92

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

YOLOv3class chainercv.links.model.yolo.YOLOv3(n_fg_class=None, pretrained_model=None)YOLOv3.
This is a model of YOLOv32 . This model uses Darknet53Extractor as its feature extractor.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded.
'voc0712', filepath or None. The default value is None.

This can take– 'voc0712': Load weights trained on trainval split of PASCAL VOC 2007 and 2012.
The weight file is downloaded and cached automatically. n_fg_class must be 20 orNone. These weights were converted from the darknet model. The conversion code ischainercv/examples/yolo/darknet2npz.py.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
forward(x)Compute localization, objectness, and classification from a batch of images.
This method computes three variables, locs, objs, and confs. self._decode() converts thesevariables to bounding box coordinates and confidence scores. These variables are also used in training
YOLOv3.
Parameters x (chainer.Variable) – A variable holding a batch of images.
Returns
This method returns three variables, locs, objs, and confs.
• locs: A variable of float arrays of shape (𝐵, 𝐾, 4), where 𝐵 is the number of samples inthe batch and 𝐾 is the number of default bounding boxes.
• objs: A variable of float arrays of shape (𝐵, 𝐾).
• confs: A variable of float arrays of shape (𝐵, 𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠).
Return type tuple of chainer.Variable
to_cpu()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)
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
2 Joseph Redmon, Ali Farhadi. YOLOv3: An Incremental Improvement. arXiv 2018.

3.7. Links

93

ChainerCV Documentation, Release 0.13.1

Utility
ResidualBlockclass chainercv.links.model.yolo.ResidualBlock(*links)
ChainList with a residual connection.
Darknet19Extractor
class chainercv.links.model.yolo.Darknet19Extractor
A Darknet19 based feature extractor for YOLOv2.
This is a feature extractor for YOLOv2
forward(x)Compute a feature map from a batch of images.
Parameters x (ndarray) – An array holding a batch of images. The images should be resized
to 416 × 416.
Returns
Return type Variable
Darknet53Extractor
class chainercv.links.model.yolo.Darknet53Extractor
A Darknet53 based feature extractor for YOLOv3.
This is a feature extractor for YOLOv3
forward(x)Compute feature maps from a batch of images.
This method extracts feature maps from 3 layers.
Parameters x (ndarray) – An array holding a batch of images. The images should be resized
to 416 × 416.
Returns Each variable contains a feature map.
Return type list of Variable
YOLOBaseclass chainercv.links.model.yolo.YOLOBase(**links)
Base class for YOLOv2 and YOLOv3.
A subclass of this class should have extractor, forward(), and _decode().
predict(imgs)
Detect objects from images.
This method predicts objects for each image.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their value is [0, 255].

94

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Returns
This method returns a tuple of three lists, (bboxes, labels, scores).
• bboxes: A list of float arrays of shape (𝑅, 4), where 𝑅 is the number of bounding boxes
in a image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in the second
axis.
• labels : A list of integer arrays of shape (𝑅, ). Each value indicates the class of thebounding box. Values are in range [0, 𝐿 − 1], where 𝐿 is the number of the foregroundclasses.
• scores : A list of float arrays of shape (𝑅, ). Each value indicates how confident theprediction is.
Return type tuple of lists
use_preset(preset)
Use the given preset during prediction.
This method changes values of nms_thresh and score_thresh. These values are a thresholdvalue used for non maximum suppression and a threshold value to discard low confidence proposals in
predict(), respectively.
If the attributes need to be changed to something other than the values provided in the presets, pleasemodify them by directly accessing the public attributes.
Parameters preset ({'visualize', 'evaluate'}) – A string to determine the preset
to use.
YOLOv2Baseclass chainercv.links.model.yolo.YOLOv2Base(n_fg_class=None, pretrained_model=None)
Base class for YOLOv2 and YOLOv2Tiny.
A subclass of this class should have _extractor, _models, and _anchors.
forward(x)Compute localization, objectness, and classification from a batch of images.
This method computes three variables, locs, objs, and confs. self._decode() converts thesevariables to bounding box coordinates and confidence scores. These variables are also used in training
YOLOv2.
Parameters x (chainer.Variable) – A variable holding a batch of images.
Returns
This method returns three variables, locs, objs, and confs.
• locs: A variable of float arrays of shape (𝐵, 𝐾, 4), where 𝐵 is the number of samples inthe batch and 𝐾 is the number of default bounding boxes.
• objs: A variable of float arrays of shape (𝐵, 𝐾).
• confs: A variable of float arrays of shape (𝐵, 𝐾, 𝑛_𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠).
Return type tuple of chainer.Variable
to_cpu()Copies parameter variables and persistent values to CPU.

3.7. Links

95

ChainerCV Documentation, Release 0.13.1

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)
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
Semantic Segmentation
Semantic segmentation links share a common method predict() to conduct semantic segmentation of images. For
more details, please read SegNetBasic.predict().
SegNetSemantic Segmentation Link
SegNetBasicclass chainercv.links.model.segnet.SegNetBasic(n_class=None,
pretrained_model=None, initialW=None)
SegNet Basic for semantic segmentation.
This is a SegNet1 model for semantic segmenation. This is based on SegNetBasic model that is found here.
When you specify the path of a pretrained chainer model serialized as a npz file in the constructor, this chain
model automatically initializes all the parameters with it. When a string in prespecified set is provided, apretrained model is loaded from weights distributed on the Internet. The list of pretrained models supported are
as follows:• camvid: Loads weights trained with the train split of CamVid dataset.
Parameters• n_class (int) – The number of classes.
pretrained_model is given.

If None, it can be infered if• pretrained_model (string) – The destination of the pretrained chainer model serialized as a npz file. If this is one of the strings described above, it automatically loads
weights stored under a directory $CHAINER_DATASET_ROOT/pfnet/chainercv/
models/, where $CHAINER_DATASET_ROOT is set as $HOME/.chainer/dataset
unless you specify another value by modifying the environment variable.
• initialW (callable) – Initializer for convolution layers.
forward(x)Compute an image-wise score from a batch of images
1 Vijay Badrinarayanan, Alex Kendall and Roberto Cipolla “SegNet: A Deep Convolutional Encoder-Decoder Architecture for Image Segmentation.” PAMI, 2017

96

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters x (chainer.Variable) – A variable with 4D image array.
Returns An image-wise score. Its channel size is self.n_class.
Return type chainer.Variablepredict(imgs)
Conduct semantic segmentations from images.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their values are [0, 255].
Returns List of integer labels predicted from each image in the input list.
Return type list of numpy.ndarray
DeepLabSemantic Segmentation Link
DeepLabV3plusXception65
class chainercv.links.model.deeplab.DeepLabV3plusXception65(n_class=None, pretrained_model=None,min_input_size=None,scales=None,
flip=None, extractor_kwargs=None,aspp_kwargs=None,
decoder_kwargs=None)
Utility
Decoderclass chainercv.links.model.deeplab.Decoder(in_channels, out_channels, proj_channels,
depth_channels, bn_kwargs={})
Decoder for DeepLab V3+.
Parameters• in_channels (int) – Number of channels of input arrays.
• out_channels (int) – Number of channels of output arrays.
• proj_channels (int) – Number of channels of output of first 1x1 convolution.
• depth_channels (int) – Number of channels of output of convolution after concatenation.
• bn_kwargs (dict) – Keywod arguments passed to initialize the batch normalization layers of chainercv.links.Conv2DBNActiv and chainercv.links.
SeparableConv2DBNActiv.

3.7. Links

97

ChainerCV Documentation, Release 0.13.1

DeepLabV3plus
class chainercv.links.model.deeplab.DeepLabV3plus(feature_extractor, aspp, decoder,
min_input_size, scales=(1.0, ),flip=False)
Base class of DeepLab V3+.
Parameters• fature_extractor (callable) – Feature extractor network. This network should
return lowlevel and highlevel feature maps as (lowlevel, highlevel).
• aspp (callable) – ASPP network.
• decoder (callable) – Decoder network.
• min_input_size (int or tuple of ints) – Minimum image size of inputs. ifheight or width is lower than this values, input images are padded to be this shape. The
default value is (513, 513)
• scales (tuple of floats) – Scales for multi-scale prediction. Final outputs are averaged after softmax activation. The default value is (1.0,).
• flip (bool) – When this is true, a left-right flipped images are also input and finallyaveraged. When len(scales) are more than 1, flipped prediction is performed in eachscales. The default value is False
predict(imgs)
Conduct semantic segmentation from images.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their values are [0, 255].
Returns List of integer labels predicted from each image in the input list.
Return type list of numpy.ndarray
prepare(image)
Preprocess an image for feature extraction.
1. padded by mean pixel defined in feature extractor.
2. scaled to [-1.0, 1.0]
After resizing the image, the image is subtracted by a mean image value self.mean.
Parameters image (ndarray) – An image. This is in CHW and RGB format. The range ofits value is [0, 255].
Returns A preprocessed image.
Return type ndarray
SeparableASPP
class chainercv.links.model.deeplab.SeparableASPP(in_channels,
dilate_list=(12,bn_kwargs={})Atrous Spatial Pyramid Pooling with Separable Convolution.

out_channels,
24,
36),

average pooling with FC layer 1x1 Convolution

98

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

in –> Separable Convolution(k=12) –> concat –> 1x1 Convolution Separable Convolution(k=24) Separable
Convolution(k=36)
Parameters• in_channels (int) – Number of channels of input arrays.
• out_channels (int) – Number of channels of output arrays.
• dilate_list (tuple of ints) – Tuple of Dilation factors. the length of this tuple
must be 3.
• bn_kwargs (dict) – Keywod arguments passed to initialize the batch normalization layers of chainercv.links.Conv2DBNActiv and chainercv.links.
SeparableConv2DBNActiv.
Xception65
class chainercv.links.model.deeplab.Xception65(bn_kwargs={})Xception65 for backbone network of DeepLab v3+.
Unlike original Xception65, this follows implementation in deeplab v3 (https://github.com/tensorflow/models/tree/master/research/deeplab). This returns lowlevel feature (an output of second convolution in second blockin entryflow) and highlevel feature (an output before final average pooling in original).
Parameters bn_kwargs (dict) – Keywod arguments passed to initialize the batch normalization layers of chainercv.links.Conv2DBNActiv and chainercv.links.
SeparableConv2DBNActiv.
XceptionBlockclass chainercv.links.model.deeplab.XceptionBlock(in_channels, depthlist, stride=1,
dilate=1, skip_type=’conv’, activ_first=True,bn_kwargs={},dw_activ_list=[None, None, None],
pw_activ_list=[<function
relu>,<function relu>, None])A building block for Xceptions.
Not only final outputs, this block also returns unactivated outputs of second separable convolution.
Parameters• in_channels (int) – The number of channels of the input array.
• depthlist (tuple of ints) – Tuple of integers which defines number of channels
of intermediate arrays. The length of this tuple must be 3.
• stride (int or tuple of ints) – Stride of filter application.
• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• skip_type (string) – the type of skip connection. If sum, original input is summed
to output of network directly. When conv, convolution layer is applied before summation.
When none, skip connection is not used. The default value is conv.
• activ_first (boolean) – If True, activation function is applied first in this block.
The default value is True

3.7. Links

99

ChainerCV Documentation, Release 0.13.1• bn_kwargs (dict) – Keywod arguments passed to initialize the batch normalization layers of chainercv.links.Conv2DBNActiv and chainercv.links.
SeparableConv2DBNActiv.
Links for Multiple Tasks
FPN (Feature Pyramid Networks)
Detection Links
FasterRCNNFPNResnet50
class chainercv.links.model.fpn.FasterRCNNFPNResNet50(n_fg_class=None,
pretrained_model=None,
return_values=[’bboxes’,’labels’,’scores’],min_size=800,
max_size=1333)
Faster R-CNN with ResNet-50 and FPN.
Please refer to FasterRCNNFPNResNet.
FasterRCNNFPNResnet101
class chainercv.links.model.fpn.FasterRCNNFPNResNet101(n_fg_class=None,
pretrained_model=None,
return_values=[’bboxes’,’labels’,’scores’],min_size=800,
max_size=1333)
Faster R-CNN with ResNet-101 and FPN.
Please refer to FasterRCNNFPNResNet.
Instance Segmentation Links
MaskRCNNFPNResNet50
class chainercv.links.model.fpn.MaskRCNNFPNResNet50(n_fg_class=None,
pretrained_model=None,
return_values=[’masks’,’labels’, ’scores’], min_size=800,
max_size=1333)
Mask R-CNN with ResNet-50 and FPN.
Please refer to FasterRCNNFPNResNet.

100

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

MaskRCNNFPNResNet101
class chainercv.links.model.fpn.MaskRCNNFPNResNet101(n_fg_class=None,
pretrained_model=None,
return_values=[’masks’,’labels’, ’scores’], min_size=800,
max_size=1333)
Mask R-CNN with ResNet-101 and FPN.
Please refer to FasterRCNNFPNResNet.
Utility
FasterRCNN
class chainercv.links.model.fpn.FasterRCNN(extractor, rpn, bbox_head, mask_head, return_values, min_size=800, max_size=1333)
Base class of Faster R-CNN with FPN.
This is a base class of Faster R-CNN with FPN.
Parameters• extractor (Link) – A link that extracts feature maps. This link must have scales,mean and forward().
• rpn (Link) – A link that has the same interface as RPN . Please refer to the documentation
found there.
• bbox_head (Link) – A link that has the same interface as BboxHead. Please refer tothe documentation found there.
• mask_head (Link) – A link that has the same interface as MaskHead. Please refer tothe documentation found there.
• return_values (list of strings) – Determines the values returned by
predict().
• min_size (int) – A preprocessing paramter for prepare(). Please refer to a docstring
found for prepare().
• max_size (int) – A preprocessing paramter for prepare(). Note that the result ofprepare() can exceed this size due to alignment with stride.
• nms_thresh (float) – The threshold value for non_maximum_suppression().
The default value is 0.45.
This value can be changed directly or by using
use_preset().
• score_thresh (float) – The threshold value for confidence score. If a bounding box
whose confidence score is lower than this value, the bounding box will be suppressed. The
default value is 0.6. This value can be changed directly or by using use_preset().
predict(imgs)
Conduct inference on the given images.
The value returned by this method is decided based on the argument return_values of __init__().

3.7. Links

101

ChainerCV Documentation, Release 0.13.1

Examples>>> from chainercv.links import FasterRCNNFPNResNet50>>> model = FasterRCNNFPNResNet50(...
pretrained_model='coco',...
return_values=['rois', 'bboxes', 'labels', 'scores'])>>> rois, bboxes, labels, scores = model.predict(imgs)

Parameters imgs (iterable of numpy.ndarray) – Inputs.
Returns The table below shows the input and possible outputs.
Return type tuple of lists
Input nameimgs

Output namerois
bboxesscoreslabelsmasks

shape[(3, 𝐻, 𝑊 )]shape[(𝑅′ , 4)][(𝑅, 4)][(𝑅, )][(𝑅, )][(𝑅, 𝐻, 𝑊 )]dtype
float32

dtype
float32
float32
float32
int32
boolformat
RGB, [0, 255]

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )–[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–

prepare(imgs)
Preprocess images.
Parameters imgs (iterable of numpy.ndarray) – Arrays holding images. All images
are in CHW and RGB format and the range of their value is [0, 255].
Returns preprocessed images and scales that were caluclated in prepocessing.
Return type Two arrays
use_preset(preset)
Use the given preset during prediction.
This method changes values of nms_thresh and score_thresh. These values are a thresholdvalue used for non maximum suppression and a threshold value to discard low confidence proposals in
predict(), respectively.
If the attributes need to be changed to something other than the values provided in the presets, pleasemodify them by directly accessing the public attributes.
Parameters preset ({'visualize', 'evaluate'}) – A string to determine the preset
to use.
FasterRCNNFPNResNetclass chainercv.links.model.fpn.FasterRCNNFPNResNet(n_fg_class=None,
pretrained_model=None,
return_values=[’bboxes’,’labels’, ’scores’], min_size=800,
max_size=1333)
Base class for Faster R-CNN with a ResNet backbone and FPN.

102

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

A subclass of this class should have _base and _models.
Parameters• n_fg_class (int) – The number of classes excluding the background.
• pretrained_model (string) – The weight file to be loaded. This can take 'coco',
filepath or None. The default value is None.
– 'coco': Load weights trained on train split of MS COCO 2017. The weight file isdownloaded and cached automatically. n_fg_class must be 80 or None.
– 'imagenet': Load weights of ResNet-50 trained on ImageNet. The weight file isdownloaded and cached automatically. This option initializes weights partially and therests are initialized randomly. In this case, n_fg_class can be set to any number.
– filepath: A path of npz file. In this case, n_fg_class must be specified properly.
– None: Do not load weights.
• return_values (list of strings) – Determines the values returned by
predict().
• min_size (int) – A preprocessing paramter for prepare().
prepare().

Please refer to• max_size (int) – A preprocessing paramter for prepare().
FPN
class chainercv.links.model.fpn.FPN(base, n_base_output, scales)
An extractor class of Feature Pyramid Networks.
This class wraps a feature extractor and provides multi-scale features.
Parameters• base (Link) – A base feature extractor. It should have forward() and mean.
forward() should take a batch of images and return feature maps of them. The sizeof the 𝑘 + 1-th feature map should be the half as that of the 𝑘-th feature map.
• n_base_output (int) – The number of feature maps that base returns.
• scales (tuple of floats) – The scales of feature maps.
BboxHeadclass chainercv.links.model.fpn.BboxHead(n_class, scales)
Bounding box head network of Feature Pyramid Networks.
Parameters• n_class (int) – The number of classes including background.
• scales (tuple of floats) – The scales of feature maps.
decode(rois, roi_indices, locs, confs, scales, sizes, nms_thresh, score_thresh)
Decodes back to coordinates of RoIs.
This method decodes locs and confs returned by a FPN network back to bboxes, labels andscores.

3.7. Links

103

ChainerCV Documentation, Release 0.13.1

Parameters• rois (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , 4), where 𝑅𝑙 isthe number of RoIs in the 𝑙-th feature map.
• roi_indices (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , ).
• locs (array) – An array whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠, 4), where 𝑅 is the total numberof RoIs in the given batch.
• confs (array) – An array whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠).
• scales (list of floats) – A list of floats returned by prepare()• sizes (list of tuples of two ints) – A list of (𝐻𝑛 , 𝑊𝑛 ), where 𝐻𝑛 and 𝑊𝑛
are height and width of the 𝑛-th image.
• nms_thresh (float) – The threshold value for non_maximum_suppression().
• score_thresh (float) – The threshold value for confidence score.
Returns bboxes, labels and scores.
Return typetuple of three list of arrays• bboxes: A list of float arrays of shape (𝑅𝑛′ , 4), where 𝑅𝑛′ is the number of bounding boxesin the 𝑛-th image. Each bounding box is organized by (𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ) in thesecond axis.
• labels : A list of integer arrays of shape (𝑅𝑛′ , ). Each value indicates the class of thebounding box. Values are in range [0, 𝐿 − 1], where 𝐿 is the number of the foregroundclasses.
• scores : A list of float arrays of shape (𝑅𝑛′ , ). Each value indicates how confident theprediction is.
distribute(rois, roi_indices)
Assigns Rois to feature maps according to their size.
Parameters• rois (array) – An array of shape (𝑅, 4), where 𝑅 is the total number of RoIs in thegiven batch.
• roi_indices (array) – An array of shape (𝑅, ).
Returnsrois and roi_indices.
• rois: A list of arrays of shape (𝑅𝑙 , 4), where 𝑅𝑙 is the number of RoIs in the 𝑙-th featuremap.
• roi_indices : A list of arrays of shape (𝑅𝑙 , ).
Return type tuple of two lists
forward(hs, rois, roi_indices)
Calculates RoIs.
Parameters• hs (iterable of array) – An iterable of feature maps.

104

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• rois (list of arrays) – A list of arrays of shape: math: (R_l, 4), where: math: R_lis the number of RoIs in the: math: l- th feature map.
• roi_indices (list of arrays) – A list of arrays of shape (𝑅𝑙 , ).
Returns
locs and confs.
• locs: An arrays whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠, 4), where 𝑅 is the total number of RoIs in
the batch.
• confs: A list of array whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠).
Return type tuple of two arrays
RPN
class chainercv.links.model.fpn.RPN(scales)
Region Proposal Network of Feature Pyramid Networks.
Parameters scales (tuple of floats) – The scales of feature maps.
anchors(sizes)
Calculates anchor boxes.
Parameters sizes (iterable of tuples of two ints) – An iterable of (𝐻𝑙 , 𝑊𝑙 ),where 𝐻𝑙 and 𝑊𝑙 are height and width of the 𝑙-th feature map.
Returns The shape of the 𝑙-th array is (𝐻𝑙 * 𝑊𝑙 * 𝐴, 4), where 𝐴 is the number of anchor ratios.
Return type list of arrays
decode(locs, confs, anchors, in_shape)
Decodes back to coordinates of RoIs.
This method decodes locs and confs returned by a FPN network back to rois and roi_indices.
Parameters• locs (list of arrays) – A list of arrays whose shape is (𝑁, 𝐾𝑙 , 4), where 𝑁 is thesize of batch and 𝐾𝑙 is the number of the anchor boxes of the 𝑙-th level.
• confs (list of arrays) – A list of array whose shape is (𝑁, 𝐾𝑙 ).
• anchors (list of arrays) – Anchor boxes returned by anchors().
• in_shape (tuple of ints) – The shape of input of array the feature extractor.
Returnsrois and roi_indices.
• rois: An array of shape (𝑅, 4), where 𝑅 is the total number of RoIs in the given batch.
• roi_indices : An array of shape (𝑅, ).
Return type tuple of two arrays
forward(hs)Calculates RoIs.
Parameters hs (iterable of array) – An iterable of feature maps.

3.7. Links

105

ChainerCV Documentation, Release 0.13.1

Returns
locs and confs.
• locs: A list of arrays whose shape is (𝑁, 𝐾𝑙 , 4), where 𝑁 is the size of batch and 𝐾𝑙 is thenumber of the anchor boxes of the 𝑙-th level.
” confs: A list of array whose shape is (𝑁, 𝐾𝑙 ).
Return type tuple of two arrays
MaskHeadclass chainercv.links.model.fpn.MaskHead(n_class, scales)
Mask Head network of Mask R-CNN.
Parameters• n_class (int) – The number of classes including background.
• scales (tuple of floats) – The scales of feature maps.
decode(segms, bboxes, labels, sizes)
Decodes back to masks.
Parameters• segms (iterable of arrays)(𝑅𝑛 , 𝑛_𝑐𝑙𝑎𝑠𝑠, 𝑀, 𝑀 ).

–An

iterableofarraysofshape• bboxes (iterable of arrays) – An iterable of arrays of shape (𝑅𝑛 , 4).
• labels (iterable of arrays) – An iterable of arrays of shape (𝑅𝑛 , ).
• sizes (list of tuples of two ints) – A list of (𝐻𝑛 , 𝑊𝑛 ), where 𝐻𝑛 and 𝑊𝑛
are height and width of the 𝑛-th image.
Returns This list contains instance segmentation for each image in the batch. More precisely,
this is a list of boolean arrays of shape (𝑅𝑛′ , 𝐻𝑛 , 𝑊𝑛 ), where 𝑅𝑛′ is the number of boundingboxes in the 𝑛-th image.
Return type list of arrays
distribute(rois, roi_indices)
Assigns feature levels to Rois based on their size.
Parameters• rois (array) – An array of shape (𝑅, 4), where 𝑅 is the total number of RoIs in thegiven batch.
• roi_indices (array) – An array of shape (𝑅, ).
Returns
out_rois, out_roi_indices and order.
• out_rois: A list of arrays of shape (𝑅𝑙 , 4), where 𝑅𝑙 is the number of RoIs in the 𝑙-th
feature map.
• out_roi_indices : A list of arrays of shape (𝑅𝑙 , ).
• order: A correspondence between the output and the input. The relationship below issatisfied.

106

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

xp.concatenate(out_rois, axis=0)[order[i]] == rois[i]Return type two lists and one arraysegm_to_mask
chainercv.links.model.fpn.segm_to_mask(segm, bbox, size)
Recover mask from cropped and resized mask.
This function requires cv2.
Parameters• segm (ndarray) – See below.
• bbox (ndarray) – See below.
• size (tuple) – This is a tuple of length 2. Its elements are ordered as (height, width).
Returns See below.
Return type ndarray
name
segm
bbox
mask (output)

shape(𝑅, 𝑆, 𝑆)(𝑅, 4)(𝑅, 𝐻, 𝑊 )dtype
float32
float32bool

format–(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )–Train-only Utility
bbox_head_loss_prechainercv.links.model.fpn.bbox_head_loss_pre(rois, roi_indices, std, bboxes, labels)
Loss function for Head (pre).
This function processes RoIs for bbox_head_loss_post().
Parameters• rois (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , 4), where 𝑅𝑙 is thenumber of RoIs in the 𝑙-th feature map.
• roi_indices (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , ).
• std (tuple of floats) – Two coefficients used for encoding bounding boxes.
• bboxes (list of arrays) – A list of arrays whose shape is (𝑅𝑛 , 4), where 𝑅𝑛 is thenumber of ground truth bounding boxes.
• labels – A list of arrays whose shape is (𝑅𝑛 , ).
bbox_head_loss_post
chainercv.links.model.fpn.bbox_head_loss_post(locs, confs, roi_indices, gt_locs, gt_labels,
batchsize)
Loss function for Head (post).

3.7. Links

107

ChainerCV Documentation, Release 0.13.1

Parameters• locs (array) – An array whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠, 4), where 𝑅 is the total number of
RoIs in the given batch.
• confs (array) – An iterable of arrays whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠).
• roi_indices (list of arrays)bbox_head_locs_pre().

–• gt_locs(list of arrays)bbox_head_locs_pre().

A• gt_labels (list of arrays)bbox_head_locs_pre().

–
–

A

A

list

of

arraysreturned

by

list

of

arraysreturned

by

list

of

arraysreturnedby• batchsize (int) – The size of batch.
Returns loc_loss and conf_loss.
Return type tuple of two variables
rpn_losschainercv.links.model.fpn.rpn_loss(locs, confs, anchors, sizes, bboxes)
Loss function for RPN.
Parameters• locs (iterable of arrays) – An iterable of arrays whose shape is (𝑁, 𝐾𝑙 , 4), where
𝐾𝑙 is the number of the anchor boxes of the 𝑙-th level.
• confs (iterable of arrays) – An iterable of arrays whose shape is (𝑁, 𝐾𝑙 ).
• anchors (list of arrays) – A list of arrays returned by anchors().
• sizes (list of tuples of two ints) – A list of (𝐻𝑛 , 𝑊𝑛 ), where 𝐻𝑛 and 𝑊𝑛
are height and width of the 𝑛-th image.
• bboxes (list of arrays) – A list of arrays whose shape is (𝑅𝑛 , 4), where 𝑅𝑛 is thenumber of ground truth bounding boxes.
Returns loc_loss and conf_loss.
Return type tuple of two variables
mask_head_loss_prechainercv.links.model.fpn.mask_head_loss_pre(rois, roi_indices, gt_masks, gt_bboxes,
gt_head_labels, segm_size)
Loss function for Mask Head (pre).
This function processes RoIs for mask_head_loss_post() by selecting RoIs for mask loss calculation andpreparing ground truth network output.
Parameters• rois (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , 4), where 𝑅𝑙 is thenumber of RoIs in the 𝑙-th feature map.
• roi_indices (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , ).

108

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• gt_masks (iterable of arrays) – An iterable of arrays whose shape is(𝑅𝑛 , 𝐻, 𝑊 ), where 𝑅𝑛 is the number of ground truth objects.
• gt_head_labels (iterable of arrays) – An iterable of arrays of shape (𝑅𝑙 , ).
This is a collection of ground-truth labels assigned to rois during bounding box localization stage. The range of value is (0, 𝑛_𝑐𝑙𝑎𝑠𝑠 − 1).
• segm_size (int) – Size of the ground truth network output.
Returnsmask_rois, mask_roi_indices, gt_segms, and gt_mask_labels.
• rois: A list of arrays of shape (𝑅𝑙′ , 4), where 𝑅𝑙′ is the number of RoIs in the 𝑙-th featuremap.
• roi_indices: A list of arrays of shape (𝑅𝑙′ , ).
• gt_segms: A list of arrays of shape (𝑅𝑙′ , 𝑀, 𝑀 ). : 𝑚𝑎𝑡ℎ : is the argument segm_size.
• gt_mask_labels: A list of arrays of shape (𝑅𝑙′ , ) indicating the classes of ground truth.
Return type tuple of four lists
mask_head_loss_post
chainercv.links.model.fpn.mask_head_loss_post(segms,
mask_roi_indices,
gt_mask_labels, batchsize)
Loss function for Mask Head (post).

gt_segms,

Parameters• segms (array) – An array whose shape is (𝑅, 𝑛_𝑐𝑙𝑎𝑠𝑠, 𝑀, 𝑀 ), where 𝑅 is the total
number of RoIs in the given batch.
• mask_roi_indices(array)mask_head_loss_pre().

–

A

list

of

arraysreturnedby• gt_segms(list of arrays)
mask_head_loss_pre().

–

A

list

of

arraysreturned

by

–

A

list

returnedby• gt_mask_labels (list of arrays)
mask_head_loss_pre().

ofarrays• batchsize (int) – The size of batch.
Returns Mask loss.
Return type chainer.Variable
mask_to_segm
chainercv.links.model.fpn.mask_to_segm(mask, bbox, segm_size, index=None)
Crop and resize mask.
This function requires cv2.
Parameters• mask (ndarray) – See below.
• bbox (ndarray) – See below.

3.7. Links

109

ChainerCV Documentation, Release 0.13.1• segm_size (int) – The size of segm 𝑆.
• index (ndarray) – See below. 𝑅 = 𝑁 when index is None.
Returns See below.
Return type ndarray
name
mask
bbox
index (optional)
segms (output)

shape(𝑁, 𝐻, 𝑊 )(𝑅, 4)(𝑅, )(𝑅, 𝑆, 𝑆)

dtype
bool
float32
int32
float32

format–(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )–[0, 1]ClassifiersClassifier
PixelwiseSoftmaxClassifierclass chainercv.links.PixelwiseSoftmaxClassifier(predictor,
ignore_label=-1,
class_weight=None)
A pixel-wise classifier.
It computes the loss based on a given input/label pair for semantic segmentation.
Parameters• predictor (Link) – Predictor network.
• ignore_label (int) – A class id that is going to be ignored in evaluation. The default
value is -1.
• class_weight (array) – An array that contains constant weights that will be multipliedwith the loss values along with the channel dimension. This will be used in chainer.
functions.softmax_cross_entropy().
forward(x, t)
Computes the loss value for an image and label pair.
Parameters• x (Variable) – A variable with a batch of images.
• t (Variable) – A variable with the ground truth image-wise label.
Returns Loss value.
Return type Variable
to_cpu()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)
Copies parameter variables and persistent values to GPU.

110

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

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

3.7.2 Connection
Connection
Conv2DActivclass chainercv.links.connection.Conv2DActiv(in_channels, out_channels, ksize=None,
stride=1, pad=0, dilate=1, nobias=False,
initialW=None, initial_bias=None, activ=<function relu>)
Convolution2D –> Activation
This is a chain that does two-dimensional convolution and applies an activation.
The arguments are the same as those of chainer.links.Convolution2D except for activ.
ExampleThere are several ways to initialize a Conv2DActiv.
1. Give the first three arguments explicitly:>>> l = Conv2DActiv(5, 10, 3)

2. Omit in_channels or fill it with None:
In these ways, attributes are initialized at runtime based on the channel size of the input.
>>> l = Conv2DActiv(10, 3)>>> l = Conv2DActiv(None, 10, 3)

Parameters• in_channels (int or None) – Number of channels of input arrays. If None, parameter initialization will be deferred until the first forward data pass at which time the size will
be determined.
• out_channels (int) – Number of channels of output arrays.
• ksize (int or tuple of ints) – Size of filters (a.k.a. kernels). ksize=k andksize=(k, k) are equivalent.
• stride (int or tuple of ints) – Stride of filter applications. stride=s andstride=(s, s) are equivalent.
• pad (int or tuple of ints) – Spatial padding width for input arrays. pad=p andpad=(p, p) are equivalent.
• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• nobias (bool) – If True, then this link does not use the bias term.
3.7. Links

111

ChainerCV Documentation, Release 0.13.1• initialW (callable) – Initial weight value. If None, the default initializer is used.
May also be a callable that takes numpy.ndarray or cupy.ndarray and edits its value.
• initial_bias (callable) – Initial bias value. If None, the bias is set to 0. May also
be a callable that takes numpy.ndarray or cupy.ndarray and edits its value.
• activ (callable) – An activation function. The default value is chainer.
functions.relu(). If this is None, no activation is applied (i.e. the activation is
the identity function).
Conv2DBNActivclass chainercv.links.connection.Conv2DBNActiv(in_channels, out_channels, ksize=None,
stride=1, pad=0, dilate=1, groups=1,
nobias=True,
initialW=None,
initial_bias=None, activ=<function relu>,
bn_kwargs={})Convolution2D –> Batch Normalization –> Activation
This is a chain that sequentially applies a two-dimensional convolution, a batch normalization and an activation.
The arguments are the same as that of chainer.links.Convolution2D except for activ andbn_kwargs. bn_kwargs can include comm key and a communicator of ChainerMN as the value to use
chainermn.links.MultiNodeBatchNormalization. If comm is not included in bn_kwargs,
chainer.links.BatchNormalization link from Chainer is used. Note that the default value for the
nobias is changed to True.
ExampleThere are several ways to initialize a Conv2DBNActiv.
1. Give the first three arguments explicitly:>>> l = Conv2DBNActiv(5, 10, 3)

2. Omit in_channels or fill it with None:
In these ways, attributes are initialized at runtime based on the channel size of the input.
>>> l = Conv2DBNActiv(10, 3)>>> l = Conv2DBNActiv(None, 10, 3)

Parameters• in_channels (int or None) – Number of channels of input arrays. If None, parameter initialization will be deferred until the first forward data pass at which time the size will
be determined.
• out_channels (int) – Number of channels of output arrays.
• ksize (int or tuple of ints) – Size of filters (a.k.a. kernels). ksize=k andksize=(k, k) are equivalent.
• stride (int or tuple of ints) – Stride of filter applications. stride=s andstride=(s, s) are equivalent.
• pad (int or tuple of ints) – Spatial padding width for input arrays. pad=p andpad=(p, p) are equivalent.

112

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• groups (int) – The number of groups to use grouped convolution. The default is one,
where grouped convolution is not used.
• nobias (bool) – If True, then this link does not use the bias term.
• initialW (callable) – Initial weight value. If None, the default initializer is used.
May also be a callable that takes numpy.ndarray or cupy.ndarray and edits its value.
• initial_bias (callable) – Initial bias value. If None, the bias is set to 0. May also
be a callable that takes numpy.ndarray or cupy.ndarray and edits its value.
• activ (callable) – An activation function. The default value is chainer.
functions.relu(). If this is None, no activation is applied (i.e. the activation is
the identity function).
• bn_kwargs (dict) – Keyword arguments passed to initialize chainer.links.
BatchNormalization. If a ChainerMN communicator (CommunicatorBase) is
given with the key comm, MultiNodeBatchNormalization will be used for the batchnormalization. Otherwise, BatchNormalization will be used.
SEBlock
class chainercv.links.connection.SEBlock(n_channel, ratio=16)
A squeeze-and-excitation block.
This block is part of squeeze-and-excitation networks. Channel-wise multiplication weights are inferred fromand applied to input feature map. Please refer to the original paper for more details.
See also:
chainercv.links.model.senet.SEResNet
Parameters• n_channel (int) – The number of channels of the input and output array.
• ratio (int) – Reduction ratio of n_channel to the number of hidden layer units.
SeparableConv2DBNActivclass chainercv.links.connection.SeparableConv2DBNActiv(in_channels, out_channels,
ksize, stride=1, pad=0,
dilate=1, nobias=False,
dw_initialW=None,
pw_initialW=None,
dw_initial_bias=None,
pw_initial_bias=None,
dw_activ=<function identity>, pw_activ=<function
relu>, bn_kwargs={})Separable Convolution with batch normalization and activation.
Convolution2D(Depthwise) –> Batch Normalization –> Activation –> Convolution2D(Pointwise) –> Batch
Normalization –> Activation

3.7. Links

113

ChainerCV Documentation, Release 0.13.1

Separable convolution with batch normalizations and activations.
Parameters are almost same as
Conv2DBNActiv except depthwise and pointwise convolution parameters.
Parameters• in_channels (int) – Number of channels of input arrays. Unlike Conv2DBNActiv,
this can’t accept None currently.
• out_channels (int) – Number of channels of output arrays.
• ksize (int or tuple of ints) – Size of filters (a.k.a. kernels). ksize=k andksize=(k, k) are equivalent.
• stride (int or tuple of ints) – Stride of filter applications. stride=s andstride=(s, s) are equivalent.
• pad (int or tuple of ints) – Spatial padding width for input arrays. pad=p andpad=(p, p) are equivalent.
• dilate (int or tuple of ints) – Dilation factor of filter applications.
dilate=d and dilate=(d, d) are equivalent.
• nobias (bool) – If True, then this link does not use the bias term.
• dw_initialW (callable) – Initial weight value of depthwise convolution. If None, thedefault initializer is used. May also be a callable that takes numpy.ndarray or cupy.
ndarray and edits its value.
• pw_initialW (callable) – Initial weight value of pointwise convolution.
• dw_initial_bias (callable) – Initial bias value of depthwise convolution. If None,
the bias is set to 0. May also be a callable that takes numpy.ndarray or cupy.ndarrayand edits its value.
• pw_initial_bias (callable) – Initial bias value of pointwise convolution.
• dw_activ (callable) – An activation function of depthwise convolution. The default
value is chainer.functions.relu(). If this is None, no activation is applied (i.e.
the activation is the identity function).
• pw_activ (callable) – An activation function of pointwise convolution.
• bn_kwargs (dict) – Keyword arguments passed to initialize chainer.links.
BatchNormalization. If a ChainerMN communicator (CommunicatorBase) is
given with the key comm, MultiNodeBatchNormalization will be used for the batchnormalization. Otherwise, BatchNormalization will be used.

3.8 Transforms
3.8.1 Image
center_crop
chainercv.transforms.center_crop(img, size, return_param=False, copy=False)
Center crop an image by size.
An image is cropped to size. The center of the output image and the center of the input image are same.
Parameters• img (ndarray) – An image array to be cropped. This is in CHW format.
114

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• size (tuple) – The size of output image after cropping. This value is (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
• return_param (bool) – If True, this function returns information of slices.
• copy (bool) – If False, a view of img is returned.
Returns
If return_param = False, returns an array out_img that is cropped from the input array.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• y_slice (slice): A slice used to crop the input image. The relation below holds together with
x_slice.
• x_slice (slice): Similar to y_slice.
out_img = img[:, y_slice, x_slice]

Return type ndarray or (ndarray, dict)flip
chainercv.transforms.flip(img, y_flip=False, x_flip=False, copy=False)
Flip an image in vertical or horizontal direction as specified.
Parameters• img (ndarray) – An array that gets flipped. This is in CHW format.
• y_flip (bool) – Flip in vertical direction.
• x_flip (bool) – Flip in horizontal direction.
• copy (bool) – If False, a view of img will be returned.
Returns Transformed img in CHW format.
pca_lighting
chainercv.transforms.pca_lighting(img, sigma, eigen_value=None, eigen_vector=None)
AlexNet style color augmentation
This method adds a noise vector drawn from a Gaussian. The direction of the Gaussian is same as that of theprincipal components of the dataset.
This method is used in training of AlexNet1 .
Parameters• img (ndarray) – An image array to be augmented. This is in CHW and RGB format.
• sigma (float) – Standard deviation of the Gaussian. In the original paper, this value is
10% of the range of intensity (25.5 if the range is [0, 255]).
• eigen_value (ndarray) – An array of eigen values. The shape has to be (3, ). If it is
not specified, the values computed from ImageNet are used.
1 Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton. ImageNet Classification with Deep Convolutional Neural Networks. NIPS 2012.

3.8. Transforms

115

ChainerCV Documentation, Release 0.13.1• eigen_vector (ndarray) – An array of eigen vectors. The shape has to be (3, 3). If it
is not specified, the vectors computed from ImageNet are used.
Returns An image in CHW format.
random_crop
chainercv.transforms.random_crop(img, size, return_param=False, copy=False)
Crop array randomly into size.
The input image is cropped by a randomly selected region whose shape is size.
Parameters• img (ndarray) – An image array to be cropped. This is in CHW format.
• size (tuple) – The size of output image after cropping. This value is (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
• return_param (bool) – If True, this function returns information of slices.
• copy (bool) – If False, a view of img is returned.
Returns
If return_param = False, returns an array out_img that is cropped from the input array.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• y_slice (slice): A slice used to crop the input image. The relation below holds together with
x_slice.
• x_slice (slice): Similar to x_slice.
out_img = img[:, y_slice, x_slice]

Return type ndarray or (ndarray, dict)random_expand
chainercv.transforms.random_expand(img, max_ratio=4, fill=0, return_param=False)
Expand an image randomly.
This method randomly place the input image on a larger canvas. The size of the canvas is (𝑟𝐻, 𝑟𝑊 ), where(𝐻, 𝑊 ) is the size of the input image and 𝑟 is a random ratio drawn from [1, 𝑚𝑎𝑥_𝑟𝑎𝑡𝑖𝑜]. The canvas is filled
by a value fill except for the region where the original image is placed.
This data augmentation trick is used to create “zoom out” effect2 .
Parameters• img (ndarray) – An image array to be augmented. This is in CHW format.
• max_ratio (float) – The maximum ratio of expansion. In the original paper, this value
is 4.
• fill (float, tuple or ndarray) – The value of padded pixels. In the original
paper, this value is the mean of ImageNet. If it is numpy.ndarray, its shape should be(𝐶, 1, 1), where 𝐶 is the number of channels of img.
2 Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox

Detector. ECCV 2016.

116

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1• return_param (bool) – Returns random parameters.
Returns
If return_param = False, returns an array out_img that is the result of expansion.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• ratio (float): The sampled value used to make the canvas.
• y_offset (int): The y coordinate of the top left corner of the image after placing on thecanvas.
• x_offset (int): The x coordinate of the top left corner of the image after placing on thecanvas.
Return type ndarray or (ndarray, dict)random_flip
chainercv.transforms.random_flip(img,y_random=False,
x_random=False,
turn_param=False, copy=False)
Randomly flip an image in vertical or horizontal direction.

re-Parameters• img (ndarray) – An array that gets flipped. This is in CHW format.
• y_random (bool) – Randomly flip in vertical direction.
• x_random (bool) – Randomly flip in horizontal direction.
• return_param (bool) – Returns information of flip.
• copy (bool) – If False, a view of img will be returned.
Returns
If return_param = False, returns an array out_img that is the result of flipping.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• y_flip (bool): Whether the image was flipped in the vertical direction or not.
• x_flip (bool): Whether the image was flipped in the horizontal direction or not.
Return type ndarray or (ndarray, dict)random_rotate
chainercv.transforms.random_rotate(img, return_param=False)
Randomly rotate images by 90, 180, 270 or 360 degrees.
Parameters• img (ndarray) – An arrays that get flipped. This is in CHW format.
• return_param (bool) – Returns information of rotation.

3.8. Transforms

117ChainerCV Documentation, Release 0.13.1

Returns
If return_param = False, returns an array out_img that is the result of rotation.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• k (int): The integer that represents the number of times the image is rotated by 90 degrees.
Return type ndarray or (ndarray, dict)random_sized_crop
chainercv.transforms.random_sized_crop(img,scale_ratio_range=(0.08,
1),
aspect_ratio_range=(0.75,
1.3333333333333333),
return_param=False, copy=False)
Crop an image to random size and aspect ratio.
The size (𝐻𝑐𝑟𝑜𝑝 , 𝑊𝑐𝑟𝑜𝑝 ) and the left top coordinate (𝑦𝑠𝑡𝑎𝑟𝑡 , 𝑥𝑠𝑡𝑎𝑟𝑡 ) of the crop are calculated as follows:√• 𝐻𝑐𝑟𝑜𝑝 = ⌊ 𝑠 × 𝐻 × 𝑊 × 𝑎⌋√
• 𝑊𝑐𝑟𝑜𝑝 = ⌊ 𝑠 × 𝐻 × 𝑊 ÷ 𝑎⌋
• 𝑦𝑠𝑡𝑎𝑟𝑡 ∼ 𝑈 𝑛𝑖𝑓 𝑜𝑟𝑚{0, 𝐻 − 𝐻𝑐𝑟𝑜𝑝 }• 𝑥𝑠𝑡𝑎𝑟𝑡 ∼ 𝑈 𝑛𝑖𝑓 𝑜𝑟𝑚{0, 𝑊 − 𝑊𝑐𝑟𝑜𝑝 }• 𝑠 ∼ 𝑈 𝑛𝑖𝑓 𝑜𝑟𝑚(𝑠1 , 𝑠2 )• 𝑏 ∼ 𝑈 𝑛𝑖𝑓 𝑜𝑟𝑚(𝑎1 , 𝑎2 ) and 𝑎 = 𝑏 or 𝑎 = 1𝑏 in 50/50 probability.
Here, 𝑠1 , 𝑠2 are the two floats in scale_ratio_range and 𝑎1 , 𝑎2 are the two floats in
aspect_ratio_range. Also, 𝐻 and 𝑊 are the height and the width of the image. Note that 𝑠 ≈𝐻𝑐𝑟𝑜𝑝 ×𝑊𝑐𝑟𝑜𝑝
𝐻. The approximations come from flooring floats to integers.
and 𝑎 ≈ 𝑊𝑐𝑟𝑜𝑝
𝐻×𝑊
𝑐𝑟𝑜𝑝
Note: When it fails to sample a valid scale and aspect ratio for ten times, it picks values in a non-uniform way.
If this happens, the selected scale ratio can be smaller than scale_ratio_range[0].

Parameters• img (ndarray) – An image array. This is in CHW format.
• scale_ratio_range (tuple of two floats) – Determines the distribution fromwhich a scale ratio is sampled. The default values are selected so that the area of the cropis 8~100% of the original image. This is the default setting used to train ResNets in Torchstyle.
• aspect_ratio_range (tuple of two floats) – Determines the distribution
from which an aspect ratio is sampled. The default values are 34 and 43 , which are also
the default setting to train ResNets in Torch style.
• return_param (bool) – Returns parameters if True.
Returns
If return_param = False, returns only the cropped image.

118

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

If return_param = True, returns a tuple of cropped image and param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and thedescription of the value.
• y_slice (slice): A slice used to crop the input image. The relation below holds together with
x_slice.
• x_slice (slice): Similar to y_slice.
out_img = img[:, y_slice, x_slice]• scale_ratio (float): 𝑠 in the description (see above).
• aspect_ratio (float): 𝑎 in the description.
Return type ndarray or (ndarray, dict)resizechainercv.transforms.resize(img, size, interpolation=2)
Resize image to match the given shape.
The backend used by resize() is configured by chainer.global_config.cv_resize_backend.
Two backends are supported: “cv2” and “PIL”. If this is None, “cv2” is used whenever “cv2” is installed, and“PIL” is used when “cv2” is not installed.
Parameters• img (ndarray) – An array to be transformed. This is in CHW format and the type should
be numpy.float32.
• size (tuple) – This is a tuple of length 2. Its elements are ordered as (height, width).
• interpolation (int) – Determines sampling strategy. This is one of PIL.
Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.
LANCZOS. Bilinear interpolation is the default strategy.
Returns A resize array in CHW format.
Return type ndarray
resize_containchainercv.transforms.resize_contain(img, size, fill=0, interpolation=2, return_param=False)
Resize the image to fit in the given area while keeping aspect ratio.
If both the height and the width in size are larger than the height and the width of the img, the img is placedon the center with an appropriate padding to match size.
Otherwise, the input image is scaled to fit in a canvas whose size is size while preserving aspect ratio.
Parameters• img (ndarray) – An array to be transformed. This is in CHW format.
• size (tuple of two ints) – A tuple of two elements: height, width. The sizeof the image after resizing.
• fill (float, tuple or ndarray) – The value of padded pixels. If it is numpy.
ndarray, its shape should be (𝐶, 1, 1), where 𝐶 is the number of channels of img.

3.8. Transforms

119ChainerCV Documentation, Release 0.13.1• interpolation (int) – Determines sampling strategy. This is one of PIL.
Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.
LANCZOS. Bilinear interpolation is the default strategy.
• return_param (bool) – Returns information of resizing and offsetting.
Returns
If return_param = False, returns an array out_img that is the result of resizing.
If return_param = True, returns a tuple whose elements are out_img, param.
param is a dictionary of intermediate parameters whose contents are listed below with key,value-type and the description of the value.
• y_offset (int): The y coordinate of the top left corner of the image after placing on thecanvas.
• x_offset (int): The x coordinate of the top left corner of the image after placing on thecanvas.
• scaled_size (tuple): The size to which the image is scaled to before placing it on a canvas.
This is a tuple of two elements: height, width.
Return type ndarray or (ndarray, dict)rotatechainercv.transforms.rotate(img, angle, expand=True, fill=0, interpolation=2)
Rotate images by degrees.
The backend used by rotate() is configured by chainer.global_config.cv_rotate_backend.
Two backends are supported: “cv2” and “PIL”. If this is None, “cv2” is used whenever “cv2” is installed, and“PIL” is used when “cv2” is not installed.
Parameters• img (ndarray) – An arrays that get rotated. This is in CHW format.
• angle (float) – Counter clock-wise rotation angle (degree).
• expand (bool) – The output shaped is adapted or not. If True, the input image is contained complete in the output.
• fill (float) – The value used for pixels outside the boundaries.
• interpolation (int) – Determines sampling strategy. This is one of PIL.Image.
NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC. Bilinear interpolation isthe default strategy.
Returns returns an array out_img that is the result of rotation.
Return type ndarray
scale
chainercv.transforms.scale(img, size, fit_short=True, interpolation=2)
Rescales the input image to the given “size”.
When fit_short == True, the input image will be resized so that the shorter edge will be scaled to length
size after resizing. For example, if the height of the image is larger than its width, image will be resized to(size * height / width, size).

120

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Otherwise, the input image will be resized so that the longer edge will be scaled to length size after resizing.
Parameters• img (ndarray) – An image array to be scaled. This is in CHW format.
• size (int) – The length of the smaller edge.
• fit_short (bool) – Determines whether to match the length of the shorter edge or the
longer edge to size.
• interpolation (int) – Determines sampling strategy. This is one of PIL.
Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.
LANCZOS. Bilinear interpolation is the default strategy.
Returns A scaled image in CHW format.
Return type ndarray
ten_crop
chainercv.transforms.ten_crop(img, size)
Crop 10 regions from an array.
This method crops 10 regions. All regions will be in shape size. These regions consist of 1 center crop and 4
corner crops and horizontal flips of them.
The crops are ordered in this order.
• center crop
• top-left crop
• bottom-left crop
• top-right crop
• bottom-right crop
• center crop (flipped horizontally)• top-left crop (flipped horizontally)• bottom-left crop (flipped horizontally)• top-right crop (flipped horizontally)• bottom-right crop (flipped horizontally)
Parameters• img (ndarray) – An image array to be cropped. This is in CHW format.
• size (tuple) – The size of output images after cropping. This value is (ℎ𝑒𝑖𝑔ℎ𝑡, 𝑤𝑖𝑑𝑡ℎ).
Returns The cropped arrays. The shape of tensor is (10, 𝐶, 𝐻, 𝑊 ).

3.8.2 Bounding Box

3.8. Transforms

121ChainerCV Documentation, Release 0.13.1

crop_bbox
chainercv.transforms.crop_bbox(bbox, y_slice=None, x_slice=None, allow_outside_center=True,
return_param=False)
Translate bounding boxes to fit within the cropped area of an image.
This method is mainly used together with image cropping. This method translates the coordinates of boundingboxes like translate_bbox(). In addition, this function truncates the bounding boxes to fit within thecropped area. If a bounding box does not overlap with the cropped area, this bounding box will be removed.
Parameters• bbox (ndarray) – See the table below.
• y_slice (slice) – The slice of y axis.
• x_slice (slice) – The slice of x axis.
• allow_outside_center (bool) – If this argument is False, bounding boxes whose
centers are outside of the cropped area are removed. The default value is True.
• return_param (bool) – If True, this function returns indices of kept bounding boxes.
name
bbox

shape
(𝑅, 4)

dtype
float32

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )Returns
If return_param = False, returns an array bbox.
If return_param = True, returns a tuple whose elements are bbox, param. param isa dictionary of intermediate parameters whose contents are listed below with key, value-type andthe description of the value.
• index (numpy.ndarray): An array holding indices of used bounding boxes.
• trancated_index (numpy.ndarray): An array holding indices of truncated bounding boxes,
with respect to returned bbox, rather than original bbox.
Return type ndarray or (ndarray, dict)flip_bbox
chainercv.transforms.flip_bbox(bbox, size, y_flip=False, x_flip=False)
Flip bounding boxes accordingly.
Parameters• bbox (ndarray) – See the table below.
• size (tuple) – A tuple of length 2. The height and the width of the image before resized.
• y_flip (bool) – Flip bounding box according to a vertical flip of an image.
• x_flip (bool) – Flip bounding box according to a horizontal flip of an image.
name
bbox

shape
(𝑅, 4)

dtype
float32

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )Returns Bounding boxes flipped according to the given flips.

122

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Return type ndarray
resize_bbox
chainercv.transforms.resize_bbox(bbox, in_size, out_size)
Resize bounding boxes according to image resize.
Parameters• bbox (ndarray) – See the table below.
• in_size (tuple) – A tuple of length 2. The height and the width of the image before
resized.
• out_size (tuple) – A tuple of length 2. The height and the width of the image after
resized.
name
bbox

shape
(𝑅, 4)

dtype
float32

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )Returns Bounding boxes rescaled according to the given image shapes.
Return type ndarrayrotate_bbox
chainercv.transforms.rotate_bbox(bbox, angle, size)
Rotate bounding boxes by degrees.
Parameters• bbox (ndarray) – See the table below.
• angle (float) – Counter clock-wise rotation angle (degree). image is rotated by 90
degrees.
• size (tuple) – A tuple of length 2. The height and the width of the image.
name
bbox

shape
(𝑅, 4)

dtype
float32

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )Returns Bounding boxes rescaled according to the given k.
Return type ndarraytranslate_bbox
chainercv.transforms.translate_bbox(bbox, y_offset=0, x_offset=0)
Translate bounding boxes.
This method is mainly used together with image transforms, such as padding and cropping, which translates theleft top point of the image from coordinate (0, 0) to coordinate (𝑦, 𝑥) = (𝑦𝑜𝑓 𝑓 𝑠𝑒𝑡 , 𝑥𝑜𝑓 𝑓 𝑠𝑒𝑡 ).
Parameters• bbox (ndarray) – See the table below.
• y_offset (int or float) – The offset along y axis.
3.8. Transforms

123ChainerCV Documentation, Release 0.13.1• x_offset (int or float) – The offset along x axis.
name
bbox

shape
(𝑅, 4)

dtype
float32

format(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )Returns Bounding boxes translated according to the given offsets.
Return type ndarray

3.8.3 Point
flip_point
chainercv.transforms.flip_point(point, size, y_flip=False, x_flip=False)
Modify points according to image flips.
Parameters• point (ndarray or list of arrays) – See the table below.
• size (tuple) – A tuple of length 2. The height and the width of the image, which is
associated with the points.
• y_flip (bool) – Modify points according to a vertical flip of an image.
• x_flip (bool) – Modify keypoipoints according to a horizontal flip of an image.
name
point

shape
(𝑅, 𝐾, 2) or [(𝐾, 2)]

dtype
float32

format(𝑦, 𝑥)

Returns Points modified according to image flips.
Return type ndarray or list of arrays
resize_point
chainercv.transforms.resize_point(point, in_size, out_size)
Adapt point coordinates to the rescaled image space.
Parameters• point (ndarray or list of arrays) – See the table below.
• in_size (tuple) – A tuple of length 2. The height and the width of the image before
resized.
• out_size (tuple) – A tuple of length 2. The height and the width of the image after
resized.
name
point

shape
(𝑅, 𝐾, 2) or [(𝐾, 2)]

dtype
float32

format(𝑦, 𝑥)

Returns Points rescaled according to the given image shapes.
Return type ndarray or list of arrays

124

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

translate_point
chainercv.transforms.translate_point(point, y_offset=0, x_offset=0)
Translate points.
This method is mainly used together with image transforms, such as padding and cropping, which translates the
top left point of the image to the coordinate (𝑦, 𝑥) = (𝑦𝑜𝑓 𝑓 𝑠𝑒𝑡 , 𝑥𝑜𝑓 𝑓 𝑠𝑒𝑡 ).
Parameters• point (ndarray or list of arrays) – See the table below.
• y_offset (int or float) – The offset along y axis.
• x_offset (int or float) – The offset along x axis.
name
point

shape
(𝑅, 𝐾, 2) or [(𝐾, 2)]

dtype
float32

format(𝑦, 𝑥)

Returns Points modified translation of an image.
Return type ndarray

3.9 Visualizations
3.9.1 vis_bbox
chainercv.visualizations.vis_bbox(img, bbox, label=None, score=None, label_names=None,instance_colors=None,alpha=1.0,
linewidth=3.0,
sort_by_score=True, ax=None)
Visualize bounding boxes inside image.
Example>>> from chainercv.datasets import VOCBboxDataset>>> from chainercv.datasets import voc_bbox_label_names>>> from chainercv.visualizations import vis_bbox>>> import matplotlib.pyplot as plt>>> dataset = VOCBboxDataset()>>> img, bbox, label = dataset[60]>>> vis_bbox(img, bbox, label,...
label_names=voc_bbox_label_names)>>> plt.show()This example visualizes by displaying the same colors for bounding boxes assigned to the same labels.
>>> from chainercv.datasets import VOCBboxDataset>>> from chainercv.datasets import voc_bbox_label_names>>> from chainercv.visualizations import vis_bbox>>> from chainercv.visualizations.colormap import voc_colormap>>> import matplotlib.pyplot as plt>>> dataset = VOCBboxDataset()>>> img, bbox, label = dataset[61]>>> colors = voc_colormap(label + 1)
(continues on next page)

3.9. Visualizations

125ChainerCV Documentation, Release 0.13.1(continued from previous page)>>> vis_bbox(img, bbox, label,...
label_names=voc_bbox_label_names,...
instance_colors=colors)>>> plt.show()Parameters• img (ndarray) – See the table below. If this is None, no image is displayed.
• bbox (ndarray) – See the table below.
• label (ndarray) – See the table below. This is optional.
• score (ndarray) – See the table below. This is optional.
• label_names (iterable of strings) – Name of labels ordered according to label
ids. If this is None, labels will be skipped.
• instance_colors (iterable of tuples) – List of colors. Each color is RGB
format and the range of its values is [0, 255]. The i-th element is the color used to visualize
the i-th instance. If instance_colors is None, the red is used for all boxes.
• alpha (float) – The value which determines transparency of the bounding boxes. The
range of this value is [0, 1].
• linewidth (float) – The thickness of the edges of the bounding boxes.
• sort_by_score (bool) – When True, instances with high scores are always visualized
in front of instances with low scores.
• ax (matplotlib.axes.Axis) – The visualization is displayed on this axis. If this isNone (default), a new axis is created.
name
img
bbox
label
score

shape
(3, 𝐻, 𝑊 )(𝑅, 4)
(𝑅, )
(𝑅, )

dtype
float32
float32
int32
float32

format
RGB, [0, 255]
(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 )[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–

Returns Returns the Axes object with the plot for further tweaking.
Return type Axes

3.9.2 vis_image
chainercv.visualizations.vis_image(img, ax=None)
Visualize a color image.
Parameters• img (ndarray) – See the table below. If this is None, no image is displayed.
• ax (matplotlib.axes.Axis) – The visualization is displayed on this axis. If this isNone (default), a new axis is created.
name
img

126

shape
(3, 𝐻, 𝑊 )dtype
float32

format
RGB, [0, 255]

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Returns Returns the Axes object with the plot for further tweaking.
Return type Axes

3.9.3 vis_instance_segmentation
chainercv.visualizations.vis_instance_segmentation(img,mask,label=None,score=None, label_names=None,instance_colors=None,alpha=0.7,
sort_by_score=True,
ax=None)Visualize instance segmentation.
ExampleThis example visualizes an image and an instance segmentation.
>>> from chainercv.datasets import SBDInstanceSegmentationDataset>>> from chainercv.datasets...
import sbd_instance_segmentation_
˓→label_names>>> from chainercv.visualizations import vis_instance_segmentation>>> import matplotlib.pyplot as plt>>> dataset = SBDInstanceSegmentationDataset()>>> img, mask, label = dataset[0]>>> vis_instance_segmentation(...
img, mask, label,...
label_names=sbd_instance_segmentation_label_names)>>> plt.show()This example visualizes an image, an instance segmentation and bounding boxes.
>>> from chainercv.datasets import SBDInstanceSegmentationDataset>>> from chainercv.datasets...
import sbd_instance_segmentation_
˓→label_names>>> from chainercv.visualizations import vis_bbox>>> from chainercv.visualizations import vis_instance_segmentation>>> from chainercv.visualizations.colormap import voc_colormap>>> from chainercv.utils import mask_to_bbox>>> import matplotlib.pyplot as plt>>> dataset = SBDInstanceSegmentationDataset()>>> img, mask, label = dataset[0]>>> bbox = mask_to_bbox(mask)>>> colors = voc_colormap(list(range(1, len(mask) + 1)))>>> ax = vis_bbox(img, bbox, label,...
label_names=sbd_instance_segmentation_label_names,...
instance_colors=colors, alpha=0.7, linewidth=0.5)>>> vis_instance_segmentation(...
None, mask, instance_colors=colors, alpha=0.7, ax=ax)>>> plt.show()Parameters• img (ndarray) – See the table below. If this is None, no image is displayed.
• mask (ndarray) – See the table below.
• label (ndarray) – See the table below. This is optional.
3.9. Visualizations

127

ChainerCV Documentation, Release 0.13.1• score (ndarray) – See the table below. This is optional.
• label_names (iterable of strings) – Name of labels ordered according to label
ids.
• instance_colors (iterable of tuple) – List of colors. Each color is RGB format and the range of its values is [0, 255]. The i-th element is the color used to visualize
the i-th instance. If instance_colors is None, the default color map is used.
• alpha (float) – The value which determines transparency of the figure. The range ofthis value is [0, 1]. If this value is 0, the figure will be completely transparent. The default
value is 0.7. This option is useful for overlaying the label on the source image.
• sort_by_score (bool) – When True, instances with high scores are always visualized
in front of instances with low scores.
• ax (matplotlib.axes.Axis) – The visualization is displayed on this axis. If this isNone (default), a new axis is created.
name
img
mask
label
score

shape
(3, 𝐻, 𝑊 )(𝑅, 𝐻, 𝑊 )
(𝑅, )
(𝑅, )

dtype
float32
bool
int32
float32

format
RGB, [0, 255]–
[0, #𝑓 𝑔_𝑐𝑙𝑎𝑠𝑠 − 1]–

Returns Returns ax. ax is an matploblib.axes.Axes with the plot.
Return type matploblib.axes.Axes

3.9.4 vis_point
chainercv.visualizations.vis_point(img, point, visible=None, ax=None)
Visualize points in an image.
Example>>> import chainercv>>> import matplotlib.pyplot as plt>>> dataset = chainercv.datasets.CUBKeypointDataset()>>> img, point, visible = dataset[0]>>> chainercv.visualizations.vis_point(img, point, visible)>>> plt.show()Parameters• img (ndarray) – See the table below. If this is None, no image is displayed.
• point (ndarray or list of arrays) – See the table below.
• visible (ndarray or list of arrays) – See the table below.
• ax (matplotlib.axes.Axes) – If provided, plot on this axis.

128

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

name
img
point
visibleshape(3, 𝐻, 𝑊 )(𝑅, 𝐾, 2) or [(𝐾, 2)](𝑅, 𝐾) or [(𝐾, )]dtype
float32
float32bool

format
RGB, [0, 255]
(𝑦, 𝑥)–

Returns Returns the Axes object with the plot for further tweaking.
Return type Axes

3.9.5 vis_semantic_segmentation
chainercv.visualizations.vis_semantic_segmentation(img, label, label_names=None,label_colors=None,
ignore_label_color=(0,0,0),
alpha=1,
all_label_names_in_legend=False,
ax=None)Visualize a semantic segmentation.
Example>>> from chainercv.datasets import VOCSemanticSegmentationDataset>>> from chainercv.datasets...
import voc_semantic_segmentation_
˓→label_colors>>> from chainercv.datasets...
import voc_semantic_segmentation_
˓→label_names>>> from chainercv.visualizations import vis_semantic_segmentation>>> import matplotlib.pyplot as plt>>> dataset = VOCSemanticSegmentationDataset()>>> img, label = dataset[60]>>> ax, legend_handles = vis_semantic_segmentation(...
img, label,...
label_names=voc_semantic_segmentation_label_names,...
label_colors=voc_semantic_segmentation_label_colors,...
alpha=0.9)>>> ax.legend(handles=legend_handles, bbox_to_anchor=(1, 1), loc=2)>>> plt.show()Parameters• img (ndarray) – See the table below. If this is None, no image is displayed.
• label (ndarray) – See the table below.
• label_names (iterable of strings) – Name of labels ordered according to label
ids.
• label_colors – (iterable of tuple): An iterable of colors for regular labels. Each color
is RGB format and the range of its values is [0, 255]. If colors is None, the default color
map is used.
• ignore_label_color (tuple) – Color for ignored label. This is RGB format and therange of its values is [0, 255]. The default value is (0, 0, 0).

3.9. Visualizations

129

ChainerCV Documentation, Release 0.13.1• alpha (float) – The value which determines transparency of the figure. The range ofthis value is [0, 1]. If this value is 0, the figure will be completely transparent. The default
value is 1. This option is useful for overlaying the label on the source image.
• all_label_names_in_legend (bool) – Determines whether to include all labelnames in a legend. If this is False, the legend does not contain the names of unusedlabels. An unused label is defined as a label that does not appear in label. The default
value is False.
• ax (matplotlib.axes.Axis) – The visualization is displayed on this axis. If this isNone (default), a new axis is created.
name
img
label

shape
(3, 𝐻, 𝑊 )(𝐻, 𝑊 )

dtype
float32
int32

format
RGB, [0, 255][−1, #𝑐𝑙𝑎𝑠𝑠 − 1]

Returns Returns ax and legend_handles. ax is an matploblib.axes.Axes with the plot.
It can be used for further tweaking. legend_handles is a list of legends. It can be passed
matploblib.pyplot.legend() to show a legend.
Return type matploblib.axes.Axes and list of matplotlib.patches.Patch

3.10 Utils
3.10.1 Bounding Box Utilities
bbox_iouchainercv.utils.bbox_iou(bbox_a, bbox_b)
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 and cupy.ndarray as inputs. Please note that both bbox_aand bbox_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 (𝑁, 4). 𝑁 is the number of bounding boxes.
The dtype should be numpy.float32.
• bbox_b (array) – An array similar to bbox_a, whose shape is (𝐾, 4). The dtype should
be numpy.float32.
Returns An array whose shape is (𝑁, 𝐾). An element at index (𝑛, 𝑘) contains IoUs between 𝑛 thbounding box in bbox_a and 𝑘 th bounding box in bbox_b.
Return type array
non_maximum_suppression
chainercv.utils.non_maximum_suppression(bbox, thresh, score=None, limit=None)
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
130

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

is mainly used as postprocessing of object detection. The bounding boxes are selected from ones with higherscores. If score 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 (𝑅, 4), where 𝑅 is thenumber of bounding boxes in the image. The second axis represents attributes of the bounding box. They are(𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 ), where the four attributes are coordinates of the top left and the bottom right vertices.
score is a float array of shape (𝑅, ). Each score indicates confidence of prediction.
This function accepts both numpy.ndarray and cupy.ndarray as an input. Please note that both bbox
and score 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 (𝑅, 4). 𝑅 is the numberof bounding boxes.
• thresh (float) – Threshold of IoUs.
• score (array) – An array of confidences whose shape is (𝑅, ).
• 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 ofbounding boxes in descending order. The shape of this array is (𝐾, ) and its dtype is numpy.
int32. Note that 𝐾 ≤ 𝑅.
Return type array

3.10.2 Download Utilities
cached_download
chainercv.utils.cached_download(url)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_REPORTto ‘OFF’.
It downloads a file from the URL if there is no corresponding cache. After the download, this function stores acache 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)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.

3.10. Utils

131

ChainerCV Documentation, Release 0.13.1

Parameters url (string) – URL to download from.
Returns Path to the downloaded file.
Return type string
extractall
chainercv.utils.extractall(file_path, destination, ext)
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 thisdirectory.
• ext (string) – An extension suffix of the archive file. This function supports '.zip','.tar', '.gz' and '.tgz'.

3.10.3 Image Utilities
read_image
chainercv.utils.read_image(file, dtype=<class ’numpy.float32’>, color=True, alpha=None)
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]. Ifcolor = True, the order of the channels is RGB.
The backend used by read_image() is configured by chainer.global_config.
cv_read_image_backend. Two backends are supported: “cv2” and “PIL”. If this is None, “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 objectof image.
• dtype – The type of array. The default value is float32.
• color (bool) – This option determines the number of channels. If True, the numberof channels is three. In this case, the order of the channels is RGB. This is the default
behaviour. If False, 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 ndarray

132

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

read_label
chainercv.utils.read_label(file, dtype=<class ’numpy.int32’>)
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 parameter color=True.
Parameters• file (string or file-like object) – A path of image file or a file-like objectof image.
• dtype – The type of array. The default value is int32.
• color (bool) – This option determines the number of channels. If True, the numberof channels is three. In this case, the order of the channels is RGB. This is the default
behaviour. If False, this function returns a grayscale image.
Returns An image.
Return type ndarraytile_images
chainercv.utils.tile_images(imgs, n_col, pad=2, fill=0)
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 (𝐶, 1, 1), where 𝐶 is the number of channels of img.
Returns An image array in CHW format. The size of this image is ((𝐻 + 𝑝𝑎𝑑𝑦 ) × ⌈𝐵/𝑛𝑛𝑐𝑜𝑙 ⌉, (𝑊 +𝑝𝑎𝑑𝑥 ) × 𝑛𝑐𝑜𝑙 ).
Return type ndarraywrite_image
chainercv.utils.write_image(img, file, format=None)
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 objectof image.
• format ({'bmp', 'jpeg', 'png'}) – The format of image. If file is a file-likeobject, this option must be specified.

3.10. Utils

133

ChainerCV Documentation, Release 0.13.1

3.10.4 Iterator Utilities
apply_to_iterator
chainercv.utils.apply_to_iterator(func, iterator, n_input=1, hook=None, comm=None)
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, thetuples may contain values that are not used by func(). For convenience, we allow the iterator to iterate overa collection of inputs that are not tuple. Here is an illustration of the expected behavior of the iterator. Thisbehaviour is the same as chainer.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 by func(). 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((continues on next page)

134

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1(continued from previous page)...
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 eachsample are treated as input values. They are passed to func. If comm is specified, only theiterator 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, and
rest_values are passed as arguments. Note that these values do not contain data fromthe previous iterations. If comm 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:
rest_values.

in_values, out_values and• in_values: A tuple of iterators. Each iterator returns a corresponding input value. For
example, if func() takes [in_val0], [in_val1], next(in_values[0]) andnext(in_values[1]) will be in_val0 and in_val1.
• out_values: A tuple of iterators. Each iterator returns a corresponding computed value. For example, if func() returns ([out_val0], [out_val1]),next(out_values[0]) and next(out_values[1]) will be out_val0 and
out_val1.
• rest_values: A tuple of iterators. Each iterator returns a corresponding rest
value. For example, if the iterator returns [(in_val0, in_val1, rest_val0,
rest_val1)], next(rest_values[0]) and next(rest_values[1]) will be
rest_val0 and rest_val1. If the input iterator does not give any rest values, this tuple
will be empty.
Return type Three tuples of iterators
ProgressHook
class chainercv.utils.ProgressHook(n_total=None)
A hook class reporting the progress of iteration.
This is a hook class designed for apply_prediction_to_iterator().
Parameters n_total (int) – The number of images. This argument is optional.

3.10. Utils

135

ChainerCV Documentation, Release 0.13.1

unzip
chainercv.utils.unzip(iterable)
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 samelength.
Returns Each iterator corresponds to each element of input tuple. Note that each iterator storesvalues until they are popped. To reduce memory usage, it is recommended to delete unused
iterators.
Return type tuple of iterators

3.10.5 Link Utilities
prepare_pretrained_model
chainercv.utils.prepare_pretrained_model(param, pretrained_model, models, default={})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 adictionary containing the configuration used by the selected weight.
model has four keys: param, overwritable, url and cv2.
– 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 if cv2 is not installed.

136

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

3.10.6 Mask Utilities
mask_iouchainercv.utils.mask_iou(mask_a, mask_b)
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 and cupy.ndarray as inputs. Please note that both mask_a
and mask_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 (𝑁, 𝐻, 𝑊 ). 𝑁 is the number of masks. The
dtype should be numpy.bool.
• mask_b (array) – An array similar to mask_a, whose shape is (𝐾, 𝐻, 𝑊 ). The dtype
should be numpy.bool.
Returns An array whose shape is (𝑁, 𝐾). An element at index (𝑛, 𝑘) contains IoUs between 𝑛 thmask in mask_a and 𝑘 th mask in mask_b.
Return type arraymask_to_bbox
chainercv.utils.mask_to_bbox(mask)
Compute the bounding boxes around the masked regions.
This function accepts both numpy.ndarray and cupy.ndarray as inputs.
Parameters mask (array) – An array whose shape is (𝑅, 𝐻, 𝑊 ). 𝑅 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 (𝑅, 4). 𝑅
is the number of bounding boxes. The dtype should be numpy.float32.
Return type array
scale_mask
chainercv.utils.scale_mask(mask, bbox, size)
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 (𝑅, 𝐻, 𝑊 ). 𝑅 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 by bbox = chainercv.utils.mask_to_bbox(mask).
• size (int) – The length of the smaller edge.
Returns An array whose shape is (𝑅, 𝐻, 𝑊 ). 𝑅 is the number of masks. The dtype should benumpy.bool.

3.10. Utils

137

ChainerCV Documentation, Release 0.13.1

Return type array

3.10.7 Testing Utilities
assert_is_bbox
chainercv.utils.assert_is_bbox(bbox, size=None)
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, Eachbounding box should be within the image.
assert_is_bbox_dataset
chainercv.utils.assert_is_bbox_dataset(dataset, n_fg_class, n_example=None)
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.
Parameters• dataset – A dataset to be checked.
• n_fg_class (int) – The number of foreground 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.
assert_is_detection_link
chainercv.utils.assert_is_detection_link(link, n_fg_class)
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, thisfunction 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)
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, thisfunction raises an AssertionError.
138

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• img (ndarray) – An image to be checked.
• color (bool) – A boolean that determines the expected channel size. If it is True, thenumber of channels should be 3. Otherwise, it should be 1. The default value is True.
• check_range (bool) – A boolean that determines whether the range of values arechecked or not. If it is True, The values of image must be in [0, 255]. Otherwise, thisfunction does not check the range. The default value is True.
assert_is_instance_segmentation_dataset
chainercv.utils.assert_is_instance_segmentation_dataset(dataset,
n_fg_class,n_example=None)
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.
Parameters• dataset – A dataset to be checked.
• n_fg_class (int) – The number of foreground 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.
assert_is_label_dataset
chainercv.utils.assert_is_label_dataset(dataset, n_class, n_example=None, color=True)
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 theAPI, 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, thenumber of channels should be 3. Otherwise, it should be 1. The default value is True.
assert_is_point
chainercv.utils.assert_is_point(point, visible=None, size=None, n_point=None)
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.
Parameters3.10. Utils

139

ChainerCV Documentation, Release 0.13.1• 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 ben_point.
assert_is_point_dataset
chainercv.utils.assert_is_point_dataset(dataset,n_point=None,
no_visible=False)
Checks if a dataset satisfies the point dataset API.

n_example=None,

This function checks if a given dataset satisfies the point dataset API or not. If the dataset does not satifiy theAPI, 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 numberof 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 that visible is always not contained. If
False, :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)
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.
Parameters• dataset – A dataset to be checked.
• n_class (int) – The number of classes including background.
• 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.
assert_is_semantic_segmentation_link
chainercv.utils.assert_is_semantic_segmentation_link(link, n_class)
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.
140

Chapter 3. ChainerCV Reference ManualChainerCV Documentation, Release 0.13.1

Parameters• link – A link to be checked.
• n_class (int) – The number of classes including background.
ConstantStubLink
class chainercv.utils.ConstantStubLink(outputs)
A chainer.Link that returns constant value(s).
This is a chainer.Link that returns constant chainer.Variable (s) when forward() method iscalled.
Parameters outputs (ndarray or tuple or ndarray) – The value(s) of variable(s) returned by forward(). If an array is specified, forward() returns a chainer.Variable.
Otherwise, it returns a tuple of chainer.Variable.
forward(*_)
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 a chainer.Variable. Otherwise, thisreturns a tuple of chainer.Variable.
Return type chainer.Variable or tuple of chainer.Variable
to_cpu()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)
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)
Generate valid bounding boxes with random position and shape.
Parameters• n (int) – The number of bounding boxes.
• img_size (tuple) – A tuple of length 2. The height and the width of the image on whichbounding boxes locate.
• min_length (float) – The minimum length of edges of bounding boxes.

3.10. Utils

141

ChainerCV Documentation, Release 0.13.1• max_length (float) – The maximum length of edges of bounding boxes.
Returns Coordinates of bounding boxes. Its shape is (𝑅, 4). Here, 𝑅 equals n. The second axis
contains 𝑦𝑚𝑖𝑛 , 𝑥𝑚𝑖𝑛 , 𝑦𝑚𝑎𝑥 , 𝑥𝑚𝑎𝑥 , where 𝑚𝑖𝑛_𝑙𝑒𝑛𝑔𝑡ℎ ≤ 𝑦𝑚𝑎𝑥 − 𝑦𝑚𝑖𝑛 < 𝑚𝑎𝑥_𝑙𝑒𝑛𝑔𝑡ℎ. and𝑚𝑖𝑛_𝑙𝑒𝑛𝑔𝑡ℎ ≤ 𝑥𝑚𝑎𝑥 − 𝑥𝑚𝑖𝑛 < 𝑚𝑎𝑥_𝑙𝑒𝑛𝑔𝑡ℎReturn type numpy.ndarray

142

Chapter 3. ChainerCV Reference ManualCHAPTER

FOUR

NAMING CONVENTIONS

Here are the notations used.
• 𝐵 is the size of a batch.
• 𝐻 is the height of an image.
• 𝑊 is the width of an image.
• 𝐶 is the number of channels.
• 𝑅 is the total number of instances in an image.
• 𝐿 is the number of classes.

4.1 Data objects
4.1.1 Images• imgs: (𝐵, 𝐶, 𝐻, 𝑊 ) or [(𝐶, 𝐻, 𝑊 )]• img: (𝐶, 𝐻, 𝑊 )Note: image is used for a name of a function or a class (e.g., chainercv.utils.write_image()).

4.1.2 Bounding boxes• bboxes: (𝐵, 𝑅, 4) or [(𝑅, 4)]• bbox: (𝑅, 4)• bb: (4, )4.1.3 Labels
namelabelslabel
lclassification
(𝐵, )
()
r lb

detection and instance segmentation(𝐵, 𝑅) or [(𝑅, )](𝑅, )–semantic segmentation(𝐵, 𝐻, 𝑊 )(𝐻, 𝑊 )()–

143

ChainerCV Documentation, Release 0.13.1

4.1.4 Scores and probabilitiesscore represents an unbounded confidence value. On the other hand, probability is bounded in [0, 1] and sums to1.
namescores or probs
score or probsc or pbclassification(𝐵, 𝐿)(𝐿, )–detection and instance segmentation(𝐵, 𝑅, 𝐿) or [(𝑅, 𝐿)](𝑅, 𝐿)(𝐿, )semantic segmentation(𝐵, 𝐿, 𝐻, 𝑊 )(𝐿, 𝐻, 𝑊 )–Note: Even for objects that satisfy the definition of probability, they can be named as score.

4.1.5 Instance segmentations• masks: (𝐵, 𝑅, 𝐻, 𝑊 ) or [(𝑅, 𝐻, 𝑊 )]• mask: (𝑅, 𝐻, 𝑊 )• msk: (𝐻, 𝑊 )4.2 Attributing an additonal meaning to a basic data object
4.2.1 RoIs
• rois: (𝑅′ , 4), which consists of bounding boxes∑︀
for multiple images. Assuming that there are 𝐵 images eachcontaining 𝑅𝑖 bounding boxes, the formula 𝑅′ =𝑅𝑖 is true.
• roi_indices: An array of shape (𝑅′ , ) that contains batch indices of images to which bounding boxes
correspond.
• roi: (𝑅, 4). This is RoIs for single image.

4.2.2 Attributes associated to RoIs
RoIs may have additional attributes, such as class scores and masks. These attributes are named by appending roi_(e.g., scores-like object is named as roi_scores).
• roi_xs: (𝑅′ , ) + 𝑥𝑠ℎ𝑎𝑝𝑒• roi_x: (𝑅, ) + 𝑥𝑠ℎ𝑎𝑝𝑒
In the case of scores with shape (𝐿, ), roi_xs would have shape (𝑅′ , 𝐿).
Note: roi_nouns = roi_noun = noun when batchsize=1. Changing names interchangeably is fine.

144

Chapter 4. Naming Conventions

ChainerCV Documentation, Release 0.13.1

4.2.3 Class-wise vs class-independent
cls_nouns is a multi-class version of nouns. For instance, cls_locs is (𝐵, 𝑅, 𝐿, 4) and locs is (𝐵, 𝑅, 4).
Note: cls_probs and probs can be used interchangeably in the case when there is no confusion.

4.2.4 Arbitrary input
x is a variable whose shape can be inferred from the context. It can be used only when there is no confusion on its
shape. This is usually the case when naming an input to a neural network.

4.2. Attributing an additonal meaning to a basic data object

145

ChainerCV Documentation, Release 0.13.1

146

Chapter 4. Naming Conventions

CHAPTERFIVE

LICENSE5.1 Source CodeThe source code of ChainerCV is licensed under MIT-License.

5.2 Pretrained Models
Pretrained models provided by ChainerCV are benefited from the following resources. See the following resources forthe terms of use of a model with weights pretrained by any of such resources.

147

ChainerCV Documentation, Release 0.13.1

model
ResNet50/101/152 (imagenet)
SEResNet50/101/152 (imagenet)
SEResNeXt50/101 (imagenet)
VGG16 (imagenet)
FasterRCNNVGG16 (imagenet)
FasterRCNNVGG16 (voc07/voc0712)

SSD300/SSD512 (imagenet)
SSD300/SSD512 (voc0712)

YOLOv2 (voc0712)

YOLOv3 (voc0712)

PSPNetResNet101 (cityscapes)
SegNetBasic (camvid)
FCISResNet101 (sbd)148

resource• ResNet50/101/152 (trained on ImageNet)• SEResNet50/101/152 (trained on ImageNet)• SEResNeXt50/101 (trained on ImageNet)• VGG-16 (trained on ImageNet)• VGG-16 (trained on ImageNet)• VGG-16 (trained on ImageNet)• PASCAL VOC• VGG-16 (trained on ImageNet, FC reduced)• SSD300/SSD512 (trained on PASCAL VOC
2007 and 2012)• Darknet19 (trained on ImageNet)• PASCAL VOC• Darknet53 (trained on ImageNet)• PASCAL VOC• PSPNet101 (trained on Cityscapes)• CamVid• ResNet101 (trained on ImageNet)• SBD

Chapter 5. LicenseCHAPTERSIX

INDICES AND TABLES• genindex• modindex• search

149

ChainerCV Documentation, Release 0.13.1

150

Chapter 6. Indices and tables

BIBLIOGRAPHY[Ren15] Shaoqing Ren, Kaiming He, Ross Girshick, Jian Sun. Faster R-CNN: Towards Real-Time Object Detection
with Region Proposal Networks. NIPS 2015.
[Liu16] Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C.
Berg. SSD: Single Shot MultiBox Detector. ECCV 2016.

151

ChainerCV Documentation, Release 0.13.1

152

Bibliography

PYTHON MODULE INDEX

cchainercv, 17
chainercv.chainer_experimental, 17
chainercv.chainer_experimental.datasets.sliceable,
17
chainercv.chainer_experimental.training.extensions,20
chainercv.datasets, 21
chainercv.evaluations, 32
chainercv.experimental.links.model.fcis,
45
chainercv.experimental.links.model.pspnet,
42
chainercv.experimental.links.model.yolo,
41
chainercv.extensions, 53
chainercv.functions, 58
chainercv.links, 61
chainercv.links.connection, 111
chainercv.links.model.deeplab, 97
chainercv.links.model.faster_rcnn, 70
chainercv.links.model.fpn, 100
chainercv.links.model.resnet, 63
chainercv.links.model.segnet, 96
chainercv.links.model.senet, 67
chainercv.links.model.ssd, 82
chainercv.links.model.vgg, 69
chainercv.links.model.yolo, 92
chainercv.transforms, 114
chainercv.utils, 130
chainercv.visualizations, 125

153

ChainerCV Documentation, Release 0.13.1

154

Python Module Index

INDEX

SymbolsB

bbox2loc()(inmodulechain__call__() (chainercv.experimental.links.model.fcis.ProposalTargetCreator
ercv.links.model.faster_rcnn), 72
method), 52
bbox_head_loss_post() (in module chain__call__() (chainercv.links.model.faster_rcnn.AnchorTargetCreator
ercv.links.model.fpn), 107
method), 79
bbox_head_loss_pre() (in module chain__call__() (chainercv.links.model.faster_rcnn.ProposalCreator
ercv.links.model.fpn), 107
method), 76
bbox_iou() (in module chainercv.utils), 130__call__() (chainercv.links.model.faster_rcnn.ProposalTargetCreator
BboxHead (class in chainercv.links.model.fpn), 103
method), 81
Bottleneck (class in chainercv.links.model.resnet), 65A

add_getter()(chain- C
cached_download() (in module chainercv.utils), 131
ercv.chainer_experimental.datasets.sliceable.GetterDataset
calc_detection_voc_ap() (in module chainmethod), 18
ercv.evaluations), 35
ADE20KSemanticSegmentationDataset (class
calc_detection_voc_prec_rec() (in modulein chainercv.datasets), 24
ADE20KTestImageDataset (class in chainchainercv.evaluations), 35
calc_instance_segmentation_voc_prec_rec()ercv.datasets), 25(in module chainercv.evaluations), 38
anchors() (chainercv.links.model.fpn.RPN method),
calc_semantic_segmentation_confusion()
105(in module chainercv.evaluations), 40
AnchorTargetCreator(classinchaincalc_semantic_segmentation_iou() (in modercv.links.model.faster_rcnn), 79
apply_to_iterator() (in module chainercv.utils),
ule chainercv.evaluations), 40
CamVidDataset (class in chainercv.datasets), 25
134
assert_is_bbox() (in module chainercv.utils), 138 center_crop() (in module chainercv.transforms),
114
assert_is_bbox_dataset() (in module chainercv.utils), 138
chainercv (module), 17
assert_is_detection_link() (in module chain- chainercv.chainer_experimental (module),
ercv.utils), 13817assert_is_image() (in module chainercv.utils), 138 chainercv.chainer_experimental.datasets.sliceable
assert_is_instance_segmentation_dataset()(module), 17(in module chainercv.utils), 139
chainercv.chainer_experimental.training.extensions(module), 20
assert_is_label_dataset() (in module chainercv.utils), 139
chainercv.datasets (module), 21
assert_is_point() (in module chainercv.utils), 139 chainercv.evaluations (module), 32
assert_is_point_dataset() (in module chain- chainercv.experimental.links.model.fcis(module), 45
ercv.utils), 140
assert_is_semantic_segmentation_dataset()
chainercv.experimental.links.model.pspnet(module), 42(in module chainercv.utils), 140
assert_is_semantic_segmentation_link() chainercv.experimental.links.model.yolo(in module chainercv.utils), 140(module), 41
chainercv.extensions (module), 53
155

ChainerCV Documentation, Release 0.13.1

chainercv.functions (module), 58
chainercv.links (module), 61, 110
chainercv.links.connection (module), 111
chainercv.links.model.deeplab (module), 97
chainercv.links.model.faster_rcnn (module), 70
chainercv.links.model.fpn (module), 100
chainercv.links.model.resnet (module), 63
chainercv.links.model.segnet (module), 96
chainercv.links.model.senet (module), 67
chainercv.links.model.ssd (module), 82
chainercv.links.model.vgg (module), 69
chainercv.links.model.yolo (module), 92
chainercv.transforms (module), 114
chainercv.utils (module), 130
chainercv.visualizations (module), 125
CityscapesSemanticSegmentationDataset(class in chainercv.datasets), 26
CityscapesTestImageDataset (class in chainercv.datasets), 26
COCOBboxDataset (class in chainercv.datasets), 28
COCOInstanceSegmentationDataset (class inchainercv.datasets), 29
COCOSemanticSegmentationDataset (class inchainercv.datasets), 29
ConcatenatedDataset(classinchainercv.chainer_experimental.datasets.sliceable),
17
ConstantStubLink (class in chainercv.utils), 141
Conv2DActiv (class in chainercv.links.connection),111
Conv2DBNActiv (class in chainercv.links.connection),112
convolution_crop()(inmodulechainercv.experimental.links.model.pspnet), 42
copy()(chainercv.links.PickableSequentialChain
method), 63
crop_bbox() (in module chainercv.transforms), 122
CUBKeypointDataset (class in chainercv.datasets),
27
CUBLabelDataset (class in chainercv.datasets), 27

decode() (chainercv.links.model.fpn.RPN method),105
decode() (chainercv.links.model.ssd.MultiboxCodermethod), 84
Decoder (class in chainercv.links.model.deeplab), 97
DeepLabV3plus(classinchainercv.links.model.deeplab), 98
DeepLabV3plusXception65 (class in chainercv.links.model.deeplab), 97
DetectionCOCOEvaluator (class in chainercv.extensions), 53
DetectionVisReport(classinchainercv.extensions), 57
DetectionVOCEvaluator(classinchainercv.extensions), 54
directory_parsing_label_names() (in module chainercv.datasets), 22
DirectoryParsingLabelDataset(classinchainercv.datasets), 21
distribute() (chainercv.links.model.fpn.BboxHead
method), 104
distribute() (chainercv.links.model.fpn.MaskHead
method), 106
download_model() (in module chainercv.utils), 131

D

FasterRCNN(classinchainercv.links.model.faster_rcnn), 72
FasterRCNN (class in chainercv.links.model.fpn), 101
FasterRCNNFPNResNet(classinchainercv.links.model.fpn), 102
FasterRCNNFPNResNet101 (class in chainercv.links.model.fpn), 100
FasterRCNNFPNResNet50(classinchainercv.links.model.fpn), 100
FasterRCNNTrainChain(classinchainercv.links.model.faster_rcnn), 80
FasterRCNNVGG16(classinchainercv.links.model.faster_rcnn), 71

Darknet19Extractor(classinchainercv.links.model.yolo), 94
Darknet53Extractor(classinchainercv.links.model.yolo), 94
DarknetExtractor(classinchainercv.experimental.links.model.yolo), 41
decode()(chainercv.links.model.fpn.BboxHead
method), 103
decode()(chainercv.links.model.fpn.MaskHead
method), 106

156

E
encode() (chainercv.links.model.ssd.MultiboxCodermethod), 85
eval_detection_coco() (in module chainercv.evaluations), 32
eval_detection_voc() (in module chainercv.evaluations), 34
eval_instance_segmentation_coco()(inmodule chainercv.evaluations), 36
eval_instance_segmentation_voc() (in module chainercv.evaluations), 37
eval_semantic_segmentation() (in module
chainercv.evaluations), 39
extractall() (in module chainercv.utils), 132

F

Index

ChainerCV Documentation, Release 0.13.1

FCIS (class in chainercv.experimental.links.model.fcis), FPN (class in chainercv.links.model.fpn), 103
46
FCISResNet101(classinchain- G
ercv.experimental.links.model.fcis), 45
generate_anchor_base() (in module chainFCISResNet101Head(classinchainercv.links.model.faster_rcnn), 74
ercv.experimental.links.model.fcis), 49
generate_random_bbox() (in module chainFCISTrainChain(classinchainercv.utils), 141
ercv.experimental.links.model.fcis), 50
get_example_by_keys()(chainFeaturePredictor (class in chainercv.links), 61
ercv.chainer_experimental.datasets.sliceable.ConcatenatedDataseflip() (in module chainercv.transforms), 115
method), 17
flip_bbox() (in module chainercv.transforms), 122
get_example_by_keys()(chainflip_point() (in module chainercv.transforms), 124
ercv.chainer_experimental.datasets.sliceable.GetterDataset
forward() (chainercv.experimental.links.model.fcis.FCIS
method), 18
method), 47
get_example_by_keys()(chainforward() (chainercv.experimental.links.model.fcis.FCISTrainChain
ercv.chainer_experimental.datasets.sliceable.TupleDataset
method), 51
method), 19
forward() (chainercv.experimental.links.model.yolo.DarknetExtractor
GetterDataset(classinchainmethod), 41
ercv.chainer_experimental.datasets.sliceable),forward() (chainercv.links.model.faster_rcnn.FasterRCNN
18
method), 73
GradientScaling(classinchainforward() (chainercv.links.model.faster_rcnn.FasterRCNNTrainChain
ercv.links.model.ssd), 89
method), 80
I
forward() (chainercv.links.model.faster_rcnn.RegionProposalNetwork
method), 77
InstanceSegmentationCOCOEvaluator (classforward()(chainercv.links.model.fpn.BboxHead
in chainercv.extensions), 55
method), 104
InstanceSegmentationVOCEvaluator (class inforward() (chainercv.links.model.fpn.RPN method),
chainercv.extensions), 56
105
forward() (chainercv.links.model.segnet.SegNetBasic K
method), 96
keys() (chainercv.chainer_experimental.datasets.sliceable.ConcatenatedD
forward()(chainercv.links.model.ssd.Multibox
property), 18
method), 83
keys() (chainercv.chainer_experimental.datasets.sliceable.GetterDataset
forward()(chainercv.links.model.ssd.Normalize
property), 19
method), 86
keys() (chainercv.chainer_experimental.datasets.sliceable.TupleDataset
forward() (chainercv.links.model.ssd.SSD method),
property), 19
87
forward() (chainercv.links.model.ssd.VGG16Extractor300
Lmethod), 88
loc2bbox()(inmodulechainforward() (chainercv.links.model.ssd.VGG16Extractor512
ercv.links.model.faster_rcnn), 75
method), 89
forward() (chainercv.links.model.yolo.Darknet19ExtractorM
method), 94
make_shift()(inmodulechainforward() (chainercv.links.model.yolo.Darknet53Extractor
ercv.chainer_experimental.training.extensions),
method), 94
20
forward() (chainercv.links.model.yolo.YOLOv2Base mask_head_loss_post() (in module chainmethod), 95
ercv.links.model.fpn), 109
forward()(chainercv.links.model.yolo.YOLOv3 mask_head_loss_pre() (in module chainmethod), 93
ercv.links.model.fpn), 108
forward() (chainercv.links.PickableSequentialChain mask_iou() (in module chainercv.utils), 137
method), 63
mask_to_bbox() (in module chainercv.utils), 137
forward() (chainercv.links.PixelwiseSoftmaxClassifier mask_to_segm()(inmodulechainmethod), 110
ercv.links.model.fpn), 109
forward() (chainercv.utils.ConstantStubLink method), mask_voting()(inmodulechain141
ercv.experimental.links.model.fcis), 49
Index

157

ChainerCV Documentation, Release 0.13.1

MaskHead (class in chainercv.links.model.fpn), 106
MaskRCNNFPNResNet101(classinchainercv.links.model.fpn), 101
MaskRCNNFPNResNet50(classinchainercv.links.model.fpn), 100
MixUpSoftLabelDataset(classinchainercv.datasets), 22
Multibox (class in chainercv.links.model.ssd), 83
multibox_loss()(inmodulechainercv.links.model.ssd), 89
MultiboxCoder (class in chainercv.links.model.ssd),
84

prepare()(chainercv.links.model.fpn.FasterRCNN
method), 102
prepare_pretrained_model() (in module chainercv.utils), 136
ProgressHook (class in chainercv.utils), 135
ProposalCreator(classinchainercv.links.model.faster_rcnn), 76
ProposalTargetCreator(classinchainercv.experimental.links.model.fcis), 51
ProposalTargetCreator(classinchainercv.links.model.faster_rcnn), 81
ps_roi_average_align_2d() (in module chainercv.functions), 58
N
ps_roi_average_pooling_2d() (in module
chainercv.functions), 59
non_maximum_suppression() (in module chainps_roi_max_align_2d() (in module chainercv.utils), 130
ercv.functions), 60
Normalize (class in chainercv.links.model.ssd), 85
ps_roi_max_pooling_2d() (in module chainercv.functions), 60O
PSPNet(classinchainOnlineProductsDataset(classinchainercv.experimental.links.model.pspnet),
44
ercv.datasets), 30
PSPNetResNet101(classinchainercv.experimental.links.model.pspnet), 42
P(classinchainpca_lighting() (in module chainercv.transforms), PSPNetResNet50
ercv.experimental.links.model.pspnet),
42
115
PickableSequentialChain (class in chainR
ercv.links), 62
PixelwiseSoftmaxClassifier (class in chain- random_crop() (in module chainercv.transforms),
116
ercv.links), 110
random_crop_with_bbox_constraints()(inpredict() (chainercv.experimental.links.model.fcis.FCIS
modulechainercv.links.model.ssd),
90
method), 47
random_distort()(inmodulechainpredict() (chainercv.experimental.links.model.pspnet.PSPNet
ercv.links.model.ssd),
91
method), 44
predict() (chainercv.links.FeaturePredictor method), random_expand() (in module chainercv.transforms),
116
62
random_flip()(in module chainercv.transforms),
predict() (chainercv.links.model.deeplab.DeepLabV3plus
117
method), 98
random_rotate() (in module chainercv.transforms),
predict() (chainercv.links.model.faster_rcnn.FasterRCNN
117
method), 74
random_sized_crop()(inmodulechainpredict()(chainercv.links.model.fpn.FasterRCNN
ercv.transforms),
118
method), 101
predict() (chainercv.links.model.segnet.SegNetBasic read_image() (in module chainercv.utils), 132
read_label() (in module chainercv.utils), 133
method), 97(classinchainpredict() (chainercv.links.model.ssd.SSD method), RegionProposalNetwork
ercv.links.model.faster_rcnn),
77
87(chainpredict()(chainercv.links.model.yolo.YOLOBase remove_unused()
ercv.links.PickableSequentialChain
method),method), 94
63
prepare() (chainercv.experimental.links.model.fcis.FCISResBlock(class in chainercv.links.model.resnet), 66
method), 48
ResidualBlock(class in chainercv.links.model.yolo),
prepare() (chainercv.links.model.deeplab.DeepLabV3plus
94
method), 98
resize() (in module chainercv.transforms), 119
prepare() (chainercv.links.model.faster_rcnn.FasterRCNN
resize_bbox() (in module chainercv.transforms),
method), 74
123
158

Index

ChainerCV Documentation, Release 0.13.1

resize_contain()(inmodulechainercv.transforms), 119
resize_point() (in module chainercv.transforms),
124
resize_with_random_interpolation() (inmodule chainercv.links.model.ssd), 91
ResNet (class in chainercv.links.model.resnet), 64
ResNet101 (class in chainercv.links.model.resnet), 65
ResNet101Extractor(classinchainercv.experimental.links.model.fcis), 50
ResNet152 (class in chainercv.links.model.resnet), 65
ResNet50 (class in chainercv.links.model.resnet), 65
rotate() (in module chainercv.transforms), 120
rotate_bbox() (in module chainercv.transforms),123
RPN (class in chainercv.links.model.fpn), 105
rpn_loss() (in module chainercv.links.model.fpn),
108

to_cpu() (chainercv.links.model.ssd.SSD method), 87
to_cpu()(chainercv.links.model.yolo.YOLOv2Basemethod), 95
to_cpu()(chainercv.links.model.yolo.YOLOv3
method), 93
to_cpu() (chainercv.links.PixelwiseSoftmaxClassifier
method), 110
to_cpu() (chainercv.utils.ConstantStubLink method),141
to_gpu() (chainercv.links.model.ssd.SSD method), 87
to_gpu()(chainercv.links.model.yolo.YOLOv2Basemethod), 96
to_gpu()(chainercv.links.model.yolo.YOLOv3
method), 93
to_gpu() (chainercv.links.PixelwiseSoftmaxClassifier
method), 110
to_gpu() (chainercv.utils.ConstantStubLink method),141
TransformDataset(classinchainS
ercv.chainer_experimental.datasets.sliceable),20
SBDInstanceSegmentationDataset (class intranslate_bbox()(inmodulechainchainercv.datasets), 32
ercv.transforms), 123
scale() (in module chainercv.transforms), 120
translate_point()(inmodulechainscale_mask() (in module chainercv.utils), 137
ercv.transforms), 125
SEBlock (class in chainercv.links.connection), 113(classinchainsegm_to_mask()(inmodulechain- TupleDataset
ercv.chainer_experimental.datasets.sliceable),
ercv.links.model.fpn), 107
19
SegNetBasic (class in chainercv.links.model.segnet),
96
SemanticSegmentationEvaluator (class in U
chainercv.extensions), 56
unzip() (in module chainercv.utils), 136
SeparableASPP(classinchain- use_preset()(chainercv.links.model.deeplab), 98
ercv.experimental.links.model.fcis.FCIS
SeparableConv2DBNActiv (class in chainmethod), 48
ercv.links.connection), 113
use_preset()(chainSEResNet (class in chainercv.links.model.senet), 67
ercv.links.model.faster_rcnn.FasterRCNN
SEResNet101 (class in chainercv.links.model.senet),
method), 74
68
use_preset()(chainSEResNet152 (class in chainercv.links.model.senet),
ercv.links.model.fpn.FasterRCNN
method),68
102
SEResNet50 (class in chainercv.links.model.senet), 67 use_preset()(chainercv.links.model.ssd.SSD
SEResNeXt (class in chainercv.links.model.senet), 68
method), 88
SEResNeXt101 (class in chainercv.links.model.senet), use_preset()(chain69
ercv.links.model.yolo.YOLOBasemethod),SEResNeXt50 (class in chainercv.links.model.senet),
95
69
V
SiameseDataset (class in chainercv.datasets), 23
SSD (class in chainercv.links.model.ssd), 86
VGG16 (class in chainercv.links.model.ssd), 88
SSD300 (class in chainercv.links.model.ssd), 82
VGG16 (class in chainercv.links.model.vgg), 69
SSD512 (class in chainercv.links.model.ssd), 82
VGG16Extractor300(classinchainercv.links.model.ssd), 88
T
VGG16Extractor512(classinchainercv.links.model.ssd), 89
ten_crop() (in module chainercv.transforms), 121
tile_images() (in module chainercv.utils), 133

Index

159

ChainerCV Documentation, Release 0.13.1

VGG16RoIHead(classinchainercv.links.model.faster_rcnn), 78
vis_bbox() (in module chainercv.visualizations), 125
vis_image() (in module chainercv.visualizations),
126
vis_instance_segmentation() (in module
chainercv.visualizations), 127
vis_point() (in module chainercv.visualizations),
128
vis_semantic_segmentation() (in module
chainercv.visualizations), 129
VOCBboxDataset (class in chainercv.datasets), 30
VOCInstanceSegmentationDataset (class inchainercv.datasets), 31
VOCSemanticSegmentationDataset (class inchainercv.datasets), 31

W
write_image() (in module chainercv.utils), 133

X
Xception65 (class in chainercv.links.model.deeplab),
99
XceptionBlock(classinchainercv.links.model.deeplab), 99

Y
YOLOBase (class in chainercv.links.model.yolo), 94
YOLOv2 (class in chainercv.links.model.yolo), 92
YOLOv2Base (class in chainercv.links.model.yolo), 95
YOLOv2Tiny(classinchainercv.experimental.links.model.yolo), 41
YOLOv3 (class in chainercv.links.model.yolo), 93

160

Index