API documentation

This is API documentation.

class img.Image(data, params)

A data container. The underlying data structure is a numpy ndarray. Implements transformations on images, as well as type conversion from the following data types :

png The classical image extension

gslib The .gslib format is a text format with the following structure :

nx ny nz x_orig y_orig z_orig x_padding y_padding z_padding

number_of_variables (should be 1 for our use)

name_of_variable_1

…

name_of_variable_n

then, on each line, the value of a coordinate (x,y,z), in the order of the nested loop :

for x = 1 to nx

for y = 1 to ny:

for z = 1 to nz:

vox A binary file used in MagicaVoxel and in other voxel editors. https://ephtracy.github.io/index.html?page=mv_main

Methods

apply_fun(fun)	Transformation method.
asArray()	Return the raw data as a numpy array
categorize(nb_categories[, …])	Transformation method.
exportAsGslib(output_name[, verbose])	Export the Image object data as a gslib file.
exportAsPng(output_name[, verbose])	Export the Image object data as a png file.
exportAsTxt(output_name[, verbose])	Export the Image object data as a txt file.
exportAsVox(output_name[, verbose])	Export the Image object data as a vox file.
exportCuts([output_folder, axis, n, invert])	Export the Image object data as cuts along an axis.
fromArray(ar[, normalize])	Image staticmethod.
fromGslib(file_name[, normalize])	Image staticmethod.
fromPng(file_name[, normalize])	Image staticmethod.
fromTxt(file_name, shape[, normalize])	Image staticmethod.
fromVox(file_name)	Image staticmethod.
get_sample(output_dim[, normalize])	Extract a random submatrix of a given size from the data container.
normalize()	Transformation method.
plot()	Displays the image using matplotlib.pyplot
saturate([t])	Transformation method.
threshold([thresholds, values])	Returns a categorized image according to thresholds specified.
tile_images(image_stack, mode)	Given a list of Images, reshapes them into a tiling for display.
unnormalize([output_type])	Transformation method.

apply_fun(fun)

Transformation method. Applies a function to every element of the data container.

Parameters:

‘fun’ : a python function returning an number

the function to be called

asArray()

Return the raw data as a numpy array

categorize(nb_categories: int, initial_clusters=None, norm='l1', max_iter=10)

Transformation method. Applies a clustering algorithm to categorize the image. k clusters will be created, with the color value of their barycenter.

Parameters:

‘nb_categories’ : int

The number of categories

‘initial_clusters’ : list

Values of the initial centroids for the cluster. If not provided, those values will be taken at random

‘norm’ : str

The distance to be used. Supported distance are l1 and l2. Only relevant when dealing with colored (multi channel) images.

‘max_iter’ : int

Maximal number of cluster updates allowed

exportAsGslib(output_name: str, verbose=False)

Export the Image object data as a gslib file. Requires the image to be a black and white one (only one channel)

Parameters:

‘output_name’ : string

relative path to the gslib file to be output

‘verbose’ : boolean

enables verbose mode. Set to False by default

exportAsPng(output_name: str, verbose=False)

Export the Image object data as a png file. Requires the data to be two dimensionnal.

Parameters:

‘output_name’ : string

relative path to the png file to be output

‘verbose’ : boolean

enables verbose mode. Set to False by default

exportAsTxt(output_name: str, verbose=False)

Export the Image object data as a txt file. Requires the data to be two dimensionnal.

Parameters:

‘output_name’ : string

relative path to the txt file to be output

‘verbose’ : boolean

enables verbose mode. Set to False by default

exportAsVox(output_name: str, verbose=False)

Export the Image object data as a vox file. Requires the image to be a black and white one (only one channel). Requires py-vox-io to function.

Parameters:

‘output_name’ : string

relative path to the vox file to be output

‘verbose’ : boolean

enables verbose mode. default=False

exportCuts(output_folder='cut_output', axis=-1, n=-1, invert=False)

Export the Image object data as cuts along an axis. Requires the image to be a black and white one (only one channel). The exported cuts are saved as png files. If the image is two dimensionnal, performs as exportAsPng.

Parameters:

‘output_folder’ : string

relative path to the folder file in which the cuts will be saved

‘axis’ : intI

The axis along the cuts are made. If set to -1, will perform cuts along all axis. default=-1

‘n’ : int

The number of cuts performed in the given direction. If set to -1, will perform every possible cuts. Otherwise, takes n cuts at random. Default=-1

‘invert’ : boolean

if set to true, will invert the colors of the image (x -> 255-x) default=False

static fromArray(ar, normalize=False)

Image staticmethod. Used as an initializer. Builds the container from a numpy array

Parameters:

‘ar’ : ndarray | list of ndarray

The numpy array around which the Image object is built A list of 2D ndarray can be given in order to build a 3D image

Returns:

A new Image object

static fromGslib(file_name: str, normalize=False)

Image staticmethod. Used as an initializer. Builds the container from a .gslib file.

Parameters:

‘file_name’ : string

relative path to the gslib file

‘normalize’ : boolean

if set to true, the values will be stretched to fit in [-1;1]

Returns:

A new Image object

static fromPng(file_name: str, normalize=False)

Image staticmethod. Used as an initializer. Builds the container from a .png file. Makes calls to the Pillow library

Parameters:

‘file_name’ : string

relative path to the png file

‘normalize’ : boolean

if set to true, the values will be stretched to fit in [-1;1]

Returns:

A new Image object

static fromTxt(file_name: str, shape, normalize=False)

Image staticmethod. Used as an initializer. Builds the container from a raw txt file

Parameters:

‘file_name’ : string

the relative path to the txt file to read

‘shape’ : tuple of int

the shape of the data (shape is not contained in the raw txt file, thus this parameter is necessary)

Returns:

A new Image object

static fromVox(file_name: str)

Image staticmethod. Used as an initializer. Builds the container from a .vox file. Requires py-vox-io to function

Parameters:

‘file_name’ : string

relative path to the gslib file

Returns:

A new Image object

get_sample(output_dim, normalize=False)

Extract a random submatrix of a given size from the data container.

Parameters:

‘output_dim’ : tuple

The size of the sample. All coordinates should lay between 0 and the corresponding coordinate of self._data

‘normalize’ : boolean

if set to true, apply the normalize method to the output sample to get values in [-1;1]

Returns:

A new Image object of size ‘output_dim’

normalize()

Transformation method. Applies a linear transformation to get all data in range [-1,1]

plot()

Displays the image using matplotlib.pyplot

saturate(t=5)

Transformation method. Applies a saturation of height t on the image, that is to say : sends elements with values<t to 255 and does not change other values.

This is usefull for the .vox format, where 0 values are being rendered as transparent.

Parameters:

‘t’ : int

the height of the saturation. default = 5

threshold(thresholds=[127], values=None)

Returns a categorized image according to thresholds specified.

Parameters:

‘thresholds’ : ndarray | list

must be non-empty and all image values must lie between first and last element of threshold

‘values’ : ndarray | list

a list of size len(thresholds)+1. If this argument is not None, the categories will take the given. Otherwise, the categores will have their mean value as a category value.

static tile_images(image_stack, mode)

Given a list of Images, reshapes them into a tiling for display.

Parameters:

‘image_stack’ : list of Images

the images that will be concatenated

‘mode’ : string | tuple

The mode of tiling. Three predefined modes are available :

horizontal -> ‘h’ option vertical -> ‘v’ option square -> ‘s’ option

You can also provide a tuple (nb_lines,nb_columns) for any rectangular tiling. If your number of images is not nb_lines*nb_columns, the function will complete with black images

Returns:

A new Image instance

unnormalize(output_type=<class 'numpy.uint8'>)

Transformation method. Applies a linear transformation to get all data in range [0,255]

Parameters:

‘output_type’ : np.dtype

The type the data will be casted to. default = np.uint8 (integers in range [0;255])

img.gslib_to_png(gslib_file: str, output_name: str)

Conversion function

img.gslib_to_vox(in_file: str, out_file: str, verbose=False)

Conversion function

img.labelize(image)

Label the data to get integers from 0 to the number of facies

Parameters:

image : ndarray | Image

non-empty numpy array or Image class object

Returns:

ndarray

array of the same shape of image containing the categories

img.png_to_gslib(png_file: str, output_name: str)

Conversion function

img.vox_to_gslib(in_file: str, out_file: str)

Conversion function