A Tutorial Introduction to the MNI-ray_trace Software
David MacDonald (david@bic.mni.mcgill.ca)
- Introduction
- How to Run MNI-ray_trace
- Data for this Tutorial
- Example 1: Making a Slice Image
- Example 2: Setting the Image Size
- Example 3: Setting the Background
- Example 4: Setting the Over/Under
- Example 5: Cropping the Image
- Example 6: Displaying Tags on a Slice
- Example 7: Using Lighting
- Example 8: Superimposing PET on MRI
- Example 9: Superimposing PET on MRI with Transparency
- Example 10: Displaying Surfaces
- Example 11: Choosing View Orientation
- Example 12: Colouring Surfaces with Volumes
- Example 13: Defining Lights
- Example 14: Cross sections of Surfaces Superimposed on a Slice
- Example 15: Supersampling
Introduction
The MNI-ray_trace is a set of software used to render high-quality images for publication and animation, and represents an alternative to using MNI-Display and MNI-register to create neuroanatomical images. The reasons to use MNI-ray_trace over the other two programs include:
- Reproducibility : using script files allows images to be easily regenerated or modified, and
- Image Quality : the use of partial transparency, super-sampling, and other features create better images.
What follows is a tutorial consisting of examples, starting with the simpler cases and progressing to more complicated examples.
How to Run MNI-ray_trace
All the executables listed in this tutorial reside in the directory ~david/public_bin. The list of programs used include:
- ~david/public_bin/ray_trace : the ray trace program
- ~david/public_bin/make_slice : creates a slice object
Data for this Tutorial
The following data are used for the examples in this tutorial.
- a T1-weighted Minc volume : /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc
- a cortical surface : /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz
- a set of tags : tags.tag which contains the following:
- MNI Tag Point File
Volumes = 1;
- MNI Tag Point File
Points =
-30 -52 64 “Marker”
-30 15 58 “Marker”
-30 -14 28 “Marker”;
Example 1: Making a Slice Image
First a rectangle is created using the make_slice program, then the ray tracer is invoked with the rectangle following the Minc file colour coding arguments on the command line. Note that the -nolight argument must precede the slice.obj argument in order to have the desired effect of not using lighting equations to render the colours of the slice. Instead of -hot , one can use -gray , -spectral , -red , -green , -blue , -colour , or -usercc .
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj
Example 2: Setting the Image Size
Use the -size x_size y_size option.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200
Example 3: Setting the Background Colour
Use the -bg colour option.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white
Example 4: Setting the Over/Under Colours
Use the -over colour_name and -under colour_name option. These two argument only affect subsequent colour coding arguments on the command line, in this case, the -hot … arguments.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -under blue -over green -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white
Example 5: Cropping the Image
Since the default view provides a border around the object, the -crop option is one way to remove the wasted space, by reducing the width of background to 1 pixel. Another way is to explicitly define the view yourself, described later in the tutorial.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -under blue -over green -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white -crop
Example 6: Displaying Tags on a Slice
A tag file contains points in 3 dimensional space and usually has the suffix .tag. The ray_tracer displays them as spheres. Be careful to put the tag filename on the command line before the -hot option, in order for the tags not to be colour coded by the volume. The colour and size of the tags (if the size is not in the .tag file) are specified by the -marker_size size and -marker_colour colour arguments.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -marker_size 2 -marker_colour green tags.tag -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white -crop
Example 7: Using Lighting
The -light and -nolight turn on and off lighting effects for subsequent objects on the command line. In this example, the tag points have been made larger, and use lighting, but the slice does not use lighting effects.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex1.rgb -nolight -marker_size 2 -marker_colour green tags.tag -hot 80000 500000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white -crop
Example 8: Superimposing PET on MRI
This example shows all regions of PET activation above a certain value on top of an MR image. This is accomplished by putting the -gray MR colour coding on the command line, followed by -under transparent, and finally the -spectral colouring of the PET volume.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex8.rgb -nolight -gray 80000 450000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 -under transparent -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 1 slice.obj -size 200 200 -bg white -crop
Example 9: Superimposing PET on MRI with Transparency
The last argument of the colouring coding argument indicates the opacity of the volume colours. By changing the argument: -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 1 to -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 .4 , the PET image shows a little of the underlying MR image.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/ray_trace -output ex8.rgb -nolight -gray 80000 450000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 -under transparent -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 .4 slice.obj -size 200 200 -bg white -crop
Example 10: Displaying Surfaces
Surfaces are collections of triangles constituting a 3D surface, usually in a file with a suffix of .obj. They are rendered simply by placing the filename on the command line. The default view is a 3/4 view from the posterior top left
david/public_bin/ray_trace -output ex11.rgb /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz -size 200 200 -crop
Example 11: Choosing View Orientation
Besides specifying a view orientation numerically (described later), there are 6 canonical views which may be chosen: -top , -bottom , -left , -right , -back , and -front .
david/public_bin/ray_trace -output ex11.rgb /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz -size 200 200 -crop -left
Example 12: Colouring Surfaces with Volumes
Pet activations and other volume information may be coloured onto a surface in the same way as coloured slices were created in earlier examples.
~david/public_bin/ray_trace -output ex12.rgb -under white -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 1 /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz -size 200 200 -crop -left
Example 13: Defining Lights
Lights may be defined by the use of -directional x y z r g b where x y z defines the direction the light is shining, and r g b define the three colour components of the light, with maximum values of 1. The usual is 1 1 1, which corresponds to white light.
~david/public_bin/ray_trace -output ex12.rgb -under white -spectral 40 60 /avgbrain/brain/images/mni_demo_cbf_normal_pet_tal.mnc.gz 0 1 /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz -size 200 200 -crop -left -directional 1 -1 -1 1 1 1 -directional -1 -1 -1 1 1 1
Example 14: Cross Sections of Surfaces Superimposed on a Slice
Cross sections of surfaces are created by the plane_polygon_intersection program to create lines, the set_object_colour program to set the colour, which are then rendered on top of slices.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/plane_polygon_intersect /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz lines.obj x -30
~david/public_bin/set_object_colour lines.obj lines.obj green
~david/public_bin/ray_trace -output ex14.rgb -nolight -line_width 2 lines.obj -hot 80000 450000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white -crop -right
Example 15: Supersampling
Supersampling is a method of computing the colour several times per pixel and assigning the average value. Essentially it smooths the jagged edges that often appear in images. An argument of -sup 3 requires 9 times the computation time as the default (which is -sup 1), but the results can sometimes be subtly more pleasing.
~david/public_bin/make_slice /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc slice.obj x w -30 2 2
~david/public_bin/plane_polygon_intersect /data/icbm/mri1/new_icbm/subjects/00100/surfaces/mni_icbm_00100_t1_cortex.obj.gz lines.obj x -30
~david/public_bin/set_object_colour lines.obj lines.obj green
~david/public_bin/ray_trace -output ex14.rgb -nolight -line_width 2 lines.obj -hot 80000 450000 /data/icbm/mri1/new_icbm/subjects/00100/final/mni_icbm_00100_t1_final.mnc 0 1 slice.obj -size 200 200 -bg white -crop -right -sup 3