API for split supervoxel hierarchy

[stuarteberg]

When a supervoxel A is split into B and C, it would be nice if I had a way to query DVID to learn B's "parent" supervoxel.

Something like:

/api/node/<uuid>/<labelmap-instance>/parent/<B>, which returns the parent ID.

If you want to get a little fancier, you could return the whole tree of splits that mentions B, in JSON form.

<server>/api/node/<uuid>/<labelmap-instance>/split-tree/<B>

Returns the entire split tree that contains B, if any.

If SV 1 were split into 2 and 3, and then 2 was further split into 4 and 5, maybe it would return something like the following:

GET <server>/api/node/<uuid>/<labelmap-instance>/split-tree/2

{
  "1": {
    "2": {
      "4": null,
      "5": null
    },
    "3": null
}

[DocSavage]

Is the hierarchy necessary for you, or will you always know the supervoxel ids you want the parents for? For your fancy tree, you give SV 2 but ask for sibling 3 and children 4 and 5, which is the inverse of the mapping in your first request.

[stuarteberg]

In the near term, I just need the parent. My use case is for the cleave server. When I see that a body of interest contains a supervoxel that isn't mentioned in my merge graph for that body, I'll assume that it's probably split fragment. I'll ask DVID for it's parent, and then patch my merge graph.

Having the entire tree might be convenient in other scenarios, particularly when debugging unexpected differences between our agglomeration and the original FFN agglo.

If it's easy for you to implement the API to give the complete tree, I'll take it. If it's hard, just implement the /parent (or whatever name you choose). If it's somewhere between easy and hard, well, it's your call. :-)

BTW: The json response above is just an example. Of course, another way to express the same information could be a simple mapping of child -> parent.

GET <server>/api/node/<uuid>/<labelmap-instance>/split-tree/2

[[4,2],
 [5,2],
 [2,1],
 [3,1]]

That might be even more convenient for clients who were only interested in a particular split fragment.

[stuarteberg]

BTW, it would also be useful for me to obtain ALL split mappings for a given uuid, or perhaps for the entire instance, across all nodes in the DAG (assuming split supervoxel IDs are unique, even across branches).

[stuarteberg]

After discussing with @DocSavage, I'd like to emphasize my previous comment. I need the ability to load all splits at once, for the entire instance.

I think my preferred format is a simple table of [child, parent] pairs as shown above, in JSON. But protobuf is fine, too, if you must. ;-)

[stuarteberg]

In person, we revised the proposed format of the response. Now it will look something like this:

[
  "abc123",
    [[<old>, <remain>, <split>],
     [<old>, <remain>, <split>],
     [<old>, <remain>, <split>]],
  "bcd234",
    [[<old>, <remain>, <split>],
     [<old>, <remain>, <split>],
     [<old>, <remain>, <split>]]
]

In that list, the UUIDs should be sorted topologically.