Tightened up motor definitions and adapted virtual-motor names

diffractometer.md

@@ -4,22 +4,23 @@ This allows them to be used in a standard way by the MXCuBE application (web or
 
 We also introduce a convention about the direction of the alignment and centring motors:
 
-- x axis is parallel to the beam. Positive direction is from right to left.
-- y axis is perpendicular to the beam, parallel to the ground. Positive direction is from left to right, facing the beam.
-- z axis is perpendicular to the floor. Positive direction is top down.
+- z axis is in the direction of gravity. Positive direction is downwards.
+- y axis is perpendicular to the z axis and to the nominal beam direction. Positive direction is so that x,y,z would form a right-handed coordinate system.
+- x axis is orthogonal to the y and z axes (and approximately parallel to the beam). Positive direction is from the sample towards the detector.
 
 Here follows the list of the fixed roles and the description of the corresponding objects, accessible via beamline.diffractometer hardware object.
 
 1\. Motor objects (roles) and their functionality:
 
-- **omega** - the rotation axis, independent of the orientation (up, down or side). Positive direction is clockwise
-- **sampx** - centring table x axis
+- **omega** - the rotation axis, independent of the orientation (up, down or side). Positive direction is a right-handed rotation
+- **kappa** - the rotation axis between the omega and kappa_phi axes. Positive direction is a right-handed rotation. Not present on all goniostats.
+- **kappa_phi** - the rotation axis directly attached to the sample. Positive direction is a right-handed rotation. Not present on all goniostats.
 - **sampy** - centring table y axis
 - **focus** - alignment table x axis
 - **phiy** - alignment table y axis
 - **phiz** - alignment table z axis
-- **sample_horizontal** - x axis, combination of sampx and sampy. Equivalent to sampx at omega=0 and sampy for omega=90.
-- **sample_vertical** - y axis, combination of sampx and sampy. Equivalent to sampy at omega=0 and sampx for omega=90.
+- **sample_focus** - virtual motor along the y axis, omega-dependent combination of sampx and sampy.
+- **sample_lateral** - virtual motor along the z axis, omega-dependent combination of sampx and sampy.
 - **backlight** - adjust the intensity of the back light
 - **frontlight** - adjust the intensity of the front light
 

mxcubecore/HardwareObjects/abstract/AbstractDiffractometer.py

@@ -25,26 +25,32 @@
 actuator object. This allows to use them in a standard way by the MXCuBE
 application (web or Qt).
 There is also a convention of the direction of the motors:
-  - x axis is parallel to the beam. Positive direction is from right to left.
-  - y axis is perpendicular to the beam, parallel to the ground. Positive
-      direction is from left to right when facing the beam.
-  - z axis is perpendicular to the floor. Positive direction is top down.
+- z axis is in the direction of gravity. Positive direction is downwards.
+- y axis is perpendicular to the z axis and to the nominal beam direction.
+  Positive direction is so that x,y,z would form a right-handed coordinate system.
+- x axis is orthogonal to the y and z axes (and approximately parallel to the beam).
+  Positive direction is from the sample towards the detector.
+
 
 Here follows the list of the fixed roles and the description of the
 corresponding objects, accessible via beamline.diffractometer hardware object.
 
 1. Motor objects (roles)  and their functionality:
   omega - the rotation axis, independent of the orientation (up, down or side).
-          Pisitive direction is clockwise.
+          Positive direction is a right-handed rotation.
+  kappa - the rotation axis between the omega and kappa_phi axes.
+          Positive direction is a right-handed rotation. Not present on all goniostats.
+  kappa_phi - the rotation axis directly attached to the sample.
+          Positive direction is a right-handed rotation. Not present on all goniostats.
   sampx - centring table x axis
   sampy - centring table y axis
   focus - alignment table x axis
   phiy - alignment table y axis
   phiz - alignment table z axis
-  sample_horizontal - x axis, combination of sampx and sampy. Equivalent to
-                      sampx at omega=0 and sampy for omega=90.
-  samle_vertical - y axis, combination of sampx and sampy. Equivalent to
-                   sampy at omega=0 and sampx for omega=90.
+  sample_focus - virtual motor along the x axis,
+                      omega-dependent combination of sampx and sampy.
+  sample_lateral - virtual motor along the y or z axis, orthogonal to the omega axis,
+                      omega-dependent combination of sampx and sampy.
   backlight - adjust the intensity of the back light
   frontlight - adjust the intensity of the front light
   kappa - the minikappa kappa axis