MedX3D

From H3D.org

Jump to: navigation, search

Contents

Introduction

Screen shot from a volume rendered with MedX3D
Enlarge
Screen shot from a volume rendered with MedX3D

MedX3D is an implementation of Volume Rendering component of X3D.

MedX3D contains nodes for visual rendering of volume data, such as medical data from CT/MRI-scans. A correct X3D file using X3D volume rendering component nodes must specify a volume data node, a volume style node and the data for which to apply this style. The default volume renderer is implemented using a GPU-based ray caster, but as an option there is also a view-aligned 3D-textured slice rendering. The ray caster supports empty-space skipping, stochastic jittering and cubic filtering.

The existing volume data nodes are:

  • VolumeData - render one volume data set using any available style.
  • SegmentedVolumeData - allows for segmentation of the data, with a different parts rendered with separate styles.
  • ISOSurfaceVolumeData - render one or multiple iso-surfaces.

The styles to choose from are:

  • BoundaryEnhancementVolumeStyle
  • SilhouetteEnhancementVolumeStyle
  • EdgeEnhancementVolumeStyle
  • MIPVolumeStyle - maximum intensity projection rendering
  • OpacityMapVolumeStyle - use a transfer function
  • CartoonVolumeStyle - cartoon shading
  • ShadedVolumeStyle - Phong shading
  • ToneMappedVolumeStyle - tone mapped shading
  • ComposedVolumeStyle - combine several styles in succession to create more advanced visualizations.

The formats for volume data supported by the MedX3D toolkit are:

The MedX3D toolkit also contains various extra nodes not specified in the specification for the volume rendering component, such as an implementation of the Marching cubes algorithm and various nodes to extend the functionality of MedX3D. For more information about each node in MedX3D see the doxygen documentation for MedX3D. The doxygen documentation can be obtained from the documentation section on h3dapi.org. Note that the binary release for Windows contains this documentation.

MedX3D does not contain any specific haptic features.

Installation on Windows

To install MedX3D on Windows simply download H3DViewer from H3DViewer downloads MedX3D is included in this installation as a plugin binary to H3DViewer. If x3d example files are desired then use the full H3D installation package instead H3D downloads

Building from source

To build MedX3D on Windows follow these steps.

  1. Obtain the source code by using the full H3D installation package as in instructions above.
  2. Start CMake GUI. Put the search path to CMakeLists.txt in the first text box in this GUI. On a standard installation the search path is C:\H3D\MedX3D\build. Put the search path to where the generate projects will be build in the second text box, for example C:\H3D\MedX3D\build\mybuild. Press the Configure button and choose the compiler for which CMake will generate build files. Then wait while CMake tries to detect what libraries are installed on your system. If everything went fine then the "OK" button should light up and when it is pressed the project files will be generated. If CMake could not find all libraries then these paths can be manually specified. All such paths are advanced variables so the "show advanced" checkbox must be active.
    All libraries needed for building MedX3D with support loading image data from DICOM files are included in the distribution, note that the libraries might only link against a specific version of Visual Studio. If DICOM is wanted for other versions of Visual Studio the only CMake variable needed to be set is DCMTK_DIR, the other DCMTK_-variables will be filled in with the correct location if they were empty prior to setting DCMTK_DIR.
  3. Open the projects and start building. When generating project files for Microsoft Visual Studio the project file to open is the solution file generated.
  4. When the MedX3D library finished building build the INSTALL project once. This will copy library files and binary files to a bin and lib folder in the location set by CMAKE_INSTALL_PREFIX. The value of this variable can be seen in the CMake GUI. On a default installation this will be C:\H3D\MedX3D\bin64. This default location is the location in which the provided examples and the CMakeLists.txt for other project depending on MedX3D will look for the binaries for MedX3D.
  5. To generate MedX3DDemo use the CMake GUI again and check the option named MedX3D_Demo_PROJECT

Installation on GNU/Linux

Currently you might need to build MedX3D on Linux yourself. To build MedX3D on Linux follow these steps.

  1. Build and install H3DAPI.
  2. If you did not use the debian packages then download the source for MedX3D.
  3. To generate the make files use the terminal and change folder to the MedX3D/build folder and write:
    cmake .

    To build MedX3D write: (tip: write "make -j3" if you have a core duo, and "make -j5" for quads: faster)
    make

    To install MedX3D write:
    sudo make install

    MedX3D header and libraries are now installed on your system. But there is no application installed that use MedX3D libraries.
  4. There is one application provided that depends on MedX3D. This application is called MedX3DDemo and is included by default if the H3D version is later than 2.3. Otherwise you might have to build it yourself by doing the following:
    Change folder to MedX3D/demo/build.
    cmake .
    make
  5. Run MedX3DDemo by writing
    ./MedX3DDemo

Installation on Mac OS

MedX3D builds and MedX3Demo builds and runs on Mac OS if the graphics drivers support the glsl shading language properly. If a build on Mac OS is desired a similar procedure as for GNU/Linux can be used provided that the gnu compiler is used. Also consider using macports to just install the medx3d library.

Using MedX3D

This section will explain how to use MedX3D. A short explanation of the different parts of MedX3DDemo and then information about how to use and perhaps change the example X3D files provided with MedX3D.

MedX3DDemo

Old screen shot from MedX3DDemo
Enlarge
Old screen shot from MedX3DDemo

MedX3DDemo is an example application that lets the user load some volume data and explore it by choosing a render style and setting the properties of the styles.

When MedX3DDemo is started it will display a window in which to render a 3D-scene and some menus. Here follows a listing of the different menu items.

  • File
    • Load volume data - Open any file supported by MedX3D with the exception of RAW.
    • Load raw data - Open a file in the RAW format. After the file has been selected some additional parameters must be specified in order to load the RAW file.
    • Quit - Exit program.
  • Windows
    • Render Options - Opens a dialog with various options on how to perform the rendering such as ray step for ray casting or if slice based rendering is needed. Also contains an option to change the background color in the scene.
    • Console - Show a Console window that can be used for debugging issues.

Simply play around with different styles and options in the "Render Options" dialog to visually explore the loaded data.

A typical MedX3D x3d-file

MedX3D is distributed with a couple of example x3d files. These files might be the easiest way to figure out how to specify scene using the MedX3D nodes. Each one of the example x3d files can be loaded with H3DLoad through a terminal by navigating to the MedX3D folder and typing:
H3DLoad "x3d/nameoffile.x3d"
Most of the distributed examples will load the distributed data (foot.nrrd) by default.

It might be good to know the x3d-syntax for how to load volume data from a file. Volume data in MedX3D is specified as an X3DTexture3DNode and should be put in the voxels field of a node that is a subclass of X3DVolumeNode in use, for example a VolumeData node. For most files it is enough to simply use the Image3DTextureNode and specify an url to the file since MedX3D will find the appropriate image loader and load the file:

<VolumeData>
<Image3DTexture url="pathtofile"/>
</VolumeData>
 

In some cases though the loader to use has to be specified since there might exist properties that are needed to be set in order to load the file correctly. An example of file for which this is needed are files in the raw format. The x3d-code to load a raw-file could look like this:

<VolumeData>
  <Image3DTexture containerField="voxels"
                  url="data/foot128.raw">
    <RawImageLoader width="128"
                    height="128"
                    depth="128"
                    bitsPerPixel="8"
                    pixelType="LUMINANCE"
                    pixelComponentType="UNSIGNED"
                    pixelSize="0.01 0.01 0.01" />
  </Image3DTexture>
</VolumeData>

Tweaking MedX3D

This section is only important for users planning to extend MedX3D or change the source code.

Adding new nodes to MedX3D is just like adding new nodes to H3DAPI. Figure out which node class to inherit from, specify fields and a database object and add fields to the database. Figure out which virtual functions to override in order to get the needed functionality. Since MedX3D is built on the glsl shading language it is more or less required to know this to tweak/extend MedX3D.

One important thing to know when playing around with the shader functionality is that the shader strings are hardcoded in MedX3D. It is however possible to use the distributed shader files instead (in order to avoid the edit/compile/link cycle of C++ which might be slow). To do this simply edit lines in RayCaster.cpp or MultiVolumeRayCaster.cpp to something like this:

string stylefunction_file = 
    "C:/H3D/MedX3D/src/shaders/StyleFunctions.glsl";
fragmentshader += readShaderFromFile( stylefunction_file );
 
string main_file = 
    "C:/H3D/MedX3D/src/shaders/RayCaster_FS_main.glsl";
fragmentshader += readShaderFromFile( main_file );

To have MedX3D generate a temporary shader file composed from the three files above simply uncomment a comment in RayCaster.cpp or MultiVolumeRayCaster.cpp to look something like this:

string saveshaderfile = 
    "c:/tmp" + getName() +".glsl";
  writeShaderToFile( fragmentShaderString->getValue()[0], 
         saveshaderfile );

Links to sites with volume data

  • medvis.org - MedVis describes links to sites with volume data files free to use. The raw file (foot128.raw) distributed with MedX3D is obtained from volvis.org linked to by this site.
Personal tools
go to