API

This is automatically generated API documentation.

class Quant4D

Bases: matlab.apps.AppBase

Constructor Summary

Quant4D(varargin)

Create UIFigure and components

Property Summary

debug

Debug mode. false to disable; else enables timers/tracers

Type:

bool

data

Imported dataset, may be moved to GPU

Type:

array

memfile

Memory map file of the imported dataset

Type:

memmapfile

sys_constants

Constants for system info that set at app startup

Type:

struct

tmp_variables

Temporary global variables, e.g. for progress bar and import etc., should never be cleared

Type:

struct

dataset_parameters

Parameters of the current imported dataset; should be constants (except for data type conversion)

Type:

struct

common_parameters

Common parameters, should be cleared when a dataset is unloaded

Type:

struct

previous_values

Previous values, should be cleared when a dataset is unloaded

Type:

struct

figures

All figure windows excluding the Main UI

Type:

struct

image_axes

All image axes

Type:

struct

images

Arrays of raw data for the images/masks to be plotted/saved

Type:

struct

image_displays

Image objects with modified contrast for display, e.g. by app.image_displays.(id) = imagesc(...)

Type:

struct

annotations

Image annotations on axes or uiaxes, excluding annotations on figure and uifigure

Type:

struct

masks

Real and Diffraction space masks applied to data

Type:

struct

ui_groups

Different groups of figures/axes/images; assigned just once at startup in create_other_windows()

Type:

struct

center

Central beam absolute pixel coordinates

Type:

[int int]

center_rel

Relative position of center. [0 0] (when “Absolute” position) or center (when “Relative”)

Type:

[int int]

diff_scale

Diffraction pixel scale. 1 (when in pixel) or mrad/px (when in mrad)

Type:

double

real_scale

Real-space pixel scale. 1 (when in pixel) or nm/px (when in nm). Not implemented yet

Type:

double

variable_nodes

uitree nodes to display variables for users

Type:

struct

byte_size

Method Summary

enable_virtual_aperture_UI(app)

Function to update UI enable/disable states

Parameters:

app (Quant4D)

Returns:

None

limit_virtual_aperture_UI(app)

Function to update UIs Limits/Labels for coordinate options

Parameters:

app (Quant4D)

Returns:

None

draw_virtual_aperture_annotation(app)

Function to draw virtual aperture annotations

Parameters:

app (Quant4D)

Returns:

None

move_virtual_aperture(app, source, event)

Live update function for virtual aperture annotations

Parameters:

• app (Quant4D)

• source (images.roi.Circle | images.roi.Point) – virtual aperture annotations

• event (event.EventData) – ROIMoved, MovingROI

Returns:

None

auto_align(app)

Auto-align transmitted beam

Parameters:

app (Quant4D)

Returns:

None

cross_align(app)

Function to align the transmitted beam to the intersection of two lines

Parameters:

app (Quant4D)

Returns:

None

move_transmitted_beam(app, source, event)

Function to sync UIs/ROIs depending on the central beam location

Parameters:

• app (Quant4D)

• source (images.roi.Circle) – transmitted beam annotation

• event (event.EventData) – ROIMoved, MovingROI

Returns:

None

get_import_info(app)

Function to update current dataset import parameters

Parameters:

app (Quant4D)

Returns:

notes (str) – collection of import parameters for display to the user

export_data(app, event)

Function to export data as .h5 or .raw

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

err (int | bool) – error code, default: false, -1 if an error has occurred

update_export_range(app, event)

Save images based on the user selections on the Save/Export UI

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

• pixels_dist (int) – binning distance in diffraction space

• pixels_start ([int int]) – starting pixel index in diffraction space (default: 1, unless cropping)

• n_pixels ([int int]) – number of pixels to be exported in diffraction space

• pixels_end ([int int]) – final pixel index in diffraction space (default: n_pixels, unless cropping)

• frames_dist (int) – sub-sampling distance in real space

• frames_start ([int int]) – starting frame index in real space (default: 1, unless sub-sampling)

• n_frames ([int int]) – number of frames to be exported in real space

move_export_annotation(app, ~, event)

Update Export Data boundaries as user change the Export Data Annotations

Parameters:

• app (Quant4D)

• source (images.roi.Rectangle) – real-space export annotations, ignored

• event (event.EventData)

Returns:

None

update_prefix(app, event)

Update image name prefix on the Save/Export UI

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

save_images(app)

Save images based on the user selections on the Save/Export UI

Parameters:

app (Quant4D)

Returns:

None

check_GPU_memory(app, n_pixels, n_frames)

Check the amount of GPU memory on the available GPU(s), compare with the estimated memory from check_memory() and warn if incompatible.

Parameters:

• app (Quant4D)

• n_pixels ([int int]) – number of pixels in Diffraction space

• n_frames ([int int]) – number of probe positions in Real space

Returns:

gpu_note (str) – report on memory usage for the user

check_memory(app, event, n_pixels, n_frames, bytesize)

Check the amount of system memory available, estimate the required memory, compare and warn if incompatible.

Parameters:

• app (Quant4D)

• n_pixels ([int int]) – number of pixels in Diffraction space

• n_frames ([int int]) – number of probe positions in Real space

• bytesize (int) – size of the data type in bytes

Returns:

memory_note (str) – report on memory usage for the user

guess_frames_from_dim3(app, dim3)

Guess number of real space frames in X and Y when a dataset is read in as 3D, rather than 4D.

Parameters:

• app (Quant4D)

• dim3 (int) – Total number of real-space frames in a 4D dataset that has been read in as 3D.

Returns:

None

get_dims_from_name(app, filename)

Guess dataset size from filename if it contains certain regular expressions. Where A, B, C, D are integers. (A,B) = # pixels in Diffraction space. (C,D) = # probe positions in Real space.

Parameters:

• app (Quant4D)

• filename (str) – ‘prefixAxBxCxDbar’ or ‘scan_xC_yD.raw’

Returns:

None

guess_frames_from_size(app)

Make an initial guess at the dataset dimensions assuming a roughly square field of view (ImportFramesX≈ImportFramesY). Sets the estimated values in their respective numeric fields in the Import UI

Parameters:

app (Quant4D)

Returns:

None

import_data(app, event)

Function to prepare for dataset import, read the file, and switch the UI to Alignment mode

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

read_file(app, event)

Function to read the dataset from file

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

err (int | bool) – error code, default: false, -1 if an error has occurred

prepare_data(app, event)

Initialize GUI/Image/app.common_parameters defaults based on the specifics of the imported dataset.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

gather_import_options(app, preview)

Collects all import parameters from the Import UI into a structure, d.

Parameters:

• app (Quant4D)

• preview (bool) – true = Preview mode, false = Import mode

Returns:

d (struct) – dataset parameters from Import UI

switch_on_off(~, status)

Wrapper function for MATLAB’s OnOffSwitchState()

Parameters:

• app (Quant4D) – ignored

• status (int | bool) – 0 or false = off; 1 or true = on

Returns:

output (str) – “on”, “off”

set_external_source(app, event, object, varargin)

Set properties of objects that are not source if it is a changing event

Parameters:

• app (Quant4D)

• event (event.EventData)

• object – UI component, annotation, list of objects with a common property

• varargin – property/value pair(s) (i.e. “Value”, 1)

Returns:

None

rotation_matrix(~, degrees)

Rotation matrix, for degree input

Parameters:

• app (Quant4D) – ignored

• degrees (double) – angle in degrees

Returns:

R (array) – 2D rotation matrix

is_static_event(~, event)

Function to test whether an event is NOT “MovingROI” or “ValueChanging”; return true for [] etc. This helps to reduce computational load, especially on image refresh.

Parameters:

• app (Quant4D) – ignored

• event (event.EventData)

Returns:

status (bool) – true if event is static; else false

h5_datasets(~, file)

Return all h5 Datasets with some key info

Parameters:

• app (Quant4D) – ignored

• file (str) – file path from app.ImportFilePath.Value

Returns:

h (struct) – h5 Dataset information, including Name, Dataspace, Datatype, offset, size, byte_ordering, and type.

debug_toc(app, event, notes, tic_start)

Function to debug and time functions

Parameters:

• app (Quant4D)

• event (event.EventData)

• notes (str) – debugging information

• tic_start (uint64) – stopwatch timer start

Returns:

None

flash_background(~, target)

Function to flash the background of UIs, which have BackgroundColor. This process will pause the whole program during flashing

Parameters:

• app (Quant4D) – ignored

• target – UI component

Returns:

None

change_icon_background(app, source)

state button background color change to highlight when it is/isn’t enabled

Parameters:

• app (Quant4D)

• source (matlab.ui.control.Button) – UI State Button

Returns:

None

get_GPU(app)

Function to get all available GPUs

Parameters:

app (Quant4D)

Returns:

None

get_memory(app)

Function to Check usable system memory and make sure the file will fit

Parameters:

app (Quant4D)

Returns:

None

range_import_export(app, event)

Function to calculate import/export range for pixels/frames

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

• notes (str) – Diffraction or Real space-dependent notes on import range and binning

• binning (int) – binning distance in Diffraction, sub-sampling distance in Real

• xy_start ([int int]) – starting pixels or frames in x,y

• n_points ([int int]) – number of pixels or frames in x,y

• xy_end ([int int]) – ending pixels or frames in x,y

import_export_progress(app, process, n_frames, frame_size)

Function for progress bar of data import/export, with a timer() to update its progress per second

Parameters:

• app (Quant4D)

• process (str) – “Import”, “Export”

• n_frames (int) – total number of Real space frames (i.e. rx*ry)

• frame_size (int) – frame size in bytes

Returns:

• wait_bar (matlab.ui.Figure) – waitbar to display progress

• tmr (timer) – 1 Hz timer to update progress bar information (i.e. import rate)

import_mask(app, space)

Function to import mask for given (diffraction/real) space

Parameters:

• app (Quant4D)

• space (str) – “Real”, “Diffraction”

Returns:

mask (array) – array imported by user to mask Real or Diffraction space

plot_all_patterns(app, event)

Wrapper function for (re)plotting all images

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

plot_image(app, event, id)

Generic function for plotting an image on a given axis with brightness/contrast/gamma values

Parameters:

• app (Quant4D)

• event (event.EventData)

• id (str) – image identification string

Returns:

None

is_different_to_previous(app, name, value)

Function to check whether the given name value is changed compared to the previous value, and store the new value

Parameters:

• app (Quant4D)

• name (str) – field name in app.previous_values

• value – value of app.previous_values.(name) to be tested for update

Returns:

status (bool) – Whether app.previous_values.(name) ~= value

to_update_image(app, event)

Function to determine whether to update images. Return true if any: 1) app.CalculationPolicy.Value is 2 (active update) OR 2) app.CalculationPolicy.Value is 1 (reduced) and not when changing OR 3) is a manual update (from update buttons or detector mode change)

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

to_update (bool) – Whether or not image(s) should be updated at the time of calling based on app.CalculationPolicy and current user interactions

mock_UI_callbacks(app, source, value)

Function to mock UI callbacks.

Parameters:

• app (Quant4D)

• source – UI elements

• value (str) – additional information to be passed along to further function calls

Returns:

None

notification_dialog(app, icon, msg, title_name, option)

Wrapper for notification dialog; use sprintf() before calling this function to process “n” in message

Parameters:

• app (Quant4D)

• icon (str) – “quest”, “list”, “help”, “warn”, “error”, “none”, “”

• msg (str) – dialog message

• title_name (str) – dialog title

• option – dialog selection options

Returns:

selection (str | int) – user response

progress_dialog(app, msg, title_name, interruptible)

Wrapper for waitbar

Parameters:

• app (Quant4D)

• msg (str) – dialog message

• title_name (str) – dialog title

• interruptible (bool) – can the dialog be interrupted

Returns:

wait_bar (matlab.ui.Figure)

unload_data(app, swap_data)

Function to unload data and clean all images; swap_data keeps all previous parameters and simply swaps out data

Parameters:

• app (Quant4D)

• swap_data (bool) – swap dataset (true), unload all data (false)

Returns:

None

enable_windows(app, state)

Function to enable/disable windows/UI; disable is only for notification/progress bar/busy background, etc.

Parameters:

• app (Quant4D)

• state (bool) – enable (true) or disable (false) all windows

Returns:

None

create_other_windows(app)

Function to create other UI windows and Image figures

Parameters:

app (Quant4D)

Returns:

None

check_NaN(app, image, preview)

Function to check NaN/Inf in data/image

Parameters:

• app (Quant4D)

• image (array) – image to be checked for the presence of NaNs

• preview (bool)

Returns:

selection

get_screen_info(app)

Function to check the size of various screen attributes.

Parameters:

app (Quant4D)

Returns:

None

get_sys_constants(app)

Function to get/set system constants

Parameters:

app (Quant4D)

Returns:

None

save_vector_field(app)

Function to save vector field images.

Parameters:

app (Quant4D)

Returns:

None

clear_detectors(app)

Function to delete plotted detectors if they exist.

Parameters:

app (Quant4D)

Returns:

None

draw_real_ROI(app, event, roi_type)

Function to draw Real-space ROI of various shapes on real space image(s)

Parameters:

• app (Quant4D)

• event (event.EventData)

• roi_type (str) – “full”, “point”, “ellipse”, “rectangle”, “poly”, “file”

Returns:

None

move_real_ROI(app, source, event)

Function to move Real-space ROIs on real space image(s)

Parameters:

• app (Quant4D)

• source (images.roi.Rectangle | images.roi.Point | images.roi.Ellipse | images.roi.Polygon) – Real-space ROIs

• event (event.EventData)

Returns:

None

get_fields(app, tree_node, variable_struct)

Function to recursively get all fields on a TreeNode so the user can view important internal variables and values

Parameters:

• app (Quant4D)

• tree_node (TreeNode) – matlab.ui.container.TreeNode

• variable_struct (struct) – structure containing variables or parameters

Returns:

None

preview_frame(app, probe_position)

Function to import a single detector frame for previewing

Parameters:

• app (Quant4D)

• probe_position ([int int]) – probe position to be previewed

Returns:

• frame (array) – detector frame, cropped and binned as set by the user

• err (int) – fseek status for error handling

startup_function(app, debug)

Code that executes after component creation

Parameters:

• app (Quant4D)

• debug (bool) – Enable (true), disable (false) timings for debugging

Returns:

None

import_callbacks(app, event)

Function called when the user clicks ImportData, CancelImport, or ShowImportWindow (on the main UI).

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

import_select_file(app, event)

Function called when the user clicks Select or updates the file path on the Import UI (ImportFileSelect and ImportFilePath, respectively)

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

import_file_type(app, event)

Function called when the user selects a new file type category (FileTypeButtonGroup) or selects a new SubDataset

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

import_box_input(app, event)

Function called when the user interacts with the Import UI

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

save_callbacks(app, event)

Function called when the user interacts with the Save/Export UI

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

export_callbacks(app, event)

Function called when the user interacts with the Save/Export UI

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

axis_direction_callbacks(app, event)

Function called when the user modifies the axis orientation in diffraction or real space

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

display_callbacks(app, event)

Function to update all aspects of the image display, including brightness, contrast, gamma, colormap, histogram, vector field, and mask opacity.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

realspace_ROI_callbacks(app, event)

Function to update the real space ROI based on the selected type and location from the main UI, as well as to update the diffraction pattern accordingly.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

detector_mode_callbacks(app, event)

Function called when the mode changes, either by the user or programmatically (i.e. Preview -> Alignment, or between any of the available imaging modes).

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

detector_coordinates_callbacks(app, event)

Function called when the users selects a different coordinate system (“Polar” or “Cartesian”), positioning system (“Relative” or “Absolute”), or unit (“mrad” or “pixels”); as well as if the user changes the annular integration step size.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

dataset_options_callbacks(app, event)

Function called when the user request a swap of data byte ordering (i.e. big endian -> little endian), real space x,y (i.e. [kx, ky, rx, ry] -> [kx, ky, ry, rx]), or diffraction space x,y (i.e. [kx, ky, rx, ry] -> [ky, kx, rx, ry]).

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

preview_callbacks(app, event)

Function called when the user request to preview a diffraction pattern before importing.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

transmitted_beam_callbacks(app, event)

Function called when the user interacts with UI elements on the Alignment tab of the main UI (i.e. convergence angle, transmitted beam x/y/radius, AutoAlign, etc.)

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

annular_detector_callbacks(app, event)

Function called when the user interacts with UI elements on the Annular/Round, Segmented (DPC), and Center of Mass tabs of the main UI (i.e. inner/outer annular angles, segmented detector controls, scan direction alignment, etc.)

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

virtual_aperture_callbacks(app, event)

Function called to during all virtual aperture interactions, including entering the Virtual Aperture mode, drawing virtual aperture annotations, and updating UI elements.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

custom_detector_callbacks(app, event)

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

first_moment(app, event)

Function called when the user applies a filter to iDPC/dDPC or iCoM/dCoM images, or saves a vector field image

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

show_window(app, event)

Function called when the user presses any of the Show*Window buttons

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

resize_window(app, event)

Function called when the user sets the size of one or more windows from the Window size and orientation panel in the Windows tab of the Settings UI.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

update_images(app, event)

Function called when the user changes the CalculationPolicy (Active, Reduced or Passive) or explicitly refreshes the images (can also be called programmatically).

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

reset_Quant4D(app, event)

Function to revert all UI properties to their initial state and unload all data from RAM and the GPU, if used.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

enable_all_UI(app, event)

Context menu item to re-enable all UI elements. Mostly used for debugging.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

test1(app, event)

User editable function for debugging.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

test2(app, event)

User editable function for debugging.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

close_function(app, event)

Function called to ensure that all figure windows and any progress dialogs are closed when the app exits.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

variable_viewer(app, event)

Function used to display or hide the variable viewer treenode in the Settings UI.

Parameters:

• app (Quant4D)

• event (event.EventData)

Returns:

None

createComponents(app)

Get the file path for locating images

delete(app)

Delete UIFigure when app is deleted