Newer
Older
30 August 2001
partiview is a program that enables you to visualize and animate par-
ticle data. partiview runs on relatively simple desktops and laptops,
but is mostly compatible with its big brother VirDir. 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 par-
ticular the detailed description of all the commands.
______________________________________________________________________
Table of Contents
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
1. Installation
1.1 MESA/OpenGL
1.2 FLTK
1.3 partiview
3.1 Example 1: Hipparcos Bright Star Catalogue 3-D viewing
3.3 Group row (optional)
3.4 Time Animation rows (Optional)
3.5 Camera (path) Animation row
3.6 Logfile window
3.7 Command window
3.8 Viewing window
3.9 Example 2: a (starlab) animation
3.10 Example 3: stereo viewing
4.1 Control Commands
4.2 I/O commands
4.3 Object group commands
4.4 View commands
4.5 Particle Display Commands
4.6 Particle subsetting & statistics
4.7 Boxes
4.8 Data commands
4.9 Kira/Starlab
4.9.1 Kira particle attributes
4.9.2 Hertzsprung-Russell diagram
4.9.3 kira control commands
4.10 Textures
4.11 Coordinates and Coordinate Transformations
5. Viewing Window Keyboard Shortcuts
6. Partiview and NEMO
7. Tips
______________________________________________________________________
This assumes you have the July 2001 release (version 0.6 or later) of
ppaarrttiivviieeww, not the earlier "ggvviieeww" release that was described in
earlier versions of this document. We keep copies of some Linux
support files (Mesa, FLTK) on our current
http://www.astro.umd.edu/nemo/amnh website. Although more current
versions of support libraries may be available, they may not have been
tested out. Note that this current development release is only
documented for work under Linux (redhat 6.2 and 7.1 have been tested),
although we expect it to work for at least SGI and maybe Solaris too.
partiview needs two libaries to compile: OpenGL (or MESA) for the
drawing operations, and FLTK for the window makeup.
First make sure Mesa is installed, for redhat6.2 there are rpm files
available. Check if you have the following:
______________________________________________________________________
% rpm -qa | grep Mesa
Mesa-3.2-2
Mesa-devel-3.2-2
% rpm -i Mesa-3.2-2.i686.rpm Mesa-devel-3.2-2.i686.rpm
______________________________________________________________________
You should have both installed. Some packages will use libMesaGL,
others libGL. The configure script (see below) should take care of the
two possible options.
Redhat packages: (part of powertools I believe)
Mesa3D is under continuous development. As of this writing the stable
release is 3.4.2, but it has not been tested with the current
partiview release. Redhat 7.1 comes with Mesa-3.4 and also works with
partiview.
11..22.. FFLLTTKK
Also make sure fltk is installed. If you got my version, do this (as
root)
______________________________________________________________________
% locate libfltk.a
% locate Fl_Slider.h
______________________________________________________________________
(you only need it if you want to recompile the program at some point,
not if you just want to run it)
Homepage: http://www.fltk.org/
Redhat packages: http://www.cs.cornell.edu/nogin/RPM/fltk-devel.html
Find rpms: http://rpmfind.net
FLTK is under continuous development. As of this writing the latest
release is 1.0.10, but has not been tested with the current partiview
release.
Extract the tarball, and install the program from within the src
directory:
______________________________________________________________________
% cd partiview-0.6/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)
______________________________________________________________________
Since version 0.5 partiview is under CVS control, and occasionally we
will stamp out a new release when we deem it stable. Anonymous or
read-only CVS access is also offered. Currently the CVS repository
machine is cvs.astro.umd.edu and you will need to setup your
developers account with Peter (teuben@astro.umd.edu). Here's a sample
session with some commonly used CVS commands:
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
______________________________________________________________________
setenv CVSROOT :pserver:myname@cvs.astro.umd.edu:/home/cvsroot
setenv CVSEDITOR emacs
setenv CVS_RSH ssh (not needed for pserver access though)
cvs login (only needed once, and only for pserver type access)
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 kira_parti.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
______________________________________________________________________
Here is the directory structure, as per version 0.1:
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
First we describe a simple example how to run partiview with a
supplied sample dataset. Then we describe the different windows that
partiview is made up of, and the different commands and keystrokes it
listens to.
33..11.. EExxaammppllee 11:: HHiippppaarrccooss BBrriigghhtt SSttaarr CCaattaalloogguuee 33--DD vviieewwiinngg
Start the program using one of the sample "speck" files in the data
directory:
______________________________________________________________________
% cd partiview/data
% ./hipbright
or
______________________________________________________________________
and this should come up with a display familiar to most of us who
watch the skies. 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 :-) (Hint: the .partiviewrc file may
contain commands like eval winsize 600 400.)
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
______________________________________________________________________
fov 50 (field of view 50 degrees)
jump 0 0 0 80 70 60 (put yourself in the origin
and look at euler angles
RxRyRz (80,70,60)
______________________________________________________________________
and it should give another nice comfy view :-) If you ever get lost,
use the jump command to go back to a known position and/or viewing
angle.
Note that spatial units for this dataset are parsecs, though angular
units are degrees for any data in partiview.
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. This is one 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.
The RGB axes represent the XYZ axes in a cartesian system. For the
Hipparcos data the X (red) axis points to RA=0h, Y (green) axis to
RA=6h, both in the equatorial plane, and the Z (blue) axis points to
the equatorial north pole.
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 :-)
[NOTE: these Hipparcos data do not have reliably distance above
100-200 pc, so Orion's distances are probably uncertain to 30%]
A little bit on the types of motion, and what the mouse buttons do
______________________________________________________________________
| left middle right
| Button-1 Button-2 Button-3 Shift Button-1
------------------------------------------------------------------------------------
f (fly) | fly 'pick' zoom
o (orbit) | orbit 'pick' zoom
r (rotate) | rotate X/Y 'pick' rotate Z (+bug?) translate
t (translate) | translate 'pick' zoom
______________________________________________________________________
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.
______________________________________________________________________
red = X axis
green = Y axis
blue = Z axis
______________________________________________________________________
33..22.. TToopp RRooww
The top row, from left to right, shows the following buttons:
Offers some mode switches as toggles: inertia for continues spin
or motion, and a H-R Diagram to invoke a separate H-R diagram
window.
Pulldown g1, g2, ... (or whichever group) is the currently
selected group. See object command to make aliases which group
is defined to what object. If multiple groups are defined, the
next row below this contains a list of all the groups, and their
aliases, so you can toggle them to be displayed.
Pulldown to select fly/orbit/rot/tran, which can also be
activate by pressing the f/o/r/t keys inside the viewing window.
ppooiinntt
Toggle to turn the points on/off. See also the points command.
Toggle to turn polygons on/off. See also the polygon command.
Toggle to turn labels on/off. See also the label command.
Toggle to turn textures on/off. See also the texture command.
Toggle to turn boxes on/off. See also the boxes command.
##..######
The current displayed value of the logslum lum slider (see
below)
Slider controlling the logarithm of the ddaattaavvaarr variable
selected as luminosity (with the lum command).
33..33.. GGrroouupp rrooww ((ooppttiioonnaall))
When more than one group has been activated (groups of particles or
objects can have their own display properties, and be turned on and
off at will), a new Group Row will appear as the 2nd row.
Left-clicking (button 1) on a button toggles the display of that
group; right-clicking (button 3) enables display of the group, and
also selects it as the current group for GUI controls and text
commands.
33..44.. TTiimmee AAnniimmaattiioonn rroowwss ((OOppttiioonnaall))
For time-dependent data, the third and fourth row from the top control
the currently displayed data-time. This time-control bar is only
visible when the object has a nonzero time range.
TT Shows the current time (or offset from the tripmeter). The
absolute time is the sum of the TT and ++ fields. Both are
editable. See also the step control command.
ttrriipp
Press to mark a reference point in time. The T field becomes
zero, and the + field (below) is set to current time. As time
passes, T shows the offset from this reference time.
bbaacckk
Press to return to reference time (sets T to 0).
++ Current last time where tripmeter was set. You can reset to the
first frame with the command step 0
ddiiaall
Drag to adjust the current time. Sensitivity depends on the
speed setting; dragging by one dial-width corresponds to 0.1
wall-clock second of animation, i.e. 0.1 * _s_p_e_e_d in data time
units.
||<<
>>||
Step time backwards or forwards by 0.1 * _s_p_e_e_d data time units.
See also the < and > keyboard shortcuts.
toggle movie move forwards in time Toggle animating backwards or
forwards in time, by 1 * _s_p_e_e_d data time units per real-time
second. See also the {, ~, and } keyboard shortcuts.
##..########
(Logarithmic) value denoting _s_p_e_e_d of animation. See also the
speed control command.
33..55.. CCaammeerraa ((ppaatthh)) AAnniimmaattiioonn rrooww
The fifth (or 4th or 3rd, depending if Group and/or Time rows are
present) row from the top controls loading and playing sequences of
moving through space.
PPaatthh......
Brings up a filebrowser to load a ..wwff path file. This is a file
with on each line 7 numbers: xyz location, RxRyRz viewing
direction, and FOV (field of view). The rdata command loads
such path files too.
Play the viewpoint along the currently loaded path, as the play
command does. Right-click for a menu of play-speed options.
Step through camera-path frames. See also frame control
command.
Slides through camera path, and displays current frame.
The third window from the top contains a logfile of past commands and
responses to them, and can be resized by dragging the bar between
command window and viewing window. The Logfile window also has a
scroll bar on the left. You can direct the mouse to any previous
command, and it will show up in the command window. Using the arrow
keys this command can then be edited.
33..77.. CCoommmmaanndd wwiinnddooww
The Command window is a single line entry window, in which Control
Commands can be given. Their responses appear in the Logfile window
and on the originating console. (unlike Data Commands, which show no
feedback). You can still give Data Commands in this window by
prefixing them with the add command. The Up- and Down-arrow keys (not
those on the keypad) scroll through previous commands, and can be
edited using the arrow keys and a subset of the emacs control
characters.
33..88.. VViieewwiinngg wwiinnddooww
The (OpenGL) 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.
33..99.. EExxaammppllee 22:: aa ((ssttaarrllaabb)) aanniimmaattiioonn
Setting up a small animation in for example Starlab can be done quite
simply as follows: (see also the primbim16.mk makefile to create a
standard one):
______________________________________________________________________
% makeplummer -i -n 20 | makemass -l 0.5 -u 10.0 | scale -s | kira -d 2 -D x10 > run1
% partiview run1.cf
% cat run1.cf
kira run1
eval every
eval lum mass 0 0.01
eval psize 100
eval cment 1 1 .7 .3
eval color clump exact
______________________________________________________________________
Alternatively, if you had started up partiview without any arguments,
the following Control Command (see below) would have done the same
______________________________________________________________________
read run1.cf
______________________________________________________________________
33..1100.. EExxaammppllee 33:: sstteerreeoo vviieewwiinngg
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
will probably work too. See sstteerreeoo and ffooccaalllleenn in the View Commands
section.
There are two types of commands in 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 without comment. The command window expects
to receive Control Commands. However, it is possible to enter a Data
Command where a Control Command is expected, using the add command
prefix. Likewise, a Control Command may be given where data is
expected, using the eval prefix, e.g. in a data (or .cf) file.
44..11.. CCoonnttrrooll CCoommmmaannddss
(see partibrains.c::specks_parse_args)
Control Commands are accepted in the Command window, and in some other
contexts. Generally, partiview gives a response to every Control
Command, reporting the (possibly changed) status.
Typically, if parameters are omitted, the current state is reported.
Some commands apply to particles in the current group (see Object
group commands); others affect global things, such as time or display
settings.
Data Commands can also be given, if prefixed with add.
44..22.. II//OO ccoommmmaannddss
rreeaadd _s_p_e_c_k_s_-_f_i_l_e
Read a file containing Data Commands (typical suffix .cf or
.speck).
aassyynncc _u_n_i_x_-_c_o_m_m_a_n_d
Run an arbitrary unix command (invoked via /bin/sh) as a
subprocess of partiview. Its standard output is interpreted as
a stream of control commands. Thus partiview can be driven
externally, e.g. to record an animation (using the snapshot
command), or to provide additional GUI controls. Several async
commands can run concurrently. Examples are given later.
Warning: you cannot interrupt a started command, short of
hitting ESC to exit partiview.
aadddd _d_a_t_a_-_c_o_m_m_a_n_d
Enter a Data Command where a Control Command is expected, e.g.
in the text input box. For example,
add 10 15 -1 text blah
adds a new label "blah" at 10 15 -1, or
add kira myrun.out
loads a kira (starlab) output file.
eevvaall _c_o_n_t_r_o_l_-_c_o_m_m_a_n_d
Processes that control command just as if the eval prefix
weren't there. Provided for symmetry: wherever either a control
command or a data command is expected, entering eval _c_o_n_t_r_o_l_-
_c_o_m_m_a_n_d ensures that it's taken as a control command.
aadddd ffiilleeppaatthh ((ddaattaa--ccoommmmaanndd))
Determines the list of directories where all data files, color
maps, etc. are sought. See the filepath entry under Data
Commands.
44..33.. OObbjjeecctt ggrroouupp ccoommmmaannddss
Partiview can load multiple groups of particles, each with independent
display settings, colormaps, etc. When more than one group is loaded,
the Group Row appears on the GUI, with one toggle-button for each
group. Toggling the button turns display of that group on or off.
Right-clicking turns the group unconditionally on, and selects that
group as the current one for other GUI controls.
Many Control Commands apply to the _c_u_r_r_e_n_t_l_y _s_e_l_e_c_t_e_d group.
Groups always have names of the form g_N for some small positive _N;
each group may also have an alias.
gg_N Select group g_N. Create a new group if it doesn't already
exist.
Assign name _a_l_i_a_s to group g_N. Note no blanks around the =
sign.
oobbjjeecctt _o_b_j_e_c_t_n_a_m_e
Likewise, select object _o_b_j_e_c_t_n_a_m_e, which may be either an alias
name or g_N.
gg_N _c_o_n_t_r_o_l_-_c_o_m_m_a_n_d
oobbjjeecctt _o_b_j_e_c_t_n_a_m_e _c_o_n_t_r_o_l_-_c_o_m_m_a_n_d
Either form may be used as a _p_r_e_f_i_x to any control command to
act on the specified group, e.g. object fred poly on
ggaallll _c_o_n_t_r_o_l_-_c_o_m_m_a_n_d
Invoke the given _c_o_n_t_r_o_l_-_c_o_m_m_a_n_d in all groups. For example, to
turn display of group 3 on and all others off, use:
gall off
g3 on
eennaabbllee
Enable display of currently selected group (as it is by
default).
ddiissaabbllee
Turn off display of current group.
44..44.. VViieeww ccoommmmaannddss
View commands affect the view; they aren't specific to data groups.
ffoovv _f_l_o_a_t
Angular field of view (in degrees) in Y-direction.
cceenn[[tteerr]] _X _Y _Z [_R_A_D_I_U_S]
Set point of interest. This is the center of rotation in
[o]rbit and [r]otate modes. Also, in [o]rbit mode, translation
speed is proportional to the viewer's distance from this point.
The optional _R_A_D_I_U_S (also set by censize) determines the size of
the marker crosshair, initially 1 unit.
cceenn[[tteerr]] [[_X _Y _Z [_R_A_D_I_U_S]]
int[erest] [_X _Y _Z [_R_A_D_I_U_S]]" Set point of interest. This is the
center of rotation in [o]rbit and [r]otate modes. And, in
[o]rbit mode, translation speed is proportional to the viewer's
distance from this point. The optional _R_A_D_I_U_S (also set by
censize) determines the size of the marker crosshair, initially
1 unit.
**** why is center/interest commented out in the first example.
Originally this command was documented twice, the first one has
/interest commented out.
cceennssiizzee [[_R_A_D_I_U_S]
Set size of point-of-interest marker.
wwhheerree _(_a_l_s_o_) w
Report the 3-D camera position and forward direction vector.
cclliipp _N_E_A_R _F_A_R
Clipping distances. The computer graphics setup always requires
drawing only objects in some finite range of distances in front
of the viewpoint. Both values must be strictly positive, and
their ratio is limited; depending on the graphics system in use,
distant objects may appear to blink if the _F_A_R/_N_E_A_R ratio
exceeds 10000 or so.
To set the far clip range without changing the near, use a non-
numeric near clip value, e.g. clip - 1000.
jjuummpp [[_X _Y _Z] [_R_x _R_y _R_z]
Get or set the current position (XYZ) and/or viewing (RxRyRz)
angle. NOTE: there may be a bug with the command jump 0 0 0 on
redhat7.1, it will crash the X server!
rreeaaddppaatthh
Read a Wavefront (.wf) file describing a path through space.
Synonym for readpath.
ppllaayy _s_p_e_e_d[f]
Play the currently loaded (from readpath/rdata) camera animation
path, at _s_p_e_e_d times normal speed, skipping frames as needed to
keep up with wall-clock time. (Normal speed is 30 frames per
second.) With "f" suffix, displays every _s_p_e_e_d-th frame,
without regard to real time.
ffrraammee [[_f_r_a_m_e_n_o]
Get or set the current frame the _f_r_a_m_e_n_o-th.
uuppddaattee
Ensures the display is updated, as before taking a snapshot.
Probably only useful in a stream of control commands from an
async subprocess.
wwiinnssiizzee [[_X_S_I_Z_E [_Y_S_I_Z_E]]
Resize graphics window. With no arguments, reports current
size. With one argument, resizes to given width, preserving
aspect ratio.
bbggccoolloorr _R _G _B
Set window background color (three R G B numbers or one
grayscale value).
ffooccaalllleenn _d_i_s_t_a_n_c_e
Focal length: distance from viewer to a typical object of
interest. This affects stereo display (see below) and
navigation: the speed of motion in [t]ranslate and [f]ly modes
is proportional to this distance.
sstteerreeoo [[oonn||ooffff||rreeddccyyaann||ggllaasssseess]] [[_s_e_p_a_r_a_t_i_o_n]
Stereo display. Also toggled on/off by typing 's' key in
graphics window. Where hardware allows it, stereo glasses
selects CrystalEyes-style stereo. All systems should be capable
of stereo redcyan, which requires wearing red/green or red/blue
glasses. Useful _s_e_p_a_r_a_t_i_o_n values might be 0.02 to 0.1, or
-0.02 to -0.1 to swap eyes. See also focallen command, which
gives the distance to a typical object of interest: left- and
right-eye images of an object at that distance will coincide on
the screen.
ssnnaappsseett [[-n _F_R_A_M_E_N_O] _F_I_L_E_S_T_E_M [_F_R_A_M_E_N_O]
Set parameters for future snapshot commands. _F_I_L_E_S_T_E_M may be a
printf format string with frame number as argument, e.g. snapset
pix/%04d.ppm, generating image names of pix/0000.ppm,
pix/0001.ppm, etc. If _F_I_L_E_S_T_E_M contains no % sign, then
.%03d.ppm.gz is appended to it, so snapset ./pix/fred yields
snapshot images named ./pix/fred.000.ppm.gz etc.
Frame number _F_R_A_M_E_N_O (default 0) increments with each snapshot
taken.
ssnnaappsshhoott [[_F_R_A_M_E_N_O]
Capture a snapshot image of the current view. Use snapset to
specify the output image name. Default format is snap.%03d.tif.
Partiview generally invokes the ImageMagick program convert(1),
which must be installed and be on the user's $PATH. Convert
determines the type of image (jpeg, sgi, bmp, etc.) based on the
file suffix.
Convert is not needed if the snapset _F_I_L_E_S_T_E_M ends in .ppm.gz
(invokes gzip rather than convert) or .ppm (no external program
required).
44..55.. PPaarrttiiccllee DDiissppllaayy CCoommmmaannddss
These commands affect how particles (in the current group) are
displayed.
ppssiizzee _s_c_a_l_e_f_a_c_t_o_r
All particle luminosities (as specified by lum command) are
scaled by the product of two factors: a _l_u_m_v_a_r-specific factor
given by slum, and a global factor given by psize. So the
intrinsic brightness of a particle is _v_a_l_u_e_-_s_p_e_c_i_f_i_e_d_-_b_y_-lum *
_s_l_u_m_-_f_o_r_-_c_u_r_r_e_n_t_-_l_u_m_v_a_r * _p_s_i_z_e_-_s_c_a_l_e_f_a_c_t_o_r.
sslluumm _s_l_u_m_f_a_c_t_o_r
Data-field specific luminosity scale factor, for current choice
of _l_u_m_v_a_r as given by the lum command. A _s_l_u_m_f_a_c_t_o_r is recorded
independently for each data field, so if data fields mass and
energy were defined, one might say
lum mass
slum 1000
lum energy
slum 0.25