SciVis 2017 Lab 1: Using "rplotr" and "unu"
The goals of this lab are to make sure all students can:
- Exercise 1: Check out scivis-2017 and CNETID-scivis-2017 repos, make and commit changes to their p1plotr code, and run the rplotr reference implementation.
- Exercise 2: Use rplotr to learn about index vs world-space
- Exercise 3: Use rplotr to learn about derivatives in world-space
- Exercise 4: Begin using unu for raster data hacking, including a demo of fast vs slow axes.
There are no specific files to check in, and nothing will be graded. However, the TAs and the instructor will know if you are asking a question that would have been answered by working through the material here.
Exercise 1: Opening shell, checking out repos, running rplotr
After logging into a CSIL Mac, open the iTerm application (note the exact icon at left) to get a command-line prompt at a bash shell. Various features make iTerm better then Apple's Terminal.
Then, copy and paste the curl and source commands at the top of the SVN for SciVis page. This downloads (via curl) a set of commands to set up your repos according to the SVN instructions, and then runs (via source) these commands. The commands being executed are printed before they are run. The svn checkout commands may require you to accept a server certificate for phoenixforge.cs.uchicago.edu (type "p"), and to enter your CNetID password to authenticate your access to repos on phoenixforge.
After source scivis-setup.sh finishes, you should be able to:
to get to your CNetID-scivis-2017 repo checkout, which is inside a new scivis-work directory. Alongside CNetID-scivis-2017 is a checkout of scivis-2017 repositories, and the $SCIVIS environment variable should be set to its full path. Also, your $PATH variable now includes some Teem binaries like unu, which we will use in this lab.cd scivis-work/$USER-scivis-2017Then you should be able to build your Project 1 code:
This should run successfully (no error messages) with the code originally distributed to you.cd p1plotr makeIf you have not already started on this project, make sure you can edit, compile, and commit your code. Try this by (staying within the p1plotr directory) editing util.c, so that pltItoW() looks like:
Then, at your shell, re-run make. It should create a new plotr executable that includes your new code. To test this:float pltItoW(const pltData *data, float indexPos) { float ret=0; /* v.v.v.v.v.v.v.v.v.v.v.v.v.v.v.v.v.v.v begin student code */ if (pltCenterCell == data->center) { printf("cell-centered\n"); } else { printf("node-centered\n"); } /* ^'^'^'^'^'^'^'^'^'^'^'^'^'^'^'^'^'^'^ end student code */ return ret; }The two rplotr psamp commands make little datasets cell.txt and node.txt. The output of the first plotr itow command should be the the "cell-centered" that we printfed from pltItoW. The second plotr itow command should generate "node-centered"../rplotr psamp -p 0 -mm 0 1 -n 5 -c cell -o cell.txt ./rplotr psamp -p 0 -mm 0 1 -n 5 -c node -o node.txt ./plotr itow cell.txt 0 ./plotr itow node.txt 0Because we made a modification to the code, we will see this change when we run
and we can concisely see which files were modified withsvn diff(note which files are listed with an "M") Every time you are finishing up work, you should do an svn status to see what files you have modified. And if there are any modified files, you must svn commit -m "message" those files before you log off the Mac, or else you may lose your work. Make sure you can successfully commit modifications:svn statussvn commit -m "testing during lab1" util.cNOTE that neither printf above should stay in your final pltItoW() code in util.c. The purpose of this exercise was to demonstrate the connection from editing a function (pltItoW()) in one of the files you'll need to edit for the assignment (util.c), to running make to get a new plotr, to running a command (plotr itow) which calls the function you edited. This kind of development/debugging process will continue for all the other functions you have to finish implementing, as described in plotr about.
Finally, you should be able to run the rplotr command and create the PNG image below (nevermind the 1-pixel border) with it
./rplotr psamp -mm -2 3 -p 2 -1 -2 1 -n 6 -c cell -o samp.txt ./rplotr plot -s 400 200 -xmm -2 3 -ymm -3 4 -p 2 -1 -2 1 -thp 15 -tha 5 -i samp.txt -dd 30 -hz 80 -o plot.png
You can view plot.png, or any of the other images we generate here, from the command-line, as with:which should open the image with Mac's general purpose "Preview" viewer.open plot.pngNote that all the commands here can be run in your p1plotr directory of your CNetID-scivis-2017 repo checkout. A lot of new files will be generated, but this is okay, since you should not "svn add" and "svn commit" them, so they will be gone the next time you checkout your CNetID-scivis-2017 repo.
If you are not able to run these commands, please bring this to the attention of the person running the lab session.
Exercise 2: Node- vs cell-centering, index- vs world-space
We can use the rplotr command to make illustrations of node-centered vs cell-centered samples from the node.txt and cell.txt files generated above:./rplotr plot -i cell.txt -xmm 0 1 -ymm -1 1 -s 700 80 -k zero -dd 40 -o cell.png
./rplotr plot -i node.txt -xmm 0 1 -ymm -1 1 -s 700 80 -k zero -dd 40 -o node.png
Make sure you understand (from FSV Section 4.3) that each of these 5 dots represents the position of a sample within the world-space interval [0,1] requested via rplotr plot -xmm 0 1, but in both cases the indices for each of the dots are 0, 1, 2, 3, 4; these are the integers in the data's index-space. Separate from either the world-space or the data index-space is the index-space of the output image, which in this case varies from 0 to 699 in the horizontal and 0 to 79 in the vertical (due to rplotr plot -s 700 80).
We can test our understanding of the relationship between index and world space, for cell-centered and node-centered samples, by considering each of these commands, and predicting what the answer will be before you run it.
./rplotr itow cell.txt 0 ./rplotr itow node.txt 0 ./rplotr itow cell.txt 4 ./rplotr itow node.txt 4 ./rplotr wtoi cell.txt 0 ./rplotr wtoi node.txt 0 ./rplotr wtoi cell.txt 1 ./rplotr wtoi node.txt 1Exercise 3: Derivatives in world-space
One of the challenges for Project 1 may be correctly implementing differentiation by convolution. FSV Section 4.2 ends with the observation that differentiation of a convolution is just convolution with the derivative of the filter, but that really only holds when working in index-space. Taking derivatives in world-space has to account for the spacing between samples, as discussed at the end of FSV Section 4.3.We can use rplotr to make a visual demonstration of this. First we sample the line f(x)=x at samples that are unit-distance apart, and then with samples that that are twice as close:
When you "cat ramp1.txt" you will see that, as you should expect, the data values are simply -2, -1, 0, 1, and 2. ramp2.txt should also contain no surprises. We can plot these with:./rplotr psamp -p 0 1 -mm -2 2 -c node -n 5 -o ramp1.txt ./rplotr psamp -p 0 1 -mm -2 2 -c node -n 9 -o ramp2.txt./rplotr plot -i ramp1.txt -k tent -xmm -2 2 -ymm -2 2 -s 300 300 -dd 10 -o ramp1.png ./rplotr plot -i ramp2.txt -k tent -xmm -2 2 -ymm -2 2 -s 300 300 -dd 10 -o ramp2.png
We can now plot the derivative of f(x)=x, or f'(x)=1, with:./rplotr plot -i ramp1.txt -k tent -d 1 -xmm -2 2 -ymm -2 2 -s 300 300 -dd 10 -o ramp1d.png ./rplotr plot -i ramp2.txt -k tent -d 1 -xmm -2 2 -ymm -2 2 -s 300 300 -dd 10 -o ramp2d.png
Note that in both cases, by adding the -d 1 option, we obtained a plot of f'(x)=1, even though in the second case the index-space derivative was half as large as in the first case: in ramp2.txt, successive sample values differ by 0.5, but in ramp.txt successive sample values differ by 1.0. But the world-space derivative is the same: this is the same result your code should produce.Exercise 4: Unu for fast/slow axes, and basic raster data hacking
Like plotr, the unu command has many subcommands. Since the scivis-2017 repo includes teem-install/bin and that should have been added to your path with scivis-setup.sh, you should be able to see all the unu commands withWe will use unu reshape to demonstrate some basics of raster structure. First we make a little 1-D array with integers 0 through 5:unuYou should "cat ramp6.txt" to make sure you see the sequence of values stored there. Then:./rplotr psamp -p 0 1 -mm 0 5 -c node -n 6 -o ramp6.txtDo a "cat ramp23.txt" and "cat ramp32.txt" to see the contents of these new files. unu reshape has taken the 6 values, and reshaped them into two 2-D arrays, with axis lengths 2 and 3, without changing the ordering of the values in memory (or on disk). The layout of values in the 2-D array is stored in the text file with spaces and newlines. In the case of ramp23.txt, the length-2 axis was faster, and the length-3 axis was slower: as you traverse the values in one-dimensional order (from 0 to 5), the length-2 axis is traversed faster (and is traversed 3 times) than then length-3 axis (traversed once). The situation is reversed with ramp32.txt; for which the length-2 axis is slower, and the length-3 axis is faster.unu reshape -i ramp6.txt -s 2 3 -o ramp23.txt unu reshape -i ramp6.txt -s 3 2 -o ramp32.txtType "unu reshape" to get the usage information about this command. When using the unu tool, remember that it always orders axes from fast to slow.
We can also see the effect of reshape on color images. Standard RGB image value ordering puts the colors on a fast short axis, followed by a slower horizontal axis, followed by the (slowest) vertical axis. We can use unu to inspect this about the plot.png we made at the end of Exercise 1.
which should give you:unu save -i plot.png -f nrrd | unu head -This shows how the (2-D) PNG image is really a 3-D array with axes sizes, from fast to slow: 3, 400, and 200. Understanding a 2-D color image as a 3-D array is discussed in FSV section 3.3. The axis mins, axis maxs, and centerings fields show the information that was set by rplotr plot (and saved as meta-data in the PNG file; the mechanics of which aren't important for this class).NRRD0001 # Complete NRRD file format specification at: # http://teem.sourceforge.net/nrrd/format.html type: unsigned char dimension: 3 sizes: 3 400 200 axis mins: nan -2 4 axis maxs: nan 3 -3 centerings: ??? cell cell encoding: rawWe use the term "raster data hacking" to refer to data operations that assume a close understanding the raster structure of the data, in order to get some fun or useful thing done with the data. We could ask, for example, "How can we make a new grayscale image that shows each of the red, green, and blue components of plot.png, as separate images, on top of each other?" The key will be using unu permute to permute the axes in their fast-to-slow ordering, which does change the ordering of the values in memory (in contrast to "unu reshape").
We want a 2-D grayscale image for which the horizontal axis is the same as in plot.png, but vertically, first we want the vertical axis of the red part of plot.png, then green, then blue. So the new logical ordering of axes is horizontal, vertical, color. But we'll then need a reshape to get it into a real 2-D array. The unu commands are then:
unu permute -i plot.png -p 1 2 0 | unu reshape -s 400 600 -o plot-cv.png
The "unu head" command before is useful to debug results of unu hacking; as with:to see what the "unu permute" did with the axes: it permuted them so that axis #0 (length 3) is last, axis #1 (length 400) is second, and axis #2 (length 200) is last. Type "unu permute" to get usage information about this command, and make sure you understand what is going on. The subsequent "unu reshape" combined the last two axes into a single length-600 vertical axis. To avoid having to do arithmetic on the axis lengths, we could have also done this:unu permute -i plot.png -p 1 2 0 | unu head -Try this, and type "unu axmerge" to get the usage information about this command.unu permute -i plot.png -p 1 2 0 | unu axmerge -a 1 -o plot-cv.pngThe effect of looking at colors in a per-component way may be clearer with a more interesting image, fruit.png (created from this):
curl -O http://people.cs.uchicago.edu/~glk/class/scivis-2017/lab1/img/fruit.png unu permute -i fruit.png -p 1 0 2 | unu axmerge -a 0 -o fruit-hv.png
In this case the color channels were laid out side-by-side. Make sure you understand why the unu command above does this; it uses commands that we've already seen, but in a slightly different way.