\(\renewcommand\AA{\text{Å}}\)

11. GSASIIimage: Image calc module

11.1. Summary/Contents

Image calibration, masking & image integration routines.

Note that the GSAS-II image coordinate system is defined as follows: standing facing the x-ray source (e.g. behind the beamstop), the synchrotron ring will be to the left (for a left handed synchrotron – almost all are left handed). That left-right direction defines X. Y is up and thus Z is toward the source/sample. The resulting 2D image is then viewed from the sample position (e.g. between the x-ray source and the detector). The detector is addressed in units of pixels (or distances using the pixel size) with the origin as the lower left corner. The beam center is measured from this point; usually somewhere near the center of the image, thus both Xc & Yc will be greater than zero unless the beam center is not on the image. Note that when images are displayed in image viewers, most software puts the origin in the upper left corner.

11.2. GSASIIimage Routines

Classes and routines defined in GSASIIimage follow.

GSASIIimage.AutoPixelMask(Image, Masks, Controls, numChans, dlg=None)

Find “bad” regions on an image and creata a pixel mask to remove them. This works by masking pixels that are well outside the range of the median at that radial distance. This is ~4x faster than the original version from RBVD. Developed by Howard Yanxon, Wenqian Xu and James Weng.

Called from GSASIIimgGUI.UpdateMasks.OnFindPixelMask (single image) and GSASIIimgGUI.UpdateMasks.OnAutoFindPixelMask (multiple images) [see GSASIIimgGUI.UpdateMasks()]

Parameters:

• Image (np.array) – 2D data structure describing a diffaction image

• Masks (dict) – contents of Masks data tree

• Controls (dict) – diffraction & calibration parameters for image from IMG data tree entry

• numChans (int) – number of channels in eventual 2theta pattern after integration

• dlg (wx.Dialog) – a widget that can be used to show the status of the pixel mask scan and can optionally be used to cancel the scan. If dlg=None then this is ignored (for non-GUI use).

Returns:

a mask array with the same shape as Image or None if the the scan is cancelled from the dlg Dialog.

GSASIIimage.AzimuthIntegrate(image, data, masks, ringId, blkSize=1024)

Integrate by azimuth around the ring masked region in 0.5 deg steps

GSASIIimage.DoPolaCalib(ImageZ, imageData, arcTth)

Determine image polarization by successive integrations with & without preset arc mask. After initial search, does a set of five with offset azimuth to get mean(std) result.

GSASIIimage.EdgeFinder(image, data)

this makes list of all x,y where I>edgeMin suitable for an ellipse search? Not currently used but might be useful in future?

GSASIIimage.FastAutoPixelMask(Image, Masks, Controls, numChans, dlg=None)

Find “bad” regions on an image and create a pixel mask to remove them. This works by masking pixels that are m*sigma outside the range of the median at that radial distance using the using the fmask C module (based on the AIRXD C++ code https://github.com/AdvancedPhotonSource/AIRXD-ML-PUB, developed by Howard Yanxon, Wenqian Xu and James Weng.)

This is much faster than AutoPixelMask, which does pretty much the same computation, but uses pure Python/numpy code.

Called from GSASIIimgGUI.UpdateMasks.OnFindPixelMask (single image) and GSASIIimgGUI.UpdateMasks.OnAutoFindPixelMask (multiple images) [see GSASIIimgGUI.UpdateMasks()]

Parameters:

• Image (np.array) – 2D data structure describing a diffaction image

• Masks (dict) – contents of Masks data tree

• Controls (dict) – diffraction & calibration parameters for image from IMG data tree entry

• numChans (int) – number of channels in eventual 2theta pattern after integration

Returns:

a bool mask array with the same shape as Image

GSASIIimage.Fill2ThetaAzimuthMap(masks, TAr, tam, image, ringMask=False)

Makes masked intensity correction arrays that depend on image intensity, 2theta and azimuth. Masking is generated from the combination of the following: an array previously generated by MakeMaskMap() combined with Thresholds, Rings and Arcs mask input.

These correction arrays are generated for a rectangular section of an image (must be 1024x1024 or smaller) where the size is determined the input arrays.

Note that older, less optimized, code has been left commented out below in case there are future problems or questions.

Parameters:

• masks (dict) – GSAS-II mask settings

• TAr (np.array) – 2theta/azimuth/correction arrays, reshaped

• tam (np.array) – mask array from MakeMaskMap()

• image (np.array) – image array

Returns:

a list of 4 masked arrays with values for: azimuth, 2-theta, intensity/polarization, dist**2/d0**2

GSASIIimage.FitDetector(rings, varyList, parmDict, Print=True, covar=False)

Fit detector calibration parameters

Parameters:

• rings (np.array) – vector of ring positions

• varyList (list) – calibration parameters to be refined

• parmDict (dict) – all calibration parameters

• Print (bool) – set to True (default) to print the results

• covar (bool) – set to True to return the covariance matrix (default is False)

Returns:

[chisq,vals,sigList] unless covar is True, then [chisq,vals,sigList,coVarMatrix] is returned

GSASIIimage.FitImageSpots(Image, ImMax, ind, pixSize, nxy, spotSize=1.0)

Used with “s” key in image plots to search for spot masks

GSASIIimage.FitMultiDist(rings, varyList, parmDict, Print=True, covar=False)

Fit detector calibration parameters with multi-distance data

Parameters:

• rings (np.array) – vector of ring positions (x,y,dist,d-space)

• varyList (list) – calibration parameters to be refined

• parmDict (dict) – calibration parameters

• Print (bool) – set to True (default) to print the results

• covar (bool) – set to True to return the covariance matrix (default is False)

Returns:

[chisq,vals,sigDict] unless covar is True, then [chisq,vals,sigDict,coVarMatrix] is returned

GSASIIimage.FitStrSta(Image, StrSta, Controls)

Needs a doc string

GSASIIimage.FitStrain(rings, p0, dset, wave, phi, StaType)

Fits external strain tensor from distortion of Bragg rings in images

GSASIIimage.GetAzm(x, y, data)

Give azimuth value for detector x,y position; calibration info in data

GSASIIimage.GetDetXYfromThAzm(Th, Azm, data)

Computes a detector position from a 2theta angle and an azimultal angle (both in degrees) - apparently not used!

GSASIIimage.GetDetectorXY(dsp, azm, data)

Get detector x,y position from d-spacing (dsp), azimuth (azm,deg) & image controls dictionary (data) - new version it seems to be only used in plotting

GSASIIimage.GetDetectorXY2(dsp, azm, data)

Get detector x,y position from d-spacing (dsp), azimuth (azm,deg) & image controls dictionary (data) it seems to be only used in plotting

GSASIIimage.GetDsp(x, y, data)

Give d-spacing value for detector x,y position; calibration info in data

GSASIIimage.GetEllipse(dsp, data)

uses Dandelin spheres to find ellipse or hyperbola parameters from detector geometry as given in image controls dictionary (data) and a d-spacing (dsp)

GSASIIimage.GetEllipse2(tth, dxy, dist, cent, tilt, phi)

uses Dandelin spheres to find ellipse or hyperbola parameters from detector geometry on output radii[0] (b-minor axis) set < 0. for hyperbola

GSASIIimage.GetTth(x, y, data)

Give 2-theta value for detector x,y position; calibration info in data

GSASIIimage.GetTthAzm(x, y, data)

Give 2-theta, azimuth values for detector x,y position; calibration info in data

GSASIIimage.GetTthAzmDsp(x, y, data)

Computes a 2theta, etc. from a detector position and calibration constants - checked OK for ellipses & hyperbola. Use for detector 2-theta != 0.

Returns:

np.array(tth,azm,G,dsp) where tth is 2theta, azm is the azimutal angle, and dsp is the d-space - not used in integration

GSASIIimage.GetTthAzmDsp2(x, y, data)

Computes a 2theta, etc. from a detector position and calibration constants - checked OK for ellipses & hyperbola. Use only for detector 2-theta = 0

Returns:

np.array(tth,azm,G,dsp) where tth is 2theta, azm is the azimutal angle, and dsp is the d-space - not used in integration

GSASIIimage.GetTthAzmG(x, y, data)

Give 2-theta, azimuth & geometric corr. values for detector x,y position; calibration info in data - only used in integration for detector 2-theta != 0. checked OK for ellipses & hyperbola This is the slow step in image integration

GSASIIimage.GetTthAzmG2(x, y, data)

Give 2-theta, azimuth & geometric corr. values for detector x,y position; calibration info in data - only used in integration for detector 2-theta = 0

GSASIIimage.ImageCalibrate(G2frame, data)

Called to perform an initial image calibration after points have been selected for the inner ring.

GSASIIimage.ImageCompress(image, scale)

Reduces size of image by selecting every n’th point param: image array: original image param: scale int: intervsl between selected points returns: array: reduced size image

GSASIIimage.ImageIntegrate(image, data, masks, blkSize=128, returnN=False, useTA=None, useMask=None)

Integrate an image; called from OnIntegrate() and OnIntegrateAll() inside GSASIIimgGUI.UpdateImageControls() as well as GSASIIscriptable.G2Image.Integrate().

Parameters:

• image (np.array) – contains the 2-D image

• data (np.array) – specifies controls/calibration parameters for an image

• masks (np.array) – specifies masks parameters for an image

• blkSize (int) – a blocksize that is selected for speed

• returnN (bool) – If True, causes an extra matrix (NST) to be returned. The default is False.

• useTA (np.array) – contains a cached set of blocked 2theta/azimuth/correction matrices (see MakeUseTA()) for the current image. The default, None, causes this to be computed as needed.

• useMask (np.array) – contains a cached set of blocked masks (see MakeUseMask()) for the current image. The default, None, causes this to be computed as needed.

Returns:

list ints, azms, Xvals, cancel (or ints, azms, Xvals, NST, cancel if returnN is True), where azms is a list of M azimuth values that were requested for integration, ints is a list M arrays of diffraction intensities (where each array of diffraction data is length N), Xvals is an array of “x” values, 2theta, Q, log(q) (determined by data[‘binType’]), also of length N. Variable cancel will always be False, since a status window is no longer supported.

GSASIIimage.ImageLocalMax(image, w, Xpix, Ypix)

Needs a doc string

GSASIIimage.ImageRecalibrate(G2frame, ImageZ, data, masks, getRingsOnly=False)

Called to repeat the calibration on an image, usually called after calibration is done initially to improve the fit, but also can be used after reading approximate calibration parameters, if they are close enough that the first ring can be found.

Parameters:

• G2frame – The top-level GSAS-II frame or None, to skip plotting

• ImageZ (np.Array) – the image to calibrate

• data (dict) – the Controls dict for the image

• masks (dict) – a dict with masks

Returns:

a list containing vals,varyList,sigList,parmDict,covar or rings (with an array of x, y, and d-space values) if getRingsOnly is True or an empty list, in case of an error

GSASIIimage.Make2ThetaAzimuthMap(data, iLim, jLim)

Makes a set of matrices that provide the 2-theta, azimuth and geometric correction values for each pixel in an image taking into account the detector orientation. Can be used for the entire image or a rectangular section of an image (determined by iLim and jLim).

This is used in two ways. For image integration, the computation is done over blocks of fixed size (typically 128 or 256 pixels) but for pixel mask generation, the two-theta matrix for all pixels is computed. Note that for integration, this routine will be called to generate sections as needed or may be called by MakeUseTA(), which creates all sections at once, so they can be reused multiple times.

Parameters:

• data (dict) – GSAS-II image data object (describes the image)

• iLim (list) – boundary along x-pixels

• jLim (list) – boundary along y-pixels

Returns:

TA, array[4,nI,nJ]: 2-theta, azimuth, 2 geometric corrections

GSASIIimage.MakeFrameMask(data, frame)

Assemble a Frame mask for a image, according to the input supplied. Note that this requires use of the Fortran polymask routine that is limited to 1024x1024 arrays, so this computation is done in blocks (fixed at 512) and the master image is assembled from that.

Parameters:

• data (dict) – Controls for an image. Used to find the image size and the pixel dimensions.

• frame (list) – Frame parameters, typically taken from Masks['Frames'].

Returns:

a mask array with dimensions matching the image Controls.

GSASIIimage.MakeMaskMap(data, masks, iLim, jLim, tamp)

Makes a mask array from masking parameters that are not determined by image calibration parameters or the image intensities. Thus this uses mask Frames, Polygons and Lines settings (but not Thresholds, Rings or Arcs). Used on a rectangular section of an image (must be 1024x1024 or smaller, as dictated by module polymask) where the size is determined by iLim and jLim.

Parameters:

• data (dict) – GSAS-II image data object (describes the image)

• iLim (list) – boundary along x-pixels

• jLim (list) – boundary along y-pixels

• tamp (np.array) – all-zero pixel mask array used in Polymask

Returns:

array[nI,nJ] TA: 2-theta, azimuth, 2 geometric corrections

GSASIIimage.MakeUseMask(data, masks, blkSize=128)

Precomputes a set of blocked mask arrays for the mask elements that do not depend on the instrument controls (see MakeMaskMap()). This computation is done optionally, but provides speed as the results from this can be cached to avoid recomputation for a series of images with the same mask parameters.

Parameters:

• data (np.array) – specifies mask parameters for an image

• blkSize (int) – a blocksize that is selected for speed

Returns:

a list of TA blocks

GSASIIimage.MakeUseTA(data, blkSize=128)

Precomputes the set of blocked arrays for 2theta-azimuth mapping from the controls settings of the current image for image integration. This computation is done optionally, but provides speed as the results from this can be cached to avoid recomputation for a series of images with the same calibration parameters.

Parameters:

• data (np.array) – specifies parameters for an image

• blkSize (int) – a blocksize that is selected for speed

Returns:

a list of TA blocks

GSASIIimage.TestFastPixelMask()

Test if the fast (C) version of Auto Pixel Masking is available.

Returns:

True if the airxd.mask package can be imported; False otherwise.

GSASIIimage.calcFij(omg, phi, azm, th)

Uses parameters as defined by Bob He & Kingsley Smith, Adv. in X-Ray Anal. 41, 501 (1997)

Parameters:

• omg – his omega = sample omega rotation; 0 when incident beam || sample surface, 90 when perp. to sample surface

• phi – his phi = sample phi rotation; usually = 0, axis rotates with omg.

• azm – his chi = azimuth around incident beam

• th – his theta = theta

GSASIIimage.checkEllipse(Zsum, distSum, xSum, ySum, dist, x, y)

Needs a doc string

GSASIIimage.makeMat(Angle, Axis)

Make rotation matrix from Angle and Axis

Parameters:

• Angle (float) – in degrees

• Axis (int) – 0 for rotation about x, 1 for about y, etc.

GSASIIimage.makeRing(dsp, ellipse, pix, reject, scalex, scaley, image, mul=1)

Needs a doc string

GSASIIimage.peneCorr(tth, dep, dist)

Needs a doc string

GSASIIimage.pointInPolygon(pXY, xy)

Needs a doc string