Generalise support for dynamic shadowing in dxtbx

[graeme-winter]

Prepared with @benjaminhwilliams

Problem statement:

We would like to be able to support the general application of diamond anvil cells with arbitrary opening angles with any appropriate format class. The current model encodes the goniometer / anvil shadowing information alongside the detector description which is both uncomfortable and incorrect, since they are strictly decoupled.

Proposal:

1. generalise the concept of dynamic_shadowing PHIL parameter from a boolean to a boolean or a pointer to a description of the occluder
2. define a file format which allows the occluder to de defined e.g. through a list of vertices, as a circle in a given position, and whether it is positive (i.e. goniometer shadow) or negative (i.e. anvil, which defines an allowed portal)
3. incorporate this into the GoniometerShadowMasker factory so that this can be used with any instrument which supports shadowing
4. replace existing shadowing implementation with this for i19 use cases

First cut YAML description needs to define:

• type: aperture|object
• shape: polygon|disk|cone
• vectors: 3...N vertices for polygon; 1 for disk or cone as offset of centre or principal axis of cone
• angle: for cone, the angle between the principal axis and the edge of the cone (i.e. half opening angle)
• radius: for disk, the radius of the disk

All vectors are defined in the laboratory frame at datum in mm. All angles defined in degrees. All radii defined in mm. Clearly there is degeneracy between the cone and disk, this is deliberate. The system must allow for an arbitrary list of occluders e.g. if you have a diamond anvil cell mounted on a multi-axis goniometer, or both directions of a diamond anvil cell. Note: care will need to be taken when performing the composition to ensure that e.g. the intersection of shadows and apertures is correctly combined as the intersection of the allowed region from each of the occluders (valid = allowed & allowed & allowed)

[benjaminhwilliams]

Two additions to the description above:

• We must handle the case where the shadowing object's rotation does not match that of the sample. For example, we must account for the movement of the κ arm of a mini-κ goniometer. The specification should therefore include the axis on which the object is mounted.
• We must allow for objects with multiple apertures, such as the forward and backward apertures of a diamond anvil cell, in which case valid = allowed_1 | allowed_2. So the specification must permit distinction between & and | combination.