Plane parameters specification

[FedeClaudi]

Following on discussion from https://github.com/brainglobe/brainrender/pull/186#issuecomment-1016431053 cc @vigji

Currently, the 'slicing' is done by specifying for one plane:

• position as offset in XYZ relative to the center of mass of root mesh
• norm vector (x, y, z) A second plane is created offset by a user specified ammount in the direction -norm and with norm as -norm. These two planes slice the brain regions twice so that you're left with just what's inbetween the planes as a 'slice'. Alternative the plane's orientation can be passed by a string that refers to pre-established orientations frontal, sagittal and horizontal.

Now, I think specifying the position of the plane as relative to the center of mass of the root is not very intuitive, perhaps expressing its coordinates as a point in the atlas' reference space is better. The norm is useful because you don't just need to have a plane at a given angle, you need to have a sense of orientation. E.g., if you are slicing through the midline sagittal plane, do you want to keep what's on the left or on the right of the plane? The norm encodes both angles and orientation in an efficient format. The downside for the norm is that it's not very intuitive: what's norm=(1, 1, 1) in angles?

I can think of three ways to specify the plane's position:

• center + norm (current)
• center + 2 angles
• 3/4 coordinates

I think we should implement all three and let the user pick the one they prefer, it should be some simple geometry to go from one to the other. We should also have 2 useful features:

1. a 'design' visualization in which the user can see the position of the planes in the brain, without slicing. This should show plane1 and plane2 clearly labelled and maybe the norm vectors as well.
2. we should export plane metadata information in some easy to use format for records keeping for the users

[vigji]

I think that maybe @nickdelgrosso has gained some experience to offer here in terms of what users might find more intuitive as a slice parameterisation?

[FedeClaudi]

At least it will have a planner so that users can see where the planes are and how they intersect with the regions:

I still think that center + norm is the best. Especially since you have the named orientations which means that most of the times users won't even bother with the norm as they'll just use 'frontal'.

[FedeClaudi]

As mentioned yesterday, there's a planner functionality that shows the position of the planes and the norm vectors:

as well as how the main plane (blue) intersects with the meshes the user is interested in. The planner also provides some coordinates information:

I think that this, together with a detailed explanation of how things work (the two planes to slice etc...) and what position/norm do would be enough. Without having to provide additional methods to specify the plane position (which most people won't care about because they'll use the named orientations).

If you're happy with this @vigji (and @adamltyson ), I'd leave it as is and focus on documenting/testing this thing before releasing it.

[adamltyson]

Looks great!