Part 1 - JdlView User's Guide

  John W. Campbell

1.1 Introduction

The JdlView objects basically fall into two categories. These are the general purpose JdlView objects which are written without any particular application in mind (e.g the menu area object or the I/O window JdlView object) and those which are written with a particular application or group of applications in mind (e.g. the image view-object)

For applications written using the JdlView manager object, a number of the JdlView objects will be displayed with an 'active strip' area at the top (see below for details) which indicates whether or not the application program is currently ready to receive input from the JdlView object in question. The JdlView objects can however be used independently of any such manager, in which case no active strip will appear.

Many of the JdlView objects use items such as buttons, sliders and choice items which are also part of the JdlView package. These are described in the section entitled 'JdlView Panel Items' below.

List of sections:

The 'Active Strip' Area
The Base Frame JdlView Object
The Menu Area JdlView Object
The Parameter Table JdlView Object
The I/O Window JdlView Object
The Text Table JdlView Object
The Cell Window JdlView Object
The Graphics Window JdlView Object
The Split List JdlView Object
The Progress Bar JdlView Object
The Blank Object JdlView Object
The PXImage JdlView Object
The PX Simulation JdlView Object
The Show Unique Coverage JdlView Object
JdlView Panel Items

1.2 The 'Active Strip' Area

If running under the JdlView manager, JdlView objects which can return data to the program, will normally contain an 'active strip' area. This indicates whether or not the program is waiting for the JdlView object to return data (e.g. a menu selection, text string, spot position etc.) to the program. The active strip consists of a diamond shaped item at the left hand side and a rectangle at the right hand side, usually stretching across the width of the JdlView object. When the program is ready to receive input from the JdlView object, then the diamond is displayed in a cyan colour and a message is displayed in the rectangle. When the program is not waiting to receive input then both parts of the active strip are cleared. A program may be waiting to receive input from more than one JdlView object at a time and from different JdlView objects at different times and hence the reason for indicating to the user the current 'active/inactive' state of any particular JdlView object.

Figure 1: An Active Strip in it's Active State

1.3 The Base Frame JdlView Object

This is just an empty 'top level' window on which other JdlView objects may be laid out. The window manager will usually add a frame of some kind round such a window and its exact appearance will therefore depend on the system on which the program is being run. Frequently the added frame will display a title which has been supplied by the application programmer. Any operations on the base frame (e.g. moving it or resizing it) are functions of the particular window manager which is running.

1.4 The Menu Area JdlView Object

The menu area JdlView object provides an area containing a menu from which items may be selected by the user by means of the mouse. Typically, an application will use the same menu area for a series of different menus. The menu area has an optional title. It also has an optional extra menu item situated below the other menu items and separated from them. This item is typically used either as a 'Quit' item or as an item which will instruct the program to return to the previously displayed menu. The menu area also has an 'active strip' at the top of the area when used in conjunction with the JdlView manager. When the program is waiting for a menu item to be selected then this will display a message e.g. (by default) 'Input Mode'.

Figure 2: Example of a Menu Area JdlView Object


When the menu area is in its 'active' state and the mouse pointer is is within the boundary of a menu item, then that item will be highlighted by displaying the item name in bold print. A menu item is selected by pointing to the item and clicking Button1 of the mouse.

1.5 The Parameter Table JdlView Object

The parameter table JdlView object provides an area containing an editable table of parameter values. The parameter table has an optional title. The table itself consists of one or more columns, each with a number of rows containing a parameter name and a parameter value. (These parameter items are 'Value Items' whose operation is also described in the section on 'JdlView Panel Items below') The parameter table has an 'active strip' at the top when used in conjunction with the JdlView manager to indicate when the entries may be edited; when the program is prepared to service parameter value edits, then a message e.g. (by default) 'Input Mode' is displayed in the active strip. Optionally, a Parameter Table object may be set up to display multiple tables of parameters; in such a case, there will be a coloured oblong indicator displayed at the right hand side of the title area. This is split into segments with one segment for each of the alternative parameter sets. The segment for the currently displayed parameter set is coloured green and the other segments are coloured orange. The alternative parameter sets are selected by clicking the mouse (Button1) on the required segment of the indicator.

An example (with alternative parameter sets) is shown below.

Figure 3: Example of a Parameter Table JdlView Object


When the parameter table is in 'active' mode and the mouse pointer points at an item in the table, then the parameter value for the item may be changed by clicking Button1 of the mouse in the value area of the item. The value string is cleared and a flashing cursor is displayed. The user types in the new value and inputs it to the program by pressing the 'Return' or 'Enter' or key. While a value string is being input, incorrect characters may be deleted using the the 'Delete' or 'Backspace' key. A value string selected/copied on another window may be pasted in by pressing Button2 when the value input is awaited. The user may abandon the input of the new value by pressing the 'Escape' key, in which case, the old value will be restored. If a new value is input, then it will normally be checked by the application program which will decide what course of action is taken. Usually, if an invalid input was given, the program will use the function which causes an Error Dialogue to be displayed. This will contain an error message and the message '** Old value will be replaced **'. To proceed, the user must select the 'OK' box in the dialogue; the old value will then be restored.

When inputting a new parameter value, the parameter table window must have the keyboard focus. It will automatically gain the keyboard focus when the mouse Button1 is clicked to change a parameter value. If required, the keyboard focus may be restored to the window by pointing to the value area and clicking Button1 of the mouse. When the parameter table has the keyboard focus, the cursor in the value area will flash rapidly (at 0.4 second intevals); when it does not have the keyboard focus, the cursor will flash more slowly (at 1.5 second intervals).

Parameter values longer than the displayed value field may be used. In this case the value field may be scrolled by pointing to the value, holding down Button2 and moving it to the left or right within the value field. Moving the pointer to the left will move towards the start of the value string and moving it to the right will move it towards the end of the value string. Button2 is released to finish the scrolling. When the value string extends beyond the displayed field, this is indicated by an arrow mark at the appropriate end or ends. The maximum allowed length for the value string is set under program control.

In some cases, parameter values may be displayed as 'toggle' values. These are either a 'Yes/No' toggle or an 'On/Off' toggle. The toggle value is displayed enclosed in a box. When an item with a toggle value has been highlighted and when Button1 of the mouse is clicked, then the value will switch to its alternative, 'Yes' to 'No' or vice versa or 'On' to 'Off' or vice versa.

Alternatively, some items in the parameter table may have drop down menus associated with them. These have an arrow menu button at the right hand side of the parameter value field. To select a value from the menu, click on the menu button and then click on the required menu item.

A third special type of item may have a step button associated with them. This is indicated by a small pair of up and down arrow buttons. Clicking these buttons enables the user to step up and down through a list of options or values (the exact details depend obviously on the requirement of the program using the option).

Sometimes, the application may choose to emphasise certain items by displaying them in a bold font, perhaps to bring particularly important items to the attention of the user. These emphasised items are treated in exactly the same way as the items in the normal font.

Also, sometimes the application may choose, in certain conditions, to disallow (or freeze) the changing of selected parameter values.

There is also an option to have labels in the parameter table, perhaps introducing a related group of items. These have a name but no value and cannot therefore be selected.

1.6 The I/O Window JdlView Object

The I/O window JdlView object provides an area for the output of text from the program and input of text strings by the user when required (e.g. for a question and answer sequence). The I/O window has an 'active strip' at the top when used in conjunction with the JdlView manager to indicate whether or not the program is waiting for a reply string to be input by the user; when the program is waiting for input, then a message ('Input mode' by default) is displayed in the active strip.

Figure 4: Example of an i/o window JdlView Object


When the program is waiting for the input of a text string, then a text cursor will be displayed at the point where the next character is to be input. The input of a text string is completed by pressing the 'Return' or 'Enter' key. While a text string is being input, it may be edited using the cursor left/right keys or the mouse to set a new cursor position, followed by insertion or addition of characters and/or deletion of characters using the 'Delete' or 'Backspace' keys.

Long text strings will wrap around onto successive lines as needed and the text will scroll up when the bottom of the window is reached.

When inputting the characters of a text string, the I/O window must have the keyboard focus. It will automatically gain the keyboard focus when the text string input is first requested. If required, the keyboard focus may be restored to the window by pointing to the window and clicking Button1 of the mouse. When the I/O window has the keyboard focus, the cursor will flash rapidly (at 0.4 second intevals); when it does not have the keyboard focus, the cursor will flash more slowly (at 1.5 second intervals); also, the message in the active strip, if present, will be be in black if the window has got the keyboard focus or blue if it has not.

When input is requested, previous commands may be recalled by pressing the Up arrow (cursor) key; each press of the key goes one futher back in the previous commands list. Pressing the Down arrow (cursor) key moves forward through the list. The latest 100 commands are stored.

When a reply is to be input, text which has been 'selected' on another or the same window, may be pasted into the reply field by clicking Button2. Note that if the selected text contains more than one line, then only the text up to the first newline character will be pasted in. Text may be 'selected' by pointing to the first character of the text to be selected, holding down Button1, dragging the pointer to the last character of the text to be selected and then releasing Button1. The selected text will be highlighted.

The I/O window object has a scroll bar at the right hand side of the window so that previous contents of the window can be seen after they have scrolled off at the top of the window.

1.7 The Text Table JdlView Object

The text table window JdlView object provides an area for the simple output of text from the program, particularly for tabular data. There is no scrolling. The text may be in bold or normal print in a variety of colours. The program may output text at any character position within the window and areas of the window may be cleared and redrawn as required. A limited series of symbols are also available. There is an option to create a text table with 'active' cells defining areas of text which may be highlighted and, when required, selected using the mouse. In the example figure, the cell highlighting feature has been used to display additional details relating to a selected item from the table.

Figure 5: Example of a Text Table JdlView Object


It may be noted that the text table uses a fixed width character font.

1.8 The Cell Window JdlView Object

The cell window window JdlView object is basically an extended version of the text table JdlView object described above. The additional features are as follows:
Figure 6: Example of a Cell Window JdlView Object


When the command line, if present, has the keyboard focus, the cursor will flash rapidly (at 0.4 second intevals); when it does not have the keyboard focus, the cursor will flash more slowly (at 1.5 second intervals); also, the message in the active strip, if present, will be be in black if the window has got the keyboard focus or blue if it has not.

It may be noted that the cell window object uses a fixed width character font. The functions of this object basically include all those of the text table object but there is a difference in that the cell size used in the text table depends on the size of the fixed font used (and can therefore use a large character size if required) whereas the characters in the cell window object are always fitted into a cell which is eight pixels wide and sixteen pixels deep.

The functions of this object are basically a subset of a further developed object, the JdlView graphics object which has, in addition, options for graphical output and also for printer (/file) output.

1.9 The Graphics Window JdlView Object

The graphics window JdlView object incorporates all the functions of the JdlView cell window object described above. In addition, the main scrolling area may be used for the output of graphics. A number of methods are supplied to give access to a basic set of line plotting functions including drawing of rectangles, polygons and arcs. Filled areas may also be drawn. Symbol, polysymbol and text plotting functions are also available. In addition to the 'cell based' text output as available in the cell window object, text strings may be output using a variety of fonts (not all fixed width) and may be drawn at an angle to the horizontal if required. For plotting graphs, there are two simple axis drawing routines. The object has an optional printer output facility.

Figure 7: Graphics Window Example with a Graph


Figure 8: Graphics Window Example for Music Input


In addition to responding to mouse clicks on 'active' cells and/or buttons/icons, the program may accept input from the mouse when it is outside these areas or from the keyboard.

When used for outputting graphics, a number of options are available for defining the mapping of the user coordinates onto the window and for handling possible re-sizing of the graphics window.

The command line, if present, may be positioned at either the top or the bottom of the window.

A printer icon button will be displayed when the printing option is available. This will be positioned to the right of the command line, if present, or otherwise at the right hand side of the active strip; If no command line or active strip is present, then the printer icon button will be positioned at the right hand side of a blank strip at the top of the window.

When the printer icon button is selected a dialogue window will be displayed allowing various options to be selected.

Figure 9: Print Dialogue


The following choices may be made:

1.10 The Split List JdlView Object

This class provides a titled list which may be split into vertical columns with movable boundaries. The list has a title line and is vertically scrollable. One or more items may be selected from the list as required. The Split List object may have an 'active strip' at the top when used in conjunction with the JdlView manager to indicate whether or not the program is waiting for items to be selected by the user; when the program is waiting for input, then a message ('Input mode' by default) is displayed in the active strip. An example is shown below:

Figure 10: Example of a Split List JdlView Object


When the columns overlap, the right hand columns overlap those to the left. A column boundary is moved by pointing to the boundary line between the columns in the title area. When the cursor has changed, to a form with a pair of vertical lines and arrows pointing to left and right, the boundary may be moved by clicking and dragging with Button1 of the mouse. Columns to the right of the boundary being moved will move with the selected boundary.

A single item may be selected by clicking on its line in the table with Button1 of the mouse. A contiguous set of lines may be selected by clicking on the first required line with the mouse, then holding down the SHIFT key and clicking on the final line of the set of lines to be selected. A non-contiguous set of lines may be selected by holding down the CTRL key while selecting the required individual lines using the mouse. Note that the selection modes actually made available are under program control.

A scrollbar at the right hand side of the split list object enables scrolling up and down the list when it is too long to be shown complete within the window.

Optionally, a horizontal scrollbar may also be displayed at the bottom of the split list object. Drag and drop and copy and paste options may also be used. Drag and drop between split lists should normally only be used between lists with the same number of columns if a transfer in both directions is required.

1.11 The Progress Bar JdlView Object

The progress bar object is used to indicate the progress of a time consuming operation e.g. reading in of a large file or performing a lengthy calculation. The progress bar is a window containing a title and the bar itself. The bar starts as an empty rectangle which is gradually filled in colour as the operation proceeds. The program needs to be able to pass the current degree of progress to the object at reasonably frequent intervals for its use to be effective.

Figure 11: Example of a Progress Bar JdlView Object

1.12 The Blank Object JdlView Object

This is merely a window with a surrounding border similar to that used in other JdlView objects which may be output on a display for aesthetic reasons to indicate the position on a layout which will be occupied by another JdlView object at a later stage.

1.13 The PXImage JdlView Object

This object is designed specifically for displaying X-ray diffraction images used in Protein Crystallography. It may be used for measuring spot positions and has facilities for overlaying symbols, boxes, other vectors or text on top of the displayed image. A magnifying window within the JdlView object shows a magnified version of a portion of the image from the main image display area. The image may also be zoomed in various ways. A control panel allows for a series of adjustments to the display, display of help information, initiation of hard copy (/file) output and access to additional options which may be made available by the calling program.

Figure 12: Example of JdlView PXImage Object


The object has an 'active strip' at the top when used in conjunction with the JdlView manager to indicate whether or not the program is waiting for user input (e.g. selecting a spot); when the program is waiting for input, then a message ('Input mode' by default) is displayed in the active strip.

The main image display area at the bottom of the object displays the image using a gray or colour scale palette. It may also be overlayed by symbols when the program requires it e.g. to mark the image centre position or to display a predicted spot pattern. There are scrollbars to the left and right of the image display and at the bottom of the display. The left hand scrollbar is used to zoom the image (other zoom options are also available). The bottom scrollbar may be used to re-position the view of a zoomed image in a horizontal direction and the right hand scrollbar may be used to re-position the view of a zoomed image in a vertical direcion.

The magnifying window area (top left) shows an enlarged section from a small part of the image in the main display area (magnification may be changed by a Control Panel option - see below). The portion of the image magnified normally follows the cursor position on the main image display area though its position may be frozen (fixed) when required. There is an option for doubling the size of the magnifying window (see Mouse Buttons below). When this is done the magifying window overlays the top left hand corner of the main image display area.

The control panel area is situated at the top right of the object to the right of the magnifying window.

The control panel contains the following panel items:- The PXImage object makes use of a three button mouse (though a single button mouse may be used if necessary - see mouse selection icon button below). The three buttons are used as follows:

Button1

General Use
Use with buttons, scrollbars etc.
User Input
These are basically program dependent but would typically be:
  • Selection of spot positions on main or magnifying window.
  • Selection of an image area.

Button2

This button is used for the control of the magnifying window:
Button3

Image zooming
Thus the image may be zoomed and the position of the zoomed section selected either using the scrollbars or using Button3 of the mouse as described above. When the image is sufficiently zoomed, the pixel intensities will be shown on the image display (for greyscale images).

When the mouse pointer is within the main image display area or within the magnifying window, a special cursor is displayed. This is designed for selecting spot/symbol positions and for visibility either on images with a light or dark background. It consists of a cross made up of dashed lines with alternating black and white segments. The centre of the cross is 'transparent' allowing the underlying image to show through. Two sizes of cursor may be used depending on the capability of the display device.

The label at the top of the control panel displays the current cursor position as a pixel position within the full image as contained in the image data file. The displayed image will frequently have several pixels from the original image compressed into one and may possibly only represent a section of the complete image. When the cursor is outside the main image display area and the magnifying window area, the label displays the message 'Cursor Position'. When an image has been compressed before display then the pixel position is calculated as the one which would be closest to the centre of the pixel selected by the cursor position. The pixel intensity is also shown in brackets following the pixel position.

It may be noted that, when symbols have been overlayed on the main image display area, they will also appear on the magnifying window though they will not be magnified in size. Any other overlayed vectors will be magnified without any thickening of the lines.

If a rectangular area from the main image display is to be selected (under program control), the user points to one corner of the rectangle, presses and holds down Button1 of the mouse and drags it to the opposite corner of the required rectangle. Button1 is then released and the selected rectangle will be returned to the calling program. During the selection, the current state of the rectangle will be outlined on the display. If the user is not happy with the rectangle being selected then the selection can be dismissed by clicking on Button2 before Button1 has been released. Button1 is then released and a new selection may be made.

Control Panel Options

The following paragraphs describe the options which may be selected via the control panel.
  1.   Contrast Slider

    This slider controls the contrast on the displayed image from minimum at the left to maximum at the right hand side of the slider bar. The position is ignored if a user defined colour display has been selected via the colour choice icon button.

  2.  Minimum and Maximum Threshold Values

    Editable minimum and maximum threshold values, for scaling the displayed image, are shown in value items (labels 'Min:' and 'Max:') on the control panel. The range of pixel values between the minimum and maximum values is divided into 255 equal parts for display using the 255 gray or colour levels selected. Pixel values lower than the minimum value are displayed as for the minimum value and pixel values greater than the maximum value are displayed as for the maximum value. The program ensures that the maximum threshold value is at least one greater than the minimum threshold value and also that the minimum and maximum threshold values are within the range of pixel values in the image. Incorrect input values will be reset by the program.

  3.      Mouse Options Icon Button

    The normal operation of the PXImage object is based on the use of a three button mouse. However, if needed, the object may be controlled using a single button by using the mouse options icon button to enable Button1 of the mouse to be used as either Button1, Button2 or Button3. The user will obviously need to switch between these options as required for a particular function.

  4.      Colour Choice Icon Button

    This enables the selection of a number of options for the colouring of the image display. The following choices are available:

    Black on white

    This gives a 255 level gray scale with increasing blackness as the pixel values increase.

    White on black

    This gives a 255 level gray scale with increasing whiteness as the pixel values increase.

    User defined

    The program may set a user defined colour map of 255 colours. This may be changed under program control as needed. The object has a default colour scheme if none has been defined via the calling program.

  5.   --->    Magnification Icon Button

    This enables the selection of the magnifying factor to be used for the magnifying window. The values are from 2 to 8.

  6.          Overlay Icon Button

    This enables the selection of a number of options for the display of overlays (symbols drawn on the image) when present.

    Two different sets options may be presented (under program control). The five icons shown are for the following cases:

    For the first type, the following choices are available:

    on

    The overlayed symbols are displayed on the main image display and on the magnifying window.

    off

    The overlayed symbols are not displayed.

    offset

    The overlayed symbols are displayed on the main image display and on the magnifying window but the symbols of the overlay set 1 are offset by a constant amount from the actual positions to which they refer. This may sometimes be useful when, for example, a predicted pattern is displayed as an overlay. In such a case the predicted pattern symbols would be assigned to overlay set 1 and any symbols marking observed spot positions would be assigned to overlay set 2. By default the offset is to the left and down by 4 pixels in each direction on the main image display area though some programs may set other offsets.

    For the second type , the following choices are available:

    on

    The overlayed symbols are displayed on the main image display and on the magnifying window.

    off

    The overlayed symbols are not displayed.

    overlay 1 symbols on

    Only the symbols belonging to the overlay set 1 are displayed.

    overlay 2 symbols on

    Only the symbols belonging to the overlay set 2 are displayed.

  7.      Background Options Icon Button

    The background image options will only be available if a background image has been calculated. The options are as follows: the image JdlView object. The following choices are available:

    background image included

    The image is presented without any background subtraction being performed.

    background image subtracted

    The background subtracted image is displayed.

    background image only

    The backgound image is displayed on its own.

  8.  Print Icon Button

    This icon button initiates the process of either printing the displayed image (with selected annotation) on the printer or outputting the displayed image to a PNG or JPEG file. When the button is selected a dialogue window is displayed.

    Figure 13: Print Dialogue


    This dialogue box enables the following items/options to be set:

    Title

    The title, if given, will be printed underneath the image.

    Width

    This is the required width of the image plot in cms. The valid range is 0.5 to 18.0 cms.

    Header

    If selected, there will be a header line with the words "Image Plot: " followed by the date.

    Key

    If selected, a key will be printed at the bottom of the page containing details about the image section including its size, orientation, maximum pixel value and scaling thresholds.

    Comment

    If present, the comment text will be output under the title line (centred on the page). It may be split into more than one line if it is too long to fit into a single line.

    The alternative file output may be selected via the JPEG File or PNG File buttons depending on the format required. When one of these is selected, the dialogue box will appear as follows:

    Figure 14: File Output Dialogue


    The required output file name may then be given.

    Note that the printer and/or file output options will not work when the PXImage object is used in an applet unless the appropriate security permissions are in place. This is a general feature of the use of Java Applets.

  9.  Help Icon Button

    This icon button displays a scrollable window which gives 'Help' information on how to use the PXImage object. A brief summary is given on how to use the mouse buttons, how to zoom the image and the functions of the control panel icon buttons is given.

  10.  Menu Icon Button

    This icon button displays a drop down menu which gives access to additional functions. There is one built in function to calculate a background image (see below for details). Other 'User Supplied Options...' are those, if any, which have implemented by the calling program.
The object includes an option to calculate a background image which may then be used for the background subtracted or background image only displays. It is accessed via the menu option icon button followed by the selection of the 'Calculate Background Image' item from the displayed menu. The following dialogue box is then displayed enabling a few parameters to be set before calculating the background image.

Figure 15: Dialogue Box for Background Image Calculation


The method used assumes an image with spots over a fairly slowly changing background. The procedure calculates the background at a pixel by taking the average of the lowest pixel values in a box surrounding the pixel such that the number of such values is a requested percentage of the total number of pixels in the box. To optimise the calculation, the box is walked through the image moving a pixel at a time starting at the top left. It then repeats the process of left from to right, then one pixel down, then from right to left, and then one pixel down etc. until the image has been covered. (In this description the slow moving image index is visualised as being from top to bottom and the fast one from left to right). The methods will cope with a maximum background level up to around 65000. To speed up the calculation the image is normally based on a compressed image. The following values may be selected for the calculation:

Background image compression factor

Compress (sample) this number of pixels into 1 pixel in each direction for background image.

Box size (pixels - compressed image)

Size, in pixels, of box (after compression of the image) for each background calculation - preferably an odd number.

Percentage of pixels for background

Percentage of pixels within a box to treat as background. If minus the required percentage value is given is given, then pixel values of zero will be omitted from the calculation.

The overlay symbols are either vertical crosses, diagonal crosses or squares which may be drawn in a range of different sizes using up to six different colours. Options are also available for overlaying boxes and other vectors on the image using the same six colours.

Facilities are available within the PXImage object and related software to enable input of image data in any of the eight possible orders and to display it with the axes again in any of the eight possible combinations. When several pixels are combined into one then, under program control, the contributing pixels may either be averaged or just sampled.

1.14 The PX Simulation JdlView Object

This JdlView object was written for a specific use relating to Protein Crystallography. It is used for displaying simulations of monochromatic rotation image X-ray diffraction patterns, Weissenberg patterns or Laue Diffraction patterns. Laue images may also be displayed as Gnomonic projections. There two modes of display, a standard mode and an interactive mode, both of which use colour codings to represent different classes of spots. In each mode there is a display area for the simulation, an area to list details of a selected spot, a control panel area where various options may be selected. The selection of Rotation/Weissenberg/Laue options is under program control (e.g. Depending on the value of the diffraction type parameter in the program PXSim). The following links show some examples:

Figure 16: Example of a Standard Colour Rotation Simulation


Figure 17: Example of an Interactive Rotation Simulation


Figure 18: Example of a Standard Colour Laue Simulation


Figure 19: Example of an Interactive Laue Simulation


Figure 20: Example of a Laue Gronomic Projection Simulation


As far as using the PX Simulation JdlView Object is concerned, the Rotation and Weissenberg options are identical.

Before describing the detailed options for the various cases, some features, common to all cases, are described:

Mouse Buttons

The PX Simulation object assumes the use of a three button mouse (though a single button mouse may be used if necessary - see mouse selection icon button below). Button2 is not currently used. The buttons are used as follows:

Button1
General Use

Use with buttons, scrollbars etc.

Spot Selection

Click on a spot for which details are to be listed. Click away from the spot to remove the selection.

Spot labelling

For interactive colour plots only. To label a spot do the following:
  • Point to spot and hold down Button1
  • Drag away from spot to required label position
  • Release Button1
Move Label

(For interactive colour plots only) To move a label hold down Button1 on the label, drag the label to the new position and release Button1.

Remove Label

(For interactive colour plots only) Double click Button1 on the label.
Button3

Image zooming
  • Single click to re-centre on selected pixel.
  • Select an area (point to one corner, hold down button, drag to other corner and release button). The zoom factor will be the nearest available value possible and the aspect ratio of the displayed portion of the image will remain unchanged.
  • Double click will restore the image to its original (un-zoomed) state
  • When the image is zommed, hold down the SHIFT key and press Button3 to show the un-zoomed image with the zoomed area marked. Releasing the button returns to the zoomed image display.

Control Panel

The common items on the control panel are as follows:

  1.   Mode Button

    This button toggles between the standard colour display and the interactive colour display. (For Laue simulations, where gnomonic projections have been calculated, the mode button will step through the standard and interactive simulations first for the normal pattern and then for the gnomonic projection).

  2.    Mouse Options Icon Button

    The normal operation of the PX Simulations object is based on the use of a three button mouse. However, if needed, the object may be controlled using a single button by using the mouse options icon button to enable Button1 of the mouse to be used as either Button1, or Button3 (Button2 not currently used). The user will obviously need to switch between these options as required for a particular function.

  3.  Help Icon Button

    This icon button displays a scrollable window which gives 'Help' information on how to use the PX Simulations object. A brief summary is given on how to use the mouse buttons, how to zoom the image and the functions of the control panel icon buttons is given.

  4.  Print Icon Button

    This icon button initiates the process of either printing the displayed simulation (with selected annotation) on the printer or outputting the displayed pattern to a PNG or JPEG file. When the button is selected a dialogue window is displayed.

    Figure 21: Print Dialogue



    This dialogue box enables the following items/options to be set:

    Title

    The title, if given, will be printed underneath the simulated pattern.

    Width

    This is the required width of the simulated pattern plot in cms. The valid range is 0.5 to 18.0 cms.

    Header

    If selected, there will be a header line showing the type of plot followed by the date.

    Key

    If selected, a key will be printed at the bottom of the page containing details about the parameters on which the predicted simulation was based.

    Black bg

    If selected, the page will be printed with a black background with any text required being output in a light colour.

    Comment

    If present, the comment text will be output under the title line (centred on the page). It may be split into more than one line if it is too long to fit into a single line.

    The alternative file output may be selected via the JPEG File or PNG File buttons depending on the format required. When one of these is selected, the dialogue box will appear as follows:

    Figure 22: File Output Dialogue


    The required output file name may then be given. Note that, with these type of plots with sharp features and a limited number of colours, the PNG files provide a higher quality output than JPEG files.

    Note that the printer and/or file output options will not work when the PXImage object is used in an applet unless the appropriate security permissions are in place. This is a general feature of the use of Java Applets.

Scrollbars

There are scrollbars to the left and right of the simulated pattern display and at the bottom of the display. The left hand scrollbar is used to zoom the pattern (other zoom options are also available). The bottom scrollbar may be used to re-position the view of a zoomed pattern in a horizontal direction and the right hand scrollbar may be used to re-position the view of a zoomed pattern in a vertical direcion.

Zooming

The two methods for zooming in on the pattern have already been described. These are the use of the scrollbars and the use of Button3 of the mouse.

Rotation and Weissenberg Simulations

Laue Simulations

1.15 The Show Unique Coverage JdlView Object

This is a special purpose object for use within the field of Protein crystallography. It is used to display, in pictorial or graphical form, the coverage of the unique part of the reciprocal lattice by the currently predicted and/or measured data. There are basically three options:
The object may be used to display unique data derived from either Rotation or Laue data. In the former case reflections may be categorized by whether or not they were fully recorded and in the latter case whether they were single reflection spots or deconvoluted from multiple spots.

In each case, there is a main display area on which the data is displayed and a control panel area at the top which enables various options to be selected. On each control panel, there is a 'Mode' button which is used to step through the three types of display. The three cases are described in detail below:
  1. Display of Reciprocal Lattice Layers

  2. The main display area shows a single section of the reciprocal lattice at a time showing which reflections are part of the unique area of the reciprocal lattice and which of these reflections have been predicted or observed. An example is shown below:

    Figure 23: Unique Coverage - Layers


    Different categories of reflections e.g. fulls, singles, partials or deconvoluted multiples may be included in the plot and, where appropriate, merged or unmerged anomalous data pairs may be indicated. Spots predicted as spatial overlaps may be included or excluded as desired. Spots which are classified as unknown full/partial/single/multiple (e.g. derived from a merged dataset) are included in the display as fully recorded or single (and non-spatially overlapped) spots. If anomalous separated data is displayed then these spots may also be of unknown sign (see below for colour coding). In all cases the section axis is along 'l'. On the l=0 section the a* and b* axes are displayed. The points on the unique part of the reciprocal lattice are marked by small greenish dots for those spots which have not been predicted/measured.

    The following options are available via the control panel (the case for the Rotation data case is shown first with any variation for the Laue case following in square brackets):

    Fulls [Singles]

    The options are for fulls [singles] to be included or excluded.

    Partials [Mults]

    For partials the options are as follows:
    • none.
    • partiality = 2 partials only included.
    • partiality <= 3 partials only included.
    • partiality <= nwmax partials included (nwmax is a parameter from the Diffraction Data Module (DDM)).


    [For deconvoluted multiples the options are as follows:
    • none.
    • deconvoluted from multiplicity = 2 only included.
    • deconvoluted from multiplicity <= 3 only included.
    • deconvoluted from any multiple.]


    Anom

    The options are as follows:
    • merged.
    • separate.
    • both I+ and I- measurements made.
    • I+ measurement made.
    • I- measurement made.

    For merged data, all measured reflections are shown as yellow spots. For the other cases, the colour coding is as follows:
    • yellow: Both an I+ and an I- reflection are present.
    • red: Only the I+ reflection is present.
    • blue: Only the I- reflection is present.
    • white : Unknown sign (i.e. both I+ and I- are not present though I+ or I- may be present in addition to measurements flagged as being of unknown sign.

    Spatials

    Spatially overlapped spots may be either included or excluded.

    Up and Down buttons and Slider

    Clicking on one of these buttons moves up or down one layer of the reciprocal lattice. The slider between the buttons enables rapid access to the different layers though, if there are a large number of layers, a final adjustment may be needed using the Up/Down buttons to get to the exact layer required. The current layer number is shown at the bottom left of the plot.

    Cycle button and Slider

    Clicking the Cycle button will start/stop automatically cycling through the layers. The speed of the cycling may be adjusted using the slider to the left of the Cycle button.

    Printer Icon Button

    This initiates the output of the plots to a printer or a file. Details are given below.

  3. 3D Unique Coverage Plot

  4. In this case, the main display area shows a three dimensional perspective view of the unique section of the reciprocal lattice. The picture indicates by colour coded dots which of these reflections have been predicted or observed. This view may be rotated automatically or its orientation changed by means of a slider. An example is shown below:

    Figure 24: Unique Coverage - 3D Plot


    Different categories of reflections e.g. fulls, singles, partials or deconvoluted multiples may be included in the plot and, where appropriate, merged or unmerged anomalous data pairs may be indicated. Spots predicted as spatial overlaps may be included or excluded as desired. Spots which are classified as unknown full/partial/single/multiple (e.g. derived from a merged dataset) are included in the display as fully recorded or single (and non-spatially overlapped) spots. If anomalous separated data is displayed then these spots may also be of unknown sign (see below for colour coding). The a* and b* axes are displayed in the horizontal plane an c* is in an upwards direction. The points on the unique part of the reciprocal lattice are marked by small greenish dots for those spots which have not been predicted/measured.

    The following options are available via the control panel (the case for the Rotation data case is shown first with any variation for the Laue case following in square brackets):

    Fulls [Singles]

    The options are for fulls [singles] to be included or excluded.

    Partials [Mults]

    For partials the options are as follows:
    • none.
    • partiality = 2 partials only included.
    • partiality <= 3 partials only included.
    • partiality <= nwmax partials included (nwmax is a parameter from the Diffraction Data Module (DDM)).
    [For deconvoluted multiples the options are as follows:
    • none.
    • deconvoluted from multiplicity = 2 only included.
    • deconvoluted from multiplicity <= 3 only included.
    • deconvoluted from any multiple.]


    Anom

    The options are as follows:
    • merged.
    • separate.
    • both I+ and I- measurements made.
    • I+ measurement made.
    • I- measurement made.


    For merged data, all measured reflections are shown as yellow spots. For the other cases, the colour coding is as follows:
    • yellow: Both an I+ and an I- reflection are present.
    • red: Only the I+ reflection is present.
    • blue: Only the I- reflection is present.
    • white : Unknown sign (i.e. both I+ and I- are not present though I+ or I- may be present in addition to measurements flagged as being of unknown sign.

    Spatials

    Spatially overlapped spots may be either included or excluded.

    Up and Down buttons and Slider

    Clicking on one of these buttons moves the viewing angle of the three dimensional plot up or down 5 degrees at a time up to a maximum view angle of plus or minus 45 degrees. The slider between the buttons enables the 3D plot to be rotated to any of the positions within the possible 360 degrees of rotation.

    Cycle button and Slider

    Clicking the Cycle button will start/stop automatically rotating the 3D view of the reciprocal lattice. The speed of the rotation may be adjusted using the slider to the left of the Cycle button.

    Printer Icon Button

    This initiates the output of the plots to a printer or a file. Details are given below.

  5. Unique Coverage Histograms

  6. In this case, the main display area shows one of a series of histograms. These are all plots against resolution. The requested resolution range is divided into eight equal bins of 4.sin**2(theta)/lambda**2. An example is shown below:

    Figure 25: Unique Coverage - 3D Plot


    Different categories of reflections e.g. fulls, singles, partials or deconvoluted multiples may be included in the plots.

    The three types of histogram available are as follows:
    :
    1. Unique Data

      This plot shows the percentage of coverage of the unique data within each resolution bin. Where partials [deconvoluted multiples] are included two coloured bars are drawn, an orange one indicating the coverage for the full [single] reflections and an additional green section showing the coverage with the included partials [deconvoluted multiples]. The overall percentage coverage for each of these cases is given at the top of the plot. Where no partials [deconvoluted multiples] are included, an orange bar shows the coverage for the fulls [singles] data and the overall coverage by the fulls [singles] data is given at the top of the plot.

    2. Acentric Pairs

      This plot shows the percentage coverage of the unique acentric data within each resolution bin. A reflection must be present for each mate of a Bijvoet pair to be included. Where partials [deconvoluted multiples] are included in the analysis, two coloured bars are drawn, an orange one indicating the coverage for the full [single] reflections and an additional green section showing the coverage with the included partials [deconvoluted multiples]. The overall percentage coverage for each of these cases is given at the top of the plot. Where no partials [deconvoluted multiples] are included, an orange bar shows the coverage for the fulls [singles] data and the overall coverage by the fulls [singles] data is given at the top of the plot. Reflections of unknown sign are excluded from the analyses of acentric pairs.

    3. Multiplicity

      This plot shows the average reflection measurement multiplicity within each resolution bin. This refers to the number of times each reflection was measured and not, in the case of Laue data, to the multiplicity of individual spots (multiples). Where partials [deconvoluted multiples] are included, two coloured bars are drawn, an orange one indicating the multiplicity for the full [single] reflections and an additional green section showing the multiplicity with the included partials [deconvoluted multiples]. Note: It can happen in some cases that the multiplicity in a resolution bin decreases when partials [deconvoluted multiples] data are included as there will be additional reflections which could have any multiplicities; in such cases, a green line will be drawn through the orange bar at the appropriate height. The overall average multiplicity for each of these cases is given at the top of the plot. Where no partials [deconvoluted multiples] are included, an orange bar shows the multiplicity for the fulls [singles] data and the average multiplicity for the fulls [singles] data is given at the top of the plot.

    The following options are available via the control panel (the case for the Rotation data case is shown first with any variation for the Laue case following in square brackets):

    Fulls [Singles]

    The options are for fulls [singles] to be included or excluded.

    Partials [Mults]

    For partials the options are as follows:
    • none.
    • partiality = 2 partials only included.
    • partiality <= 3 partials only included.
    • partiality <= nwmax partials included (nwmax is a parameter from the Diffraction Data Module (DDM)).
    [For deconvoluted multiples the options are as follows:
    • none.
    • deconvoluted from multiplicity = 2 only included.
    • deconvoluted from multiplicity <= 3 only included.
    • deconvoluted from any multiple.]

    Type

    This selects the type of histogram to be displayed.The options are as follows:
    1. Unique.
    2. Acentric Data.
    3. Multiplicity.

    Spatials

    Spatially overlapped spots may be either included or excluded.

    Printer Icon Button

    This initiates the output of the plots to a printer or a file. Details are given below.

Printer/File Output

When the printer icon button is selected a dialogue window is displayed, for example as follows:

Figure 26: Print Dialogue


The 'Multiple' check box is only present for the first type of unique data coverage plot (Reciprocal Lattice Layers). In general, the dialogue box enables the following items/options to be set:

Title

The title, if given, will be printed underneath the displayed plot.

Width

This is the required width of the simulated pattern plot in cms. The valid range is 0.5 to 18.0 cms.

Header

If selected, there will be a header line showing the type of plot followed by the date.

Multiple

This is only present for the Reciprocal Lattice Layers type of plot. If selected, this enables the output of a plot with a whole series of layers shown (up to 9 per page). The dialogue changes in that the 'Header' and 'Width' options are removed but there is instead a 'Layers or All' option. In this, the user may give a list of layer numbers and/or ranges of layers (e.g. 1, 2, 3, 10-20, 25) or the code 'All' (the initial default) for all layers.

Black bg

If selected, the page will be printed with a black background with any text required being output in a light colour.

Comment

If present, the comment text will be output under the title line (centred on the page). It may be split into more than one line if it is too long to fit into a single line.

The alternative file output may be selected via the JPEG File or PNG File buttons depending on the format required. When one of these is selected, the dialogue box will appear as follows:

Figure 27: File Output Dialogue


The required output file name may then be given. Note that, with these type of plots with sharp features and a limited number of colours, the PNG files provide a higher quality output than JPEG files.

Note that the printer and/or file output options will not work when the PXImage object is used in an applet unless the appropriate security permissions are in place. This is a general feature of the use of Java Applets.

1.16 JdlView Panel Items

The panel items are objects which are used in the coding of the higher level JdlView objects to provide items like labels, buttons, sliders etc. Not all of them require user input, but for those that do, their use is described in this section.

The following figure shows the available panel items (though not all variations are shown):


Figure 28: JdlView Panel Items


These are used as follows:
  1. Labels

    These may be used to output text or labels with an image or drawn picture. They have no user input.

  2. Buttons

    There are buttons of various shapes and an up-down arrow pair button. All respond to a mouse Button 1 click though the diamond button, for example, can be used as an indicator by a program (using its in and out states), in which case it does not accept user input.

  3. Value Item

    The basic value item (a) displays a parameter name (label) at the left hand side and a value field at the right hand side. When the value field has been selected (click on it with Button 1 of the mouse), a new value may be input. A cursor in the value field indicates that value input is in progress. The value field must have the keyboard focus to receive input; this is automatically requested when the value field is first selected and if it is lost the user needs to click Button 1 on the value field again. When the value field has the keyboard focus, the cursor flashes on and off at 400 ms intervals which increase to intervals of 1.5 seconds when the focus is lost. Selected text may be pasted in to the value field using by clicking Button 2 of the mouse when the selected value field has the keyboard focus. Pressing the Return or Enter keys on the keyboard completes the input of the new value. If the Escape key on the keyboard is pressed, the value input will be aborted and the previous value restored. If a value is too long to be displayed then a scroll arrow will be shown at one end of the value field. Dragging the mouse Button 2 along the field will let the user scan the full value string (to the left moves the view towards the start of the string and to the right moves the view towards the end of the string).

    A version (b) with a drop down menu may also be used. If the arrow button is selected (Button 1 click) a pop-up menu will be displayed with a choice of values. A value is selected from this menu by clicking Button 1 on the required item. If Button 1 is clicked with the pointer not on the menu, the menu will be removed without any change to the value. Normally, when a value item has a menu option available, a new value may be input as for the standard case described above; however, there is an option to allow only value changes via the menu and in this case the button will be highlighted in blue if an attempt is made to change the value by selecting the value field.

    A version (c) with an up/down button pair is also available. This enables the user to step up and down though a series of values as implemented by the calling program. When this option is available, a new value may still be input as for the standard case described above.

    A version (d) may be used for parameters which toggle between on/off values or yes/no values. In this case, selecting the value field will change the value to its opposite value.

    Occasionally a value item may be used, without a value field, as a label. This may be used, for example, in the parameter table object. When in this state, there is no user input.

  4. Slider

    The slider enables a value to be selected from a value range. The value is changed by pointing to the slider grip, holding down Button 1 of the mouse and dragging it to the left or right as required and then releasing the mouse button when the required position is reached. Note that the program using the slider may choose to make continuous adjustments while the slider grip is being dragged or may wait until the grip is released before responding to the new value

  5. Separator

    This is just used to separate items on a display. There is no user input.

  6. Scrollbar

    The scroll bar item may be used to scroll though a window or as another form of slider. The slider is moved by dragging the grip as for the slider item described above. In addition, the program can respond to clicking Button 1 on an end arrow of the scrollbar item (usually to make a minimum increment in the scrolled value) or on 'empty space' between the grip and an end arrow to make (usually to make a larger increment in the scrolled value). As for the slider, the program may choose to respond continuously to the movement of the grip or to respond only when the grip is released.

    To make it clear when the mouse pointer is on a scrollbar, it is changed to a special form as shown to the right of the scrollbar in the figure.

  7. Command Line

    This allows for the output of a prompt followed by the input of a text string (all on a single line. When input is expected, a text cursor will be displayed. The input field must have the keyboard focus to receive input; this is automatically requested when the input is first requested and if it is lost the user needs to click Button 1 on the input field again. When the input field has the keyboard focus, the cursor flashes on and off at 400 ms intervals which increase to intervals of 1.5 seconds when the focus is lost. Selected text may be pasted in to the value field using by clicking Button 2 of the mouse when the input field has the keyboard focus.


⇑ Up 2   ⇑ Up 1   ⇑ Top of this