4.3.2 - Diffraction Data Module Class - JdlDiffractionDataModule

John W. Campbell

4.3.2.1 Introduction

This class provides a Java implementation of a Diffraction Data Module (DDM). The DDM parameters form a set of parameters required primarily to predict the positions of reflections for rotation or Laue X-Ray diffraction patterns of protein crystals. The handling of DDM data is done using the general purpose JdlKeywordDataModule class keyworded data handling and storage mechanism. Details of the DDM parameters themselves are documented separately.

Class, constructors and methods:

Class Details
Accessible Fields
Constructor
Read DDM Data
Set DDM Parameter Values
Get DDM Parameter Values
Rotation Range Methods
Write DDM file
JdlView Parameter Table

4.3.2.2 Class Details

Package:
Jdl.JdlPX;
Class name:
JdlDiffractionDataModule
Class definition:
public class JdlDiffractionDataModule
Extends:
Object
Implements:
JdlStringWriter
Actions:
none

4.3.2.3 Accessible Fields

No fields with public, package or protected access defined.

4.3.2.4 Constructor

4.3.2.4.1 Introduction

There is a single constructor for creating a JdlDiffractionDataModule object.

Constructor:

Standard Constructor

4.3.2.4.2 Standard Constructor

The constructor sets up a JdlDiffractionDataModule object specifying limits for the maximum number of sets (crystal sets) and sub-sets (images/crystal set) which may be held.

Constructor Definition:
public JdlDiffractionDataModule (int max_sets, int max_images, int max_ranges)
Parameters List:
max_sets
Maximum number of crystal sets allowed.
max_images
Maximum number of images allowed for each crystal set.
max_ranges
The maximum number of Rotation/Laue start/end of range parameters (ROTSTART, ROTEND)

4.3.2.5 Read DDM Data

4.3.2.5.1 Introduction

This section has methods to read DDM data from a keyworded DDM file.

Methods:

Read DDM file - readDDMFile
Read DDM file - readDDMFile

4.3.2.5.2 Read DDM file - readDDMFile

This method reads an DDM data file given its file or URL name.

Method Definition:
public boolean readDDMFile (String filnam, JdlError jerr)
Parameters List:
filnam
The file or URL name of the DDM keyworded data set.
jerr
If an error was found 'jerr.err' is set to true, an error message is returned in 'jerr.msg1' and 'jerr.flag' is set as follows:
= -4, Access control exception
= -3, Malformed URL Exception
= -2, File not found
= -1, File reading error
= 1, Error reading DDM file
= 100, Non-DDM data found (In this case 'jerr.err' is false)
Method Return:
Returns true if OK (note that jerr.flag may be set to 100), or false if an error was found (see jerr above for details).

4.3.2.5.3 Read DDM file - readDDMFile

This method reads M data from an open buffered reader.

Method Definition:
public boolean readDDMFile (BufferedReader bsr, JdlError jerr)
Parameters List:
bsr
The BufferedReader object for the DDM data file.
jerr
If an error was found 'jerr.err' is set to true, an error message is returned in 'jerr.msg1' and 'jerr.flag' is set as follows:
= 1, Error reading DDM file
= 100, Non-DDM data found (In this case 'jerr.err' is false)
Method Return:
Returns true if OK, or false if an error was found (see jerr above for details).

4.3.2.6 Set DDM Parameter Values

4.3.2.6.1 Introduction

This section has a series of methods to set the values of DDM parameters. The specific method required depends on the parameter type.

Methods:

Set a value - setValue
Set string parameter - setStringValue
Set integer parameter - setIntegerValue
Set integer parameter - setIntegerValue
Set double parameter - setDoubleValue
Set double parameter - setDoubleValue
Set double parameter - setDoubleValue
Set double parameter - setDoubleValue
Set cell - setCell
Set symmetry - setSymmetry
Reset defaults - resetDefaults
Clear rotation range - clearRotationRange

4.3.2.6.2 Set a value - setValue

This method sets a DDM parameter value from a given value in String form.

Method Definition:
public boolean setValue(String name, int iset, int imgnum, int irange, String valstr, JdlError err)
Parameters List:
name
The full parameter (keyword) name.
iset
Set number, 0=all sets - ignored for single value type parameters.
imgnum
The image number within the given rotation range (0=all images in all ranges). If irange is 0 then imgnum is the overall image position. If the parameter is not an image based parameter, then a value of 0 or 1 should be given.
irange
The rotation range number.
valstr
The parameter value (or values) as a string - ignored if iopt=1.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -100, No keyword parameters defined
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.3 Set string parameter - setStringValue

This method sets the value of a dataset based string parameter.

Method Definition:
public boolean setStringValue (String name, String valstr, JdlError err)
Parameters List:
name
The parameter name. (May be: TITLE, TYPE, SYSTEM, LATTICE)
valstr
The parameter value string.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.4 Set integer parameter - setIntegerValue

This method sets the value of a dataset based integer parameter.

Method Definition:
public boolean setIntegerValue (String name, int ival, JdlError err)
Parameters List:
name
The parameter name. (May be: NUMSETS)
ival
The parameter value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.5 Set integer parameter - setIntegerValue

This method sets the value of a set based integer parameter.

Method Definition:
public boolean setIntegerValue (String name, int iset, int ival, JdlError err)
Parameters List:
name
The parameter name. (May be: CRYSTAL_NUMBER, IAX_H, IAX_V, IMAGE_RECL, IMAGE_HEADER, NULL_PIXEL, OVLD_PIXEL, NXRASTS, NYRASTS, NWMAX)
iset
The set number, 0 = all sets.
ival
The parameter value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.6 Set double parameter - setDoubleValue

This method sets the value of a set based double parameter.

Method Definition:
public boolean setDoubleValue (String name, int iset, String valstr, JdlError err)
Parameters List:
name
The parameter name. (May be: RMAX, TAU_X, TAU_Y, TAU_Z, DET_GAIN, WAVELENGTH, DISPERSION, DIVV, DIVH, DELCOR, POLARISATION, PIX_X, PIX_Y, TWOTH_MIN, RMIN, R_XCEN, R_YCEN, X_MIN, X_MAX, Y_MIN, Y_MAX, A, B, C, ALPHA, BETA, GAMMA, PHI_ORIENT, ROTSTART, ROTEND, ANGLE_INC/ANGLE_OSC, SPOT_SIZE)
iset
The set number, 0 = all sets.
valstr
The parameter value as a string.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.7 Set double parameter - setDoubleValue

This method sets the value of a set based double parameter.

Method Definition:
public boolean setDoubleValue (String name, int iset, double val, boolean upd_nd, JdlError err)
Parameters List:
name
The parameter name. (May be: RMAX, TAU_X, TAU_Y, TAU_Z, DET_GAIN, WAVELENGTH, DISPERSION, DIVV, DIVH, DELCOR, POLARISATION, PIX_X, PIX_Y, TWOTH_MIN, RMIN, R_XCEN, R_YCEN, X_MIN, X_MAX, Y_MIN, Y_MAX, A, B, C, ALPHA, BETA, GAMMA, PHI_ORIENT, ROTSTART, ROTEND, ANGLE_INC/ANGLE_OSC, SPOT_SIZE)
iset
The set number, 0 = all sets.
val
The parameter value.
upd_nd
If true, update the number of decimal places flag to the default value for the parameter; if false, leave at current value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.8 Set double parameter - setDoubleValue

This method sets the value of a set and image based double parameter.

Method Definition:
public boolean setDoubleValue (String name, int iset, int imgnum, int irange, String valstr, JdlError err)
Parameters List:
name
The parameter name. (May be: DISTANCE, RESOLUTION, MOSAICITY, PHI_X, PHI_Y, PHI_Z, LAMBDA_MIN, LAMBDA_MAX, SPOT_SIZE, X_CEN, Y_CEN, X_C, Y_C, W_C, TWIST, TILT, ROFF, TOFF, Y_SCALE)
iset
The set number (>= 1) - May give 0 for all sets if imgnum is also 0.
imgnum
The image number within the given rotation range (0=all images in all ranges).
irange
The rotation range number.
valstr
The parameter value as a string.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.9 Set double parameter - setDoubleValue

This method sets the value of a set and image based double parameter.

Method Definition:
public boolean setDoubleValue (String name, int iset, int imgnum, int irange, double val, boolean upd_nd, JdlError err)
Parameters List:
name
The parameter name. (May be: DISTANCE, RESOLUTION, MOSAICITY, PHI_X, PHI_Y, PHI_Z, LAMBDA_MIN, LAMBDA_MAX, SPOT_SIZE, X_CEN, Y_CEN, X_C, Y_C, W_C, TWIST, TILT, ROFF, TOFF, Y_SCALE)
iset
The set number (>= 1) - May give 0 for all sets if imgnum is also 0.
imgnum
The image number within the given rotation range (0=all images in all ranges).
irange
The rotation range number.
val
The parameter value.
upd_nd
If true, update the number of decimal places flag to the default value for the parameter; if false, leave at current value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.10 Set cell - setCell

Convenience method to set all cell parameters.

Method Definition:
public boolean setCell(JdlCell cell, int iset, boolean upd_nd, JdlError err)
Parameters List:
cell
The JdlCell cell object.
iset
The set number (>= 1) - May give 0 for all sets if imgnum is also 0.
upd_nd
If true, update the number of decimal places flags to the default values for the parameters; if false, leave at current value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -1, Invalid set number
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

4.3.2.6.11 Set symmetry - setSymmetry

This method enables the symmetry to be set for a given space group number or name (or add the specified symmetry operator)

Method Definition:
public void setSymmetry (String valstr, JdlError err)
Parameters List:
valstr
Space group number or name as a String (as in the CCP4 'symop.lib' file or a symmetry operator or 'end'. The string "undef" may also be given to set the symmetry to 'undefined'. If an error occurs, the symmetry will remain unchanged.
err
Error return object. If an error was found 'err.err' will be returned as true, error messages will be set in 'err.msg1' (and 'err.msg2') and the flag 'err.flag' will be set as follows:
= 0, OK
= 1, Specified space group not found or data incomplete in stored symmetry data (JdlSymops)
= 2, Error in symmetry operator
= -1, No symmetry data given

4.3.2.6.12 Reset defaults - resetDefaults

This method may be used to set default values for a selected parameter or for all parameters.

Method Definition:
public boolean resetDefaults (String name, int iset, int isubset, boolean reset_var)
Parameters List:
name
Parameter name (null/blank string means all parameters).
iset
Set number, 0=all sets - ignored for single value type parameters.
isubset
Subset number, 0=all subsets - ignored for single value or set type parameters.
reset_var
If true set current number of values back to 1 for integer or double parameters which may have a variable number of values (suffixed parameters).
Method Return:
true OK, false error: parameter not found or invalid set/subset number.

4.3.2.6.13 Clear rotation range - clearRotationRange

This method enables one or more rotation ranges to be unset/cleared.

Method Definition:
public void clearRotationRange(int iset, int irange)
Parameters List:
iset
Set number (0 = all sets);
ir
The rotation range number for which the ROTSTARTn and ROTENDn parameters are to be cleared (2 or more). If 0 is given then these parameters will be unset/cleared for all rotation ranges except the first. (The values are set to -1000.0 which can only be set by restoring default values)

4.3.2.7 Get DDM Parameter Values

4.3.2.7.1 Introduction

This section has a series of methods to return the values of DDM parameters. The first few methods return individual parameter values depending on the parameter type and the later methods return complete groups of data in arrays or specially defined objects which may be used in a variety of Protein Crystallography related calculations.

Methods:

Get value string - getValueString
Get string parameter - getStringParameter
Get string parameter - getStringParameter
Get integer parameter - getIntegerParameter
Get integer parameter - getIntegerParameter
Get double parameter - getDoubleParameter
Get suffixed double parameter - getSuffixedDoubleParameter
Get double parameter - getDoubleParameter
Get pattern centre - getPatternCentre
Get pixel dimensions in mm. - getPixelDimensions
Get detector rotations - getDetectorRotations
Get detector axes - getDetectorAxes
Get scan axis - getScanAxis
Get U-matrix - getUMatrix
Get crystal system - getSystem
Get lattice type - getLattice
Get detector basics - getDetectorBasics
Get positioned detector - getPositionedDetector
Get X-ray source - getXraySource
Get cell - getCell
Get positioned crystal - getPositionedCrystal
Get orientation matrix - getOrientationMatrix
Get detector limits - getDetectorLimits
Get symmetry - getSymmetry
Get KDM reference - getKDM

4.3.2.7.2 Get value string - getValueString

This method returns the value for any parameter as a string.

Method Definition:
public String getValueString(String name, int iset, int imgnum, int irange, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>= 1) if a set or set/image based parameter.
imgnum
The image number within the given rotation range (or overall position if irange = 0) for a set and image based parameter.
irange
The rotation range number for a set and image based parameter.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= -2, Parameter may not be suffixed = -3, Parameter suffix out of current range = 1, Invalid set/subset number
Method Return:
The parameter value as a string.

4.3.2.7.3 Get string parameter - getStringParameter

This method returns the value of a dataset based string parameter.

Method Definition:
public String getStringParameter (String name, JdlError err)
Parameters List:
name
The parameter name. (May be: TITLE, TYPE, SYSTEM, LATTICE)
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value string.

4.3.2.7.4 Get string parameter - getStringParameter

This method returns the value of a set based string parameter.

Method Definition:
public String getStringParameter (String name, int iset, JdlError err)
Parameters List:
name
The parameter name. (May be: DET_TYPE, AX1_NAME, AX2_NAME, IX1_NAME, IX2_NAME, SYNCHROTRON, GONIO_ORIENT, IMAGE_TYPE, IMAGE_FORMAT, IMAGE_DATA, AXORD, DISTOR_TYPE, IMAGE_DIR, IMAGE_TEMPLATE)
iset
The set number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value string.

4.3.2.7.5 Get integer parameter - getIntegerParameter

This method returns the value of a dataset based integer parameter.

Method Definition:
public int getIntegerParameter(String name, JdlError err)
Parameters List:
name
The parameter name. (May be: NUMSETS)
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value.

4.3.2.7.6 Get integer parameter - getIntegerParameter

This method returns the value of a set based integer parameter.

Method Definition:
public int getIntegerParameter(String name, int iset, JdlError err)
Parameters List:
name
The parameter name. (May be: CRYSTAL_NUMBER, IAX_H, IAX_V, IMAGE_RECL, IMAGE_HEADER, NULL_PIXEL, OVLD_PIXEL, NXRASTS, NYRASTS, NWMAX)
iset
The set number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value.

4.3.2.7.7 Get double parameter - getDoubleParameter

This method returns the value of a set based double parameter.

Method Definition:
public double getDoubleParameter(String name, int iset, JdlError err)
Parameters List:
name
The parameter name. (May be: RMAX, TAU_X, TAU_Y, TAU_Z, DET_GAIN, WAVELENGTH, DISPERSION, DIVV, DIVH, DELCOR, POLARISATION, PIX_X, PIX_Y, TWOTH_MIN, RMIN, R_XCEN, R_YCEN, X_MIN, X_MAX, Y_MIN, Y_MAX, A, B, C, ALPHA, BETA, GAMMA, PHI_ORIENT, ANGLE_OSC)
iset
The set number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value

4.3.2.7.8 Get suffixed double parameter - getSuffixedDoubleParameter

This method returns the value of a set based suffixed double parameter.

Method Definition:
public double getSuffixedDoubleParameter(String name, int iset, int irange, JdlError err)
Parameters List:
name
The parameter name. (May be: ROTSTART, ROTEND, SPOT_SIZE)
iset
The set number.
irange
The range number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value

4.3.2.7.9 Get double parameter - getDoubleParameter

This method returns the value of a set and image based double parameter.

Method Definition:
public double getDoubleParameter(String name, int iset, int imgnum, int irange, JdlError err)
Parameters List:
name
The parameter name. (May be: DISTANCE, RESOLUTION, MOSAICITY, PHI_X, PHI_Y, PHI_Z, LAMBDA_MIN, LAMBDA_MAX, SPOT_SIZE, X_CEN, Y_CEN, X_C, Y_C, W_C, TWIST, TILT, ROFF, TOFF, Y_SCALE)
iset
The set number (>= 1).
imgnum
The image number within the given rotation range (or overall position if irange = 0).
irange
The rotation range number
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= 1, Invalid set/subset number
Method Return:
The parameter value.

4.3.2.7.10 Get pattern centre - getPatternCentre

Return the pattern centre position in rasters.

Method Definition:
public JdlXY getPatternCentre(int iset, int imgnum, int irange, JdlError err)
Parameters List:
iset
The set number (>= 1).
imgnum
The image number within the given rotation range (or overall position if irange = 0).
irange
The rotation range number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The centre position (null if error).

4.3.2.7.11 Get pixel dimensions in mm. - getPixelDimensions

This returns the pixel dimensions in x and y in millimetres.

Method Definition:
public JdlXY getPixelDimensions(int iset, int imgnum, int irange, JdlError err)
Parameters List:
iset
The set number (>= 1).
imgnum
The image number within the given rotation range (or overall position if irange = 0).
irange
The rotation range number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The pixel dimensions in x and y in mm.

4.3.2.7.12 Get detector rotations - getDetectorRotations

This method returns the detector rotation axis vectors in arrays.

Method Definition:
public void getDetectorRotations (int iset, double[] det1, double[] det2, double[] det3, JdlError err)
Parameters List:
iset
The set number.
det1
3 element array in which first detctor rotation vector is to be returned.
det2
3 element array in which first detctor rotation vector is to be returned.
det3
3 element array in which first detctor rotation vector is to be returned.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number

4.3.2.7.13 Get detector axes - getDetectorAxes

This method returns the detector axis vectors in arrays.

Method Definition:
public void getDetectorAxes (int iset, double[] detax1, double[] detax2, JdlError err)
Parameters List:
iset
The set number.
detax1
3 element array in which first detctor axis vector is to be returned.
detax2
3 element array in which first detctor axis vector is to be returned.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number

4.3.2.7.14 Get scan axis - getScanAxis

Returns the scan axis vector in an array.

Method Definition:
public void getScanAxis (int iset, double[] scax, JdlError err)
Parameters List:
iset
The set number.
scax
3 element array in which the scan axis vector is to be returned.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number

4.3.2.7.15 Get U-matrix - getUMatrix

Returns the U-Matrix in an array.

Method Definition:
public void getUMatrix (int iset, double[][] umat, JdlError err)
Parameters List:
iset
The set number.
umat
3x3 element array in which the U-Matrix is to be returned.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number

4.3.2.7.16 Get crystal system - getSystem

This method returns the crystal system number.

Method Definition:
public int getSystem()
Parameters List:
none
Method Return:
The crystal system number (1-7) for Triclinic, Monoclinic, Orthorhombic, Tetragonal, Hexagonal, Rhombohedral or Cubic resepctively.

4.3.2.7.17 Get lattice type - getLattice

This method returns the lattice type as an integer.

Method Definition:
public int getLattice()
Parameters List:
none
Method Return:
The lattice type as an integer (1-7) for P, A, B, C, I, F or R respectively.

4.3.2.7.18 Get detector basics - getDetectorBasics

This method returns a basic set of detector related parameters in a JdlDetectorBasics object.

Method Definition:
public JdlDetectorBasics getDetectorBasics(int iset, JdlError err)
Parameters List:
iset
The set number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The JdlDetectorBasics object - null if error.

4.3.2.7.19 Get positioned detector - getPositionedDetector

This method returns a set of detector related parameters in a JdlPositionedDetector object. These include the parameters from the JdlDetectorBasics object with additional parameters defining the current setting of the detector including the detector to crystal distance.

Method Definition:
public JdlPositionedDetector getPositionedDetector(int iset, int img, JdlError err)
Parameters List:
iset
The set number.
img
The image position number (over all defined ranges). [Can use the getImagePosition(..) method to find this number from the rotation range number and the image number within that range]
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The JdlPositionedDetector object - null if error.

4.3.2.7.20 Get X-ray source - getXraySource

This method returns a basic set of X-ray source related parameters in a JdlXraySource object.

Method Definition:
public JdlXraySource getXraySource (int iset, int img, JdlError err)
Parameters List:
iset
The set number.
img
The image position number (over all defined ranges). [Can use the getImagePosition(..) method to find this number from the rotation range number and the image number within that range]
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The JdlXraySource object - null if error.

4.3.2.7.21 Get cell - getCell

This method returns the cell parameters in a JdlCell object.

Method Definition:
public JdlCell getCell(int iset, JdlError err)
Parameters List:
iset
The set number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The JdlCell object - null if error.

4.3.2.7.22 Get positioned crystal - getPositionedCrystal

This method returns a set of crystal related parameters in a JdlPositionedCrystal object. These include parameters from the defining the current setting of the crystal.

Method Definition:
public JdlPositionedCrystal getPositionedCrystal(int iset, int img, JdlError err)
Parameters List:
iset
The set number.
img
The image position number (over all defined ranges). [Can use the getImagePosition(..) method to find this number from the rotation range number and the image number within that range]
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The JdlPositionedCrystal object - null if error.

4.3.2.7.23 Get orientation matrix - getOrientationMatrix

Get the crystal orientation matrix.

Method Definition:
public Jdl3x3 getOrientationMatrix(int iset, int img, JdlError err)
Parameters List:
iset
The set number.
img
The image position number (over all defined ranges). [Can use the getImagePosition(..) method to find this number from the rotation range number and the image number within that range]
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
The orientation matrix (null if error)

4.3.2.7.24 Get detector limits - getDetectorLimits

Return a detector limits (JdlDetectorLimits) object with data to select the part of the image to be processed. Note that 'rmax' is not included in this object but is included in a JdlPositionedDetector object as it is considered to be a more commonly used parameter.

Method Definition:
public JdlDetectorLimits getDetectorLimits (int iset, int img, JdlError err)
Parameters List:
iset
The set number.
img
The image position number (over all defined ranges). [Can use the getImagePosition(..) method to find this number from the rotation range number and the image number within that range]
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
Method Return:
A JdlDetectorLimits object.

4.3.2.7.25 Get symmetry - getSymmetry

Returns a reference to the stored symmetry data.

Method Definition:
public JdlSymmetry getSymmetry()
Parameters List:
none
Method Return:
A reference to the stored symmetry data.

4.3.2.7.26 Get KDM reference - getKDM

This method returns a reference to the JdlKeywordDataModule object around which the DDM is constructed. This enables its methods to be accessed if required. It should not normally be needed though it does if access to the 'NUMIMG' parameter if that is required (but see description of the updateNUMIMG() method). Because of the relationship between image numbers, rotation ranges and angle increment parameters, the ROTSTART, ROTEND and ANGLE_INC/ANGLE_OSC parameters, the values of those parameters should only be set via the DDM setDoubleValue(..) method as it automatically shifts the data for image dependent parameters to be consistent with the updated rotation range data.

Method Definition:
public JdlKeywordDataModule getKDM()
Parameters List:
none
Method Return:
A reference to the internal KDM object.

4.3.2.8 Rotation Range Methods

4.3.2.8.1 Introduction

This section contains a series of methods related to the specialised handling required for the use of multiple rotation ranges.

List of Methods:

Get number of rotation ranges - numberOfRotationRanges
Get image position - getImagePosition
Get rotation start angle - getRotationStart
Get rotation start angle - getRotationMidpoint
Get range number - getRangeNumber
Get number of images - numImages
Set image identifier - setImageID
Get range from image ID - getRangeFromImageID
Get number from image ID - getNumberFromImageID
Update NUMIMG - updateNUMIMG

4.3.2.8.2 Get number of rotation ranges - numberOfRotationRanges

This method returns the number of rotation ranges which have been defined for a given crystal set. This may include 'empty' ranges for which the current value for the rotation end angle is not greater than the start angle.

Method Definition:
public int numberOfRotationRanges(int iset)
Parameters List:
iset
The set number.
Method Return:
The number of rotation ranges (0 if an invalid set number was given).

4.3.2.8.3 Get image position - getImagePosition

Get the current overall position number (from 1 up) of an image from the image number within a rotation range and the rotation range number.

Method Definition:
public int getImagePosition(int iset, int imgnum, int irange)
Parameters List:
iset
The set number.
imgnum
The image number within the rotation range (if irange==0 then this is the overall image number which will be returned unchanged if it is withing the current range of images).
irange
The range number.
Method Return:
The image position number (KDM subset number):
> 0, Image number
= 0, Image number not currently defined for requested range
= -1, Invalid set number
= -2, Invalid range number

4.3.2.8.4 Get rotation start angle - getRotationStart

This method gets the rotation start angle for an image

Method Definition:
public double getRotationStart(int iset, int imgnum, int irange, JdlError err)
Parameters List:
iset
The set number.
imgnum
The image number within the rotation range.
irange
The range number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
= 2, Undefined rotation range
= 3, Undefined image for range
Method Return:
The rotation start angle; 0.0 if error.

4.3.2.8.5 Get rotation start angle - getRotationMidpoint

This method gets the rotation start angle for an image

Method Definition:
public double getRotationMidpoint(int iset, int imgnum, int irange, JdlError err)
Parameters List:
iset
The set number.
imgnum
The image number within the rotation range.
irange
The range number.
err
JdlError object to return error codes etc. If an error was detected, then err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= 1, Invalid set/subset number
= 2, Undefined rotation range
= 3, Undefined image for range
Method Return:
The rotation start angle; 0.0 if error.

4.3.2.8.6 Get range number - getRangeNumber

This method gets the rotation range number (and image position within that range) given an overall image position number.

Method Definition:
public int getRangeNumber(int iset, int imgnum, JdlInt imgr)
Parameters List:
iset
The required set number
imgnum
The overall image position number.
imgr
Returns the image position within the range
Method Return:
The range number (0 if not within a current range; -1 if set not present)

4.3.2.8.7 Get number of images - numImages

This method returns the current number of images for a given set for a given range or for all ranges together.

Method Definition:
public int numImages(int iset, int irange)
Parameters List:
iset
The required set number (>= 1).
irange
The rotation range number (0 for all ranges together).
Method Return:
The number of images:
>= 0, The required number of images
= -1, Invalid set number
= -2, Invalid range number

4.3.2.8.8 Set image identifier - setImageID

This method calculates an image identifier from a rotation range number and the image number within the range.

Method Definition:
public static int setImageID(int irange, int imgnum)
Parameters List:
irange
The rotation range number.
imgnum
The image number within the range (>0).
Method Return:
The packed image identifier.

4.3.2.8.9 Get range from image ID - getRangeFromImageID

This method returns the rotation range number from a packed image identifier.

Method Definition:
public static int getRangeFromImageID(int img_id)
Parameters List:
img_id
The packed image identifier
Method Return:
The rotation range number.

4.3.2.8.10 Get number from image ID - getNumberFromImageID

This method returns the image number within a rotation range from a packed image identifier.

Method Definition:
public static int getNumberFromImageID(int img_id)
Parameters List:
img_id
The packed image identifier.
Method Return:
The image number.

4.3.2.8.11 Update NUMIMG - updateNUMIMG

This method can be used to set the values for the set dependent NUMIMG parameter. This parameter should not normally need to be accessed by the user but if it is, then this method should be invoked prior to retrieving its value(s). Normally when using the DDM, the current numbers of images and other image number details are determined from the current settings of the rotation range and angle increment parameters. As the NUMIMG parameter is needed when a DDM file is written, this method is automatically called when one of the methods to write DDM data is used.

Method Definition:
public void updateNUMIMG()
Parameters List:
none

4.3.2.9 Write DDM file

4.3.2.9.1 Introduction

This section has methods for writing a DDM file.

List of Methods:

Write DDM file - writeDDMFile
Write DDM file - writeDDMFile

4.3.2.9.2 Write DDM file - writeDDMFile

This method is used to write a DDM file to a given buffered writer stream.

Method Definition:
public boolean writeDDMFile(String filnam, int outtyp, int ichanged, JdlError jerr)
Parameters List:
filnam
Output file name.
outtyp
Type of output:
= 1, Minimum, do not o/p parameters with default values
= 2, Standard output, do not o/p parameters with default values except for those which have been flagged to be printed as standard
= 3, Full (all parameters will be included) but with reduced output where feasible by recombining values if all the same for a set etc.
= 4, All pamaeters and individual values given explicitly for all set/image parameters </br>
ichanged
Output changed parameters flag:
= 0, Output all parameters </br> = 1-16, Write changed parameter values since last reset of flag for channel 'ichanged'
jerr
If an error was found 'jerr.err' is set to true, an error message is returned in 'jerr.msg1' and 'jerr.flag' is set as follows:
= -4, Access control exception
= -3, Malformed URL Exception
= -2, File opening error
= -1, File writing error
= 1, Invalid method parameters
Method Return:
True if OK, false if error.

4.3.2.9.3 Write DDM file - writeDDMFile

This method is used to write a DDM file to a given buffered writer stream.

Method Definition:
public boolean writeDDMFile(BufferedWriter bwr, int outtyp, int ichanged, JdlError err)
Parameters List:
bwr
Buffered writer for the file output.
outtyp
Type of output:
= 1, Minimum, do not o/p parameters with default values
= 2, Standard output, do not o/p parameters with default values except for those which have been flagged to be printed as standard
= 3, Full (all parameters will be included) but with reduced output where feasible by recombining values if all the same for a set etc.
= 4, All pamaeters and individual values given explicitly for all set/image parameters </br>
ichanged
Output changed parameters flag:
= 0, Output all parameters </br> = 1-16, Write changed parameter values since last reset of flag for channel 'ichanged'
jerr
If an error was found 'jerr.err' is set to true, an error message is returned in 'jerr.msg1' and 'jerr.flag' is set as follows:
= -1, File writing error
= 1, Invalid method parameters
Method Return:
True if OK, false if error.

4.3.2.10 JdlView Parameter Table

4.3.2.10.1 Introduction

This section contains a series of methods for creating and processing DDM data in a JdlView parameter table window.

List of Methods:

Get JdlParameterTable - getParameterTable
Get JdlParameterTable - getParameterTable
Set parameter values - setParameterTableValues
Process parameter input - processParameterInput
Get current set - getParameterTableSet
Get current image - getParameterTableImage
Share parameter table - shareParameterTable

4.3.2.10.2 Get JdlParameterTable - getParameterTable

This method returns a JdlView JdlParameterTable object for displaying and editing the DDM data. The parameter table has three columns of up to 14 items on each of three selectable tables. The setParameterTableValues(..) method will auttomatically be called with the table number, set number and image number all set to 1. This version uses the default view options

Method Definition:
public JdlParameterTable getParameterTable()
Parameters List:
none
Method Return:
The JdlParameterTable object.

4.3.2.10.3 Get JdlParameterTable - getParameterTable

This method returns a JdlView JdlParameterTable object for displaying and editing the DDM data. The parameter table has three columns of up to 14 items on each of three selectable tables. The setParameterTableValues(..) method will auttomatically be called with the table number, set number and image number all set to 1.

Method Definition:
public JdlParameterTable getParameterTable(JdlViewOptions view_opts)
Parameters List:
view_opts
Object to set non-default options for borders, active strip, colours and fonts.
Method Return:
The JdlParameterTable object.

4.3.2.10.4 Set parameter values - setParameterTableValues

This method sets parameters from the DDM into the parameter table (for all three table numbers) and selects the table to be displayed. The method cannot be used unless the getParameterTable() method has previously been called.

Method Definition:
public void setParameterTableValues (int itabl, int iset, int imgpos)
Parameters List:
itabl
The table number to be displayed (1-3).
iset
The current set number to de displayed (will be reset to 1 if outside current valid range).
imgpos
The current image number to display (over all ranges) ((will be reset to 1 if outside current valid range).

4.3.2.10.5 Process parameter input - processParameterInput

This method is used to processes the input from the parameter table following a value input action from the table. The values will be updated in the DDM as needed and error conditions handled via the normal dialogues.

Method Definition:
public String processParameterInput()
Parameters List:
none
Method Return:
The parameter name String. (If the set or image number were changed the returned strings will be "SET n" or "IMG n" where 'n' is the new set/image number).

4.3.2.10.6 Get current set - getParameterTableSet

This method returns the number of the set currently selected in the parameter table.

Method Definition:
public int getParameterTableSet()
Parameters List:
none
Method Return:
The set number.

4.3.2.10.7 Get current image - getParameterTableImage

This method returns the number of the image currently selected in the parameter table.

Method Definition:
public int getParameterTableImage()
Parameters List:
none
Method Return:
The image number.

4.3.2.10.8 Share parameter table - shareParameterTable

This method enables the same parameter table to be used by more than one DDM object. The parameter table for the first object needs to have been set via a call to getParameterTable(). When switching DDM sets the setParameterTableValues(..) and processParameterInput(..) methods will need to be used for the new object.

Method Definition:
public void shareParameterTable (JdlDiffractionDataModule ddm)
Parameters List:
ddm
The JdlDiffractionDataModule object which was used to create the parameter table.

⇑ Up 2   ⇑ Up 1   ⇑ Top of this