UpdateBot: Nightly -> 4.4

2014-12-24T19:59:18Z

Nightly -> 4.4

New page

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

== Goal ==

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

== 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 <code>vtkMRMLNode</code> 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 the 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 <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: http://slicer.org/doc/html/classvtkMRMLNode-members.html

Currently the following MRML nodes are implemented using MRML Node Reference API:
* vtkMRMLStorableNode
* vtkMRMLTransformableNode
* vtkMRMLDisplayableNode

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

Documentation/4.4/Developers/MRML/NodeReferences - Revision history

UpdateBot: Nightly -> 4.4