partiview.sgml

<!doctype linuxdoc system>

<!-- 
     Changelog:
     2000-09-25   created the changelog after a week of initial editing    PJT
     2000-10-10   made consistent with VERSION 0.1 release                 PJT
     2000-11-07   election night changes                                   PJT
     2000-11-20   document some CVS and new configure stuff for 0.3        PJT
     2000-12-21   document new movie features for the new CVS version      PJT
 -->

<article>

<!-- Title information -->

<title> Partiview (PC-VirDir)
<author> Peter Teuben
<date> 21 December 2000
<abstract>
This document helps you installing and running the development version 
of partiview.
Quite a few things in this manual have not been fleshed
out, in particular the detailed description of all the commands.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<!--------------------------------------------------------------------------- -->

<sect> Installation
<p>

This assumes you have the October 2000 release (version 0.1 or later) of 
<bf/partiview/, not the earlier "<bf/gview/" release that was described
in earlier versions of this document. We keep copies of some support
files on our initial
<htmlurl url="http://www.astro.umd.edu/nemo/amnh"
        name="http://www.astro.umd.edu/nemo/amnh"> website. Note that
this current development release is only documented for work under Linux,
although we expect it to work for at least SGI and maybe Solaris too.

<sect1> MESA/OpenGL
<p>
    First make sure <tt/Mesa/ is installed, for <tt/redhat6.2/
       there are rpm files
       available.  Check if you have the following:

<tscreen><code>
       % rpm -qa | grep Mesa
       Mesa-3.2-2
       Mesa-devel-3.2-2
</code></tscreen>

       You should see both. Some packages will use <tt/libMesaGL/, others
       <tt/libGL/. The <tt/configure/ script (see below) 
       should take care of the two possible options.
<p>
	Homepage: <htmlurl url="http://mesa3d.sourceforge.org"
			  name="http://mesa3d.sourceforge.org">
<p>
	Redhat packages: (part of powertools I believe)

<sect1> FLTK
<p>
    Also make sure <tt/fltk/ is installed.  If you got my version, do this (as
       root)

<tscreen><code>
       % cd <where-ever>/fltk-1.0.9
       % make install
</code></tscreen>

       (you only need it if you want to recompile the program at some point,
        not if you just want to run it)
<p>
	Homepage: <htmlurl url="http://www.fltk.org/"
			   name="http://www.fltk.org/">
<p>
	Redhat packages: <htmlurl url="http://www.cs.cornell.edu/nogin/RPM/fltk-devel.html"
			       name="http://www.cs.cornell.edu/nogin/RPM/fltk-devel.html">

<sect1> partiview
<p>
     Now compile the program
     should be in the <tt/src/ directory already:

<tscreen><code>
       % tar zxf partiview-0.5.tar.gz

       % cd partiview-0.5/src
       % make clean                (if you really must compile a new executable)
       % ./configure               (GNU autoconf toolset to ease installation)
       % make depend               (might need to make new local dependancies)
       % make partiview	           (should not have to edit Makefile anymore)
</code></tscreen>

<sect1> CVS
<p>
Since version 0.3 <tt/partiview/ is under CVS control, and occasionally we
will stamp out a new release when we deem it stable. Anonymous CVS may also
be offered, but this is not currently enabled. Currently the 
CVS repository machine is
<tt/grus.astro.umd.edu/ and you will need to setup your developers account with
Peter (<tt/teuben@astro.umd.edu/). Here's a sample session with some commonly
used CVS commands:

<tscreen><code>
 setenv CVSROOT   :pserver:pteuben@grus.astro.umd.edu:/grus/cvsroot
 setenv CVSEDITOR emacs
 setenv CVS_RSH   ssh           (not needed for pserver access though)

 mkdir ~/cvsstuff
 cd ~/cvsstuff
 cvs checkout partiview              # get a new local sandbox to work in, or

 cvs -n -q update partiview          # check if others had made any changes
 cvs update partiview                # if so, update your sandbox and/or resolve conflicts
 cd partiview/src
 ./configure
 emacs partibrains.c                 # edit some files
 make all                            # compile the program
 ./partiview                         # test the program
 emacs partipanel.cc                 # edit another file
 make all                            # check if it still compiles

 cvs -n -q update                    # check if anybody else made changes
 cvs update                          # if so, update your sandbox again, resolve conflicts

 cvs commit                          # and commit your changes
 cd ../..

 cvs release partiview               # if you want to release and remove this sandbox

</code></tscreen>

<!--------------------------------------------------------------------------- -->
<sect> Directory structure
<p>

Here is the proposed directory structure, as per version 0.1:

<p>
<tscreen><verb>
     partiview/             root directory
     partiview/src          source code
     partiview/data         sample datafiles (e.g. Hipparcos Bright Star Catalogue)
     partiview/doc          manual (sgml, and derived  html, txt, ps/dvi)
     partiview/nemo         NEMO specific converters/code
     partiview/starlab      STARLAB specific converters/code
     partiview/tutor        examples of tutorial type code (added in 0.2)
     partiview/windows      windows executables/support (old)
     
</verb></tscreen>

<sect> Running the program
<p>
First we describe a simple example how to run <tt/partiview/ with a supplied sample
dataset. Then we describe the different windows that <tt/partiview/ is made up of, and
the different commands and keystrokes it listens to.

<sect1>  Example 1: Hipparcos Bright Star Catalogue 3-D viewing
<p>

Now start the program using one of the sample  "speck" files in the
<tt/data/ directory:

<tscreen><code>
       % cd partiview/data
       % ./hipbright
</code></tscreen>

and this should come up with a display. You should probably enlarge the
window a bit. Mine comes up in roughly a 300 by 300 display window,
which may be a bit small (certainly on my screen :-)


Hit the TAB key to bring focus to the (one line) command window inbetween
the log screen (top) and viewing screen (bottom). Type the commands

<tscreen><code>
	fov 50				(field of view 50 degrees)
	jump 0 0 0 80 70 60		(put yourself in the origin
					and look at to euler angles
					RxRyRz (80,70,60)

</code></tscreen>

and it should give a nice comfy view :-)  If you ever get lost, use
the <tt/jump/ command to go back to a known position and/or viewing
angle.

<figure loc="tbp">
<img src="pv1.gif">
<caption>partiview view</caption>
</figure>

<p>
[spatial units are parsecs, angle units are degrees]
<p>
Now play with the display, use the 't', 'r', 'f' and 'o' keys in the viewing
window and use the
left and mouse buttons down to (carefully) move around a bit, and make
yourself comfortable with moving around. Using the 't' button you get
some idea of the distance of the stars by moving back and forth a little
(the parallax trick). In fact, if you 't' around a little bit, you may
see a green line flashing through the display. That is on of the  RGB
(xyz) axes attached to the (0,0,0) [our sun] position.  You should see
Procyon and Sirius exhibit pretty large parallaxes, but Orion is pretty
steady since it is several hundred parsecs away.
If you move the right mouse button you will zoom in/out and 
should see our Sun flash by with the red-green-blue axes.
<p>
The RGB axes represent the XYZ axes in a cartesian system. For the Hipparchos
data the X axis points to RA=0h, Y axis to RA=6h, both in the equatorial
plane, and the X axis points to the equatorial north pole.
<p>
Try and use the middle mouse button (or the 'p' key)  to click on Sirius
or Procyon, and see if you can get it to view its properties.  Now use
the 'P' key to switch center to rotation to that star. Sirius is
probably a good choice. Move around a bit, and try and get the sun and orion
in the same view :-)
<p>
[NOTE: these Hipparcos data do not have reliably distance above
100-200 pc, so Orion's distances are probably uncertain to 30%]
<p>

A little bit on the types of motion, and what the mouse buttons do

<tscreen><code>

              |     left            middle          right
              |     Button-1        Button-2        Button-3
--------------------------------------------------------------------
f (fly)       |     fly             'pick'          zoom
o (orbit)     |     orbit           'pick'          zoom
r (rotate)    |     rotate X/Y      'pick'          rotate Z (+bug?)
t (translate) |     translate       'pick'          zoom

</code></tscreen>

The point of origin for rotations can be changed with the 'P' button.
First you can try and pick ('p' or Button-2) a point, and if found,
hit 'P' to make this point the new rotation center default.



<tscreen><code>
red   = X axis
green = Y axis
blue  = Z axis
</code></tscreen>

<sect1> Top Row
<p>
The top row, from left to right, shows the following buttons:
<p>
<descrip>

<tag> More </tag>
Pulldown; item

<tag> [g1] </tag>
Pulldown g1 (or whichever group) is the currently selected group. See command <tt/object/ ?
to make aliases which group is defined to what object.

<tag> [f]ly </tag>
Pulldown to select fly/orbit/rot/tran, which can also be activate
by pressing the f/o/r/t keys inside the viewing window.

<tag> point </tag>
Toggle to turn the points on/off 

<tag> poly </tag>
Toggle to turn polygons on/off 

<tag> lbl </tag>
Toggle to turn labels on/off 

<tag> tex </tag>
Toggle to turn textures on/off 

<tag> box </tag>
Toggle to turn boxes on/off 

<tag> #.### </tag>
The current displayed value of <tt/logslum lum/ (see below)

<tag> logslum lum </tag>
Slider controlling a <bf/datavar/ variable (the one selected as
luminosity)

</descrip>

<sect1> Second and Third Row
<p>
The second and third row from the top control playing sequences
of time, including a trip meter. This 
time-control bar is only visible when the object has a nonzero
time range.

<descrip>

<tag> T </tag>
The current time (or offset from the tripmeter)

<tag>trip </tag>

<tag>back </tag>

<tag> dial </tag>

<tag> |< </tag>

<tag> >| </tag>

<tag> + </tag>
Current last time where tripmeter was set. You can reset to
the first frame with the command <tt/step 0/


<tag> #.#### </tag>
(Logarithmic) value denoting the speed of animation.

<tag> << </tag>  toggle movie move backwards in time

<tag> >> </tag>  toggle movie move forwards in time


</descrip>


<sect1> Fourth Row
<p>
The fourth row from the top
controls loading and playing sequences of moving through space
<p>
<descrip>

<tag> Load... </tag>
Brings up a filebrowser to load a <bf/.wf/ path file. This is a file with on each
line 7 numbers: xyz location, RxRyRz viewing direction, and FOV (field of view).

<tag> Play </tag>
Play the currently loaded path

<tag> << < [###] >>> </tag>
Control individual path frames

<tag> slider </tag>
Slider

</descrip>

<sect1> Logfile window
<p>
The third window from the top contains a logfile of commands gives, and can be resized 
by dragging the bar between command window and viewing window. The Logfile windows also
has a scroll bar on the left.
<p>

<sect1> Command window
<p>
The Command window is a single line entry window, in which Control Commands can be given.
Some commands show their result in the Logfile window, others on the originating console.
(unlike Data Commands, which show no feedback).
<p>

<sect1> Viewing window
<p>
The Viewing window is where all the action occurs. Typically this is where you give
single keystroke commands and/or move the mouse for an interactive view of the data.
It can be resized two ways: either by resizing the master window, or by picking up
the separator between Viewing window and Command window above.

<sect1> Example 2: a (starlab) animation
<p>
Setting up a small animation in for example Starlab can be done quite simply as follows:

<tscreen><code>
  mkplummer -i -n 20 | mkmass -l 0.5 -u 10.0 | scale -s | kira -d 2 -D x10 > run1
     (lots of output from kira will still appear on the screen)
  partiview run1.cf
  cat run1.cf

     datavar 0 id
     datavar 1 mass
     datavar 2 clump
     kira data2 1
     eval every
     eval lum mass 0 0.01
     eval psize 100
     eval cment 1   1 .7 .3
     eval color clump exact
       
</code></tscreen>


<sect1> Example 3: stereo viewing 
<p>
The 's' key within the viewing window toggles stereo viewing. By default each
object is split in a blue and a red part, that should be viewed with a pair
of red(left)/blue(right) glasses. Red/Green glasses are also popular in the
industry, and you need the change the color 

<!--------------------------------------------------------------------------- -->
<sect> Commands
<p>
There are two types of commands in <tt/partiview/: 
Control Commands and Data Commands.
Probably the most important difference between the two is that Control
Commands return feedback to the user, whereas Data Commands
are interpreted "as is". But once in Control Command mode,
you can still let commands become Data Commands (using the 
<tt/add/ Control Command, and in Data Command mode one can
let a command be a Control Command by preceding it with the
<tt/eval/ command. Before we explain the two types of Commands in
detail, a few concepts are needed:

<!--------------------------------------------------------------------------- -->
<sect1> Textures
<p>

<!--------------------------------------------------------------------------- -->
<sect1> Coordinates and Coordinate Transformations
<p>

<!--------------------------------------------------------------------------- -->
<sect1> Control Commands
<p>

(see also partibrains.c::specks_parse_args); these are commands typically
called as "<tt/eval/ <it/commands..../".  Most (all?) commands can be
prefixed with a generic group designation, <tt/gN/, to which this command
applies. See the <tt/object/ Data Command how to place different data in 
different groups.


<descrip>

<tag>
read		
</tag>
read a specks file

<tag>
include		
</tag>
NOTYET, does the same as the <bf/read/ command.

<tag>
on
</tag>


<tag>
off
</tag>

<tag>
enable
</tag>
see the <tt/on/ command.

<tag>
disable
</tag>
see the <tt/off/ command.

<tag>
eval <it/control-command/
</tag>
This should be a no-op, since it would normally allow you to
give a Control Command in Data Command mode. 

<tag>
add <it/data-command/
</tag>
This will enter a Data Command while in Control Command mode.

<tag>
async		
</tag>
This will allow you to execute a shell command (/bin/sh) subprocess
of which  its <it/stdout/ will be taken as a stream of Control Commands.

<tag>
update		
</tag>
Ensures the screen is updated.

<tag>
hist <it/datavar/ [-l] [-c] [-t] [<it/minval/] [<it/maxval/]
</tag>
Generates a histogram of values of the datafield named by <it/dataval/.
<p>
-l logarithmic, -c clipped, -t threshed.

<tag>
bound
</tag>
Reports 3D extent of the data

<tag>
speed
</tag>
(note that <tt/fspeed/ has been deprecated)

<tag>
run
</tag>

<tag>
fade
</tag>

<tag>
clipbox [cb] ....
</tag>
Selects a 3D clipbox
    <descrip>
    <tag> <it/xmin ymin zmin  xmax ymax zmax/ </tag> <p>
    <tag> <it/xcen,ycen,zcen xrad,yrad,zrad/  </tag><p>
    <tag> <tt/on/  </tag><p>
    <tag> <tt/off/ </tag><p>
    </descrip>


<tag>
object
</tag>

<tag>
tfm
</tag>

<tag>
bgcolor
</tag>

<tag>
gN <it/control-command/
</tag>
Generic prefix to any control command

<p>
	BEGIN	!CAVEMENU	(virdir emulation)

<tag>
stereo <it/float/ <it/color/
</tag>
Add stereo separation. Numbers can be 0.02 to 0.1 or -0.02 to -0.1 to swap
eyes.

<tag>
snapset
</tag>

<tag>
snapshot
</tag>

<tag>
move on|off
</tag>

<tag>
move-objects on|off
</tag>

<tag>
clip
</tag>

<tag>
ortho
</tag>
NOTYET

<tag>
fov <it/float/
</tag>
Get or set field of view (in degrees)

<tag>
fovy <it/float/
</tag>
Get or set field of view (in degrees)

<tag>
focal <it/float/
</tag>
Get or set the focal length. Use the 's' key to toggle 
stereo display.

<tag>
jump [<it/X Y Z/] [<it/Rx Ry Rz/]
</tag>
Get or set the current position (XYZ) and viewing (RxRyRz) angle

<tag>
rdata
</tag>
Read a (<tt/.wf/) file describing a path through space.

<tag>
readpath
</tag>
Read a (<tt/.wf/) file describing a path through space.

<tag>
play
</tag>

<tag>
frame
</tag>
Get or set current frame

<tag>
int[erest] [X Y Z Radius]
</tag>
Get or set region of interest

<tag>
cen[ter] [X Y Z Radius]
</tag>
Get or set region of interest

<tag>
censize
</tag>
interest-marker size
<p>
	END	!CAVEMENU	(virdir emulation)

<tag>
step [step-number]
</tag>
This either reports at which step you are, or changes the view
to the selected step-number. If preceded with a plus or minus
sign, the step is relative to the current frame.

<tag>
fwd
</tag>

<tag>
gscale
</tag>
scaling particles

<tag>
clearobj
</tag>

<tag>
every   N
</tag>
Get or set the value to display every N-th particle

<tag>
color
</tag>

<tag>
datavar [dv]
</tag>

<tag>
datawait   on|off
</tag>

<tag>
lum
</tag>

<tag>
cmap    <it/filename/
</tag>
Load (ascii) filename with RGB values 

<tag>
boxcmap
</tag>

<tag>
cment
</tag>

<tag>
boxcment
</tag>

<tag>
only
</tag>

<tag>
thresh
</tag>

<tag>
rawdump
</tag>

<tag>
slum
</tag>

<tag>
scale-lum
</tag>

<tag>
see
</tag>

<tag>
show
</tag>

<tag>
showbox
</tag>

<tag>
hide
</tag>

<tag>
hidebox
</tag>

<tag>
box
</tag>

<tag>
boxes
</tag>

<tag>
boxlabel
</tag>

<tag>
boxaxes
</tag>

<tag>
boxscale
</tag>

<tag>
go
</tag>

<tag>
gobox
</tag>

<tag>
goboxscale
</tag>

<tag>
psize
</tag>

<!-- DEPRECATED COMMAND
<tag>
pointsize
</tag>
-->

<tag>
polysize
</tag>

<tag>
polylum
</tag>

<tag>
polyminpixels
</tag>

<tag>
labelminpixels
</tag>

<tag>
labelsize
</tag>

<tag>
lsize
</tag>

<tag>
point
</tag>

<tag>
points
</tag>

<tag>
poly
</tag>

<tag>
polygon
</tag>

<tag>
texture [tx]
</tag>

<tag>
txscale		
</tag>

<tag>
polyorivar
</tag>

<tag>
texturevar
</tag>

<tag>
label labels
</tag>

<tag>
laxes
</tag>

<tag>
polyside(s)
</tag>
number of sides a polygon should have

<tag>
gamma
</tag>

<tag>
alpha
</tag>

<tag>
fast
</tag>
see also <tt/ptsize/

<tag>
ptsize
</tag>
makes more sense than <tt/fast/.

<tag>
fog
</tag>

<tag>
menu fmenu
</tag>

<p>

			BEGIN CAVEMENU
	pos P1 P2
	wall P1
	hid [P1]
	show [P1]
	h  [P1]
	demandfps [P1]
	font
	help
	?
			END CAVEMENU	
<p>

<tag>
datascale
</tag>

<tag>
where  [w]
</tag>

</descrip>

<!--------------------------------------------------------------------------- -->
<sect1> Data commands
<p>

(see also partibrains.c::specks_read)
<p>
Lines starting with <tt/#/ will be skipped. The following Data Commands
can be placed in a data file, as opposed to a Control Command, 
which are entered in the command window (but see the <tt/eval/ command below):

<descrip>

<tag> 
read <it/file/ 
</tag> 
read a <tt/speck/ formatted file. Recursive, commands can nest. (strtok ok??)

<tag> 
include  <it/file/
</tag>
read a <tt/speck/ formatted file.

<tag>
ieee [-t time] <it/file/
</tag>
read a IEEEIO formatted file, with optional timestep number (0 based).
Support for this type of data must be explicitly compiled into the program.

<tag>
object <it/gN=ALIAS/
</tag>
Defines/Selects a particular group number (N=1,2,3....) to an ALIAS. In
command mode you can use <tt/gN=ALIAS/. Any data following this command
will now belong to this group.

<tag>
object <it/ObjectName/
</tag>
Select an existing group. Following data will now belong to this group.

<tag>
sdbvars <it/var/
</tag>
Choose which data fields to
extract from binary sdb files (any of: <tt/mMcrogtxyzSn/) for subsequent
<tt/sbd/ commands.

<tag>
sdb [-t time] <it/file/
</tag>
Read an SDB (binary) formatted file, with optional timestep number (0 based).

<tag>
box[es] <it/..../
</tag>
Draw a box, using any of the following formats:
<p>
    <descrip>
    <tag> <tt/xmin ymin zmin  xmax ymax zmax/ </tag> <p>
    <tag> <tt/xmin,xmax ymin,ymax zmin,zmax/   </tag><p>
    <tag> <tt/xcen,ycen,zcen xrad,yrad,zrad/  </tag><p>
    <tag> <tt/[-t time] [-n boxno] [-l level] xcen,ycen,zcen  xrad,yrad,zrad /  </tag><p>
    </descrip>
<tt/level/ determines color.

<tag>
annot <it/[-t timestep] string .../
</tag>

<!-- DEPRECATED COMMAND
<tag>
size <it/float/
</tag>
-->

<!-- DEPRECATED COMMAND
<tag>
scale <it/float/
</tag>
-->

<tag>
tfm 
</tag>
Object-to-world transformation. Either 
<it/tx ty tz rx ry rz/ or 16 numbers for 4x4 matrix.
(<it/something> must contain <tt/* / h p r/)

<tag>
eval <it/command/
</tag>
execute a Control Command.

<tag>
feed  <it/command/
</tag>
Synonymous for <tt/eval/

<tag>
VIRDIR  <it/command/
</tag>
Synonymous for <tt/eval/