SciVis 2015 Lab 1: Using "rplotr" and "unu"

The goals of this lab are to make sure all students can:

• Exercise 1: Check out scivis-2015 and CNETID-scivis-2015 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, within your shell (copy and paste these commands):

  curl -O http://people.cs.uchicago.edu/~glk/class/scivis-2015/scivis-setup.sh
  source scivis-setup.sh
  

  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 inside your CNetID-scivis-2015 repo checkout, which is inside a new scivis-work directory. Alongside CNetID-scivis-2015 is a checkout of scivis-2015 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.

  Then you should be able to build your Project 1 code:

  cd CNetID-scivis-2015
  cd p1plotr
  make
  

  This should run successfully (no error messages) with the code originally distributed to you.

  To make sure you can edit, compile, and commit your code, stay within the p1plotr directory, and edit util.c, so that pltItoW() looks like:

  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;
  }
  

  Then, at your shell, re-run make. It should create a new plotr executable that includes your new code. To test this:

  ./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 0
  

  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".

  Because we made a modification to the code, we will see this change when we run

  svn diff
  

  and we can concisely see which files were modified with

  svn status
  

  (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 commit -m "testing during lab1" util.c
  

  NOTE 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 4 -3 -p 2 -1 -2 1 -thp 15 -tha 5 -i samp.txt -r 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:

  open plot.png
  

  which should open the image with Mac's general purpose "Preview" viewer.

  Note that all the commands here can be run in your p1plotr directory of your CNetID-scivis-2015 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-2015 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 -r 40 -o cell.png
  

  
  

  ./rplotr plot -i node.txt -xmm 0 1 -ymm -1 1 -s 700 80 -k zero -r 40 -o node.png
  

  
  

  Make sure you understand (from FSV Section 4.2.6) 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, but 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 1
  

  Exercise 3: Derivatives in world-space

  One of the challenges for Project 1 may be correctly implementing differentiation by convolution. We emphasized in class last week 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 in FSV Section 4.2.6.

  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:

  ./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
  

  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 plot -i ramp1.txt -k tent -xmm -2 2 -ymm 2 -2 -s 300 300 -r 10 -o ramp1.png
  ./rplotr plot -i ramp2.txt -k tent -xmm -2 2 -ymm 2 -2 -s 300 300 -r 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 -r 10 -o ramp1d.png
  ./rplotr plot -i ramp2.txt -k tent -d 1 -xmm -2 2 -ymm 2 -2 -s 300 300 -r 10 -o ramp2d.png
  

  
  
  Note that in both cases 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.

  Exercise 4: Unu for fast/slow axes, and basic raster data hacking

  Like plotr, the unu command has many subcommands. Since the scivis-2015 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 with

  unu
  

  We will use unu reshape to demonstrate some basics of raster structure. First we make a little 1-D array with integers 0 through 5:

  ./rplotr psamp -p 0 1 -mm 0 5 -c node -n 6 -o ramp6.txt
  

  You should "cat ramp6.txt" to make sure you see the sequence of values stored there. Then:

  unu reshape -i ramp6.txt -s 2 3 -o ramp23.txt
  unu reshape -i ramp6.txt -s 3 2 -o ramp32.txt
  

  Do 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.

  Type "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.

  unu save -i plot.png -f nrrd | unu head -
  

  which should give you:

  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: raw
  

  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. 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).

  We 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:

  unu permute -i plot.png -p 1 2 0 | unu head -
  

  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 axmerge -a 1 -o plot-cv.png
  

  Try this, and type "unu axmerge" to get the usage information about this command.

  The 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-2015/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.

  Finally, we can play with a 4D array that represents a color video ...