Documentation/4.3/Developers/FAQ

From Slicer Wiki
Revision as of 03:41, 5 September 2013 by UpdateBot (talk | contribs) (Nightly -> 4.3)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Home < Documentation < 4.3 < Developers < FAQ


For the latest Slicer documentation, visit the read-the-docs.


Contents


Developer FAQ: General

What is Slicer ?

3D Slicer is a free open source extensible software application for medical image computing and visualization. Mainly written in C++ and based on the NA-MIC kit, 3D Slicer relies on a variety of libraries: VTK, ITK, CTK, CMake, Qt and Python.

To ensure the stability of the application, relying on a robust software process, the source code is compiled and tested on a daily basis on a variety of platform configurations. The testing results are summarized and reported using a web-based centralized CDash dashboard. Developers of 3D Slicer can also report issues on the open mailing list or using the web-based bug tracking system.

3D Slicer consists of both a lean application core and modules offering specific functionality. The core implements the user interface, provides support for data input/output (IO) and visualization and also exposes developer interfaces that support extension of the application with new modules.

Multiple types of modules are supported: CLI, Loadable module, Scripted module and Editor effect. While the developer has to choose between one of these types to implement its module, the end user won't notice the difference as they all share the same look & feel. The choice for a given type of module is usually based on the type of inputs/parameters for a given module.

These modules can be either built-in or installed on demand via the extensions manager.

How to setup for Git development ?

See Slicer Setup

How to contribute a patch ?

The following instructions describes the recommended workflow to contribute patch to Slicer code base.

It is assumed that you followed the New community member checklist, have a clone of https://github.com/Slicer/Slicer/ and have setup the development environment as described here.

  1. Create an issue in the tracker. For example, see issue #1906

  2. Make sure your clone has a git remote. After forking Slicer repository, replace jcfr with your git login.

    git remote add jcfr git@github.com:jcfr/Slicer.git

  3. Create a topic named <issuer_number>-a-descriptive-topic-name. For example:

    git checkout -b 1906-uninstall-extensions-on-restart

  4. Fix the code or implement your feature, then commit your change(s)

    1. Make sure to read the Slicer Coding and Commit Style Guide

  5. Publish the topic on your fork

    git push jcfr 1906-uninstall-extensions-on-restart

  6. Add a note to the issue with a link pointing to your topic. For example, see note 1906#c4578



What is our bug / feature request workflow ?

The following diagram illustrates Slicer issue workflow:

Mantis-workflow.png

Source: Adapted from http://www.warelab.org/blog/?p=24


How to schedule a Developer Hangout ?

See instruction here


Developer FAQ: Building

What to do if QtSDK installer hangs ?

If QtSDK installer hangs, use -style cleanlooks command line option. For details, see here.


Developer FAQ: Python Scripting

How to systematically execute custom python code at startup ?

Each time Slicer starts, it will look up for a file named .slicerrc.py into your HOME folder.

See What is my HOME folder ?

How to save an image/volume using python ?

The module slicer.util provides methods allowing to save either a node or an entire scene:

  • saveNode
  • saveScene

For more details see:


How to assign a volume to a Slice view ?

Assuming the MRHead sample data has been loaded, you could do the following: 

red_logic = slicer.app.layoutManager().sliceWidget("Red").sliceLogic()
red_cn = red_logic.GetSliceCompositeNode()
red_logic.GetSliceCompositeNode().SetBackgroundVolumeID(slicer.util.getNode('MRHead').GetID())

Discussion: http://slicer-devel.65872.n3.nabble.com/Assign-volumes-to-views-tt4028694.html

How to access vtkRenderer in Slicer 3D view ?

renderer = slicer.app.layoutManager().threeDWidget(0).threeDView().renderWindow().GetRenderers().GetFirstRenderer()

Should I used 'old style' or 'new style' python classes in my scripted module

When python classes have no superclass specified they are 'old style' as described here [1].

In general it doesn't matter for the classes in a scripted module, since they won't be subclassed either old or new style should be the same.

For other python code in slicer where you might be subclassing, it's better to use new style classes. See the class hierarchies in the EditorLib and the DICOMLib for examples.

How to harden a transform ?

>>> n = getNode('Bone')
>>> logic = slicer.vtkSlicerTransformLogic()
>>> logic.hardenTransform(n)

Discussion: http://slicer-devel.65872.n3.nabble.com/Scripting-hardened-transforms-tt4029456.html

Where can I find example scripts?

Have a look at Documentation/4.3/ScriptRepository.


User FAQ: Extensions

What is an extension ?

Extensions in the Extension manager.

An extension could be seen as a delivery package bundling together one or more Slicer modules. After installing an extension, the associated modules will be presented to the user as built-in ones

The Slicer community maintains a website referred to as the Slicer Extensions Catalog to support finding, downloading and installing of extensions. Access to this website is integral to Slicer and facilitated by the Extensions Manager functionality built into the distributed program.

The Catalog classifies extensions into three levels of compliance:

  1. Category 1: Fully compliant Slicer Extensions: Slicer license, open source, maintained.
  2. Category 2: Open source, contact exists.
  3. Category 3: All other extensions (work in progress, beta, closed source etc).

To publish extensions, developers should consider reading the following pages:

What is the extensions catalog ?

The extensions catalog provides Slicer users with a convenient way to access the extensions previously uploaded on the extensions server:

Why there are no windows 32-bit extensions available ?

  • Win 32 has a very limited amount of memory available to an application.
  • Many registration and segmentation algorithms fail on that platform because they run out of memory, when used with state of large data.
  • Some of these failures are just that, some can crash slicer. Even though the "real" failure is caused by overextending the capabilities of the hardware (in a way the users fault), it appears to the user that Slicer does not work.
  • If you search the archives of slicer-users there are several such complaints until we started to discourage people to use 32 bit.

Discussion: http://massmail.spl.harvard.edu/public-archives/slicer-users/2013/006703.html

Should I install the nightly version to access to last extension updates ?

If the extension developers contributed updates for the current stable release, you don't have to install the nightly version of Slicer. You can simply update the extension. Consider reading How to update an already installed extension ?.

On the other hand, if the extension developers stopped to maintain the version of their extension built against the stable release (so that we can use the latest feature that will be in the next Slicer release), downloading the nightly is the only way to get the latest version of the extension.

How to update an already installed extension?

Assuming updates extensions are available for your version of Slicer, it is currently not possible without uninstalling the extension and re-installing it.

We are currently developing a mechanism allowing to either manually update or automatically suggest update. In the process of finalizing, reviewing and testing, the corresponding feature will be available in Slicer 4.12.

For more details, see [1][2] and [3]

[1] http://na-mic.org/Mantis/view.php?id=2089

[2] https://github.com/mwoehlke-kitware/Slicer/tree/REBASE-2089-update-extensions

[3] http://wiki.slicer.org/wiki/Documentation/Labs/ExtensionsFrameworkRoadmap

How to manually install an extension ?

1) Get revision associated with your install or built Slicer. (Menu -> Help -> About)

2) Download extension matching your Slicer revision. Select operating system, bitness and enter revision on http://slicer.kitware.com/midas3/slicerappstore

3) Extract the archive (zip or tar.gz) in a folder. You should then have a folder like: 

/path/to/<slicer_revision>-<os>-<bitness>-<extension_name>-<extension_scm><extension_revision>-YYYY-MM-DD

containing folder like: 

lib/Slicer-X.Y/cli-modules
lib/Slicer-X.Y/qt-loadable-modules
lib/Slicer-X.Y/qt-scripted-modules

For more details: Documentation/4.3/Developers/DirectoryStructure

4) In the Module settings (Menu -> Edit -> Settings), add the path ending with lib/Slicer-X.Y/{cli|qt-scripted|qt-loadable}-modules


Developer FAQ: Modules

Within a Slicer build-tree, where are located Slicer modules ?

Slicer module executables and libraries are located in your main Slicer build directory Slicer-Superbuild/Slicer-build. Refer to Directory Structure description for more details.

How to build module outside of Slicer source tree

Follow developers guide for building modules

How to modify local version of External module

Some Slicer modules (such as OpenIGTLink and OpenIGTLinkIF) are built as External git projects by CMake scripts in the Slicer/SuperBuild directory. The SuperBuild process may refresh from the repository unexpectedly, overwriting any local changes. To avoid this, comment out the git settings in the appropriate external build file while making local edits. For example, in SuperBuild/External_OpenIGTLinkIF.cmake: 

     GIT_REPOSITORY "${git_protocol}://github.com/openigtlink/OpenIGTLinkIF.git"
     GIT_TAG "f9b65b1ffd2992862025f3c6ec5fe30e6f5dd395"
     SOURCE_DIR ${CMAKE_BINARY_DIR}/${proj}
 
     # GIT_REPOSITORY "${git_protocol}://github.com/openigtlink/OpenIGTLinkIF.git"
     # GIT_TAG "f9b65b1ffd2992862025f3c6ec5fe30e6f5dd395"
     SOURCE_DIR ${CMAKE_BINARY_DIR}/${proj}


Developer FAQ: Extensions

Should the name of the source repository match the name of the extension ?

Assuming your extension is named AwesomeFilter, generally, we suggest to name the extension repository either SlicerAwesomeFilter, Slicer-AwesomeFilter, Slicer_AwesomeFilter, SlicerExtension-AwesomeFilter, SlicerExtension_AwesomeFilter.

Doing so will minimize confusion by clearly stating that the code base is associated with Slicer.

What is the Extensions Index ?

Think of the ExtensionsIndex as a repository containing a list of extension description files *.s4ext used by the Slicer extensions build system to build, test, package and upload extensions on the extensions server.

Once uploaded on an extensions server, within Slicer, extensions can be installed using the extensions manager.

The extensions catalog provides Slicer users with a convenient way to access the extensions previously uploaded.

There are multiple branches on the ExtensionsIndex:

  • master: This branch contain description files of extensions that will be built against Slicer nightly.
  • [...]
  • 4.10: This branch contain description files of extensions that will be built against latest Slicer 4.10 available patch release.

The reasoning behind this approach is that since both the Slicer API and ABI associated with Slicer base libraries are changing often, compatibility of the extensions available for download is guaranteed by building extensions against every Slicer revisions.

It means that developer willing to have their extensions available on the different versions of Slicer will have to submit pull requests for each version.

What is an API Key ?

See http://en.wikipedia.org/wiki/Application_programming_interface_key


How to obtain an API key to submit on the extension server ?

In order to upload extensions on the slicer extensions server, it is required to:


  1. Create an account on the extension server: http://slicer.kitware.com by clicking on the Register link in the top right corner

    2. Slicer-midas-extensions-server-registration.png

    This image shows the top portion of http://slicer.kitware.com after it has been expanded by clicking the Register button.

  2. Go to NA-MIC community and click on Join community

  3. Retrieve your API key looking at your account details:

    1. Go to http://slicer.kitware.com. If needed, signin by clicking on Login in the top right corner.
    2. Click on your name in the top right corner.
    3. Click on My account.
    4. Click on API tab.

    5. Copy the API Key associated with Default application.

      1. There is currently a bug preventing api key containing non alpanumeric characters from being used.
        If your Default api key contain for example a /, try to delete the api key and regenerate one that is not containing "/" and is named Default.
        We are working on the issue to update the build system so that it properly escape "/" and also get in touch with Midas team so that api key containing just number and letter are generated.

    4. Slicer-midas-extensions-server-obtaining-api-key.png

Where can I find the extension templates ?

The extensions templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Extensions/Testing/

Using the Wizard, you could easily create a new extension without having to copy, rename and update manually every files.

How to build an extension ?

Assuming that the source code of your extension is located in folder MyExtension, this could be achieved doing:

Makefile Visual Studio 
$ mkdir MyExtension-build
$ cd MyExtension-build
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
$ make
  1. Start CMake, select source and build directory
  2. Add Slicer_DIR entry to the cache
  3. Click on Configure, select generator, then click on Generate button.
  4. Open MyExtension.sln, select Release configuration, then menu Project -> Build Solution.

How to package an extension ?

Assuming your extension has been built into folder MyExtension-build, this could be achieved doing:

Makefile Visual Studio 
$ make package
  1. Open MyExtension.sln
  2. Select PACKAGES project, then right click and select Build

How to upload an extension ?

Assuming your extension has been built and packaged into folder MyExtension-build, this could be achieved by first re-configuring the project providing your midas credentials and then building the ExperimentalUploadOnly target:

Makefile Visual Studio 
$ cmake -DMIDAS_PACKAGE_EMAIL:STRING=<YOUR-MIDAS-LOGIN> -DMIDAS_PACKAGE_API_KEY:STRING=<YOUR-MIDAS-APIKEY> .
$ make ExperimentalUploadOnly
  1. Start CMake, select source and build directory
  2. Add MIDAS_PACKAGE_EMAIL and MIDAS_PACKAGE_API_KEY entries to the cache
  3. Open MyExtension.sln
  4. Select Release configuration
  5. Select ExperimentalUploadOnly project, then right click and select Build

What are the extension specific targets: ExperimentalUpload, ExperimentalUploadOnly, ... ?

Slicer extension build system provides the developer with a set of convenient targets allowing to build and upload extensions.

Target name Description
Experimental Configure, build, test the extension and publish result on CDash.
ExperimentalUpload Equivalent to Experimental target followed by packaging and upload of the extension on the extension server.
ExperimentalUploadOnly Only proceed to the upload of the extension on the extension server.
test or BUILD_TESTS Locally execute the test
package or PACKAGE Locally package the extension

Is --launch flag available for a MacOSX installed Slicer.app ?

On MacOSx, running Slicer with the --help argument does NOT list the usual launcher related options. 

$ ./Slicer.app/Contents/MacOS/Slicer --help
Usage
 Slicer [options]
 
 Options
   --, --ignore-rest                     Ignores the rest of the labeled arguments following this flag. (default: false)
   -h, --help                            Display available command line arguments.
   [...]
   --version                             Displays version information and exits.

To provide some background information, when generating the package that will be distributed, an application bundle Slicer.app is created. As explained here, a bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code. It means that since all libraries contained within a bundle are referenced relatively to the location of either the CLI or the Slicer executable, the use of launcher does NOT make sens.

To help fixing-up the libraries, executables and plugins so that they reference each other in a relative way, CMake provides us with the BundleUtilities module.

This module is used in two situations:

  1. Fixup of Slicer application itself. See SlicerCPack.cmake#L36-68 and SlicerCPackBundleFixup.cmake.in
  2. Fixup of an extension package. See SlicerExtensionCPack.cmake#L126-143 and SlicerExtensionCPackBundleFixup.cmake.in


What is the difference between Documentation/Nightly/Modules and Documentation/Nightly/Extensions ?

As suggested by the namespace names:

  • All module documentation pages should be located under Documentation/Nightly/Modules
  • All extension documentation pages should be located under Documentation/Nightly/Extensions


For example, if an an extension named DoSomethingGreat bundles three modules ModuleA, ModuleB and ModuleC. The following pages should be created:

  • Documentation/Nightly/Extensions/DoSomethingGreat
  • Documentation/Nightly/Modules/ModuleA
  • Documentation/Nightly/Modules/ModuleB
  • Documentation/Nightly/Modules/ModuleC


In case your extension bundles only one module, the extension name is expected to match the module name. For example, if your extension is named DoSomethingAwesome, the associated module is expected to be named DoSomethingAwesome. The following pages will then be created:

  • Documentation/Nightly/Extensions/DoSomethingAwesome
  • Documentation/Nightly/Modules/DoSomethingAwesome

where page Extensions/DoSomethingAwesome redirect to page Modules/DoSomethingAwesome.


To setup a redirection, simply add the following text to page Extensions/DoSomethingAwesome: 

#REDIRECT [[Documentation/Nightly/Modules/DoSomethingAwesome]]

For an example, see here

More details about redirection are available here: http://www.mediawiki.org/wiki/Help:Redirects


Which URL should be associated with EXTENSION_HOMEPAGE metadata ?

Extensions available through the Slicer Extensions Catalog are expected to have a page created under the Nightly documentation namespace. The corresponding URL should be associated with the EXTENSION_HOMEPAGE metadata.

For example:

  • set(EXTENSION_HOMEPAGE "http://slicer.org/wiki/Documentation/Nightly/Extensions/DoSomethingGreat")
  • set(EXTENSION_HOMEPAGE "http://slicer.org/wiki/Documentation/Nightly/Extensions/DoSomethingAwesome")

Note that this also apply for extension bundling only one module. Indeed, in this case the page will redirect to the appropriate module page. For example: http://www.slicer.org/wiki/Documentation/Nightly/Extensions/SkullStripper

How to rename an extension to add new features ?

If you created an extension to perform Task1, but later on, your module is getting more generic and you add some other tasks, the name of your extension might change. In order to rename, your extension, you should:

  • Remove your old extension from the ExtensionsIndex
  • Then, submit your extension again (including new features) with a new name
  • Make also sure to add redirection from the "deprecated" module documentation to the "new" pages. On the Slicer wiki, this could be using the #REDIRECT instruction.
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/4.3/Developers/FAQ&oldid=35395"