SurfaceTransform class

[feilong]

Transforms data between different surface spaces.

Dylan is working on algorithms to derive the transforms.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 89.92629% with 41 lines in your changes missing coverage. Please review.

Project coverage is 94.39%. Comparing base (76832f5) to head (f34d609). Report is 4 commits behind head on master.

:exclamation: Current head f34d609 differs from pull request most recent head f69faaf

Please upload reports for the commit f69faaf to get more accurate results.

Files	Patch %	Lines
nitransforms/surface.py	89.37%	26 Missing and 13 partials :warning:
nitransforms/base.py	94.87%	1 Missing and 1 partial :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #203 +/- ## ========================================== - Coverage 95.79% 94.39% -1.40% ========================================== Files 14 15 +1 Lines 1307 1713 +406 Branches 259 323 +64 ========================================== + Hits 1252 1617 +365 - Misses 52 79 +27 - Partials 3 17 +14 ``` | [Flag](https://app.codecov.io/gh/nipy/nitransforms/pull/203/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=nipy) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/nipy/nitransforms/pull/203/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=nipy) | `94.39% <89.92%> (-1.40%)` | :arrow_down: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=nipy#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[Shotgunosine]

From the documentation for wb_command -surface-sphere-project-unproject:

A surface registration starts with an input sphere, and moves its vertices around on the sphere until it matches the template data. This means that the registration deformation is actually represented as the difference between two separate files - the starting sphere, and the registered sphere. Since the starting sphere of the registration may not have vertex correspondence to any other sphere (often, it is a native sphere), it can be inconvenient to manipulate or compare these deformations across subjects, etc.

Based on that description, I think the next class we need is one that will represent registration deformation and contains the original sphere and the deformation sphere (in other words, mea culpa, @oesteban was right). I'm not 100% certain it will be useful for anything (maybe project-unproject?), but it is the representation of the deformation.

Edit: Ok actually the Surface Coordinate Transform class will already represent this deformation.

[oesteban]

As I mentioned, I totally see why you wanted to focus on the interpolation matrix. In practical terms, it's all you care for.

But to calculate it, in one way or another you need to formalize the transform ;)

[Shotgunosine]

@oesteban Happy to talk about it more, but I think the SurfaceCoordinateTransform is the formalization of the transform. Isn't it? The deformation itself isn't useful and transforming data by subtracting the coordinate would less accurate than looking up the new coordinates by index.

[oesteban]

@oesteban Happy to talk about it more, but I think the SurfaceCoordinateTransform is the formalization of the transform. Isn't it? The deformation itself isn't useful and transforming data by subtracting the coordinate would less accurate than looking up the new coordinates by index.

Yup, that's correct.

[Shotgunosine]

In terms of use cases for surface transformations, here's what I can think of: 1) Taking some metric defined on the cortical surface in subject T1w space and determining what the value of that metric would be for every vertex in a reference space (wb_command -metric-resample). 2) Taking labels defined in a reference space and determining which vertices in subject space those labels should be applied to (wb_command -label-resample). 3) Creating a surface in which every vertex corresponds to a vertex from a reference surface, but with coordinates defined in the subject's T1w space (wb_command -surface-sphere-project-unproject).

We can kinda do 1 and 2 with the resampling method we've got now (though we've only implemented barycentric for this and they recommend adap_bary_area). I still have trouble wrapping my head around how surface-sphere-project-unproject works, but I feel like that's the next use case to try implementing to confirm that this representation of surface transformation is sufficient.

[feilong]

Hi @Shotgunosine, I think surface-sphere-project-unproject is closely related to the transform @oesteban wants. It defines the warp using two spheres (e.g., sphere and sphere.reg). If a new sphere X is aligned to one of them (say, sphere.reg), we can use the barycentric weights (between sphere.reg and X) and the coordinates of sphere to warp X. That is, computing the new coordinates of X when it's aligned to sphere space. Conceptually, it's a diffeomorphic transform defined by the two spheres. In practice, this is hardly used. The only use case I know is warping between fsaverage and fs_LR spheres. That being said, it's good to have it for completeness.