 |
|
| www.slicer.org | Slicer Wiki pages |
This Developer's Guide presents the steps for adding a new module, compiling the VTK source, and creating documentation.
Slicer is easily extendable due to its modular structure. Each module automatically gets its own panel in the Slicer GUI, which the developer then fleshes out to create its own user interface. Since Slicer is built on VTK, the Visualization Toolkit, modules have access to a wide range of visualization capabilities.
The source code of Slicer can be divided into two main parts: Tcl/Tk modules and C++ code that extends VTK. Modules are written directly in Tcl/Tk. C++ code is wrapped in Tcl when VTK is compiled.
Slicer includes several different types of files, stored in different locations.
The Slicer core Tcl source files are in 3 subdirectories of the slicer2/Base/tcl directory, depending upon their use.
| Tcl Source Files |
|---|
|
slicer2/Base/tcl/tcl-main
These are the files Slicer must have to run.
|
|
slicer2/Base/tcl/tcl-modules
These files are optional, and each one implements a specific function
in Slicer. These Tcl files are called modules.
|
|
slicer2/Base/tcl/tcl-shared
These files implement functionality that multiple modules may share.
For example, generally helpful procedures or new widgets are here.
|
VTK classes that are part of the core of Slicer are in the slicer2/Base/cxx directory.
| C++ Source Files |
|---|
|
slicer2/Base/cxx
These are the classes that Slicer adds to VTK.
The VTK classes are compiled outside the source tree, in the slicer2/Base/builds/[os-name] subdirectory. |
| Build Files |
|---|
|
slicer2/Base/builds/[os-name]
cmake generated files are at this level. |
|
slicer2/Base/builds/[os-name]/bin
Once built, the shared library files are placed here.
|
|
slicer2/Base/builds/[os-name]/cxx
The generated, Tcl-wrapped, cxx files are placed here, as well as compiled object files.
|
We are migrating towards a more independent module structure, populating the slicer2/Modules directory. New modules are added by creating a directory with a name that starts with vtk, such as vtkCustomModule. Full instructions, and an automated script, for adding a new module can be found in that subdirectory.
In each module, there is a tcl subdirectory in which you can place the Tcl files associated with your module. There is also a cxx directory, similar to the Slicer core cxx directory.
| Module Source Files |
|---|
|
slicer2/Modules/vtkCustomModule/cxx
These are the VTK classes that the Custom Module adds to Slicer.
|
|
slicer2/Modules/vtkCustomModule/tcl
Tcl files that implement the GUI and functionality of the module.
|
|
slicer2/Modules/vtkCustomModule/builds/[os-name]
Subdirectories are created for each OS on which you are going to build the C++ classes, for example,
solaris8. |
Scripts to run Slicer and perform useful functions
are in the slicer2/Scripts directory.
| Shell Scripts |
|---|
|
slicer2/Scripts
Useful shell scripts. Read
slicer2/Scripts/README.scripts for an overview.
|
|
slicer2/Scripts/genlib.tcl
Runs
cmake and compiles C++ source code for the support libraries that are necessary for slicer to build (VTK, Insight, GSL, TCL, TK, BLT). |
|
slicer2/Scripts/cmaker.tcl
Runs
cmake and compiles C++ source code. |
|
slicer2/Scripts/tarup.tcl
Packages Slicer for distribution.
|
This website is also in the Slicer source code tree. You may generate the website and Tcl code documentation locally yourself.
| Website |
|---|
|
slicer2/Doc
This directory contains files used to generate this website.
|
|
For versions of Slicer starting with 2.0, new modules that are not
part of the main Slicer code base are added to the directory
slicer2/Modules. Instructions for building a custom module can
be found in Modules/README.modules, and sample code can be
found in slicer2/Modules/vtkCustomModule.
To ensure that the tcl files associated with the module are loaded during the GUI construction, follow the instructions in the README.txt file in the vtkCustomModule directory. If the renaming is done via the call to the vtkNameModule tcl script, your module will be registered with the Slicer base and will be initialized correctly. You must name your subdirectory in the Modules directory starting with the prefix vtk or it will not be automatically found at run time nor during auto compilation via the cmaker.tcl script.
New core modules are added to the code base in the directory
All files in the
To allow multiple users to develop their own modules on UNIX systems,
Slicer will preferentially source modules in any local |
Easy Development Tip |
| release-2-6 | Slicer-2-6 | Slicer-2-6 | core-8-4-6 | core-8-4-6 | itcl-3-2-1 | iwidgets-4-0-1 (win32: 4-0-2) | blt24z | REMOVED | CMake-2-0-6 | Teem-1-9-0 | Slicer-2-6 |
| release-2-5-patches | VTK-Slicer-2-5 | ITK-Slicer-2-5 | core-8-4-6 | core-8-4-6 | itcl-3-2-1 | iwidgets-4-0-1 | blt24z | release-1-4 | CMake-2-0-6 | ||
| release-2-4-patches | Slicer-2-4 | Slicer-2-4 | core-8-4-6 | core-8-4-6 | itcl-3-2-1 | iwidgets-4-0-1 | blt24z | release-1-4 | CMake-2-0-1 | ||
| 2.3 | release-4-2-3 | ITK-1-6 | |||||||||
| release-2_1_0-06_09_2003-patches | release-4-2-2 | ITK-1-4 | |||||||||
| 2.0: CVS co -D "2002-5-4" | release-4-0 | Release-1-6-0 | |||||||||
| release-1_3_1-06_30_2002-patches | |||||||||||
| release-1_2_3-02_25_2002 | release-3-2 | ||||||||||
| release-1_2_2-05_30_2001 | release-3-1 | ||||||||||
| slicer1_0_0_release-bugfixes | release-3-1 |
Slicer 2.5.x uses the VTK code that has been tagged in their repository with VTK-Slicer-2-5. We're using the ITK tagged version ITK-Slicer-2-5. You can examine the script
Slicer 2.4.x uses the VTK code that has been tagged in their repository with Slicer-2-4. We're also using the ITK tagged version Slicer-2-4. You can examine the script
In December 2003, we standardized our CVS repository of
Slicer version 2.1 has been compiled with
VTK 4.2.2,
and Slicer version 2.0 was compiled with
VTK 4.0.
Make sure that you have a recent (> 1.6) release of CMake as well.
This point marks a break in the release structure, as both VTK and Slicer moved to new CVS
directories.
Slicer can be checked out with the same CVS
The 1.3.* versions of Slicer that can be obtained through the ftp site work with
VTK 3.2,
available via Kitware's CVS server, via the tag release-3-2. This Slicer version was built from
the Slicer source code in SPL's CVS repository tagged with release-1_2_3-02_25_2002.
If you are working in the SPL at Brigham and Women's, there are a few compiled versions on the Solaris system to which you have access:
This section details how to build your own development version of Slicer. You can also use it if you wish to run a version from the CVS repository. It details what support libraries that you need to install first, how to get the Slicer code from CVS, and how to build it all.
The build process that the developers use assumes that third-party sources (Tcl and VTK) are built in subdirectories of You can also refer to the alternate instructions for Building Slicer 2.6 if you wish to build the release from sources.
You need some software on your machine before starting.
On Solaris especially, you must build VTK (and ITK) against the same version of Tcl that you will be
using to run Slicer. Tcl, VTK, and Slicer must all be compiled with the same compiler.
The classes that Slicer adds to VTK are found in the directory
cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer login
Then execute:
slicer2/Scripts/genlib.tcl
Then execute:
slicer2/Scripts/cmaker.tcl
The
cd ${SLICER_HOME}/Base/tests
SLICER_HOME /path_to_slicer2/slicer2
cd ${SLICER_HOME}/Base/tests
This section is under construction.
This involves adding Tcl files to the Editor subdirectory of
Also, a
The script
These comments are used to generate documentation for this website.
See the link Tcl Source Code in the Developer's Guide.
The comment headers can be written in pseudo-html.
See
The script You can obtain anonymous read only access to the CVS repository as follows:
cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer login Respond with the password slicer2/slicer_variables.tcl where we define the repository tags for all of the support libraries that we compile against.
slicer2/Scripts/genlib.tcl where we define the repository tags for all of the support libraries that we compile against.
slicer2 to
VTK 4.2.3,
because the CVS version of VTK
is currently changing rapidly in the time up to the release of VTK 5.0. Intermediate Slicer development versions 2.3 have been compiled with VTK 4.2.3.
pserver as previous versions, but the checkout
command must be given the argument slicer2 instead of slicer.
VTK changed their CVS pserver to use
uppercase VTK instead of vtk, and VTK must be passed to the checkout command instead of vtk,
in order to access versions 4.0 and above.
The 1.2.2 version on the ftp site works with
VTK 3.1, which
Kitware no longer distributes as a package, but can be obtained through CVS via the tag release-3-1.
/spl/os/bin/slicer24 is the 2.4.1 release version of the Slicer code that includes the vtkAG module for internal use (it will appear in the next public release). We are currently supporting and developing against this version.
/local/bin/slicer2 is the 2.1 release version of the Slicer code.
/projects/birn/slicer2/slicer2* are previous and current release versions.
slicer-old is ancient, and holds the original code by Dave Gering and Peter Everett. This has been
superseded by slicer2, as their code has been incorporated into the latest release.
/local/bin/slicer-stable is a stable version of slicer1.*. It runs with VTK 3.1.
/local/bin/slicer was for general use/beta testing. It runs with VTK 3.2.
/local/bin/slicer-nightly was for alpha testing new modules.
5. Build Slicer
These instructions were originally written for UNIX/Linux machines. Windows requires a similar setup if you are using cygwin, which provides a UNIX-like command prompt. slicer2/Lib/[osname]. This procedure assumes that arrangement.1. Set Up
After you check out the Slicer code from CVS first, run the tcl script found in slicer2/Scripts/genlib.tcl and it will build the support software for you (assuming you have a compiler and a cvs client available).
On Solaris, we use g++, which is available free from http://gcc.gnu.org/.
On Windows, we use Microsoft Developer Studio, version 6 or 7. (Version 7 is also called .NET). You can obtain the C++ compiler separately, if you prefer.
cvs
A standard UNIX environment will supply this.
On Windows, you will need cygwin. You can download it from http://sources.redhat.com/cygwin/. Install everything on the options list, if possible, but be sure to get cvs, zip, curl, svn.
For Windows, chances are good that the precompiled binaries were compiled with Microsoft Visual Studio, though there may be version issues.
slicer2/Base/cxx.
2. Get Slicer2
You will need to check the source code out from CVS in order to get the latest version. In an xterm or a cygwin window, do the following:
The password for the anonymous (read only) account is
cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer checkout slicer2bwhspl. Replace anonymous with your user name if you have a CVS account.
If, under cygwin, you have problems logging into the CVS server because your cvspass
file couldn't be found, set your HOME variable to the path to your cygwin home directory and
use the tcsh shell instead of bash.
3. Compile the Support Libraries
We have provided a convenient script to allow one step configuring and building of Slicer's support libraries. slicer2/Scripts/genlib.tcl contains the commands to download and build Tcl/Tk, VTK, ITK, etc. genlib.tcl sources the slicer2/slicer_variables.tcl file, which sets up the environment variables needed for the compilation. For Windows, you will need to point the COMPILER variable to the MS Visual Studio compiler, cl.exe. Slicer will pick up the Tcl settings from VTK.
This will configure and build the support libraries needed before you can build Slicer.
4. Compile Slicer2
We have provided a convenient script to allow one step configuring and building of Slicer.
slicer2/Scripts/cmaker.tcl contains the commands to set up cmake and then start the compilation after cmake generates your make files. cmaker.tcl sources the slicer2/slicer_variables.tcl file, which sets up the environment variables needed for the compilation (and run) step.
For Windows, you will need to point the COMPILER variable to the MS Visual Studio compiler, cl.exe, if you have not already done so.
This will configure and build the Slicer core against the version of VTK that slicer_variables.tcl supplies. It will also compile the distributed Modules in the slicer2/Modules subdirectory and any others that you specify (see Adding a Module for more details). Slicer inherits CMake settings from VTK, which inherits some CMake settings from Tcl, which is why all three must be compiled with the same compiler.
5. Running Slicer
If you installed the support packages in slicer2/Lib or built them using the genlib.tcl script, you shouldn't need to make any changes to slicer2/slicer_variables.tcl, otherwise edit it to reflect your local setup. slicer2/slicer2-[os]-[arch] executables from cvs will read in launch.tcl
and bootstrap Slicer. (NOTE: There is no need to run Scripts/make-launchers.tcl since most of
the launch process is now in launch.tcl and cvs has the pre-made launchers.) Execute the file labeled for your operating system to start Slicer.
6. Running Tests of the slicer code
You need to have downloaded VTK4 data from http://prdownloads.sourceforge.net/vtk/VTKData-4.2.tar.gz?download. Then set the environment variable VTK_DATA_ROOT to point to where you installed it.
The launch.tcl script will accept a path to a Tcl script to execute, instead of the Slicer user interface. You can call it via:
You can also run the tests from VTK.
Set the following environment variables appropriately, as they are set automatically in the
../../slicer-[os]-[arch] ./TestImageCloseUp2D.tcl
slicer2 launching script, but we by-pass that script for the test:
To run
TCL_LIBRARY /path_to_lib/tcl8.4
TK_LIBRARY /path_to_lib/tk8.4
VTK_DATA_ROOT /projects/VTKData/
LD_LIBRARY_PATH ${SLICER_HOME}/Base/builds/[my-os]/bin:${LD_LIBRARY_PATH}
TCLLIBPATH "${SLICER_HOME}/Base/Wrapping/Tcl/vtkSlicerBase /usr/local/src/vtk4/VTK/Wrapping/Tcl"
TestImageCloseUp2D.tcl, for example, do the following:
vtk TestImageCloseUp2D.tcl
6. Adding Editor Effects
tcl-modules.
Look at the interaction between tcl-modules/Editor.tcl and one of the
Editor modules, such as tcl-modules/Editor/EdDraw.tcl.vtkImageEditorEffects VTK object (from the vtksrc directory) is
used to apply the pipeline for each effect.
7. Commenting Source Code
slicer2/Scripts/comment.tcl will automatically place
comment headers above all procedures in all Tcl source code files.
Please run this script regularly, and then place descriptions of the procedures
in the comment headers.
(This script also places the copyright in all files, including those in the Base/cxx directory.)slicer2/Base/tcl/tcl-main/Comment.tcl for an example.
8. Generating Documentation
slicer2/Scripts/document.tcl will automatically generate the html pages that make up
this website. It uses the information recorded in slicer2/slicer_variables.tcl. Read it for information on how to add to the website or to generate your own local copy.
9. Helpful Links
Here are links to useful information for developers:
10. Source code access via CVS
bwhspl.
cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer co slicer2
To request write access to the repository, please fill out this form: SendPassword.
Please be aware, that according to the software license that applies
to the Slicer code, that the copyright of code contributed to the cvs
repository is signed over to the copyright holder of Slicer. Please
see the
Software License Agreement
for further details, as it also applies to the source code, not just
the distributed versions.
Access to the web interface to CVS is available via the following URL: http://www.na-mic.org/ViewVC/index.cgi/slicer2/?root=Slicer2
To subscribe to the developer mailing list, send mail to slicer-devel-request@massmail.spl.harvard.edu with the word subscribe as the subject.
The address of the mailing list itself is slicer-devel@massmail.spl.harvard.edu.
The web interface can be accessed through http://massmail.spl.harvard.edu/mailman/listinfo/slicer-devel.
When adding new pages to the web site, you can refer to the document template.
The comments inserted into the Tcl files by the comment script and filled in by the developers are extracted from the Tcl files and collected into a documentation page.
The Slicer project follows the coding style set out by KitWare for use with their VTK project. Coding standards for VTK classes.
The comments placed in the VTK source code according to the doxygen standard will be extracted from the VTK files and collected into a documentation page when the document script is run.
This will produce the Base documentation page as well as Module documentation pages.
1.) How to update the content at www.slicer.org -------------------------------------------------------------------------- The website is hosted on the web server at the Surgical Planning Lab. Run this script: /projects/birn/slicer2/updateslicerweb which does this (order matters): cd /projects/birn/slicer2/slicerweb cvs update -d echo "Updating slicer2-web" cd /projects/birn/slicer2/slicer2-web cvs update -d echo "Calling slicer2-web/Scripts/document.tcl" cd Scripts ./document.tcl The call to cvs update in /projects/birn/slicer2/slicerweb is to ensure that all needed directories have been created before the documentation is generated. The SLICER_DOC environment variable is set to /projects/birn/slicer2/slicerweb in the document script so that when the document script is run, it will place the output html pages in the directories that the web server displays to the rest of the world. 2.) How To Restart the web server: -------------------------------------------------------------------------- If there are problems with the pages being served, send an email to help@bwh.harvard.edu detailing the symptoms. The virtual hosting file is located here: /projects/web/support/apache-common/conf/vhosts/slicer.conf Namesdirect.com provides the redirection service, Steve Pieper at pieper@bwh.harvard.edu holds the account password for slicer.org. 3.) How To View the error log -------------------------------------------------------------------------- The error log is recorded here: /projects/web/support/apache-common/log/slicerweb/error_log