DOKK / manpages / debian 12 / dioptas / dioptas.1.en
DIOPTAS(1) Dioptas DIOPTAS(1)

dioptas - Dioptas Documentation

Dioptas is a GUI program for fast integration and exploration of 2D X-ray diffraction Images. It provides the capability of calibrating, integrating, creating masks, showing multiple pattern overlays and display phases line positions. The basis of the integration and calibration algorithm is the pyFAI library. The usage of pyFAI allows integration times on the order of 80 milliseconds and calibration of every possible detector geometry.

Dioptas has three different modules which can all be accessed by the tab indicators on the left side of the user interface: Calibration, Mask, Integration.

The Calibration module enables you to calibrate the detector geometry. Within the Mask module you can select regions you want to exclude from the image integration and the Integration module is the heart of Dioptas, where you will spend most time for data exploration. It shows both, the image and integrated pattern, and one can overlay different pattern and show line position of phases.

[image] Location of module selectors..UNINDENT

The basis for data exploration in are the image and pattern widgets available in all 3 modules. The interaction with these widgets is tried to be as intuitive as possible, without extra need of different selection modes. All widgets support to following mouse commands:

•
Action depends on the module you are in. In the calibration view it will search for peaks. In the Mask view it is the primary tool for creating the geometric objects used to build up the mask and in the integration view it draws a line at the current two theta value.

•
Zooms into the selected area. It will try to scale images accordingly, but will not perfectly zoom in to the selected area, because pixels are kept as square objects on the screen.

•
Zoom out.

•
Completely zoom out.

•
Zoom in and zoom out based on the current cursor position.


Every image widget has a color bar and a histogram either on the side of the image (Mask module and Calibration Module) or on the top (integration module). The colors of the color bars can be easily adjusted. You can switch to a completely different color-scale by right clicking the color bar. This creates a pop-up where one of the predefined color scales can be selected. The position of the individual colors can be adjusted by dragging the triangle of this color. Further the colors can be changed completely by double clicking (left) it, which will pop up a color chooser. It is in addition also possible to add a complete new color by double clicking (left) next to the color bar. The histogram next to the color bar shows the intensity distribution of the loaded image on a log scale. The sliders two lines define the scaling of the image in the image view. Please feel free to adjust their position by dragging them.

Make sure you are in the calibration mode, which should be selected on the left side of the window.

Load the calibration image by clicking the "Load file" button on the upper right side of the window. Now you can insert the starting values for the calibration in the menu on the right. The calibration procedure will estimate distance and center position of the x-ray, as well as detector rotation. For this procedure the wavelength and pixel width/height have to be defined based on the experimental setup and detector used. Please choose the correct calibrant from the Calibrant drop-down list. In case your calibrant is not available, your own calibrant can be added in the dioptas/calibrants folder as a text file containing a list of d-spacings, Dioptas will automatically have this calibrant available in the combobox after a restart. Different detector orientations can be accommodated by rotation or flipping the image. These image transformations will be applied to all subsequent loaded images in the calibration module and in the integration module.

[image] Start values for calibration.UNINDENT

In order for Dioptas to find the correct geometry it needs an initial guess for the position of some of the rings. This is done by selecting several peaks on each diffraction ring. The parameters for peak selection are given in the "Peak Selection" section on the right site of the calibration module, when "Calibration Parameters" is selected.

[image] Peak Selection Options.UNINDENT

By default automatic peak search is selected, which tries to automatically find peaks on a clicked ring. To search on the first ring please click on it with the left mouse button. In case it is very difficult to "hit" the ring with the mouse you can just zoom in by using the drag-zoom or mouse-wheel zoom. If the peak search was successful it should look like this:

[image] LaB6 2D diffraction image with the first ring selected..UNINDENT

If the automatic peak searching fails (when Dioptas fails to select other peaks on the first diffraction ring) there are several available options:

•
perform the automatic peak search on a different ring.
  • change the "Current Ring Number"
  • and select the a peak on this ring

•
size of the search area is defined byt the search size

  • then search one peak for one diffraction ring (the current peak number will automatically increase)
  • or deselect the automatic increase checkbox and click several spots on the first ring, or any ring you like (with the corresponding peak number selected)


After the peaks/ring(s) have been selected we can start the calibration procedure. This is done by clicking the "Calibrate" Button on the lower left of the interface. This will calculate the geometric parameters based on the current peak selection and then automatically refine the calibration parameters.

After refinement Dioptas will automatically create a 360 degree cake image and an integrated pattern. When the procedure is finished it will jump to the "Cake" tab (top tab-bar above the image) and show the cake image. In this image you can easily check if the calibration was successful (by checking if the cake lines are straight). Additionally, the pattern is plotted with calculated calibrant positions in the "Pattern" Tab. All peak maxima should coincide with phase line positions. The resulting calibration parameters are shown by clicking the pyFAI parameters or Fit2d Parameters tabs in the right control panel. The current calibration parameters can be saved by clicking the Save Calibration button on the lower right of the user interface. To fast reuse the a calibration, the calibration can be reloaded by clicking Load Calibration.

If the calibration failed, either the start values are wrong, the initial peak selection was faulty or the refinement parameters need to be adjusted. For a new peak selection, just click "clear all peaks" and start the the peak selection again, make sure that current peak number belongs to the corresponding clicked ring. The meaning of each of the refinement options are explained in the next section.

The refinement options are defined on the right control panel of the Calibration module, when "Calibration Parameters" is selected.

[image] Available options for calibration refinement.UNINDENT

There are several options available:

•
Defines if Dioptas should search for peaks by itself after using the initially selected peaks. When this option is deselected only the selected peaks are used for calculating the detector calibration.

•
The refinement can be constraint to a certain image area by using a mask previously defined in the mask module. The image of the mask can be made transparent to be able to "look behind"

•
The algorithm used for searching peaks on the ring. The standard algorithm is "Massif" although "Blob" detection may give better results in some cases.

•
This is the +- search range used for automatic peak search for each ring. The center value depends on the values, estimated by the calibration procedure, so ultimately by the initial choice of predefined peaks (Peak selection)

•
This factor determines how many times the peak intensity has to be higher than the mean value of the search area (within the delta 2th value) for each individual ring. The lower this value is the more peaks will be selected, however, also the likelihood of selecting wrong background peaks increase. The default value is 3, which is good for rather spotty patterns. If your calibration image has perfect diffraction rings, this value needs to be reduced to about 1-1.5.

•
A threshold value which excludes all peaks above this value. The default value is 55000 which is good for 16 bit detectors. In case a detector with more levels is used this value needs to be adjusted.

•
The number of rings on which peaks are searched. This should be chosen based on the number of visible rings in the calibration image. For an optimal calibration all visible rings should be used.


If the calibration/refinement fails you can in principle play with all parameters. However, the most common adjustments are the number of rings and the Intensity Min factor.

In the mask module areas can be defined which will be excluded from integration or calibration. There are several geometries available to select different kind of areas. Additionally it is possible to mask based on threshold values and perform automatic cosmic removal. All tools are available on the right control panel in the Mask view. It can be either chosen to mask a certain region or unmask it (select either on the top of the control panel).

[image] The Mask module of Dioptas..UNINDENT

To select a specific geometry just click on it and an orange border will show which one is active right now. All geometric shapes are created by using left clicks:

•
The first click defines the center of the circle and the second the radius of the circle.

•
The first click defines one corner and the second the corner on the opposite side.

•
A click will mask an area as large as the circle floating around the mouse pointer. The size of the circle can be changed by changing the value next the the Point button or using just pressing the q and w keys.

•
Subsequent clicks will define edges of the polygon. A double click will close the polygon (and add the position of the double click as last point to the polygon)

•
The first 3 clicks define a circle section and the 4th click defines the thickness of the arc.


In order to do threshold masking, please insert the wanted number next to the desired Thresh button and click the button.

Cosmic removal is an automatic optimization procedure trying to mask cosmic rays from the image. This procedure can take considerable amount of time, please be patient.

•
Grows the current mask by one pixel in all directions.

•
Shrinks the current mask by one pixel in all directions.

•
This will invert the mask so that unmasked areas become masked and vice versa.

•
This will remove the complete mask.

•
Enabling to undo the last action or redo them. You can undo up to 50 actions.


•
Saves the current mask as a tiff file with intensities being 1 for masked areas and 0 for unmasked areas.

•
Loads a previously saved mask. Clears the current mask before.

•
Loads a previously saved mask and adds it to the current mask.


The integration module is the heart of Dioptas. Here you can automatically integrate multiple images to pattern, browse between images and integrated pattern, compare multiple pattern to each other, perform background subtraction and compare pattern peak positions and intensities to the ones of known phases.

[image] The integration module of Dioptas..UNINDENT

In the integration module the current image is displayed on the left side with the integrated pattern shown on the lower right. The control panel has several tabs for different functions.

The "Img" and "Pattern" tabs are primarily for loading and browsing images and pattern, respectively. In the "Overlay" tab integrated pattern can be loaded for comparing them to the currently loaded shown active pattern. The "Phase" tab enables opening/editing jcpds files and changing the equation of state parameters of the loaded phases. The "Cor" tab gives options for performing intensity corrections. Here the absorption of a c-BN seat and diamond in a diamond anvil cell, or the detector scintillator can be corrected prior to integration. The controls in the "Bkg" tab can be used to define an image as background prior to integration and doing automatic background subtraction of the integrated pattern. The "X" (special) tab contains several additional optional features like cBN absorption correction, manual selection of the number of integrating bins.

Images and pattern can be loaded by clicking the Load button in the respective modules. Images can be in different file formats: .img, .sfrm, .dm3, .edf, .xml, .cbf, .kccd, .msk, .spr, .tif, .mccd, .mar3450, .pnm, or any other common image formats. Pattern files should be 2 column files. If there is a header present it should be commented by '#' signs.

Images loaded will be automatically integrated if a calibration is available (either by performing it in the calibration window or by loading a previously saved calibration file (* *.poni*) file). There are too modes for file browsing (clicking the "<" and ">" buttons):

the next and previous filenames will be searched based on the last digits in the filename. For example the next file from test_002.tif will be test_003.tif and the previous will be test_001.tif
The next and previous files loaded will be search based on creation time of the files. This filemode does not need any numbers in the filenames it will just sort the files based on creation time and go forward and backwards in this list.

In case you want to browse through files in larger steps the "step" value can be adjusted. Any newly added file to the current img working directory can be opened automatically by checking the autoprocess checkbox in the Image module.

By default the integrated pattern is not saved. To automatically save the integrated patterns choose an output folder in the Pattern tab by clicking the "..." button and then check the autocreate checkbox. All new integrated patterns will then be automatically saved in this folder with name being the same as the image but different file extension. The integrated pattern can be automatically saved in 4 different formats by checking their respective boxes in the lower right of the Pattern tab:

•
.xy:
(Selected by default) A two column format with a header which contains the calibration parameters, polarization correction and integration unit (2th, Q or d)

•
.chi:
A two column format with a 5 line header containing the filename, integration unit and number of points. Based on Fit2d output format.

•
.dat:
A two column format without any header. It saved just the plain data.

•
.fxye:
A three column format used by GSAS and GSAS-II. The third column is the error of the intensity which is usually defined as square root of the integrated intensity.


In addition to file browsing and the "load" button, files can also be loaded by inserting their name and folder in the respective text fields. The upper one is the filename and the lower one is the containing folder. If the file does not exist it the text field will revert to its previous state.

[image] Overlay controls in the integration window..UNINDENT

In the overlay control panel you can add, delete or clear overlays and adjust their scaling and offset.

•
Loads a pattern file (2-column file) as overlay. It is possible to select multiple pattern and load them all at once.

•
Deletes the currently selected overlay in the overlay list.

•
Deletes all currently loaded overlays.


The list of overlays shows several widgets representing the state of each individual overlay. The first checkbox controls if the overlay is visible in the graph. The colored button shows the overlay color. Clicking on it will pop-up a color-chooser dialog where the color for this overlay can be changed. The name of an overlay is by default its filename, but it can be modified by double-clicking the name in the overlay list.

On the right side you can adjust the scale and offset of the overlays by either entering a specific number or using the spin-box controls. The step text fields control the steps of the spin-box.

An overlay can be used as a background for the integrated pattern. In order to to so, you have to activate the "Set as Background" button. This button sets the currently selected overlay as background for the pattern file. It can be seen that an overlay is set as background by the Set as Background button being activated for a specific overlay and by the background overlay name being shown in the lower right of the graphical user interface (right below the graph). The scaling and offset of the overlay/background can still be adjusted by using the respective spin boxes. The background overlay remains active until it is deactivated, therefore the background will be automatically subtracted from each newly integrated image or newly loaded pattern. If autosave for pattern is set, Dioptas will create a bkg_subtracted folder in the autosave folder and automatically save all subtracted patterns.

The Waterfall button will automatically adjust the offset of all loaded overlays to a multiple of the text box to the right of it. This creates a waterfall plot of all overlays. The Reset button resets all overlay offset to zero.

[image] Phase controls in the integration window..UNINDENT

The basic controls for phases are similar to the ones in overlay:

•
Loads a *.jcpds or *.cif file, calculates the line positions in the range of the current pattern and shows the phase lines in the graph. Cif-files will be internally converted into the jcpds format. For doing so, a small window will pop-up asking which intensity should be the minimum intensity for each reflection (Intensity Cutoff) and up to which minimum d-spacing the reflections should be included (Minimum d-spacing). You can select multiple *.jcpds or *.cif files in the file dialog to load multiple phases.

•
Opens a dialog where the jcpds file can be edited. For further details see the JCPDS editor section

•
Deletes the currently selected phase in the phase list.

•
Deletes all phases.

•
Saves a list of phases (basically a text file with the path to all phases loaded) which can be later restored.

•
Loads a list of phases which was previously saved by the Save List function.


The list of phases shows several widgets representing the state of each individual phase overlay. The first checkbox controls if the phase lines are visible in the graph. The colored button shows the color of the phase lines. Clicking on it will pop-up a color-chooser dialog where the color for this phase can be changed. The name of an phase is by default its filename, but can be changed by double-clicking the name in the phase list. Additionally the pressure and temperature for each phase is shown in the phase list. If for a particular phase thermal expansion is not in the jcpds file it will always display '- K'.

On the right side the pressure and temperatures of the loaded phases can be adjusted. If Apply to all phases is checked the pressure and temperature will be set for all loaded phases. By default the pressure and temperature values will be displayed in the phase legend in the pattern if they differ from ambient conditions. For disabling this feature please uncheck the Show in Pattern checkbox.

[image] Graphical JCPDS editor..UNINDENT

In the JCPDS Editor the parameters of the jcps phase can be modified. Every change will be immediately reflected in the position of the lines in the pattern. You can edit the comment, the symmetry, lattice parameter and equation of state parameters. Reflections can be edited in the reflections table. h, k, l and intensities can be modified by double clicking in the table all other parameters are calculated correspondingly. A "0" after a parameter name always means that this is the value at ambient condition and when there is no "0" the value corresponds to the current temperature and pressure conditions modified in the Phase tab. The changes can be saved as a new file by clicking the Save As button. If you want to revert all changes and reload the original files please press the Reload File button. If you like the changes you made you can close the JCPDS editor either by clicking the X button or the OK button on the lower right. The Cancel button will close the JCPDS editor and revert the changes made since the last opening of the JCPDS editor.

[image] Correction controls in the integration window..UNINDENT

In the Cor tab it is possible to enable intensity corrections for cBN seats, diamonds and the scintillator thickness of the detector.

Enabling this option calculates the theoretical transmitted intensity through a diamond and cBN seat based on the parameters entered into the text boxes. Where:

•
anvil thickness in mm.

•
seat thickness in mm

•
radius of the small opening of the cBN seat (close to the diamond) in mm

•
radius of the outer opening of the cBN seat in mm

•
tilting of the cell in respect to the primary beam in degrees.

•
direction of the Cell tilt in degrees.

•
offset of the sample position from the center of the diamond - seat assemblage in mm

•
defines the rotation of the center offset

•
Absorption length of the anvil in \mu m

•
Absorption length of the seat in \mu m


To see the calculated transmitted intensity distribution press the Plot button. This will show the calculated absorption correction in the image view.

Enabling this option will correct the intensity response of the detector for large angles. The intensity is proportional to the path length of the diffracted x-ray beam through the scintillator of the detector. This causes higher intensities at larger angles between the diffracted beam and the normal of the detector plane due to larger path lengths. The correction assumes that the source of the intensity is coming from the calibrated sample position. This correction is not valid if there is additional contribution from air or other background. The background contribution needs to be either removed first or the correction needs to be applied to the sample and the background signal before subtraction.

Parameters:

•
Thickness of the detector scintillator in mm

•
Absorption length of the detector scintillator in \mu m


To see the calculated intensity correction press the Plot button. This will show the calculated absorption correction in the image view.

[image] Background controls in the integration window..UNINDENT

In the Bkg tab an image can be loaded as background image or we can automatically subtract an estimated background from the integrated pattern.

This image will be subtracted from the original image prior to the integration process. The intensity of the image can scaled or offset by using the corresponding spin boxes. The text fields next to the spin boxes define the individual steps for the spinbox. After each change, loading an image as background, removing it, or change the scale and offset of the background image, the image will be automatically reintegrated.

•
Loads an image as background image.

•
Removes the currently loaded background image. The original image will then be integrated without any background subtraction.

•
The intensity of the background image is scaled by: scale x img_intensity + offset.


Activating this, will automatically try to estimate the background in the integrated pattern using a moving average method. The background will then be created by fitting the resulting pattern with a polynomial.

•
Defines the width of the moving window. The unit is based on the selection in the pattern plot (2\theta, Q or d).

•
Number of times the moving averages filter goes through the pattern.

•
The order of the polynomial which is fitted after the moving average filter.

•
Defines the minimum and maximum x-value of the pattern used for background subtraction. CAUTION the subtracted pattern will only be displayed in this range.

•
This button enables the inspection mode in the pattern widget (see Fig. %s). Enabling this mode shows the original pattern and the subtracted pattern (red dashed line). This is very useful to tweak the background subtraction parameters to the specific needs of the pattern. Furthermore, the x-range can be adjusted visually by dragging the ROI (solid yellow lines).


[image] Inspect-Mode in the pattern widget for background subtraction..UNINDENT

Enabling the pattern background subtraction and also the inspect mode can also be easily done by using the quick actions in the pattern widget (see Fig. %s). The "bg" button on the right side will enable the background subtraction and clicking the "I" button will enable the inspection mode.

[image] Special Options..UNINDENT

The currently available features:

Here you can manually specify the number of integration bins and/or choose to supersample the image. Supersampling an image by a factor of n>1 results in of splitting of each pixel into n^2 pixels with equal distribution of intensities among the splitted pixels. For perfect powder samples this can result in smaller integrated peak widths and more points per peak if the physical pixel width is too high. However, it may result in unreasonable intensity distributions. Please use at your own risk.

The "Image" widget and the "Pattern" widget exhibit several quick actions. Some of them can be context sensitive (e.g. if there is an image background loaded).

[image] Quick actions in the image widget..UNINDENT

The image quick actions are shown in the lower left of the image widget in the integration view.

•
Enables a Rectangular region of interest (ROI) on the image, which can be dragged and changed in size by dragging the corners. Only the image part in the ROI will be integrated.

•
The image will now always automatically shown as Cake (2d-integrated image), which basically shows the change in intensity with azimuth.

•
This will change back to only display the original image and not the cake.

•
Activates the mask for integration. The mask needs to be defined before in the Mask-module.

•
This checkbox will define whether the mask is displayed with transparent or solid color.

•
If checked the widget will show the background subtracted image. (a background has to be loaded to enable this button).

•
Defines whether a the intensity range displayed in the image widget will be rescaled for each new loaded image.

•
This button will undock the image widget from the Dioptas window into a new window. This is especially useful for multi-monitor setups, where the image can be displayed on one monitor and the integrated pattern on another.


The pattern widget exhibits several buttons on the top and also on the right (see Fig. %s)

•
•
Saves the currently shown image as either a *.png file for presentation or *.tiff file as data.

•
Saves the current pattern either in a two-column format (*.xy) or the complete pattern content in a *.png or vectorized *.svg format.

•
Adds the currently active pattern (white) to overlays.

•
Adds the currently active pattern (white) to overlays and sets it as background.

•
Opens a dialog to open a *.poni calibration file and sets this as the new calibration parameters.



•
•
2\theta, Q or d:
selects the unit in which the image should be integrated to a pattern.

•
enable background subtraction and the background inspection mode.

•
determines whether anti-aliasing is enabled for the pattern widget. Disabling AA improves performance when many overlays are shown in the pattern widget.

•
when enabled, a newly integrated or loaded pattern will be shown otherwise the zoom will stay as is. This will be enabled on every double right click in the pattern widget.




[image] Location of configuration controls..UNINDENT

Configuration are used to handle experimental setups with multiple detectors in one Dioptas instance. A configuration contains the calibration information, loaded image, image corrections, mask, integrated pattern and background corrections. Overlays and phases are not handled in configurations and are global. By default the configuration control panel (Fig. %s) is hidden and only one configuration is active (single Detector mode). To enable the panel, please click the C button on the upper left corner of Dioptas. In principle, Dioptas can handle infinite configurations, however, this also means a lot of RAM usage.

A configuration can be added or removed by the + and - buttons. Each added will be subsequently numbered and can be selected by the buttons to the left of the - button. After adding a a new configuration the configuration will be empty and needs to be newly calibrated for the wanted detector geometry.

The File and Folder controls in the middle of the configuration panel enable combined file browsing for all configurations, whereas the Pos textfield defines the position of the number in the string. By using the "<" and ">" buttons the next or previous image in each configuration will be loaded.

This is also true for the similar Folder "<" and ">" buttons. Here Dioptas supposes that the actual filenames stay the same, but the images are saved in subsequently indexed folders, like e.g. "run101", "run102". The MEC checkbox enables a special mode for the matters at extreme conditions beamline at LCLS where both, the folder and the filenames have the run number included.

The Factor Input is an intensity scaling factor for the image in the configuration, so that different configurations can be compared where the detector response is not equal.

If there is overlap between the different configurations, the intensity will be averaged.
If there is overlap between the different configurations (which is in principle not possible in a multi detector setup), the intensity will be averaged.

[image] Location of the project controls.UNINDENT

The state of Dioptas including the different configurations with image, mask, image corrections, background corrections overlays and phases can be open and saved in projects. This is very useful in case you want to continue working on a project another day. The controls for this are in the upper left of the Dioptas window (see Fig. %s). The Dioptas project files have a *.dio extension and are basically HDF5 under the hood. Thus, can the data can be also opened or edited with any HDF5 viewer. [image]

Opens a file browser where you can select a Dioptas project (*.dio) to open. [image]

Saves the current state of Dioptas into a Dioptas project (*.dio). [image]

Resets the current state of Dioptas. This means all phases, overlays, and configurations will be deleted and you can start from a new fresh Dioptas.

Clemens Prescher

Dioptas - GUI program for fast processing of 2D X-ray diffraction data Principal author: Clemens Prescher (clemens.prescher@gmail.com) Copyright (C) 2014-2019 GSECARS, University of Chicago, USA Copyright (C) 2015-2018 Institute for Geology and Mineralogy, University of Cologne, Germany Copyright (C) 2019 DESY, Hamburg, Germany

January 30, 2023 0.4.0