API documentation

This is API documentation.

connectivity.get_components(image, background=None)

Computes connected components array of an input image

Returns array of the same size as the input array. The returned array contains integer labels, pixels belonging to the same components have the same label.

http://scikit-image.org/docs/stable/api/skimage.measure.html#label

Parameters:

image : ndarray | Image

non-empty numpy array

background : int

optional argument for background category; background pixels will belong to the same connected component If no background specified, no background is used at all

Returns:

ndarray

numpy array of the same size as input

connectivity.get_function(image, axis, max_lag=None)

Computes connectivity function along given axis for all categories in image

Returns a dictionary of connectivity functions. Keys of the dictionary are the categories given by get_categories. Each entry is a numpy array of connectivity values for all pixels in axis direction for all categories

Parameters:

image : ndarray | Image

axis : int | axis indicating the direction of the connectivity function

max_lag : int | maximum lag distance in pixels, default: image.shape[axis]

Returns:

dict

dictionary of connectivity functions, each being a numpy array of length max_lag

connectivity.get_map(image)

Computes connectivity map for all categories in image.

Returns a dictionary of connectivity maps. Keys of the dictionary are the categories given by get_categories. Each entry is a numpy 2D array of connectivity values for given shifts

Parameters:

image : ndarray | Image

non-empty numpy array

Returns:

ndarray

2D numpy array of size nx-1, ny-1

file: img.py author: Guillaume Coiffier, Julien Straubhaar last update: September 2018

Definition of class Image, and relative functions.

class img.Image(data, params)

A data container. Defines an image as a 3D grid with variable(s) / attribute(s):

shape: (3-uple of int) number of grid cells in each direction spacing : (3-uple of float) cell size in each direction origin : (3-uple float) origin of the grid (bottom-lower-left corner) nv: (int) number of variable(s) / attribute(s) data: dictionnary of (nz,ny,nx) arrays name: (string) name of the image

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

png pgm ppm vtk

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

nx ny nz x_orig y_orig z_orig x_spacing y_spacing z_spacing

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

add_variable(var_name[, value])	Appends one variable to the image
apply_fun(var_name[, fun])	Transformation method.
asArray([var_name])	Return the raw data as a numpy array
categorize([nb_categories, …])	Transformation method.
cutplot([name_var, cut_position])	Displays 3 perpendicular cuts through image using matplotlib.pyplot
exportAsGslib(output_name[, verbose])	Export the Image object data as a gslib file.
exportAsPgm(output_name[, var_name, …])	Export the Image object data as a pgm file.
exportAsPng(output_name[, colored, …])	Export the Image object data as a png file.
exportAsPpm(output_name[, var_name, …])	Export the Image object data as a pgm 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.
exportAsVtk(output_name[, var_name, …])	Export the Image object data as a vtk file.
exportCuts([output_folder, axis, n, invert])	Export the Image object data as cuts along an axis.
extract_variable(var_name[, copy])	Creates a new Image containing only the extracted variable
flipx()	Flips variable values according to x direction.
flipy()	Flips variable values according to x direction.
flipz()	Flips variable values according to x direction.
fromArray(ar[, var_first, normalize])	Image staticmethod.
fromGslib(file_name[, normalize, missing_value])	Image staticmethod.
fromPgm(file_name[, missing_value, var_name])	Image static method.
fromPng(file_name[, normalize, channel_mode])	Image staticmethod.
fromPpm(file_name[, missing_value, var_name])	Image static method.
fromTxt(file_name, shape[, normalize])	Image staticmethod.
fromVox(file_name)	Image staticmethod.
fromVtk(file_name[, missing_value])	Image static method.
get_sample(output_dim, var_name, normalize)	Extract a random submatrix of a given size from the data container.
normalize([var_names])	Transformation method.
permxy()	Permutes x and y directions.
permxz()	Permutes x and z directions.
permyz()	Permutes y and z directions.
plot([name_var])	Calls appropriate plot method for 2D and 3D image
plot_2D([name_var])	Displays the image using matplotlib.pyplot
remove_variable(var_name)	Delete one variable of the image
rename_variable(old_var_name, new_var_name)	Rename one variable.
reset_var_names_to_default()	Sets default variable names: var_name = (‘V0’, ‘V1’,…).
saturate(var_name, t)	Transformation method.
set_variable(var_name, value)	Sets one variable (of given name):
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(var_name[, output_type])	Transformation method.
vmax(var_name)	Maximal value of a variable.
vmin(var_name)	Minimal value of a variable.
x()	Returns 1-dimensional array of x coordinates.
y()	Returns 1-dimensional array of y coordinates.
z()	Returns 1-dimensional array of z coordinates.

empty
get_variables
nxy
nxyz
nxz
nyz
xmax
xmin
ymax
ymin
zmax
zmin

add_variable(var_name: str = None, value=None) → None

Appends one variable to the image

Parameters:

‘var_name’ : string | None

Name of the appended variable (set by default if None)

‘v’ : int/float | tuple/list/ndarray

value(s) of the newvariable: if type is int/float: constant variable if tuple/list/ndarray: must contain nx*ny*nz values,

which are appended in the image (after reshape if needed)

apply_fun(var_name: str = None, fun=None)

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

Parameters:

‘var_name’ : str

The name of the variable to apply the function to. Needs to be provided if several variables exist.

‘fun’ : a python function returning an number

the function to be called

asArray(var_name=None)

Return the raw data as a numpy array

Parameters:

‘var_name’ : string

The variable to export. If None, all variables will be exported and the variable selection will be the first dimension of the array

categorize(nb_categories=2, var_name: str = None, 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:

‘var_name’ : str

The name of the variable to categorize. Needs to be provided if several variables exist.

‘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

cutplot(name_var=None, cut_position=0)

Displays 3 perpendicular cuts through image using matplotlib.pyplot

exportAsGslib(output_name: str, verbose=False)

Export the Image object data as a gslib file.

Parameters:

‘output_name’ : string

relative path to the gslib file to be output

‘verbose’ : boolean

enables verbose mode. Set to False by default

exportAsPgm(output_name: str, var_name=None, missing_value=None, fmt='%.10g')

Export the Image object data as a pgm file.

Parameters:

‘output_name’ : string

name of the file to be written

‘var_name’ : string

The variable to be exported. Needs to be not None if several variables are present in the Image class.

‘missing_value’ float or None

nan values will be replaced by missing_value before writing

‘fmt’ : string

single format for variable values, of the form:

‘%[flag]width[.precision]specifier’

exportAsPng(output_name: str, colored=True, color_channels=['R', 'G', 'B'], 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

‘colored’ : boolean

Say if the output images is colored. If colored is False, will output every variable as a different png. If colored is True, will output one png file with 3 channels. Channels are defined in the color_channels argument

‘color_channels’ : list of 3 strings

The name of the three variables to be taken as red, green and blue channels. Default names are [‘R’, ‘G’, ‘B’]. This argument is ignored if colored is False

‘verbose’ : boolean

enables verbose mode. Set to False by default

exportAsPpm(output_name: str, var_name=['R', 'G', 'B'], missing_value=None, fmt='%.10g')

Export the Image object data as a pgm file.

Parameters:

‘output_name’ : string

name of the file to be written

‘var_name’ : list of 3 strings

The names of the channels to be output. There should be three channels

‘missing_value’ : float or None

nan values will be replaced by missing_value before writing

‘fmt’ : string

single format for variable values, of the form:

‘%[flag]width[.precision]specifier’

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

exportAsVtk(output_name: str, var_name=None, missing_value=None, fmt='%.10g', data_type='float', version=3.4)

Export the Image object data as a vtk file.

Parameters:

‘output_name’ : string

relative path to the vox file to be output

‘var_name’ : string

The variable to be exported. name to be written at line 2

‘verbose’ : boolean

enables verbose mode. default=False

‘missing_value’ : float|None

nan values will be replaced by this value before writing

‘fmt’ : string

single format for variable values, of the form:

‘%[flag]width[.precision]specifier’

‘data_type’ : string

data type (can be ‘float’, ‘int’, …)

‘version’ : float

version number (for data file)

exportCuts(output_folder='cut_output', var_name: str = None, 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:

‘var_name’ : str

The name of the variable to take cuts from. Needs to be provided if several variables exist.

‘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

extract_variable(var_name: list, copy=True)

Creates a new Image containing only the extracted variable

Parameters:

‘var_name’: list

List of the names of variables to be extracted

‘copy’ : boolean

If set to False, will delete the variables of var_name from the original imageself.

Returns:

A new Image object

flipx()

Flips variable values according to x direction.

flipy()

Flips variable values according to x direction.

flipz()

Flips variable values according to x direction.

static fromArray(ar, var_first=True, 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

‘var_first’ : boolean

Indicates if the variable index is the first of the last of the array. Set to True by default.

Returns:

A new Image object

static fromGslib(file_name: str, normalize=False, missing_value=None)

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 fromPgm(file_name: str, missing_value=None, var_name=['pgmValue'])

Image static method. Used as an initializer. Builds the container from a .pgm file.

Parameters:

‘file_name’ : string

name of the file

‘missing_value’ : float|None

value that will be replaced by nan

Returns:

A new Image object

static fromPng(file_name: str, normalize=False, channel_mode='RGB')

Image staticmethod. Used as an initializer. Builds the container from a .png file. If the png file is colored, three variables, named R,G and B will be imported.

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]

‘channel_mode’ : string

if set to RGB, will extract three variables R,G and B if set to Gray, will perform a grayscale transformation and extract only one variable. Default is RGB

Returns:

A new Image object

static fromPpm(file_name: str, missing_value=None, var_name=['R', 'G', 'B'])

Image static method. Used as an initializer. Builds the container from a .ppm file.

Parameters:

‘file_name’ : string

name of the file

‘missing_value’ : float|None

value that will be replaced by nan

‘var_name’ : list of 3 strings

name of the different variables of the image (default is [‘R’,’G’,’B’])

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

static fromVtk(file_name: str, missing_value=None)

Image static method. Used as an initializer. Builds the container from a .vtk file.

Parameters:

‘file_name’ : string

name of the file

‘missing_value’ : float|None

value that will be replaced by nan

Returns:

A new Image object

get_sample(output_dim, var_name: list = None, normalize: bool = 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]

‘var_name’ : list

the name of the variables in which the sample is taken. Needs to be specified if nvariables>1

Returns:

A new Image object of size (output_dim * len(var_name))

normalize(var_names=[])

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

Parameters:

‘var_names’ : list of string

The names of the variables to normalize. If set to empty list (default value), all variables will be normalized

permxy()

Permutes x and y directions.

permxz()

Permutes x and z directions.

permyz()

Permutes y and z directions.

plot(name_var=None)

Calls appropriate plot method for 2D and 3D image

plot_2D(name_var=None)

Displays the image using matplotlib.pyplot

remove_variable(var_name: str) → None

Delete one variable of the image

Parameters:

‘var_name’ string

Name of the variable to delete. If this variable is not present in the image, nothing happens

rename_variable(old_var_name: str, new_var_name: str) → None

Rename one variable. Parameters ———- ‘old_var_name’ : string

The name of the variable to be replaced. If old_var_name does not exist in the Image, nothing happens

‘new_var_name’ : string

The new name of the variable

reset_var_names_to_default()

Sets default variable names: var_name = (‘V0’, ‘V1’,…).

saturate(var_name: str = None, t: int = 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:

‘var_name’ : str

The name of the variable to saturate. Needs to be provided if several variables exist.

‘t’ : int

the height of the saturation. default = 5

set_variable(var_name: str, value)

Sets one variable (of given name):

Parameters:

var_name : string

variable name. If the name is not present in the image, nothing happens

v : int/float | tuple/list/ndarray

value(s) of the new variable: if type is int/float: constant variable if tuple/list/ndarray: must contain nx*ny*nz values,

which are appended in the image (reshaped if needed)

threshold(thresholds=[127], values=None, var_name: str = None)

Returns a categorized image according to thresholds specified.

Parameters:

‘var_name’ : str

The name of the variable to threshold. Needs to be provided if several variables exist.

‘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(var_name: list = None, 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])

‘var_names’ : list of string

The names of the variables to normalize. If set to empty list (default value), all variables will be normalized

vmax(var_name: str = None)

Maximal value of a variable.

Parameters:

‘var_name’ : string

The variable to consider. Has to be provided if there is more than one variable in the Image.

vmin(var_name: str = None)

Minimal value of a variable.

Parameters:

‘var_name’ : string

The variable to consider. Has to be provided if there is more than one variable in the Image.

x()

Returns 1-dimensional array of x coordinates.

y()

Returns 1-dimensional array of y coordinates.

z()

Returns 1-dimensional array of z coordinates.

exception img.UndefVarExc(fun_name)

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