NAMIC Wiki - User contributions [en]

Slicer3:Downloads

2007-07-27T15:13:02Z

Klawson1:

{| class="toccolours" style="margin-right: 25px" align="right"
! bgcolor="#ccccff" align="center" | Slicer3
|-
|
[[Slicer3|Home]]
|-
|
[[Slicer3:About|About]]
|-
|
[[Slicer3:FAQ|FAQ]]
|-
|
[[Slicer3:Status|Status]]
|-
| '''Downloads'''
|-
|
[[Slicer3:Documentation|Documentation]]
|-
|
[[Slicer3:Community_Support|Community Support]]
|-
|
[[Slicer3:Developers|Developers]]
|-
|
[[Slicer3:Acknowledgements|Acknowledgements]]
|-
|
[[Slicer3:Links|Links]]
|}

==About Slicer3==

Slicer3 is a project under active development. See [[Slicer3:Status|the Status Page]] for more information on what the software does and the current status of product features. Release notes for Slicer3 are available [[Slicer3:Slicer3_Alpha_Release_Notes|here]]

As Slicer3 is changing on a daily basis, some features may not be implemented or will be in various stages of completion. Slicer2.6 is the current fully supported release of Slicer. For information about the current release of Slicer2.6, see [[Slicer:Slicer2.6_Getting_Started|Slicer2.6 Getting Started]].

There are a couple different ways to obtain Slicer3 to run on your own computer. You can either download a precompiled Slicer3 installer for your platform, or build it yourself from an SVN checkout.

==Obtaining a Precompiled Binary==

Compiled '''Slicer3 executables''' are [http://www.na-mic.org/Slicer/Download/Snapshots/ '''available here''']. From the Snapshots directory, select your architecture.

The current supported architectures are:

* darwin-x86: Mac OSX - Darwin x86 Intel
* darwin-ppc: Mac OSX - Darwin Power PC
* linux-x86: Linux-x86 - Linux 32-bit
* linux-x86_64: Linux-x86_64 - Linux 64-bit
* win32: Windows

The Snapshots directory contains both Slicer2 and Slicer3 binaries. For the latest build, select the filename that begins with "Slicer3" and has the most recent date. For the beta binary released prior to the January 2007 All Hands Meeting, choose the file with "PreAHM" in the filename. These are all beta builds, so you might find some bugs. If you do, or are having trouble installing Slicer3, please email slicer-users@bwh.harvard.edu so we can continue to improve Slicer3.

===Installing on Mac OSX===

The latest Mac OSX builds are either tar.gz files or .sh files. To install Slicer3, open up an X11 terminal window and copy the binary to the location where you want to install. Change the filename in the examples below to reflect the binary you downloaded.

=====Unpacking .tar.gz Files=====

To unzip and untar the .tar.gz binary, type:

gunzip ./Slicer3-3.0.2007-01-10-Darwin-x86.tar.gz
tar -xvf ./Slicer3-3.0.2007-01-10-Darwin-x86.tar

=====Unpacking .sh Files=====

To unpack the .sh binary, type:

./Slicer3-3.0.2007-01-10-Darwin-x86.sh

You will be prompted to accept the license agreement, and asked where you want to install it. Respond "Y" to both questions.

=====Running Slicer3=====

To run Slicer3, cd into the Slicer3-3.0.2007-xx-xx/ directory and type:

./Slicer3

===Installing on Linux===

After downloading the file, move it to where you would like to install Slicer3, and then execute the .sh binary. To do this, simply do the following (replace the filename with the one you downloaded):

./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

If the file doesn't execute, make sure that you have execute permission set. To add execute permission, type:

chmod a+x ./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

Some shells have problems executing the script. If so, you might need to specify which shell you want to execute the script, e.g.:

/bin/sh ./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

To run Slicer3, cd into the Slicer3-3.0.2007-xx-xx/bin directory and type:

./Slicer3

===Installing on Windows===

After downloading the file, simply double-click on it to start the installation process. To uninstall Slicer3, double-click the Uninstall icon in the Slicer3 directory. To run Slicer, go to Start -> Programs -> Slicer3-3.0.2007.xx-xx -> Slicer

==Build Slicer3 Yourself==

If you would like to build Slicer3 yourself from an SVN checkout, you can find detailed instructions [[Slicer3:Build_Instructions|here]].

Slicer3:Downloads

2007-07-27T15:12:33Z

Klawson1:

{| class="toccolours" style="margin-right: 25px" align="right"
! bgcolor="#ccccff" align="center" | Slicer3
|-
|
[[Slicer3|Home]]
|-
|
[[Slicer3:About|About]]
|-
|
[[Slicer3:FAQ|FAQ]]
|-
|
[[Slicer3:Status|Status]]
|-
| '''Downloads'''
|-
|
[[Slicer3:Documentation|Documentation]]
|-
|
[[Slicer3:Community_Support|Community Support]]
|-
|
[[Slicer3:Developers|Developers]]
|-
|
[[Slicer3:Acknowledgements|Acknowledgements]]
|-
|
[[Slicer3:Links|Links]]
|}

==About Slicer3==

Slicer 3 is a project under active development. See [[Slicer3:Status|the Status Page]] for more information on what the software does and the current status of product features. Release notes for Slicer 3 are available [[Slicer3:Slicer3_Alpha_Release_Notes|here]]

As Slicer3 is changing on a daily basis, some features may not be implemented or will be in various stages of completion. Slicer2.6 is the current fully supported release of Slicer. For information about the current release of Slicer2.6, see [[Slicer:Slicer2.6_Getting_Started|Slicer2.6 Getting Started]].

There are a couple different ways to obtain Slicer3 to run on your own computer. You can either download a precompiled Slicer3 installer for your platform, or build it yourself from an SVN checkout.

==Obtaining a Precompiled Binary==

Compiled '''Slicer3 executables''' are [http://www.na-mic.org/Slicer/Download/Snapshots/ '''available here''']. From the Snapshots directory, select your architecture.

The current supported architectures are:

* darwin-x86: Mac OSX - Darwin x86 Intel
* darwin-ppc: Mac OSX - Darwin Power PC
* linux-x86: Linux-x86 - Linux 32-bit
* linux-x86_64: Linux-x86_64 - Linux 64-bit
* win32: Windows

The Snapshots directory contains both Slicer2 and Slicer3 binaries. For the latest build, select the filename that begins with "Slicer3" and has the most recent date. For the beta binary released prior to the January 2007 All Hands Meeting, choose the file with "PreAHM" in the filename. These are all beta builds, so you might find some bugs. If you do, or are having trouble installing Slicer3, please email slicer-users@bwh.harvard.edu so we can continue to improve Slicer3.

===Installing on Mac OSX===

The latest Mac OSX builds are either tar.gz files or .sh files. To install Slicer3, open up an X11 terminal window and copy the binary to the location where you want to install. Change the filename in the examples below to reflect the binary you downloaded.

=====Unpacking .tar.gz Files=====

To unzip and untar the .tar.gz binary, type:

gunzip ./Slicer3-3.0.2007-01-10-Darwin-x86.tar.gz
tar -xvf ./Slicer3-3.0.2007-01-10-Darwin-x86.tar

=====Unpacking .sh Files=====

To unpack the .sh binary, type:

./Slicer3-3.0.2007-01-10-Darwin-x86.sh

You will be prompted to accept the license agreement, and asked where you want to install it. Respond "Y" to both questions.

=====Running Slicer3=====

To run Slicer3, cd into the Slicer3-3.0.2007-xx-xx/ directory and type:

./Slicer3

===Installing on Linux===

After downloading the file, move it to where you would like to install Slicer3, and then execute the .sh binary. To do this, simply do the following (replace the filename with the one you downloaded):

./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

If the file doesn't execute, make sure that you have execute permission set. To add execute permission, type:

chmod a+x ./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

Some shells have problems executing the script. If so, you might need to specify which shell you want to execute the script, e.g.:

/bin/sh ./Slicer3-3.0.2007-01-08-Linux-x86_64.sh

To run Slicer3, cd into the Slicer3-3.0.2007-xx-xx/bin directory and type:

./Slicer3

===Installing on Windows===

After downloading the file, simply double-click on it to start the installation process. To uninstall Slicer3, double-click the Uninstall icon in the Slicer3 directory. To run Slicer, go to Start -> Programs -> Slicer3-3.0.2007.xx-xx -> Slicer

==Build Slicer3 Yourself==

If you would like to build Slicer3 yourself from an SVN checkout, you can find detailed instructions [[Slicer3:Build_Instructions|here]].

Slicer3:Large scale experiment control brainstorming

2007-07-01T03:21:19Z

Klawson1:

'''Bold text'''== Goal ==

To provide Slicer3 with a mechanism for submitting, monitoring, and summarizing large scale experiments that utilize Slicer3 modules, particularly the Command Line Modules. This page summarizes our thoughts, requirements, and experiments to date, mostly accomplished during the [[Slicer3:MiniRetreat March 29, 30, 2007 | March 2007 Slicer3 MiniRetreat]].

There are two introductory use cases that we wish to support:

# Slicer3 is used interactively to select a set of parameters for an algorithm or workflow on a single dataset. Then, these parameters are applied to N datasets non-interactively.
# Slicer3 is used interactively to select a subset of parameters for an algorithm or workflow on a single dataset. Then, the remaining parameter space is searched non-interactively. Various parameter space evaluation techniques could be employed, the simplest of which is to sample the space of (param1, param2, param3).

Note, that with the above two use cases, we are only trying to address large scale experiment control from the standpoint of what it means to Slicer3. We are '''not''' trying to solve the general case of large scale experiment control.

== Assumptions and restrictions ==

# Computing configuration.
#: We shall support a variety of computing infrastructures which include
#:# single computer systems,
#:# clusters,
#:# grids (optional)
# Access to compute nodes.
#: We shall have no direct access to the compute nodes. All '''job submissions''' shall be to some sort of submit node. Exception may be when operating on a single computer system configuration.
# Staged data
#: The compute nodes shall mount a filesystem outside of the node on which data is staged. We are not providing Slicer3 with the mechanisms to stage data. We assume that all data is staged outside of Slicer3.
# Staged programs
#: The compute nodes shall have access to the Slicer3 processing modules. Like the case for data, the processing modules are staged outside of the Slicer3 environment.
# Experiment scheduling
#: A given experiment shall result in one or more processing jobs being submitted to the computing resources.
# Job submission
#: Submitting a job to the computing infrastructure shall result in a job submission token such that that job can be
#:# monitored for status: scheduled, running, completed
#:# terminated
# Experiment control
#: We shall be able to monitor an experiment to see its status.
#: We shall be able to interrupt an experiment. This may involve removing jobs from the queue and terminating jobs in process.
#: We shall be able to resume an experiment without re-running the entire experiment. Previously terminated jobs will be resubmitted. Previously completed jobs will not be rerun.
#: We shall be able to rerun an experiment, overwriting previous results.
# Job execution robustness
#: Jobs terminating unsuccessfully shall be automatically resubmitted to the computing environment upon the experiment designers request. Jobs may be resubmitted zero times, K times, or until successful.
# Platform
#: The cluster head node is expected to be a linux machine with standard packages installed.

== Components ==

To address the application scenario, we considered the following:

=== Completion of a Single Execution Step ===

Given that any job submission may fail (for example, if the cluster or a node goes down) we need to be able to distinguish the following cases when starting a job:

1. job has not been started
2. job has been started (i.e. we are reattaching to a running job)
2a job still running
2b job not running
3 job has completed successfully

We want to provide the following capabilities:
* the job can started (i.e. we have a back-end for different job control systems)
* we can check the status of jobs (we save the job token)
* we can restart a job that has died
* we don't start a job if it is alreay running
* we don't re-run a job that already has completed successfully
* we can clean up the state so the whole job can be re-run

=== Overall Experiment Control ===

We would like tools to provide the following controls:

* Be able to start and experiment
* Be able to check the status of an experiment that is running
* Be able to confirm that the experiment has completed
* Be able to restart an experiment in the middle if the cluster crashed or jobs failed.

== Thought experiments ==

Below are a few thought experiments to address the above. These will be used to see how the above needs can be addressed.

=== Makefiles + the Looping Launcher ===

We considered the running of the experiment as a dependency graph, and realized that the 'make' utitlity is a powerful system for expressing and resolving dependencies, and that it has parallel exeucution features with the -j flag. We'd like to be able to say 'make Experiment' and have the results generated. Make is good at re-running only what is needed.

We looked at three issues:
# Makefiles are not friendly to write (particularly with large numbers of dependencies), so some helper utilities would be needed. we anticipate 100s or 1000s of file dependencies in an experiment, but this is doable by make.
# We needed a 'looping launcher' (a.k.a. loopy) that would submit a job and monitor it for successful completion. If the job fails, the launcher resubmits the job for a pre-set number of times.
# Make works on the dependencies at the file level, whereas some steps in an experiment may write several files or write to a database. So a wrapper utility is needed to monitor the job status and create a file that make can use to determine dependencies. The loopy command includes this functionality.

==== Example Makefile Using the Looping Launcher ====

The following example illustrates the concept on a simple example of 2 input data sets, each of which needs to be segmented before a summary statistics program can be run. We simulated the cluster submit with a program called 'randomFail' which accepts a 'probability of failure' argument so we can test the approach's ability to recover from individual job failures. This makefile would be run on the head node of a cluster.

In this case, the program <loopy> accepts two important parameters
--retries tells loopy how many times to try running the job before considering it a failure
-d is the "done file" which tells loopy that it's target command has completed successfully

Internally the loopy code [http://www.na-mic.org/ViewVC/index.cgi/trunk/Utilities/ETC/loopy?view=log (in slicer3 snv here)] starts the job and monitors it for completion. Loopy saves the job id associated with a given job in a file name of the "done file" with the addition of a .started suffix. This allows subsequent invokations of loopy to determine what state the job is in. The .started file is deleted when the job completes successfully.

<pre>
LOOPY=../../loopy --retries 10
SEGMENTER=./randomFail --p-fail 0.0 --delay 2000
STATISTICS=./randomFail --p-fail 0.0 --delay 2000

all: data/summary-statistics.out
@echo job complete

data/summary-statistics.out: data/ex1.out data/ex2.out
@echo making summary
$(LOOPY) -d data/summary-statistics.out "$(STATISTICS) -o data/summary-statistics.out"

data/ex1.out:
@echo making ex1
$(LOOPY) -d data/ex1.out "$(SEGMENTER) -o data/ex1.out"
data/ex2.out:
@echo making ex2
$(LOOPY) -d data/ex2.out "$(SEGMENTER) -o data/ex2.out"

clean:
rm -f data/ex1.out data/ex2.out data/summary-statistics.out
</pre>

==== Utility to help Generate Experiment Makefiles ====

A set of experiment control helper code [http://www.na-mic.org/ViewVC/index.cgi/trunk/Utilities/ETC/Examples/RandomFail/Experiment.tcl?revision=3093&view=markup (in slicer3 snv here)] was prototyped. This code, called ETC for now, allows you to make simple high level looping constructs to build up the dependencies needed for a complex experiment.

In the following example, 50 experimental subjects are generated where each one must complete successfully before the summary statistics can be executed. The ETC code generates a Makefile.ETC which uses the loopy code internally to implement a robust and restartable experiment.

<pre>
source ../../ETC.tcl

::ETC::SetProject ExampleSegmentation

::ETC::SetWorkingDirectory .
for {set i 0} {$i < 50} {incr i} {
lappend SubjectList ex$i
}

foreach Subject $SubjectList {
::ETC::Schedule -name EM$Subject "./randomFail -d 1000 -p 0.6 -o data/$Subject"
}

::ETC::Schedule -name Summary -depends EM* ""
::ETC::RootTask Summary

::ETC::Generate Makefile.ETC
</pre>

=== BatchMake ===

BatchMake allows for large scale experiments to be designed using a scripting language similar to CMake scripts. BatchMake provides a number of looping constructs which can be used to design experiments and parameter searches
* foreach
* sequence
* randomize
* fornfold
Here is a BatchMake script to search the parameter space of a median filter
<pre>
SetApp(median @'Median Filter')
SetAppOption(median.inputVolume 'c:/projects/I2/Insight/Testing/Data/Input/cthead1.png')

Set(kernels '1,1,1' '2,2,1' '3,3,1' '4,4,1' '5,5,1')
Set(outVolumePrefix 'c:/projects/Temp/Slicer3/median')

foreach(kernel ${kernels})
RegEx(kernelText ${kernel} ',' REPLACE '_')
SetAppOption(median.outputVolume ${outVolumePrefix}${kernelText}.png)
SetAppOption(median.neighborhood ${kernel})

Run(output ${median})

endforeach(kernel)
</pre>
We have extended the [[Slicer3:Execution Model Documentation | ModuleDescription library]] in Slicer3 to generate a BatchMake XML Application Wrapper from a ModuleDescription object. This allows Slicer3 Command Line Modules to be loaded into BatchMake and used as BatchMake application objects in BatchMake scripts. This code has yet to be integrated into Slicer3 permanently because there a number of design decisions outstanding. Here is the ModuleDescription XML file that Slicer uses
<pre>
<?xml version="1.0" encoding="utf-8"?>
<executable>
<category>
Filtering.Denoising
</category>
<title>
Median Filter
</title>
<description>
The MedianImageFilter is commonly used as a robust approach for
noise reduction. This filter is particularly efficient against
"salt-and-pepper" noise. In other words, it is robust to the presence
of gray-level outliers. MedianImageFilter computes the value of each output
pixel as the statistical median of the neighborhood of values around the
corresponding input pixel.
</description>
<version>0.1.0.$Revision: 2085 $(alpha)</version>
<documentation-url></documentation-url>
<license></license>
<contributor>Bill Lorensen</contributor>
<acknowledgements>This command module was derived from Insight/Examples/Filtering/MedianImageFilter (copyright) Insight Software Consortium</acknowledgements>
<parameters>
<label>Median Filter Parameters</label>
<description>Parameters for the median filter</description>
<integer-vector>
<name>neighborhood</name>
<longflag>--neighborhood</longflag>
<description>The size of the neighborhood in each dimension</description>
<label>Neighborhood Size</label>
<default>1,1,1</default>
</integer-vector>
</parameters>
<parameters>
<label>IO</label>
<description>Input/output parameters</description>
<image>
<name>inputVolume</name>
<label>Input Volume</label>
<channel>input</channel>
<index>0</index>
<description>Input volume to be filtered</description>
</image>
<image>
<name>outputVolume</name>
<label>Output Volume</label>
<channel>output</channel>
<index>1</index>
<description>Output filtered</description>
</image>
</parameters>
</executable>
</pre>
and here is the resulting BatchMake XML Application wrapper
<pre>
<?xml version="1.0" encoding="utf-8"?>
<BatchMakeApplicationWrapper>
<BatchMakeApplicationWrapperVersion>1.0</BatchMakeApplicationWrapper>
<Module>
<Name>Median Filter</Name>
<Version>0.1.0.$Revision: 2085 $(alpha)</Version>
<Path>c:/projects/Slicer3-clean-net2005/bin/RelWithDebInfo/../../lib/Slicer3/Plugins/RelWithDebInfo/MedianImageFilter.exe</Path>
<Parameters>
<Param>
<Type>1</Type>
<Name>neighborhood.flag</Name>
<Value>--neighborhood</Value>
<Parent>0</Parent>
<External>0</External>
<Optional>1</Optional>
</Param>
<Param>
<Type>4</Type>
<Name>neighborhood</Name>
<Value>1,1,1</Value>
<Parent>1</Parent>
<External>0</External>
<Optional>0</Optional>
</Param>
<Param>
<Type>0</Type>
<Name>inputVolume</Name>
<Value></Value>
<Parent>0</Parent>
<External>1</External>
<Optional>0</Optional>
</Param>
<Param>
<Type>0</Type>
<Name>outputVolume</Name>
<Value></Value>
<Parent>0</Parent>
<External>2</External>
<Optional>0</Optional>
</Param>
</Parameters>
</Module>
</BatchMakeApplicationWrapper>
</pre>

==== BatchMake and the Computing Infrastructure ====

* What is needed to make BatchMake submit to a cluster?
* To a grid?

==== BatchMake and Job Control ====

# Can BatchMake terminate a job?
# Can BatchMake resubmit a job until it completes successfully?

==== BatchMake and Experiment Control ====

Can BatchMake interrupt, continue, and rerun an experiment?

Slicer3:Data Model

2007-06-17T21:47:21Z

Klawson1:

= Slicer3 MRML Overview =

*MRML Library provides API for managing medical image data types (Volumes, Models, Transforms, Fiducials, Cameras, etc) and their visualization.
*Each data type is represented by a special MRML node.
*MRML Scene is a collection of MRML nodes.
*Slicer MRML data model is implemented independent of the visualization and algorithmic components of the system.
*Other Slicer components (Logic and GUI) observe changes in MRML scene and individual nodes and process change MRML events.

For more details on MRML architecture see [http://www.na-mic.org/Wiki/images/e/e3/Slicer_3-alpha-2006-04-03.ppt Architecture Slides].

= MRML Scene =

*MRML Scene manages MRML nodes : add, delete, find, find by type, etc.
*MRML Scene provides persistence of MRML nodes (reading/writing to/from XML file).
*MRML Scene provides Undo/Redo mechanism that restores a previous state of the scene and individual nodes.

= MRML Nodes =

*The MRML nodes are designed to store the state of the Slicer application, both raw data and visualization parameters.

There following is a set of core MRLN nodes that store the state of core Slicer modules:

* vtkMRMLCameraNode
* vtkMRMLClipModelsNode
* vtkMRMLSliceCompositeNode
* vtkMRMLSliceNode
* vtkMRMLColorNode
* vtkMRMLTransformNode
* vtkMRMLLinearTransformNode
* vtkMRMLTransformableNode
* vtkMRMLFiducialListNode
* vtkMRMLModelNode
* vtkMRMLModelDisplayNode
* vtkMRMLStorageNode
* vtkMRMLModelStorageNode
* vtkMRMLVolumeNode
* vtkMRMLScalarVolumeNode
* vtkMRMLVectorVolumeNode
* vtkMRMLTensorVolumeNode
* vtkMRMLDiffusionTensorVolumeNode
* vtkMRMLDiffusionWeightedVolumeNode
* vtkMRMLVolumeDisplayNode
* vtkMRMLVectorVolumeDisplayNode
* vtkMRMLDiffusionTensorVolumeDisplayNode
* vtkMRMLDiffusionWeightedVolumeDisplayNode
* vtkMRMLVolumeHeaderlessStorageNode
* vtkMRMLVolumeArchetypeStorageNode

<br />
*MRML nodes are organized into C++ class hierarchies, all derived from vtkMRMLNode class.
*For example vtkMRMLTransformableNode is the parent class of Volume, Model, Fiducial, and Transformation nodes; vtkVolumeNode is a parent of vtkMRMLScalarVolumeNode and vtkMRMLVectorVolumeNode
*All MRML nodes have to implement certain standard API: ReadAttributes, WriteAttributes, Copy, etc.
{|
|[[Image: Slicer3_MRML_Node_Hier.jpg|thumb|400px]]
|}

= References to MRML Nodes =

*Some MRML nodes have references to other nodes.
*Transformable Node has a reference to a Transformation node. Transformation node has a reference to its parent Transformation node.
*References are stored by node ID.
*Use vtkSetReferenceStringMacro to set reference ID (it registers reference with the scene).
*Access methods should check if the referenced node is still in the MRML scene using its ID.
{|
|[[Image: Slicer3_MRML_Trans_Ref.jpg|thumb|400px]]
|}

= MRML Events and Observers =

*Changes in MRML scene and individual nodes propagate to other observing nodes, GUI and Logic objects via vtk events and command-observer mechanism.
*Use vtk AddObserver() and InvokeEvent() methods. vtk SetMacro generates ModifiedEvent.
*The command-observer mechanism for MRML is implemented using helper vtkObserverManager, class, MRML Observer macros, and ProcessMRMLEvents method.
*Observers should store a registered pointer to a MRML node to prevent callbacks on a deleted object.
{|
|[[Image: Slicer3_MRML_Observ.jpg|thumb|400px]]
|}

*MRML observer macros are defined in Libs/MRML/vtkMRMLNode.h
*VtkSetMRMLObjectMacro - registers MRML node with another vtk object (another MRML node, Logic or GUI). No observers added.
*VtkSetAndObserveMRMLObjectMacro - registers MRML node and adds an observer for vtkCommand::ModifyEvent.
*VtkSetAndObserveMRMLObjectEventsMacro - registers MRML node and adds an observer for a specified set of events.
*SetAndObserveMRMLScene[Events]() method is used in GUI and Logic to observe Modify, NewScene, NodeAdded, etc. events.
*ProcessMRMLEvents method should be implemented in MRML nodes, Logic, and GUI classes in order to process events from the observed nodes.

= Creating Custom MRML Node Classes=

*Custom MRML nodes provide persistent storage for the module parameters.
*Custom MRML nodes should be registered with the MRML scene using RegisterNodeClass() so they can be saved and restored from a scene file.
*Classes should implement the following methods:
*CreateNodeInstance() – similar to VTK New() method only not static.
*GetNodeTagName() – return a unique XML tag for this node.
*ReadXMLAttributes() – reads node attributes from XML file as name-value pairs.
*WriteXML() – writes node attributes to output stream (as in interpolate="1" ).
*Copy() – copies node attributes.

*If the node has references to other nodes the following additional methods should be implemented:
–UpdateReferenceID() - updates the stored reference to another node.
–UpdateScene()- updates other nodes in the scene depending on this node or updates this node if it depends on other nodes when the scene is read in.
This method is called automatically by XML parser after all nodes are created.
*An example of a custom MRML node implementation: vtkMRMLGradientAnisotropicDiffusionFilterNode in Modules/GradientAnisotropicDiffusionFilter directory.
*To add node to the MRML scene:
–In the code: use standard vtk New() and add node to the scene using vtkMRMLScene::AddNode(vtkMRMLNode *)
–By user request: use vtkSlicerNodeSelectorWidget that creates a new node from the module’s UI.

= Undo/Redo Mechanism =

*Undo/Redo is based on saving and restoring the state of MRML nodes in the Scene.
*MRML scene can save snapshot of all nodes into a special Undo and Redo stacks.
*The Undo and Redo stacks store copies of nodes that have changed from the previous snapshot. The node that have not changes are stored by a reference (pointer).
*When an Undo is called on the scene, the current state of Undo stack is copied into the current scene and also into Redo stack.
* All Undoable operations must store their data as MRML nodes

{|
|[[Image: Slicer3_MRML_Undo.jpg|thumb|400px]]
|}

*Developer controls at what point the snapshot is saved by calling SaveStateForUndo method on the MRML scene.
–SaveStateForUndo() - saves the state of all nodes in the scene
<br />–SetActiveScene(vtkMRMLScene *) - saves the state of the specified node.
<br />–SetActiveScene(vtkCollection*) - saves the state of the specified collection of nodes.
*SaveStateForUndo() should be called in GUI/Logic classes before changing the state of MRML nodes. Usually done in the ProcessGUIEvents method that processes events from the user interactions with GUI widgets.
*SaveStateForUndo() should not be called while processing transient events such as continuous events sent by KW UI while dragging a slider (for example vtkKWScale::ScaleValueStartChangingEvent).

The following methods on the MRML scene are used to manage Undo/Redo stacks:

* vtkMRMLScene::Undo() – restore the previously saved state of the MRML scene.
* vtkMRMLScene::Redo() – restore the previously undone state of the MREML scene.
* vtkMRMLScene::SetUndoOff() – ignore following SaveStateForUndo calls (usefull when making multiple changes to the scene/nodes that does not need to be undone).
* vtkMRMLScene::SetUndoOn() – enable following SaveStateForUndo calls.
* vtkMRMLScene::ClearUndoStack() – clears the undo history.
* vtkMRMLScene::ClearRedoStack() – clears the redo history.

Slicer Module developers should call vtkMRMLScne::SaveStateForUndo() method in their modules before changing the state of MRML nodes. This is usually done in the ProcessGUIEvents method that processes events from the user interactions with GUI widgets. Note, that vtkMRMLScne::SaveStateForUndo() method should not be called while processing transient events such as continuos events sent by UI while dragging a slider (for example vtkKWScale::ScaleValueStartChangingEvent).

= Other Useful References =

== MRML API Documentation ==

The detailed documentation of MRML API can be found in [http://www.na-mic.org/Slicer/Documentation/Slicer3/html/classes.html <nowiki> Slicer3 Doxygen pages</nowiki>]

== History ==

See Data Model notes in [[AHM_2006:ProjectsSlicerDataModel|AHM 2006 Programming week project]].

== Path-based MRML proposal ==

Mike's proposal for a [[Slicer3:MRML3_Path|path-based MRML3 representation]], based on extending the Coordinate Space Manager ideas to the entire MRML3 tree

== Slicer Daemon ==

The goal of the [[Slicer3:Slicer_Daemon|Slicer Daemon]] project is to allow remote editing of the MRML data model by external programs over a socket.

= Slicer 2.6 MRML =

== Data Represented in MRML in Slicer 2.6 ==

* Volumes
** IJK->RAS (VTK->RAS)
** Scalar Types
** Multicomponent (RGB, Displacement Vector)
** Tensor Volumes
** Label Maps
** Reference to Lookup Table

* Models
** vtkPolyData
*** Named Field Data (scalars, vectors, labels) at points and cells (FreeSurferReaders)
*** Polylines with tensor point data (DTMRI Module)
** Color, Clipping State, Visibility, Scalar Visibility, LookupTable

* Transforms
** Matrix4x4

* Lookup Tables
** vtkLookupTable info

* Fiducials
** Position, Quaternion
** Name, Selection State, Type (endoscopic, normal)
** Glyph Size, Text Size

* Fiducial Lists
** Name, Slze, Color, Selection State

* Colors
** Name, Label#, Diffuse/Ambient/Specular

* Model Groups

* Application State (not to be carried to Slicer3 MRML)
* Locator (not to be carried to Slicer3 MRML)
* Module Specific Parameters (not to be carried to Slicer3 MRML)

<br />

== Operations On MRML Scene ==

* Load from File
* Save to File
* Traverse Nodes in Tree
* Insert Node
* Delete Node
* Register Tree Observer
* Update MRML
* Get Transformations (e.g. IJK to World through transform tree)

* Data Type Specific Operations
** Get/Set Node MetaData
** Get/Set Data (e.g. as vtkImageData)

== General References on XML ==

A wikibook on XML: http://en.wikibooks.org/wiki/XML:_Managing_Data_Exchange

The section on ID/IDREF implementations which are similar to what we use in MRML: http://en.wikibooks.org/wiki/XML:_Managing_Data_Exchange/The_many-to-many_relationship#ID.2FIDRE

Event Bindings

2007-06-15T17:58:28Z

Klawson1:

= Keyboard accelerators =

A list of global "hot-keys" and module-specific "hot-keys" for Slicer2 and Slicer3 is being actively compiled below. (This page is a little out of sync with development -- please make current!) With respect to the specification of keyboard accelerators, please follow these three recommendations;

* Before assigning "hot-keys" to functionality, either in the main Slicer application or in a new module, please consult the list below to make sure the key is not already mapped.
* Across Slicer modules, try to use similar "hot-key" assignments for similar functionality, and try to observe existing paradigms outlined below; this consistency makes Slicer easier for users to learn.
* Once you assign "hot-keys" in your module, please add those mappings to the list below for others to reference.

== Design paradigms ==

* use CTRL-modified keys as global, and non-modified keys for module-specific accelerators.
* use ALT modifiers to access menu items
* SHIFT modifiers should apply to all instances of the same type as the current window

== Design ideas ==

* using CTRL-1, CTRL-2 CTRL-3 to navigate to most commonly used modules in the base (for instance, Data, Volumes, Editor?).
* having hotkeys to toggle between axial, saggital, and coronal views in a slice window.
* having a hotkey to toggle any window the mouse is inside between full screen and current size.
* consistent set of mouse actions in 2D, 3D and control windows
* consistent set of mouse-mode switches in 2D, 3D windows
* use the right menu button to bring up a context-dependent menu (e.g. actions appropriate for the item under the cursor).

== Global "hot-keys" ==

=== Window Behavior ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|-
| Toggle Maximize current window
| Control-m
| Make the current Slice or 3D View expand to full view space or return to previous size depending on current state
| None
|-
| Toggle Control Pane View
| F5 (KWW default)
| Show or hide the Control Pane depending on state
| None
|}
<br />

=== MRML ===
{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key

|-
| Open Scene...
| Control-O
| Bring up file browser to locate .mrml file
| None
|-
| Save Scene
| Control-S
| Save current scene no browser, disabled if no current file. If no current scene, does Save As...
| None
|-
| Save Scene As...
| None
| Bring up file browser to locate .mrml file
| None
|-
| Undo
| Control-Z
| Revert to last undo point
| None
|-
| Redo
| Control-Y
| Revert to last redo point
| None
|-
| Other Menu Items
| Alt-<letter>
| Bring up or invoke menu or menu item corresponding to letter
| Same
|}

=== Slice Manipulation ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|-
| Next slice
| Right Arrow and Up Arrow
| Axial: move Superior, Sag: Right, Cor: Anterior
| Right Arrow
|-
| Previous slice
| Left Arrow and Down Arrow
| Axial: move Inferior, Sag: Left, Cor: Posterior
| Left Arrow
|-
| Linked Motion
| Shift Key
| Cause other slice windows to scroll to RAS point at current cursor location
| Same
|-
| Toggle Slice Visible
| v
| Make the current slice window show as a plane in the 3D view
| None
|-
| Toggle All Slices Visible
| V
| Make all slices show in 3D View
| None
|-
| Toggle Foreground/Background Opacity
| T
| Change opacity of foreground overlay
| None
|-
| Toggle Label Overlay
| g
| Show/Hide Label for this slice
| None
|-
| Toggle Label Overlay
| G
| Show/Hide Label for all slices
| None
|-
| Cycle Orientations
| Tab
| Cycle through Axial/Sagittal/Coronal
| None
|-
| Cycle All Orientations
| Shift-Tab
| Cycle through Axial/Sagittal/Coronal in all slice windows
| None
|-
| Fit to volume
| f
| Set the field of view to match the full extent of the foreground and background volumes
| None
|-
| Fit to volumes all
| Shift-F
| Set the field of view in all slices to match the full extent of the foreground and background volumes
| None
|}

=== 3D Manipulation ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|-
| Wireframe
| w
| change render mode to wireframe
| Same
|-
| Shaded
| s
| change render mode to shaded
| Same
|-
| Reset View
| r
| Set camera to see all objects
| None
|-
| Toggle Rock Mode
| TBD
| Toggle rock mode
| None
|-
| Toggle Spin Mode
| TBD
| Toggle spin mode
| None
|}

=== Navigating Application ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|-
| Application Menu
| Space Bar
| Brings up a popup menu with all the application operations and their key binding information
| None
|-
| Module Navigation
| Control-<number>
| Jumps to the numbered module (number order is the same as the order of the shortcut icons in the toolbar at the top of the application.
| None
|-
| Move through module history
| Control-PageUp/PageDown
| Short cuts for the two arrow buttons next to the module popup menu
| None
|-
| Search for Module
| Control-F
| Starts an incremental search through the module names and descriptions, terminated by Enter to jump to the module. Probably needs a dialog box.
| None
|}

== Module-specific hot-keys ==

=== Fiducials ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|-
| Add Fiducial
| Control-p
| Adds fiducial at current pointer position
| Same
|-
| Delete Fiducial
| Control-d
| Deletes the fiducial picked from current mouse position (ignored if no fiducial is under mouse)
| Same
|-
| Select Fiducial
| Control-q
| Selects/Deselects the fiducial under the mouse
| q
|}

=== Editor ===

{| border="1" cellpadding="5"
|- style="background:#c2c2c2; color:black" align="eft"
| style="width:20%" | Action
| style="width:15%" | Slicer3 Key
| style="width:40%" | Meaning
| style="width:10%" | Slicer3 Key
|}

= Mouse Actions =

== Button Use Constraints ==

* Alt-Left mouse button should always be available as a substitute for the middle mouse button to support two button mice. On Mac, you can also use the command key with a mouse click to get middle mouse events.
* Contrl-Left mouse button should always be available as a substitute for the right mouse button to support one button mice (on Mac).

== Toolbar ==

The current mouse mode will always be visible in a toolbar in the slicer display. There will also be hot keys to select specify mouse modes. Instead of (or in addition to) a toolbar we may want to use a WWidget in the overlay planes to reflect the mouse mode.

Slicer3:Interface Design and Usability

2007-06-14T21:59:28Z

Klawson1: /* Event Bindings */

'''[[Slicer3|<< Back to Slicer3 main page]]'''

[[Slicer3:Developers |Go to Slicer3 Developer Info >> ]]

<br />

= Project goals =

Design and engineer Slicer3 UI. Employ a user-centered approach and establish usability guidelines.

= Project reporting =

The scope of this effort is sorted into four categories: Engineering, UI design, Usability and Slicer3 branding. The subtasks of each category are itemized below and specific information about each category is located on the linked pages.

=== [[Slicer3:UIEngineering|UI Architecture & Engineering]] ===

Tasks: (more detailed UI Architecture & Engineering information can be found [[Slicer3:UIEngineering|here]]).

* design thin GUI layer, separate from the control logic and data model;
* design a model for representing the UI and managing local events;
* extend the model for handling remote events;
* design means of mapping KWWidgets onto that model;
* set priorities with Kitware involving extensions & modifications to KWWidgets;
* determine the api to application logic, used by GUI and by scripts;
* design set of base classes that give module developers an easy pattern to follow;
* develop guidelines for slicer base developers and module developers;
* design mechanism for centrally specifying look & feel (and permitting overrides);

=== [[Slicer3:UIDesign|UI Design & Prototypes]] ===

Tasks: (more detailed UI Design & Prototype information can be found [[Slicer3:UIDesign|here ]]).

* design overall look to Slicer3 application in keeping with core values;
* design look & feel applied to developer modules;
* design KWWidgets class to specify custom widgets for Slicer main app & modules;
* implement Slicer3 Application GUI
* design conventions for specifying global and module-specific keyboard accelerators;
* specify and document global keyboard accelerators;
* iterate on prototype(s) and present them for comments and suggestions;

=== [[Slicer3:Usability|Usability]] ===

Tasks: (more detailed Usability information can be found [[Slicer3:Usability|here ]]).

* develop and publish a user-centered design practice that support usability and software consistency.
* use this process to design and implement main application interface, and some core functionality.

=== [[Slicer3:Slicer3Brand|3DSlicer Brand]] ===

Tasks: (Slicer3 brand sketches can be found[[Slicer3:Slicer3Brand| here ]]).

* fully express new 3DSlicer brand: design logo, splash screen, style sheets for web presence;

= First steps: How to build a Slicer3 Module GUI =

== Virtual Methods ==

At the slicer-developers tcon 2007-02-13, we discussed some adjustments to the virtual methods in vtkSlicerModuleGUI for better consistency and utility. The following list defines the methods that a module needs to implement so the main application (Slicer3.cxx) can operate on all modules generically:

<div style="width: 40%; float: left; padding-right: 3%;">
The following methods are defined by the vtkSlicerModuleGUI and typically won't be overriden:

* '''Enter'''
** ''called when module is raised''
** ''calls CreateGUI if needed (instance variable tracks create state)''
** ''calls AddGUIObservers''
** ''calls UpdateGUI''
* '''Exit'''
** ''called when module is replaced by another''
** ''calls RemoveMRMLObservers''
</div>

<div style="width: 40%; float: left; padding-right: 3%;">

The following methods should be defined by the Module to implement the specific behavior:

* '''CreateGUI'''
** ''instances and packs widgets''
* '''DestroyGUI'''
** ''typically called only by destructor''
** ''breaks any reference cycles''
** ''Deletes widgets''
* '''ProcessGUIEvents'''
** ''responds to events from widgets or slicer GUI classes''
** ''propagates data from GUI into MRML nodes''
* '''ProcessMRMLEvents'''
** ''responds to updates to MRML nodes''
** ''propagates data from MRML to widgets''
* '''AddGUIObservers'''
** ''set observers on widgets and GUI classes (use GUICallbackCommand local instance -- it will call ProcessGUIEvents)''
* '''AddMRMLObservers'''
** ''set observers on MRML nodes and scene (use MRMLCallbackCommand local instance -- it will call ProcessMRMLEvents)''
* '''RemoveGUIObservers'''
* '''RemoveMRMLObservers'''
* '''UpdateGUI'''
** ''copy state from MRML nodes to GUI/Widgets''
** ''if needed for efficiency, check the MTime for the MRML Node and the corresponding GUI and only update if needed (e.g. for a MultiColumnList or other widget the holds a lot of data)''
* '''UpdateMRML'''
** ''copy state from GUI/Widgets to MRML''
</div>

<br style="clear: both;" />

== Usage ==

'''NOTE: this description will change due to current ongoing changes to the module GUI base classes.'''
The figure below shows a current overview of the three classes a new module (called MyModule for example) will need to define (vtkSlicerMyModuleGUI, vtkSlicerMyModuleLogic and vtkMRMLMyModuleNode) and some of the methods those classes should include to utilize the Slicer3 infrastructure. These classes should reside in the slicer3/Modules/MyModule/ directory.

[[Image:Slicer3MyModule.png|[[Image:Slicer3MyModule.png| Base classes for GUI, Logic and MRML ]]]]

'''Deriving your GUI class:''' To create a Module GUI that expresses its interface in Slicer's shared UIpanel, derive your class (vtkSlicerMyModuleGUI) from vtkSlicerModuleGUI. For a Module GUI that expresses its interface in a different panel of the Main Slicer Window, or in a toplevel widget, derive vtkSlicerMyModuleGUI from vtkSlicerComponentGUI instead. Your GUI class will inherit application logic and MRML pointers, an API for setting and observing them, and a framework for defining MRML, Logic and GUI callbacks from its parent class. Specific mediator methods, other logic and MRML node pointers can be added to the module's class definition. Importantly, keep logic and MRML classes independent of the GUI to facilitate testing and command-line execution possible *without* instantiating the Slicer3 GUI.

'''Example:''' An early example to work from is the GradientAnisotropicDiffusionFilter Module; define all the widgets you need within the class and create Get Macros for each of them. Define the methods you need from vtkSlicerModuleGUI and its parent class vtkSlicerComponentGUI, including BuildGUI(); in this method, you'll first add a page to the class's UIPanel (for now, only create one page).

=== Two GUI styles ===
'''Two styles:''' Depending on whether you want a notebook-style GUI for your module (similar to the style used in Slicer2) or a set of stacked collapsible frames to contain different logical sections of your interface like "help" and "display", your BuildGUI() method can be written in one of two ways. The '''notebook style''' may be appropriate for modules with long logical sections within their GUI, to minimize the amount of scrolling required of a user. The '''collapsing style''' may be appropriate for modules that have numerous logical sections, since the amount of horizontal space across which a notebook would array them is limited. The way these two styles are expressed in Slicer3's GUI panel is shown below.

[[Image:S3ModuleStyles.png]]

'''''Collapsing style:''''' The GradientAnisotropicDiffusionFilter Module example implements the collapsible style, first adding a single new Page in its UIPanel:

this->UIPanel->AddPage ( "MyModule", "MyModule", NULL );

then creating a vtkSlicerModuleCollapsibleFrame widget for each logical section in the GUI, parenting each to the UIPanel's single PageWidget, then creating, configuring and packing them from top to bottom in the UIPanel's PageWidget. Each logical section's widgets can be organized inside each of the vtkSlicerModuleCollapsibleFrames. The superclass has some helper methods to construct consisten Help&About Frames across modules.

//--- help and about frame
const char *help = "MyModule does the following...";
const char *about = "This work was supported by...";
vtkKWWidget *page = this->UIPanel->GetPageWidget ("MyModule");
this->BuildHelpAndAboutFrame ( page, help, about );

//--- rest of the frames
vtkSlicerModuleCollapsibleFrame *firstFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *secondFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *thirdFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *forthFrame = vtkSlicerModuleCollapsibleFrame::New ( );
...
//--- parenting the frames to the same UIpanel page
firstFrame->SetParent ( page );
secondFrame->SetParent ( page );
...
//--- parenting widgets to the various frames
this->widget2->SetParent ( firstFrame->GetFrame () );
this->widget3->SetParent ( secondFrame->GetFrame () );

'''''Notebook style:''''' To create a notebook style GUI (as there is no example yet, a little code will be included here), a new Page must be added to the UIPanel for every tab in the notebook:

//--- get a pointer to the KWUserInterfaceManagerNotebook
vtkKWUserInterfaceManagerNotebook *nbm = vtkKWUserInterfaceManagerNotebook::SafeDownCast ( this->UIPanel->GetUserInterfaceManager());
//--- help and about frame
this->UIPanel->AddPage ( "Help&About", "Information about using this module", NULL );
const char *help = "MyModule does the following...";
const char *about = "This work was supported by...";
vtkKWWidget *page = this->UIPanel->GetPageWidget ("Help");
this->BuildHelpAndAboutFrame ( page, help, about );

//--- pages for other frames
int page1ID = this->UIPanel->AddPage ( "First", "Functionality for some logical piece of module", NULL );
int page2ID = this->UIPanel->AddPage ( "Second", "Functionality for another logical piece of module", NULL );

//--- enabling or disabling notebook tabs
nbm->GetNotebook()->SetPageEnabled ( page1ID, 1 );
nbm->GetNotebook()->SetPageEnabled ( page2ID, 0 );

Widgets to be packed within each notebook page are parented to the PageWidget:

this->widget2->SetParent ( this->UIPanel->GetPageWidget ( "First" ) );
this->widget3->SetParent ( this->UIPanel->GetPageWidget ( "Second" ) );

or can be parented to a widget already parented to the PageWidget. Then they themselves can be created, configured, and packed in the same manner as they are in the GradientAnisotropicDiffusionFilter Module.

=== Defining methods ===
'''Methods to define:''' Define the methods you require from vtkSlicerComponentGUI base class, like: AddGUIObservers(), RemoveGUIObservers(), ProcessLogicEvents(), ProcessGUIEevents(), ProcessMRMLEvents(), Enter() and Exit(); and whatever else your module needs. (Eventually, available modules will be automatically detected, but this is not yet implemented; then, the Enter() method will probably be made to call the BuildGUI() method. For now, instantiate your class in Slicer3.cxx and call its BuildGUI() and other methods, following the pattern for other modules established there.)

=== Adding and removing observers ===
'''Adding observers:''' In AddGUIObservers, add an observer on each widget whose events you want to process. When an event is observed, the ProcessGUIEvents() method is called via the GUICallbackCommand; define this class to propagate information from the GUI to logic and MRML. Though it is tempting, try not to use ProcessGUIEvents() to update the GUI state directly -- just modify the Logic state, and allow observers on the logic and subsequent processing in ProcessLogicEvents() and ProcessMRMLEvents() to bring that state change BACK into the GUI.

'''Removing observers:''' In RemoveGUIObservers, make sure you remove every observer you've added to widgets in the GUI before calling Delete() on your widget. Make sure you call SetAndObserveMRML() and SetAndObserveLogic( ) with NULL pointers in your GUI class destructor to remove all observers on MRML and Logic that you have created.

=== Adding and removing references ===
For convenience, you may want to define pointers to Slicer's MainViewer, or to the SliceViewers, etc. Before Delete() can be called on anything you are referencing, you'll need to release the references. (Failure to release references can result in vtkDebugLeak reports on Application exit). The virtual method TearDownGUI() (inherited from vtkSlicerComponentGUI) can be defined for this purpose. References may be released in this method, and you can also use this method to call RemoveGUIObservers() if you don't want to explicitly call that method.

=== Defining new widgets ===
'''Defining your own widgets:''' The framework for doing this is still evolving. Currently there are two types of new widgets, those defined as extensions to vtkKW (like vtkKWWindowLevelThresholdEditor.h/cxx) and those defined as Slicer-specific widgets, (like vtkSlicerSliceControlWidget.h/cxx, derived from the vtkSlicerWidget.h/cxx base class). The Slicer widgets have methods for putting observers on their widget components, Logic and MRML, and processing events as well. Thus GUI classes that instance them do not have to manage events for them if the widgets' methods are used instead.

=== Using Undo and Redo ===
'''Undo:''' Make sure you process those events that mark junctures at which MRML state should be saved for Undo/Redo (using MRML's SaveStateForUndo() method. For instance, when an entry widget's value has changed, before changing a parameter in the appropriate MRML node, make a call to the MRMLScene's SaveStateForUndo() method with that node as a parameter. Save MRML state at reasonable junctures: for instance, for scale widgets, save MRML state when the scale starts changing, rather than continuously as the scale changes. For an example of they way SaveStateForUndo() is called, see slicer3/Base/GUI/vtkSlicerSliceControllerWidget.cxx. A detailed description of how undo/redo works, and how to use it in your module is available [[Slicer3:Data_Model#Undo.2FRedo_Mechanism | here]].

=== Adding the module to the rest of Slicer3 ===
'''Other files you will have to touch:''' For now, to add your module to Slicer3, create a new instance of vtkSlicerMyModuleLogic and vtkSlicerMyModuleGUI in Applications/GUI/Slicer3.cxx, and follow the pattern used by the GradientAnisotropicDiffusionFilter module for now, until the framework is developed for Slicer3 to autodetect your module and do the right things. Then:

* create your own CMakeLists.txt file and your own vtkMyModuleWin32Header.h file following the pattern set by other Modules.
* add your module SUBDIR to the CMakeLists.txt file in the Slicer3/Modules directory above.
* to add your module to Slicer3, create a new instance of vtkSlicerMyModuleLogic and vtkSlicerMyModuleGUI in Slicer3/Applications/GUI/Slicer3.cxx, and follow the pattern used by other modules, like the GradientAnisotropicDiffusionFilter module.
* include relevant .h files in Slicer3/Applications/GUI/Slicer3.cxx, and
* specify your module's source and binary Include directories in Slicer3/Application/GUI/CMakeLists.txt
* and include your module in the CMakeLists.txt target link libraries

===Add a module-switch in CMake===
You can add an automatic on/off switch to the ccmake configuration GUI, which will make compilation and development for the user easier.
To do this add the following to two CMakeLists.txt und the Slicer3.cxx files:

* add the following lines to your Slicer3/Module/MyModule/CMakeLists.txt
PROJECT(MyModule)

OPTION(MYMODULE "Do you want to build the MyModule?")
IF(MYMODULE)
... (Rest of the file)
ENDIF(MYMODULE)

* after this you have MYMODULE as a variable which says if your module is build or not
* but we want also to exclude the module library and our source in the Slicer3.cxx file if the module is not build
* in /Slicer3/Applications/GUI/CMakeLists.txt add the following directly above TARGET_LINK_LIBRARIES(...
IF(MYMODULE)
SET(MYMODULE_LINK_LIB MyModule)
ELSE(MYMODULE)
ADD_DEFINITIONS(-DMYMODULE_DEBUG)
ENDIF(MYMODULE)
* then add to the TARGET_LINK_LIBRARIES(...${MYMODULE_LINK_LIB}) instead of your previous entry
* the ''ADD_DEFINITIONS'' declaration adds a preprocessor symbol to the compile which we use to exclude our code from the /Slicer3/Applications/GUI/Slicer3.cxx
* just border your code in /Slicer3/Applications/GUI/Slicer3.cxx with the following:
#ifndef MYMODULE_DEBUG
...(your code/includes)
#endif

=== Miscellaneous ===
'''Helpful tips:'''
* Make the vtkModuleCollapsibleFrames which contain the major logical sections of your module members of your module GUI class and expose them through your API. Doing so helps other developers, who may want to offer a jump to your module's functionality, to programmatically raise your UIpanel and expand the frame they're interested in. This paradigm will help to promote fluid navigation of slicer's interface and the reuse of existing functionality.

= Human Interface and Style Guide for Developers (STILL UNDER DEVELOPMENT) =

=== Introduction ===

These following sections (work in progress) describe how to create 3DSlicer modules that conform to the application's look and feel and behave in a manner consistent with the rest of 3DSlicer. Provided is information on basic interface elements, advice on the effective GUI construction with the available widget set, and some recommended design principles that will help your module integrate well with the rest of 3DSlicer. These guidelines are also intended to enhance 3DSlicer's usability. Following the simple design philosophy outlined here will support the following important goals:

* Users will learn to use your module faster, because interface elements will look and behave in an expected manner across the application.
* Your module will have a nice look & feel that fits within the 3DSlicer environment.
* Your module will be accessible to users at all levels (novice, intermediate and expert).

=== Look and Feel ===

'''GUI Style:''' Try not to add style elements (like foreground and background color, font, relief, etc.) to the interface you create; let the options database (as set up by the vtkSlicerTheme class) specify the style for the widgets in your module so that all modules appear consistent within the Slicer3 application.

=== Module style ===

=== Pop-up windows ===

=== Confirm on Delete ===

Check vtkSlicerApplication::ConfirmDelete setting; if a user has requested to be presented with a confirm on delete, then give them that option.

=== [[Event Bindings]] ===

With respect to the specification of keyboard accelerators, please follow these three recommendations;

* Before assigning "hot-keys" to functionality, either in the main Slicer application or in a new module, please consult the table (and design plan) linked below to make sure the key is not already assigned.
* Across Slicer modules, try to use similar "hot-key" assignments for similar functionality; this consistency makes Slicer easier to learn.
* Once you assign "hot-keys" in your module, please add those mappings to the table for others to reference.

=== Application Font ===
Verdana is the font chosen for the 3DSlicer brand.

Maintaining consistency of type is an important component of maintaining a coherent look and feel for 3DSlicer and any related or derived visual communications. Verdana was designed specifically to be read on a digital display; it is recommended that we use Verdana (or Geneva) wherever possible in 3DSlicer's web presence and online tutorial materials, and wherever reasonable and appropriate in formal printed materials.

Within the software, since it can't be guaranteed that these fonts will be widely available on all platforms, Helvetica or Arial should be used as a substitute. Slicer's theme sets the application font to be Helvetica 8 normal. Please avoid typefaces with serifs.

=== Icons ===

Icons can be a powerful way to represent complicated information within a small footprint on the GUI panel. They associate a visual image with data, state, or a particular operation.

* They should be easy to parse, convey a strong metaphor, and not require significant time for a user to interpret.
* They should be memorable so that a user can recognize them quickly in future sessions with your module.
* If an icon already exists within 3DSlicer to represent the data, state or operation you want to indicate, then re-use that icon (indicate visibility with the open/shutting eye, for example.)
* Note: if the concept is too difficult to represent with a picture, then a text label can always be used instead!

When designing icons, do bear in mind that it's possible to offend users with images that have cultural or polictal connotations. Even colors can have connotations for users in different parts of the world that may be surprising and unintended for the designer and developer. Generally speaking, it's useful to avoid images that contain:

* icons that depict only hands or feet
* images of animals
* maps containing disputed boundaries or region names.
* lists of countries that are not in alphabetical order.
* pictures of flags
* pictures of money

====Slicer icon conventions====
3DSlicer icons should all be of dimension 21x21 pixels.

'''Enabled''' or '''Enabled + Selected''' icons should have:

* a white background (r=255, g=255, b=255, or #FF FF FF)
* a black hairline along the perimeter (r=0,g=0,b=0, or #00 00 00).

'''Disabled''' or '''Enabled + Deselected''' icons should have:
* a grey background, value (r=230, g=230, b=230, or hex value #E6 E6 E6)
* a grey hairline perimeter of value (r=178, g=178, b=178, hex value #B2 B2 B2).

====Downloadable blank icons:====
These icon blanks are provided for download and use:

* Enabled or Enabled+Selected: [[image:IconBlank.png | conventional Slicer icon ]]
* Disabled or Enabled+Deselected: [[image:IconBlankLow.png | "deselected" Slicer icon]]
* Enabled Menubutton: [[image:MenuButtonIconBlank.png | conventional Slicer menubutton icon]]
* Disabled Menubutton: [[image:MenuButtonIconBlankDisabled.png | "disabled" Slicer menubutton icon]]

====Icons currently used in Slicer's Base====
Below is a figure of icons currently in use in 3DSlicer. If the icon you need is already used in Slicer, we encourage its re-use in your own module (the visibility icon is a good example). However, if an icon is re-used, make sure you are using it to convey the same meaning/function -- icons shouldn't have different meanings in different places. Finally, make sure any new icons designed for a module don't duplicate ones already in use elsewhere in Slicer.

[[Image:SlicerToolbarIcons2.png | Slicer icons ]]

=== Widget-specific patterns to follow ===

=== Providing help ===

=== Popup messages (dialog, warning, error, confirm, etc.) ===

=== Language ===

=== Credit and Logos ===

=== Controls and Layout ===

=== Progress Feedback ===

=== Colors: application palette ===

The draft slicer color palette is shown below (this palette will still evolve as the UI design evolves -- in particular to accommodate colors used in the final Slicer3 logo). Developers of code, web content and training materials are encouraged to make color choices for GUI components according to this palette, bearing in mind that some of the colors are linked with special meaning, such as error (red), warning (bright yellow), and system (mediumBlue) messages, and unsaved data in drop-down menus and selection boxes (warmMediumGrey).

[[Image:Slicer3Palette.jpg|[[Image:Slicer3Palette.jpg| Slicer GUI color palette (not applicable to visualization)]]]]

<br />

{| border="1"
|- bgcolor="#ffffff"
!
! color
! R
! G
! B
! hex
! use in slicer
|-
| black
| bgcolor="#000000" |
| align="center" | 0
| align="center" | 0
| align="center" | 0
| #000000
|
|-
| white
| bgcolor="#ffffff" |
| align="center" | 255
| align="center" | 255
| align="center" | 255
| #ffffff
| GUI background
|-
| darkWarmGrey
| bgcolor="#605e53" |
| align="center" | 96
| align="center" | 94
| align="center" | 83
| #605e53
|
|-
| mediumWarmGrey
| bgcolor="#8b8878" |
| align="center" | 139
| align="center" | 136
| align="center" | 120
| #8b8878
| unsaved data ?
|-
| lightWarmGrey
| bgcolor="#cdc8b1" |
| align="center" | 205
| align="center" | 200
| align="center" | 177
| #cdc8b1
|
|-
| warmGreyTint
| bgcolor="#eee8dc" |
| align="center" | 238
| align="center" | 232
| 220
| #eee8dc
|
|-
| darkOrange
| bgcolor="#c44a1a" |
| align="center" | 196
| align="center" | 74
| align="center" | 26
| #c44a1a
|
|-
| brightOrange
| bgcolor="#e06f13" |
| align="center" | 224
| align="center" | 111
| align="center" | 19
| #e06f13
|
|-
| brightYellow
| bgcolor="#e7d13e" |
| align="center" | 231
| align="center" | 209
| align="center" | 62
| #e7d13e
| warning message code
|-
| yellowTint
| bgcolor="#eed680" |
| align="center" | 238
| align="center" | 214
| align="center" | 128
| #eed680
| sag slice
|-
| darkCocoa
| bgcolor="#826647" |
| align="center" | 130
| align="center" | 102
| align="center" | 71
| #826647
|
|-
| lightCocoa
| bgcolor="#b39169" |
| align="center" | 179
| align="center" | 145
| align="center" | 105
| #b39169
|
|-
| stone
| bgcolor="#e0c39e" |
| align="center" | 224
| align="center" | 195
| align="center" | 158
| #e0c39e
|
|-
| stoneTint
| bgcolor="#efe0cd" |
| align="center" | 239
| align="center" | 224
| align="center" | 205
| #efe0cd
|
|-
| red
| bgcolor="#c32e10" |
| align="center" | 195
| align="center" | 46
| align="center" | 15
| #c32e10
| error message code
|-
| brick
| bgcolor="#ba462b" |
| align="center" | 186
| align="center" | 70
| align="center" | 43
| #ba462b
|
|-
| lightBrick
| bgcolor="#c17350" |
| align="center" | 193
| align="center" | 115
| align="center" | 80
| #c17350
| axi slice
|-
| redTint
| bgcolor="#e0b6af" |
| align="center" | 224
| align="center" | 182
| align="center" | 175
| #e0b6af
|
|-
| darkGreen
| bgcolor="#445632" |
| align="center" | 68
| align="center" | 86
| align="center" | 50
| #445632
|
|-
| brightGreen
| bgcolor="#688f42" |
| align="center" | 104
| align="center" | 143
| align="center" | 66
| #688f42
|
|-
| dustyGreen
| bgcolor="#8aa56f" |
| align="center" | 138
| align="center" | 165
| align="center" | 111
| #8aa56f
| cor slice
|-
| greenTint
| bgcolor="#ccf4a6" |
| 204
| 244
| 166
| #ccf4a6
|
|-
| darkBlue
| bgcolor="#494066" |
| align="center" | 73
| align="center" | 64
| align="center" | 102
| #494066
|
|-
| mediumBlue
| bgcolor="#625b81" |
| align="center" | 98
| align="center" | 91
| align="center" | 129
| #625b81
| system message code
|-
| lightBlue
| bgcolor="#887fa3" |
| align="center" | 136
| align="center" | 127
| align="center" | 163
| #887fa3
| unsaved data?
|-
| slicerBlue
| bgcolor="#b3b3e6" |
| align="center" | 179
| align="center" | 179
| align="center" | 230
| #b3b3e6
|
|}

<br />

= Feature Requests, Resource Requests and Emerging Conventions =

We are collecting '''[[Slicer3:FeatureRequests|feature, conventions and resource requests]]''' from users and developers. Appropriate entries from [http://www.na-mic.org/Bug Slicer2's bug tracker] will be periodically added to this repository also.

<br />

= Working questions =

* Getting correct render window size information from vtkKWRenderWidget (answer: yes, vtkKWRenderWidget::GetWidth() is actually its superclass' vtkKWFrame::GetWidth(), which is misleading, it's more a "requested width" kind of option. What you did by calling Tk is OK).
* First pack/unpack of Nav/Zoom widget interacting with scrollbar, making display flash (answer: fixed, update KWWidgets, in vtkSlicerViewControlGUI::PackZoom/NavWidget replace "-fill x -fill y" by "-fill none" if it is still flashing)
* Registry and window size (answer: investigating)
* Progress feedback (answer: vtkKWWindowBase::GetProgressGauge()::SetValue())
* Using registry (what application and module state is reasonable to save?) (answer: I would recommend: the last selected module, the collapsed state of "Manipulate Slice Views", "Manipulate 3D View", the layout (i.e. 1 over 3, or 2x2,etc), if the slice controls are collapsed or not).
* In the toolbar, the indicator should be off, and we could use a different image for the selected and unselected state of a button. Sadly, doing so still seems to make the button recess/shift when it is selected (answer: investigated this one thoroughly, there is sadly no work around that, it's a Tk problem unfortunately).

[[Slicer3:Interface_Design | Return to Slicer3 Interface Design and Usability ]]

[[Slicer3 | Return to Slicer3 main page ]]

Slicer3:Interface Design and Usability

2007-06-14T21:58:59Z

Klawson1: /* Event Bindings */

'''[[Slicer3|<< Back to Slicer3 main page]]'''

[[Slicer3:Developers |Go to Slicer3 Developer Info >> ]]

<br />

= Project goals =

Design and engineer Slicer3 UI. Employ a user-centered approach and establish usability guidelines.

= Project reporting =

The scope of this effort is sorted into four categories: Engineering, UI design, Usability and Slicer3 branding. The subtasks of each category are itemized below and specific information about each category is located on the linked pages.

=== [[Slicer3:UIEngineering|UI Architecture & Engineering]] ===

Tasks: (more detailed UI Architecture & Engineering information can be found [[Slicer3:UIEngineering|here]]).

* design thin GUI layer, separate from the control logic and data model;
* design a model for representing the UI and managing local events;
* extend the model for handling remote events;
* design means of mapping KWWidgets onto that model;
* set priorities with Kitware involving extensions & modifications to KWWidgets;
* determine the api to application logic, used by GUI and by scripts;
* design set of base classes that give module developers an easy pattern to follow;
* develop guidelines for slicer base developers and module developers;
* design mechanism for centrally specifying look & feel (and permitting overrides);

=== [[Slicer3:UIDesign|UI Design & Prototypes]] ===

Tasks: (more detailed UI Design & Prototype information can be found [[Slicer3:UIDesign|here ]]).

* design overall look to Slicer3 application in keeping with core values;
* design look & feel applied to developer modules;
* design KWWidgets class to specify custom widgets for Slicer main app & modules;
* implement Slicer3 Application GUI
* design conventions for specifying global and module-specific keyboard accelerators;
* specify and document global keyboard accelerators;
* iterate on prototype(s) and present them for comments and suggestions;

=== [[Slicer3:Usability|Usability]] ===

Tasks: (more detailed Usability information can be found [[Slicer3:Usability|here ]]).

* develop and publish a user-centered design practice that support usability and software consistency.
* use this process to design and implement main application interface, and some core functionality.

=== [[Slicer3:Slicer3Brand|3DSlicer Brand]] ===

Tasks: (Slicer3 brand sketches can be found[[Slicer3:Slicer3Brand| here ]]).

* fully express new 3DSlicer brand: design logo, splash screen, style sheets for web presence;

= First steps: How to build a Slicer3 Module GUI =

== Virtual Methods ==

At the slicer-developers tcon 2007-02-13, we discussed some adjustments to the virtual methods in vtkSlicerModuleGUI for better consistency and utility. The following list defines the methods that a module needs to implement so the main application (Slicer3.cxx) can operate on all modules generically:

<div style="width: 40%; float: left; padding-right: 3%;">
The following methods are defined by the vtkSlicerModuleGUI and typically won't be overriden:

* '''Enter'''
** ''called when module is raised''
** ''calls CreateGUI if needed (instance variable tracks create state)''
** ''calls AddGUIObservers''
** ''calls UpdateGUI''
* '''Exit'''
** ''called when module is replaced by another''
** ''calls RemoveMRMLObservers''
</div>

<div style="width: 40%; float: left; padding-right: 3%;">

The following methods should be defined by the Module to implement the specific behavior:

* '''CreateGUI'''
** ''instances and packs widgets''
* '''DestroyGUI'''
** ''typically called only by destructor''
** ''breaks any reference cycles''
** ''Deletes widgets''
* '''ProcessGUIEvents'''
** ''responds to events from widgets or slicer GUI classes''
** ''propagates data from GUI into MRML nodes''
* '''ProcessMRMLEvents'''
** ''responds to updates to MRML nodes''
** ''propagates data from MRML to widgets''
* '''AddGUIObservers'''
** ''set observers on widgets and GUI classes (use GUICallbackCommand local instance -- it will call ProcessGUIEvents)''
* '''AddMRMLObservers'''
** ''set observers on MRML nodes and scene (use MRMLCallbackCommand local instance -- it will call ProcessMRMLEvents)''
* '''RemoveGUIObservers'''
* '''RemoveMRMLObservers'''
* '''UpdateGUI'''
** ''copy state from MRML nodes to GUI/Widgets''
** ''if needed for efficiency, check the MTime for the MRML Node and the corresponding GUI and only update if needed (e.g. for a MultiColumnList or other widget the holds a lot of data)''
* '''UpdateMRML'''
** ''copy state from GUI/Widgets to MRML''
</div>

<br style="clear: both;" />

== Usage ==

'''NOTE: this description will change due to current ongoing changes to the module GUI base classes.'''
The figure below shows a current overview of the three classes a new module (called MyModule for example) will need to define (vtkSlicerMyModuleGUI, vtkSlicerMyModuleLogic and vtkMRMLMyModuleNode) and some of the methods those classes should include to utilize the Slicer3 infrastructure. These classes should reside in the slicer3/Modules/MyModule/ directory.

[[Image:Slicer3MyModule.png|[[Image:Slicer3MyModule.png| Base classes for GUI, Logic and MRML ]]]]

'''Deriving your GUI class:''' To create a Module GUI that expresses its interface in Slicer's shared UIpanel, derive your class (vtkSlicerMyModuleGUI) from vtkSlicerModuleGUI. For a Module GUI that expresses its interface in a different panel of the Main Slicer Window, or in a toplevel widget, derive vtkSlicerMyModuleGUI from vtkSlicerComponentGUI instead. Your GUI class will inherit application logic and MRML pointers, an API for setting and observing them, and a framework for defining MRML, Logic and GUI callbacks from its parent class. Specific mediator methods, other logic and MRML node pointers can be added to the module's class definition. Importantly, keep logic and MRML classes independent of the GUI to facilitate testing and command-line execution possible *without* instantiating the Slicer3 GUI.

'''Example:''' An early example to work from is the GradientAnisotropicDiffusionFilter Module; define all the widgets you need within the class and create Get Macros for each of them. Define the methods you need from vtkSlicerModuleGUI and its parent class vtkSlicerComponentGUI, including BuildGUI(); in this method, you'll first add a page to the class's UIPanel (for now, only create one page).

=== Two GUI styles ===
'''Two styles:''' Depending on whether you want a notebook-style GUI for your module (similar to the style used in Slicer2) or a set of stacked collapsible frames to contain different logical sections of your interface like "help" and "display", your BuildGUI() method can be written in one of two ways. The '''notebook style''' may be appropriate for modules with long logical sections within their GUI, to minimize the amount of scrolling required of a user. The '''collapsing style''' may be appropriate for modules that have numerous logical sections, since the amount of horizontal space across which a notebook would array them is limited. The way these two styles are expressed in Slicer3's GUI panel is shown below.

[[Image:S3ModuleStyles.png]]

'''''Collapsing style:''''' The GradientAnisotropicDiffusionFilter Module example implements the collapsible style, first adding a single new Page in its UIPanel:

this->UIPanel->AddPage ( "MyModule", "MyModule", NULL );

then creating a vtkSlicerModuleCollapsibleFrame widget for each logical section in the GUI, parenting each to the UIPanel's single PageWidget, then creating, configuring and packing them from top to bottom in the UIPanel's PageWidget. Each logical section's widgets can be organized inside each of the vtkSlicerModuleCollapsibleFrames. The superclass has some helper methods to construct consisten Help&About Frames across modules.

//--- help and about frame
const char *help = "MyModule does the following...";
const char *about = "This work was supported by...";
vtkKWWidget *page = this->UIPanel->GetPageWidget ("MyModule");
this->BuildHelpAndAboutFrame ( page, help, about );

//--- rest of the frames
vtkSlicerModuleCollapsibleFrame *firstFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *secondFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *thirdFrame = vtkSlicerModuleCollapsibleFrame::New ( );
vtkSlicerModuleCollapsibleFrame *forthFrame = vtkSlicerModuleCollapsibleFrame::New ( );
...
//--- parenting the frames to the same UIpanel page
firstFrame->SetParent ( page );
secondFrame->SetParent ( page );
...
//--- parenting widgets to the various frames
this->widget2->SetParent ( firstFrame->GetFrame () );
this->widget3->SetParent ( secondFrame->GetFrame () );

'''''Notebook style:''''' To create a notebook style GUI (as there is no example yet, a little code will be included here), a new Page must be added to the UIPanel for every tab in the notebook:

//--- get a pointer to the KWUserInterfaceManagerNotebook
vtkKWUserInterfaceManagerNotebook *nbm = vtkKWUserInterfaceManagerNotebook::SafeDownCast ( this->UIPanel->GetUserInterfaceManager());
//--- help and about frame
this->UIPanel->AddPage ( "Help&About", "Information about using this module", NULL );
const char *help = "MyModule does the following...";
const char *about = "This work was supported by...";
vtkKWWidget *page = this->UIPanel->GetPageWidget ("Help");
this->BuildHelpAndAboutFrame ( page, help, about );

//--- pages for other frames
int page1ID = this->UIPanel->AddPage ( "First", "Functionality for some logical piece of module", NULL );
int page2ID = this->UIPanel->AddPage ( "Second", "Functionality for another logical piece of module", NULL );

//--- enabling or disabling notebook tabs
nbm->GetNotebook()->SetPageEnabled ( page1ID, 1 );
nbm->GetNotebook()->SetPageEnabled ( page2ID, 0 );

Widgets to be packed within each notebook page are parented to the PageWidget:

this->widget2->SetParent ( this->UIPanel->GetPageWidget ( "First" ) );
this->widget3->SetParent ( this->UIPanel->GetPageWidget ( "Second" ) );

or can be parented to a widget already parented to the PageWidget. Then they themselves can be created, configured, and packed in the same manner as they are in the GradientAnisotropicDiffusionFilter Module.

=== Defining methods ===
'''Methods to define:''' Define the methods you require from vtkSlicerComponentGUI base class, like: AddGUIObservers(), RemoveGUIObservers(), ProcessLogicEvents(), ProcessGUIEevents(), ProcessMRMLEvents(), Enter() and Exit(); and whatever else your module needs. (Eventually, available modules will be automatically detected, but this is not yet implemented; then, the Enter() method will probably be made to call the BuildGUI() method. For now, instantiate your class in Slicer3.cxx and call its BuildGUI() and other methods, following the pattern for other modules established there.)

=== Adding and removing observers ===
'''Adding observers:''' In AddGUIObservers, add an observer on each widget whose events you want to process. When an event is observed, the ProcessGUIEvents() method is called via the GUICallbackCommand; define this class to propagate information from the GUI to logic and MRML. Though it is tempting, try not to use ProcessGUIEvents() to update the GUI state directly -- just modify the Logic state, and allow observers on the logic and subsequent processing in ProcessLogicEvents() and ProcessMRMLEvents() to bring that state change BACK into the GUI.

'''Removing observers:''' In RemoveGUIObservers, make sure you remove every observer you've added to widgets in the GUI before calling Delete() on your widget. Make sure you call SetAndObserveMRML() and SetAndObserveLogic( ) with NULL pointers in your GUI class destructor to remove all observers on MRML and Logic that you have created.

=== Adding and removing references ===
For convenience, you may want to define pointers to Slicer's MainViewer, or to the SliceViewers, etc. Before Delete() can be called on anything you are referencing, you'll need to release the references. (Failure to release references can result in vtkDebugLeak reports on Application exit). The virtual method TearDownGUI() (inherited from vtkSlicerComponentGUI) can be defined for this purpose. References may be released in this method, and you can also use this method to call RemoveGUIObservers() if you don't want to explicitly call that method.

=== Defining new widgets ===
'''Defining your own widgets:''' The framework for doing this is still evolving. Currently there are two types of new widgets, those defined as extensions to vtkKW (like vtkKWWindowLevelThresholdEditor.h/cxx) and those defined as Slicer-specific widgets, (like vtkSlicerSliceControlWidget.h/cxx, derived from the vtkSlicerWidget.h/cxx base class). The Slicer widgets have methods for putting observers on their widget components, Logic and MRML, and processing events as well. Thus GUI classes that instance them do not have to manage events for them if the widgets' methods are used instead.

=== Using Undo and Redo ===
'''Undo:''' Make sure you process those events that mark junctures at which MRML state should be saved for Undo/Redo (using MRML's SaveStateForUndo() method. For instance, when an entry widget's value has changed, before changing a parameter in the appropriate MRML node, make a call to the MRMLScene's SaveStateForUndo() method with that node as a parameter. Save MRML state at reasonable junctures: for instance, for scale widgets, save MRML state when the scale starts changing, rather than continuously as the scale changes. For an example of they way SaveStateForUndo() is called, see slicer3/Base/GUI/vtkSlicerSliceControllerWidget.cxx. A detailed description of how undo/redo works, and how to use it in your module is available [[Slicer3:Data_Model#Undo.2FRedo_Mechanism | here]].

=== Adding the module to the rest of Slicer3 ===
'''Other files you will have to touch:''' For now, to add your module to Slicer3, create a new instance of vtkSlicerMyModuleLogic and vtkSlicerMyModuleGUI in Applications/GUI/Slicer3.cxx, and follow the pattern used by the GradientAnisotropicDiffusionFilter module for now, until the framework is developed for Slicer3 to autodetect your module and do the right things. Then:

* create your own CMakeLists.txt file and your own vtkMyModuleWin32Header.h file following the pattern set by other Modules.
* add your module SUBDIR to the CMakeLists.txt file in the Slicer3/Modules directory above.
* to add your module to Slicer3, create a new instance of vtkSlicerMyModuleLogic and vtkSlicerMyModuleGUI in Slicer3/Applications/GUI/Slicer3.cxx, and follow the pattern used by other modules, like the GradientAnisotropicDiffusionFilter module.
* include relevant .h files in Slicer3/Applications/GUI/Slicer3.cxx, and
* specify your module's source and binary Include directories in Slicer3/Application/GUI/CMakeLists.txt
* and include your module in the CMakeLists.txt target link libraries

===Add a module-switch in CMake===
You can add an automatic on/off switch to the ccmake configuration GUI, which will make compilation and development for the user easier.
To do this add the following to two CMakeLists.txt und the Slicer3.cxx files:

* add the following lines to your Slicer3/Module/MyModule/CMakeLists.txt
PROJECT(MyModule)

OPTION(MYMODULE "Do you want to build the MyModule?")
IF(MYMODULE)
... (Rest of the file)
ENDIF(MYMODULE)

* after this you have MYMODULE as a variable which says if your module is build or not
* but we want also to exclude the module library and our source in the Slicer3.cxx file if the module is not build
* in /Slicer3/Applications/GUI/CMakeLists.txt add the following directly above TARGET_LINK_LIBRARIES(...
IF(MYMODULE)
SET(MYMODULE_LINK_LIB MyModule)
ELSE(MYMODULE)
ADD_DEFINITIONS(-DMYMODULE_DEBUG)
ENDIF(MYMODULE)
* then add to the TARGET_LINK_LIBRARIES(...${MYMODULE_LINK_LIB}) instead of your previous entry
* the ''ADD_DEFINITIONS'' declaration adds a preprocessor symbol to the compile which we use to exclude our code from the /Slicer3/Applications/GUI/Slicer3.cxx
* just border your code in /Slicer3/Applications/GUI/Slicer3.cxx with the following:
#ifndef MYMODULE_DEBUG
...(your code/includes)
#endif

=== Miscellaneous ===
'''Helpful tips:'''
* Make the vtkModuleCollapsibleFrames which contain the major logical sections of your module members of your module GUI class and expose them through your API. Doing so helps other developers, who may want to offer a jump to your module's functionality, to programmatically raise your UIpanel and expand the frame they're interested in. This paradigm will help to promote fluid navigation of slicer's interface and the reuse of existing functionality.

= Human Interface and Style Guide for Developers (STILL UNDER DEVELOPMENT) =

=== Introduction ===

These following sections (work in progress) describe how to create 3DSlicer modules that conform to the application's look and feel and behave in a manner consistent with the rest of 3DSlicer. Provided is information on basic interface elements, advice on the effective GUI construction with the available widget set, and some recommended design principles that will help your module integrate well with the rest of 3DSlicer. These guidelines are also intended to enhance 3DSlicer's usability. Following the simple design philosophy outlined here will support the following important goals:

* Users will learn to use your module faster, because interface elements will look and behave in an expected manner across the application.
* Your module will have a nice look & feel that fits within the 3DSlicer environment.
* Your module will be accessible to users at all levels (novice, intermediate and expert).

=== Look and Feel ===

'''GUI Style:''' Try not to add style elements (like foreground and background color, font, relief, etc.) to the interface you create; let the options database (as set up by the vtkSlicerTheme class) specify the style for the widgets in your module so that all modules appear consistent within the Slicer3 application.

=== Module style ===

=== Pop-up windows ===

=== Confirm on Delete ===

Check vtkSlicerApplication::ConfirmDelete setting; if a user has requested to be presented with a confirm on delete, then give them that option.

=== Event Bindings ===

With respect to the specification of keyboard accelerators, please follow these three recommendations;

* Before assigning "hot-keys" to functionality, either in the main Slicer application or in a new module, please consult the table (and design plan) linked below to make sure the key is not already assigned.
* Across Slicer modules, try to use similar "hot-key" assignments for similar functionality; this consistency makes Slicer easier to learn.
* Once you assign "hot-keys" in your module, please add those mappings to the table for others to reference.

[[Event bindings]].

=== Application Font ===
Verdana is the font chosen for the 3DSlicer brand.

Maintaining consistency of type is an important component of maintaining a coherent look and feel for 3DSlicer and any related or derived visual communications. Verdana was designed specifically to be read on a digital display; it is recommended that we use Verdana (or Geneva) wherever possible in 3DSlicer's web presence and online tutorial materials, and wherever reasonable and appropriate in formal printed materials.

Within the software, since it can't be guaranteed that these fonts will be widely available on all platforms, Helvetica or Arial should be used as a substitute. Slicer's theme sets the application font to be Helvetica 8 normal. Please avoid typefaces with serifs.

=== Icons ===

Icons can be a powerful way to represent complicated information within a small footprint on the GUI panel. They associate a visual image with data, state, or a particular operation.

* They should be easy to parse, convey a strong metaphor, and not require significant time for a user to interpret.
* They should be memorable so that a user can recognize them quickly in future sessions with your module.
* If an icon already exists within 3DSlicer to represent the data, state or operation you want to indicate, then re-use that icon (indicate visibility with the open/shutting eye, for example.)
* Note: if the concept is too difficult to represent with a picture, then a text label can always be used instead!

When designing icons, do bear in mind that it's possible to offend users with images that have cultural or polictal connotations. Even colors can have connotations for users in different parts of the world that may be surprising and unintended for the designer and developer. Generally speaking, it's useful to avoid images that contain:

* icons that depict only hands or feet
* images of animals
* maps containing disputed boundaries or region names.
* lists of countries that are not in alphabetical order.
* pictures of flags
* pictures of money

====Slicer icon conventions====
3DSlicer icons should all be of dimension 21x21 pixels.

'''Enabled''' or '''Enabled + Selected''' icons should have:

* a white background (r=255, g=255, b=255, or #FF FF FF)
* a black hairline along the perimeter (r=0,g=0,b=0, or #00 00 00).

'''Disabled''' or '''Enabled + Deselected''' icons should have:
* a grey background, value (r=230, g=230, b=230, or hex value #E6 E6 E6)
* a grey hairline perimeter of value (r=178, g=178, b=178, hex value #B2 B2 B2).

====Downloadable blank icons:====
These icon blanks are provided for download and use:

* Enabled or Enabled+Selected: [[image:IconBlank.png | conventional Slicer icon ]]
* Disabled or Enabled+Deselected: [[image:IconBlankLow.png | "deselected" Slicer icon]]
* Enabled Menubutton: [[image:MenuButtonIconBlank.png | conventional Slicer menubutton icon]]
* Disabled Menubutton: [[image:MenuButtonIconBlankDisabled.png | "disabled" Slicer menubutton icon]]

====Icons currently used in Slicer's Base====
Below is a figure of icons currently in use in 3DSlicer. If the icon you need is already used in Slicer, we encourage its re-use in your own module (the visibility icon is a good example). However, if an icon is re-used, make sure you are using it to convey the same meaning/function -- icons shouldn't have different meanings in different places. Finally, make sure any new icons designed for a module don't duplicate ones already in use elsewhere in Slicer.

[[Image:SlicerToolbarIcons2.png | Slicer icons ]]

=== Widget-specific patterns to follow ===

=== Providing help ===

=== Popup messages (dialog, warning, error, confirm, etc.) ===

=== Language ===

=== Credit and Logos ===

=== Controls and Layout ===

=== Progress Feedback ===

=== Colors: application palette ===

The draft slicer color palette is shown below (this palette will still evolve as the UI design evolves -- in particular to accommodate colors used in the final Slicer3 logo). Developers of code, web content and training materials are encouraged to make color choices for GUI components according to this palette, bearing in mind that some of the colors are linked with special meaning, such as error (red), warning (bright yellow), and system (mediumBlue) messages, and unsaved data in drop-down menus and selection boxes (warmMediumGrey).

[[Image:Slicer3Palette.jpg|[[Image:Slicer3Palette.jpg| Slicer GUI color palette (not applicable to visualization)]]]]

<br />

{| border="1"
|- bgcolor="#ffffff"
!
! color
! R
! G
! B
! hex
! use in slicer
|-
| black
| bgcolor="#000000" |
| align="center" | 0
| align="center" | 0
| align="center" | 0
| #000000
|
|-
| white
| bgcolor="#ffffff" |
| align="center" | 255
| align="center" | 255
| align="center" | 255
| #ffffff
| GUI background
|-
| darkWarmGrey
| bgcolor="#605e53" |
| align="center" | 96
| align="center" | 94
| align="center" | 83
| #605e53
|
|-
| mediumWarmGrey
| bgcolor="#8b8878" |
| align="center" | 139
| align="center" | 136
| align="center" | 120
| #8b8878
| unsaved data ?
|-
| lightWarmGrey
| bgcolor="#cdc8b1" |
| align="center" | 205
| align="center" | 200
| align="center" | 177
| #cdc8b1
|
|-
| warmGreyTint
| bgcolor="#eee8dc" |
| align="center" | 238
| align="center" | 232
| 220
| #eee8dc
|
|-
| darkOrange
| bgcolor="#c44a1a" |
| align="center" | 196
| align="center" | 74
| align="center" | 26
| #c44a1a
|
|-
| brightOrange
| bgcolor="#e06f13" |
| align="center" | 224
| align="center" | 111
| align="center" | 19
| #e06f13
|
|-
| brightYellow
| bgcolor="#e7d13e" |
| align="center" | 231
| align="center" | 209
| align="center" | 62
| #e7d13e
| warning message code
|-
| yellowTint
| bgcolor="#eed680" |
| align="center" | 238
| align="center" | 214
| align="center" | 128
| #eed680
| sag slice
|-
| darkCocoa
| bgcolor="#826647" |
| align="center" | 130
| align="center" | 102
| align="center" | 71
| #826647
|
|-
| lightCocoa
| bgcolor="#b39169" |
| align="center" | 179
| align="center" | 145
| align="center" | 105
| #b39169
|
|-
| stone
| bgcolor="#e0c39e" |
| align="center" | 224
| align="center" | 195
| align="center" | 158
| #e0c39e
|
|-
| stoneTint
| bgcolor="#efe0cd" |
| align="center" | 239
| align="center" | 224
| align="center" | 205
| #efe0cd
|
|-
| red
| bgcolor="#c32e10" |
| align="center" | 195
| align="center" | 46
| align="center" | 15
| #c32e10
| error message code
|-
| brick
| bgcolor="#ba462b" |
| align="center" | 186
| align="center" | 70
| align="center" | 43
| #ba462b
|
|-
| lightBrick
| bgcolor="#c17350" |
| align="center" | 193
| align="center" | 115
| align="center" | 80
| #c17350
| axi slice
|-
| redTint
| bgcolor="#e0b6af" |
| align="center" | 224
| align="center" | 182
| align="center" | 175
| #e0b6af
|
|-
| darkGreen
| bgcolor="#445632" |
| align="center" | 68
| align="center" | 86
| align="center" | 50
| #445632
|
|-
| brightGreen
| bgcolor="#688f42" |
| align="center" | 104
| align="center" | 143
| align="center" | 66
| #688f42
|
|-
| dustyGreen
| bgcolor="#8aa56f" |
| align="center" | 138
| align="center" | 165
| align="center" | 111
| #8aa56f
| cor slice
|-
| greenTint
| bgcolor="#ccf4a6" |
| 204
| 244
| 166
| #ccf4a6
|
|-
| darkBlue
| bgcolor="#494066" |
| align="center" | 73
| align="center" | 64
| align="center" | 102
| #494066
|
|-
| mediumBlue
| bgcolor="#625b81" |
| align="center" | 98
| align="center" | 91
| align="center" | 129
| #625b81
| system message code
|-
| lightBlue
| bgcolor="#887fa3" |
| align="center" | 136
| align="center" | 127
| align="center" | 163
| #887fa3
| unsaved data?
|-
| slicerBlue
| bgcolor="#b3b3e6" |
| align="center" | 179
| align="center" | 179
| align="center" | 230
| #b3b3e6
|
|}

<br />

= Feature Requests, Resource Requests and Emerging Conventions =

We are collecting '''[[Slicer3:FeatureRequests|feature, conventions and resource requests]]''' from users and developers. Appropriate entries from [http://www.na-mic.org/Bug Slicer2's bug tracker] will be periodically added to this repository also.

<br />

= Working questions =

* Getting correct render window size information from vtkKWRenderWidget (answer: yes, vtkKWRenderWidget::GetWidth() is actually its superclass' vtkKWFrame::GetWidth(), which is misleading, it's more a "requested width" kind of option. What you did by calling Tk is OK).
* First pack/unpack of Nav/Zoom widget interacting with scrollbar, making display flash (answer: fixed, update KWWidgets, in vtkSlicerViewControlGUI::PackZoom/NavWidget replace "-fill x -fill y" by "-fill none" if it is still flashing)
* Registry and window size (answer: investigating)
* Progress feedback (answer: vtkKWWindowBase::GetProgressGauge()::SetValue())
* Using registry (what application and module state is reasonable to save?) (answer: I would recommend: the last selected module, the collapsed state of "Manipulate Slice Views", "Manipulate 3D View", the layout (i.e. 1 over 3, or 2x2,etc), if the slice controls are collapsed or not).
* In the toolbar, the indicator should be off, and we could use a different image for the selected and unselected state of a button. Sadly, doing so still seems to make the button recess/shift when it is selected (answer: investigated this one thoroughly, there is sadly no work around that, it's a Tk problem unfortunately).

[[Slicer3:Interface_Design | Return to Slicer3 Interface Design and Usability ]]

[[Slicer3 | Return to Slicer3 main page ]]