Support loading of user-generated normals

[kevinyamauchi]

I think we should support loading of user-generated normals. Perhaps we can start via the python API (user passes in an (n x 3) array as it's the easiest thing. I would propose the following:

• if present, load the surface normals from an (n x 3) array in the normal_vectors key in the layer.metadata. otherwise, compute the normals. this way other plugins can easily pass normal vectors to surforama and people can programatically add them via the python API.
• later, we can add a VTK reader that grabs the surface normals from a VTK file (vertex data) and load them into the appropriate layer.metadata key

From @bbarad in https://github.com/cellcanvas/surforama/issues/4#issuecomment-1988982870:

Pycurv (and therefore also surface morphometrics) currently stores vector-voted face normals as a graph property that can be accessed as an Nx3 array (albeit its face-centered rather than vertex-centered so it will need some calculation fixes...) so I'd be fine with reading from an Nx3 array or constraining to the vtk filetype (which makes node annotation very easy as you mentioned).

[kevinyamauchi]

I thought about it a bit more and I am in favor of the layer metadata approach. I think the main question about that implementation is if the key should be a "top level" key or under a surforama key.

Top level:

>>>  layer.metadata
{ "vertex_normals": [[ ...]]}

under surforama key:

>>>  layer.metadata
{ 
    "surforama": {
        "vertex_normals": [[ ...]]}
    }
}

The advantage of the surforama key is that it reduces the chance of a name collision. The advantage of the top level approach is that we might be able to convince other plugins to do the same and that facilitates interchange.

Thoughts?

[bbarad]

Vertex normals should be consistent across basically any analysis (and if another tool improves them, all the better for surforama or morphometric analysis or anything else) so I'd prefer the top-level implementation.

Would it be better to define "vertex_properties" and then do normals under that, so you could do something similar with "face_properties" and "edge_properties"? That is more or less how triangle graphs in pycurv are organized and I find it relatively intuitive, but I am not attached to doing it that way. It might be a more flexible long term organization for mesh layers.