Usage of CCFv3

[rly]

The python package includes a predefined space "CCFv3":

"CCFv3": {
    "name": "space",
    "space_name": "CCFv3",
    "origin": "In the middle of the anterior commissure",
    "units": "um",
    "orientation": "RAS",
}

However, my admittedly limited understanding of CCFv3 is that:

1. The origin is a corner of the bounding volume, not bregma and not the middle of the anterior commissure. As a result, all coordinate values within the brain should be positive (https://community.brain-map.org/t/how-to-switch-between-the-3-coordinate-systems-of-mouse-connectivity/952)

2. The CCFv3 coordinate units are in number of voxels, not mm, and the relation to real-world space is dependent on which resolution of CCFv3 is used, e.g. 25um spacing or 10um spacing

3. The above image suggests the orientation is actually x=AP, y=DV, z=LR, not "RAS". I'm not sure where that came from.

4. There is no straightforward way to map between CCFv3 coordinates and stereotactic coordinates for several reasons. Stereotactic coordinates for the mouse are relative to bregma, which is a skull reference, and CCF does not have a skull. CCF is based on slices of PFA-fixed mouse brain, and the size and angle of those images are slightly warped relative to the in vivo brain. There appears to be some stretching and tilting required to convert a CCFv3 space into stereotactic coordinates. See discussion in https://community.brain-map.org/t/how-to-transform-ccf-x-y-z-coordinates-into-stereotactic-coordinates/1858 and https://community.brain-map.org/t/why-doesnt-the-3d-mouse-brain-atlas-have-bregma-coordinates/158

As a result, I believe:

1. the CCF should be used to localize electrodes/fibers/etc. only when histology and registration to the atlas has been done, and we should add that to the README. If a user has stereotactic coordinates and no histology, then we should encourage them to create a new space for those coordinates instead of using CCF.
2. we should decide whether to store CCF coordinates in voxels or convert them to um/mm. If we store them in voxels, then we need to specify which CCF atlas we are using. I think which spacing of atlas was used is unnecessary for data reuse, so I think we should leave that out and store coordinates in um. (That detail is useful for provenance, but that's a whole other thing that I think we should push out of scope for now.)
3. "origin" should be "anterior, dorsal, left corner of the bounding volume"
4. "orientation" should be "PIR"

I only have a novice understanding of CCFv3. We should check with Lydia and maybe folks from the IBL or BrainGlobe communities.

Additional references:

• The Scalable Brain Atlas chose its own origin based on the origin of another atlas, saying: "The Allen Institute does not define an origin for its atlases, and therefore we took the freedom to set it as close as possible to the origin of the Waxholm mouse atlas. It is set to voxel [229,314,114] (where the first voxel has index 1 in each dimension)." https://scalablebrainatlas.incf.org/mouse/ABA_v3#about