Directed distance is confusing

[phyy-nx]

(Arising from a conversation with @LouConreux, who is working on LCLS geometry interoperabilty with DIALS)

Sometimes even if the geometry in an image file is right, dials.show prints out a negative distance, which is confusing. A negative origin vector z-value is fine, but a negative distance makes one worry something is wrong.

Not only that, the image viewer has a bug that results from this, namely the unit cell tool frame shows puts a negative distance into the distance box and rings don't display until the minus sign is removed.

This arises because these programs are using directed distance, which is defined as the origin dot the normal. See these lines:

https://github.com/cctbx/dxtbx/blob/main/src/dxtbx/model/virtual_panel.h#L325
https://github.com/cctbx/dxtbx/blob/main/src/dxtbx/model/virtual_panel.h#L217-L225
https://github.com/cctbx/dxtbx/blob/main/src/dxtbx/model/panel.h#L554

(the image viewer is trickier to track down, but I suspect the issue is similar)

This is fine if the normal points in the same direction as the origin, which it does in a lot of cases, but for some formats it doesn't. This little jiffy script will show the basis frames of the example images we have in dials.data:

cd `dials.data get image_examples --quiet`
for i in `ls`; do echo $i; libtbx.python -c "import dxtbx; img = dxtbx.load('$i'); d = img.get_detector(); p = d[0]; print(p.get_fast_axis(), p.get_slow_axis(), p.get_origin(), p.get_directed_distance())"; done

You will see that most of them have a postiive distance, but a few have a negative distance, such as RAXIS-HTC-test1_lysozyme_0111060001.osc.bz2. dials.show:

Detector:
Panel:
  name: Panel
  type: SENSOR_IMAGE_PLATE
  identifier: 
  pixel_size:{0.1,0.1}
  image_size: {3000,3000}
  trusted_range: {0,1e+06}
  thickness: 0
  material: 
  mu: 0
  gain: 1
  pedestal: 0
  fast_axis: {0,1,0}
  slow_axis: {-1,0,0}
  origin: {149.87,-149.61,-120}
  distance: -120
  pixel to millimeter strategy: SimplePxMmStrategy

The normal vector isn't shown but it's (0,0,1), which is the opposite direction of the origin, which is why the distance is shown as negative.

I purport the distance here should be the abs(distance) to be less confusing. Even though the concept of distance isn't a thing in the mathematics dials uses to process the data, users expect a positive number. Likewise I propose that the image viewer be fixed to not show a negative distance in the unit cell frame and that it properly displays the rings.

Note also that it's perfectly legal to have the panel normal face in either direction. See this sentence in Waterman 2016:

"To parameterize a detector plane, a reference coordinate basis is formed from the orthonormal triplet dx, dy, dn, consisting of a pair of in-plane axes and the plane normal vector for the initial orientation, which may face either towards or away from the sample"

[dagewa]

I agree it makes sense to always show positive distance to the user. However, one issue is that we might want to set geometry.detector.distance on import. I suspect this takes a signed value. We could make this a bit cleverer, to work out the sign itself depending on the beam direction.