QUENCH

From VISTA LAB WIKI

Jump to: navigation, search

QUENCH is a tool for visualizing and interacting with fibers. We use it to segment fibers into groups and to visualize statistical properties along the fiber bundles.

Quench Interface

Contents

[edit] Introduction

QUENCH allows the user to visualize and edit fiber tracts. The fiber tracts are normally estimated using other programs, such as mrDiffusion and ConTrack. QUENCH is integrated with ConTrack scoring CINCH. Consult the QUENCH Tutorial to see the user interface. See the ConTrack page to understand scoring. CINCH was retired in the fall of 2009.

QUENCH was built by Shireesh Agrawal, Dave Akers, and Tony Sherbondy.

Dave Akers and Doug Hamilton have been extending DTIQUERY which has many other useful features. We hope to integrate these different programs some day. But for now, they are separate and both useful.

[edit] Download

The downloads featured here were compiled for various operating systems and may therefore not work on your specific OS. If you download a version here and it does not work for you it might be because you're missing a library, or it could mean that you need to compile the program for your OS. For help see the next section.

MAC
LINUX
WINDOWS

[edit] Software Build

The preferred way to create Quench on a Linux box is to run the shell script on the page Build QUENCH.

When using Linux, it is probably important to download the specific graphics card driver from NVIDIA or ATI rather than using the generic graphics card driver that is bundled with, say, Ubuntu. In Ubuntu you can search for the relevant driver for your system using Synaptic or the apt-get search method.

To explore some simple features of QUENCH we provide a sample dataset. This is the same data set used in the QUENCH Tutorial.

To build Quench on a fresh download of Ubuntu 10.10 we needed to install a series of packages (which are available through Synaptic). These are described on the Build Quench page.

[edit] QUENCH Tutorial

The QUENCH Tutorial provides a quick overview of Quench and it's features. The tutorial will take you through the basics of the software's operation (e.g., loading backgrounds, loading fibers, overview of bins, overview of selection tools, overview of selecting fibers etc.).

[edit] Relevant Matlab Routines

Quench related functions are located in vistasoft/trunk/mrDiffusion/Quench. Below are the list of function which interact with Quench

  • dtiClearQuenchStats Removes all statistic information from input fiber group.
  • dtiCreateQuenchStats Adds statistic information to a fiber group. The statistic can be geometry based eg. Length or image/array based.
  • dtiLoadMetrotracPathsFromStr Main function to load a PDB file into memory. If the file version is 3, it calls dtiLoadMetrotracPathsFromStrVer3 to complete the loading of the PDB file.
  • dtiLoadMetrotracPathsFromStrVer3 This function completes the loading of a version 3 PDB file into memory.
  • fiberToStr Converts a version 2 PDB file to string. This function is very slow due to the way PDB version 2 is structured.
  • fiberToStr3 Converts a version 3 PDB file to string. This function takes only a few seconds even for big PDB files
  • quenchCheckServer Tries to check if Quench is already running by a handshake.
  • quenchStart Tries to start Quench if its not already running.
  • mtrExportFibers Allows you to save a fiber group structure in .pdb format.
  • mtrImportFibers Allows you to import .pdb file as a fiber group structure in matlab.

The following two functions only work with Quench '.qst' Version 2 files.

[edit] Quench FAQ

Here we will have insightful questions with helpful answers.


[edit] Protocols

[edit] PDB File Format - Version 3

The pdb file format in version 3 is described below.

uint (4 bytes) header size, unused
double x 16 ACPC transformation matrix
DTIPathwayStatisticHeader x number of stats Write out statistic header for each stat
DTIPathwayAlgorithm x number of algos Write out algorithm header for each algo, usually 0
int (4 bytes) Version number, must be 3
int (4 bytes) number of fibers
int (4 bytes) x number of fibers Write out the number of points in each fiber, used as look up table
double x number of fibers x points per fiber x 3 Write out the 3d point data for each fiber
double x number of stats x number of fibers Write out the per fiber statistics
double x number of stats x number of fibers x points per fiber Write out per point stats for each fiber

This spec is also described here: http://graphics.stanford.edu/projects/dti/software/pdb_format.html

Note: In case you are wondering, ".pdb" stand for "pathway database" and apparently has nothing to do with the popular "protein database" file-format, using the same extension.

[edit] Pushing/Pulling fibers from Matlab

This is a two step process. First we pass the fibers as a version 3 pdb file. In the next pass we pass fiber group information specifying which group each fiber is assigned to and group properties

float number of fibers
float x number of fibers group # to which each fiber is assigned
float number of groups to be sent
Repeat items below for each group to be sent
float group index
float is group visible
float group color's red component
float group color's green component
float group color's blue component


[edit] Feature Requests

  • (JY) Load/save ROI nifti files or from Matlab
  • (AS) Per point info display using color maps
  • (AS) Loading meshes and ROIs from files
  • (JY) Draw ROIs on a slice... Seems like CreateCylinderFromPoints( ) in qGestureInteractor.cpp is never got hooked up... Useful code from Quench 1.0 ...
  • from vtkInteractorStyleQuench.cpp
    case QIS_BEGIN_VOI_MESH:
    frame->EndVOIMeshCreation();
    break;
    
    from Quench.cpp
    void MyFrame::EndVOIMeshCreation()
    {
       istyle->_GestureInteractor->EndSelect();
       vtkPolyData *pd = istyle->_GestureInteractor->CreateMeshFromGesture();
       if(_stats_panel)_stats_panel->TempShow();
       if(pd)
       {
         _Scene->GetPathwayViz()->CreateVOIMesh(pd);
         _stats_panel->GetVOIPanel()->Update();
         istyle->HighlightProp(_Scene->GetPathwayViz()->GetActiveVOI()->getActor());
         if(_score_panel_visible) _Scene->GetPathwayViz()->SetScoreThreshold(-1,0,0,true, _stats_panel->GetState());
         RefreshViz();
       }
    }
    
  • (AS) Break QuenchController into multiple Controller objects
  • (AS) Replace RAPID with opcode or ozcollide
  • [edit] Bug report

    Please put your name or something on this so I can contact you directly if I need clarification on the bug.

  • (LMP 3.14.11) I get a core dump and hard crash when I attempt to load multiple fiber groups after I edit and save them in Quench. For example, if I load any two fiber groups (generated by conTrack) and edit them, then save them in Quench (using File > Save Visible Pathways) I can't open them both simultaneously using Quench. Interestingly, if I take those fibers and run dtiClearQuenchStats on both of them I can open them again in Quench, but if I edit them I won't be able to open them together again. Note that I can open either fiber group by itself at any point. I reproduced this error on sepia using a different set of pathways. This bug must have been introduced with the last build, I don't remember this ever being an issue before... EDIT This seems to be a problem with the way that Quench is saving fibers, not necessarily the statistics. If you simply load the fibers into matlab (mtrImportFibers) and then save them out again (mtrExportFibers) the problem goes away and you can load multiple groups at once in Quench.
  •  Initializing Quench...
     In case of crash your last selection is saved to ~lastState.qst file
     Loading /viridian/scr1/data/FINRA/CC/DTI/t1acpc.nii.gz...
     Warning: Unusual number of algorithms. Assuming old path format; will create default algorithm headers.
     Loaded 100%
     Finished loading pathways.
     Loaded 100%
     Finished loading pathways.
     Loaded 100%
     Finished loading pathways.
     Loaded 100%Segmentation fault (core dumped)
     [lmperry@viridian DTI]$ 
    


  • (AS) Get the following error when trying to run Quench remotely from brown or veridian, but works fine on khaki??
  • ERROR: In /khaki/scr1/Quench2/vtk/VTK/Rendering/vtkXOpenGLRenderWindow.cxx, line 404
    vtkXOpenGLRenderWindow (0x1616050): Could not find a decent visual
    
  • (LMP) AS cannot replicate this on khaki, but I was able to get what may be the same error on brown. The error message was different (reporting something wrong with the NVidia driver, but happened as soon as I tried to interact with the GL window after inserting a VOI, but not after just a refresh. Using gdb, it seems that the error is within the VTK library. For some reason the picker is getting called as well... When working with VOIs from within the VOI tab Quench crashes and produced the following in the command window.
  •  Finished loading pathways. 
     Warning: No distance matrix file found - grow/shrink selection disabled.
     (Quench64:29558): GLib-GObject-WARNING **: invalid unclassed pointer in cast to `GtkRadioMenuItem'
     (Quench64:29558): Gtk-CRITICAL **: IA__gtk_radio_menu_item_get_group: assertion `GTK_IS_RADIO_MENU_ITEM (radio_menu_item)' failed
     Segmentation fault (core dumped)
     [lmperry@viridian quench]$ 
    
  • (LMP) AS cannot replicate this... For some reason it is possible to write out corrupt state files where the number of assigned pathway groups is off or stored in the wrong place. This resulted in the following example ... where Quench crashes when attempting to load a state file, using the example data in the vistadata repository. We can see that the fibers load, but prior to showing anything it dumps the core and crashes. ** We can't reproduce this bug. ** Something is wrong with a specific state file. /home/lmperry/svn/vistadata/quench/exampleState.qst.
  •  Error:
     (Quench64:27560): GLib-GObject-WARNING **: invalid uninstantiatable type `<invalid>' in cast to `GtkRadioMenuItem'
     (Quench64:27560): Gtk-CRITICAL **: IA__gtk_radio_menu_item_get_group: assertion `GTK_IS_RADIO_MENU_ITEM (radio_menu_item)' failed
     Segmentation fault (core dumped)
    
  • (JY) How do I get cortex or other ROI meshes into Quench? --> Transfer through dtiFiberUI is only partly functional Shireesh never finished the code transfer for 2.0, he said he would look into it to see if he can do a quick fix on 12/11 weekend.
  • (AS) Check marks on Panels items gets out of sync.
  • (AS) PerPoint coloring does not seem to be working and it kicks paths into a weird unlabeled state that I can't get back from.
  • (AS) Reset pathway colors should reset to the original colors not black and invisible.
  • [edit] Fixed

  • 2011-01-16 (AS) Image preview takes way too long, e.g., much longer than it seems to take to draw the scene in the first place. --> Fixed, turned out that tubes were always being enforced no matter what quality level and the tube filter is very slow, the quality only controlled the number of sides of tubes. I simplified this by giving the user the ability to choose between lines or tubes to save and lines is very fast.
  • 2011-01-16 (AS) Reno noticed a crash when he opens Quench and then closes it without doing anything.... When I try to debug it on Linux gdb suggests that the crash is occurring in the VTK library... Valgrind won't run Quench?? ... Need to try on OSX when the gesture interactor is finished... Latest updates suggests that it is working, at least on OSX... Need to test Linux. --> Fixed.
  • 2011-01-16 (LMP) With certain T1 images Quench will not scroll in every direction. For example, if you load the t1 in /azure/scr1/lmperry/quench/t1acpc.nii.gz. I can't scroll in the axial plane to the right - only to the left. I'm not sure why this only happens with certain t1s. (AS) Also, if the coronal or axial planes are selected -> WorldToLocal and LocalToWorld functions were not symmetric, because a floating round off errors can happen that are then exaggerated only in the WorldToLocal direction because of a floor function, this was fixed by adding a small offset only in this function before the floor.
  • 2011-01-16 (AS) Keyboard lock/unlock assignment doesn't refresh screen text immediately, but menu does.
  • 2011-01-16 (AS) If I am in surface mode and I change the label of some pathways and switch out of surface mode, the label of the pathways does not seem changed in the 3D scene. If I go back to surface mode than the label of the pathways is seen as changed. If I flip back to 3D mode, still no change... --> QuenchController was not updating pathway color group...Fixed.
  • 2011-01-16 (AS) qGestureInteractor seems to be broken because it was only partially transferred from Quench 1.0 to Quench 2.0, e.g., intersect surface only lets me touch points to change their label, I used to be able to lasso them... Almost there, the gesture just isn't showing up. --> Fully implemented.
  • 2011-01-11 (AS) Once RAPID is in SVN, remove "Warning! Some triangles have zero area!" message. --> Done.
  • 2011-01-10 (AS) Remove "Warning: No distance matrix file found - grow/shrink selection disabled." because we are not using this shape similarity matrix. -->Fixed.
  • 2011-01-10 (AS) On OS X screen must be resized before the interaction hooks work correctly. --> Fixed.
  • 2011-01-10 (AS) Check marks on "Show" menu items get out of sync with the actual state of the windows. --> Fixed.
  • 2011-01-10 (AS) "Show Pathways" starts invisible. --> Fixed.
  • 2011-01-09 (AS) Toggling image plane visibility does not work through the menu. --> Fixed.
  • 2011-01-08 (AS) Global access to the QuenchFrame object seems unnecessary and complicates much of the code. --> All code requiring global access to the frame have been removed.
  • 2011-01-06 (AS) Shireesh added a nice design pattern known as "event handling," which allows us to unlink objects by exposing a dynamic interface only exposed through events. Unfortunately, the unlinking also made Quench way too complicated for tracking down who is listening to which sources. --> I have greatly simplified Quench by placing all event listening attachments in the class that is listening, most significant listening attachments are handled within QuenchController.
  • 2011-01-06 (AS) Quench.cpp is a monolithic mess. --> Separated Quench into 3 objects with 3 files QuenchApp, QuenchFrame, QuenchController. Similar to many GUI systems Quench now has a separate application object, main window or frame object and controller or handler of the main window.
  • 2011-01-06 (AS) Default camera coordinates don't seem to take world dimensions into account, example microtrack phantoms. --> Fixed as part of the massive Quench logic overhaul between 2010-12-20 and now.
  • 2011-01-06 (AS) Clicking color maps for overlays doesn't work on Mac --> Handle MouseDown events now instead of MouseUp.
  • 2010-12-24 (AS) Overlays still have multiple problems, i.e., they hover above the plane too far and there is also some weird out of order rendering depending on the viewpoint. --> Bypassed the VTK code and made my own OpenGL calls in a class called vtkOpenGLImageOverlayActor, which simply makes a plane that will hover very slightly above the background image plane... I can only guess that this wasn't possible previously because people did not understand how the OpenGL calls were working in the previous VTK overlay class.
  • 2010-12-6 (JY) remove overlay button doesn't work --> Old version, this button does not exist anymore.
  • 2010-12-6 (JY) Load/save ROI nifti files --> menu not available in Quench 2.0, this transfer has to be done through Matlab.
  • 2010-12-6 (JY/BW) Loading a NIFTI volume as an overlay produces 3D regions that float outside of the rendered cardinal planes. --> This has been fixed for Quench 2.0.
  • 2010-12-6 (JY/BW) Saving the state does not save a full state that can be efficiently loaded at startup. --> I believe this was considered a bug because of the discrepancy between what the user's noticed on an old version of Quench vs. what is currently available on the new version. If the new version is still not deemed fully featured enough then this should be labeled a feature request rather than a bug.
  • 2010-12-6 (AS) Still pointing to CINCH_sample data, we should now call this Quench sample data, CINCH is retired. --> Added vistadata tutorial that we will point to.
  • 2010-12-6 (AS) Command line ability to load all images with * wildcard is not working. Would need to use the escape sequence \* to include the asterisk --> Changed command line format so that we could specify all images within a directory with -a flag.
  • 2010-12-6 (JY) when loading an overlay on the windows build, the range is set improperly --> Seems like you were using an old windows build.
  • 2010-12-6 (JY) Image quality slider for screenshots does not appear to do anything and it also doesn't seem to be rendering tubes for screenshots --> verified that tubes are rendered and saved to images (AJS)
  • Need to add fiber exporting function and description...I believe dtiExportFibers?
  • This page needs to be written for Quench version 2 not 1.
  • There is too much time lag between when we press the right mouse button down and we are able to start zooming. ---- Changed to 100ms. See vtkInteractorStyleQuench::OnRightButtonDown() function; line Start(100) to change the delay.
  • Title bar of quench2 says quench version 1
  • API documentation does not render correctly for Safari and Firefox.
  • Matlab section is missing function list and explanation.
  • get_stanford_dwitools.sh has a lot of legacy lines in there, e.g., Insight, cvs when using git, please clean.
  • [edit] The Past

    Old Quench Page


    [edit] Collaborations

    Puget Sound Collaboration

    Personal tools