API documentation

This is API documentation.

connectivity.get_categories(image)

Find all values in a numpy array

Return a sorted list of categories found in image 2D arrays.

Parameters:

image : ndarray | Image

non-empty numpy array

Returns:

list

sorted list of all categories (from smallest to greatest)

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)

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

Returns:

dict

dictionary of connectivity functions, each being a numpy array of length n = image.shape[axis]

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

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