Overview

Seg3D is a free volume segmentation and processing tool developed by the NIH Center for Integrative Biomedical Computing at the University of Utah Scientific Computing and Imaging (SCI) Institute. Seg3D combines a flexible manual segmentation interface with powerful higher-dimensional image processing and segmentation algorithms from the Insight Toolkit. Users can explore and label image volumes using volume rendering and orthogonal slice view windows.

Seg3D at a glance:

• Fully 3D interface with multiple volumes managed as layers
• Automatic segmentation integrated with manual contouring
• Volume rendering with 2D transfer function manipulation in real-time
• Image processing and segmentation from the Insight Toolkit (ITK)
• Real time display of ITK filtering output allows for computational steering
• 64-bit enabled for handling large volumes on large memory machines
• Supports many common biomedical image formats
• Open source with BSD-style license
• Cross platform: Windows, OSX, and Linux

Please see the GitHub documentation pages for up-to-date installation and build documentation.

User Documentation

Seg3D is a relatively simple-to-use segmentation program that can be used for cases where automatic segmenting programs fail. It has a strong emphasis on manual and semi-manual segmentation, where filtered data guides the user in making decent segmentations of the data. The program is mainly intended for, but is not strictly limited to, segmentation of biological/medical data.

Seg3D also serves as the start of the modeling pipeline, where BioMesh3D can be used to turn segmentations into quality meshes and SCIRun can be used to simulate biological process on the segmented images.

Tutorials

Seg3D Basic Functionality

Seg3D Tutorial

Seg3D Python examples

Developer Documentation

Build Seg3D on Windows

#twoj_fragment2-1

Build Seg3D on Mac OS X

#twoj_fragment2-2

Build Seg3D on Linux

#twoj_fragment2-3

Extend Seg3D with Plugins

#twoj_fragment2-4

Windows

Seg3D source code is hosted on GitHub.

Build Machine Requirements

To build Seg3D on Windows, you will need a 64-bit Windows machine, running Visual Studio 2013 with 64-bit compiler support. You should also have CMake 2.8 (2.8.12 recommended) installed. If building the installer using CPack, NSIS is required.

Building Qt

Besides Visual Studio you will need to install Qt. We normally build Qt from source to ensure that it is built against the same runtime redistributable libraries (deployed as private side-by-side assemblies) that are shipped with the Visual Studio SDK. These two MSDN articles: Redistributing Visual C++ Files and Choosing a Deployment Method contain very useful information about Visual Studio redistributable libraries.

Installing Qt on Your System and Building from Scratch

1. Download the open source version of Seg3D2. Qt 4.8 is recommended.
2. Qt will need to be built from the command line using Visual C++ command line tools. Troubleshooting tips can be found here.
3. Create a new directory called C:\Qt.8-64bit (or name of your choice), change into that directory and copy all the source files into it.
4. Now, run configure.exe from this new directory with the following parameters (using the -fast flag to speed up build process can be helpful too):
   configure.exe -platform win32-msvc2013 -no-gif -qt-libpng -qt-zlib -no-libmng -qt-libtiff -qt-libjpeg -no-openssl -no-phonon -no-phonon-backend -no-qt3support -D _BIND_TO_CURRENT_VCLIBS_VERSION=1 -debug-and-release -opensource
   
   You will be asked a few questions on license before configuring.
   
   
5. Now run nmake and compile all of Qt (this is a long build).

Building Seg3D

Before running CMake, you can add qmake to your System Path to automate configuring your Qt libraries in the Seg3D build:

1. In the Control Panel select System and go to Advanced Settings. Click on environment variables. Add C:\Qt.8-64bit (or directory name used) to PATH.
2. Check in the command prompt (by typing the command qmake -version) to see whether the right version is found. This will tell which version is run. If the qmake version is correct, you can proceed.
3. Download the Seg3D code and launch the visual CMake interface. Set Where is the source code text field to the Seg3D Superbuild directory and the Where to build the binaries field to the Seg3D bin directory. When setting up the project, you will be prompted for which version of Visual Studio to use. Pick Visual Studio 12 Win64.
4. Run both configure and generate. If Qt was configured correctly, everything should proceed normally and a Superbuild Visual Studio solution will be generated in the bin directory.
5. Open the project file in Visual Studio and build the Superbuild solution. To build the installer, go to bin/Seg3D build the PACKAGE target in the Seg3D solution. If building the PACKAGE target, ensure that you are building in Release mode and not in Debug mode (building the package will not work properly in Debug mode because the Debug runtime libraries are not copied).The Seg3D application will be built in the bin/Seg3D directory under Release, Debug etc. The installer, if building the PACKAGE target, will be created in the bin/Seg3D directory.
   
   

Mac OS X

Seg3D source code is hosted on GitHub.

Possible CMake Issues on OS X 10.7 (Lion)

The following warning may be seen while trying to configure a CMake project on OS X Lion:

xcode-select: Error: No Xcode folder is set. Run xcode-select -switch to set the path to the Xcode folder.

To fix the error, the following should work:

sudo /usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer/

LaTeX Documentation

Requires a LaTeX to PDF compiler for building PDF documents from LaTeX sources; we recommend MacTex.

Seg3D 2.1.5 and greater includes LaTeX documentation.

Requirements

Seg3D 2 currently builds under OS X 10.7 and higher. The CMake system was set up to run from the command line using clang and GNU make, or to use Xcode. Both versions of the build system should work. Currently the only thing not included in the source download, is a copy of Qt.

Qt

Qt 4.8 is recommended. We are currently building Seg3D2 against Qt 4.8.5 or higher.

Disk images with installers can be found here, which will contain Qt frameworks.

Advanced CMake Settings

The Seg3D build.sh script, which runs a GNU make-based build, should work for most users.

To configure the source, use the CMakeLists.txt file in the Superbuild directory and point CMake at the target directory in which the code needs to be built. If Qt was installed using the .dmg file provided at the Qt website, CMake should be able to find all the dependencies needed and will generate a the appropriate project type.

To generate an Xcode project, from the bin directory, for example:

cmake ../Superbuild -G Xcode

An Xcode based build can also be run from the build.sh script using the ‘--xcode-build’ flag, which will run the Xcode build from the command line using the xcodebuild tool.

If advanced CMake settings need to be changed, Advanced View Mode should be turned on in ccmake (CMake’s console-based application) or cmake-gui (CMake’s Qt-based GUI application).


App Bundle

The build generated by the CMake project will create a fully functional application bundle that contains all the Qt libraries inside the App bundle. This application bundle should not depend on any other software, and can be copied anywhere to run Seg3D.

The application bundle can be packaged as an installer using the package target created by CPack.

Linux

Seg3D source code is hosted on GitHub.

Linux software prerequisites can be found on this page, under the "Specifications" tab, organized by distribution.

Using the build.sh command line script supplied with Seg3D sources is recommended, or configure a GNU make project using CMake:

cd bin
cmake ../Superbuild



Following this example, the Seg3D executable will be built in bin/Seg3D.

We strongly recommend making sure that graphics drivers are up-to-date.

LaTeX Documentation

Requires a LaTeX to PDF compiler pdflatex for building PDF documents from LaTeX sources.

Qt

Qt 4.8 is recommended.

Building Qt from Source

1. Download Qt 4.8.
2. Run the configure script with the '-static' flag.
3. Configure the build for the open source version following the directions .
4. After building and installing, add the install path bin directory the PATH environment variable.

Qt from SDK

If you are using the SDK rather than vendor packages, set QT_DIR to /qt. You may also have to delete Qt configure variables (such as QT_BINARY_DIR, QT_HEADERS_DIR, QT_MKSPECS_DIR etc.) that were set during the first configure step when using the CMake console version ccmake because CMake will find Qt settings in system directories by default. Once QT_DIR is set, and any incorrect configure variables are deleted, configure again, and verify that Qt configure variables are referencing the location where the SDK is installed.

Deployment Using CPack

Source Archive

By default, CPack creates a target for generating a source archive:

make package_source

This creates compressed archives with the naming scheme -Source.tar containing all the directories and files under CMAKE_SOURCE_DIR.

Archive creation can be controlled using the following CPack options in CMake:

• CPACK_SOURCE_TBZ2
• CPACK_SOURCE_TGZ
• CPACK_SOURCE_TZ
• CPACK_SOURCE_ZIP

RPM

Turn on building RPM using CPACK_BINARY_RPM. CPack creates a target for creating a binary package:

make package

Debian Package

Turn on building Debian package using CPACK_BINARY_DEB. CPack creates a target for creating a binary package:

make package

Adding a Filter

Sample code, showing how to create a new Seg3D filter (wrapping the ITK noise image filter) as a plugin, has been saved in workshop_plugin_sources.zip. The zip file should be extracted in Seg3D 2's Plugins directory.

Plugin Architecture

When the sample plugin code (workshop_plugin_sources.zip) has been extracted in Seg3D's Plugins directory, Seg3D 2 source should resemble this image:

GUI

Each filter or tool has a GUI component, which is designed in Qt Designer. Qt Designer generates an XML file that is compiled to C++ code; this is controlled by Seg3D's CMake based build. Most of the time, the GUI is a fairly simple Qt widget. Qt Designer source can be found under Interface/ToolInterface, both in the main sources (below), or under Plugins (see above).

Wrapper files, which are also placed in Interface/ToolInterface, are required to wrap the Qt generated GUI class.

Building Seg3D 2

Simply compile the plugin code to add it to Seg3D.

Windows

Windows users will have to configure a Visual Studio project using CMake. The Windows build instructions under the Developer tab explain how to compile Seg3D from source. The NSIS requirement and packaging instructions can be ignored if an installer does not need to be built.

Mac OS X

Mac OS X can be built using the supplied build.sh script. The build.sh script can be used to generate either an Xcode project (use the --xcode-build flag) or to run a full Seg3D 2 build using GNU makefiles (the default). If a GNU makefile-based build is used, the make parallel build flag -j option is supported and can be passed to make.

Linux

The build.sh script can be used to run a full Seg3D 2 build using GNU makefiles (the default). If a GNU makefile-based build is used, the make parallel build flag -j option is supported and can be passed to make.

FAQ

Q: What are the system requirements for Seg3D?

A: If you are running Seg3D on Windows or Mac OX, you can find system requirements under the Specifications tab. If you are running Seg3D on Linux, you’ll need to build it from source. You can check the Specifications tab for platform requirements, as well as the Developer Documentation tab for build instructions.

Q: How can I migrate Seg3D 1.x sessions to Seg3D 2.x?

Seg3D 1.x session files are gzipped tar archives. The session file will typically contain a data volume (NRRD), a label file (NRRD), and an XML session descriptor file.

Just extract the all files, and then load the data volume and label files in Seg3D 2. After extracting the files, load the data volume in Seg3D 2 first, and afterward, the label file

For Linux, OS X, extract the files using tar. For example if the Seg3D 1.x session file is test_tooth.ses:

rideau:tmp aylakhan$ tar xzvf test_tooth.ses

x session.xml

x label1.nrrd

x data1.nrrd

For Windows: Seg3D sessions must be opened with tools that can open gzip files, such as the 7-zip utility, which can unpack gzipped tar archives.

Q: How can I do a quick segmentation or image viewing without creating a new project file?

A: From the original launch screen, choose the "Quick Open File" option, which allows you to open a file without creating a new project

Q: Is it possible to export segmentations to formats other than the NRRD format?

A: We support a number of file formats, including DICOM. There is limited support for exporting to Matlab because spacing and axis information is hardcoded into the file header. Supported file types can be seen in the Segmentation Export Wizard, which is located in the file type drop-down list.

Q: I'm working with a large amount of data, and Seg3D is behaving sluggishly. Are there any settings I can adjust to improve performance?

A: Try reducing or eliminating the amount of memory assigned to the Undo buffer. You can find this option in the “Preferences” window under “General/Project”.

Q: What kind of Matlab data can Seg3D read?

A: Seg3D 2.x can read 3D Matlab structs, and also has backward compatibility for 4D Matlab structs formatted for Seg3D 1.x.

Seg3D 1.x can read 3D structs, as well as 4D Matlab structs with the first dimension as a dummy dimension (size == 1). In the case of 4D structs, the first dimension is simply ignored, and the information from the remaining axes is read in as a 3D struct.

Q: How do I pan, scroll, and zoom?

A: pan: shift + left mouse button
    scroll: shift + middle mouse button
    zoom: shift + right mouse button

Support

Mailing List:

Joining the Seg3D Mailing List

1. Compose an email to This email address is being protected from spambots. You need JavaScript enabled to view it. with the following in the body of message: subscribe seg3d
2. Nothing needed in the Subject line. Just send.
3. You will receive a response from the list manager requesting confirmation. Just send back a reply message to confirm your subscription (no added text needed).
4. Finally, you will receive a welcome message confirming that you have been added to the mailing list.

Unsubscribing

1. Compose an email to This email address is being protected from spambots. You need JavaScript enabled to view it. with the following in the body of message: unsubscribe seg3d
2. Nothing needed in the Subject line. Just send.
3. You will receive a response from the list manager notifying you that the command has succeeded and you have been removed from the list.

Reporting Bugs and Features Requests

Seg3D Data