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 obtain from the downloads section on h3dapi.org. Note that the binary release for Windows contains this documentation.

MedX3D does not contain any specific haptic features.

The X3D specification for the Volume Rendering component has not yet been released so this toolkit might have to change a bit in the future. When the Volume Rendering component specification is released it is likely that the MedX3D nodes will be incorporated in H3DAPI and not released as a separate toolkit. Here is a link to a draft of the volume rendering component specification.

Installation on Windows

To install MedX3D on Windows simply download H3DViewer from http://www.h3dapi.org/modules/PDdownloads/viewcat.php?cid=28 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 http://www.h3dapi.org/modules/PDdownloads/viewcat.php?cid=14

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\vc10. 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. It might be so that the Configure button will have to be pressed again after the first configure run. 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 Visual Studio 2010. 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.

    If a user dislikes GUIs the CMake command line could be used to generate the project files. In that case navigate (in the command line) to the MedX3D\build folder and on a standard installation of CMake 2.6 write:
    C:\Program Files\CMake 2.6\bin\cmake.exe
    The project files will then be generated in MedX3D\build folder.
  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\bin. 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. To use MedX3DDemo do the following.
    Change folder to MedX3D/demo/build.
    cmake .
    make
    Run program by writing
    ./MedX3DDemo

Installation on Mac OS

MedX3D builds and MedX3Demo builds and runs on Mac OS however, there seem to be something odd with the drivers for the glsl shading language so there will be no good visual output. Therefore there are no explicit build instructions for Mac OS. 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. NOTE: I am not sure that this is true anymore. Please test H3DViewer bundle or build it yourself and test.

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

Screen shot from MedX3DDemo
Enlarge
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
    • Open volume image file - Open any file supported by MedX3D with the exception of RAW.
    • Open DICOM files - Select one DICOM file and all files in the same folder with similar name will be opened to construct the volume.
    • Open RAW file - 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.
    • 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.
    • Close file - Close previously opened file(s).
    • Exit - Exit program.
  • VolumeStyle - Options for which style should be used and how they should change.
    • No Style - No style corresponds to OpacityMapVolumeStyle with default values.
    • OpacityMap - Select OpacityMapVolumeStyle
    • ISOSurface - Select ISOSurfaceVolumeStyle
    • Shaded - Select ShadedVolumeStyle
    • Tone mapped - Select ToneMappedVolumeStyle
    • Edge enhancement - Select EdgeEnhancementVolumeStyle
    • Boundary enhancement - Select BoundaryEnhancementVolumeStyle
    • Silhouette enhancement - Select SilhouetteEnhancementVolumeStyle
    • Cartoon - Select CartoonVolumeStyle
    • MIP style - Select MIPVolumeStyle
    • Composed - Select ComposedVolumeStyle. Use options dialog to select which styles to composed the style of.
    • Options - Open an options dialog for the current style.
  • Navigation - Change navigation mode.
    • EXAMINE
    • WALK
    • LOOKAT
    • FLY
    • NONE
  • Advanced
    • Show Console - Show a window in which console messages and will be displayed.
  • Help
    • Help - Not used yet.
    • About - Displayed About dialog.

Simply play around with different styles and options 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"
All of the distributed examples will load the distributed data (foot128.raw) 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 1493-1505 in X3DVolumeNode.cpp to something like this:

string stylefunction_file = 
    "C:/H3D/MedX3D/src/shaders/StyleFunctions.glsl";
  fragmentshader += /*X3DVolumeNodeInternals::style_function;*/readShaderFromFile( stylefunction_file );
 
  if( useSlicing->getValue() ) {
    string main_file = 
      "C:/H3D/MedX3D/src/shaders/Slices_FS_main.glsl";
    fragmentshader += /*X3DVolumeNodeInternals::slices_fs_main;*/readShaderFromFile( main_file );
  } else {
    string main_file = 
      "C:/H3D/MedX3D/src/shaders/RayCaster_FS_main.glsl";
    fragmentshader += /*X3DVolumeNodeInternals::raycaster_fs_main;*/readShaderFromFile( main_file );
  }

To have MedX3D generate a temporary shader file composed from the three files above simply uncomment the comment which starts at line 1547 in X3DVolumeNode.cpp to look something like this:

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

Links to sites with volume data

  • www.volvis.org - Volvis is a collection of volume data files free to use. The raw file (foot128.raw) distributed with MedX3D is obtained from this site.
Personal tools
go to