Migrate aeva to the graph resource
Motivation
This issue exists to document/discuss the next version of aeva's resource. Currently, aeva has modeling entities taken from traditional boundary-representation (b-rep) modeling (volumes, surfaces, edges, vertices); these entities are marked with properties to denote their function (e.g., side set vs primary geometry). This has been restrictive, since our b-rep model doesn't include fields/functions defined on geometric domains and other common anatomical annotations.
We don't want to just confiscate MRML's schema — it is relatively low-level; it is focused on serializing visualizations/scenes of mostly-structured (image) data; and it does not provide obvious integration with anatomical ontologies. Nor do we want to stick with the MED data model which is focused on simulation preparation as opposed to annotation.
To address this, we are prototyping a change in aeva to a different type of resource based one multipartite graphs: entities are nodes in the graph and related to one another via arcs. The node types and arc types are up to the application (aeva in this case). Below, we propose some node and arc types. The goal is not to implement all of these initially, but to identify a consistent approach to organizing annotations so that we avoid redundant or confusing nodes and arcs.
Proposed entity (node) types
Common base types
-
Annotation
; The base type for allCollection/Reference
entries -
PrimaryAnnotation
;Annotation
that needs nothing external to define itself -
ReferenceAnnotation
;Annotation
whose existence depends on reference(s) to other annotations
Grouping types
-
Collection
; InheritsPrimaryAnnotation
. Container with ownership semantics (removingCollection
children removes them from the resource). -
References
; InheritsReferenceAnnotation
. Container with reference semantics (removingReferences
children leaves them in the resource).
Primary shape types
These node types have geometric representation independent of any other entities.
-
Frame
; InheritsPrimaryAnnotation
. A coordinate system (specified relative to world coordinates). -
Plane
: InheritsPrimaryAnnotation
. A datum plane such as the sagittal or coronal planes. -
Image
; InheritsPrimaryAnnotation
. A regular grid (points with implied connectivity) thatField
instances may reference. -
DiscreteVolume
; InheritsPrimaryAnnotation
. An unstructured grid (points and connectivity).Fields
may reference. -
DiscreteSurface
; InheritsPrimaryAnnotation
. A polygonal surface grid (points and connectivity).Fields
may reference. -
CompSolid
; InheritsPrimaryAnnotation
. A composite CAD solid via OpenCascade. -
Solid
; InheritsPrimaryAnnotation
. A volumetric CAD region via OpenCascade. -
Surface
; InheritsPrimaryAnnotation
. A CAD surface via OpenCascade. -
Edge
; InheritsPrimaryAnnotation
. A CAD edge via OpenCascade. -
Vertex
; InheritsPrimaryAnnotation
. A CAD model-vertex via OpenCascade.
Reference shape types
These node type have a geometric representation dependent on some other modeling entity.
-
SubSet
; InheritsReferenceAnnotation
. A portion of one or morePrimaryAnnotation
instances. -
SideSet
; InheritsReferenceAnnotation
. Lower-dimensional boundary or one or morePrimaryAnnotation
instances. -
NodeSet
; InheritsReferenceAnnotation
. A special-case ofSideSet
consisting only of points.
Non-geometric annotations
-
Field
; InheritsReferenceAnnotation
. A function that takes on a value over some referenced shape or collection of shapes. -
Segmentation
; InheritsField
. An integer-valuedField
with values that areLabels
. -
Label
; InheritsReferenceAnnotation
. An integer value (or set of values) taken on by a referencedSegmentation
field. -
Tissue
; InheritsPrimaryAnnotation
. A type of tissue -
Organ
; InheritsReferenceAnnotation
. A functional collection of referenced tissues. -
Feature
; InheritsReferenceAnnotation
. A generic notation of interest that is common to some referenced cohort. -
Landmark
; InheritsFeature
. A feature whose referenced cohort has a geometric representation. -
OntologyId
; InheritsReferenceAnnotation
. This holds an OWL URL that applies to the referenced annotation. -
Comment
; InheritsReferenceAnnotation
. User-provided text to be stored as a note on the referenced annotation. -
Interaction
; InheritsFeature
. A feature denoting some interaction (e.g., adhesion, sliding contact) between its references -
Function
; InheritsReferenceAnnotation
. Used to denote a biological function provided by the referenced data (e.g., joint surface, duct, hormone production).
Proposed arc types
Given a collection of nodes as above, we should provide some way to relate them. Strict adherence to the types of relations adds some simple validity checking. Many of these are related to concepts in ontologies such as FMA or Uberon
Grouping arcs
-
Child
; from a parent to a child. The parent must be aPrimaryAnnotation
and the child aReferenceAnnotation
. -
Parent
; from a child to a parent. The parent must be aPrimaryAnnotation
and the child aReferenceAnnotation
.
Provenance arcs
-
Derivative
; from an annotation used as source material for another (derived) annotation. Examples:- a Field defined on an image is imprinted onto a surface overlapped by the image, creating a new Field. The image's Field has a Derivative arc connecting to the new Field.
- a solid model is meshed; the solid model has a Derivative arc connecting to the mesh.
-
DerivedFrom
; the inverse of a Derivative arc. -
Marks
andMarkupFor
; Indices that one piece of primary geometry serves as markup for another. Examples:- a 2-D polygon might serve as a parameter-space markup on a
Surface
to indicate a proposed surgical plan. - a
Landmark
in world coordinates might serve as markup for to anchor aComment
.
- a 2-D polygon might serve as a parameter-space markup on a
Geometric arcs
- Anatomical relationships
-
Superior
andInferior
-
Lateral
andMedial
-
Anterior
andPosterior
-
Extremal
andDistal
-
Ventral
andDorsal
-
Superficial
andDeep
-
Cephalic
andCaudal
-
Afferent
andEfferent
-
- Algebraic relationships
-
ReferenceFrame
; from any primary geometry to aFrame
node, indicating how to transform geometry into the scene. -
Deflection
; from a vector-valuedField
node to any primary geometry, indicating a deformation that may be applied.
-
Functional arcs
-
Constitutes
andDivides
; relate tissues or organs to groupings (e.g., bones, cartilage, ligaments that constitute a knee joint) -
BranchOf
andConnects
; relate portions of a branching structure such as lungs, arteries, neurons.
Example
An example of how the femur-tibia-acl tutorial data might be expressed using the graph resource. Node names/values are followed by the node type in parentheses.
Not all of the nodes are shown in order to make the graph more legible: specifically, the MRI image would have a separate file node and 2 geometry-group entries: "data (image)" and "density (field)". There are also missing entries for the tibia-acl insertion-point areas. Other nodes might be added by a user but are not supported in aeva 2.0 (e.g., a medial plane, a reference frame describing a coordinate system).