Skip to content

Home

Jump to bottom
Kay Lächler edited this page Jul 9, 2021 · 11 revisions

ImageAccess class

The ImageAccess class provides an interface to multidimensional arrays in JavaScript which represent graylevel or colour images. It provides utility functions and easy pixel access. For this documentation it is assumed, for simplicity and readability, that the ImageAccess will be imported as

const Image = require('./ImageAccess.js')

which is why ImageAccess will be replaced by Image for the rest of the documentation.

Contents

Constructor

An Image object can either be instantiated with

var img = new Image(height, width);

which will create a new Image object of dimensions heightxwidth or with

var img = new Image(height, width, {rgb:true});

wich will create a new Image object of dimensions heightxwidthx3 when rgb is set to true.
Optionally height and width can be provided as an array [height, width] which makes it easy to create an image with the same dimensions as an existing image by using the shape method

var img = new Image(an_existing_image.shape());

By default the image is initialized to 0 for every pixel, but we can prvide an alternative initialization value by specifying the init_value parameter while instatiating a new Image object

var img = new Image(height, width, {init_value:255});

When using both optional arguments rgb and init_value, they need to be grouped in the same optional object

var img = new Image(height, width, {rgb:true, init_value:255});

An Image object can also be instatiated from an existing JavaScript array by passing it to the constructor

var img = new Image(an_existing_array);

Or finally, an empty image can be declared and afterwards be initialized with an existing array using the fromArray method. 

var img = new Image();
img.fromArray(some_existing_array);

Attributes

  • image : The actual image which is represented as a multidimensional array
  • nx : The horizontal size of the image
  • ny : The vertical size of the image

Static Methods

Static methods can be used without instantiating a class object and can be applied to any type of array.

Image.arrayCompare

Image.arrayCompare(a1, a2, err={'msg':null}, tol=1e-5)

  • Compares two arrays.

Parameters:

  • a1 (multidimensional array) : First array to compare
  • a1 (multidimensional array) : Second array to compare
  • err (object) : Object with a 'msg' field, where the error message will be stored
  • tol (scalar) : the tolerance to use in the comparison between each element

Returns:

  • output (boolean) : true if the arrays are the same, false if not

See also: imageCompare

Image.getMax

Image.getMax(arr)

  • Returns the maximum value of an arbitrarily-sized array.

Parameters:

  • arr (multidimensional array) : The array from which the maximum will be extracted.

Returns:

  • max_value (scalar) : Maximum value of the input array

See also: getMax

Image.getMin

Image.getMin(arr)

  • Returns the minimum value of an arbitrarily-sized array.

Parameters:

  • arr (multidimensional array) : The array from which the minimum will be extracted.

Returns:

  • min_value (scalar) : Minimum value of the input array

See also: getMin

Image.getNbh

Image.getNbh(img, x_pos, y_pos, nx, ny, padding='mirror')

  • Returns the nxxny neighbourhood around position (x_pos, y_pos) of the input array

Parameters:

  • img (2D or 3D array) : The array from which the neighbourhood will be extracted.
  • x_pos (integer scalar) : The x position where the neighbourhood should be extracted
  • y_pos (integer scalar) : The y position where the neighbourhood should be extracted
  • nx (integer scalar) : The width of the neighbourhood
  • ny (integer scalar) : The height of the neighbourhood
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

Returns:

  • nbh (2D or 3D array) : The neighbourhood around the specified location

Examples:
To get the zero-padded 5 by 5 neighbourhood around position (3,7) of image we use

var nbh_5x5 = Image.getNbh(image, 3, 7, 5, 5, padding='zero');

See also: getNbh

The effect of the different padding styles are given below:

zero-padding mirror-folding repeat-folding

Image.min

Image.min(a, b)

  • Calculates the minimum between two graylevel- and/or colour pixels. If one of the pixels is an rgb pixel, the return value will be an rgb pixel.

Parameters:

  • a (scalar or 1D array with 3 color channels) : First pixel
  • b (scalar or 1D array with 3 color channels) : Second pixel

Returns:

  • ouput (scalar or 1D array with 3 color channels) : Minimum of the two input pixels. For rgb pixels, each channel is calculated independently.

Image.MultidimArray

Image.MultidimArray(init_value, height, width, depth)

  • Creates a multidimensional array based on the given input parameters. Unused dimensions should be left out.

Parameters:

  • init_value (scalar) : Every element of the array will be initialized to this value
  • height (integer scalar) : The height of the array (y direction)
  • width (integer scalar) : The width of the array (x direction)
  • depth (integer scalar) : The depth of the array (z direction) also called channels in images

Returns:

  • ouput (1D/2D/3D array) : Multidimensional array with dimensions according to the input parameters and initialized to init_value

Examples:
To create a 1D array filled with zeros of length 100 we use

var arr_1d = Image.MultidimArray(0, 100);

To create a 2D array filled with zeros of size 100x100 we use

var arr_2d = Image.MultidimArray(0, 100, 100);

which could potentially represent a grayscale image of 100 by 100 pixels.

To create a 3D array filled with 255s of size 100x100x3 we use

var arr_3d = Image.MultidimArray(255, 100, 100, 3);

which could potentially represent a colour image of 100 by 100 pixels.

Image.ndims

Image.ndims(arr)

  • Returns the dimensionality of a given array

Parameters:

  • arr (multidimensional array) : The array of which we want to know the dimensionality

Returns:

  • ndims (scalar) : Scalar indicating the number of dimensions

See also: ndims

Image.shape

Image.shape(arr)

  • Returns the shape of a given array

Parameters:

  • arr (multidimensional array) : The array of which we want to know the shape

Returns:

  • shape (1D array) : 1D array containing the number of elements in each dimension (height, width, depth/channels, additional dimensions...)

See also: shape

Image.transpose

Image.transpose(array)

  • Returns transpose of the input array.

Parameters:

  • array(2D or 3D array) : The array that should be transposed

Returns:

  • output(2D or 3D array) : The transposed input array

See also: transposeImage

Prototypical methods

Prototypical methods have to be called from an instantiated Image object and are usually applied to the Image object itself.

copy

copy()

  • Returns a copy of the Image object

Returns:

  • copy (Image object) : A copy of the Image object this is called from.

fromArray

fromArray(arr)

  • Initializes an Image object from a given array as described here.

Parameters:

  • arr (2D array or 3D array with 3 channels) : An array containing image information

getMax

getMax()

  • Returns the maximum value of the image

Returns:

  • output (scalar) : The maximum value of the image

See also : Image.getMax

getMin

getMin()

  • Returns the minimum value of the image

Returns:

  • output (scalar) : The minimum value of the image

See also : Image.getMin

getNbh

getNbh(x_pos, y_pos, nx, ny, padding='mirror')

  • Returns the nxxny neighbourhood around position (x_pos, y_pos) of the image

Parameters:

  • x_pos (integer scalar) : The x position where the neighbourhood should be extracted
  • y_pos (integer scalar) : The y position where the neighbourhood should be extracted
  • nx (integer scalar) : The width of the neighbourhood
  • ny (integer scalar) : The height of the neighbourhood
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

Returns:

  • nbh (Image object) : A new Image object containing the neighbourhood around the specified location

Examples:
To get the zero-padded 5 by 5 neighbourhood around position (3,7) of the Image object img we use

var nbh_5x5 = img.getNbh(3, 7, 5, 5, padding='zero');

See also: Image.getNbh

A representation of the different padding styles is given here.

getPixel

getPixel(x, y, padding='mirror')

  • Returns the pixel at location (x,y)

Parameters:

  • x (integer scalar) : x position of the pixel
  • y (integer scalar) : y position of the pixel
  • padding (optional)(string) : The type of padding which should be applied when accessing an out of bounds pixel. Default is 'mirror', other padding possibilities are shown here.

Returns:

  • pixel (scalar or 1D array) : The pixel at location (x,y) of the image as a scalar for grayscale images or 3 values in a 1D array for colour images

imageCompare

imageCompare(newImage, err={'msg':null}, tol=1e-5)

  • Compares two images

Parameters:

  • newImage (2D or 3D(with 3 channels) array) : The image to which the object will be compared to
  • err (object) : Object with a 'msg' field, where the error message will be stored
  • tol (scalar) : The tolerance to use in the comparison between each pixel

Returns:

  • output (boolean) : true if the images are the same, false if not

See also: Image.arrayCompare

ndims

ndims()

  • Returns the dimensionality of the image

Returns:

  • output (scalar) : The number of dimensions of the image (1 if empty, 2 if grayscale, 3 if colour)

See also: Image.ndims

setPixel

setPixel(x, y, value, padding='mirror')

  • Set the pixel at location (x,y) to value value

Parameters:

  • x (integer scalar) : x position of the pixel
  • y (integer scalar) : y position of the pixel
  • value (scalar or 1D array with 3 channels) : pixel value to set
  • padding (optional)(string) : The type of padding which should be applied when accessing an out of bounds pixel. Default is 'mirror', other padding possibilities are shown here. Zero-padding cannot be applied to setPixel.

Examples: To set the pixel of a grayscale image img_gray at location (2,5) to 1 we use

img_gray.setPixel(2, 5, 1);

To set the pixel of a colour image img_colour at location (215,512) to blue ([0, 0, 255]) we use

img_colour.setPixel(215, 512, [0, 0, 255]);

shape

shape()

  • Returns the shape of the image

Returns:

  • shape (1D array) : 1D array containing the number of elements in each dimension (height, width, channels)

See also: Image.shape

sort

sort(b)

  • Returns a sorted array (in ascending order) of the pixel values.

Parameters:

  • b (optional) (Image object) : Structuring element defining which pixels are used from the image. Set the pixels that should be used to 1 or true. When none is given, all pixels are used.

Returns:

  • ouput (Image object) : The sorted array. For grayscale images this is a 1D Image object. For colour images this is a an array, containing one 1D Image object per color channel.

Examples:
Accessing the 2nd smallest value of a grayscale image

var sorted = grayscale_image.sort();
var second_smallest_value = sorted[1];

For colour images 3 arrays are returned, one for each color channel

var sorted = colour_image.sort();
var red_sorted = sorted[0];
var green_sorted = sorted[1];
var blue_sorted = sorted[2];

then we can access the 5th smallest value of the blue colour channel

var fifth_smallest_blue_value = blue_sorted[4];

Optionally, a structuring element can be defined to indicate the pixels that should be used. For example we could have a 3 by 3 neighbourhood of some image and we only want to use the corners of this neighbourhood and get them as a sorted array. First we define the structuring element as an Image object with size 3x3, which will be initialized to 0 everywhere

var structuring_element = new Image(3, 3);

then we can set the pixels of the structuring element to 1, which we want to use for the sorting. In our case just the corners

structuring_element.setPixel(0, 0, 1); // upper left corner
structuring_element.setPixel(0, 2, 1); // upper right corner
structuring_element.setPixel(2, 0, 1); // lower left corner
structuring_element.setPixel(2, 2, 1); // lower right corner

finally we pass the structuring element to the sort function, when calling it on nbh that should be sorted

var sorted = nbh.sort(structuring_element);

sorted is now a sorted array consisting of the corners of nbh.

toArray

toArray()

  • Returns the image as a 2D/3D array, which is needed to convert the image to python

Returns:

  • output (2D/3D array) : the image as a 2D/3D array

Examples:
In JavaScript, we instantiate a new Image object from an existing array

var img = new Image(an_existing_array);

After modifying the Image object using the utility functions provided by the Image class, we convert it back to an array

var img_array = img.toArray();

which can then be imported to python as explained here.

normalize

normalize()

  • Returns the image with its range normalized to the range [0,1]

Returns:

  • output (Image object) : The normalized image

getRow

getRow(y, padding='mirror')

  • Returns the y'th row of the image.

Parameters:

  • y (integer scalar) : The row to be extracted
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

Returns:

  • row (1D Image object) : The row at position y

See also: getColumn, putRow

getColumn

getColumn(x, padding='mirror')

  • Returns the x'th column of the image.

Parameters:

  • x (integer scalar) : The column to be extracted
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

Returns:

  • col (1D Image object) : The column at position x

See also: getRow, putRow

putRow

putRow(y, new_row, padding='mirror')

  • Inserts new_row into the y'th row.

Parameters:

  • y (integer scalar) : Where the row should be inserted
  • new_row(1D Image Object) : The row which should be inserted
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

See also: getRow, putColumn

putColumn

putColumn(x, new_column, padding='mirror')

  • Inserts new_column into the x'th column.

Parameters:

  • x (integer scalar) : Where the column should be inserted
  • new_column(1D Image object) : The column which should be inserted
  • padding (string) : The type of padding that should be applied when extracting regions that are outside the image. Default is 'mirror', which mirrors the image on its edges; 'repeat' will repeat the image on its edges; 'zero' will return '0' for pixels that are outside the image.

See also: getRow, putRow

transposeImage

transposeImage()

  • Transposes the image.

See also: Image.transpose

putSubImage

putSubImage(x, y, img)

  • Inserts the sub-image img at location (x,y) into the image.

Parameters:

  • x(integer scalar) : The x position of the top-left corner where the sub-image should be inserted
  • y(integer scalar) : The y position of the top-left corner where the sub-image should be inserted
  • img(Image object) : The sub-image that should be inserted

getSubImage

getSubImage(x, y, nx, ny)

  • Returns the sub-image img of dimensions nx by ny at location (x,y).

Parameters:

  • x(integer scalar) : The x position of the top-left corner from where the sub-image should be extracted
  • y(integer scalar) : The y position of the top-left corner from where the sub-image should be extracted
  • nx(integer scalar) : The horizontal size of the subimage
  • ny(integer scalar) : The vertical size of the subimage

Returns

  • sub_img(Image object) : The nx by ny subimage image at location (x,y)

visualize

visualize(decimals=3)

  • Returns a formatted string that can be used to display the image in the console.

Parameters:

  • decimals(integer scalar) : The desired number of decimals after the comma

Returns

  • f_string(string) : The image as a formatted string
Clone this wiki locally