View source for Documentation/4.10/Developers/Python scripting

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

= Start Here =

Please read [https://docs.google.com/presentation/d/1JXIfs0rAM7DwZAho57Jqz14MRn2BIMrjB17Uj_7Yztc/edit?usp=sharing these slides] and work through the example code.

Refer to [http://www.na-mic.org/Wiki/index.php/2013_Project_Week_Breakout_Session:Slicer4Python this description that includes links to all the documentation].

Look at the [[Documentation/{{documentation/version}}/ScriptRepository |Script Repository]] for examples and inspiration.

= Background =

This is an evolution of the [[Slicer3:Python|python implementation in slicer3]].  Slicer's APIs are now natively wrapped in python.  

Topics like plotting are still experimental in slicer4.

See [http://www.na-mic.org/Wiki/index.php/AHM2012-Slicer-Python this 2012 presentation on the state of python in slicer4].

'''See [[Documentation/{{documentation/currentversion}}/Training#Slicer4_Programming_Tutorial|the python slicer4 tutorial for more examples]].'''

[[Documentation/{{documentation/version}}/Developers/Tutorials/SelfTestModule|Slicer Self Tests]] can be written in python, and provide a good source of examples for manipulating the data, logic, and gui of slicer.

= Start Here for Scripted Module and Extension Development=
An extensive tutorial and reference page was created [http://www.na-mic.org/Wiki/index.php/2013_Project_Week_Breakout_Session:Slicer4Python for the Slicer/Python breakout session at the NA-MIC 2013 Summer Project Week].

= Usage options =

==Python Interactor==

Use the Window->Python Interactor (Control-3 on window/linux, Command-3 on mac) to bring up the Qt-based console with access to the vtk, Qt, and Slicer wrapped APIs.

Most python code can be installed and run from this window, but because it exists in the event driven Qt GUI environment, some operations like, like parallel processing or headless operation, are not easily supported.

=== Examples ===

Start Slicer and bring up python console.  Load a sample volume like this:

<pre>
import SampleData
sampleDataLogic = SampleData.SampleDataLogic()
sampleDataLogic.downloadMRHead()
</pre>

Get the volume node for that volume:

<pre>
n = getNode('MRHead')
</pre>

You can use Tab to see lists of methods for a class instance.

==== Accessing Volume data as numpy array ====

You can easily inspect and manipulate volume data using numpy and related code.  In slicer you can do this:

<pre>
a = array('MRHead')
</pre>

and 'a' will be a pointer to the appropriate data (no data copying). If you get an error that 'array' is not defined then run 'import slicer.util' and use 'slicer.util.array'. Scalar volumes become three-dimensional arrays, while vector volumes become 4D, and tensor volumes are 5D.  All arrays can be manipulated directly. After modification is completed, call Modified() method of the volume node to indicate that the image is modified and trigger display update.

The '''array''' method is intended for quick testing only, as multiple nodes may have the same name and various arrays may be retrieved from MRML nodes. In Slicer modules, it is recommended to use '''arrayFromVolume''' instead, which takes a MRML node as input.

<pre>
volumeNode = getNode('MRHead')
a = arrayFromVolume(volumeNode)
# Increase image contrast
a[:] = a * 2.0
arrayFromVolumeModified(volumeNode)
</pre>

If you don't process the data in-place but you have computation results in a numpy array, then you have to copy the contents of a numpy array into a volume, using '''updateVolumeFromArray''':

<pre>
import numpy as np
import math

def some_func(x, y, z):
  return 0.5*x*x + 0.3*y*y + 0.5*z*z

a = np.fromfunction(some_func,(30,20,15))

volumeNode = slicer.mrmlScene.AddNewNodeByClass('vtkMRMLScalarVolumeNode')
volumeNode.CreateDefaultDisplayNodes()
updateVolumeFromArray(volumeNode, a)
setSliceViewerLayers(background=volumeNode)
</pre>

==== Accessing Model data as numpy array ====

You can easily inspect and manipulate point coordinates of a model using numpy and related code by calling `arrayFromModelPoints`. After modification is completed, call Modified() method on the polydata to indicate that the model is modified and trigger display update.

<pre>
# Create a model containing a sphere
sphere = vtk.vtkSphereSource()
sphere.SetRadius(30.0)
sphere.Update()
modelNode = slicer.mrmlScene.AddNewNodeByClass('vtkMRMLModelNode')
modelNode.SetAndObservePolyData(sphere.GetOutput())
modelNode.CreateDefaultDisplayNodes()
a = arrayFromModelPoints(modelNode)
# change Y scaling
a[:,2] = a[:,2] * 2.5
arrayFromModelPointsModified(modelNode)
</pre>

==== Running a CLI from Python ====

Here's an example to create a model from a volume using the [[Documentation/4.0/Modules/GrayscaleModelMaker|Grayscale Model Maker]]
<pre>
def grayModel(volumeNode):
  parameters = {}
  parameters["InputVolume"] = volumeNode.GetID()
  outModel = slicer.vtkMRMLModelNode()
  slicer.mrmlScene.AddNode( outModel )
  parameters["OutputGeometry"] = outModel.GetID()
  grayMaker = slicer.modules.grayscalemodelmaker
  return (slicer.cli.runSync(grayMaker, None, parameters))
</pre>

To try this, download the MRHead dataset from the [[Documentation/4.0/Modules/SampleData|Sample Data]] and paste the code into the python console and then run this:
<pre>
v = getNode('MRHead')
cliNode = grayModel(v)
</pre>

Here is an example for running a CLI module from a scripted module:
https://github.com/fedorov/ChangeTrackerPy/blob/master/ChangeTracker/ChangeTrackerWizard/ChangeTrackerRegistrationStep.py#L56-L67

'' Passing Fiducials to CLIs via a Python Script ''

<pre>

import SampleData
sampleDataLogic = SampleData.SampleDataLogic()
head = sampleDataLogic.downloadMRHead()
volumesLogic = slicer.modules.volumes.logic()
headLabel = volumesLogic.CreateLabelVolume(slicer.mrmlScene, head, 'head-label')

fiducialNode = slicer.vtkMRMLAnnotationFiducialNode()
fiducialNode.SetFiducialWorldCoordinates((1,0,5))
fiducialNode.SetName('Seed Point')
fiducialNode.Initialize(slicer.mrmlScene)
fiducialsList = getNode('Fiducials List')

params = {'inputVolume': head.GetID(), 'outputVolume': headLabel.GetID(), 'seed' : fiducialsList.GetID(), 'iterations' : 2} 

cliNode = slicer.cli.runSync(slicer.modules.simpleregiongrowingsegmentation, None, params)

</pre>

''Running CLI in the background''

If the CLI module is executed using slicer.cli.run method then the CLI module runs in a background thread, so the call to grayModel will return right away and the user interface will not be blocked. The slicer.cli.run call returns a cliNode (an instance of [http://slicer.org/doc/html/classvtkMRMLCommandLineModuleNode.html vtkMRMLCommandLineModuleNode]) which can be used to monitor the progress of the module.

In this example we create a simple callback that will be called whenever the cliNode is modified.  The status will tell you if the nodes is Pending, Running, or Completed.

<pre>
def printStatus(caller, event):
  print("Got a %s from a %s" % (event, caller.GetClassName()))
  if caller.IsA('vtkMRMLCommandLineModuleNode'):
    print("Status is %s" % caller.GetStatusString())

cliNode.AddObserver('ModifiedEvent', printStatus)
</pre>

If you need to cancel the CLI, call
<pre>
cliNode.Cance()
</pre>

To get the log info for the process you can call <pre>cliNode.GetOutputText()</pre> and <pre>cliNode.GetErrorText()</pre>.

''Get list of parameter names''

The following script prints all the parameter names of a CLI parameter node:

<pre>
cliModule = slicer.modules.grayscalemodelmaker
n=cliModule.cliModuleLogic().CreateNode()
for groupIndex in xrange(0,n.GetNumberOfParameterGroups()):
  for parameterIndex in xrange(0,n.GetNumberOfParametersInGroup(groupIndex)):
    print '  Parameter ({0}/{1}): {2} ({3})'.format(groupIndex, parameterIndex, n.GetParameterName(groupIndex, parameterIndex), n.GetParameterLabel(groupIndex, parameterIndex))
</pre>

==== Accessing slice vtkRenderWindows from slice views ====

The example below shows how to get the rendered slice window.

<pre>
lm = slicer.app.layoutManager()
redWidget = lm.sliceWidget('Red')
redView = redWidget.sliceView()
wti = vtk.vtkWindowToImageFilter()
wti.SetInput(redView.renderWindow())
wti.Update()
v = vtk.vtkImageViewer()
v.SetColorWindow(255)
v.SetColorLevel(128)
v.SetInputConnection(wti.GetOutputPort())
v.Render()
</pre>

= Script Repository = 

See [[Documentation/Nightly/ScriptRepository|ScriptRepository]] for a larger collection of example code.

{{:Documentation/{{documentation/version}}/Developers/FAQ/Python Scripting|Python Scripting}}