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 contents of a file, an iterable of files, or an iterable of `bob.io.base.File`'s into a `numpy.ndarray`.
`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(*args, **kwds)¶

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) → data[source]¶

Loads the contents of a file, an iterable of files, or an iterable of bob.io.base.File’s into a numpy.ndarray.

Parameters:

inputs : various types

This might represent several different entities:

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.

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.

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

An iterable with mixed filenames and File. In this case, this would returned a 2D numpy.ndarray, as described by points 2 and 3 above.

Returns:

datanumpy.ndarray: The data loaded from the given inputs.

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

Opens a file for reading.

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

bob.io.base.read(inputs)¶

load(inputs) -> data

Loads the contents of a file, an iterable of files, or an iterable of bob.io.base.File’s into a numpy.ndarray.

Parameters:

inputs : various types

This might represent several different entities:

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.

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.

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

An iterable with mixed filenames and File. In this case, this would returned a 2D numpy.ndarray, as described by points 2 and 3 above.

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 creating a File object 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 creating a File object 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) → 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 object of pillow.Image.
Return type: Image

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

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

Parameters: img (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