View source for Documentation/4.8/Developers/MRML/NodeReferences

<noinclude>{{documentation/versioncheck}}</noinclude>

== Overview ==

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

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).

== 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 [{{doxygen-class-url|vtkMRMLNode}} 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
reference in the .mrml file.

The only other call that is needed is either:
<pre>
vtkMRMLNode* SetAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);
</pre>
or 
<pre>
vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const char* referencedNodeID, vtkIntArray *events=0);
</pre>
if multiple instances of this reference are allowed.

[{{doxygen-class-url|vtkMRMLNode}} vtkMRMLNode] also provides virtual callbacks that can be extended in the
derived classes:
<pre>
OnNodeReferenceAdded(vtkMRMLNodeReference *reference)
OnNodeReferenceRemoved(vtkMRMLNodeReference *reference)
OnNodeReferenceModified(vtkMRMLNodeReference *reference)
</pre>

By default those methods generate the following events:
<pre>
vtkMRMLNode::ReferenceAddedEvent
vtkMRMLNode::ReferenceRemovedEvent
vtkMRMLNode::ReferenceModifiedEvent
</pre>

In the derived classes those methods could be extended using <code>vtkMRMLNode</code>
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 [{{doxygen-class-url|vtkMRMLNode|members}} here]

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]

Other references to MRML nodes such as to [{{doxygen-class-url|vtkMRMLColorTableNode}} vtkMRMLColorTableNode], [{{doxygen-class-url|vtkMRMLDiffusionTensorDisplayPropertiesNode}} 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