Difference between revisions of "Documentation/Nightly/Developers/MRML/NodeReferences"

From Slicer Wiki
Jump to: navigation, search
m
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<noinclude>{{documentation/versioncheck}}</noinclude>
 
<noinclude>{{documentation/versioncheck}}</noinclude>
−
== Goal ==
 
−
This page explains how to create a MRML node that reference and observes
 
−
other MRML nodes.
 
  
−
== History ==
+
== Overview ==
−
In Slicer4.2 prior to March of 2013 each MRML node that contained
+
 
−
references to other MRML nodes (for example each vtkMRMLDisplayableNode contained
+
This page explains how to create a MRML node that reference and observes other MRML nodes.
−
a reference to an instance vtkMRMLDisplayNode) was responsible for
+
 
−
managing the references internally. This involved complicated logic and
+
As describe in the [[Documentation/{{documentation/version}}/Developers/MRML#MRML_Nodes|MRML Nodes]] section, node references allow to associate data node implementing interfaces (like [{{doxygen-class-url|vtkMRMLDisplayableNode}} Displayable], [{{doxygen-class-url|vtkMRMLStorableNode}} Storable] and [{{doxygen-class-url|vtkMRMLTransformableNode}} Transformable]) with a representation node (like [{{doxygen-class-url|vtkMRMLStorageNode}} Storage] or [{{doxygen-class-url|vtkMRMLDisplayNode}} Display] node) or other data node (like [{{doxygen-class-url|vtkMRMLTransformNode}} Transform] node).
−
bookkeeping to maintain the references in sync when importing scenes,
 
−
adding/deleting nodes, modifying referenced nodes, etc.
 
  
−
When creating a new node with the reference to another node the following
+
== API Description ==
−
methods needed to be created/updated to handle the references:
 
  
 +
The node reference API automatically takes care of
 +
(1) read/write/copy of node references,
 +
(2) updating references on scene import,
 +
(3) adding and deleting nodes.
  
−
* Copy
+
All that functionality is implemented in the [{{doxygen-class-url|vtkMRMLNode}} vtkMRMLNode] base class.
−
* PrintSelf
 
−
* ReadXMLAttributes
 
−
* WriteXML
 
−
* ProcessMRMLEvents
 
−
* UpdateReferenceID
 
−
* SetSceneReferences
 
−
* UpdateScene
 
−
* UpdateReferences
 
−
* SetAndObserveNodeReferenceID
 
  
−
== New API ==
+
The only thing that needs to happen in the derived MRML node class (usually in the constructor of the class)
−
The new node reference API automatically takes care of read/write/copy of
+
is a call to <code>vtkMRMLNode::AddNodeReferenceRole(const char *referenceRole, const char *mrmlAttributeName)</code>
−
node references, updating references on scene import, adding and deleting
+
that takes a unique string defining the reference role between this node  
−
nodes. All that functionality in implemented the vtkMRMLNode base
 
−
class. The only thing that needs to happen in the derived MRML node class
 
−
(usually in the constructor of the class)
 
−
is a call to <code>vtkMRMLNode::AddNodeReferenceRole(const char *referenceRole,
 
−
const char *mrmlAttributeName)</code>
 
−
that takes a unique string defining the reference role between this node
 
 
and the referenced node, and a MRML attribute name for storing the
 
and the referenced node, and a MRML attribute name for storing the
 
reference in the .mrml file.
 
reference in the .mrml file.
Line 47: Line 30:
 
vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);
 
vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);
 
</pre>
 
</pre>
−
if the multiple instances of this reference are allowed.
+
if multiple instances of this reference are allowed.
  
−
vtkMRMLNode also provides virtual callbacks that can be extended in the
+
[{{doxygen-class-url|vtkMRMLNode}} vtkMRMLNode] also provides virtual callbacks that can be extended in the
−
derived calsses:
+
derived classes:
−
* OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
+
<pre>
−
* OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
+
OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
−
* OnNodeReferenceModified(vtkMRMLNodeReference *reference)
+
OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
 +
OnNodeReferenceModified(vtkMRMLNodeReference *reference)
 +
</pre>
  
 
By default those methods generate the following events:
 
By default those methods generate the following events:
−
* vtkMRMLNode::ReferenceAddedEvent
+
<pre>
−
* vtkMRMLNode::ReferenceRemovedEvent
+
vtkMRMLNode::ReferenceAddedEvent
−
* vtkMRMLNode::ReferenceModifiedEvent
+
vtkMRMLNode::ReferenceRemovedEvent
 +
vtkMRMLNode::ReferenceModifiedEvent
 +
</pre>
  
−
In the derived classes those methods could be extended using vtkMRMLNode
+
In the derived classes those methods could be extended using <code>vtkMRMLNode</code>
 
API that allows querying of node's references:
 
API that allows querying of node's references:
  
Line 68: Line 55:
 
* etc.
 
* etc.
  
−
For full API see:
+
For full API see [{{doxygen-class-url|vtkMRMLNode|members}} here]
  
−
http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLNode.h?view=log
+
Currently the following MRML nodes are implemented using MRML Node Reference API:
 +
* [{{doxygen-class-url|vtkMRMLStorableNode}} vtkMRMLStorableNode]
 +
* [{{doxygen-class-url|vtkMRMLTransformableNode}} vtkMRMLTransformableNode]
 +
* [{{doxygen-class-url|vtkMRMLDisplayableNode}} vtkMRMLDisplayableNode]
  
−
Currently the following MRML nodes are implemented using new API:
+
Other references to MRML nodes such as to [{{doxygen-class-url|vtkMRMLColorTableNode}} vtkMRMLColorTableNode], [{{doxygen-class-url|vtkMRMLDiffusionTensorDisplayPropertiesNode}} vtkMRMLDiffusionTensorDisplayPropertiesNode] are currently not using this API.  
−
* vtkMRMLStorableNode
 
−
* vtkMRMLTransformableNode
 
−
* vtkMRMLDisplayableNode
 
−
 
 
−
Other references to MRML nodes such as to vtkMRMLColorTableNode, vtkMRMLDiffusionTensorDisplayPropertiesNode are currently not using new API.
 
  
 
Module parameter nodes that contain references to input/output Volume/Model, etc. nodes may or may not require a new API since not all of them contain logic to deal with reference changes.
 
Module parameter nodes that contain references to input/output Volume/Model, etc. nodes may or may not require a new API since not all of them contain logic to deal with reference changes.
Line 88: Line 73:
 
* vtkMRMLStorableNodeimplementation:
 
* vtkMRMLStorableNodeimplementation:
 
http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLStorableNode.h?view=log
 
http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLStorableNode.h?view=log
 +
 +
== History ==
 +
In Slicer4.2 prior to March of 2013 each MRML node that contained
 +
references to other MRML nodes (for example each vtkMRMLDisplayableNode contained
 +
a reference to an instance vtkMRMLDisplayNode) was responsible for
 +
managing the references internally. This involved complicated logic and
 +
bookkeeping to maintain the references in sync when importing scenes,
 +
adding/deleting nodes, modifying referenced nodes, etc.
 +
 +
When creating a new node with the reference to another node the following
 +
methods needed to be created/updated to handle the references:
 +
 +
 +
* Copy
 +
* PrintSelf
 +
* ReadXMLAttributes
 +
* WriteXML
 +
* ProcessMRMLEvents
 +
* UpdateReferenceID
 +
* SetSceneReferences
 +
* UpdateScene
 +
* UpdateReferences
 +
* SetAndObserveNodeReferenceID

Latest revision as of 22:20, 3 April 2015

Home < Documentation < Nightly < Developers < MRML < NodeReferences


For the latest Slicer documentation, visit the read-the-docs.


Overview

This page explains how to create a MRML node that reference and observes other MRML nodes.

As describe in the MRML Nodes section, node references allow to associate data node implementing interfaces (like Displayable, Storable and Transformable) with a representation node (like Storage or Display node) or other data node (like Transform node).

API Description

The node reference API automatically takes care of (1) read/write/copy of node references, (2) updating references on scene import, (3) adding and deleting nodes.

All that functionality is implemented in the vtkMRMLNode base class.

The only thing that needs to happen in the derived MRML node class (usually in the constructor of the class) is a call to vtkMRMLNode::AddNodeReferenceRole(const char *referenceRole, const char *mrmlAttributeName) that takes a unique string defining the reference role between this node and the referenced node, and a MRML attribute name for storing the reference in the .mrml file.

The only other call that is needed is either: 

vtkMRMLNode* SetAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);

or 

vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);

if multiple instances of this reference are allowed.

vtkMRMLNode also provides virtual callbacks that can be extended in the derived classes: 

OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
OnNodeReferenceModified(vtkMRMLNodeReference *reference)

By default those methods generate the following events: 

vtkMRMLNode::ReferenceAddedEvent
vtkMRMLNode::ReferenceRemovedEvent
vtkMRMLNode::ReferenceModifiedEvent

In the derived classes those methods could be extended using vtkMRMLNode API that allows querying of node's references:

  • char *GetNthNodeReferenceID(const char* referenceRole, int n);
  • vtkMRMLNode* GetNthNodeReference(const char* referenceRole, int n);
  • int GetNumberOfNodeReferences(const char* referenceRole);
  • etc.

For full API see here

Currently the following MRML nodes are implemented using MRML Node Reference API:

Other references to MRML nodes such as to vtkMRMLColorTableNode, vtkMRMLDiffusionTensorDisplayPropertiesNode are currently not using this API.

Module parameter nodes that contain references to input/output Volume/Model, etc. nodes may or may not require a new API since not all of them contain logic to deal with reference changes.

Examples

  • vtkMRMLTransformableNode implementation:

http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLTransformableNode.h?view=log

  • vtkMRMLDisplayableNodeimplementation:

http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLDisplayableNode.h?view=log

  • vtkMRMLStorableNodeimplementation:

http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLStorableNode.h?view=log

History

In Slicer4.2 prior to March of 2013 each MRML node that contained references to other MRML nodes (for example each vtkMRMLDisplayableNode contained a reference to an instance vtkMRMLDisplayNode) was responsible for managing the references internally. This involved complicated logic and bookkeeping to maintain the references in sync when importing scenes, adding/deleting nodes, modifying referenced nodes, etc.

When creating a new node with the reference to another node the following methods needed to be created/updated to handle the references:


  • Copy
  • PrintSelf
  • ReadXMLAttributes
  • WriteXML
  • ProcessMRMLEvents
  • UpdateReferenceID
  • SetSceneReferences
  • UpdateScene
  • UpdateReferences
  • SetAndObserveNodeReferenceID
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Developers/MRML/NodeReferences&oldid=41277"