Tightened up motor definitions and adapted virtual-motor names

[rhfogh]

Modified motor definitions following discussion in #1470

• Definitions follow the original system of @beteva, but are tightened to avoid any possible ambiguity. x, y and z form a right-handed orthogonal axis system with z in the direction of gravity, y orthogonal to gravity and beam, and x approximately along the beam. Note that the definitions use the nominal beam direction, as the motor vectors are not supposed to be update when the actual beam drifts.

• sample_horizontal and sample_vertical have been renamed sample_focus and sample_lateral, as proposed by Gleb, and the comment about being equal to sampx and sampy at certain omega values have been removed as inapplicable in many circumstances. The new names are valid for both horizontal and vertical goniostats.

The new names have been applied across the mxcubecore and mxcubeweb code (see separate mxcubeweb PR).

NBNB The @beteva definitions said that the Z axis direction was Positive direction is top down and this PR follows tha, having the positive direction downwards. The comment in #1470 by @marcus-oscarsson sais ẑ: Is in the, negative, direction of gravity, pointing "upwards"! This seems contradictory. We should make sure which convention we want and if necessary adapt this PR.

[marcus-oscarsson]

Hm, there is some miss conception here I believe. In today's convention, before AbstractDiffractometer sample_horizontal and sample_vertical are in relation to gravity and both perpendicular to x (focus). These are the movements of the sample after the rotation stage and are are very much a function of sampx, sampy, and gonio orientation. Its what the user would use to move the sample vertically or horizontally across the beam.

The comment I made in #1470 was just to outline the laboratory frame we are using for the sake of background that, @beteva suggest another direction of the z vector is of lesser importance.

Edit: Indeed anything moving the sample in the x direction could be called sample_focus

[rhfogh]

@marcus-oscarsson There is indeed a misconception here somewhere, but maybe you can explain it to me.
My logic was this:

• Sample_horizontal and Sample_vertical were explained (by @beteva) as being linear combinations of sampx and sampy, depending on omega.
• sampx and sampy are orthogonal to the omega axis.
• Therefore Sample_horizontal and Sample_vertical must also be orthogonal to the omega axis.
• Since the omega axis is perpendicular to x no matter how the goniostat is mounted, then Sample_horizontal and Sample_vertical cannot both be orthogonal to x, so one must be along x.

If you want to move the sample orthogonal to the beam, you need to bring in sampx+sampy for one of the dimensions, and phiy or phiz for the other, depending on goniostat orientation.

I must admit I am getting ever more happy with Gleb's CentringMath convention, where you do not need to define explicitly which motors contribute to what but only to give the motor order and direction vectors.

Anyway, which part of the above did I get wrong?

[marcus-oscarsson]

You mentioned in your very first post that "sample_horizontal and sample_vertical have been renamed sample_focus and sample_lateral". Neither of sample_horizontal or sample_vertical can be sample_focus.

Either sample_vertical or sample_horizontal coincides with the rotation axis. On a horizontal micro diffractometer sample_horizontal would be the same as phiy (also called alignment-y) and sample_vertical would be a linear combination of sampx and sampy. For a vertical micro diffractometer it would be the other way around, sample_vertical coincides with phiz and sample_horizontal is a a linear combination of sampx and sampy.

Giving the centering routine a mapping, either via order or something more explicit, that makes the calculations independent of the diffractometer orientation is of course a good idea.

You will need to care about which motors are which when you would like to move the sample around across the beam and when you would like to give the users intuitive controls to do so. At that stage we care about in which direction the sample moves on the OAV and in relation to the beam.

[marcus-oscarsson]

Its true that the terms "horizontal" or "lateral" could mean both in x and y directions perhaps thats where the confusion lies. We are "looking" down the beam so "horizontal" is orthogonal to x and z.

[rhfogh]

@marcus-oscarsson OK, then I had misunderstood the situation after reading the original documentation. It does not matter whose fault it was, though I note that Gleb seems to have made the same mistake - hence his proposed motor names. I shall withdraw this PR and come up with a modified one.