Python API

This section includes information for using the pure Python API of bob.io.base.

Functions

bob.io.base.save(array, filename[, ...])

Saves the contents of an array-like object to file.

bob.io.base.load(inputs)

Loads the content of a file.

bob.io.base.vstack_features(reader, paths[, ...])

Stacks all features in a memory efficient way.

bob.io.image.to_matplotlib(img)

Returns a view of the image from Bob format to matplotlib format.

bob.io.image.to_bob(img)

Returns a view of the image from matplotlib format to Bob format.

bob.io.image.bob_to_pillow(img)

Converts the floating or uint8 image to a Pillow Image.

bob.io.image.pillow_to_bob(img)

Converts an RGB or gray-scale pillow image to Bob format.

bob.io.image.opencvbgr_to_bob(img)

Returns a view of the image from OpenCV BGR format to Bob RGB format.

bob.io.image.bob_to_opencvbgr(img)

Returns a view of the image from Bob format to OpenCV BGR format.

bob.io.image.imshow(img[, cmap])

Plots the images that are returned by bob.io.base.load()
bob.io.base.create_directories_safe(directory, dryrun=False)[source]

create_directories_safe is deprecated, use os.makedirs(directory, exist_ok=True) instead!

Creates a directory if it does not exists, with concurrent access support. This function will also create any parent directories that might be required. If the dryrun option is selected, it does not actually create the directory, but just writes the (Linux) command that would have been executed.

Parameters:

directorystr

The directory that you want to create.

dryrunbool

Only print the command to console, but do not execute it.

bob.io.base.load(inputs) → ndarray[source]

Loads the content of a file.

Will take a filename (or an iterable of filenames) and put the content into a numpy.ndarray.

Parameters:

inputs : various types

This might represent several different entities:

  1. The name of a file (full path) from where to load the data. In this case, this assumes that the file contains an array and returns a loaded numpy ndarray.

  2. An iterable of filenames to be loaded in memory. In this case, this would assume that each file contains a single 1D sample or a set of 1D samples, load them in memory and concatenate them into a single and returned 2D numpy.ndarray.

Returns:

datanumpy.ndarray

The data loaded from the given inputs.

bob.io.base.open_file(filename) → ndarray[source]

Reads a file content.

Parameters:

filename (str) – The name of the file to open.

bob.io.base.read(inputs) → ndarray

Loads the content of a file.

Will take a filename (or an iterable of filenames) and put the content into a numpy.ndarray.

Parameters:

inputs : various types

This might represent several different entities:

  1. The name of a file (full path) from where to load the data. In this case, this assumes that the file contains an array and returns a loaded numpy ndarray.

  2. An iterable of filenames to be loaded in memory. In this case, this would assume that each file contains a single 1D sample or a set of 1D samples, load them in memory and concatenate them into a single and returned 2D numpy.ndarray.

Returns:

datanumpy.ndarray

The data loaded from the given inputs.

bob.io.base.save(array, filename, create_directories=False)[source]

Saves the contents of an array-like object to file.

Effectively, this is the same as opening a file with the mode flag set to 'w' (write with truncation) and calling file.write passing array as parameter.

Parameters:

arrayarray_like

The array-like object to be saved on the file

filenamestr

The name of the file where you need the contents saved to

create_directoriesbool

Automatically generate the directories if required (defaults to False because of compatibility reasons; might change in future to default to True)

bob.io.base.vstack_features(reader, paths, same_size=False, dtype=None)[source]

Stacks all features in a memory efficient way.

Parameters:

  • reader (collections.Callable) – The function to load the features. The function should only take one argument path and return loaded features. Use functools.partial to accommodate your reader to this format. The features returned by reader are expected to have the same numpy.dtype and the same shape except for their first dimension. First dimension should correspond to the number of samples.

  • paths (collections.Iterable) – An iterable of paths to iterate on. Whatever is inside path is given to reader so they do not need to be necessarily paths to actual files. If same_size is True, len(paths) must be valid.

  • same_size (bool, optional) – If True, it assumes that arrays inside all the paths are the same shape. If you know the features are the same size in all paths, set this to True to improve the performance.

  • dtype (numpy.dtype, optional) – If provided, the data will be casted to this format.

Returns:

The read features with the shape (n_samples, *features_shape[1:]).

Return type:

numpy.ndarray

Examples

This function in a simple way is equivalent to calling numpy.vstack([reader(p) for p in paths]).

>>> import numpy
>>> from bob.io.base import vstack_features
>>> def reader(path):
...     # in each file, there are 5 samples and features are 2 dimensional.
...     return numpy.arange(10).reshape(5,2)
>>> paths = ['path1', 'path2']
>>> all_features = vstack_features(reader, paths)
>>> numpy.allclose(all_features, numpy.array(
...     [[0, 1],
...      [2, 3],
...      [4, 5],
...      [6, 7],
...      [8, 9],
...      [0, 1],
...      [2, 3],
...      [4, 5],
...      [6, 7],
...      [8, 9]]))
True
>>> all_features_with_more_memory = numpy.vstack([reader(p) for p in paths])
>>> numpy.allclose(all_features, all_features_with_more_memory)
True

You can allocate the array at once to improve the performance if you know that all features in paths have the same shape and you know the total number of the paths:

>>> all_features = vstack_features(reader, paths, same_size=True)
>>> numpy.allclose(all_features, numpy.array(
...     [[0, 1],
...      [2, 3],
...      [4, 5],
...      [6, 7],
...      [8, 9],
...      [0, 1],
...      [2, 3],
...      [4, 5],
...      [6, 7],
...      [8, 9]]))
True
bob.io.base.write(array, filename, create_directories=False)

Saves the contents of an array-like object to file.

Effectively, this is the same as opening a file with the mode flag set to 'w' (write with truncation) and calling file.write passing array as parameter.

Parameters:

arrayarray_like

The array-like object to be saved on the file

filenamestr

The name of the file where you need the contents saved to

create_directoriesbool

Automatically generate the directories if required (defaults to False because of compatibility reasons; might change in future to default to True)

bob.io.base.write_file(filename, data, format='pillow') → None[source]

Writes the contents of a numpy.ndarray to a file.

Parameters:

  • filename (str) – The name of the file to write to.

  • data (numpy.ndarray) – The data to write to the file.

  • format (str) – The format to use to read the file. By default imageio selects the appropriate for you based on the filename and its contents

bob.io.image.to_matplotlib(img)[source]

Returns a view of the image from Bob format to matplotlib format. This function works with images, batches of images, videos, and higher dimensional arrays that contain images.

Parameters:

img (numpy.ndarray) – A N dimensional array containing an image in Bob format (channels first): For an ND array (N >= 3), the image should have the following format: (..., c, h, w).

Returns:

A view of the img compatible with matplotlib.pyplot.imshow().

Return type:

numpy.ndarray

bob.io.image.to_bob(img)[source]

Returns a view of the image from matplotlib format to Bob format. This function works with images, batches of images, videos, and higher dimensional arrays that contain images.

Parameters:

img (numpy.ndarray) – An image in matplotlib format (channels last): For an ND array (N >= 3), the image should have the following format: (..., h, w, c).

Returns:

A view of the img compatible with Bob.

Return type:

numpy.ndarray

bob.io.image.bob_to_pillow(img)[source]

Converts the floating or uint8 image to a Pillow Image.

Parameters:

img (numpy.ndarray) – A gray-scale or RGB color image in Bob format (channels first)

Returns:

An Image object of pillow.

Return type:

PIL.Image.Image

bob.io.image.pillow_to_bob(img)[source]

Converts an RGB or gray-scale pillow image to Bob format.

Parameters:

img (PIL.Image.Image) – A Pillow Image

Returns:

Image in Bob format

Return type:

numpy.ndarray

bob.io.image.opencvbgr_to_bob(img)[source]

Returns a view of the image from OpenCV BGR format to Bob RGB format. This function works with images, batches of images, videos, and higher dimensional arrays that contain images.

Parameters:

img (numpy.ndarray) – An image loaded by OpenCV. It needs to have at least 3 dimensions.

Returns:

A view of the img compatible with Bob.

Return type:

numpy.ndarray

Raises:

ValueError – If the image dimension is less than 3.

bob.io.image.bob_to_opencvbgr(img)[source]

Returns a view of the image from Bob format to OpenCV BGR format. This function works with images, batches of images, videos, and higher dimensional arrays that contain images.

Parameters:

img (numpy.ndarray) – An image loaded by Bob. It needs to have at least 3 dimensions.

Returns:

A view of the img compatible with OpenCV.

Return type:

numpy.ndarray

Raises:

ValueError – If the image dimension is less than 3.

bob.io.image.imshow(img, cmap=None, **kwargs)[source]

Plots the images that are returned by bob.io.base.load()

Parameters:

  • img (numpy.ndarray) – A 2 or 3 dimensional array containing an image in bob style: For a 2D array (grayscale image) should be (h, w); A 3D array (color image) should be in the (c, h, w) format.

  • cmap (matplotlib.colors.Colormap) – Colormap, optional, default: None. If cmap is None and img.ndim is 2, defaults to ‘gray’. cmap is ignored when img has RGB(A) information.

  • **kwargs – These are passed directly to matplotlib.pyplot.imshow()

Returns:

Returns whatever plt.imshow returns.

Return type:

object