ENH: Add structure ID to JSON format.

Adds `structure` to each control point in JSON output. This value is ignored during file loading, only used as metadata in consuming applications. See #208.

Note this change requires each `Annotation` instance hold a reference to the `HomeLogic` instance. Looking toward #196, it may make sense to introduce a "AtlasLogic" or similar which contains the volume node, color node, and related metadata _for only one atlas_. This metadata could then be serialized within `Annotation.toDict`.

CHANGES.md

@@ -4,6 +4,8 @@
 
 Features:
 
+- Add structure ID and acronym to JSON format. [#208](https://github.com/BICCN/cell-locator/issues/208)
+
 Fixes:
 
 - Don't show exit confirmation when file (or LIMS specimen) is unchanged. [#204](https://github.com/BICCN/cell-locator/pull/204)

Documentation/developer_guide/AnnotationFileFormat.md

@@ -10,6 +10,10 @@ We mean it.
 
 ## Versions
 
+## Next Release
+
+Add the `structure` object to control point. `null` for values with missing structure (outside of atlas, converted from old file, etc.)
+
 ## 0.2.0 (2021-08-11)
 
 Unchanged from 0.1.1; this version synchronizes the file format and cell locator release.

Modules/Scripted/Home/Home.py

@@ -67,11 +67,12 @@ class Annotation(VTKObservationMixin):
   DisplayName = 'Annotation'
   MarkupType = ''
 
-  def __init__(self, markup=None):
+  def __init__(self, homeLogic, markup=None):
     """Setup the annotation markup and model, and add each to the scene."""
 
     VTKObservationMixin.__init__(self)
 
+    self.homeLogic = homeLogic  # For structure information.
     self.logic = slicer.vtkSlicerSplinesLogic()
 
     if markup is not None:
@@ -144,6 +145,22 @@ def toDict(self) -> dict:
           for control in markup['controlPoints']
         ]
 
+        volumeNode = self.homeLogic.getAnnotation()
+        transform = self.homeLogic.getWorldRASToIJKTransform(volumeNode)
+        for i, point in enumerate(markup['controlPoints']):
+          ras = [0, 0, 0]
+          self.markup.GetNthControlPointPositionWorld(i, ras)
+          ijk = transform.TransformPoint(ras)
+          index = self.homeLogic.getAllenLabelIndex(ijk, volumeNode)
+
+          try:
+            point['structure'] = {
+              'id': index,
+              'acronym': self.homeLogic.AllenStructureNames[index],
+            }
+          except KeyError:
+            point['structure'] = None
+
     return {
       'markup': markup,
       'name': self.markup.GetName(),
@@ -152,7 +169,7 @@ def toDict(self) -> dict:
     }
 
   @classmethod
-  def fromMarkup(cls, markup):
+  def fromMarkup(cls, homeLogic, markup):
     """Initialize an Annotation given an existing markup. Selects from subclasses based on that class's MarkupType.
 
     For example, FiducialsAnnotation is a subclass of Annotation, so it is queried. FiducialsAnnotation.MarkupType is
@@ -167,13 +184,13 @@ def fromMarkup(cls, markup):
 
     for icls in cls.__subclasses__():
       if markup.IsA(icls.MarkupType):
-        return icls(markup=markup)
+        return icls(homeLogic, markup=markup)
 
     logging.error('Unsupported markup type %r', markup.GetClassName())
     return None
 
   @classmethod
-  def fromDict(cls, data):
+  def fromDict(cls, homeLogic, data):
     """Convert a dict representation to an annotation, suitable for json deserialization."""
 
     with tempfile('json/annotation.json') as filename:
@@ -193,7 +210,7 @@ def fromDict(cls, data):
     # we want to use fromMarkup so the correct behavior (annotation type) is used for the given markup type.
     # since each annotation type may have extra parameters, we should use setMetadata
 
-    annotation = cls.fromMarkup(markup)
+    annotation = cls.fromMarkup(homeLogic, markup)
     annotation.setMetadata(data)
     annotation.orientation.DeepCopy(listToMat(data['orientation']))
 
@@ -211,8 +228,8 @@ class FiducialAnnotation(Annotation):
   DisplayName = 'Point'
   MarkupType = 'vtkMRMLMarkupsFiducialNode'
 
-  def __init__(self, markup=None):
-    super().__init__(markup=markup)
+  def __init__(self, homeLogic, markup=None):
+    super().__init__(homeLogic, markup=markup)
 
 
 class ClosedCurveAnnotation(Annotation):
@@ -222,15 +239,15 @@ class ClosedCurveAnnotation(Annotation):
   DefaultRepresentationType = 'spline'
   DefaultThickness = 50
 
-  def __init__(self, markup=None):
+  def __init__(self, homeLogic, markup=None):
     self.representationType = self.DefaultRepresentationType
     self.thickness = self.DefaultThickness
 
     self.model = slicer.mrmlScene.AddNode(slicer.vtkMRMLModelNode())
     self.model.CreateDefaultDisplayNodes()
 
     # need to have representationType, thickness, model, etc when the markup is created.
-    super().__init__(markup=markup)
+    super().__init__(homeLogic, markup=markup)
 
     generator = self.markup.GetCurveGenerator()
     generator.SetNumberOfPointsPerInterpolatingSegment(20)
@@ -285,7 +302,7 @@ def setMetadata(self, data):
 class AnnotationManager:
   """Manage serialization and bookkeeping for a collection of annotations."""
 
-  FORMAT_VERSION = '0.2.0+2021.08.12'
+  FORMAT_VERSION = '0.2.1+2022.03.04'
 
   DefaultReferenceView = 'Coronal'
   DefaultOntology = 'Structure'
@@ -413,12 +430,12 @@ def toDict(self):
     }
 
   @classmethod
-  def fromDict(cls, data):
+  def fromDict(cls, homeLogic, data):
     """Convert a dict representation to annotation collection, suitable for json deserialization."""
 
     manager = cls()
 
-    manager.annotations = [Annotation.fromDict(item) for item in data['markups']]
+    manager.annotations = [Annotation.fromDict(homeLogic, item) for item in data['markups']]
     manager.currentIdx = data['currentId']
 
     manager.referenceView = data['referenceView']
@@ -453,7 +470,7 @@ def toFile(self, fileName=None, indent=2):
       json.dump(data, f, indent=indent)
 
   @classmethod
-  def fromFile(cls, fileName):
+  def fromFile(cls, homeLogic, fileName):
     """Load an annotation collection from a json file.
 
     Instance variable fileName is set, so that subsequent calls to toFile() will
@@ -463,7 +480,7 @@ def fromFile(cls, fileName):
     with open(fileName) as f:
       data = json.load(f)
 
-    manager = cls.fromDict(data)
+    manager = cls.fromDict(homeLogic, data)
     manager.fileName = fileName
 
     return manager
@@ -603,7 +620,7 @@ def postStartupInitialization():
 
       annotationFilePath = slicer.app.commandOptions().annotationFilePath
       if annotationFilePath:
-        annotations = AnnotationManager.fromFile(annotationFilePath)
+        annotations = AnnotationManager.fromFile(self.logic, annotationFilePath)
         self.setAnnotations(annotations)
         self.annotationStored()
 
@@ -690,20 +707,20 @@ def saveIfRequired(self):
   def onAddCurveAnnotationButtonClicked(self):
     """Add a curve annotation to the tree view."""
 
-    self.Annotations.add(ClosedCurveAnnotation())
+    self.Annotations.add(ClosedCurveAnnotation(self.logic))
 
   def onAddPointAnnotationButtonClicked(self):
     """Add a point annotation to the tree view."""
 
-    self.Annotations.add(FiducialAnnotation())
+    self.Annotations.add(FiducialAnnotation(self.logic))
 
   def onCloneAnnotationButtonClicked(self):
     """Clone the current annotation and add it to the tree view."""
 
     # copy all attributes of the annotation, reusing the existing serialization logic.
     # convert to dict and back.
     data = self.Annotations.current.toDict()
-    annotation = Annotation.fromDict(data)
+    annotation = Annotation.fromDict(self.logic, data)
 
     self.Annotations.add(annotation=annotation)
 
@@ -769,7 +786,7 @@ def onLoadAnnotationButtonClicked(self):
 
     self.setInteractionState('explore')
     self.Annotations.clear()
-    annotations = AnnotationManager.fromFile(fileName)
+    annotations = AnnotationManager.fromFile(self.logic, fileName)
     self.setAnnotations(annotations)
     self.annotationStored()
 
@@ -798,7 +815,7 @@ def loadLIMSSpecimen(self, specimenID):
       return
 
     if res.status_code == 200:
-      annotations = AnnotationManager.fromDict(res.json()['data'])
+      annotations = AnnotationManager.fromDict(self.logic, res.json()['data'])
       self.setAnnotations(annotations)
     else:
       try:
@@ -1422,7 +1439,7 @@ def onSceneEndCloseEvent(self, caller=None, event=None):
 
     # Setup Annotations
     annotations = AnnotationManager()
-    annotations.add(ClosedCurveAnnotation())
+    annotations.add(ClosedCurveAnnotation(self.logic))
     self.setAnnotations(annotations)
     self.setDefaultSettings()
     self.Annotations.current.orientation.DeepCopy(sliceNode.GetSliceToRAS())