Formalize specification of shape(s) (AKA contour(s))

[yarikoptic]

trafficstars

Problem space

It came up in the scope of working on https://bids.neuroimaging.io/bep032 , which is currently being transferred from google doc into

• #1705

in the need to describe the "contours" of the

• probes
• shanks (if multiple)
• electrodes (individual sensors on a shank)

Per our discussion with @bids-standard/bep032 folks involved in other BEPs (such as @robertoostenveld ) we saw relation to e.g.

• specification of contours/shapes for EEG electrodes or MEG sensors (attn @bids-standard/raw-electrophys-meg @bids-standard/raw-electrophys-eeg )
  • for MEG there is a https://github.com/mne-tools/mne-python/blob/main/mne/data/coil_def.dat re-shared/re-used centralized definition for shapes/orientations
• electrodes for BEP032 discussed in https://github.com/bids-standard/bids-specification/issues/1371 (attn @bids-standard/bep042)

Definitions space

I see many definitions of 3D shapes could be generalized into

• planar (2D) contour + depth/extrusion
• arbitrary mesh

And in turn planar (2D) contours could be generalized into

• basic shape (circle, square, rectangle) + shape specification (diameter, width, width+height) + orientation
• arbitrary contour -- problematic as could contain arbitrary number of points to describe

Existing structures/definitions in BIDS

• _headshape.pos -- a shape/contour of the head. (interestingly it is for MEG, but for _acq-EEG and EEG section does not define any shapes, only fiducial points and individual xyz of electrodes).
• ???

Potential solutions

shape entity + complimentary shapes/ folder

• Define shape entity so there could be shape_id = shape_<label>.
• Any {probe,shank,electrode}s.{tsv,json} could have shape_id column to associate any particular instance with a specific shape
  • we already have _electrodes.{tsv,json} suffix/sidecar files! so it is just a matter of the fact that any {entity_plural}.{tsv,json} becomes a suffix if within another entity (left comment in https://github.com/bids-standard/bids-2-devel/issues/58#issuecomment-2551845207)
• shapes.{tsv,json} could potentially provide description of "simple" shapes right there as e.g. with pre-specified columns such as planar_geometry (circle, square), and properties for those (width, radius) as applicable, with value "custom" pointing to the next:
• In a spirit of https://github.com/bids-standard/bids-2-devel/issues/54 define top level, shapes/ folder with shape-<label>_shape.pos files to describe shapes for any given probe shape in the .pos format (whatever it is) or adopt some other appropriate formats e.g. for mesh definitions or contours etc. This way there could also form some "reusable" shapes/ collection.

Data structure within sidecar .json

In BEP032 PR # 1705 we suggested to use sidecar json field ProbeContours:

"ProbeContours": {
   "probe_infoid": {
      "<my_probe_id>": {
         "Contour": <list of contour points>,
         "Unit": "<my spatial unit>"
      }
   }
}

Benefits: simple, and immediately would benefit from inheritance principle allowing to define all contours in a single (hopefully, since ATM still would need some entity IIRC, thus might need to be duplicated... needs clarification) ephys.json file on top.