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

<article>

<!-- Title information -->

<title> Partiview (PC-VirDir)
<author> Peter Teuben
<date> 10 October 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 higher) of 
<bf/partiview/, not the earlier "<bf/gview/" release that was described
in earlier versions of this document.
<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.
<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 (if you really want to) the program, normally a (linux) executable
     should be in the <tt/src/ directory already:

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

       % cd partiview-0.1/src
       % make clean                (if you really must compile a new executable)
       % ./configure               (creates a new Makefile from Makefile.in)
       % make partiview	           (might need to edit the Makefile)
</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)
     partiview/doc          manual (sgml, and derived  html, txt, ps/dvi)
     partiview/nemo         NEMO specific converters/code
     partiview/starlab      STARLAB specific converters/code
     partiview/windows      windows executables/support (old)
     
</verb></tscreen>

<sect> Running the program

<sect1> Simple example: hipparcos bright stars
<p>

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

<tscreen><code>
       % cd partiview-0.1/src        
       % ./hipbright
</code></tscreen>

and this will 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 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
					(60,70,60)

</code></tscreen>

and it should give a nice comfy view :-)  

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

<p>
[spatial units are parsec, angle units are degrees]
<p>
Now play with the display, use 't', 'r', 'f' and 'o' keys 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 atteched to the (0,0,0) [our sun] position.  You should see
Procyon and Sirius exhibit pretty large parallaxes, but Orion is pretty
steady. 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>
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>
item

<tag> [g1] </tag>
g1

<tag> [f]ly </tag>
Shortcut 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> logslum lum </tag>
Slider controlling a <bf/datavar/ variable (which?)

</descrip>


<sect1> Second Row
<p>
The second row 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>

<sect> Bugs, Features and Limitations
<p>

Here is a list of known peculiarities, some of them bugs, others just
features and others limitations, and there is always that class of
things I simply have not understood how it works.
<enum>
<item> in rotate mode, if you change the center of rotation with 'P',
button-1 works fine, but button-3 does not rotate around the
new point correctly. It seems to remember the old (or 0,0,0)
origin.

</enum>

<sect> Limitations w.r.t. VirDir:
<p>

<enum>
<item>
cannot set an auto-motion, as we can in the dome, although one could
of course load a path and move through the dataset :-)
I was able to make a path (*.wf) file and load that though.

<item>
how do we load in a timeseries again? I tried something like

</enum>

<tscreen><verb>

datavar 0 colorb_v
datavar 1 lum
datavar 2 Mv
datavar 3 mv
datatime 0
0 0 0  0.5  .008  5.2  -26.5
0 0 0  0.5  .008  5.2  -26.5
277.1 0.0 223.3  -0.02 2.87 -1.1 6.6 # 0000+3851
190.5 0.2 150.4  0.95 1.44 -0.4 6.5 # 0000+3818
...
207.6 7.7 411.3  1.00 5.8 -1.9 6.4 # 0008+6312
393.7 14.7 -124.8  1.66 6.14 -2.0 6.1 # 0008-1735
datatime 1
26.5 1.0 19.7  0.50 0.0358 3.6 6.2 # 0008+3638
....
84.8 6.9 -80.0  1.21 0.401 1.0 6.3 # 0018-4314
datatime 2
87.4 7.4 -13.6  1.21 2.97 -1.2 3.6 # 0019-08 iota Cet Deneb Kaitos Shemali
...
</verb></tscreen>
but that didn't seem to do much. Neither with the <tt/>/ or 
<tt/</ keys or the <tt/step/ command....



<sect> VIRDIR commands
<p>

(see also partibrains.c::specks_parse_args)


<descrip>

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

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

<tag>
on
</tag>

<tag>
off
</tag>

<tag>
enable
</tag>

<tag>
disable
</tag>

<tag>
eval
</tag>

<tag>
add
</tag>

<tag>
async		
</tag>
specks_add_async

<tag>
update		
</tag>
parti_update

<tag>
hist
</tag>

<tag>
bound
</tag>

<tag>
fspeed
</tag>

<tag>
speed
</tag>

<tag>
run
</tag>

<tag>
fade
</tag>

<tag>
clipbox [cb]
</tag>

<tag>
object
</tag>

<tag>
tfm
</tag>

<tag>
bgcolor
</tag>

<p>
	BEGIN	!CAVEMENU	(virdir emulation)

<tag>
stereo
</tag>

<tag>
snapset
</tag>

<tag>
snapshot
</tag>

<tag>
move
</tag>

<tag>
move-objects
</tag>

<tag>
clip
</tag>

<tag>
ortho
</tag>

<tag>
fov
</tag>

<tag>
fovy
</tag>

<tag>
focal
</tag>

<tag>
jump
</tag>

<tag>
rdata
</tag>

<tag>
readpath
</tag>

<tag>
play
</tag>

<tag>
frame
</tag>

<tag>
int[erest]
</tag>

<tag>
cen[ter]
</tag>

<tag>
censize
</tag>

<p>
	END	!CAVEMENU	(virdir emulation)

<tag>
step
</tag>

<tag>
fwd
</tag>

<tag>
gscale
</tag>

<tag>
clearobj
</tag>

<tag>
every
</tag>

<tag>
color
</tag>

<tag>
datavar [dv]
</tag>

<tag>
datawait
</tag>

<tag>
lum
</tag>

<tag>
cmap
</tag>

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

<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		BUG in 'tx' name?
</tag>

<tag>
polyorivar
</tag>

<tag>
texturevar
</tag>

<tag>
label labels
</tag>

<tag>
laxes
</tag>

<tag>
polyside
</tag>

<tag>
gamma
</tag>

<tag>
alpha
</tag>

<tag>
fast
</tag>

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


<sect> Data commands
<p>

(see also partibrains.c::specks_read)
<p>
lines starting with <tt/#/ will be skipped. The following commands can be placed in
a data file, as opposed to a VIRDIR command;


<descrip>

<tag> 
read <it/file/ 
</tag> 

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


<tag>
ieee <it/file/
</tag>
read a IEEEIO formatted file. Support for this must be explicitly 
compiled into the program.

<tag>
object
</tag>
parti_object()

<tag>
sdb <it/file/
</tag>
read an SDB (binary) formatted file.

<tag>
sdbvars <it/var/
</tag>
Select <it/var/ (any of: <tt/mMcrogtxyzSn/)

<tag>
box[es] <it/..../
</tag>
Select a box, using 
<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>

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

<tag>
size <it/float/
</tag>

<tag>
scale <it/float/
</tag>

<tag>
tfm 
</tag>
<it/something> must contain <tt/* / h p r/

<tag>
eval <it/command/
</tag>
execute a VIRDIR command

<tag>
feed  <it/command/
</tag>
execute a VIRDIR command

<tag>
VIRDIR  <it/command/
</tag>
execute a VIRDIR command

<tag>
ignorefirst, ignorepgc
</tag>

<tag>
filepath <it/path/
</tag>
A colon separate list of directories in which datafiles
will be searched for. If preceded with the <tt/+/ symbol,
this list will be appended to the current <it/filepath/.

<tag>
texture [-lmnMDB] <it/txno file.sgi/ 
</tag>
    <descrip>
    <tag> -l(inear)  </tag> <p>
    <tag> -m(ipmap) </tag>  <p>
    <tag> -n(earest) </tag>  <p>
    <tag> -M(odulate) </tag>  <p>
    <tag> -D(ecal) </tag>  <p>
    <tag> -B(lend) </tag>  <p>
    </descrip>
<tag>
polyorivar
</tag>

<tag>
texturevar
</tag>

<tag>
texturevarord
</tag>

<tag>
coord <it/name ... 16 world-to-coord tfm floats (GL order)/
</tag>

<tag>
dataset <it/indexno datasetname/
</tag>
<it/indexno/ is an integer, 0 being the first one.

<tag>
datavar <it/indexno string float float/
</tag>

<tag>
datatime <it/indexno/
</tag>

<tag>
<it/Xpos Ypos Zpos Var1 .... /
</tag>
These lines, with XYZ positions in the first 3 columns, will make up the bulk
of the dataset. The 4th and subsequent columns contain the values of the
datavariables as named with the <bf/datavar/ commands.

</descrip>

<sect> Viewing Window Commands 
<p>

Commands that you can give from within the viewing window are all single
keystroke commands, often combined with moving the mouse.


<tscreen><verb>

TAB		set focus to command window, so you can give commands
S		toggle STEREO mode (need blue/red glasses :-)
		modes:	mono redcyan crosseyed glasses

playmodes:
	s	playnow
	l	loop (rock)
	f,e	playevery=1
	r,t	playevery=0

Gview.cpp : Fl_Gview::handle()
	w	reset?
	r	ROTATE mode
	p
	P	pick
	f	FLY mode
	t	TRANSLATE mode
	o	ORBIT mode
	O	toggle perspective mode
	v	make field of view larger
	V	make field of view smaller
	^v	toggle debug output
	@	dname [g1]  
	=	show debug matrix output
	ESC	exit


</verb></tscreen>

</article>