Difference between revisions of "Documentation/Nightly/Developers/MRML/NodeReferences"
(Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887) |
m (→New API) |
||
| Line 33: | Line 33: | ||
class. The only thing that needs to happen in the derived MRML node class | class. The only thing that needs to happen in the derived MRML node class | ||
(usually in the constructor of the class) | (usually in the constructor of the class) | ||
| − | is a call to vtkMRMLNode::AddNodeReferenceRole(const char *referenceRole, | + | is a call to <code>vtkMRMLNode::AddNodeReferenceRole(const char *referenceRole, |
| − | const char *mrmlAttributeName) | + | const char *mrmlAttributeName)</code> |
that takes a unique string defining the reference role between this node | 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 | ||
| Line 40: | Line 40: | ||
The only other call that is needed is either: | The only other call that is needed is either: | ||
| + | <pre> | ||
vtkMRMLNode* SetAndObserveNodeReferenceID(const char* referenceRole , const | vtkMRMLNode* SetAndObserveNodeReferenceID(const char* referenceRole , const | ||
char* referencedNodeID, vtkIntArray *events=0); | char* referencedNodeID, vtkIntArray *events=0); | ||
| + | </pre> | ||
or | or | ||
| + | <pre> | ||
vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const | vtkMRMLNode* AddAndObserveNodeReferenceID(const char* referenceRole , const | ||
char* referencedNodeID, vtkIntArray *events=0); | char* referencedNodeID, vtkIntArray *events=0); | ||
| + | </pre> | ||
if the multiple instances of this reference are allowed. | if the multiple instances of this reference are allowed. | ||
Revision as of 19:20, 30 October 2013
Home < Documentation < Nightly < Developers < MRML < NodeReferences
|
For the latest Slicer documentation, visit the read-the-docs. |
Contents
Goal
This page explains how to create a MRML node that reference and observes other MRML nodes.
History
In Slicer4.2 prior to March of 2013 each MRML node that contained references to other MRML nodes (for example each vtkMRMLDispalyableNode 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
- UpdateReferenceIS
- SetSceneRefeecnes
- UpdateScene
- UpdateReferences
- SetAndObserveReferenedNode
New API
The new node reference API automatically takes care of read/write/copy of
node references, updating references on scene import, adding and deleting
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 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 the multiple instances of this reference are allowed.
vtkMRMLNode also provides virtual callbacks that can be extended in the derived calsses:
- 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:
http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Libs/MRML/Core/vtkMRMLNode.h?view=log
Currently the following MRML nodes are implemented using new 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.
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
