Manual for "SlugView" Visualizer Program
Version 1.0 by Tim Babb, Version 2.0+ by Michael Steffeck (msteffec@ucsc.edu)

Program purpose:
Visualizer and editor for point clouds and gridded heightfields with many millions of
points. Edits using tools for manually trimming, measuring, and fitting the dataset.
 
TABLE OF CONTENTS
 
  1) Running from the command line

  2) Running from MATLAB
        a. showpointcloud(matrix, behavior)
        b. showfromfile(path, behavior)

  3) Compatable file types

  4) Using the program
        a. Manipulation Tool   
        b. Selection Tool
                    1. Freehand
                    2. Rectangle
        c. Measure Tool
            d. Plane Fit Tool
            e. Merging data
               1. Merge with Superset
               2. Subtract from Superset
            f.  Point size
            g. Display resolution
        h. Draw-Line Tool
       i.  Undo button
        j. Cancel Selection / Clear Lines button
       k. Clear Measurement button
        l. Work On button
           m. Deleting data
               1. Delete inside
               2. Delete outside

  5) Troubleshooting

  6) Appendix
       a. Key and Mouse Bindings

============================================================
1)Running SlugView from the command line
============================================================

  - Make sure you have Java 1.5 or later (when available). Do 'java -version' to check.
  - If you do not see something similar to 'java version "1.5.0_07"' then go here: Get Java
  - If you do see that, then 'cd' to SlugView directory and type:
         
   ./SlugView.sh [option] [filename...]
            or for Windows
    SlugView.bat [option] [filename...]
   
   [filename] is either the name of a .header, .svn, or any other filetype to be defined
   
   The only [option] is "-c". This option will convert the raw text file in to a smaller, faster .svn file,
    which is native to SlugView.  More about file types in section 3: File Types.
   
    Return to Table of Contents
==============================================================  
2) Running SlugView from MATLAB
==============================================================

    **Note: When specifying a bahavior with Matlab, clicking "Done" in SlugView will exit and
            return the specified data. Clicking "Cancel" will exit without returning the specified data. **
    
  - Start MATLAB from ~/slugview
  - Run one of the following commands:
 
    a. showpointcloud(matrix, behavior)
      ARGUMENTS
          matrix:
            An [m x n] or [n x m] matrix of points, where n is the number of
            points, and m >= 3. The first three coordinates of the M dimension
            are taken to be points in euclidean space. The optional,
            additional coordinates are mapped to color.
        behavior:
            A string value indicating what kind of object to return. See
            below.
      RETURNS
        Return value is dependent on the "behavior" string. Output for
        each possible value of "behavior" is given below:
          'data'      - Return the data itself in an [m x n] matrix.
          'indexlist' - Return an [n X 1] list of indecies into the original
                        data, representing the points that you did NOT clip
                        away
          'planefit'  - Return the coefficients for the best-fit plane as a
                        function of x and y, in the form Ax + By + Cz + D.

      Return to Table of Contents    
    
    b. showfromfile(path, behavior)
        **Note: If you want to use showfromfile by specifying a behavior but not a filename then you must include empty
                single quotes. (i.e. showfromfile( '' , 'data') )  **
      ARGUMENTS
         path:
                The fully-qualified path of a point cloud file to display.       
         behavior:
                Selects whether to return data, a list of indecies, or a best-fit
                  plane ('data', 'indexlist', and 'planefit' respectively).
      BEHAVIOR
            Opens SlugView and automatically accesses the file specified. Returns specified behavior to Matlab when done
      RETURNS
        See "showpointcloud()".
    
    Return to Table of Contents

    c. showfromfile(path)
      ARGUMENTS
        path:
          The fully-qualified path of a point cloud data file to display.
      BEHAVIOR
        Opens SlugView and automatically accesses the file specified
      RETURNS
        See "showpointcloud()".

       Return to Table of Contents

==============================================================
3) File Types
==============================================================
 
   SlugView is capable of handling any text file format that is 7 dimensions or less.
    Every file is required to have at least xyz dimensions. It can also include RGB data
    and intensity data. RGB can be in floating point(decimal 0.0-1.0) form or byte(integer 0-255)
    form. Intensity can be numbers or characters.

    SlugView also has a native filetype, .svn (slugview native). SVN's store the information in binary;
    therefore are faster and smaller than their text file counterpart. It is recommended all files
    are converted to .svn.

    .headers: .header/.data file pairs have been removed from SlugView and replaced with .svn.
    SlugView will still open .header/.data pairs, but will no longer save in that format.
    
    Return to Table of Contents

=======================================================
4) Using the Program
=======================================================
    
 a. Rotation Tool    
    
      Activate this tool by clicking the circular arrow button (illustrated above).
      Right click the button for more options. You cannot make selections
      when you are in rotation mode.
      
      - PAN:      Middle-click and drag on the display window. Or if you have no middle click,
                  on most systems, clicking both left and right substitute
      - ZOOM:     Right-click and drag on the display window.
      - ROTATE:   Left-click and drag on the display window. Or use Arrow keys on keyboard
      - RECENTER: Double-click on a point in the display window. Rotation will
                  now happen around the new point. If you are having difficulty
                  manipulating the data, try recentering it.
      - SHOW POINT COORDINATES:  SHIFT + Left-Click will show the coordinates
                for the point being clicked.
      
      Whenever you re-center, a blue cone will appear and track over from the
      old center of rotation to the new one. You can bring the cone up at any
      time and see where your center of rotation is by holding the CONTROL
      key.
       
      Return to Table of Contents
      
 b. Selection Tool    
     
     Activate this tool by clicking the button with the polygon icon (Illustrated above).
      You cannot rotate while in selection mode. However, you can still pan and
     zoom.
     
     To make a selection, there are two options accessable by right clicking the button:
     
         1.Freehand:  This creates a free-hand tool which allows you to draw
             freely. When finished selecting an area, release the button and the ends will
             automatically be attached to complete the polygon
             
         2.Rectangle:     This creates a selection box. The initial click
             point is fixed, but as long as SHIFT and Click are held down, the box can be
             resized. Once the buttons are released, the box is set.
     
     When you've made your selection, you can do a number of things to it:
       - UNSELECT it:     
            By clicking the window, the selection will erase. You can also click the
            "Cancel Selection" button.
           
       - WORK ON it:     
         This will isolate the selection in your field of view. This is useful
         when there is a large amount of data in the dataset that you know you
         won't be making any immediate changes to. The program will run faster
         without these points on the screen. You'll also be able to see what
         you are working on in more detail, since the level-of-detail can be
         increased and the extraneous data won't get in your way. You can then
         merge this smaller "working set" with the larger dataset later on.
         You can work on as many successively smaller datasets as you like.
         
       - DELETE it:
         Click the "delete inside" button (a circle with an "X" in the middle
         and shading on the outside) to remove everything inside the selection
         from the working set.
       
       - DELETE everything OUTSIDE of it:
         Click the "delete outside" button (a circle with shading inside of
         it) to remove everything but what's inside of your selection.
    
      Return to Table of Contents   
   
 c. Measure Tool  
     
     Activate the measure tool by clicking on the icon of a measuring tape. It
     will turn orange when it is active.
     
     You can click anywhere on the dataset to place a marker point. Each time
     you do, a line will be connected to your previous point, and the distance
     between the two will be added to your total measurement, which is
     displayed in the lower left of the window.
     
     You can also drag the mouse to create a movable line
     
     You can clear your measurement and start over by clicking the Clear Measurement
     button
     
     The units of the measure tool are the same as those used in the original
     data file.

      Return to Table of Contents
     
 d. Plane Fit Tool  
     
     This tool is in development. Clicking it will perform a best-fit on the
     data currently being worked on. The result will be rendered in the viewer
     window.
     
     Right now, this tool is only for getting a preview of what the best-fit
     plane will look like. To obtain the actual parameters for the best-fit
     plane, you still need to use the 'planefit' tag when calling SlugView from
     Matlab.

      Return to Table of Contents
     
 e. Merging Data
     
     These tools are used in combination with the Work On function. If you've finished
     working on a small piece of your data and you want to work on a different part,
     you can merge what you've done with the rest of the dataset. There are two ways to do this:
     
     1. Merge with Superset: 
       Click the "merge with superset" button (black square being inserted
       into a larger black square), and your changes will be merged everything
       you "left behind" the last time you clicked the "work on" button.
     
     2. Subtract from Superset:  
       Click the "subtract from superset" button (grey square being removed
       from a black square), and everything in the working set will be removed
       from everything you "left behind" the last time you clicked the "work
       on" button

       **Note: The Merge and Subtract functions clear the Undo buffer.**
     
      Return to Table of Contents

 f. Point Size
     
     The program draws point clouds as a large number of small, translucent
     circles. When these circles overlap, they get brighter.
     
     The point size slider controls how big to draw a single point on the
     screen. What a reasonable value is depends on how many points you are
     viewing and how closely they are spaced. Generally, you will start zoomed
     out very far, and all the points will be overlapping each other and your
     point cloud will be very bright. This is because the computer can't draw
     points smaller than a fixed minimum size on the screen (some machines
     won't draw anything at all if the point size is below this threshold
     value). Usually, you will have to zoom in to make the points larger and
     more spaced apart on the screen before this slider will have any effect.
     If ever your point cloud appears to bright or too blurry, reducing the
     point size and/or zooming in will usually fix the problem.

      Return to Table of Contents

 g. Display Resolution
     
     SlugView allows you to control the level of detail at which to draw your
     dataset in order to maintain fast framerates.
     
     Choosing a higher number in the box in the lower right hand side of the
     window will increase the level of downsampling, i.e. the resolution will
     go down. You must click "Resample" before the change will take effect.
     
     The level of detail ONLY affects what is drawn on the screen. Selections
     always operate on the full-resolution dataset, even if you cannot see it.
     
     Return to Table of Contents

 h. Draw Line Tool  
   
      To use the Draw-Line Tool, there are two options:
           *Left-Click and drag: This enables you to draw a straight line. The
                  first point will remain locked, but the second can be moved
                  as long as the left mouse-button is held down
           *Left-Click: This will create individual points
      
      The purpose of the Draw-Line Tool is to enable you to draw lines and
      points on the screen, and to use them as reference for rotation. The lines
      and points made by this tool will rotate with the dataset
      
          *CLEAR LINES - To delete/clear the lines from the window, you must click
                  the "Clear Selection" button. They will remain until you do.
     
      **Note: The lines and points drawn by you are only displayed and
             not actually added to the dataset, so there is no risk of altering
             the point clouds **

   Return to Table of Contents
   
  i. Undo button    

    The Undo button undoes what you have just done.
    For the sake of conserving memory, the undo button has only 5 levels of undo.
    That means that only 5 previous changes are recorded. Also, important to note,
    there is no Redo button.
   
    Return to Table of Contents

  j. Cancel Selection / Clear Lines button  
     
      The Cancel Selection button has two functions. It will clear a Selection (which
      can also be done by clicking on the screen), or, more importantly,  it is the only
      way to clear the lines and points drawn by the LineDrawer.
   
    Return to Table of Contents

  k. Clear Measurement button   
   
    The Clear Measurement button is the only way (besides using the Selection tool) to clear
     a measurement. Clicking this button will remove the current measurement and clear
     the screen of measurement arrows.

    Return to Table of Contents

  l. Work On button
   
      The Work On button enables you to reduce a larger point-cloud in to a smaller one.
        The smaller point-cloud can later be merged back in to the larger. This is particularly
        useful if you have many edits to make on a smaller area. This will reduce the time
        needed to perform all operations. You can work on as many successively smaller datasets
        as you like.

    Return to Table of Contents

  m. Deleting data
     The deletion tools are used in combination with the Selection tool. The Selection tool
      draws a polygon on the screen and the two deletion tools operate on that polygon in
      different ways. Deletion functions 2-dimensionally in a 3-dimensional environment.
      This means it will delete everything in the x-y plane it creates. Up to five previous
      deletions can be undone with the Undo button.

    1. Delete inside  
        The Delete inside button will delete all points that are encased by the polygon. 
        
    2. Delete outside  
       The Delete outside button will delete all points that are not encased by the polygon.

    Return to Table of Contents

======================================================     
5) Troubleshooting
======================================================

Q: I'm viewing a pointcloud, and it looks all white and/or blurry.
Q: The "Selector" tool lags a lot when trying to draw.
Q: My pointcloud looks like pinstripes.
Q: It takes a long time to delete small bits of data.
Q: The arrow keys don't always work when trying to rotate the data.
Q: The Draw-Line tool wont draw a line or points, or sometimes stops responding while dragging.

     
 Q: I'm viewing a pointcloud, and it looks all white and/or blurry.
     
     A: Zoom in until points appear as tiny circles. Now reduce the
     point size until the data is sharp. If changing the point size does not
     seem to have any effect, you are probably still zoomed out too far.
     Changing the resolution will also reduce the whiteness by reducing
     the number of points on the screen, which will reduce the overlap--
     hence the brightness.
     
 Q: The "Selector" tool lags a lot when trying to draw.
     
     A: Reducing the Resolution will help. The tool lags because your
     computer's video processor is having difficulty rendering all the
     points of the cloud. Every time you move the selector, the screen
     has to be re-displayed.
     
 Q: My pointcloud looks like pinstripes
 
     A: More than likely, this is a precision problem. If you are using a georeferenced
     coordinate system, the numbers are too large to be displayed with precision.
     The solution for this is to change your file type from .xyz to .utm, or .pts to .gpts
     if you are using real colors. You  can change the filetype by right-clicking and
     selecting rename. Even if you are not using georeferencing, it is possible you are
     having a precision problem anyways. Try changing your file extension to .utm (or .gpts for .pts files)
     
 Q: It takes a long time to delete small bits of data.
     
     A: Use the "Work on" tool to work on smaller pieces of the data if
     you are going to make more than one change to a particular part.
     If you have a 30+ million point cloud, select maybe a 1 to 3 million
     point section of it and work on that, then merge with the larger set
     when you are done.
     
 Q: The arrow keys don't always work when trying to rotate the data.
 
    A: You have to click on the 3d window (the black area) in order for
    SlugView to recognize the signals coming from the keys. There doesn't seem
    to be any fix for this because it is about keyboard focus.
    
 Q: The Draw-Line tool wont draw a line or points, or sometimes stops responding while dragging.
 
   A: The Draw-Line tool will only draw a line or point when it is held over the
   point-cloud. If held over empty (black) space, it stops responding. This happens
   because it is dependent on the depth of the point-cloud. If there is no cloud, then
   it does not know how to draw the line.
  
    Return to Table of Contents
  
=====================================================
6) Appendix
=====================================================

a. Key and Mouse Bindings
       

--TOOL--	--KEY/BUTTON--	--FUNCTION--
Draw Line	Left-Click	Draws a single point
Draw Line	Left-Click and Drag	Draws a line with the initial point fixed. Movable until mouse is released
Draw Line	Middle-Click and Drag	Pan the image. *Note: Some systems use Left-click+Right-click as Middle-click.*
Draw Line	Right-Click and Drag	Zoom in and out
Measure	Control (Ctrl)	Uses a blue cone to show the axis of rotation
Measure	Double-Click	Moves the axis of rotation to the clicked spot
Measure	Left-Click	Creates a a series of connected points to measure
Measure	Left-Click and Drag	Draws a movable line with the initial point fixed. Movable until mouse is released
Measure	Middle-Click and Drag	Pan the image. *Note: Some systems use Left-click + Right-click as Middle-click.*
Measure	Right-Click and Drag	Zoom in and out
Rotate	Arrow-keys	Rotate the point-cloud around the x and y axes
Rotate	Arrow-keys + Z	Rotate the point-cloud around the z axis
Rotate	Control (Ctrl)	Uses a blue cone to show the axis of rotation
Rotate	Double-Click	Moves the axis of rotation to the clicked spot
Rotate	Left-Click and Drag	Rotate the point-cloud around the x and y axes
Rotate	Middle-Click and Drag	Pan the image. *Note: Some systems use Left-click + Right-click as Middle-click.*
Rotate	Right-Click and Drag	Zoom in and out
Rotate	Shift + Left-Click	Displays the xyz coordinates of the clicked point
Selector	Left-Click and Drag	Acts as a freehand tool or rectangle drawing tool to draw a polygon
Selector	Middle-Click and Drag	Pan the image. *Note: Some systems use Left-click + Right-click as Middle-click.*
Selector	Right-Click and Drag	Zoom in and out

      
 Return to Table of Contents