PEARL Procedures rev-distro-2.1.1-1-gf419e92-dirty Igor procedures for the analysis of PEARL data

Namespaces | Functions
pearl-area-display.ipf File Reference
ARPES package

visualization tools for 2D and 3D data. More...

`#include "pearl-compat"`

Go to the source code of this file.

## Namespaces
| PearlAreaDisplay
| instant visualization of angle scan and manipulator position.

## Functions
static string | graphname_from_dfref (dfref df, string prefix)
| compose a valid and unique graph name from a data folder reference More...
string | ad_display (wave image)
| open a new graph window with a 2D image. More...
string | ad_display_histogram (wave image)
| display the histogram of a 2D image. More...
string | ad_display_profiles (wave image, string filter=defaultValue)
| open a new profiles graph window. More...
wave | ad_add_overlay (wave image, string rgba=defaultValue)
| add an overlay on top of the displayed image More...
variable | ad_update_profiles (wave image)
| update a profiles graph with new data. More...
variable | ad_profiles_cursor_mode (wave image, variable mode)
| switch cursors on a profiles graph More...
variable | ad_profiles_set_cursor (wave image, string cursorname, variable xa, variable ya, variable pscale=defaultValue)
| move a cursor to the specified position in a profiles graph. More...
variable | ad_profiles_crosshairs (wave image, variable clear=defaultValue)
| draw permanent crosshairs in a profiles graph. More...
static wave | get_source_image (wave view)
| find the source image wave corresponding to the given view. More...
static dfr | make_view_folder (wave source)
| create a view data folder. More...
static dfr | get_view_folder (wave source)
| find the view data folder corresponding to the given source. More...
static wave | get_view_image (wave source)
| find the view image wave corresponding to the given source. More...
static variable | bp_reset_cursors (WMButtonAction *ba)
static variable | svp_smoothing (WMSetVariableAction *sva)
static variable | pmp_export (WMPopupAction *pa)
variable | ad_profiles_hook (WMWinHookStruct *s)
| hook function for user events in the profiles window. More...
variable | ad_calc_cursor_profiles (wave image)
| calculate profiles, statistics, and histogram of a cross-hair delimited region of interest. More...
variable | ad_calc_profiles (wave image, variable pa, variable qa, variable pb, variable qb)
| calculate profiles, statistics, and histogram of a rectangular region of interest. More...
variable | ad_export_profile (wave view_image, variable dim, variable trace=defaultValue, variable show=defaultValue, variable overwrite=defaultValue)
| export a profile from a profiles graph to the source data folder. More...
static variable | set_trace_colors (string graphname)
variable | ad_calc_histogram (wave image)
| calculate the histogram. More...
variable | ad_default_image_filter (wave image, string options)
| abstract filter function for image display. More...
variable | ad_box_filter (wave image, string options)
| boxcar smoothing filter. More...
variable | ad_transpose_filter (wave image, string options)
| transpose image filter. More...
string | ad_display_brick (wave data)
| open a new "gizmo" window with three-dimensional data. More...
variable | ad_brick_slicer (wave data)
| open a slicer panel for 3D data. More...
string | ad_display_slice (wave data)
| display three-dimensional data by 2D slice. More...
static variable | update_slice_info ()
| update controls with data scale limits. More...
variable | ad_gizmo_set_plane (wave brick, variable dim, variable value)
| set the position of a slicing plane of a 3D brick in a Gizmo window. More...
variable | ad_profiles_set_slice (wave brick, variable dim, variable value)
| set the position of the slicing plane of a 3D brick in a profiles window. More...
static variable | slp_slice_position (WMSliderAction *sa)
| set slice coordinate (slider procedure). More...
static variable | svp_slice_position (WMSetVariableAction *sva)
| set slice coordinate (button procedure). More...
static variable | bp_move_slice (WMButtonAction *ba)
| move slice (button procedure). More...
static variable | bp_extract_slice (WMButtonAction *ba)
| export a slice (button procedure). More...
static variable | bp_move_slice_center (wave brick, variable dim, string posvariable)
| move the slice to the center of the dimension (button procedure). More...
static variable | ad_slicer_move_bg (WMBackgroundStruct *s)
| move a slice by one step (background task). More...
variable | ad_slicer_init_bg ()
| initialize the slice animation background task. More...
variable | ad_slicer_start_bg (wave brick, variable dimension, string posvariable, variable delta)
| start the animation. More...
variable | ad_slicer_stop_bg (string posvariable)
| stop the animation. More...

## Detailed Description

visualization tools for 2D and 3D data.

these tools were initially developed for monitoring output from EPICS area detector software. they are, however, useful for any kind of intensity versus x,y(,z) data.

# 2D data

TO DO...

# 3D data

Definition in file pearl-area-display.ipf.

## Function Documentation

## ◆ ad_add_overlay()

wave ad_add_overlay | ( | wave | image,
|  | string | rgba = `defaultValue`
| ) |  |

add an overlay on top of the displayed image

the function creates the overlay wave and returns it as function result. the name of the wave is "view_overlay" and is created in the same folder as the "view_image" wave.

Parameters

  image | image wave that identifies the profiles window.

Returns
  overlay overlay wave. same dimensions and scales as image, but unsigned binary. pixels that are 0 are overlaid with semi-transparent color. other pixels should be 64 (igor's mask convention).

Definition at line 329 of file pearl-area-display.ipf.

## ◆ ad_box_filter()

variable ad_box_filter | ( | wave | image,
|  | string | options
| ) |  |

boxcar smoothing filter.

filters the image in X and Y directions using Igor's Smooth operation.

Parameters

  image | image to be filtered: original data and filter result.
  options | smoothing factors in `key1=value1;key2=value2;...` format. SmoothingX SmoothingY

Definition at line 1103 of file pearl-area-display.ipf.

## ◆ ad_brick_slicer()

variable ad_brick_slicer | ( | wave | data | ) |

open a slicer panel for 3D data.

if a panel exists, bring it to the front.

Parameters

  data | three-dimensional wave.

Definition at line 1256 of file pearl-area-display.ipf.

## ◆ ad_calc_cursor_profiles()

variable ad_calc_cursor_profiles | ( | wave | image | ) |

calculate profiles, statistics, and histogram of a cross-hair delimited region of interest.

Parameters

  image | wave which contains the image data from the detector.

the function expects further objects as created by ad_display_profiles() in the same data folder as the image wave. the most recent profiles graph of the image must exist, and the cursors A and B must be set on the image.

Definition at line 785 of file pearl-area-display.ipf.

## ◆ ad_calc_histogram()

variable ad_calc_histogram | ( | wave | image | ) |

calculate the histogram.

Parameters

  image | wave which contains the image data from the detector. the function expects further objects as created by ad_display_histogram() in the same data folder as the image wave.

Definition at line 1066 of file pearl-area-display.ipf.

## ◆ ad_calc_profiles()

variable ad_calc_profiles | ( | wave | image,
|  | variable | pa,
|  | variable | qa,
|  | variable | pb,
|  | variable | qb
| ) |  |

calculate profiles, statistics, and histogram of a rectangular region of interest.

the region of interest a rectangle spanned by the two points A and B. pixels at these coordinates are included.

Parameters

  image | wave which contains the image data.
  pa | first point coordinate of A.
  qa | second point coordinate of A.
  pb | first point coordinate of B.
  qb | second point coordinate of B.

the function expects further objects as created by ad_display_profiles() in the same data folder as the image wave.

this function does not require that the graph exists as long as the data folder is complete.

Definition at line 832 of file pearl-area-display.ipf.

## ◆ ad_default_image_filter()

variable ad_default_image_filter | ( | wave | image,
|  | string | options
| ) |  |

abstract filter function for image display.

this is a function prototype for filtering two-dimensional data for preview. to write your own filter, define a new function which has the same signature.

Parameters

  image | image to be filtered: original data and filter result.
  options | filter options in `key1=value1;key2=value2;...` format.

Returns
  the result must be written to the incoming image wave.

Definition at line 1089 of file pearl-area-display.ipf.

## ◆ ad_display()

string ad_display | ( | wave | image | ) |

open a new graph window with a 2D image.

this is essentially `display; appendimage`. the graph is directly linked to the image wave. it is, thus, updated automatically.

Parameters

  image | wave which contains the image data.

Returns
  (string) name of the graph window

Definition at line 85 of file pearl-area-display.ipf.

## ◆ ad_display_brick()

string ad_display_brick | ( | wave | data | ) |

open a new "gizmo" window with three-dimensional data.

Parameters

  data | three-dimensional wave.

Returns
  name of the gizmo window.

Definition at line 1141 of file pearl-area-display.ipf.

## ◆ ad_display_histogram()

string ad_display_histogram | ( | wave | image | ) |

display the histogram of a 2D image.

the function will create additional objects in the same data folder as the image. this objects are displayed in the graph and are updated by calling ad_calc_profiles(). see the code.

Parameters

  image | wave which contains the image data from the detector.

Returns
  (string) name of the graph window

Definition at line 115 of file pearl-area-display.ipf.

## ◆ ad_display_profiles()

string ad_display_profiles | ( | wave | image,
|  | string | filter = `defaultValue`
| ) |  |

open a new profiles graph window.

opens an extended graph window with profiles for the specified image. the function copies/creates all necessary data structures in a subfolder of the one which contains the image wave. the data folder name is derived from the image wave name by prefixing with "view_". there can be at most one profiles window of each image wave. the original wave must not be renamed while the graph window is used. to update the graph after modifying the original wave, call ad_update_profiles().

Parameters

  image | wave which contains the image data.
  filter | name of a filter function which maps the original data to the displayed data. the function must have the same parameters as ad_default_image_filter(). default: boxcar average (ad_box_filter()) using parameters view_filter_smoothing_x and _y.

Returns
  name of the graph window

Definition at line 166 of file pearl-area-display.ipf.

## ◆ ad_display_slice()

string ad_display_slice | ( | wave | data | ) |

display three-dimensional data by 2D slice.

to select the slice data to display, call ad_profiles_set_slice(), or open a ad_brick_slicer() panel. do not modify the content of the created view_ data folder.

Parameters

  data | three-dimensional wave.

Returns
  name of the graph window.

Definition at line 1404 of file pearl-area-display.ipf.

## ◆ ad_export_profile()

variable ad_export_profile | ( | wave | view_image,
|  | variable | dim,
|  | variable | trace = `defaultValue`,
|  | variable | show = `defaultValue`,
|  | variable | overwrite = `defaultValue`
| ) |  |

export a profile from a profiles graph to the source data folder.

this function does not require that the show exists as long as the view data folder is complete.

Parameters

  view_image | wave which contains the view image (image wave on display in profiles window). the function expects further objects as created by ad_display_profiles() in the same data folder as the view_image wave.
  dim | dimension index (0 = x, 1 = y).
  trace | select profile trace: 0 = cursor A 1 = cursor B 2 = average between cursors (default)
  show | display mode: 0 = do not show (default) 1 = display in new graph, or append to existing graph 2 = collate: common graph for all profiles of a dimension. rename graph manually to detach it from future additions.
  overwrite | overwrite mode: 0 = create new wave (default). wave name may get a suffix to be unique. 1 = overwrite existing wave

Definition at line 934 of file pearl-area-display.ipf.

## ◆ ad_gizmo_set_plane()

variable ad_gizmo_set_plane | ( | wave | brick,
|  | variable | dim,
|  | variable | value
| ) |  |

set the position of a slicing plane of a 3D brick in a Gizmo window.

Parameters

  brick | original data wave.
  dim | dimension index: 0, 1, or 2.
  value | new coordinate of the slicing plane (axis scaling).

Returns
  0 if successful, non-zero otherwise

Definition at line 1481 of file pearl-area-display.ipf.

## ◆ ad_profiles_crosshairs()

variable ad_profiles_crosshairs | ( | wave | image,
|  | variable | clear = `defaultValue`
| ) |  |

draw permanent crosshairs in a profiles graph.

adds dash-dotted horizontal and vertical crosshairs to a profiles graph. for each active cursor A and/or B, a pair of lines crossing at the cursor position is added. existing crosshairs are moved to the current cursor positions. optionally, existing crosshairs are removed from the graph.

in contrast to the cursors, these crosshairs will be exported and printed with the graph. they are drawn using Igor's DrawLine operation. all lines drawn by this function are part of the "crosshairs" draw group.

Parameters

  image | image displayed in the graph. this is the original image, not the one in the view data folder.
  clear | 0 (default) = add/update lines. 1 = remove lines.

Definition at line 540 of file pearl-area-display.ipf.

## ◆ ad_profiles_cursor_mode()

variable ad_profiles_cursor_mode | ( | wave | image,
|  | variable | mode
| ) |  |

switch cursors on a profiles graph

the standard cursors allow to select the profiles to display in the profiles panes. additional cursors are shown in the profiles panes.

in the background selection mode, additional cursors allow the user to select the limits of the background and peak integration regions. the meaning of the cursors depends on the particular processing function.

Parameters

  mode | cursor mode. 0 (default) standard profile selection. cursors C-F on profile panes. 1 background selection. cursors A-F on image.
  image | image displayed in the graph. this is the original image, not the one in the view data folder.

Definition at line 427 of file pearl-area-display.ipf.

## ◆ ad_profiles_hook()

variable ad_profiles_hook | ( | WMWinHookStruct * | s | ) |

hook function for user events in the profiles window.

Definition at line 745 of file pearl-area-display.ipf.

## ◆ ad_profiles_set_cursor()

variable ad_profiles_set_cursor | ( | wave | image,
|  | string | cursorname,
|  | variable | xa,
|  | variable | ya,
|  | variable | pscale = `defaultValue`
| ) |  |

move a cursor to the specified position in a profiles graph.

this function can only set cursors in the image part of the profiles graph.

Parameters

  image | image displayed in the graph. this is the original image, not the one in the view data folder.
  cursorname | name of the cursor, e.g. "A" or "B". other cursors are allowed but need to be activated separately.
  xa | x-coordinate to move the cursor to. the position is coerced to the image scale. +/-inf is allowed.
  ya | y-coordinate to move the cursor to. the position is coerced to the image scale. +/-inf is allowed.
  pscale | scaling of the position argument 0 (default) wave scaling 1 point scaling

Definition at line 488 of file pearl-area-display.ipf.

## ◆ ad_profiles_set_slice()

variable ad_profiles_set_slice | ( | wave | brick,
|  | variable | dim,
|  | variable | value
| ) |  |

set the position of the slicing plane of a 3D brick in a profiles window.

Parameters

  brick | original data wave.
  dim | dimension index: 0, 1, or 2.
  value | new coordinate of the slicing plane (axis scaling).

Returns
  0 if successful, non-zero otherwise

Definition at line 1517 of file pearl-area-display.ipf.

## ◆ ad_slicer_init_bg()

variable ad_slicer_init_bg | ( |  | ) |

initialize the slice animation background task.

Definition at line 1776 of file pearl-area-display.ipf.

## ◆ ad_slicer_move_bg()

static variable ad_slicer_move_bg | ( | WMBackgroundStruct * | s | ) |
| static

move a slice by one step (background task).

Definition at line 1737 of file pearl-area-display.ipf.

## ◆ ad_slicer_start_bg()

variable ad_slicer_start_bg | ( | wave | brick,
|  | variable | dimension,
|  | string | posvariable,
|  | variable | delta
| ) |  |

start the animation.

Parameters

  brick | 3D data wave
  dimension | dimension to animate, 0, 1, or 2.
  posvariable | full path to the global position variable.
  delta | step increment, should be +/- dimdelta.

Definition at line 1800 of file pearl-area-display.ipf.

## ◆ ad_slicer_stop_bg()

variable ad_slicer_stop_bg | ( | string | posvariable | ) |

stop the animation.

Parameters

  posvariable | full path to the global position variable.

Definition at line 1842 of file pearl-area-display.ipf.

## ◆ ad_transpose_filter()

variable ad_transpose_filter | ( | wave | image,
|  | string | options
| ) |  |

transpose image filter.

transposes the image.

Parameters

  image | image to be transposed: original data and result.
  options | not used. should be empty.

Definition at line 1125 of file pearl-area-display.ipf.

## ◆ ad_update_profiles()

variable ad_update_profiles | ( | wave | image | ) |

update a profiles graph with new data.

Parameters

  image | wave which contains the image data. must be the same (by data folder and name) wave used with ad_display_profiles().

Definition at line 375 of file pearl-area-display.ipf.

## ◆ bp_extract_slice()

static variable bp_extract_slice | ( | WMButtonAction * | ba | ) |
| static

export a slice (button procedure).

extract a slice and saves it in a separate wave.

Definition at line 1671 of file pearl-area-display.ipf.

## ◆ bp_move_slice()

static variable bp_move_slice | ( | WMButtonAction * | ba | ) |
| static

move slice (button procedure).

Definition at line 1622 of file pearl-area-display.ipf.

## ◆ bp_move_slice_center()

static variable bp_move_slice_center | ( | wave | brick,
|  | variable | dim,
|  | string | posvariable
| ) |  |
| static

move the slice to the center of the dimension (button procedure).

Definition at line 1725 of file pearl-area-display.ipf.

## ◆ bp_reset_cursors()

static variable bp_reset_cursors | ( | WMButtonAction * | ba | ) |
| static

Definition at line 677 of file pearl-area-display.ipf.

## ◆ get_source_image()

static wave get_source_image | ( | wave | view | ) |
| static

find the source image wave corresponding to the given view.

Returns
  wave reference of the original data wave. the reference may be invalid if the source wave cannot be found.

Definition at line 606 of file pearl-area-display.ipf.

## ◆ get_view_folder()

static dfr get_view_folder | ( | wave | source | ) |
| static

find the view data folder corresponding to the given source.

the result data folder reference may be invalid if no view is currently open. use the built-in DataFolderRefStatus function to check for validity.

Parameters

  source | wave which contains the image data. must be the same (by data folder and name) wave used with ad_display_profiles().

Definition at line 644 of file pearl-area-display.ipf.

## ◆ get_view_image()

static wave get_view_image | ( | wave | source | ) |
| static

find the view image wave corresponding to the given source.

Parameters

  source | wave which contains the image data. must be the same (by data folder and name) wave used with ad_display_profiles().

Definition at line 667 of file pearl-area-display.ipf.

## ◆ graphname_from_dfref()

static string graphname_from_dfref | ( | dfref | df,
|  | string | prefix
| ) |  |
| static

compose a valid and unique graph name from a data folder reference

Definition at line 57 of file pearl-area-display.ipf.

## ◆ make_view_folder()

static dfr make_view_folder | ( | wave | source | ) |
| static

create a view data folder.

Definition at line 620 of file pearl-area-display.ipf.

## ◆ pmp_export()

static variable pmp_export | ( | WMPopupAction * | pa | ) |
| static

Definition at line 721 of file pearl-area-display.ipf.

## ◆ set_trace_colors()

static variable set_trace_colors | ( | string | graphname | ) |
| static

Definition at line 1045 of file pearl-area-display.ipf.

## ◆ slp_slice_position()

static variable slp_slice_position | ( | WMSliderAction * | sa | ) |
| static

set slice coordinate (slider procedure).

Definition at line 1558 of file pearl-area-display.ipf.

## ◆ svp_slice_position()

static variable svp_slice_position | ( | WMSetVariableAction * | sva | ) |
| static

set slice coordinate (button procedure).

Definition at line 1590 of file pearl-area-display.ipf.

## ◆ svp_smoothing()

static variable svp_smoothing | ( | WMSetVariableAction * | sva | ) |
| static

Definition at line 696 of file pearl-area-display.ipf.

## ◆ update_slice_info()

static variable update_slice_info | ( |  | ) |
| static

update controls with data scale limits.

current folder must be slicer info

Definition at line 1445 of file pearl-area-display.ipf.