ndisp: display diffraction images
"ndisp" is the diffraction image display program from the collect
suite. It is used by collect to
display axial photographs, and to
follow the data collection.
For accurate display, "ndisp" should know about the detector
distortion and alignment parameters (See programs makedistor and makedetalign). Without these, ndisp will
assume that the detector has no distortion, and is aligned exactly.
Especially since the primary beam position will generally not be at
the exact center of the detector, this is a horrible approximation.
Usage
The program is invoked by the command line:
ndisp [options] [imagefilename [.x or .rmat filenames]]
The option "nofilters" instructs
ndisp to show the data without any preprocessing (i.e. it presets all the
filters in the "Filter" menu to "off"). This is the default for synthetic
precession images (file extension ".syn").
The option "mark=mmx,mmy,mmx2,mmy2,...." shows marks in the image
at each of the mmx,mmy locations indicated.
The option "slave" enables the slave-mode for ndisp, in which it
will listen for connections from another program that wants its
images to be displayed. Slave-mode is automatically enabled if
"ndisp" is called without any arguments.
An alternative to "slave" mode is "follow" mode. If the "follow" option
is given on the command line, the ndisp program will regularly check the
contents of the directory it is running in, and load any new image file
appearing there.
Different image file types are
recognized from their names.
Any .x or .rmat files following the kcdfilename on the command line
are used to preload a "Unit Cell" tool (see there). This will
only work if proper distortion correction and detector alignment have
been performed
The "ndisp" main window can be rescaled freely. The size of the image will
adapt itself automatically.
Pull-down menus
File
- Load
-
Loads an image file using a file selector
- Convert to
-
Saves an image file in a graphics file format. Please note that
"SAVE" does not save exactly what you see on the screen with all tools
on there, but a plain image. If you want to make complete images
either use the "save as postscript" option, or get and install the ImageMagick package. The
"import" program from that package can grab a window or any part of
the screen, and save the contents in a file in many different
formats. The nprint program provides a
convenient GUI to the "import" program.
ImageMagick comes preinstalled on RedHat Linux systems.
- Save as postscript
-
Saves the currently displayed image including all tools visible in the
main ndisp window as a color postscript file.
- Quit
-
Quits the ndisp program.
Options
The "Options" contains 3 different groups of items:
- Four option toggles:
- balloon help
- this will toggle balloonhelp in all active programs
- display buttons
- this will toggle the display of the toolbar on the right of the "ndisp"
window.
- display status line
- this will toggle the display of the status text on the bottom of the
"ndisp" window.
- auto raise
- If this option is activated, the display will pop itself to the top
every time a new image is loaded.
- Five possible color schemes:
- White on black
-
White peaks on a black background
- Black on white
-
Black peaks on a white background
- Mark extremes
-
Data above the "max" colored in red, below "min" in blue, and the
rest of the pixels in white peaks on a black background
- Color ramp
-
A color ramp from blue for "min" through green
and red to white for "max".
- Color ramp 2
-
A color ramp from black for "min" to blue through
red and yellow to white for "max".
- Since the human eye and computer monitors do not have 16 bit accuracy,
it is necessary to scale the image to express what we want to see.
The menu contains four possible scaling policies:
- Do not change scale
-
Scale will be left identical at loading a new image.
- Always scale 0-1000
-
Upon loading a new image, it will be scaled between 0 and
1000. Practically this means that in the "White on black" color
scheme, all pixels with negative values are black, all pixels with
values larger than 1000 are white, and the pixels with inbetween
values are on the grey ramp.
- 3%-97% median scale
-
Always scale between the 3% and 97% levels: Practically this means
that in the "White on black" color scheme, 3% pixels with the
lowest values are black, 3% pixels with the highest values are
white, and the rest is on the grey-ramp.
- Intelligent mix
-
If the image contains many pixels with values between 0 and 1000,
it will be scaled between those two values, otherwise the 3%-97%
median scale is used
New copies of the "ndisp" program run from the same directory will
copy the last-selected color scheme and scaling type. The setting of
"balloon help" is shared with other collect programs.
Tools
The "objects" menu contains tools that can calculate properties of the image
or display marks at calculated positions.
- Header information
-
This shows a window with a little bit more information from the KCD header.
- Intensity histogram
-
Shows a histogram of the intensities that are occurring in a
rectangular area of the image. The area can be selected by dragging
the mouse over the image while holding the first mouse button. The
area defaults to the entire image, so it may take some time to
calculate before the window appears.
The top part of the histogram window shows the actual histogram. If
there are many bins in the histogram, it will be shown as a line-graph
instead. If the width of the bins is sufficient, each bin will contain
its own frequency count.
Just below the histogram are some statistics on the population: the
number of points in the histogram, the range of the data, the average
with its uncertainty, and the standard deviation of the population with
its uncertainty.
The horizontal divisions can be controlled using the "Class width", "Lowest
value" and "Highest value" entries.
- Mirrored mouse pointer
-
Shows 4 marks on the display whenever the first mouse button is
pressed in the image. One of these marks will appear at the point
where the mouse was clicked, the other three are "mirrored" in the
primary beam. This can be useful to study precession images or oriented rotation images.
This option can be removed from the menu using a configuration option.
It is off by default.
- Peak list from file
-
shows marks at all locations given in a peak mark file. Each line in a
peak mark file should look like:
Impact 3.45 12.67
The two numbers are the mm coordinates on the detector where the
mark should be shown. "0.0 0.0" is the location of the primary beam
at theta=0.0.
This option can be removed from the menu using a configuration option.
It is off by default.
- Peak search
-
Shows marks at all locations that can be recognized as peaks.
- Primary beam
-
Shows a mark at the primary beam location.
- Profile; Hor/Ver
-
Shows a horizontal or vertical profile through part of the image. The
profiled part of the image can be changed by dragging the left mouse
button in the main image display window or in any zoom window.
The width of the profile (over which the data is averaged) is given in
pixels. It can be changed by typing over the value in the entry field,
or by clicking on the left and right arrows to change the value by a
factor of the square root of 2.
To prevent the profile window from reacting on a mouse click, the
"Follow mouse" checkbox can be deselected. This is useful if more than
one profile window is active, and you want them to show different profiles
through the image.
A similar function is there for the "Follow image" checkbox. If this
is deselected, the profile window will not change image if a new file
is loaded in the main window. This can be used to show identical
profiles through different images (create two profile windows,
then deselect "Follow image" in one of the two, and load the second
image).
If the "log scale" checkbox is selected, the vertical scale will
change to the logarithm (base 10) of the actual data (A minimum of 1
is enforced).
The profile window can be resized.
- Profile; General
-
shows a general (diagonal) profile through part of the image. This is
much slower than a "Hor/Ver profile".
All other properties are identical to a "Hor/Ver profile"
- Reflection map
-
This shows a rotatable 3D-view of a reflection together with some position
and intensity statistics. Can be changed by clicking the middle mouse
button in the main window or in any zoom window.
The "follow image" and "follow mouse" options have functions identical to
those of the profile window tools.
- Resolution circles
-
Shows up to 5 equi-resolution lines, with a numerical identification.
- Unit Cell
-
Shows marks at all spots where reflections are expected for the
currently loaded cell. Additionally, it shows a summary window
with some additional information.
The leftmost part shows a window with the directions of the axes and
reciprocal axes of the unit cell (red=a,a* green=b,b* blue=c,c*) as
seen from the primary beam at the center of the rotation that resulted
in the image. This image can be scaled by dragging the mouse with the
third (rightmost) button pressed.
In the central part, the reflection predictions in the main ndisp
window can be toggled on/off. Furthermore the h,k,l position pointed
at with the mouse will be displayed in here.
At the right side, three buttons allow you to:
- Cell: show the unit cell parameters and the cell reduction;
- Edit: change the unit cell and the way the predictions are shown;
- X: remove this tool completely.
- Zeta limit
-
Adds a hourglass shaped object to the display window, separating areas
with reflections at low zeta and reflections at high
zeta. Normally this separation is drawn at 20 degrees: the normal
limit for the integration of reflections by the EvalCCD
program. Only a very small amount of reflections are in the "low
zeta" areas: those reflections that are visible are moving through the
Ewald sphere very slowly, and they are often "incomplete".
- Zoom window
-
Shows a zoomed view of the display. The zoomed part of the image can
be selected by clicking the middle mouse button in the main image
display window, or in any zoom window.
The scale of the zoom window is shown in an entry field. It can be
changed by typing over the value in the entry field, or by clicking on
the left and right arrows to change the value by a factor of the
square root of 2.
To prevent the zoom window from reacting on a mouse click, the
"Follow mouse" checkbox can be deselected. This is useful if more than
one zoom window is active, and you want them to show different areas
of the image.
A similar function is there for the "Follow image" checkbox. If this
is deselected, the zoom window will not change image if a new file is
loaded or the scaling or color scheme are changed in the main
window. This can be used to show identical zoomed areas of different
images (create a zoom window, "clone" it, then deselect "Follow image"
in one of the two, and load the second image).
If the zoom-scale is 20 or larger, the intensity of each pixel can be
shown, enable this by clicking the "Show intensity" checkbox.
The zoom window can be resized: the zoomed area will adapt automatically.
An exact copy of a zoom window can be made using the "Clone" button.
There is one other option in the "Tools" menu.
- Show list
-
Brings up a list of the active tools, allowing you to change the
options for each one (click on the description of a tool to change its
parameters). Use this e.g. if you want to change the color of the
intensity values shown in a Zoom window, or to change the primary
beam indicator from a smaller circle to a larger square.
It is possible to make tools "temporarily inactive" (i.e. they are
invisible on the display) by de-selecting the checkbox in front of the
tool description in the tool list.
The tool list can also be used to add new tools (but why would you?).
It is possible to have multiple active copies of the same tools.
Imagefilters
The "imagefilters" menu contains two entries:
- Change filters
-
Display a list of image filters that are applied to the image upon
reading, allowing the user to toggle each of them.
Filters are:
- Subtract ADC offset
-
Subtracts the ADC offset from the image. This may result in a few
slightly negative pixels.
- Correct for nonempty pixels
-
Correct for pixels that always contain a signal as calibrated using
a short dark image.
- Correct for warm pixels
-
Correct for pixels that contain a signal proportional to the exposure time,
independent of the X-ray load.
- Replace unreliable pixels
-
Replace pixels that vary over time by a weighted average of their neighbours.
- Correct for pixel sensitivity
-
Multiply the image by the detector sensitivity map. This does not
create proper integrated reflection intensities!
- Correct for angle of incidence
-
Corrects the image for sensitivity differences created by differing angles
of incidence for the X-rays onto the detector.
- Correct for pixel area
-
Divide each pixel value by the relative area. This can be useful for
so-called flood-field or flat-field images that should give an
identical X-ray exposure per unit area.
- Correct for air absorption
-
Approximately correct for air-absorption by calculating the path length
of the diffracted beam for each pixel.
- Remove background slope
-
Will do a bi-linear fit though the background of the image, and remove
the slope. This can be useful for calibration "grid" images, which are
measured at much higher than the normal -60 degrees C operating
temperature of the CCD chip.
- Remove vertical lines
-
Will remove "vertical line artifacts" from the image. This can be
useful for calibration "grid" images, which are measured at much
higher than the normal -60 degrees C operating temperature of the CCD
chip.
- Remove ripples in background
-
Will perform a 1D-FFT hi-pass filter on the image to remove background
which is caused by Low Frequency interference.
- Remove complete background
-
Will perform a 2D-FFT hi-pass filter on
the image to remove all global background effects. Very slow.
- Select frame
-
Instructs the dezinger-filter to select a single frame or the
dezingered result of all frames. Please note that this setting will
stay active until it is changed. It should not be necessary to change
this option from the default, unless you are specifically looking for
the origin of an image feature.
Scaling
By default, the image is processed through a dark-current correction filter, and a
logarithmic colour scale between 0 and 1000 is used. This normally
gives a good overview of the reflections that are visible in the
image. Using the buttons and entry fields on the right of the image
display in Ndisp, the scaling can be adjusted.
The image display will be updated only when the "Redisplay" button is pressed.
The colour scheme can be adjusted in the "Options" pull-down menu (see
above for description).
Shortcut Buttons
Six shortcut buttons are displayed:
- Next file
-
Loads the next file in the series (if we are now looking at
s02f005.kcd, "Next file" will load s02f006.kcd).
- Previous file
-
Loads the previous file in the series (if we are now looking at
s02f005.kcd, "Previous file" will load s02f004.kcd).
- Next set
-
Loads the first file in the next series (if we are now looking at
s02f005.kcd, "Next set" will load s03f001.kcd).
- Previous set
-
Loads the first file in the previous series (if we are now looking at
s02f005.kcd, "Previous set" will load s01f001.kcd).
- Redisplay
-
Causes a re-display of the image based on selected filters and
scaling parameters.
- Quit
-
Quit the program.
Mouse cursor
A few text lines below the image displays some information about the
current location of the mouse cursor (either over the main image, or
over any zoom window):
- pixel coordinates
- millimeter coordinates (mmx,mmy) relative to the position where
the primary beam hits the detector at swing=0 (for correct
functioning, this requires calibration by the makedistor and makedetalign programs).
- Diffraction angle theta.
- resolution "d".
When the first mouse button is dragged over the display window, a
black line is drawn. The length of this line in diffraction space is
indicated in the status text as well (in Angstrom and reciprocal
Angstrom units). This can be used to measure the unit cell lengths
manually.
If "Unit Cell" tools are active (see menu "Tools"), the approximate
HKL corresponding to the current mouse position is displayed in those
tools (Please note that this assignment can be very inaccurate if the
rotation angle of the frame is large).
