Object Analysis

Functions for analyzing and manipulating objects in binary arrays.

objscale.get_structure_props(array, x_sizes, y_sizes, structure=array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]), print_none=False, wrap=None)

Calculate properties of structures in a binary array.

Given an array and the sizes of each pixel in each direction, calculate properties of structures. Any perimeter between structure and nan is not counted.

Parameters:

• array (np.ndarray) – Binary array of structures: 2-d array, padded with 0’s or np.nan’s.

• x_sizes (np.ndarray) – Sizes of pixels in horizontal direction, same shape as array.

• y_sizes (np.ndarray) – Sizes of pixels in vertical direction, same shape as array.

• structure (np.ndarray, default=np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])) – Defines connectivity.

• print_none (bool, default=False) – Print message if no structures found.

• wrap (str or None, default=None) – Boundary wrapping options: None, ‘sides’, ‘both’. If ‘sides’, connect structures that span the left/right edge. If ‘both’, connect structures that span the left/right edge and top/bottom edge.

Returns:

• perimeter (np.ndarray) – 1-D array, each element the perimeter of an individual structure.

• area (np.ndarray) – 1-D array, each element the area of an individual structure.

• height (np.ndarray) – 1-D array, each element the height of an individual structure.

• width (np.ndarray) – 1-D array, each element the width of an individual structure.

Notes

If x_sizes or y_sizes are not uniform, the width will be the sum of the average pixel widths of the pixels in the column and in the object. Similarly, the height will be the sum of the average pixel heights of the pixels in the row and in the object.

objscale.total_perimeter(array, x_sizes, y_sizes)

Given a binary array, calculate the total perimeter. Boundary conditions are assumed periodic. Only counts perimeter along edges between 1 and 0. (so that for different b.c. the array could be encased in any other value) Assumes periodic B.C.; for something else, padd inputs with 0s or nans.

Raises ValueError if x_sizes or y_sizes is nan where array is 1

objscale.total_number(array, structure=array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]))

Given a 2-D array with 0’s, nans, and 1’s, calculate number of objects of connected 1’s where connectivity is defined by structure

objscale.isolate_largest_structure(binary_array, structure=array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]))

objscale.remove_structures_touching_border_nan(array)

Input:

array: 2-D np.ndarray consisting of 0s, 1s, and np.nan. All values at the array edge should be np.nan

Output:

2-D np.ndarray consisting of 0s, 1s, and np.nan with any structure in contact with the nan values around the outer edge of the good data removed “in contact” is defined using adjacent connectivity, i.e. 4-connectivity

objscale.label_periodic_boundaries(labelled_array, wrap)

This functions makes labelled structures that span the edge have the same label.

Parameters: labelled_array (numpy.ndarray): A 2D array where each unique non-zero element represents a distinct label. Should be the output of scipy.ndimage.label(). wrap (str): A string that determines how the boundaries of the array should be wrapped.

It can take three values: ‘sides’, ‘both’, or any other string.

If ‘wrap’ is ‘sides’ or ‘both’:

The function sets the labels on the right boundary to be the same as those on the left boundary.

If ‘wrap’ is ‘both’:

The function also sets the labels on the top boundary to be the same as those on the bottom boundary.

If ‘wrap’ is neither ‘sides’ nor ‘both’:

The function raises a ValueError.

Returns: labelled_array (numpy.ndarray): The input array with its periodic boundaries labelled as per the ‘wrap’ parameter.

Raises: ValueError: If ‘wrap’ is neither ‘sides’ nor ‘both’.

objscale.remove_structure_holes(array, periodic=False)

Fills in all holes in all structures within array.

Set any value of 0 that is not connected to the largest connected structure of 0s (the background) to 1.

Assume the largest contiguous area of 0s is the “background”.

Input:

array: 2D np.ndarray with values either 0,1, or np.nan periodic: False, ‘both’, ‘sides’:

For structures lying along the boundary, if periodic=False, the behavior is as if the array was padded with 1’s, i.e. holes that are connected to the edge are filled.

Output: filled array

objscale.clear_border_adjacent(array, structure=array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]))

Input:

array: 2-D np.ndarray consisting of 0s and 1s

Output:

2-D np.ndarray consisting of 0s and 1s with border structures removed

Remove connected regions that touch the edge, using a connectivity determined by structure. Similar to skimage.segmentation.clear_border but structure can be changed.

Examples:

[[0,0,0,0], [[0,0,0,0], [[0,0,0,0], [0,1,1,0], [0,1,1,0], [0,1,0,0], [0,0,0,1], [0,0,1,1], [1,0,0,0], [0,0,0,0]] [0,0,0,0]] [0,0,0,0]]

so ex 1 and 3 would still have one cloud in output but ex 2 would have 0 for a structure of np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]).