Home My Page Projects Code Snippets Project Openings diderot
Summary Activity Tracker Tasks SCM

SCM Repository

[diderot] Annotation of /branches/vis15/src/tests/examples/mip/README.md
ViewVC logotype

Annotation of /branches/vis15/src/tests/examples/mip/README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3588 - (view) (download)

1 : jhr 3588 ## mip.diderot: basic maximum intensity projection (MIP) volume rendering
2 :    
3 :     Maximum intensity projection is the minimalist volume visualization
4 :     tool. This implementation is about as short as possible; much of the code is
5 :     spent on specifying and setting up the ray geometry. It can also be adapted
6 :     (by changing a line or two) to do other kinds of projections. The code for
7 :     camera geometry and ray sampling will be re-used verbatim in other volume
8 :     rendering programs. This may later become a target for evolving Diderot to
9 :     support libraries that contain common functionality.
10 :    
11 :     Note that the explicitly pedagogical nature of this example means that some
12 :     unusual usages are required (like recompiling the program multiple times for
13 :     different datasets). In addition, the interaction loop of changing the
14 :     program parameters via command-line option, generating (on the command-line)
15 :     output images, and viewing the images, is very clumsy. Diderot supports
16 :     compiling programs to libraries, around which one can generate nicer GUIs,
17 :     but these examples are intended to be as stand-alone and minimal as possible.
18 :    
19 :     Just like [`iso2d`](../iso2d) depends on first creating a dataset with
20 :     [`fs2d-scl`](../fs2d), we need to create a volume dataset with [`fs3d-scl`](../fs3d)
21 :     in order to compile this program `mip.diderot`:
22 :    
23 :     ../fs3d/fs3d-scl -which 13 -width 3 -sz0 73 -sz1 73 -sz2 73 | unu save -f nrrd -o cube.nrrd
24 :    
25 :     In this case the volume size is chosen to ensure that the local maxima of
26 :     this -which 13 synthetic function, a cube frame with maxima at
27 :     (x,y,)=(+-1,+1,+1), are actually hit by grid sample points, which helps
28 :     reason about subsequent debugging. We can inspect the volume by tiled slicing
29 :     in `unu` to make [cube-tile.png](cube-tile.png):
30 :    
31 :     unu pad -i cube.nrrd -min 0 0 0 -max M M 79 |
32 :     unu tile -a 2 0 1 -s 10 8 |
33 :     unu quantize -b 8 -o cube-tile.png
34 :    
35 :     These examples are mainly to demonstrate Diderot, but some learning some
36 :     `unu` is a useful side-effect. Type `unu` to get a list of all `unu` commands,
37 :     and type, for example, `unu pad` to get the usage info for `unu pad`.
38 :    
39 :     We copy `cube.nrrd` to `vol.nrrd`, so that `mip.diderot` can see it in its
40 :     default location (in the current directory), we then we can compile
41 :     `mip.diderot`:
42 :    
43 :     cp cube.nrrd vol.nrrd
44 :     ../../vis12/bin/diderotc --exec mip.diderot
45 :    
46 :     And then make some MIP renderings:
47 :    
48 :     ./mip -out0 0 -camFOV 20 -rayStep 0.03 -iresU 300 -iresV 300
49 :     unu quantize -b 8 -i out.nrrd -o cube-persp.png
50 :     ./mip -out0 0 -camFOV 20 -rayStep 0.03 -iresU 300 -iresV 300 -camOrtho true
51 :     unu quantize -b 8 -i out.nrrd -o cube-ortho.png
52 :    
53 :     Make sure you can run these steps to get the same
54 :     [cube-persp.png](cube-persp.png) and [cube-ortho.png](cube-ortho.png). The
55 :     only difference in the second image is the use of orthographic instead of
56 :     perspective projection, which is apparent in the result. The `-out0 0`
57 :     initialization of the MIP accumulator is safe because `unu minmax cube.nrrd`
58 :     reports that the minimum value is 0; this avoids an extra `unu 2op exists`
59 :     step.
60 :    
61 :     The usual parameters in volume rendering can be set by command-line options.
62 :     This sampling of the various options is not exhaustive; you should try more
63 :     yourself. For the purposes of this demo we set a (shell) variable to store
64 :     repeatedly used options, which can be over-ridden later in the command-line.
65 :    
66 :     OPTS="-out0 0 -camFOV 20 -rayStep 0.03 -iresU 300 -iresV 300"
67 :     ./mip $OPTS -camAt 1 1 1; unu quantize -b 8 -i out.nrrd -o cube-111.png
68 :     ./mip $OPTS -camFOV 30; unu quantize -b 8 -i out.nrrd -o cube-wide.png
69 :     ./mip $OPTS -rayStep 0.3; unu quantize -b 8 -i out.nrrd -o cube-sparse.png
70 :     ./mip $OPTS -camFar 0; unu quantize -b 8 -i out.nrrd -o cube-farclip.png
71 :     ./mip $OPTS -camEye 7 7 7; unu quantize -b 8 -i out.nrrd -o cube-eyefar.png
72 :    
73 :     Make sure that these commands generate similar [cube-111.png](cube-111.png),
74 :     [cube-wide.png](cube-wide.png), [cube-sparse.png](cube-sparse.png),
75 :     [cube-farclip.png](cube-farclip.png), and [cube-eyefar.png](cube-eyefar.png)
76 :     for you, and also make sure that you understand why the results look the way they do.
77 :    
78 :     Aside from camera and ray parameters, we now have a basis for testing that
79 :     field reconstruction can be invariant with respect to the details of the
80 :     sampling grid. We first sample a quadratic function in a few different ways
81 :     on a very low resolution grid (which is translating and rotating across these
82 :     four datasets):
83 :    
84 :     ../fs3d/fs3d-scl -which 4 -sz0 10 -sz1 10 -sz2 10 | unu save -f nrrd -o parab0.nrrd
85 :     ../fs3d/fs3d-scl -which 4 -sz0 10 -sz1 10 -sz2 10 -angle 30 -off 0.25 0.25 0.25 | unu save -f nrrd -o parab1.nrrd
86 :     ../fs3d/fs3d-scl -which 4 -sz0 10 -sz1 10 -sz2 10 -angle 60 -off 0.05 0.50 0.50 | unu save -f nrrd -o parab2.nrrd
87 :     ../fs3d/fs3d-scl -which 4 -sz0 10 -sz1 10 -sz2 10 -angle 90 -off 0.75 0.75 0.75 | unu save -f nrrd -o parab3.nrrd
88 :    
89 :     This demo (of volume rendering with sampling grid invariance) involves a very
90 :     unusual invocation of the Diderot compiler and execution of the resulting
91 :     program, so the following steps are unfortunately rather clumsy: each
92 :     different grid orientation requires a recompilation. First, we use the
93 :     program as is, with the
94 :    
95 :     field#0(3)[] F = vol ⊛ tent;
96 :    
97 :     line **uncommented out**, and then run some sh/bash commands:
98 :    
99 :     OPTS="-out0 0 -inSphere true -camOrtho true -camEye 8 0 0 -camFOV 15 -rayStep 0.01 -iresU 300 -iresV 300"
100 :     for I in 0 1 2 3; do
101 :     echo === $I ====
102 :     cp parab${I}.nrrd vol.nrrd
103 :     ../../vis12/bin/diderotc --exec mip.diderot
104 :     ./mip $OPTS
105 :     unu quantize -b 8 -min 0 -max 1 -i out.nrrd -o parab${I}-tent.png
106 :     done
107 :    
108 :     This makes orthographic MIPs of the four low-res parab?.nrrd datasets, producing
109 :     images that reveal the underlying sampling grid:
110 :     [parab0-tent.png](parab0-tent.png),
111 :     [parab1-tent.png](parab1-tent.png),
112 :     [parab2-tent.png](parab2-tent.png),
113 :     [parab3-tent.png](parab3-tent.png).
114 :    
115 :     The fact that these images differ means that the quadratic function sampled
116 :     by `fs3d-scl -which 4` is not exactly reconstructed by the `tent`
117 :     reconstruction kernel. If the reconstruction had been exact, then the
118 :     rendering would have been entirely determined by the underlying quadratic
119 :     function, rather than the particulars of the sampling grid. Note that the
120 :     `inSphere` parameter is important here: it ensures that the region rendered
121 :     (the sphere) has the same rotational symmetry as the quadratic function
122 :     itself.
123 :    
124 :     Now **we change one line of code below**, so that only the
125 :    
126 :     field#1(3)[] F = vol ⊛ ctmr;
127 :    
128 :     field definition is uncommented (commenting out `field#0(3)[] F = vol ⊛ tent;`).
129 :     This changes the reconstruction kernel the Catmull-Rom cubic interpolating spline,
130 :     which can accurately reconstruct quadratic functions.
131 :     Then we re-run the commands above, but saving the results to differently-named images.
132 :    
133 :     OPTS="-out0 0 -inSphere true -camOrtho true -camEye 8 0 0 -camFOV 15 -rayStep 0.01 -iresU 300 -iresV 300"
134 :     for I in 0 1 2 3; do
135 :     echo === $I ====
136 :     cp parab${I}.nrrd vol.nrrd
137 :     ../../vis12/bin/diderotc --exec mip.diderot
138 :     ./mip $OPTS
139 :     unu quantize -b 8 -min 0 -max 1 -i out.nrrd -o parab${I}-ctmr.png
140 :     done
141 :    
142 :     This generates four new images:
143 :     [parab0-ctmr.png](parab0-ctmr.png),
144 :     [parab1-ctmr.png](parab1-ctmr.png),
145 :     [parab2-ctmr.png](parab2-ctmr.png),
146 :     [parab3-ctmr.png](parab3-ctmr.png).
147 :    
148 :     As should be visually clear, these images are all the same (or very nearly so), demonstrating the
149 :     accuracy of the Catmull-Rom spline for quadratic functions.
150 :    
151 :     Things to try by further modifications of this program:
152 :     * Change the rendering from being a maximum intensity, to a summation intensity
153 :     (e.g. `out += F(pos)`). Make sure `out0` is zero.
154 :     * Change rendering to be mean intensity, which requires adding a counter to
155 :     count the number of samples of current ray inside the volume.
156 :     * Change the rendering to summating of gradient magnitude
157 :     (e.g. `out += |∇F(pos)|`).
158 :     * Change the rendering to generate a `vec3` output summing gradient vectors
159 :     (e.g. `out += ∇F(pos)`). Type of `out` must be `vec3`, initialized to `[0,0,0]`.
160 :    

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0