HKLVIEW (CCP4: Supported Program)


hklview - X-windows program, displays zones of reciprocal space as pseudo-precession images.


hklview [options] [ foo_in.mtz ]


This program displays zones of reciprocal space as pseudo-precession images, on an X-windows terminal, using the xdl_view subroutine library written by John Campbell at Daresbury Laboratory. Spots are represented as squares of size & darkness which depend on intensity (or alternatively amplitude). The program reads an MTZ file containing either:
unmerged intensities, in which case the spots are displayed with their original measured indices (if there are redundant observations, only the last will be drawn). Partially recorded reflections may be summed or ignored.


merged data (usually amplitudes F), in which case the reflections are expanded by the crystallographic symmetry to fill the sphere, i.e. the whole zone will be displayed.

A zone is defined by a vector zvec and a level number zlev, such that the condition for a reflection h lying in the zone is that h . zvec = zlev
For example, zones (hk0), (h0l) & (0kl) are defined by zlev = 0, zvec = (001), (010), (100)

Command line options:

-d <resolution>set resolution limit in A
-c <column label>set column label
-r[awname]don't add .mtz to filename


This may be assigned from the menu option hkl file, or by giving the file name on the command line (i.e. hklview file_name). In either case, the default extension .mtz will be added if absent, unless the command line option -rawname [-r is sufficient] is given.


The display window is divided into 4 main areas: Display Parameter area, Output area, Main menu, Image display area.

The left mouse button is the main pointer, the middle button is used on the image area to control the magnify window, the right button for sub-menu options in the image area.

Display parameter area
This allows a number of parameters affecting the display & other options to be changed. Yes/No toggles can be changed by clicking the left mouse button on the Yes/No button. Numbers & strings can be changed by clicking on the number with the left button, then typing the number, terminated by <cr>. See also more detailed description below.
Output area
This area reports the results of clicking on the image, etc. No input is accepted. See also more detailed description below.
Main menu
Click left button to select an option. See also more detailed description below.
Image display area
In the window area, the left mouse button can be used to select a point or a rectangle by dragging. Clicking on a spot will give the indices hkl, & the intensity (or amplitude) in the Output area. Selected areas may be zoomed by (a) clicking on the Zoom button at the right-hand side of the image display header, then selecting a rectangle, or (b) selecting a rectangle then clicking on the menu option Zoom; click Zoom again to restore the full image.

The middle mouse button controls the magnify window (on the left of the image display header). Clicking the middle button on the magnify window toggles a double size display. Clicking the middle button on the image display freezes the magnify window, allowing pixels in the magnify window to be picked (but not rectangles).

The top right panel of the image display header contains:-

  1. Min & Max image values for the grey level scaling (equivalent to Scale low & high in the parameter area, but less permanent)
  2. Cursor position in pixels. In zoomed images, this is the pixel position in the ZOOMED image, not in the whole image.
  3. Overlay On/Off/Offset menu, toggles display of circle and spot overlays (right button to select)
  4. Contrast slider: controls display contrast (left button)
  5. Colour table selection: probably only Black on white & White on black are useful
    (N.B. "Yellow if >Max" option makes pixels yellow if they are greater than scale-high (=Max) value)
  6. Mag menu: controls magnification in magnify window
  7. PS button: sends image to a Postscript file (after a little dialogue)
  8. Zoom button: click then select rectangle to zoom. Click twice to restore to original


Display parameters

  1. Scale low, high: define scaling range, i.e. the values of an image pixel to be displayed as white or black. The first image displayed will be scaled automatically, and the range may also be recalculated with the Rescale image option in the menu, but you may wish to change this. These numbers are exactly equivalent to the Min/Max numbers on the image panel, but numbers set here will carry over to all images. Use Redraw image option to redisplay image with altered scaling.
  2. Pick area: controls number of pixels displayed by Pick
  3. Outer circle: define resolution (Å) for the outer circle drawn by the Circles option. Default to edge of zone. The actual resolutions of the circles are given in the output area.
  4. Resolution: set outer resolution limit (Å) for storing reflections from the hkl file. If a file is open, it will be reread, & the reflections stored.
  5. Column label: specify the column label for I or F in the file. If this is blank (default), then the first column of type J or F in the file will be used.
  6. Sum partials: only relevant if the hkl file includes partially recorded reflections. Toggle to sum partials or to omit partials (default sum).


  1. Pixel: last pixel hit (Yms, Zms) or 1st corner of rectangle
  2. Resolution: of last pixel hit (in Angstrom)
  3. Spacing: result of Measure option
  4. Zoom factor: if Zoom option used
  5. Circle resolution: resolution of circles drawn by Circles option
  6. Zone normal: vector defining zone direction, e.g. 0 0 1 defines zone hkN, where N is the zone level
  7. Zone level: zone level number
  8. hkl: indices of last hit reflection
  9. F|I sd: stored value of F or I & standard deviation, for last hit reflection.
  10. Batch number, full|partial flag: only for unmerged data
  11. Intensity display | Amplitude displayed: intensity is displayed by default (even if file contains F), but amplitude (F) may be selected from menu
  12. Original indices | Symmetry applied: for unmerged files (M/ISYM column present in file), reflections are drawn according to their original indices. For merged data files, the spacegroup symmetry is used to generate the whole zone.

Main menu

  1. hkl file: give name of hkl file to be read
  2. Reread file: read hkl file again (e.g. after changing column label assignment)
  3. Display F | I: toggle display of spots graded by intensity or amplitude F. Intensity is displayed by default (even if file contains F). Note that the display will not change until a new zone is selected.
  4. Zone normal: define zone normal vector and level, and draw it. A zone is defined by a vector zvec and a level number zlev, such that the condition for a reflection h lying in the zone is that
    h . zvec = zlev
  5. 0kl, h0l, hk0, hhl: choose & draw appropriate zone
  6. Nkl, hNl, hkN: set zone level, choose & draw appropriate zone
  7. Next level, Previous level: increment or decrement zone level, then draw zone. Leave zone normal unchanged.
  8. Level number: set zone level, then draw zone. Leave zone normal unchanged.
  9. Redraw image: redraw without any overlays
  10. Rescale image: reset the scale low & high, & redraw image
  11. Pick: toggle display of figure field around picked point on image.
  12. Measure: toggle measurement of reciprocal lattice spacing. Pick two spots on a reciprocal lattice row (left button), then type number of orders, & the lattice spacing is output in the Output area. Beware skew cells, this gives you 1/a* etc, not a!
  13. Circles: toggle display of resolution circles. The resolution of the outer circle is defined in the parameter table, the resolutions of all the circles is given in the output area.
  14. Axes off | on: click to remove axes & legend, click again to put them back
  15. Zoom: zoom a part of the image. Select an area by dragging a rectangle on the image (left button), then click Zoom. A square area enclosing the selected rectangle will be displayed. Zooming may be repeated. To restore full image, click Zoom when no rectangle is selected. Note that zoom does not recreate the zone image, but just magnifies a part of it.
  16. Exit: exit program




Phil Evans, MRC LMB, Cambridge