CIBC:ImageVis3D

From NCRR Biomedical Software Development, Engineering, and Dissemination Wiki

(Redirected from CIBC:Project:ImageVis3D)

Main CIBC Page
Looking for the old ImageVis3D design page?

Motivation and Overview

The goal of ImageVis3D development is to initially replicate the capabilities of the BioImage powerapp and then expand it capabilities to include all the functionality currently within SCIRun for visualizing three-dimensional rasterized data. The program is another light weight application in the same vein as Seg3D and map3d and provides the user with streamlined access to the extensive volume visualization capabilities available from tools developed within the SCI Institute and the NCRR CIBC.

Getting ImageVis3D

Download the binary

Download milestone releases or the latest build and simply run it. ImageVis3D is generally distributed with all required prerequisites.

Visual C++ Redist error message on Windows systems

For DirectX functionality you also may need to update your DirectX subsystem via this tool.

In addition to the main ImageVis3D program, we also provide a command line tool that allows you to convert your data into ImageVis3D's internal `UVF' format and vice-versa. You can download this UVFConverter via the devbuilds site; it will be provided in the next release of ImageVis3D, but there is no official documentation as of yet (just run it with '--help' for now).

In rare instances, Windows users might need to download the Microsoft C++ runtime redistributables (VS2008SP1 redist x86, VS2008SP1 redist x64). If you run the 32bit version of ImageVis3D on a 64bit machine (not recommended), you'll need the 32bit runtime. Unless you see the error depicted on the right, this is not required.

Compile it Yourself

Assuming that you already have Qt 4.5 or newer on your machine all you have to do to compile ImageVis3D is:

svn co https://gforge.sci.utah.edu/svn/imagevis3d
qmake -recursive
make

If you do not have Qt installed yet, we provide some scripts to aid you in the process.

Windows-only Caveats

note: Recent changes to Qt's static build means that we can support 4.6 and earlier or 4.7. We have chosen to only support Qt 4.7 and later on Windows. You are welcome to hack things to work with 4.6, but you're on your own!

double-note: Visual Studio 2010 is untested at this time. It may work, it may not; we do not officially support it at present.

If you want to use the visual studio project files on windows you need to set the environment variables QTDIR32 and QTDIR64 (only if you want to compile a 64 bit build) to point to your Qt installation directories. ImageVis3D uses the 'tr1' extensions to C++. This means that you must download and install the Microsoft Visual Studio 2008 Service Pack 1 as well as Microsoft Visual Studio 2008 Feature Pack on when compiling with Microsoft Visual Studio 2008.

Do note that we do not currently support building via the binaries / Qt SDK supplied by Qt software. You must build Qt from source yourself. This restriction is somewhat relaxed on Linux, where distribution-supplied Qt installations tend to be acceptable (make sure you install "-dev" packages!).

Experimental 64-bit Mac Builds

We do not yet distribute 64-bit binaries on Apple platforms. We have internal builds for this platform, but we don't feel they meet the quality of other builds, and so we are not distributing binaries at this time. You can, however, build ImageVis3D yourself if you desperately need 64-bit support; this section shows you how.

The mile-high view is that you need a 64-bit, Cocoa-backed Qt. Then you need to apply a few changes to the .pro files in the ImageVis3D tree. Finally you need to invoke the correct qmake, and then build. Since you are building manually, when you're done you probably want to run the Scripts/mk_app.sh script manually, to create a full-fledged Apple "bundle".

There are two paths for your Qt install. The first is to use a Qt/Cocoa binary. The ImageVis3D developers have never used such binaries and have no idea if this path will work. The second is to compile Qt from source manually.

Compiling Qt from source can be a nightmare, but we provide a script that should get you past the heavy lifting, if not do everything for you. Earlier in this section we linked to a script to build Qt statically, but Qt/Cocoa must be built as a dynamic framework. We supply another script for building Qt in this manner. To compile Qt, download the script, edit it in a text editor to make sure it grabs the Qt version you want, as well as changing the argument to 'arch' from 'x86' to 'x86_64'. Finally, run 'sh Mac-DynamicQt-Cocoa.sh' in your shell to perform the compilation. This will take 10 to 20 minutes on your average Core 2 Duo iMac.

After you've got Qt installed, the process should be the same regardless of which method you chose for installation.

Download the ImageVis3D source tree out of its version control repository.
Edit ImageVis3D/ImageVis3D.pro, Tuvok/Tuvok.pro, UVFReader/UVFReader.pro and CmdLineConverter/CmdLineConverter.pro in a text editor. Make sure QT_MAC_USE_COCOA equals 1.
Run qmake -recursive, making sure it invokes the 64-bit Qt/Cocoa qmake that you just installed (you might have multiple versions on your system!).
- This should print out some messages about doing a "shared build". If it prints our messages about a "static build", then you're either using the wrong qmake or you compiled Qt with the wrong options.
make
sh Scripts/mk_app.sh

You can verify you've got a 64-bit executable using the 'file' command:

file Build/ImageVis3D.app/Contents/MacOS/ImageVis3D

should tell you that the file is a 'Mach-O 64-bit executable x86_64'. If it says 32-bit or just x86, then you've built a 32-bit binary.

Finally, you can start this version of ImageVis3D using 'open Build/ImageVis3D.app'.

If you experience inexplicable GL errors, you'll need our special version of GLEW. This is not yet committed to the ImageVis3D tree; for now, please just ask about this on the tuvok-developers mailing list.

ImageVis3D Mobile

ImageVis3D Mobile is a mobile volume rendering application that allows you visualize and share your data while you are on the go. With ImageVis3D and ImageVis3D Mobile you can transfer your data directly from the desktop to your mobile device. ImageVis3D currently supports all iPod touches and iPhones (including the new iPhone 3Gs). Download the application via the Apple App Store or request a pre-release from the ImageVis3D team. More information and a quick start guide are available on a dedicated page.

Importing Data

The most commonly asked question we get is, "How can I import my data into ImageVis3D?". Every now and again, people also ask us about our custom file format, UVF, why it exists, and if they can use or read such data in other tools.

All of these questions and more are answered in a fairly comprehensive Getting Data into ImageVis3D document.

If you have further questions, please contact us on one of the mailing lists mentioned below!

Sample Datasets

Some sample datasets are now available from the ImageVis3D download page.

Join the Community

ImageVis3D is actively developed, open source software provided under the terms of the MIT license. Most discussion about new features and development happens via a set of mailing lists. These are:

iv3d-users, where release announcements are made and general user inquiries should be done. We greatly enjoy getting feedback via this list!
tuvok-developers is where development discussion should happen. If you are writing code for ImageVis3D, you should be subscribed to this list.
iv3d-develop, for SCI-related ImageVis3D development. This is how we organize meetings at SCI, discuss what features we'd like to announce for grant requests, and so forth. The mailing list is open access and we do not discourage subscription, but we expect those without a SCI affiliation will find these discussions irrelevant.

The ImageVis3D developers have developed some terminology which are frequently used in the context of ImageVis3D-related activities. A dictionary for these terms:

"iv3d"/"IV3D"/"ImageVis"/"ImgVis": ImageVis3D
"Tuvok"/"TUVOK": The Ultimate VOlume (rendering) Kit -- the renderer that powers ImageVis3D.
"UVF": ImageVis3D's custom file format, which enables fast access to multiresolution data.
"scio"/"SCIO"/"the io layer/subsystem": An independent library handling conversion from various data formats to UVF.

Report Issues

For non-fatal issues (those that don't cause ImageVis3D to crash), please use the `Help | Report an Issue' dialog within ImageVis3D itself. This causes additional debugging information which is useful for ImageVis3D developers to be sent along with your bug report. Further, if the issue is dataset specific, you can upload your dataset easily via this mechanism.

We track bugs using the Launchpad service. If you use ImageVis3D's builtin bug reporter, it will typically end up as a bug report on Launchpad. You can create a launchpad account to be able to subscribe to bugs and receive email when a related issue comes up, but this is not required.

For all other issues, we ask that you subscribe to the iv3d-users mailing list and post any problems you run into there.

Using ImageVis3D

Manual

ImageVis3D comes with an extensive manual.

Video Tutorials

A series of video tutorials are available which visually describe how to use ImageVis3D. You can find them at the bottom of the main ImageVis3D web site.