Difference between revisions of "Documentation/Nightly/Developers/Units"

From Slicer Wiki
Jump to: navigation, search
Line 13: Line 13:
 
== Selection Node ==
 
== Selection Node ==
 
In order to propagate the unit in the application easily, access methods were added to the selection so it could stores the information regarding the current unit for a given quantity.
 
In order to propagate the unit in the application easily, access methods were added to the selection so it could stores the information regarding the current unit for a given quantity.
These methods are based the reference role of the vtkMRMLNode. The signal vtkMRMLSelectionNode::UnitModifiedEvent was added to the selection node so the application could be updated when an unit is modified/added/removed.
+
These methods are based the reference role of the ''vtkMRMLNode''. The signal ''vtkMRMLSelectionNode::UnitModifiedEvent'' was added to the selection node so the application could be updated when an unit is modified/added/removed.
  
 
== Unit Nodes ==
 
== Unit Nodes ==
Line 37: Line 37:
 
     }
 
     }
  
If the unit needs accessed multiple times (unlikely), then one can observe the selection nodes vtkMRMLSelectionNode::UnitModifiedEvent
+
If an unit needs to be accessed multiple times (very unlikely), then one can observe the selection nodes ''vtkMRMLSelectionNode::UnitModifiedEvent''.
  
 
== In the GUI==
 
== In the GUI==
  
Three qMRMLWidget have been added (or modified) to do this work for you:  
+
Three ''qMRMLWidget'' have been added (or modified) to integrate unit support:  
 
* qMRMLSpinBox
 
* qMRMLSpinBox
 
* qMRMLCoordinateWidget
 
* qMRMLCoordinateWidget
Line 47: Line 47:
 
* qMRMLRangeWidget
 
* qMRMLRangeWidget
  
They derive directly from their CTK counterpart and only add two methods. SetMRMLScene which is expected for a qMRML widget so they can observe the selection node UnitModifiedEvent()
+
They derive directly from their CTK counterpart and only add two methods. ''SetMRMLScene()'' (which is expected for a qMRML widget) so they can observe the selection node ''UnitModifiedEvent'' and the quantity property. Setting this property (''setQuantity()'') tells the widget what kind of unit node it should refer to. If a unit node with such quantity is default in the application, the widget will automatically update its minimum value, maximum value, single step, decimals, prefix and suffix according to the unit node.
and the quantity property. This property tells the widget what kind of unit node it should refer to. If a unit node with such quantity is default in the application, the widget will update its minimum value, maximum value, single step, decimals, prefix and suffix according to the unit node.
 

Revision as of 15:40, 27 May 2013

Home < Documentation < Nightly < Developers < Units

Slicer Units Overview

The Unit is a loadable module that allows the application to have a notion a unit. An unit is defined by its quantity (cf SI and quantities) and its name.

Intended capabilities

The units are intended to be used to describe a the quantity of a given object. The units should help the application to be smarter about how the user can access/view/interact with the data. For example, the unit help the user by displaying the unit in spinboxes as a suffix (1.3mm instead of 1.3).

Architecture

Settings

Right now, there are two quantities allowed (time and length). For each of these, there is an associated unit node which properties are saved in the settings. The unit nodes are not saved with the scene, it's just a setting.

Selection Node

In order to propagate the unit in the application easily, access methods were added to the selection so it could stores the information regarding the current unit for a given quantity. These methods are based the reference role of the vtkMRMLNode. The signal vtkMRMLSelectionNode::UnitModifiedEvent was added to the selection node so the application could be updated when an unit is modified/added/removed.

Unit Nodes

The vtkMRMLUnitNode are singleton and NOT saved in the scene. They have the following properties:

  • Name: The name describes the unit itself. For example the name of a length unit can be Milimetre, Metre, CentiMetre... Setting the node's name also sets the node's singleton tag.
  • Quantity: This properties is an attribute so it can be observed by the GUI. It describes what types of unit it is. For example second and day's quantity is time.
  • Precision: Describes the number of digit used after the comma. For example a precision of 2 gives 12.00 and -13.61
  • Prefix/Suffix: The unit abbreviation/text displayed respectively before and after the unit.
  • Minimum Value/Maximum Value: Range of value allowed for the unit. For example, the minimum for the Kelvin value would be 0.

How to access an Unit ?

Units can be accessed through the selection node.

In logic/nodes

For one-time access, it's preferable to do the following:

 vtkMRMLSelectionNode* selectionNode =  vtkMRMLSelectionNode::SafeDownCast(
   this->GetMRMLScene()->GetNthNodeByClass(0, "vtkMRMLSelectionNode"));
 if (selectionNode)
   {
   vtkMRMLUnitNode* unitNode = selectionNode->GetUnitNode(quantity); // Note: most often quantity will be a const string like "length" or "time"
   ...
   }

If an unit needs to be accessed multiple times (very unlikely), then one can observe the selection nodes vtkMRMLSelectionNode::UnitModifiedEvent.

In the GUI

Three qMRMLWidget have been added (or modified) to integrate unit support:

  • qMRMLSpinBox
  • qMRMLCoordinateWidget
  • qMRMLSliderWidget
  • qMRMLRangeWidget

They derive directly from their CTK counterpart and only add two methods. SetMRMLScene() (which is expected for a qMRML widget) so they can observe the selection node UnitModifiedEvent and the quantity property. Setting this property (setQuantity()) tells the widget what kind of unit node it should refer to. If a unit node with such quantity is default in the application, the widget will automatically update its minimum value, maximum value, single step, decimals, prefix and suffix according to the unit node.