2d detector projection

[dagewa]

This is an attempt to address #17, at least for the common case of (almost) co-planar detectors. A new function, project_2d is added which calculates an orthographic projection of the detector onto a 2D coordinate system. This differs from the dials.image_viewer in that the projection is not done in the laboratory frame, but in a "best fit" frame calculated by fitting a plane to the panels and aligning X and Y with the consensus fast, slow axes of the detector. As a result, bulk rotations of the detector up to 45° do not affect the 2D representation. A new test is added to check that.

The function has been added to detector_helpers.py for testing. To facilitate that, a new mode has also been added to dxtbx.plot_detector_models. If the parameters orthographic=True project_onto=image_plane are passed to this program it will produce a plot using the project_2d function.

The attached panel-beating.zip provides data to demonstrate, using a CS-PAD image, which is the most complicated co-planar geometry we currently support. Displaying imported.expt in dials.image_viewer and with the new mode to dxtbx.plot_detector_models demonstrates how the two viewers operate in a "normal" situation.

If now the whole detector is rotated about an arbitrary axis by 20 degrees then dials.image_viewer displays the "jaunty angle" in the laboratory frame, whereas the new function is unaffected

Finally, to demonstrate the choice of a consensus X, Y frame for display, we do a real nasty on the CS-PAD and break a sensor in half and leave it hanging by a thread. The dials.image_viewer displays this vandalism in the lab frame, whereas the new function projects it onto the best fit frame.

There is not a perfect alignment of the frames shown by dxtbx.plot_detector_models rotated_detector.expt rotated_panel.expt orthographic=True project_onto=image_plane, so I can see how it would continue to be better to do metrology refinement using the lab frame projection.

But perhaps this would provide a more natural view for standard image viewer tasks? If in future this function is deemed suitable as an option for display in an image viewer (see dials/dials#1358) then it could in principle be moved to the detector model itself, so that it can easily be overridden for special cases like the I23 detector, where the assumption of a single best-fit plane breaks down.

[phyy-nx]

Interesting! Do you have an example of a 2theta arm rotation and what it looks like?

[benjaminhwilliams]

Sorry for the slow reply regarding the non-zero detector 2θ. Here is an example from the chemical crystallography beamline I19 at Diamond Light Source. Unfortunately it is only a single-panel detector but everything seems to behave OK. Testing on a single CBF image from this archive, which has a detector 2θ position of 30°, we see
$ dxtbx.plot_detector_models orthographic=True l-cyst_01_00001.cbf

$ dxtbx.plot_detector_models orthographic=True project_onto=image_plane l-cyst_01_00001.cbf

The difference isn't too apparent with this small 2θ, so if we doctor the image file to have 2θ = 89°, we can see the difference more clearly.
$ dxtbx.plot_detector_models orthographic=True l-cyst_01_00001.cbf

$ dxtbx.plot_detector_models orthographic=True project_onto=image_plane l-cyst_01_00001.cbf

If we use 2θ = 90°, the edge-on projection onto the lab x-y plane causes no problems:
$ dxtbx.plot_detector_models orthographic=True l-cyst_01_00001.cbf

$ dxtbx.plot_detector_models orthographic=True project_onto=image_plane l-cyst_01_00001.cbf

Finally, if we go beyond the vertical and set 2θ = 120°, everything still looks sensible:
$ dxtbx.plot_detector_models orthographic=True l-cyst_01_00001.cbf

$ dxtbx.plot_detector_models orthographic=True project_onto=image_plane l-cyst_01_00001.cbf

Though in this last case, we cannot determine which way up the image-plane projection is.

[phyy-nx]

Cool!

[dagewa]

Thanks @benjaminhwilliams and @phyy-nx. As this doesn't change behaviour outside of adding an option to dxtbx.plot_detector_models I think it is safe to merge, and I plan to do that today.

[Anthchirp]

The test failures are not a fluke: This adds a dxtbx > scikit-learn dependency.

[dagewa]

Ah, gotcha, I forgot to look at the Azure tests. There's a single-panel mode that doesn't use the clustering. This could be used for multi-panel detectors where sklearn is not available, but the end result of the projection may be different. Adding a dependency requires wider discussion, so then I won't merge yet.

[Anthchirp]

Definition of cluster here shadows the imported name, leading to the unexpected test failure

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@f227287). Click here to learn what that means.
The diff coverage is 66.18%.

@@            Coverage Diff            @@
##             master     #224   +/-   ##
=========================================
  Coverage          ?   45.31%           
=========================================
  Files             ?      228           
  Lines             ?    19412           
  Branches          ?     2754           
=========================================
  Hits              ?     8797           
  Misses            ?    10097           
  Partials          ?      518           

[dagewa]

As all checks are now passing, I'll merge this.