util module¶

Utility functions for GUI and alignment.

Contains miscellaneous utility functions that help with GUI event handling, image handling, and certain file handling for alignment.

AUTHOR: Timothy Cote, ANL, Fall 2019.

class util.FileImage(uint8_data: Dict[KT, VT], flt_data: Dict[KT, VT], size: Tuple[int, int, int], path: str, float_array: Optional[np.ndarray] = None)[source]¶

Bases: util.FileObject

The Image Class contains data about an individual image. This data is encoded into bytes for the TK Canvas.

For more information on how to organize images the directory and load the data, as well as how to setup the .fls file please refer to the README.

path¶: String of the path name to file.

shortname¶: The shortened name of the file, only shows relative path not full path.

uint8_data¶: Dictionary of uint8 data of image.

flt_data¶: Dictionary of float data of image.

x_size¶: The x-size of the image.

y_size¶: The y-size of the image.

z_size¶: The z-size of the image.

lat_dims¶: The laterial dimensions of the image.

byte_data¶: The dictionary of the byte data of the image.

class util.FileObject(path: str)[source]¶

Bases: object

An object for holding the file data.

FileObjects hold information for .fls data or other files that may or may not be images. For more information on how to organize images the directory and load the data, as well as how to setup the .fls file please refer to the README or GUI manual.

path¶: String of the path name to file.

shortname¶: The shortened name of the file, only shows relative path not full path.

shorten_name() → None[source]¶: Creates a string of the path name with only the direct parent “image_dir” and the child of “image_dir”.

class util.Stack(uint8_data: Dict[KT, VT], flt_data: Dict[KT, VT], size: Tuple[int, int, int], path: str)[source]¶

Bases: util.FileImage

The Stack Class contains data about an image stack. This data is encoded into bytes for the TK Canvas. It is a subclass of the Image Class.

path¶: String of the full path of the stack.

shortname¶: The shortened name of the stack, only shows relative path not full path.

uint8_data¶: Dictionary of uint8 data of stack. Each key is associated with a slice of the stack.

flt_data¶: Dictionary of float data of stack. Each key is associated with a slice of the stack.

x_size¶: The x-size of the stack.

y_size¶: The y-size of the stack.

z_size¶: The z-size of the stack.

lat_dims¶: The lateral dimensions of the stack.

byte_data¶: Dictionary of the byte data of the stack.

stack_byte_data()[source]¶: Create the byte data for all the images in the stack.

class util.Struct[source]¶

Bases: object

The data structure responsible saving GUI info, image info, and reconstruction info. Attributes are built in PyLorentz ‘init’ functions.

This is the most useful class for the GUI and event handler. It contains information for each tab and keeps tracks of files, transformations, threads, subprocesses, etc.

util.add_vectors(mag_x: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a7cd0>, mag_y: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a7ed0>, color_np_array: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a7c50>, color: bool, hsv: bool, arrows: int, length: float, width: float, graph_size: Tuple[int, int], pad_info: Tuple[Any, Any], GUI_handle: bool = True, save: Optional[bool] = None) → Optional[bytes][source]¶

Add a vector plot for the magnetic saturation images to be shown in the GUI.

Parameters:	mag_x – The x-component of the magnetic induction. mag_y – The y-component of the magnetic induction. color_np_array – The colorized magnetic saturation array. color – The boolean value for a color image (True) or black & white image (False). hsv – The boolean value for hsv color image (True) or 4-fold color image (False). arrows – The number of arrows to place along the rows and cols of the image. length – The inverse length of the arrows. Inverted when passed to show_2D. width – The width of the arrows. graph_size – The (y, x) size of the GUI display graph. pad_info – The (axis, pad_size) datat. (None, 0, 1) for axes and int for pad_size. GUI_handle – The handle to pass to TIE_helper.show_2D() signalling whether to use GUI or matplotlib. This defaults to True for the GUI. save – The value to determine saving of the vectorized image.
Returns:	The byte image for the vectorized data.
Return type:	Optional

util.adjust_image(data: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a46d0>, transform: Tuple[Union[int, float], Union[int, float], Union[int, float], bool], image_size: Tuple[int, int], graph_size: Tuple[int, int]) → Tuple[bytes, PIL.Image.Image][source]¶

Apply transformations to an image given by some float data.

Apply rotations, translations, and/or flipping of image. Generally used for stack slices.

Parameters:	data – Float data of image1 in an ndarray. transform – Tuple of the rotation, x-translation, y-translation, and horizontal flip to apply to the image. image_size – The image size in (x, y) size. graph_size – The graph size in (x, y) size.
Returns:	The byte image for the data. rgba_image: The PIL rgba image of the data.
Return type:	return_img

util.apply_crop_to_stack(coords: Tuple[int, int, int, int], graph_size: Tuple[int, int], stack: util.Stack, i: int) → Tuple[bytes, PIL.Image.Image][source]¶

When an ROI mask is selected in the GUI, apply that ROI mask to a slices of image/stack.

Parameters:	coords – The tuple of the corners of the square ROI. graph_size – The tuple of the graph size (x, y). stack – Stack image object representing the loaded stack. i – The slice value of the stack to apply the crop to.
Returns:	The byte image for the data. rgba_masked_image: The PIL rgba image of the data.
Return type:	display_img

util.apply_rot_transl(data: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c614b210>, d_theta: Union[int, float] = 0, d_x: Union[int, float] = 0, d_y: Union[int, float] = 0, h_flip: Optional[bool] = None) → PIL.Image.Image[source]¶

Apply any rotations and translations to an image array. Takes an array of data and converts it to PIL

Images need to be converted to uint8 data for future processing and loading into the GUI window.

Parameters:	data – The ndarray of the image data. d_theta – The angle with which to rotate the image data. d_x – The x-translation to move the image data. d_y – The y-translation to move the image data. h_flip – Boolean value of whether to flip the image horizontally.
Returns:	The PIL rgba image of the image data.
Return type:	rgba_img

util.array_resize(array: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a6410>, new_size: Tuple[int, int]) → <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a6ed0>[source]¶

Resize numpy arrays with opencv.

Parameters:	array – Full path to the location of the image. new_size – The new size of array in (x, y) coords, generally size of display.
Returns:	The resized numpy array.
Return type:	resized_array

util.check_setup(datafolder: str, tfs_value: str, fls_value: str, fls_files: List[str], prefix: str = '') → Tuple[bool, Optional[str], Optional[str], Optional[List[str]], Optional[List[str]]][source]¶

Check to see all images filenames in .fls exist in datafolder.

Parameters:

datafolder – Datafolder path.
tfs_value – The through-focal series option. Options: Unflip/FLip, Single
fls_value – The FLS option. Options: One, Two
fls_files – A list of the FLS filenames.
prefix – The prefix to prepend for print statements in GUI.

Returns:

Will return images filenames and paths to those files: and their parent directories if all images pulled from FLS exist. - vals[0]: Corresponds to process success. - vals[1]: 1st parent directory path or None. - vals[2]: 2nd parent directory path or None. - vals[3]: 1st path list of ordered image filenames. - vals[4]: 2nd path list of ordered image filenames.

Return type:

vals

util.convert_float_unint8(float_array: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c5d8a450>, graph_size: Tuple[int, int], uint8_data: Optional[Dict[KT, VT]] = None, float_data: Optional[Dict[KT, VT]] = None, z: int = 0) → Tuple[Dict[int, <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c5e4f690>], Dict[int, <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c5e4f510>]][source]¶

Convert float image data to uint8 data, scaling for view in display.

Images need to be converted to uint8 data for future processing and loading into the GUI window.

Parameters:

float_array – Ndarray dtype float of a single slice of image data.
graph_size – The size of the graph in (x, y) coords.
uint8_data – The dictionary that stores the uint8 image data.
float_data – The dictionary that stores the scaled float image data.
z – The slice key for the uint8 and float dictionaries.

Returns:

The uint8 data dictionary with image/stack slice key: and value of uint8 dtype ndarray.
float_data: The float data dictionary with image/stack slice key: and value of float dtype ndarray.

Return type:

uint8_data

util.convert_to_bytes(img: PIL.Image.Image) → bytes[source]¶

Converts a PIL image to bytes.

The byte ‘ppm’ type is used to directly insert image data into the GUI window. Thus the PIL images need to be converted to this type.

Parameters:	img – The PIL representation of the image data.
Returns:	The byte representation of the image data.
Return type:	byte_img

util.create_mask(img: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c614e510>, mask_coords: Tuple[int, int, int, int], color: str) → <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c614e910>[source]¶

Create a mask image utilizing corner coordinates and a fill color.

Parameters:	img – The numpy array of the image data. mask_coords – The tuple of the corner coordinates of the mask. color – String denoting the color to fill in the background of the mask.
Returns:	The return mask image numpy array.
Return type:	img

util.draw_mask_points(winfo: util.Struct, graph: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c6129090>, current_tab: str, double_click: bool = False) → None[source]¶

Draw mask markers to appear on graph.

Parameters:	winfo – Struct object that holds all GUI information. graph – The selected PSG graph to draw mask points on. current_tab – String denoting the current tab the graph is on in the GUI double_click – Double-click value for terminating the mask drawing. Only necessary for bUnwarpJ masks.
Returns:	None

util.draw_square_mask(winfo: util.Struct, graph: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c6129590>) → None[source]¶

Create the square mask for the REC graph.

Parameters:	winfo – Struct object that holds all GUI information. graph – The selected PSG graph to draw mask points on.
Returns:	None

util.erase_marks(winfo: util.Struct, graph: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c61295d0>, current_tab: str, full_erase: bool = False) → None[source]¶

Erase markers off graph. Delete stored markers if full_erase enabled.

Parameters:	winfo – Struct object that holds all GUI information. graph – The selected PSG graph to draw mask points on. current_tab – String denoting the current tab the graph is on in the GUI full_erase – Value for deleting the figures from the graph.
Returns:	None

util.flatten_order_list(my_list: List[List[T]]) → List[T][source]¶

Flattens and orders a list of 3 lists into a single list.

Flattens and orders 2D list of lists of items:: [[b , a], [c, d], [e, f]]
into a 1D list of items:: [a, b, c, d, e, f]

Parameters:	my_list – A 2D list of list of items.
Returns:	A 1D flattened/ordered list of items.
Return type:	flat_list

util.grab_fls_data(fls1: str, fls2: str, tfs_value: str, fls_value: str, check_sift: bool) → Tuple[List[str], List[str]][source]¶

Grab image data from .fls file.

Given the FLS files for the flip/unflip/single images, return the image filenames depending on the fls_value and through-focal-series (tfs) value.

Examples

1 FLS, Unflip/FLip -> files1 : populated, files2 : populated
1 FLS, Single -> files1 : populated, files2 : empty
2 FLS, Unflip/FLip -> files1 : populated, files2 : populated

Parameters:

fls1 – Filename for 1st FLS file.
fls2 – Filename for 2nd FLS file.
tfs_value – Value for type of through-focal series, Single or Unflip/Flip.
fls_value – String of number of FLS files used.
check_sift – Option to check sift alignment.

Returns:

Tuple of image filenames for scenarios above

files1: List of image filenames

according to examples above.
files2: List of image filenames.

according to examples above.

util.join(strings: List[str], sep: str = '') → str[source]¶

Method joins strings with a specific separator.

Strings are joined with the separator and if the string contains double backslashes, it replaces them with a forward slash.

Parameters:	strings – A list of strings to join. sep – The character to separate the string joining.
Returns:	The concatenated string.
Return type:	final_string

util.load_image(img_path: str, graph_size: Tuple[int, int], key: str, stack: bool = False, prefix: str = '') → Tuple[Optional[Dict[int, <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c5e4f690>]], Optional[Dict[int, <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c5e4f510>]], Optional[Tuple[int, int, int]]][source]¶

Loads an image file.

Load an image file if it is a stack, dm3, dm4, or bitmap. As of now, Fiji doesn’t allow easy loading of dm4’s so be warned that alignment for dm4 files probably won’t work.

Parameters:

img_path – Full path to the location of the image.
graph_size – The size of the graph in (x, y) coords.
key – The key of the element clicked for loading an image.
stack – Boolean value if the image is a stack. Default is False.
prefix – The prefix value for the print statements to the GUI log. Default is True.

Returns:

Tuple containing three items:

uint8_data: The uint8 data dictionary with image/stack slice key and value of uint8 dtype ndarray or None if loading failed.
float_data: The float data dictionary with image/stack slice key and value of float dtype ndarray or None if loading failed.
size: The x, y, z size of the data or None if the loading failed.

Return type:

tuple

util.make_rgba(data: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a8c50>, adjust: bool = False, d_theta: Union[int, float] = 0, d_x: Union[int, float] = 0, d_y: Union[int, float] = 0, h_flip: Optional[bool] = None, color: Optional[bool] = None) → PIL.Image.Image[source]¶

Create an rgba image from numpy ndarray data of an image.

Rgba images need to be created from uint8 data so that they can be converted to bytes for display in the graph. Additionally a colormap may need to be applied along with alpha values to show overlaying images.

Parameters:	data – The ndarray of the image data. Can be float or uint8. adjust – Boolean value whether transformations need to be applied to the image. d_theta – The angle with which to rotate the image data. d_x – The x-translation to move the image data. d_y – The y-translation to move the image data. h_flip – Boolean value of whether to flip the image horizontally. color – Boolean of whether or not a color-map should be applied to the image. True if overlaying images, otherwise False.
Returns:	The PIL rgba image of the image data.
Return type:	rgba_img

util.pull_image_files(fls_file: str, check_align: bool = False) → List[List[str]][source]¶

Use .fls file to return ordered images for alignment.

Initially it will read in .fls data, pull the number of files from the first line, and then locate the in-focus image. Then it separates the overfocus and underfocus images.

If the check alignment is set, the returned images are the infocus image, and the nearest under-focused/over-focused on either side of the infocus image. Otherwise all image files are returned. The files are ordered from

[ [smallest underfocus, … , largest underfocus] [infocus] [smallest overfocus, … , largest overfocus] ]

Parameters:	fls_file – The filename for the fls file. check_align – Option for full alignment or parameter test.
Returns:	2D list of under/in/over-focus images.
Return type:	filenames

util.read_fls(path1: Optional[str], path2: Optional[str], fls_files: List[str], tfs_value: str, fls_value: str, check_sift: bool = False) → Tuple[List[str], List[str]][source]¶

Read image files from .fls files and returns their paths.

The images are read from the FLS files and the files are returned depending on the through-focal series value and the fls value. Once image filenames are pulled from the FLS file, they are joined to the paths (directories) the images are stored in. Those resulting full path names are returned in files1 and files2.

Parameters:

path1 – The first unflip/flip/single path/directory. Optional
path2 – The first unflip/flip/single path/directory. Optional
fls_files – A list of the FLS filenames.
tfs_value – The through-focal series option. Options: Unflip/FLip, Single
fls_value – The FLS option. Options: One, Two
check_sift – Option for checking SIFT alignment.

Returns:

A tuple of the lists of image paths corresponding: to path1 and path2. - files1: List of full image paths. - files2: List of full image paths or empty list.

Return type:

(files1, files2)

util.represents_float(s: str) → bool[source]¶

Returns value evaluating if a string is a float.

Parameters:	s – A string to check if it wil be a float.
Returns:	True if it converts to float, False otherwise.

util.represents_int_above_0(s: str) → bool[source]¶

Returns value evaluating if a string is an integer > 0.

Parameters:	s – A string to check if it wil be a float.
Returns:	True if it converts to float, False otherwise.

util.slice_im(image: <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a3810>, slice_size: Tuple[int, int, int, int]) → <sphinx.ext.autodoc.importer._MockObject object at 0x7f37c58a3910>[source]¶

Slice an image

Parameters:	image – ndarray of image data. slice_size – The bounds of the image slice in (y_start, x_start, y_end, x_end) coords.
Returns:	An ndarray of the sliced image. Can be 3 or 2 dimensions
Return type:	new_image

util.vis_1_im(image: util.FileImage, layer: int = 0) → bytes[source]¶

Visualize one image in the GUI canvas. Takes a FileImage Object and converts uint8 data into byte data the Tk canvas can use.

Parameters:

image – The image object that holds data and path info about the image.
layer – Default is 0 if viewing single image. If viewing a stack, must choose layer slice.

Returns:

A byte representation of the image data: to represent in TK canvas.

Return type:

return_img