TRAJECTORY-BASED SPATIO-TEMPORAL VISUALIZATION OF PIONEERING NEURON

Introduction: This program provides an interactive visualization for the spatio-temporal data in 5D image (multi-channel 3D volume over time), with the main experimental subject is the image of zebrafish embryo captured using light-sheet microscopy. The trajectory of the pioneering neuron is regarded as the main object of interest, and is also used as a direct widget for manipulation and interaction in spatio-temporal domain.

Requirement: The program is built on top of the following packages: CUDA, Teem, GLM, GLFW.

Set up: Below is the instruction to compile and set up the program, targeting mainly on UChicago's Midway server.
1) ssh into Midway server: midway.rcc.uchicago.edu
2) Make a directory to store the code, let's call it YOUR_DIR.
3) Clone this repo into YOUR_DIR, and cd to hale_cuda.
4) Load cuda compiler by calling: module load cuda/7.5
5) Build the hale library by typing "make", then "make install". The default Makefile includes the paths to prebuilt Teem, GLM, and GLFW libraries, as can be seen in the first lines of Makefile:

TEEM = /project/glk/rossc/code/teem-install
GLM = /software/glm-0.9-el6-x86_64/include/
GLFW = /software/glfw-3.1-el6-x86_64/include/

If there are changes in the system, or if you install the new libraries in other directories, make sure to change these paths accordingly.
After this step, the hale library will be installed to YOUR_DIR/hale_cuda/hale-install
6) cd to "demo" directory.
7) Build the visualization program (cpr_seq.cu) by calling this command:

nvcc -std=c++11 -I/YOUR_DIR/hale_cuda/hale-install/include -I/project/glk/rossc/code/teem-install/include -I/software/glm-0.9-el6-x86_64/include -I/software/glfw-3.1-el6-x86_64/include cpr_seq.cu lib/Image.cpp -o cpr_seq -L/YOUR_DIR/hale_cuda/hale-install/lib -L/project/glk/rossc/code/teem-install/lib -L/software/glm-0.9-el6-x86_64/lib64 -L/software/glfw-3.1-el6-x86_64/lib64 -lglfw3 -lGL -lm -ldl -lXinerama -lXrandr -lXi -lXcursor -lX11 -lXxf86vm -lpthread -lhale -lteem -lpng -lz -lbz2 -lGL -lX11 -lXxf86vm -lXrandr -lpthread -lXi

Remember to change YOUR_DIR into your path accordingly. After this step, the program will be built into cpr_seq

Testing: This section provides guides to directly run the tool with graphical interface on Midway server through the web.
1) Go to the following link and log in: https://midway.rcc.uchicago.edu/
2) Open a terminal, then type sviz, which will request a visualization node.
3) Navigate to the directory containing the compiled program (YOUR_DIR/hale_cuda/demo/)
4) Execute the program by the following command:
vglrun ./cpr_seq -isize 200 200 -swidth 1 -sstep 0.01 -i coord_newtrack_pioneer_scale_old.txt -pref /project/glk/vprince/16-05-05/vis/hp/hp2

Remember to add vglrun at the beginning to be able to have graphical interface. The program runs with some parameters such as:
-isize: the image size of the cutting plane orthogonal to the trajectory to visualize.
-swidth: the width of the image slab to consider.
-sstep: the step size of the ray during ray casting for rendering.
-i: input coordinates of the pioneering neuron trajectory.
-pref: prefix to the path containing the images.

--------------------------------------------------------------------
SOME OTHER TOOLS
The repo also contains some other tools, i.e., tex_volume_test2file.cu and cpr_seq_savespacetime.cu
* The tex_volume_test2file.cu contains code to generate volume rendering for the whole volume, given the desired viewpoint. This file can be compiled similarly as the way we did for cpr_seq.cu. An example running command for this program is:

./tex_volume_test2file -i 0-smlhp.nrrd -i2 1-sml.nrrd -fr 2453.95 1850.87 4520.28 -at 2575.22 2259.17 461.956 -up -0.996969 0.0745429 -0.0222908 -nc -400 -fc 400 -fov 18 -isize 726 528 -ldir -1 -1 -2 -step 1.5 -iso 1800 -thick 0.5

Some input arguments are as follows:
- "i" and "i2": represent two input files corresponding to 2 channels of the volume ("i" used for GFP, "i2" used for RFP).
- "fr" "at" "up": define the viewing coordinate frame.
- "nc" and "fc": near and far clipping planes.
- "fov": field of view. 
- "isize": the image size.
- "ldir": light direction.
- "step": step size during ray casting.
- "iso": isovalue to render the RFP channel.
- "thich": thichness of the isosurface.

* The cpr_seq_savespacetime.cu contains code to generate the rendering of sampled cutting plane along the pioneering neuron trajectory, across multiple time steps. A sample running command is:

./cpr_seq_savespacetime -isize 200 200 -swidth 1 -sstep 0.01 -i coord_newtrack_pioneer_all_scaled.txt -pref /project/glk/vprince/16-05-05/vis/hp/hp2scivisdata/hp2

with input arguments similar to the cpr_seq.cu file above. After running this command, it will generate the ouput into the directory "spacetime_out", with the pictures named "cpr_seq_x_y.png", where x is the image timestep, and y is the sample index along the trajectory.

After the tool generated the output folder, the kymograph-like summary can be created using unu command (from Teem). An example command is:

unu join -i cpr_seq_2*.png -a 3 | unu axsplit -a 3 -s 275 22 | unu slice -a 0 -p 1 | unu crop -min 95 95 0 0 -max m+10 m+10 M M | unu axmerge -a 0 | unu project -a 0 -m mean -t float | unu resample -s x5 x5 -k box -c cell | unu quantize -b 8 -o kymograph.png

where the parameters 275 22 are the number of sampled points (275) along the trajectory (total y in cpr_seq_x_y.png), and the number of sampled time steps (22) from the total timesteps (total of sampled x in cpr_seq_x_y.png). The above unu command will generate the result one-channel kymograph into kymograph.png. To generate the two-channel version, use the following command:

unu join -i cpr_seq_2*.png -a 3 | unu axsplit -a 3 -s 275 22 | unu crop -min 0 95 95 0 0 -max M m+10 m+10 M M | unu permute -p 0 1 4 2 3 | unu axmerge -a 1 3 | unu quantize -b 8 -o kymo2chan.png