Python API¶

This section lists all the functionality available in this library allowing to run binary-segmentation benchmarks.

PyTorch bob.db Dataset¶

class bob.ip.binseg.data.binsegdataset.BinSegDataset(bobdb, split='train', transform=None, index_to=None)[source]¶

Bases: torch.utils.data.dataset.Dataset

PyTorch dataset wrapper around bob.db binary segmentation datasets. A transform object can be passed that will be applied to the image, ground truth and mask (if present). It supports indexing such that dataset[i] can be used to get ith sample.

Parameters

bobdb (bob.db.base) – Binary segmentation bob database (e.g. bob.db.drive)
split (str) – 'train' or 'test'. Defaults to 'train'
transform (bob.ip.binseg.data.transforms, optional) – A transform or composition of transfroms. Defaults to None.
mask (bool) – whether dataset contains masks or not

property mask¶

class bob.ip.binseg.data.binsegdataset.SSLBinSegDataset(labeled_dataset, unlabeled_dataset)[source]¶

Bases: torch.utils.data.dataset.Dataset

PyTorch dataset wrapper around bob.db binary segmentation datasets. A transform object can be passed that will be applied to the image, ground truth and mask (if present). It supports indexing such that dataset[i] can be used to get ith sample.

Parameters

labeled_dataset (torch.utils.data.Dataset) – BinSegDataset with labeled samples
unlabeled_dataset (torch.utils.data.Dataset) – UnLabeledBinSegDataset with unlabeled data

class bob.ip.binseg.data.binsegdataset.UnLabeledBinSegDataset(db, split='train', transform=None, index_from=None)[source]¶

Bases: torch.utils.data.dataset.Dataset

PyTorch dataset wrapper around bob.db binary segmentation datasets. A transform object can be passed that will be applied to the image, ground truth and mask (if present). It supports indexing such that dataset[i] can be used to get ith sample.

Parameters

dv (bob.db.base or str) – Binary segmentation bob database (e.g. bob.db.drive) or path to folder containing unlabeled images
split (str) – 'train' or 'test'. Defaults to 'train'
transform (bob.ip.binseg.data.transforms, optional) – A transform or composition of transfroms. Defaults to None.

PyTorch ImageFolder Dataset¶

bob.ip.binseg.data.imagefolder.get_file_lists(data_path)[source]¶

class bob.ip.binseg.data.imagefolder.ImageFolder(path, transform=None)[source]¶

Bases: torch.utils.data.dataset.Dataset

Generic ImageFolder dataset, that contains two folders:

images (vessel images)
gt (ground-truth labels)

Parameters: path (str) – full path to root of dataset

bob.ip.binseg.data.imagefolderinference.get_file_lists(data_path, glob)[source]¶

Recursively retrieves file lists from a given path, matching a given glob

This function will use pathlib.Path.rglob(), together with the provided glob pattern to search for anything the desired filename.

class bob.ip.binseg.data.imagefolderinference.ImageFolderInference(path, glob='*', transform=None)[source]¶

Bases: torch.utils.data.dataset.Dataset

Generic ImageFolder containing images for inference

Notice that this implementation, contrary to its sister ImageFolder, does not automatically convert the input image to RGB, before passing it to the transforms, so it is possible to accomodate a wider range of input types (e.g. 16-bit PNG images).

Parameters

path (str) – full path to root of dataset
glob (str) – glob that can be used to filter-down files to be loaded on the provided path
transform (list) – List of transformations to apply to every input sample

Transforms¶

Note

All transforms work with PIL.Image.Image objects. We make heavy use of the torchvision package

class bob.ip.binseg.data.transforms.Compose(transforms)[source]¶

Bases: object

Composes several transforms.

transforms¶

list of transforms to compose.

Type: list

class bob.ip.binseg.data.transforms.CenterCrop(size)[source]¶

Bases: object

Crop at the center.

size¶

target size

Type: int

class bob.ip.binseg.data.transforms.Crop(i, j, h, w)[source]¶

Bases: object

Crop at the given coordinates.

i¶

upper pixel coordinate.

Type: int

j¶

left pixel coordinate.

Type: int

h¶

height of the cropped image.

Type: int

w¶

width of the cropped image.

Type: int

class bob.ip.binseg.data.transforms.Pad(padding, fill=0)[source]¶

Bases: object

Constant padding

padding¶

padding on each border. If a single int is provided this is used to pad all borders. If tuple of length 2 is provided this is the padding on left/right and top/bottom respectively. If a tuple of length 4 is provided this is the padding for the left, top, right and bottom borders respectively.

Type: int or tuple

fill¶

pixel fill value for constant fill. Default is 0. If a tuple of length 3, it is used to fill R, G, B channels respectively. This value is only used when the padding_mode is constant

Type: int

class bob.ip.binseg.data.transforms.AutoLevel16to8[source]¶

Bases: object

Converts a 16-bit image to 8-bit representation using “auto-level”

This transform assumes that the input images are gray-scaled.

To auto-level, we calculate the maximum and the minimum of the image, and consider such a range should be mapped to the [0,255] range of the destination image.

class bob.ip.binseg.data.transforms.ToRGB[source]¶

Bases: object

Converts from any input format to RGB, using an ADAPTIVE conversion.

This transform takes the input image and converts it to RGB using py:method:Image.Image.convert, with mode=’RGB’ and using all other defaults. This may be aggressive if applied to 16-bit images without further considerations.

class bob.ip.binseg.data.transforms.ToTensor[source]¶

Bases: object

Converts PIL.Image.Image to torch.Tensor

class bob.ip.binseg.data.transforms.RandomHFlip(prob=0.5)[source]¶

Bases: object

Flips horizontally

prob¶

probability at which imgage is flipped. Defaults to 0.5

Type: float

class bob.ip.binseg.data.transforms.RandomVFlip(prob=0.5)[source]¶

Bases: object

Flips vertically

prob¶

probability at which imgage is flipped. Defaults to 0.5

Type: float

class bob.ip.binseg.data.transforms.RandomRotation(degree_range=(-15, 15), prob=0.5)[source]¶

Bases: object

Rotates by degree

degree_range¶

range of degrees in which image and ground truth are rotated. Defaults to (-15, +15)

Type: tuple

prob¶

probability at which imgage is rotated. Defaults to 0.5

Type: float

class bob.ip.binseg.data.transforms.ColorJitter(brightness=0.3, contrast=0.3, saturation=0.02, hue=0.02, prob=0.5)[source]¶

Bases: object

Randomly change the brightness, contrast, saturation and hue

brightness¶

how much to jitter brightness. brightness_factor is chosen uniformly from [max(0, 1 - brightness), 1 + brightness].

Type: float

contrast¶

how much to jitter contrast. contrast_factor is chosen uniformly from [max(0, 1 - contrast), 1 + contrast].

Type: float

saturation¶

how much to jitter saturation. saturation_factor is chosen uniformly from [max(0, 1 - saturation), 1 + saturation].

Type: float

hue¶

how much to jitter hue. hue_factor is chosen uniformly from [-hue, hue]. Should be >=0 and <= 0.5

Type: float

prob¶

probability at which the operation is applied

Type: float

static get_params(brightness, contrast, saturation, hue)[source]¶

class bob.ip.binseg.data.transforms.RandomResizedCrop(size, scale=(0.08, 1.0), ratio=(0.75, 1.3333333333333333), interpolation=2, prob=0.5)[source]¶

Bases: object

Crop to random size and aspect ratio. A crop of random size of the original size and a random aspect ratio of the original aspect ratio is made. This crop is finally resized to given size. This is popularly used to train the Inception networks.

size¶

expected output size of each edge

Type: int

scale¶

range of size of the origin size cropped. Defaults to (0.08, 1.0)

Type: tuple

ratio¶

range of aspect ratio of the origin aspect ratio cropped. Defaults to (3. / 4., 4. / 3.)

Type: tuple

interpolation¶: Defaults to PIL.Image.BILINEAR

prob¶

probability at which the operation is applied. Defaults to 0.5

Type: float

static get_params(img, scale, ratio)[source]¶

class bob.ip.binseg.data.transforms.Resize(size, interpolation=2)[source]¶

Bases: object

Resize to given size.

size¶

Desired output size. If size is a sequence like (h, w), output size will be matched to this. If size is an int, smaller edge of the image will be matched to this number. i.e, if height > width, then image will be rescaled to (size * height / width, size)

Type: tuple or int

interpolation¶

Desired interpolation. Default is``PIL.Image.BILINEAR``

Type: int

Losses¶

class bob.ip.binseg.modeling.losses.WeightedBCELogitsLoss(weight=None, size_average=None, reduce=None, reduction='mean', pos_weight=None)[source]¶

Bases: torch.nn.modules.loss._Loss

Implements Equation 1 in Maninis et al. (2016). Based on torch.nn.modules.loss.BCEWithLogitsLoss. Calculate sum of weighted cross entropy loss.

forward(input, target, masks=None)[source]¶

Parameters

input (torch.Tensor) –
target (torch.Tensor) –
masks (torch.Tensor, optional) –

Returns

Return type

torch.Tensor

class bob.ip.binseg.modeling.losses.SoftJaccardBCELogitsLoss(alpha=0.7, size_average=None, reduce=None, reduction='mean', pos_weight=None)[source]¶

Bases: torch.nn.modules.loss._Loss

Implements Equation 3 in Iglovikov et al. (2018). Based on torch.nn.modules.loss.BCEWithLogitsLoss.

alpha¶

determines the weighting of SoftJaccard and BCE. Default: 0.7

Type: float

forward(input, target, masks=None)[source]¶

Parameters

input (torch.Tensor) –
target (torch.Tensor) –
masks (torch.Tensor, optional) –

Returns

Return type

torch.Tensor

class bob.ip.binseg.modeling.losses.HEDWeightedBCELogitsLoss(weight=None, size_average=None, reduce=None, reduction='mean', pos_weight=None)[source]¶

Bases: torch.nn.modules.loss._Loss

Implements Equation 2 in He et al. (2015). Based on torch.nn.modules.loss.BCEWithLogitsLoss. Calculate sum of weighted cross entropy loss.

forward(inputlist, target, masks=None)[source]¶

Parameters

inputlist (list of torch.Tensor) – HED uses multiple side-output feature maps for the loss calculation
target (torch.Tensor) –
masks (torch.Tensor, optional) –

Returns

Return type

torch.Tensor

class bob.ip.binseg.modeling.losses.HEDSoftJaccardBCELogitsLoss(alpha=0.3, size_average=None, reduce=None, reduction='mean', pos_weight=None)[source]¶

Bases: torch.nn.modules.loss._Loss

Implements Equation 3 in Iglovikov et al. (2018) for the hed network. Based on torch.nn.modules.loss.BCEWithLogitsLoss.

alpha¶

determines the weighting of SoftJaccard and BCE. Default: 0.3

Type: float

forward(inputlist, target, masks=None)[source]¶

Parameters

input (torch.Tensor) –
target (torch.Tensor) –
masks (torch.Tensor, optional) –

Returns

Return type

torch.Tensor

class bob.ip.binseg.modeling.losses.MixJacLoss(lambda_u=100, jacalpha=0.7, size_average=None, reduce=None, reduction='mean', pos_weight=None)[source]¶

Bases: torch.nn.modules.loss._Loss

lambda_u¶

determines the weighting of SoftJaccard and BCE.

Type: int

forward(input, target, unlabeled_input, unlabeled_traget, ramp_up_factor)[source]¶

Parameters

input (torch.Tensor) –
target (torch.Tensor) –
unlabeled_input (torch.Tensor) –
unlabeled_traget (torch.Tensor) –
ramp_up_factor (float) –

Returns

Return type

list

Training¶

bob.ip.binseg.engine.trainer.do_train(model, data_loader, optimizer, criterion, scheduler, checkpointer, checkpoint_period, device, arguments, output_folder)[source]¶

Train model and save to disk.

Parameters

model (torch.nn.Module) – Network (e.g. DRIU, HED, UNet)
data_loader (torch.utils.data.DataLoader) –
optimizer (torch.optim) –
criterion (torch.nn.modules.loss._Loss) – loss function
scheduler (torch.optim) – learning rate scheduler
checkpointer (bob.ip.binseg.utils.checkpointer.DetectronCheckpointer) – checkpointer
checkpoint_period (int) – save a checkpoint every n epochs
device (str) – device to use 'cpu' or 'cuda'
arguments (dict) – start end end epochs
output_folder (str) – output path

Checkpointer¶

class bob.ip.binseg.utils.checkpointer.Checkpointer(model, optimizer=None, scheduler=None, save_dir='', save_to_disk=None, logger=None)[source]¶

Bases: object

Adapted from maskrcnn-benchmark under MIT license

Returns: [description]
Return type: [type]

save(name, **kwargs)[source]¶

load(f=None)[source]¶

has_checkpoint()[source]¶

get_checkpoint_file()[source]¶

tag_last_checkpoint(last_filename)[source]¶

class bob.ip.binseg.utils.checkpointer.DetectronCheckpointer(model, optimizer=None, scheduler=None, save_dir='', save_to_disk=None, logger=None)[source]¶: Bases: bob.ip.binseg.utils.checkpointer.Checkpointer

Inference and Evaluation¶

bob.ip.binseg.engine.inferencer.batch_metrics(predictions, ground_truths, names, output_folder, logger)[source]¶

Calculates metrics on the batch and saves it to disc

Parameters

predictions (torch.Tensor) – tensor with pixel-wise probabilities
ground_truths (torch.Tensor) – tensor with binary ground-truth
names (list) – list of file names
output_folder (str) – output path
logger (logging.Logger) – python logger

Returns

list containing batch metrics: [name, threshold, precision, recall, specificity, accuracy, jaccard, f1_score]

Return type

list

bob.ip.binseg.engine.inferencer.save_probability_images(predictions, names, output_folder, logger)[source]¶

Saves probability maps as image in the same format as the test image

Parameters

predictions (torch.Tensor) – tensor with pixel-wise probabilities
names (list) – list of file names
output_folder (str) – output path
logger (logging.Logger) – python logger

bob.ip.binseg.engine.inferencer.save_hdf(predictions, names, output_folder, logger)[source]¶

Saves probability maps as image in the same format as the test image

Parameters

predictions (torch.Tensor) – tensor with pixel-wise probabilities
names (list) – list of file names
output_folder (str) – output path
logger (logging.Logger) – python logger

bob.ip.binseg.engine.inferencer.do_inference(model, data_loader, device, output_folder=None)[source]¶

Run inference and calculate metrics

Parameters

model (torch.nn.Module) – neural network model (e.g. DRIU, HED, UNet)
data_loader (py:class:torch.torch.utils.data.DataLoader) –
device (str) – device to use 'cpu' or 'cuda'
output_folder (str) –

Plotting¶

bob.ip.binseg.utils.plot.precision_recall_f1iso(precision, recall, names, title=None)[source]¶

Author: Andre Anjos (andre.anjos@idiap.ch).

Creates a precision-recall plot of the given data. The plot will be annotated with F1-score iso-lines (in which the F1-score maintains the same value)

Parameters

precision (numpy.ndarray or list) – A list of 1D np arrays containing the Y coordinates of the plot, or the precision, or a 2D np array in which the rows correspond to each of the system’s precision coordinates.
recall (numpy.ndarray or list) – A list of 1D np arrays containing the X coordinates of the plot, or the recall, or a 2D np array in which the rows correspond to each of the system’s recall coordinates.
names (list) – An iterable over the names of each of the systems along the rows of precision and recall
title (str, optional) – A title for the plot. If not set, omits the title

Returns

A matplotlib figure you can save or display

Return type

matplotlib.figure.Figure

bob.ip.binseg.utils.plot.precision_recall_f1iso_confintval(precision, recall, pr_upper, pr_lower, re_upper, re_lower, names, title=None)[source]¶

Author: Andre Anjos (andre.anjos@idiap.ch).

Creates a precision-recall plot of the given data. The plot will be annotated with F1-score iso-lines (in which the F1-score maintains the same value)

Parameters

precision (numpy.ndarray or list) – A list of 1D np arrays containing the Y coordinates of the plot, or the precision, or a 2D np array in which the rows correspond to each of the system’s precision coordinates.
recall (numpy.ndarray or list) – A list of 1D np arrays containing the X coordinates of the plot, or the recall, or a 2D np array in which the rows correspond to each of the system’s recall coordinates.
names (list) – An iterable over the names of each of the systems along the rows of precision and recall
title (str, optional) – A title for the plot. If not set, omits the title

Returns

A matplotlib figure you can save or display

Return type

matplotlib.figure.Figure

bob.ip.binseg.utils.plot.loss_curve(df, title)[source]¶

Creates a loss curve given a Dataframe with column names:

['avg. loss', 'median loss','lr','max memory']

Parameters: df (pandas.DataFrame) –
Returns
Return type: matplotlib.figure.Figure

bob.ip.binseg.utils.plot.read_metricscsv(file)[source]¶

Read precision and recall from csv file

Parameters

file (str) – path to file

Returns

bob.ip.binseg.utils.plot.plot_overview(outputfolders, title)[source]¶

Plots comparison chart of all trained models

Parameters

outputfolder (list) – list containing output paths of all evaluated models (e.g. ['DRIVE/model1', 'DRIVE/model2'])
title (str) – title of plot

Returns

Return type

matplotlib.figure.Figure

bob.ip.binseg.utils.plot.metricsviz(dataset, output_path, tp_color=(0, 255, 0), fp_color=(0, 0, 255), fn_color=(255, 0, 0), overlayed=True)[source]¶

Visualizes true positives, false positives and false negatives Default colors TP: Gray, FP: Cyan, FN: Orange

Parameters

dataset (torch.utils.data.Dataset) –
output_path (str) – path where results and probability output images are stored. E.g. 'DRIVE/MODEL'
tp_color (tuple) – RGB values, by default (128,128,128)
fp_color (tuple) – RGB values, by default (70, 240, 240)
fn_color (tuple) – RGB values, by default (245, 130, 48)

bob.ip.binseg.utils.plot.overlay(dataset, output_path)[source]¶

Overlays prediction probabilities vessel tree with original test image.

Parameters

dataset (torch.utils.data.Dataset) –
output_path (str) – path where results and probability output images are stored. E.g. 'DRIVE/MODEL'

bob.ip.binseg.utils.plot.savetransformedtest(dataset, output_path)[source]¶

Save the test images as they are fed into the neural network. Makes it easier to create overlay animations (e.g. slide)

Parameters

dataset (torch.utils.data.Dataset) –
output_path (str) – path where results and probability output images are stored. E.g. 'DRIVE/MODEL'