<!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-28 document new movie features for the new CVS version
and lotsa more commands described now PJT
-->
<article>
<!-- Title information -->
<title> Partiview (PC-VirDir)
<author> Peter Teuben, Stuart Levy
<date> 2 May 2001
<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 July 2001 release (version 0.6 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 (Mesa, FLTK) 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
% rpm -i Mesa-3.2-2.i686.rpm Mesa-devel-3.2-2.i686.rpm
</code></tscreen>
You should have both installed. 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>
% locate libfltk.a
% locate Fl_Slider.h
% 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>
Extract the tarball, and install the program from within the
<tt/src/ directory:
<tscreen><code>
% tar zxf partiview-0.6.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>
<tt/partiview-0.5/ 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/akash.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@akash.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)
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 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
cd ../..
cvs release partiview # if you want to release and remove this sandbox
</code></tscreen>
<!--------------------------------------------------------------------------- -->
<sect> Directory structure
<p>
Here is the 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>
Start the program using one of the sample "speck" files in the
<tt/data/ directory:
<tscreen><code>
% cd partiview/data
% ./hipbright
or
% partiview hipbright
</code></tscreen>
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 <tt/.partiviewrc/ file may contain commands like
<tt/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
<tscreen><code>
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)
</code></tscreen>
and it should give another 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. 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.
<p>
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.
<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 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
</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>
Offers some mode switches: <tt/inertia/ (not yet implemented)
and a button to invoke an H-R diagram window.
<tag> [g1] </tag>
Pulldown g1, g2, ... (or whichever group)
is the currently selected group. See <tt/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.
<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. See also the <tt/points/ command.
<tag> poly </tag>
Toggle to turn polygons on/off. See also the <tt/polygon/ command.
<tag> lbl </tag>
Toggle to turn labels on/off. See also the <tt/label/ command.
<tag> tex </tag>
Toggle to turn textures on/off. See also the <tt/texture/ command.
<tag> box </tag>
Toggle to turn boxes on/off. See also the <tt/boxes/ command.
<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> Group row (optional)
<p>
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.
<p>
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.
<sect1> Time Animation rows (Optional)
<p>
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.
<descrip>
<tag> T </tag>
Shows the current time (or offset from the tripmeter).
The absolute time is the sum of the <bf/T/ and <bf/+/ fields.
Both are editable.
See also the <tt/step/ control command.
<tag>trip </tag>
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.
<tag>back </tag>
Press to return to reference time (sets T to 0).
<tag> + </tag>
Current last time where tripmeter was set. You can reset to
the first frame with the command <tt/step 0/
<tag> dial </tag>
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 * <it/speed/ in data time units.
<tag> |< </tag>
<tag> >| </tag>
Step time backwards or forwards by 0.1 * <it/speed/ data time units.
See also the <tt/</ and <tt/>/ keyboard shortcuts.
<tag> << </tag> <p>
<tag> >> </tag> toggle movie move forwards in time
Toggle animating backwards or forwards in time, by
1 * <it/speed/ data time units per real-time second.
See also the <tt/{/, <tt/~/, and <tt/}/ keyboard shortcuts.
<tag> #.#### </tag>
(Logarithmic) value denoting <it/speed/ of animation.
See also the <tt/speed/ control command.
</descrip>
<sect1> Camera (path) Animation row
<p>
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.
<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).
The <tt/rdata/ command loads such path files too.
<tag> Play </tag>
Play the viewpoint along the currently loaded path,
as the <tt/play/ command does.
Right-click for a menu of play-speed options.
<tag> << < [###] >>> </tag>
Step through camera-path frames.
See also <tt/frame/ control command.
<tag> slider </tag>
Slides through camera path, and displays current frame.
</descrip>
<sect1> Logfile window
<p>
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.
<p>
<sect1> Command window
<p>
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).
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.
<p>
<sect1> Viewing window
<p>
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.
<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
kira run1
eval every
eval lum mass 0 0.01
eval psize 100
eval cment 1 1 .7 .3
eval color clump exact
</code></tscreen>
Alternatively, if you had started up partiview without any arguments, the following
Control Command (see below) would have done the same
<tscreen><code>
read run1.cf
</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 will probably work too.
See <bf/stereo/ and <bf/focallen/ in the View Commands section.
<!--
-->
<p>
<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 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 <tt/add/ command prefix. (Likewise, a control command
may be given where data is expected, using the <tt/eval/ prefix.)
<p>
<!--
Before we explain the two types of Commands in
more detail, a few other concepts are needed:
-->
<!--
-->
<p>
<sect1> Control Commands
<p>
(see partibrains.c::specks_parse_args)
<p>
Control Commands are accepted in the Command window, and in some other contexts.
Generally, <tt/partiview/ gives a response to every Control Command,
reporting the (possibly changed) status.
<p>
Typically, if parameters are omitted, the current state is reported.
<p>
Some commands apply to particles in the current group (see Object group commands);
others affect global things, such as time or display settings.
<p>
Data Commands can also be given, if prefixed with <tt/add/.
<sect1>I/O commands
<p>
<descrip>
<tag>
read <it/specks-file/
</tag>
Read a file containing Data Commands (typical suffix <tt/.cf/ or <tt/.speck/).
<!-- include
NOTYET (would read a file containing control commands)
-->
<tag>
async <it/unix-command/
</tag>
Run an arbitrary unix command (invoked via /bin/sh) as a subprocess of <tt/partiview/.
Its standard output is interpreted as a stream of control commands.
Thus <tt/partiview/ can be driven externally, e.g. to record an animation
(using the <tt/snapshot/ command), or to provide additional GUI controls.
Several <tt/async/ commands can run concurrently.
<tag>
add <it/data-command/
</tag>
Enter a Data Command where a Control Command is expected,
e.g. in the text input box. For example,
<verb>
add 10 15 -1 text blah
</verb>
adds a new label "blah" at 10 15 -1, or
<verb>
add kira myrun.out
</verb>
loads a starlab output file.
<tag>
eval <it/control-command/
</tag>
Processes that control command just as if the <tt/eval/ prefix weren't there.
Provided for symmetry: wherever either a control command or a data command
is expected, entering <tt/eval/ <it/control-command/ ensures that it's
taken as a control command.
<tag>
add filepath (data-command)
</tag>
Determines the list of directories where all data files, color maps, etc.
are sought. See the <tt/filepath/ entry under
<!-- ref id="datacommands" name="Data Commands" --> Data Commands.
</descrip>
<sect1>Object group commands
<p>
<tt/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.
<p>
Many Control Commands apply to the <it/currently selected/ group.
<p>
Groups always have names of the form g<it/N/ for some small positive <it/N/;
each group may also have an alias.
<descrip>
<tag>
g<it/N/ </tag>
Select group g<it/N/. Create a new group if it doesn't already exist.
<tag>
g<it/N/=<it/alias/ </tag>
Assign name <it/alias/ to group g<it/N/.
Note no blanks around the <tt/=/ sign.
<tag>
object <it/objectname/
</tag>
Likewise, select object <it/objectname/, which may be either an alias name
or g<it/N/.
<tag>
g<it/N/ <it/control-command/
</tag>
<tag>
object <it/objectname/ <it/control-command/
</tag>
Either form may be used as a <it/prefix/ to any control command
to act on the specified group, e.g. <tt/object fred poly on/
<tag>
gall <it/control-command/
</tag>
Invoke the given <it/control-command/ in all groups.
For example, to turn display of group 3 on and all others off, use:
<tscreen><verb>
gall off
g3 on
</verb></tscreen>
<tag>
on
</tag>
<tag>
enable
</tag>
Enable display of currently selected group (as it is by default).
<tag>
off
</tag>
<tag>
disable
</tag>
Turn off display of current group.
</descrip>
<sect1>View commands
<p>
View commands affect the view; they aren't specific to data groups.
<descrip>
<tag>
fov <it/float/
</tag>
Angular field of view (in degrees) in Y-direction.
<tag>
cen[ter] <it/X Y Z/ [<it/RADIUS/]
</tag>
<!-- int[erest] <it/X Y Z/ [<it/RADIUS/] -->
Set point of interest. This is the center of rotation in
<tt/[o]rbit/ and <tt/[r]otate/ modes. Also, in <tt/[o]rbit/ mode,
translation speed is proportional to the viewer's distance from this point.
The optional <it/RADIUS/ (also set by <tt/censize/) determines the size
of the marker crosshair, initially 1 unit.
<tag>
censize [<it/RADIUS/]
</tag>
Set size of point-of-interest marker.
<p>
<tag>
where <it/(also)/ w
</tag>
Report the 3-D camera position and forward direction vector.
<tag>
clip <it/NEAR/ <it/FAR/
</tag>
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 <it/FAR//<it/NEAR/ ratio exceeds 10000 or so.
To set the far clip range without changing the near, use a non-numeric
near clip value, e.g. <tt/clip - 1000/.
<!--
<tag>
ortho
</tag>
NOTYET
-->
<tag>
jump [<it/X Y Z/] [<it/Rx Ry Rz/]
</tag>
Get or set the current position (XYZ) and/or viewing (RxRyRz) angle.
<tag>
readpath
</tag>
Read a Wavefront (<tt/.wf/) file describing a path through space.
<tag>
rdata
</tag>
Synonym for readpath.
<tag>
play <it/speed/[f]
</tag>
Play the currently loaded (from <tt/readpath//<tt/rdata/) camera animation
path, at <it/speed/ 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 <it/speed/-th frame, without regard to real
time.
<tag>
frame [<it/frameno/]
</tag>
Get or set the current frame the <it/frameno/-th.
<tag>
<tag>
update
</tag>
Ensures the display is updated, as before taking a snapshot.
Probably only useful in a stream of control commands from an <tt/async/
subprocess.
<tag>
winsize [<it/XSIZE/ [<it/YSIZE/]]
</tag>
Resize graphics window. With no arguments, reports current size.
With one argument, resizes to given width, preserving aspect ratio.
<tag>
bgcolor <it/R G B/
</tag>
Set window background color (three R G B numbers or one grayscale value).
<tag>
cen[ter] [<it/X Y Z/ [<it/RADIUS/]]
int[erest] [<it/X Y Z/ [<it/RADIUS/]]
</tag>
Set point of interest. This is the center of rotation in
<tt/[o]rbit/ and <tt/[r]otate/ modes. And, in <tt/[o]rbit/ mode,
translation speed is proportional to the viewer's distance from this point.
The optional <it/RADIUS/ (also set by <tt/censize/) determines the size
of the marker crosshair, initially 1 unit.
<tag>
censize [<it/RADIUS/]
</tag>
Set size of point-of-interest marker.
<p>
<tag>
focallen <it/distance/
</tag>
Focal length: distance from viewer to a typical object of interest.
This affects stereo display (see below) and navigation: the speed of
motion in <tt/[t]ranslate/ and <tt/[f]ly/ modes is proportional to this
distance.
<tag>
stereo [on|off|redcyan|glasses] [<it/separation/]
</tag>
Stereo display. Also toggled on/off by typing <tt/'s'/ key in graphics window.
Where hardware allows it, <tt/stereo glasses/ selects
CrystalEyes-style stereo. All systems should be capable of
<tt/stereo redcyan/, which requires wearing red/green or red/blue glasses.
Useful <it/separation/ values might be 0.02 to 0.1, or -0.02 to -0.1 to swap
eyes. See also <tt/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.
<tag>
snapset [<tt/-n/ <it/FRAMENO/] <it/FILESTEM/ [<it/FRAMENO/]
</tag>
Set parameters for future <tt/snapshot/ commands.
<it/FILESTEM/ may be a printf format string with frame number as
argument, e.g. <tt>snapset pix/%04d.ppm</tt>, generating image names
of <tt>pix/0000.ppm</tt>, <tt>pix/0001.ppm</tt>, etc.
If <it/FILESTEM/ contains no % sign, then <tt/.%03d.ppm.gz/ is
appended to it, so <tt>snapset ./pix/fred</tt>
yields snapshot images named <tt>./pix/fred.000.ppm.gz</tt> etc.
<p>
Frame number <it/FRAMENO/ (default 0) increments with each snapshot taken.
<p>
<tag>
snapshot [<it/FRAMENO/]
</tag>
Capture a snapshot image of the current view.
Use <tt/snapset/ to specify the output image name.
Default format is <tt/snap.%03d.tif/.
<tt/Partiview/ generally invokes the ImageMagick program <tt/convert(1)/,
which must be installed and be on the user's $PATH. <tt/Convert/ determines
the type of image (jpeg, sgi, bmp, etc.) based on the file suffix.
<tt/Convert/ is not needed if the <tt/snapset/ <it/FILESTEM/ ends in
<tt/.ppm.gz/ (invokes gzip rather than convert) or <tt/.ppm/
(no external program required).
</descrip>
<sect1>Particle Display Commands
<p>
These commands affect how particles (in the current group) are
displayed.
<descrip>
<tag>
psize <it/scalefactor/
</tag>
All particle luminosities (as specified by <tt/lum/ command)
are scaled by the product of two factors:
a <it/lumvar/-specific factor given by <tt/slum/,
and a global factor given by <tt/psize/.
So the intrinsic brightness of a particle is
<it/value-specified-by-/<tt/lum/
* <it/slum-for-current-lumvar/
* <it/psize-scalefactor/.
<tag>
slum <it/slumfactor/
</tag>
Data-field specific luminosity scale factor, for current choice of
<it/lumvar/ as given by the <tt/lum/ command.
A <it/slumfactor/ is recorded independently for each data field, so
if data fields <tt/mass/ and <tt/energy/ were defined, one might say
<tscreen><verb>
lum mass
slum 1000
lum energy
slum 0.25
</verb></tscreen>
having chosen each variable's <it/slumfactor/ for useful display,
and then freely switch between <tt/lum mass/ and <tt/lum energy/
without having to readjust particle brightness each time.
<!-- Just describe "slum"
<tag>
scale-lum
</tag>
-->
<tag>
ptsize <it/minpixels/ <it/maxpixels/
</tag>
Specifies the range of <it/apparent/ sizes of points,
in pixels. Typical values might be <tt/ptsize 0.1 5/.
The graphics system may silently impose an upper limit
of about 10 pixels.
<!-- DEPRECATED COMMAND
<tag>
pointsize
</tag>
-->
<tag>
polysize [on|off] [a|s|r]
</tag>
<tag>
polylum
</tag>
<tag>
polyminpixels
</tag>
<tag>
polymin <it/minradius/ [<it/maxradius/]
</tag>
<tag>
color
</tag>
Specify how particles are colored.
Generally, a linear function of some data field of each particle
becomes an index into a colormap (see <tt/cmap/, <tt/cment/).
<descrip>
<tag> color <it/colorvar/ [<it/minval maxval/] </tag>
Use data field <it/colorvar/ (either a name as set by <tt/datavar/
or a 0-based integer column number) to determine color.
Map <it/minval/ to color index 1, and <it/maxval/ to
the next-to-last entry in the colormap (<it/Ncmap-2/).
The 0th and last (<it/Ncmap-1/) colormap entry are used for
out-of-range data values.
If <it/minval/ and <it/maxval/ are omitted, the actual range of
values is used.
<tag> color <it/colorvar/ exact [<it/baseval/] </tag>
Don't consider field <it/colorvar/ as a continuous variable;
instead, it's integer-valued, and mapped one-to-one with
color table slots. Data value <it/N/ is mapped to
color index <it/N+baseval/.
<tag> color <it/colorvar/ -exact </tag>
Once the <tt/exact/ tag is set (for a particular data-field),
it's sticky. To interpret that data field as a continuous, scalable
variable again, use <tt/-exact/.
<tag> color const <it/R G B/ </tag>
Show all particles as color <it/R G B/, each value in range 0 to 1,
independent of any data fields.
</descrip>
<tag>
lum
</tag>
Specify how particles' intrinsic luminosity is computed:
a linear function of some data field of each particle.
<descrip>
<tag> lum <it/lumvar/ [<it/minval maxval/] </tag>
Map values of data field <it/lumvar/ (<tt/datavar/ name or
field number) to luminosity.
The (linear) mapping takes field value <it/minval/ to
luminosity 0 and <it/maxval/ to luminosity 1.0.
<p>
If <it/minval/ and <it/maxval/ are omitted,
the actual range of values is mapped to the luminosity range
0 to 1.
<p>
Note that the resulting luminosities are then scaled by
the <tt/psize/ and <tt/slum/ scale factors, and further
scaled according to distance as specified by <tt/fade/, to compute
apparent brightness of points.
<tag> lum const <it/L/ </tag>
Specify constant particle luminosity <it/L/ independent of
any data field values.
</descrip>
<tag>
fade [planar|spherical|linear <it/refdist/|const <it/refdist/]
</tag>
Determines how distance affects particles' apparent brightness (or "size").
The default <tt/fade planar/ gives 1/r^2 light falloff, with r measured
as distance from the view plane. <tt/fade spherical/ is also 1/r^2,
but with r measured as true distance from the viewpoint.
<tt/fade linear/ <it/refdist/ gives 1/r light falloff -- not physically
accurate, but useful to get a limited sense of depth.
<tt/fade const/ <it/refdist/ gives constant apparent brightness
independent of distance, and may be appropriate for orthographic views.
The <it/refdist/ for linear and const modes is that distance <it/r/
at which apparent brightness should match that in the 1/r^2 modes --
a distance to a "typical" particle.
<tag>
labelminpixels
</tag>
<tag>
labelsize
</tag>
<tag>
lsize
</tag>
<tag>
point[s] [on|off]
</tag>
Turn display of points on or off. With no argument, toggles display.
<tag>
poly[gons] [on|off]
</tag>
Turn display of points on or off. With no argument, toggles display.
<tag>
texture [on|off]
</tag>
Turn display of textures on or off. With no argument, toggles.
<tag>
label[s] [on|off]
</tag>
Turn display of label text on or off. With no argument, toggles.
<tag>
txscale <it/scalefactor/
</tag>
Scale size of all textures relative to their polygons.
A scale factor of 0.5 (default) make the texture square
just fill its polygon, if <tt/polysides/ is 4.
<tag>
polyorivar
</tag>
Report setting of <tt/polyorivar/ data-command, which see.
<tag>
texturevar
</tag>
Report setting of <tt/texturevar/ data-command, which see.
<tag>
laxes [on|off]
</tag>
Toggle label axes. When on, and when labels are displayed,
shows a
<tag>
polyside(s)
</tag>
Number of sides a polygon should have. Default 11, for fairly round
polygons. For textured polygons, <tt/polysides 4/ might do as well,
and be slightly speedier.
<tag>
fast
</tag>
see also <tt/ptsize/
<tag>
ptsize <it/minpixels/ [<it/maxpixels/]
</tag>
Specifies range of apparent (pixel) size of points.
Those with computed sizes (based on luminosity
and distance) smaller than <it/minpixels/ are
randomly (but repeatably) subsampled -- i.e. some
fraction of them are not drawn. Those computed to be
larger than <it/maxpixels/ are drawn at size
<it/maxpixels/.
<tag>
gamma <it/displaygamma/
</tag>
Tells the particle renderer how the display + OpenGL
relates image values to visible lightness.
You don't need to change this, but may adjust it
to minimize the brightness glitches when particles change size.
Typical values are <tt/gamma 1/ through <tt/gamma 2.5/ or so.
Larger values raise the apparent brightness of dim things.
<tag>
alpha <it/alpha/
</tag>
Get or set the alpha value, in the range 0 to 1; it determines
the opacity of polygons.
<tag>
speed
</tag>
For time-dependent data, advance datatime by this many time units
per wall-clock second.
<tag>
step [<it/timestep/]
</tag>
For time-varying data, sets current timestep number.
Real-valued times are meaningful for some kinds of data including those
from Starlab/kira; for others, times are rounded to nearest integer.
If running, <tt/step/ also stops datatime animation. (See <tt/run/.)
<tag>
step [+|-]<it/deltatimestep/
</tag>
If preceded with a plus or minus sign, adds that amount to current time.
(note that <tt/fspeed/ has been deprecated)
<tag>
run
</tag>
<tag>
tfm
</tag>
<p>
<tag>
move on|off
</tag>
<tag>
fwd
</tag>
<!--
gscale
scaling particles
DEPRECATED
-->
<tag>
datawait on|off
</tag>
For asynchronously-loaded data (currently only <tt/ieee/ data command),
say whether wait for current data step to be loaded.
(If not, then keep displaying previous data while loading new.)
<tag>
cmap <it/filename/
</tag>
Load (ascii) filename with RGB values, for coloring particles.
The <tt/color/ command selects which data field is mapped to color index
and how.
<tag>
cment
</tag>
<tag>
rawdump
</tag>
<tag>
see
</tag>
</descrip>
<sect1>Particle subsetting & statistics
<p>
<descrip>
<tag>
clipbox ...
</tag><p>
<tag>
cb ....
</tag>
Display only a 3D subregion of the data -- the part lying within the clipbox.
<descrip>
<tag>cb <it/xmin ymin zmin xmax ymax zmax/ </tag> <p>
Specified by coordinate range.
<tag>cb <it/xcen,ycen,zcen xrad,yrad,zrad/ </tag>
Specified by center and "radius" of the box.
Note no spaces after the commas!
<tag>cb <tt/off/ </tag><p>
Disable clipping. The entire dataset is again visible.
<tag>cb <tt/on/ </tag><p>
Re-enable a previously defined clipbox setting.
</descrip>
<tag>
thresh
</tag>
Display a subset of particles, chosen by the value of
some data field. Each <tt/thresh/ command overrides
settings from previous commands, so it cannot be used to
show unions or intersections of multiple criteria.
For that, see the <tt/only/ command. However, unlike <tt/only/,
the <tt/thresh/ criterion applies to time-varying data.
<descrip>
<tag>thresh <it/field/ <it/minval/ <it/maxval/ </tag>
Display only those particles where
<it/minval/ <= field <it/field/ <= <it/maxval/.
The <it/field/ may be given by name (as from <tt/datavar/)
or by field number.
<tag>thresh <it/field/ <tt/</<it/maxval/ </tag> <p>
<tag>thresh <it/field/ <tt/>/<it/minval/ </tag>
Show only particles where <it/field/ is <=
or >= the given threshold.
<tag>thresh [off|on]</tag>
Disable or re-enable a previously specified threshold.
</descrip>
<tag>
only[=+-] <it/fieldname/ <it/value/ <it/minvalue-maxvalue/ <<it/value/ ><it/value/ ...
</tag>
<tag>
thresh
</tag>
<tag>
clearobj
</tag>
Erase all particles in this group. Useful for reloading on the fly.
<tag>
every <it/N/
</tag>
Display a random subset (every <it/N/-th) of all particles.
E.g. <tt/every 1/ shows all particles, <tt/every 2/ shows about half of them.
Reports current subsampling factor, and the current total number of particles.
<tag>
hist <it/datafield/ [-n <it/nbuckets/] [-l] [-c] [-t] [<it/minval/] [<it/maxval/]
</tag>
Generates a (numerical) histogram of values of <it/datafield/,
which may be a named field (as from <tt/datavar/) or a field index.
Divides the value range (either <it/minval/..<it/maxval/
or the actual range of values for that field) into <it/nbuckets/
equal buckets (11 by default). Uses logarithmically-spaced
intervals if <tt/-l/ (so long as the data range doesn't include zero).
If a clipbox is defined, use <tt/-c/ to count only
particles within it. If a <tt/thresh/ or <tt/only/
subset is defined, use <tt/-t/ to count only the chosen subset.
<tag>
bound
</tag>
Reports 3D extent of the data.
<tag>
datavar
</tag>
<tag>
dv
</tag>
Report names and value ranges (over all particles in current group)
of all named data fields.
</descrip>
<sect1>Boxes
<p>
<descrip>
<tag>
showbox <it/list of integer box level numbers.../
</tag>
<tag>
hidebox <it/list of integer box level numbers.../
</tag>
<tag>
box[es] [off|on|only]
</tag>
Turn box display off or on; or display boxes but hide all particles.
<tag>
boxcmap <it/filename/
</tag>
Color boxes using that colormap.
Each box's level number (set by <tt/-l/ option of <tt/box/ data-command,
default 0) is the color index.
<tag>
boxcment <it/colorindex/ [<it/R G B/]
</tag>
Get or set the given box-colormap index. E.g. <tt/boxcment 0/
reports the color of boxes created with no <tt/-l/ specified.
<tag>
boxlabel [on|off]
</tag>
Label boxes by id number
(set by <tt/-n/ option of <tt/box/ data-command).
<tag>
boxaxes [on|off]
</tag>
Toggle or set box axes display mode.
<tag>
boxscale [float] [on|off]
</tag>
<tag>
gobox <it/boxnumber/
</tag>
<tag>
goboxscale
</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>
</descrip>
<!--------------------------------------------------------------------------- -->
<sect1> <!-- label id="datacommands" --> 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.
<p>
Control Commands can be given, if prefixed with the <tt/eval/ command.
<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>
kira <it/file/
</tag>
read a <tt/kira/ formatted file. See the <tt/kiractl/ Control
Command to modify the looks of the objects.
<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>
<tt/mesh/ [<tt/-t/ <it/txno/] [<tt/-c/ <it/cindex/] [<tt/-s/ <it/style/]
</tag>
Draw a quadrilateral mesh, optionally colored or textured.
Following the <bf/mesh/ line, provide a line with the mesh dimensions:
<verb><it/nu nv/</verb>
Following this comes the list of <it/nu/*<it/nv/ mesh vertices,
one vertex (specified by several blank-separated numbers) per line.
(Blank lines and comments may be interspersed among them.)
Note that the mesh connections are implicit:
vertex number i*nu+j is adjacent to (i-1)*nu+j, (i+1)*nu+j, i*nu+(j-1),
and i*nu+(j+1). Each vertex line has three or five numbers:
the first three give its 3-D position, and if a <tt/-t/ texture was
specified, then two more fields give its u and v texture coordinates.
<p>
Options:
<descrip>
<tag> <tt/-t/ <it/txno/ </tag> Apply texture number <it/txno/ to surface.
In this case, each mesh vertex should also include
u and v texture coordinates.
<tag> <tt/-c/ <it/colorindex/ </tag> Color surface with color from
integer cmap entry <it/colorindex/.
<tag> <tt/-s/ <it/style/ </tag>
Drawing style: <descrip>
<tag> <it/solid/ </tag> filled polygonal surface (default)
<tag> <it/wire/ </tag> just edges
<tag> <it/point/ </tag> just points (one per mesh vertex)
</descrip>
</descrip>
<tag>
<it/Xcen Ycen Zcen/ ellipsoid <it/[options]... [transformation]/
</tag>
Draw an ellipsoid, specified by:
<descrip>
<tag> <tt/Xcen Ycen Zcen/ </tag> Center position in world coordinates
<tag> <tt/-c/ <it/colorindex/ </tag> Integer color index (default -1 => white)
<tag> <tt/-s/ <it/style/ </tag>
Drawing style: <descrip>
<tag> <it/solid/ </tag> filled polygonal surface (default)
<tag> <it/plane/ </tag> 3 ellipses: XY, XZ, YZ planes
<tag> <it/wire/ </tag> latitude/longitude ellipses
<tag> <it/point/ </tag> point cloud: one per lat/lon intersection
</descrip>
<tag> <tt/-r/ <it/Xradius/[,<it/Yradius/,<it/Zradius/] </tag>
Radius (for sphere) or semimajor axes (for ellipsoid)
<tag> <tt/-n/ <it/nlat[,nlon]/ </tag>
Number of latitude and longitude divisions.
Relevant even for <it/plane/ style, where they determine
how finely the polygonal curves approximate circles.
Default <it/nlon/ = <it/nlat//2 + 1.
<tag> <it/transformation/ </tag>
Sets the spatial orientation of the ellipsoid.
May take any of three forms:
<descrip>
<tag> (nothing) </tag> If absent, the ellipsoid's
coordinate axes are the same as the world axes
for the group it belongs to.
<tag> 9 blank-separated numbers </tag>
A 3x3 transformation matrix T from ellipsoid coordinates
to world coordinates, in the sense
Pworld = Pellipsoid * T + [Xcen, Ycen, Zcen].
<tag> 16 blank-separated numbers </tag>
A 4x4 transformation matrix, as above but for the
obvious changes.
</descrip>
</descrip>
<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/* / a e r/)
<tag>
eval <it/command/
</tag>
execute a Control Command.
<tag>
feed <it/command/
</tag>
Synonym for <tt/eval/.
<tag>
VIRDIR <it/command/
</tag>
Synonym for <tt/eval/.
<!-- DEPRECATED COMMAND
<tag>
ignorefirst, ignorepgc
</tag>
-->
<tag>
filepath <it/path/
</tag>
A colon-separated list of directories in which datafiles, color maps, etc.
will be searched for. If preceded with the <tt/+/ symbol,
this list will be appended to the current <it/filepath/.
<tag>
polyorivar <it/indexno/
</tag>
By default, when polygons are drawn, they're parallel to the screen plane --
simple markers for the points. It's sometimes useful to give each
polygon a fixed 3-D orientation (as for disk galaxies). To do this,
provide 6 consecutive data fields, representing two 3-D orthogonal unit
vectors which span the plane of the disk. Then use
<tt/polyorivar /<it/indexno/
giving the data field number of the first of the 6 fields.
The vectors define the X and Y directions on the disk, respectively --
relevant if texturing is enabled.
<p>
Actually, unit vectors aren't essential; making them different lengths
yields non-circular polygonal disks.
<p>
If <tt/polyorivar/ is specified for the group, but some polygons should
still lie in the screen plane, use values <tt/9 9 9 9 9 9/ for those polygons.
<tag>
texture [-aiAOlmnMDB] <it/txno file.sgi/
</tag>
<descrip>
<tag> -a(lpha) </tag>
A single-channel image would normally be used as luminance data.
With <tt/-a/, the image is taken as opacity data instead
(GL_ALPHA texture format).
<tag> -i(ntensity) </tag>
For 1- or 3-channel images, compute the intensity of each pixel
and use it to form an alpha (opacity) channel.
<tag> -A(dd) </tag>
Use additive blending. This texture will add to, not obscure,
the brightness of whatever lies behind it (i.e. whatever is drawn later).
<tag> -O(ver) </tag>
Use "over" compositing. This texture will obscure features lying
behind it according to alpha values at each point.
<!--
<tag> -l(inear) </tag> <p>
<tag> -m(ipmap) </tag> <p>
<tag> -n(earest) </tag> <p>
-->
<tag> -M(odulate) </tag>
Multiply texture brightness/color values by the colormap-determined
color of each particle.
<tag> -D(ecal) </tag> <p>
The textured polygon's color is determined entirely by the texture,
suppressing any colormapped color.
<tag> -B(lend) </tag> <p>
Probably not very useful.
</descrip>
<tag>
texturevar <it/field/
</tag>
If polygon-drawing and texturing are turned on, use the given
<it/field/ (datavar name or number) in each particle to select
which texture (if any) to draw on its polygon.
<tag>
coord <it/name ... 16 world-to-coord tfm floats (GL order)/
</tag>
<tag>
dataset <it/indexno datasetname/
</tag>
Give names to multiple datasets in IEEEIO files (read with <tt/ieee/ command).
<it/indexno/ is an integer, 0 being the first dataset.
<tag>
datavar <it/indexno name [minval maxval]/
</tag>
Name the variable in data field <it/indexno/. The first data field is index 0.
If provided, <it/minval maxval/ supply the nominal range of that data variable;
some control commands (<tt/lum/, <tt/color/) need to know the range of data
values, and will use this instead of measuring the actual range.
<tag>
datatime <it/time/
</tag>
Label subsequent data with this <it/time/ (a non-negative integer).
<tag>
<it/Xpos Ypos Zpos Var0 .... /
</tag>
These lines, with XYZ positions in the first 3 columns, will make up the bulk
of a typical dataset. The 4th and subsequent columns contain the values of the
datavariables as named with the <bf/datavar/ commands. Note that
data variable (field) numbers are 0-based.
</descrip>
<!---------------------------------------------------------------------- -->
<sect1> Kira/Starlab </>
To read Kira output, in human-readable or binary <bf/tdyn/ form, use the
``<tt/kira/ <it/kirafilename/'' data-command.
<p>
<sect2> Kira particle attributes </>
<p>
The particles read in have the following attributes:
<descrip>
<tag> id </>
positive integer worldline index for single stars
(matching the id in the kira stream).
For non-leaf (center-of-mass) tree nodes, <tt/id/ is a
negative integer.
<tag> mass </>
Mass, in solar mass units (see ``kira mscale'' control command).
<tag> nclump </>
Number of stars in this particle's subtree.
1 for isolated stars, 2 for binaries, etc.
<tag> Tlog </>
base-10 log of temperature (K)
<tag> Lum </>
Luminosity in solar-mass units. (Note this is linear, not log luminosity.)
<tag> stype </>
Stellar type code (small integer).
The [bracketed] message reported when picking (button-2 or p key)
on a star gives the corresponding human-readable stellar type too.
<tag> rootid </>
id of root of subtree. For single stars, rootid = id.
<tag> treeaddr </>
bit-encoded location of star in subtree.
<tag> ringsize </>
0 for stars.
For nonleaf nodes, this is the semimajor axis or instantaneous
separation (according to ``<tt/kira sep/'').
This field isn't multiplied by the scale factor given in
<tt/kira sep/; it gives the actual distance in kira units.
<tag> sqrtmass </>
Square root of mass/Msun. Might be useful for luminosity scaling.
<tag> mu </>
Mass ratio for center-of-mass nodes. Zero for stars.
</descrip>
<p>
<sect2> Hertzsprung-Russell diagram </>
The H-R diagram can be invoked via the <tt/More.../ menu (upper left)
or by the <tt/kira hrdiag on/ control command.
Axes for this plot are log temperature (initial range from 5 to 3)
and log luminosity (initial range -4 to 6). Ranges may be changed
with the <tt/kira hrdiag range/ command or with keystrokes.
<p>
Keystroke commands in the H-R window:
<descrip>
<tag> b/B </>
Adjust the (b)rightness (dot size) of the dots plotted for each star.
Small b brightens (enlarges); capital B shrinks.
<tag> a/A </>
Adjust (a)lpha (opacity) of dots plotted for each star.
If many stars coincide in H-R, their brightnesses add.
Thus reducing opacity may help clarify the relative L-T space
densities, if there are many stars.
<tag> v/V </>
Zoom out (v) or in (V) by 33%. The point under the cursor
becomes the center of the view.
</descrip>
<sect2> kira control commands </>
<p>
Viewing control options for kira/Starlab
formatted data that have been read in with
the <tt/kira/ Data Command.
All control commands begin with <tt/kira/ too.
<descrip>
<tag> kira node {on|off|root} </tag>
Show or hide center-of-mass nodes for multiple stars.
With <tt/on/, show CM nodes for each level in a binary tree.
With <tt/root/, show only the top-level CM node for each multiple.
<tag> kira ring {on|off|root} </tag>
Show circles around multiple stars; <tt/on/ and <tt/root/ as above.
<tag> kira tree {on|off|cross|tick} [<it/tickscale/] </tag> <p>
Show lines connecting pairs of stars at each binary-tree level
in a multiple group. With <tt/cross/, also show a perpendicular
line -- a tick mark -- which crosses at the CM point,
and whose length is <tt/tickscale/ (default 0.5) times the
true separation of the pair.
With <tt/tick/, just show the tick-mark with no connecting line.
<tag> kira size [sep|semi] [<it/ringscalefactor/] </tag>
Determines 3-D size of circles when <tt/kira ring on/.
With <tt/kira size sep/, ring diameter is scalefactor * instanteous
separation. With <tt/kira size semi/, ring radius is scalefactor * a
(the semimajor axis of the two-body system, or <tt/|a|/ for
hyperbolic orbits). Using <tt/semi/ gives typically more stable-looking
rings, though they will pop if they become marginally (un-)bound.
Default: <tt/kira size semi 1.5/.
<tag>kira scale <it/ringscalefactor/</tag>
Synonym for <tt/kira size/ above.
<tag> kira span <it/minpix/ <it/maxpix/ </tag>
Sets screen-space (pixel) size limits on rings.
They'll never get smaller than radius <it/minpix/ nor larger than
<it/maxpix/, regardless of true 3-D size. Thus even vanishingly
tight binaries can always be visibly marked.
Default: <tt/kira span 2 50/.
<tag> kira track <it/id/|on|off </tag>
As particle <it/id/ moves through time, move the viewpoint in the
same way, so that (if you don't move the view by navigation)
the particle remains fixed in apparent position.
<tt/kira track off/ disables tracking, and <tt/kira track on/
re-enables it.
Use the <tt/p/ key or mouse button 2 to pick a particle
(or CM node if <tt/kira node on/) to see its numeric <it/id/.
Transient center-of-mass nodes (shown if <tt/kira node on/)
can be tracked while they exist.
<tag> kira mscale <it/massscalefactor/[!] </tag>
Set/check the mass scale factor.
Starlab dynamical mass values are multiplied by this factor
for reporting to the user. Normally <it/massscalefactor/
should equal the initial cluster mass in solar-mass units.
For some input files, starlab can determine what was specified
in the original kira run. If so, ``kira mscale <it/number/''
will be ignored unless <it/number/ ends with an exclamation point (!).
So with no <tt/!/, the user (or .cf script) provides a default value;
use <tt/!/ to override the original mass scale.
<tag> kira int <it/seldest/ [= <it/selsrc/] </tag>
Track interactions between particles.
As the cluster evolves, whenever any star matching
selection-expression <it/selsrc/ encounters (is a member of
the same kira tree as) another particle, then the other
particle is added to the <it/seldest/ set. If <it/seldest/
and <it/selsrc/ are the same (or if ``= <it/selsrc/'' is omitted),
then <tt/kira int/ computes the transitive closure of the
interaction set.
Otherwise, only stars that encounter members of the initial
<it/selsrc/ set become members of the <it/seldest/ set.
Example:
<descrip>
<tag> click on some star </tag>
The clicked-on star(s) become members of the <tt/pick/ set.
<tag> sel x = pick </tag>
Save a copy in the new set named <tt/x/.
<tag> kira int x </tag>
Accumulate encounters in the set <tt/x/.
<tag> emph x </tag>
Increase brightness of members of <tt/x/.
<tag> kira trail x </tag>
Extend trails from these set members.
</descrip>
<tag> kira trail <it/selexpression/|off </tag>
Leave trails behind particles selected by <it/selexpression/
(see the <tt/sel/ command). As (dynamical) time passes, for each
display update, one sample point is added to the trail
for each selected particle. (If you reverse the direction of
time, the trails will fold back on themselves.) Some examples:
<descrip>
<tag> kira trail all </tag>
Makes trails grow behind all particles
(including CM nodes, if they're displayed)
<tag> kira trail pick </tag>
Clicking on a star will make a trail grow behind it.
If several stars are within picking range,
trails will grow behind each of them.
<tag> thresh -s big mass >1.5 </tag>
<tag> kira trail big </tag>
These two commands (a) select all stars exceeding
1.5 solar masses and (b) extend trails behind them.
</descrip>
<tag> kira trail clear </tag>
Erase current trails, but let them continue to accumulate
as time passes.
<tag> kira maxtrail <it/nsamples/ </tag>
Set how many time-points are kept for each particle's trail,
initially 50.
<tag> kira hrdiag on|off </tag>
<tag> kira hrdiag range <it/logTleft logTright logLbottom logLtop/ </tag>
</descrip>
<!---------------------------------------------------------------------- -->
<sect1> Textures </>
<p>
To make polygons be textured:
<itemize>
<item>Use a series of <tt/texture/ data-commands to provide a table
of textures, each named by a small integer <it/texture-index/;
<item>Create a data field in each particle whose value is the
<it/texture-index/ for that particle's polygon
<item>Use data-command <tt/texturevar /<it/fieldno/ to specify which
data field that is.
<item>Use control commands (<tt/poly/, <tt/polylumvar/, <tt/polysize/)
to enable drawing polygons and textures,
and to give the polygons nonzero size.
<item>Possibly use control command <tt/polysides/ to specify
4-sided polygons -- a bit faster to draw than default 11-gons.
</itemize>
It doesn't matter whether the texture-index data field is given a datavar name.
<p>
For each particle, if the value of its <it/texturevar/'th field either
(a) doesn't match the value in some <tt/texture/ command or
(b) the file named in that <tt/texture/ command couldn't be read,
then its polygon is drawn as if texturing were disabled.
<!---------------------------------------------------------------------- -->
<sect1> Coordinates and Coordinate Transformations
<p>
<!---------------------------------------------------------------------- -->
<sect> Viewing Window Keyboard Shortcuts
<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 change focus to command window for Control Commands
S/s toggle STEREO mode (need blue/red glasses :-)
modes: mono redcyan crosseyed glasses
See also the 'stereo' View Command
> single frame forward stepping, in time animation mode
< single frame backward stepping, in time animation mode
Button-N various translation/rotation/zoom, depending on mode (fly/orbit/rot/tran)
SHIFT + Button-N modifier to the usual Button-N action, to have more fine control
CTRL + Button-N modifier to orbit-mode, e.g. to do translations instead of rotations
playmodes:
s playnow
l loop (rock)
f,e playevery=1
r,t playevery=0
Gview.cpp : Fl_Gview::handle()
cw reset camera position
p identify nearest object under mouse cursor
P pick that object as the new origin
o ORBIT mode
f FLY mode
r ROTATE mode
t TRANSLATE mode
O toggle perspective mode
v make field of view larger
V make field of view smaller
^v toggle debug output
@ report viewpoint position
= show object-to-world, world-to-object 4x4 matrices
(precede by object name, e.g. "c=", "g3=")
ESC exit
PrintScreen Take image snapshot of current view
< > Step backwards/forwards in dynamical time
(numeric prefix sets time step)
{ } Animate backwards/forwards in dynamical time
~ Fermionic dynamical-time animation toggle:
cycle between stop/forward/stop/backward/...
z Z Halve/double animation speed (dyn units/sec)
(numeric prefix sets animation speed)
</verb></tscreen>
<!--------------------------------------------------------------------------- -->
<sect> Partiview and NEMO
<p>
The program <tt/snapspecks/ converts a NEMO snapshot to specks format
that can be read in directly by partiview. The default viewing variables
are <tt/x,y,z,m/, but those can be changed by using the <bf/options=/
keyword. In fact, arbitrary <it/bodytrans/ expressions can be used
to output.
<tscreen><code>
% mkplummer - 32 |\
snapmass - - massname='n(m)' masspars=p,-2 massrange=0.5,10 |\
hackcode1 - run1.dat
% snapspecks run1.dat > run1.tab
% partiview run1.cf
% cat run1.cf
read junk.tab
eval labels off
eval lum lum 0 1
eval polylumvar point-size .1 area
texturevar 4
eval psize 5000
eval slum 5
eval every 1
</code></tscreen>
<!--------------------------------------------------------------------------- -->
<sect> Tips
<p>
During animation the trip/back buttons can effectively be used to return to
a point in time where you want to return back to if you wanted to
browse around some specific point in time.
<p>
You can spend most of the time moving in [o]rbit mode. Left-button
moves around chosen center; control-left pans around the sky.
As opposed to switching to 't' mode to zoom and translate,
you can also use SHIFT-Mouse-1 and SHIFT-Mouse-3 to achieve the same from
the other ('o', 'f') modes.
<!--------------------------------------------------------------------------- -->
<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.
No, this isn't true; not sure what you were seeing. It does
rotate about the center point with both button-1 and button-3.
In Orbit mode, button-3 translation still translates straight
forward; i.e. not toward the center point. Maybe that's what you mean?
-slevy.
</enum>
-->
<!--------------------------------------------------------------------------- -->
<sect1> 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.
</enum>
</article>