I/O operation

The Plums dataflow module implements a set of IO routine to ease and speed up opening images and json files.

The Tile class and the ptype

The main interface to open and manipulation images in Plums is tthe Tile class. It allows loading images from disk through a variety of backends (TurboJPEG, Lycon, OpenCV and Pillow). It also adds explicit and native support for a variety of color domain through the ptype, which acts as a declination of numpy’s dtype for pixels.

As of now, the list of explicitly supported ptype is: RGB, BGR, RGBA, BGRA, and GREY.

Additional ptype may be created on the fly as long as they references existing channels.

class plums.dataflow.io.Tile(filename, ptype=ptype('RGB'), dtype=dtype('uint8'), **properties)[source]

Bases: plums.commons.data.mixin.PropertyContainer, plums.commons.data.tile.Tile

Load and manipulate images through a high level interface.

The Tile class acts as a “concrete” counterpart to the representational Tile class defined in the Plums data-model.

It necessarily stems from an actual image file on-disk and it additionally encloses 2 type information:

  • The data-type which is nothing more than the native numpy dtype and indicate the actual numeric type used (e.g. uint8, float32…).

  • The pixel-type which indicates the way a given pixel is stored as a vector of channel values (e.g. RGB, BGR, HSL, XYZ etc…).

Parameters

  • filename (PathLike) – The filename from where the image will be read.

  • ptype (ptype) – Optional. Default to RGB. The image pixel-type (e.g. RGB, BGR or Grey).

  • dtype (dtype) – Optional. Default to uint8. The internal ndarray storage data type.

  • **properties (Any) – Additional properties to store alongside the image.

filename

The filename from where the image was read.

Type

PathLike

property ptype

The image pixel-type.

In a similar fashion as data-type, the pixel-type encodes the way a particular pixel vector can be interpreted as actual data carried by the tile.

Type

ptype

property dtype

The internal ndarray storage data type.

Warning

Modifying the dtype will only modify the storage ndarray’s data type. No domain conversion logic is applied, that is to say that, for example, converting a uint8 Tile to float64 will effectively change the underlying array’s type but the data will still be between 0 and 255.

Type

dtype

property shape

The internal ndarray storage shape.

Type

tuple

property size

The stored image size as a (width, height) tuple.

Type

tuple

property width

The stored image width.

Type

float

property height

The stored image height.

Type

float

property info

Additional properties stored alongside the image.

Type

dict

property data

The stored image data.

Type

ndarray

save(filepath, ptype=ptype('RGB'))[source]

Save the Tile as a image on disk.

Parameters

  • ptype (ptype) – If provided, the ptype into which to save the Tile.

  • filepath (Path) – The path where to save the image.

Raises

  • ValueError – If filepath refers to un unsupported image type.

  • TypeError – If ptype is not RGB as it is the only supported save format for now.

clone()[source]

Create a copy of the Tile in a new memory location.

Returns

A new Tile instance.

Return type

Tile

totype(ptype=None, dtype=None)[source]

Convert the Tile storage format in-place to a new pixel-type or a new data-type.

Parameters

  • ptype (ptype) – If provided, the ptype into which to convert the Tile.

  • dtype (dtype) – If provided, it must be a valid numpy data-type into which the internal ndarray storage will be converted.

astype(ptype=None, dtype=None)[source]

Convert the Tile to a new pixel-type or a new data-type in a new Tile.

Parameters

  • ptype (ptype) – If provided, the ptype into which to convert the Tile.

  • dtype (dtype) – If provided, it must be a valid numpy data-type into which the internal ndarray storage will be converted.

Returns

A new converted Tile.

Return type

Tile

class plums.dataflow.io.ptype(string)[source]

Bases: object

The pixel-type of a given image: A representation of its spectral base.

As each actual pixel are stored as vectors, understanding of the base used is compulsory to decode a given pixel vector, the pixel-type class describes the way a given pixel is stored as a vector of channel values (e.g. RGB, BGR, HSL, XYZ etc…).

Parameters

string (str) – A string description of the pixel-type as a list of channel characters (e.g. 'RGB', 'rgY', 'bgr', 'y'…).

contains(channels)[source]

Return whether the pixel-type Channel vector contains a given Channel or Channel “sub-set”.

slice(channels)[source]

Compute the pixel-type Channel vector slice of a given sub-vector.

Parameters

channels (tuple, Channel) – Either a single Channel or a tuple of Channel assumed to be a sub-vector of the pixel-type Channel vector.

Returns

The slice of the Channel vector corresponding to the input or None if it is not contained in the Channel vector.

Return type

(int, int) or None

index(channels)[source]

Compute the pixel-type Channel indices of a given sub-set.

Parameters

channels (tuple, Channel) – Either a single Channel or a tuple of Channel assumed to be a sub-set of the pixel-type Channel vector.

Returns

The indices of the Channel corresponding to the input or None if it is not contained in the Channel vector.

Return type

(int, ) or None

get_conversion_fn_to(destination_ptype)[source]

Compute the conversion function from self to another ptype.

Parameters

destination_ptype (ptype) – The destination ptype object.

Returns

A conversion function to move from one ptype to another.

Return type

callable

Deserialize JSON with the fastest backend

Plums dataflow allows fast JSON deserialization with additional backends on top of the standard json library if they are available (OrJSON, RapidJSON, and SimpleJSON).

The use ordering is expected to reflect loading speed however, because the relative speed of backends is highly dependent on data, it is recommended to benchmark all library for specific use-cases to select the best possible backend.

plums.dataflow.io.json.load(filepath)[source]

Open a JSON file on disk as a Python structure.

Parameters

filepath (Path) – The path to the image file on disk.

Returns

The parsed Python structure.

Return type

Any

plums.dataflow.io.json.dump(data, filepath)[source]

Save a Python structure as a JSON file on disk.

Parameters

  • filepath (Path) – The path to the image file on disk.

  • data (Any) – The Python structure to save a JSON object.