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
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

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.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
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
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
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
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
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

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'