Instrument Description File (IDF)

An instrument definition file (IDF) is a JSON file that describes an instrument, and provides details about those components of the instruments that are essential for positioning the sample such the positioning system, guage volume, detector etc. SScanSS is mainly concerned with the geometry i.e. shape and kinematic of these components.

Note

The instrument description file used in SScanSS is different from the one used by the Mantid project

Warning

The keywords in the instrument description file are CASE-SENSITIVE so use the same case as in the documentation

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of instrument
version	string	Required	Version number of file
script_template	string	Optional (generic)	Path of script template
gauge_volume	array of float	Required	Position of gauge volume
incident_jaws	Jaws Object	Required	Jaws of instrument
detectors	array of Detector Objects	Required	Detectors of instrument
collimators	array of Collimator Objects	Optional (None)	Collimators of instrument
positioning_stacks	array of Positioning Stack Objects	Required	Positioning stacks of instrument
positioners	array of Positioner Objects	Required	Positioners of instrument
fixed_hardware	array of Fixed Hardware Objects	Optional (None)	Fixed hardware on instrument

Positioner Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of positioner
base	array of floats	Optional (zero array)	Base matrix of the positioner as a 6D array. First three value should be XYZ translation and next three should be XYZ orientation in Degrees
tool	array of floats	Optional (zero array)	Tool matrix of the positioner as a 6D array. First three value should be XYZ translation and next three should be XYZ orientation in Degrees
custom_order	array of strings	Optional (None)	Order of joint if order is different from kinematics.
joints	array of Joint Objects	Required	Joints of the positioner
links	array of Link Objects	Required	Links of the positioner

Joint Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object. The joints in a positioner must have unique names
description	string	Optional	Description of the joint object
type	enum [prismatic, revolute]	Required	The joint type: revolute for rotating joints and prismatic for translating joints.
parent	string	Required	The name of the link object to which the joint is attached
child	string	Required	The name of the link object that is attached to the joint
axis	array of floats	Required	The axis of translation or rotation with respect to the instrument coordinate frame.
origin	array of floats	Required	The centre of rotation for the revolute joint or the start position of prismatic joints with respect to the instrument coordinate frame.
lower_limit	float	Required	The lower limit of the joint
upper_limit	float	Required	The upper limit of the joint
home_offset	float	Optional ((upper_limit + lower_limit)/2)	The initial offset value of the manipulator.

Link Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object. The links in a positioner must have unique names
visual	Visual Object	Optional (None)	Visual representation of lobject

Visual Object

Key	Type	Optional (Default Value)	Description
pose	array of floats	Optional (zero array)	Transform to apply to the mesh as a 6D array. First three value should be XYZ translation and next three should be XYZ orientation in Degrees
colour	array of floats	Optional (zero array)	Normalized RGB colour [0 - 1]
mesh	string	Optional - if geometry supplied	Relative file path to mesh
geometry	Geometry Object	Required	Geometry describing the visual object

Geometry Object

Key	Type	Optional (Default Value)	Description
type	string	Required	The geometry type (one of: box, plane, sphere or mesh)
size	array of floats	Required - box, plane	Box x, y, z components or plane x, y components
radius	float	Required - sphere	Sphere radius
Path	string	Required - mesh	Mesh file path

Positioning Stack Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object.
positioners	array of strings	Required	Names of positioners in the stack from bottom to top.

Detector Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object
default_collimator	string	Optional (None)	Name of the default collimator
diffracted_beam	array of floats	Required	Normalized vector of the diffracted beam
positioner	string	Optional (None)	Name of positioner the detector is attached to.

Collimator Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object
detector	string	Required	Name of detector the collimator is attached to
aperture	array of floats	Required	Horizontal and vertical size of collimator’s aperture
visual	Visual Object	Required	Visual representation of object

Jaws Object

Key	Type	Optional (Default Value)	Description
aperture	array of floats	Required	Horizontal and vertical size of jaws’ aperture
aperture_lower_limit	array of floats	Required	Horizontal and vertical lower limit of jaws
aperture_upper_limit	array of floats	Required	Horizontal and vertical upper limit of jaws
beam_direction	array of floats	Required	Normalized vector indicating the direction of beam from source
beam_source	array of floats	Required	Source position of the beam
positioner	string	Optional (None)	Name of positioner the jaws are attached to.
visual	Visual Object	Required	Visual representation of object

Fixed hardware Object

Key	Type	Optional (Default Value)	Description
name	string	Required	Unique name of object
visual	Visual Object	Required	Visual representation of object