processing and holographic mapping of angle scanned XPD data. More...

#include "pearl-vector-operations"
#include "pearl-polar-coordinates"
#include <New Polar Graphs>

Namespaces
	PearlAnglescanProcess
	processing and holographic mapping of angle scanned XPD data.

Functions
variable	strip_delete_frames (wave strip, variable qlo, variable qhi, wave theta, wave tilt, wave phi)
	delete a contiguous range of frames from a strip. More...

variable	normalize_strip_x (wave strip, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
	divide the strip by the average X distribution. More...

variable	normalize_strip_phi (wave strip, wave theta, wave phi, variable theta_offset=defaultValue, variable theta_range=defaultValue, variable check=defaultValue)
	divide the strip by a sine function in phi (wobble correction). More...

variable	normalize_strip_theta (wave strip, wave theta, variable theta_offset=defaultValue, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
	divide the strip by the average polar distribution. More...

variable	normalize_strip_thetaphi (wave strip, wave theta, wave phi, variable theta_offset=defaultValue, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
	divide the strip by a smooth polar-azimuthal distribution. More...

variable	normalize_strip_2d (wave strip, wave theta, variable theta_offset=defaultValue, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
	divide the strip by a two-dimensional normalization function. More...

variable	crop_strip (wave strip, variable xlo, variable xhi)
	crop a strip at the sides. More...

variable	pizza_service (wave data, string nickname, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue, variable xpdplot=defaultValue)
	create a pizza plot from a measured (energy-integrated) data strip More...

variable	pizza_service_2 (wave data, string nickname, wave m_theta, wave m_tilt, wave m_phi, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue, variable xpdplot=defaultValue)
	create a pizza plot from a measured (energy-integrated) data strip More...

variable	show_analyser_line (variable theta, variable tilt, variable phi, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable xpdplot=defaultValue)
	calculate and display the line seen by the analyser for a specific emission angle More...

variable	convert_angles_ttpd2polar (wave theta, wave tilt, wave phi, wave data, wave polar, wave azi)
	convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates. More...

variable	convert_angles_ttpa2polar (wave theta, wave tilt, wave phi, wave analyser, wave polar, wave azi)
	convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates. More...

static variable	line_average (wave source, wave dest)

static variable	calc_nth (variable Theta_st, variable Theta_in, variable th, variable Phi_ran, variable Phi_ref, string Holomode)
	calculate the number of phis for a given theta More...

static variable	calc_phi_step (variable Theta_in, variable th, variable Theta_st, variable Phi_ran, variable Phi_ref, string Holomode)
	calculate delta-phi for a given theta More...

static variable	Calc_The_step (variable th, variable Theta_st, string Holomode)
	calculate delta-theta for a given theta More...

static variable	CalcN_Theta (string HoloMode, variable Theta_in, variable Theta_ran, variable Theta_st)
	calculate the number of thetas for a pattern More...

variable	make_hemi_grid (variable npol, string nickname, variable xpdplot=defaultValue)
	create a hemispherical, constant solid angle grid More...

string	get_hemi_nickname (wave w)
	finds the nick name given any hemi wave More...

string	get_hemi_prefix (wave w)
	finds the prefix given any hemi wave More...

dfr	find_hemi_data (string nickname, string prefix, string intwave)
	finds the folder, prefix and name of holo waves given their nick name More...

variable	clear_hemi_grid (string nickname)
	clear a hemispherical scan grid More...

variable	duplicate_hemi_scan (string source_nickname, dfref dest_folder, string dest_nickname, variable xpdplot=defaultValue)
	duplicate a hemispherical scan dataset. More...

variable	rotate_hemi_scan (string nickname, variable angle)
	azimuthally rotate a hemispherical scan dataset. More...

string	display_hemi_scan (string nickname, variable projection=defaultValue, variable graphtype=defaultValue, variable do_ticks=defaultValue, variable do_grids=defaultValue, string graphname=defaultValue)
	display a plot of a hemispherical angle scan. More...

static string	display_polar_graph (string graphname, variable angle_offset=defaultValue, variable do_ticks=defaultValue)
	displays an empty polar graph More...

static string	draw_hemi_axes (string graphname, variable do_grids=defaultValue)
	draw polar and azimuthal grids in an existing polar graph. More...

variable	draw_diffraction_cone (string graphname, string groupname, variable theta_axis, variable theta_inner, variable phi)
	draw the circle of a diffraction cone in a stereographic polar graph. More...

string	display_scanlines (string nickname, variable alpha_lo, variable alpha_hi, wave m_theta, wave m_tilt, wave m_phi, variable folding=defaultValue, variable projection=defaultValue)
	display a polar graph with lines indicating the angles covered by an angle scan. More...

threadsafe variable	calc_graph_radius (variable polar, variable projection=defaultValue)
	calculate the projected polar angle More...

threadsafe variable	calc_graph_polar (variable x, variable y, variable projection=defaultValue)
	calculate polar angle from Cartesian coordinate More...

threadsafe variable	calc_graph_azi (variable x, variable y, variable projection=defaultValue, variable zeroAngle=defaultValue)
	calculate azimuthal angle from Cartesian coordinate More...

static variable	update_polar_info (string graphname)
	update the angles info based on cursors A and B of a given polar graph window More...

static variable	polar_graph_hook (WMWinHookStruct *s)
	polar graph window hook More...

variable	set_polar_graph_cursor (string nickname, string cursorname, variable polar_angle, variable azim_angle, string graphname=defaultValue)

variable	hemi_add_anglescan (string nickname, wave values, wave polar, wave azi, wave weights=defaultValue)
	add an arbitrary angle scan to a hemispherical scan grid. More...

variable	hemi_add_aziscan (string nickname, wave values, variable polar, wave azi, wave weights=defaultValue)
	add an azimuthal scan to a hemispherical scan grid. More...

variable	interpolate_hemi_scan (string nickname)
	interpolate a hemispherical scan onto a rectangular grid More...

variable	quick_pizza_image (wave data, string nickname, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue)
	map angle scan data onto a rectangular grid in stereographic projection More...

variable	save_hemi_scan (string nickname, string pathname, string filename)
	save a hemispherical scan to an Igor text file More...

variable	load_hemi_scan (string nickname, string pathname, string filename)
	load a hemispherical scan from an Igor text file More...

variable	import_tpi_scan (string nickname, wave theta, wave phi, wave intensity, variable folding=defaultValue, variable npolar=defaultValue, variable nograph=defaultValue, variable xpdplot=defaultValue)
	import a hemispherical scan from theta-phi-intensity waves and display it More...

variable	trim_hemi_scan (string nickname, variable theta_max)
	trim a hemispherical scan at grazing angle More...

wave	hemi_polar_cut (string nickname, variable azim)
	extract a polar cut from a hemispherical scan. More...

wave	hemi_azi_cut (string nickname, variable pol)
	extract an azimuthal cut from a hemispherical scan More...

static variable	check_contrast (wave values, variable pcmin, variable pcmax, variable vmin, variable vmax)

variable	set_contrast (variable pcmin, variable pcmax, string graphname=defaultValue, string colortable=defaultValue)
	set the pseudocolor contrast by percentile. More...

Variables
const variable	kProjDist = 0

const variable	kProjStereo = 1

const variable	kProjArea = 2

const variable	kProjGnom = 3

const variable	kProjOrtho = 4

static const variable	kProjScaleDist = 2

static const variable	kProjScaleStereo = 2

static const variable	kProjScaleArea = 2

static const variable	kProjScaleGnom = 0.06744519021

static const variable	kProjScaleOrtho = 2

Detailed Description

processing and holographic mapping of angle scanned XPD data.

the functions in this file map angle scanned data measured at PEARL onto a hemispherical angle grid which is compatible with XPDplot. the resulting data are in a canonical polar coordinate system (normal emission <=> polar angle = 0, azimuthal axis right-handed) which is anchored in the sample surface. the orientation of polar graphs (phi = 0 at 3 o'clock) created by this procedure corresponds to a top view of the sample surface at normal emission, and the handle of the sample plate pointing to the left (phi = 180). this is the canonical orientation of a spherical coordinate system where phi = 0 corresponds to the positive part of the x axis.

Note: the orientation of the sample coordinate system has changed in version 1.6. the change was necessary for compatibility with other data analysis software and calculation programs.; data imported with version 1.5 and earlier, must be offset by 180 deg in phi to be compatible with the new version. data imported and displayed by the same code version will give the same picture but with different azimuthal axis. the new graph functions shows a warning if they are applied to code imported with earlier versions.

the measurement geometry is hard-coded but may be parametrized in the future. the theta rotation axis is perpendicular to the scattering plane. the angle dispersive axis of the analyser is parallel to the theta rotation axis. the tilt rotation axis is in the scattering plane. it rotates with theta. at normal emission it is perpendicular to the axis of the lens stack of the analyser. the phi rotation axis corresponds to the surface normal of the sample. it rotates with theta and with tilt. at normal emission it is parallel to the axis of the lens stack of the analyser.

coordinate transformations: (to be revised - v1.6)

*      theta_sample = theta_manipulator - theta_offset
*      phi_sample = phi_manipulator - phi_offset
*

valid for theta_manipulator = normal emission only: (to be revised - v1.6)

*      theta_sample = | -(tilt_manipulator - tilt_offset) |
*      phi_sample = 270 if tilt_manipulator - tilt_offset > 0
*      phi_sample = 90 if tilt_manipulator - tilt_offset < 0
*

Author: matthias muntwiler, matth.nosp@m.ias..nosp@m.muntw.nosp@m.iler.nosp@m.@psi..nosp@m.ch

Copyright: 2013-17 Paul Scherrer Institut
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Version: 1.8 canonical orientation of spherical coordinate system.

Definition in file pearl-anglescan-process.ipf.

Function Documentation

threadsafe variable calc_graph_azi	(	variable	x,
		variable	y,
		variable	projection = `defaultValue`,
		variable	zeroAngle = `defaultValue`
	)

calculate azimuthal angle from Cartesian coordinate

Parameters

x,y	projected Cartesian coordinate
projection	mapping function from polar to cartesian coordinates. all supported projections are azimuthal, they have no effect on the azimuthal coordinate. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic
zeroAngle	zeroAngleWhere parameter of polar graphs 0 (default) zero is at the 3 o'clock position 180 zero is at the 9 o'clock position other values not tested

Returns: polar angle in degrees

Definition at line 2203 of file pearl-anglescan-process.ipf.

threadsafe variable calc_graph_polar	(	variable	x,
		variable	y,
		variable	projection = `defaultValue`
	)

calculate polar angle from Cartesian coordinate

this is the reverse mapping to calc_graph_radius()

Parameters

x,y	projected Cartesian coordinate
projection	mapping function from polar to cartesian coordinates. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic

Returns: polar angle in degrees

Definition at line 2150 of file pearl-anglescan-process.ipf.

threadsafe variable calc_graph_radius	(	variable	polar,
		variable	projection = `defaultValue`
	)

calculate the projected polar angle

Parameters

polar	polar angle in degrees
projection	mapping function from polar to cartesian coordinates. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic

Returns: projected radius. the radius is scaled such that grazing emission maps to 2.

Definition at line 2105 of file pearl-anglescan-process.ipf.

static variable calc_nth	(	variable	Theta_st,
		variable	Theta_in,
		variable	th,
		variable	Phi_ran,
		variable	Phi_ref,
		string	Holomode
	)

static

calculate the number of phis for a given theta

adapted from XPDplot 8.03

Definition at line 1018 of file pearl-anglescan-process.ipf.

static variable calc_phi_step	(	variable	Theta_in,
		variable	th,
		variable	Theta_st,
		variable	Phi_ran,
		variable	Phi_ref,
		string	Holomode
	)

static

calculate delta-phi for a given theta

adapted from XPDplot 8.03

Definition at line 1047 of file pearl-anglescan-process.ipf.

static variable Calc_The_step	(	variable	th,
		variable	Theta_st,
		string	Holomode
	)

static

calculate delta-theta for a given theta

adapted from XPDplot 8.03

Definition at line 1091 of file pearl-anglescan-process.ipf.

static variable CalcN_Theta	(	string	HoloMode,
		variable	Theta_in,
		variable	Theta_ran,
		variable	Theta_st
	)

static

calculate the number of thetas for a pattern

adapted from XPDplot 8.03

Definition at line 1122 of file pearl-anglescan-process.ipf.

static variable check_contrast	(	wave	values,
		variable	pcmin,
		variable	pcmax,
		variable *	vmin,
		variable *	vmax
	)

static

Definition at line 3001 of file pearl-anglescan-process.ipf.

variable clear_hemi_grid ( string nickname )

clear a hemispherical scan grid

values and weights waves are set to zero. the intensity wave is set to NaN.

Parameters

nickname folder name or name prefix of holo waves. may be empty.

Definition at line 1401 of file pearl-anglescan-process.ipf.

variable convert_angles_ttpa2polar	(	wave	theta,
		wave	tilt,
		wave	phi,
		wave	analyser,
		wave	polar,
		wave	azi
	)

convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates.

the angles are in the manipulator coordinate system.

Parameters

[in]	theta	offset-corrected theta angle, normal emission = 0, grazing emission = 90. one dimensional wave.
[in]	tilt	offset-corrected tilt angle, normal emission = 0 same dimension size and scale as theta
[in]	phi	phi angle, range -360 < phi < +360 offset correction is optional as long as the angles lie in the accepted range. same dimension size and scale as theta
[in]	analyser	analyser angle scale corresponding to the slices scale of Scienta. one dimensional wave. this values are constant regardless of manipulator angle.
[out]	polar	wave to receive the polar coordinates.
[out]	azi	wave to receive the azimuthal coordinates.

for the output parameters polar and azi, you need to pass in existing numeric waves. dimension size does not matter, the waves are redimensioned by the function so that they have the same dimensions as the intensity data set. X dimension = analyser scale, Y dimension = manipulator scan.

Definition at line 957 of file pearl-anglescan-process.ipf.

variable convert_angles_ttpd2polar	(	wave	theta,
		wave	tilt,
		wave	phi,
		wave	data,
		wave	polar,
		wave	azi
	)

convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates.

similar to convert_angles_ttpa2polar() but reads the analyser angles from the X scale of data

Definition at line 918 of file pearl-anglescan-process.ipf.

variable crop_strip	(	wave	strip,
		variable	xlo,
		variable	xhi
	)

crop a strip at the sides.

the strip is cropped in place, data outside the region of interest is lost.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
[in]	xlo	lowest analyser angle to keep (will be rounded to nearest existing point)
[in]	xhi	highest analyser angle to keep (will be rounded to nearest existing point)

Remarks: cropping should be done after smoothing and normalization operations to reduce artefacts.

Definition at line 578 of file pearl-anglescan-process.ipf.

string display_hemi_scan	(	string	nickname,
		variable	projection = `defaultValue`,
		variable	graphtype = `defaultValue`,
		variable	do_ticks = `defaultValue`,
		variable	do_grids = `defaultValue`,
		string	graphname = `defaultValue`
	)

display a plot of a hemispherical angle scan.

the scan data must exist in the current data folder. azimuth = 0 should be at 9 o'clock. then the orientation is the same as the sample at normal emission and phi = 0, the handle of the sample plate pointing to the left.

Parameters

nickname	name prefix of holo waves. may be empty.
projection	mapping function from polar to cartesian coordinates. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic
graphtype	type of graph 1 (pol, az) trace in Igor "New Polar" (default). 2 XPDplot (reserved, not implemented). 3 matrix in Igor "New Polar". the matrix wave is a 2D wave with X and Y scaling corresponding to the selected projection. matrix waves can be created by interpolate_hemi_scan(). note: the pol and az waves are required as well.
do_ticks	select which ticks to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 major azimuthal 2 minor azimuthal S
do_grids	select which grids to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 radius at 0 and 90 degree azimuth 2 circle at 30 and 60 degree polar
graphname	name of graph window. default: nickname if empty, a default name is assigned. if a window with this name is existing, the function brings it to the front, and does nothing else.

Returns: the name of the graph window

Definition at line 1601 of file pearl-anglescan-process.ipf.

static string display_polar_graph	(	string	graphname,
		variable	angle_offset = `defaultValue`,
		variable	do_ticks = `defaultValue`
	)

static

displays an empty polar graph

the graph is drawn using Wavemetrics "New Polar Graphs.ipf".

initially the graph is empty. hemispherical scans are displayed by adding a trace that coveres the whole plot area, and setting the trace color to a function of the intensity. traces are added by calling WMPolarAppendTrace.

the following items of the graph > packages menu might be useful:

modify polar graph
color table control
show polar cursors
polar graph legend

parameters can be changed programmatically as shown in the code of this function. after programmatic parameter changes, call WMPolarAxesRedrawGraphNow(graphname).

Parameters

graphname	requested name of new graph window. if empty, a default name is assigned. if a window with this name is existing, the function brings it to the front, and does nothing else.
angle_offset	azimuth (on screen) where angle 0 is plotted (zeroAngleWhere parameter of polar graphs). starting with version 1.6, the default is 0. for hemi grids created with earlier versions, it should be set to 180 for correct orientation.
do_ticks	select which ticks to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 major azimuthal 2 minor azimuthal

Returns: the name of the graph window.

Version: 1.7 interface change: the trace drawing code is moved to display_hemi_scan, so that this function can be reused by other graph types, e.g. display_scanlines.

Definition at line 1739 of file pearl-anglescan-process.ipf.

string display_scanlines	(	string	nickname,
		variable	alpha_lo,
		variable	alpha_hi,
		wave	m_theta,
		wave	m_tilt,
		wave	m_phi,
		variable	folding = `defaultValue`,
		variable	projection = `defaultValue`
	)

display a polar graph with lines indicating the angles covered by an angle scan.

Parameters

nickname	nick name for output data. this will become the name of a child folder containing the output.
alpha_lo	low limit of the analyser angle.
alpha_hi	high limit of the analyser angle.
m_theta	manipulator theta angles, 0 = normal emission. size = dimsize(data, 1)
m_tilt	manipulator tilt angles, 0 = normal emission. size = dimsize(data, 1)
m_phi	manipulator phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
folding	rotational averaging, default = 1
projection	mapping function from polar to cartesian coordinates. see calc_graph_radius().

Remarks: this function is extremely slow.

Definition at line 1990 of file pearl-anglescan-process.ipf.

variable draw_diffraction_cone	(	string	graphname,
		string	groupname,
		variable	theta_axis,
		variable	theta_inner,
		variable	phi
	)

draw the circle of a diffraction cone in a stereographic polar graph.

the diffraction cone consists of a circle marking the diffraction ring, and a dot marking the axis. the cone is drawn as a group of draw objects on the UserFront layer. the objects can be edited interactively.

Parameters

graphname	name of graph window (not implemented yet).
groupname	name of a drawing group. if the group exists (from a previous cone) it is replaced. if the group doesn't exist, a new one is created.
theta_axis	polar angle of the cone axis in degrees.
theta_inner	polar angle of the innermost point of the circle in degrees.
phi	azimuthal angle of the cone axis in degrees.

Warning: EXPERIMENTAL! this function is under development. the interface and behaviour of this function may change significantly in future versions.

Definition at line 1926 of file pearl-anglescan-process.ipf.

static string draw_hemi_axes	(	string	graphname,
		variable	do_grids = `defaultValue`
	)

static

draw polar and azimuthal grids in an existing polar graph.

the function adds the following draw objects to a polar graph:

concentric circles at polar angles 0, 30, and 60 degrees with labels.
radial axes at 0 and 90 degree azimuth.

the objects are added to the ProgFront drawing layer and will appear in front of the data trace. in interactive drawing mode, you can select the active drawing layer by clicking the tree icon while holding the Alt key.

the graph must have been created by display_polar_graph(). the function reads the projection mode from the window user data "projection".

Parameters

graphname	name of graph window.
do_grids	select which optional grids to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 radius at 0 and 90 degree azimuth 2 circle at 30 and 60 degree polar

Warning: EXPERIMENTAL! this function is under development. the interface and behaviour of this function may change significantly in future versions.

Definition at line 1854 of file pearl-anglescan-process.ipf.

variable duplicate_hemi_scan	(	string	source_nickname,
		dfref	dest_folder,
		string	dest_nickname,
		variable	xpdplot = `defaultValue`
	)

duplicate a hemispherical scan dataset.

this function works only for hemi scans created by make_hemi_grid() (or compatible functions). the angle grid is recreated rather than copied point-by-point. the new dataset is independent from the original one.

if the version of the source dataset is pre 1.6, it is converted to version 1.6.

Parameters

source_nickname	name prefix for waves. source data must be in current data folder.
dest_folder	destination folder. folder must exist.
dest_nickname	name prefix for destination waves. must be unique in the current data folder. otherwise existing waves get overwritten. may be empty.
xpdplot	XPDplot compatibility 0 (default) create the data structures required by this module 1 create additional waves and notebook required by XPDplot

Definition at line 1448 of file pearl-anglescan-process.ipf.

dfr find_hemi_data	(	string	nickname,
		string *	prefix,
		string *	intwave
	)

finds the folder, prefix and name of holo waves given their nick name

the function looks for holo waves in the following order:

if nickname is empty, check for prefix-less waves in current folder.
if nickname is the name of a child folder in the current data folder, clear the (prefix-less) waves in the child folder.
nickname is prefix of waves in current folder.
nickname is prefix of waves in root folder.

Parameters

[in]	nickname	folder name or name prefix of holo waves. may be empty.
[out]	prefix	name prefix of waves. may be empty.
[out]	intwave	name of intensity/values wave

Returns: reference of the data folder which contains the waves

Definition at line 1367 of file pearl-anglescan-process.ipf.

string get_hemi_nickname ( wave w )

finds the nick name given any hemi wave

the nick name is either the name of a child folder in the current data folder (PEARL specification), or a prefix of the hemi wave names (XPDplot specification).

Returns: the nick name

Definition at line 1311 of file pearl-anglescan-process.ipf.

string get_hemi_prefix ( wave w )

finds the prefix given any hemi wave

the prefix is the part of the wave name before the first underscore. the prefix is used by XPDplot where it is identical to the nick name. the prefix is empty in the PEARL specification.

Returns: the prefix

Definition at line 1336 of file pearl-anglescan-process.ipf.

variable hemi_add_anglescan	(	string	nickname,
		wave	values,
		wave	polar,
		wave	azi,
		wave	weights = `defaultValue`
	)

add an arbitrary angle scan to a hemispherical scan grid.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. the function determines the bin size at the given polar angle, and adds all data points which fall into a bin. a point which lies exactly on the upper boundary falls into the next bin. this function does not clear previous values before adding new data. values are added to the _tot wave, weights to the _wt wave. the intensity (_i) wave is calculated as _tot / _wt.

Definition at line 2348 of file pearl-anglescan-process.ipf.

variable hemi_add_aziscan	(	string	nickname,
		wave	values,
		variable	polar,
		wave	azi,
		wave	weights = `defaultValue`
	)

add an azimuthal scan to a hemispherical scan grid.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. the function determines the bin size at the given polar angle, and calculates the mean values of the data points which fall into a bin. a point which lies exactly on the upper boundary falls into the next bin.

Definition at line 2418 of file pearl-anglescan-process.ipf.

wave hemi_azi_cut	(	string	nickname,
		variable	pol
	)

extract an azimuthal cut from a hemispherical scan

the function extracts all azimuthal angles that are present for the given polar angle.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. correct ordering is required.

Parameters

nickname	name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
pol	polar angle in degrees

Returns: reference of the created wave. the wave has the same name as the intensity wave of the dataset with the suffix "_azi" and the azimuthal angle rounded to integer. it is created in the same datafolder as the original data.

Definition at line 2948 of file pearl-anglescan-process.ipf.

wave hemi_polar_cut	(	string	nickname,
		variable	azim
	)

extract a polar cut from a hemispherical scan.

for each polar angle, the function first extracts all azimuthal angles. the intensity is then interpolated between the nearest neighbours of the given azimuth.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. correct ordering is required.

Parameters

nickname	name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
azim	azimuthal angle in degrees

Returns: reference of the created wave. the wave has the same name as the intensity wave of the dataset with the suffix "_azi" and the azimuthal angle rounded to integer. it is created in the same datafolder as the original data.

Definition at line 2862 of file pearl-anglescan-process.ipf.

variable import_tpi_scan	(	string	nickname,
		wave	theta,
		wave	phi,
		wave	intensity,
		variable	folding = `defaultValue`,
		variable	npolar = `defaultValue`,
		variable	nograph = `defaultValue`,
		variable	xpdplot = `defaultValue`
	)

import a hemispherical scan from theta-phi-intensity waves and display it

in the tpi format, the hemi scan data is represented by a triple of flat one-dimensional waves corresponding to the polar angle (theta), azimuthal angle (phi) and intensity. no specific sort order is required.

Parameters

nickname	nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
theta	theta angles, 0 = normal emission.
phi	phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
intensity	intensity wave, see requirements above.
npolar	number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
folding	rotational averaging. example: 3 = average to 3-fold symmetry. default = 1.
nograph	display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
xpdplot	XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Definition at line 2774 of file pearl-anglescan-process.ipf.

variable interpolate_hemi_scan ( string nickname )

interpolate a hemispherical scan onto a rectangular grid

the interpolated data is written to a new two-dimensional wave "matrix". the wave has a fixed size of 181 x 181 points optimized for 1-degree polar steps.

the function requires the ster_x and ster_y waves that are created by display_hemi_scan, and thus implicitly uses the same projection.

missing values (nan) are interpolated. this works well only if the missing values are reasonable sparse. the function also applies a gaussian filter to smooth the image. empty rings at high polar angles map are preserved.

to display the result call display_hemi_scan() with graphtype=3.

Definition at line 2524 of file pearl-anglescan-process.ipf.

static variable line_average	(	wave	source,
		wave	dest
	)

static

Definition at line 1000 of file pearl-anglescan-process.ipf.

variable load_hemi_scan	(	string	nickname,
		string	pathname,
		string	filename
	)

load a hemispherical scan from an Igor text file

Todo:: function not implemented

Definition at line 2725 of file pearl-anglescan-process.ipf.

variable make_hemi_grid	(	variable	npol,
		string	nickname,
		variable	xpdplot = `defaultValue`
	)

create a hemispherical, constant solid angle grid

all necessary waves are created in the current data folder with step size 90 / (npol - 1)

adapted from XPDplot 8.03

Parameters

npol	number of polar angles, determines polar and azimuthal step size. recommended 91 for 1-degree steps.
nickname	name prefix for waves. nick name must be unique in the current data folder. otherwise existing waves get overwritten. may be empty.
xpdplot	XPDplot compatibility 0 (default) create the data structures required by this module 1 create additional waves and notebook required by XPDplot

Definition at line 1160 of file pearl-anglescan-process.ipf.

variable normalize_strip_2d	(	wave	strip,
		wave	theta,
		variable	theta_offset = `defaultValue`,
		variable	smooth_method = `defaultValue`,
		variable	smooth_factor = `defaultValue`,
		variable	check = `defaultValue`
	)

divide the strip by a two-dimensional normalization function.

Warning: experimental. this function is under development.

Parameters

check

enable output of intermediate results

0 (default) don't create additional waves
1 create check waves in the current folder
2 calculate check waves only, do not modify strip

Returns

if check waves are enabled, the following waves are created (overwritten if existing):

check_dist average theta distribution
check_smoo smoothed distribution used to normalize the strip

Definition at line 518 of file pearl-anglescan-process.ipf.

variable normalize_strip_phi	(	wave	strip,
		wave	theta,
		wave	phi,
		variable	theta_offset = `defaultValue`,
		variable	theta_range = `defaultValue`,
		variable	check = `defaultValue`
	)

divide the strip by a sine function in phi (wobble correction).

the sine function is a curve fit to the intensity integrated over detector angle with a period of 360.

this normalization may be useful if the intensity varies with a 360 periodicity in the azimuthal angle, e.g. due to misalignment of the surface normal and the azimuthal rotation axis of the manipulator (wobble). note, however, that this function does not correct other effects of wobble such as angle shifts.

the strip is normalized in place, previous data is overwritten.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
[in]	theta	polar manipulator angle.
[in]	phi	azimuthal manipulator angle, arbitrary offset.
[in]	theta_offset	theta value corresponding to normal emission (default 0).
[in]	theta_range	maximum (offset corrected) theta to consider in the sine fit (default 10).
	check	enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns

if check waves are enabled, the following waves are created (overwritten if existing):

check_dist average theta distribution
check_smoo smoothed distribution used to normalize the strip

Definition at line 270 of file pearl-anglescan-process.ipf.

variable normalize_strip_theta	(	wave	strip,
		wave	theta,
		variable	theta_offset = `defaultValue`,
		variable	smooth_method = `defaultValue`,
		variable	smooth_factor = `defaultValue`,
		variable	check = `defaultValue`
	)

divide the strip by the average polar distribution.

this is a simple way to remove the polar angle dependence. the strip is normalized in place, previous data is overwritten.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
[in]	theta	polar manipulator angle, 0 = normal emission, 90 = grazing emission
[in]	theta_offset
[in]	smooth_method	smoothing method 0 none 1 binomial (requires monotonic theta), see Igor's Smooth operation 2 boxcar (requires monotonic theta), see Igor's Smooth operation 3 polynomial fit per slice 4 (default) Loess, see Igor's Loess operation caution: binomial and boxcar smoothing are not aware of theta. this may give unpredictable results if theta is non-monotonic.
[in]	smooth_factor	smoothing parameter, depends on smooth_method binomial/boxcar: see Igor's Smooth operation loess: see Igor's Loess operation, 0 <= smooth_factor <= 1, default 0.5 polynomial fit: polynomial degree, 1 = linear (default), 2 = quadratic
	check	enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns

if check waves are enabled, the following waves are created (overwritten if existing):

check_dist average theta distribution
check_smoo smoothed distribution used to normalize the strip

Definition at line 353 of file pearl-anglescan-process.ipf.

variable normalize_strip_thetaphi	(	wave	strip,
		wave	theta,
		wave	phi,
		variable	theta_offset = `defaultValue`,
		variable	smooth_method = `defaultValue`,
		variable	smooth_factor = `defaultValue`,
		variable	check = `defaultValue`
	)

divide the strip by a smooth polar-azimuthal distribution.

this is a simple way to remove the polar angle dependence. in contrast to normalize_strip_theta this function also removes a smooth variation over azimuthal angles.

the strip is normalized in place, previous data is overwritten.

Warning: experimental. this function is under development.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
[in]	theta	polar manipulator angle, 0 = normal emission, 90 = grazing emission
[in]	phi	azimuthal manipulator angle.
[in]	theta_offset
[in]	smooth_method	smoothing method 0 none 4 (default) Loess, see Igor's Loess operation
[in]	smooth_factor	smoothing parameter, depends on smooth_method loess: see Igor's Loess operation, 0 <= smooth_factor <= 1, default 0.5
	check	enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns

if check waves are enabled, the following waves are created (overwritten if existing):

check_dist average theta distribution
check_smoo smoothed distribution used to normalize the strip

Definition at line 451 of file pearl-anglescan-process.ipf.

variable normalize_strip_x	(	wave	strip,
		variable	smooth_method = `defaultValue`,
		variable	smooth_factor = `defaultValue`,
		variable	check = `defaultValue`
	)

divide the strip by the average X distribution.

this is a simple way to remove the effect of the angle-dependence of the analyser transmission function. the strip is normalized in place, previous data is overwritten.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
[in]	smooth_method	smoothing method 0 none 1 binomial, see Igor's Smooth operation 2 boxcar, see Igor's Smooth operation 3 scienta_ang_transm() function fit 4 (default) LOESS smoothing, see Igor's Loess operation
[in]	smooth_factor	num parameter of Igor's Smooth operation. the default value depends on smooth_method. it is 0.5 for LOESS smoothing, 2 otherwise.
[in]	check	enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns

if check waves are enabled, the following waves are created (overwritten if existing):

check_dist average X distribution
check_smoo smoothed distribution used to normalize the strip

Definition at line 185 of file pearl-anglescan-process.ipf.

variable pizza_service	(	wave	data,
		string	nickname,
		variable	theta_offset,
		variable	tilt_offset,
		variable	phi_offset,
		variable	npolar = `defaultValue`,
		variable	nograph = `defaultValue`,
		variable	folding = `defaultValue`,
		variable	xpdplot = `defaultValue`
	)

create a pizza plot from a measured (energy-integrated) data strip

accepts angle-scan data as returned by adh5_load_reduced(), maps them onto a hemispherical scan grid, and displays a polar graph.

Parameters

data	2D intensity wave, see requirements above X-axis analyser angle Y-axis manipulator scan. no specific ordering required. manipulator angle waves (ManipulatorTheta, ManipulatorTilt, ManipulatorPhi) must be in the subfolder attr below the data wave.
nickname	nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
theta_offset	manipulator theta angle corresponding to normal emission. the offset is subtracted from the ManipulatorTheta wave before processing.
tilt_offset	manipulator tilt angle corresponding to normal emission the offset is subtracted from the ManipulatorTilt wave before processing.
phi_offset	manipulator phi angle corresponding to phi_result = 0 the offset is subtracted from the ManipulatorPhi wave before processing.
npolar	number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
folding	rotational averaging, default = 1
nograph	display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
xpdplot	XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Attention: if you modify the structure of the data wave, e.g. delete some angles, this function cannot be used because the manipulator settings do not correspond to the original manipulator waves! instead, create your own manipulator waves and use pizza_service_2().

Definition at line 638 of file pearl-anglescan-process.ipf.

variable pizza_service_2	(	wave	data,
		string	nickname,
		wave	m_theta,
		wave	m_tilt,
		wave	m_phi,
		variable	npolar = `defaultValue`,
		variable	nograph = `defaultValue`,
		variable	folding = `defaultValue`,
		variable	xpdplot = `defaultValue`
	)

create a pizza plot from a measured (energy-integrated) data strip

accepts angle-scan data as returned by adh5_load_reduced(), maps them onto a hemispherical scan grid, and displays a polar graph.

the behaviour of this function is the same as pizza_service() except that the manipulator waves are specified explicitly.

Parameters

data	2D intensity wave, see requirements above X-axis analyser angle Y-axis manipulator scan. no specific ordering required. manipulator angle waves (ManipulatorTheta, ManipulatorTilt, ManipulatorPhi) must be in the subfolder attr below the data wave.
nickname	nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
m_theta	manipulator theta angles, 0 = normal emission. size = dimsize(data, 1)
m_tilt	manipulator tilt angles, 0 = normal emission. size = dimsize(data, 1)
m_phi	manipulator phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
npolar	number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
folding	rotational averaging, default = 1
nograph	display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
xpdplot	XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Definition at line 731 of file pearl-anglescan-process.ipf.

static variable polar_graph_hook ( WMWinHookStruct * s )

static

polar graph window hook

this hook converts the cursor positions to polar coordinates and displays them in a text box on the graph. the text box is visible while the cursor info box is visible.

Definition at line 2283 of file pearl-anglescan-process.ipf.

variable quick_pizza_image	(	wave	data,
		string	nickname,
		variable	theta_offset,
		variable	tilt_offset,
		variable	phi_offset,
		variable	npolar = `defaultValue`,
		variable	nograph = `defaultValue`,
		variable	folding = `defaultValue`
	)

map angle scan data onto a rectangular grid in stereographic projection

accepts angle-scan data as returned by adh5_load_reduced, maps them onto a rectangular grid in stereographic projection

Parameters

data	2D data wave, X-axis = analyser angle, Y-axis = manipulator scan (no specific ordering required)

Precondition: manipulator angles as attributes in attr folder next to the data wave

Warning: EXPERIMENTAL

Definition at line 2581 of file pearl-anglescan-process.ipf.

variable rotate_hemi_scan	(	string	nickname,
		variable	angle
	)

azimuthally rotate a hemispherical scan dataset.

this function works only for hemi scans created by make_hemi_grid() (or compatible functions).

Parameters

nickname	name prefix for waves. source data must be in current data folder.
angle	azimuthal rotation angle in degrees.

Definition at line 1523 of file pearl-anglescan-process.ipf.

variable save_hemi_scan	(	string	nickname,
		string	pathname,
		string	filename
	)

save a hemispherical scan to an Igor text file

Definition at line 2692 of file pearl-anglescan-process.ipf.

variable set_contrast	(	variable	pcmin,
		variable	pcmax,
		string	graphname = `defaultValue`,
		string	colortable = `defaultValue`
	)

set the pseudocolor contrast by percentile.

set the minimum and maximum values of the pseudocolor scale such that a specified percentile of the distribution lies outside the limits.

the new contrast is applied to traces and images of the selected graph that have pseudocolor tables.

the function is not specific to angle scans. it can be used for any pseudocolor trace or image plots except contour plots.

Parameters

pcmin	percentile below the minimum color (0-100).
pcmax	percentile above the maximum color (0-100).
graphname	name of graph. default: top graph.
colortable	name of new colortable. default: keep current table.

Definition at line 3037 of file pearl-anglescan-process.ipf.

variable set_polar_graph_cursor	(	string	nickname,
		string	cursorname,
		variable	polar_angle,
		variable	azim_angle,
		string	graphname = `defaultValue`
	)

Definition at line 2303 of file pearl-anglescan-process.ipf.

variable show_analyser_line	(	variable	theta,
		variable	tilt,
		variable	phi,
		variable	theta_offset,
		variable	tilt_offset,
		variable	phi_offset,
		variable	npolar = `defaultValue`,
		variable	nograph = `defaultValue`,
		variable	xpdplot = `defaultValue`
	)

calculate and display the line seen by the analyser for a specific emission angle

this can be used to compare to an hemispherical plot and check the manipulator angle.

Parameters

theta	manipulator theta angle
tilt	manipulator tilt angle
phi	manipulator phi angle
theta_offset	manipulator theta angle corresponding to normal emission
tilt_offset	manipulator tilt angle corresponding to normal emission
phi_offset	manipulator phi angle corresponding to phi_result = 0
npolar	number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
nograph	display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
xpdplot	XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Remarks: the function creates angle scan data under the nickname analyser.

Definition at line 848 of file pearl-anglescan-process.ipf.

variable strip_delete_frames	(	wave	strip,
		variable	qlo,
		variable	qhi,
		wave	theta,
		wave	tilt,
		wave	phi
	)

delete a contiguous range of frames from a strip.

this can be used to remove a region of bad frames due to, e.g., measurement problems. the function operates on 2D intensity data and manipulator coordinates at the same time.

Parameters

[in,out]	strip	2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan. the result is written to the original wave.
[in,out]	theta	1D data, manipulator scan. the result is written to the original wave.
[in,out]	tilt	1D data, manipulator scan. the result is written to the original wave.
[in,out]	phi	1D data, manipulator scan. the result is written to the original wave.
[in]	qlo	point index of first frame to delete.
[in]	qhi	point index of last frame to delete. qhi must be greater or equal than qlo.

Definition at line 105 of file pearl-anglescan-process.ipf.

variable trim_hemi_scan	(	string	nickname,
		variable	theta_max
	)

trim a hemispherical scan at grazing angle

the function recalaculates the values wave from totals and weights but sets elements above a given polar angle to nan.

Parameters

nickname	name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
theta_max	highest polar angle to keep (0...90 degrees).

Definition at line 2823 of file pearl-anglescan-process.ipf.

static variable update_polar_info ( string graphname )

static

update the angles info based on cursors A and B of a given polar graph window

the function reads the projection mode from the user data of the graph window and the zeroAngleWhere variable from the associated WMPolarGraph data folder.

the calculated angles are written to the csrA_theta, csrA_phi, csrB_theta, and csrB_phi global variables in the polar graph data folder. the angles text box of the graph updates from to these variables dynamically.

Parameters

graphname name of polar graph window

Definition at line 2248 of file pearl-anglescan-process.ipf.