partiview.sgml

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 has 
<it/indexno/ 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>
warp
</tag>
When 'warp' has been defined for a group,
all its particles get their positions (re)computed according to
(a) the warp data-command's parameters, (b) the current time, (c) the particle's
initial position, and (d) maybe some attributes of each particle.


There are several (mutually exclusive) kinds of warping available: 
<itemize>
 <item> for doing a sort of differential rotation for disk-like galaxies;
 <item> for doing N-D to 3-D projection, where particle positions are replaced with	
	(time-independent) linear combinations of attribute values;
 <item> linear or polynomial extrapolation of the particle position with time,
	with coefficients specified as triples of attributes
</itemize>

Options to <tt/warp/ data command:
<descrip>

<tag>-p period0[f|s]</tag>
"Rotation period".  Sets timescale of motion, in frames (f) or seconds (s).  

<tag>-extrap coef0[,degree]]</tag>
Extrapolate position with time.  Velocity is given by attribute coef0 and the two attributes following it
(coef0 .. coef0+2), in the sense p = p_0 + [coef0 .. coef0+2] * (time/period0).
If <it/degree/ given (default 1), uses 3*<it/degree/ attributes as polynomial coefficients, as
 p=p0+(t/period0)*field[coef0..coef0+2]+(t/period0)^2*[coef0+3..coef0+5]+...

<tag>-sheet ampl,xlength,zlength</tag>
For disk galaxy style: Applies exponential sheet warp for disk lying in the X-Z plane.
Scale set by xlength and zlength, Y-displacement set by ampl.

<tag>-f fin,fout</tag>
For disk-galaxy style: gives time range over which warp applies.  

<tag>-z zerotime</tag>
For disk galaxy style: sets time at which particles are in their original positions.

<tag>-R rot[,drot]</tag>
Disk galaxy style: Add constant to rotation angle.

<tag>-T o2d</tag>
Provide object-to-disk coordinate transform (in "disk" coordinates, the disk lies in X-Z plane).
9 or 16 numbers.
</tag>-F d2o</tag>
Provide disk-to-object transform.  9 or 16 numbers.
<tag>-r rcore[,transition][w]</tag>
Disk galaxy style: set radius of rigidly-rotating inner region, and transition to constant-velocity region

<tag>-fix x,y,z[w]|radius[w]</tag>
Disk galaxy style: Keep the given 3-D point, or a point at the given disk radius, fixed.  
E.g. track the sun.

<tag>-galaxy gorbcoef0</tag>
Special disk galaxy style.  Each star is on its own disk-galaxy-like orbit,
with 8 orbital parameters given by 8 consecutive attributes starting with gorbcoef0.
See galaxyorbit.h (read the source).

<tag>-ride speckno</tag>
Ride along with speckno'th particle in first loaded group (displace particles by the difference
between their computed orbit position and the ridden-on particle).

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

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> ismember </>
	Is this star still a member of (bound to) the cluster?
  <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 </>
<p>
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 (under the cursor),
		trails will grow behind each of them.
	  <tag> thresh -s big  mass > 1.5 </tag>
		threshold when masses are larger than 1.5
	  <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>
	toggle to turn HD Diagram on or off. Initially off.
    <tag> kira hrdiag range <it/logTleft logTright logLbottom logLtop/ </tag>
	set limits on the HD Diagram axes.
	
    </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>
Matrices as for the <bf/tfm/ command
are intended to be multiplied by an
object-coordinate row vector on the left,
so that 4x4 matrices specify a translation
in their 13th through 15th entries.  Generally they're
in the sense of an object-or-camera-to-world transform.

The six- or seven-number transforms (<it/tx ty tz rx ry rz /[it/scalefactor/],
as accepted by the <bf/tfm/ and <bf/jump/ commands)
are interpreted as

  <it/Pworld = Pobject * scalefactor * /rotY(<it/ry/) * rotX(<it/rx/) * rotZ(<it/rz/) * translate(<it/tx,ty,tz/)

<sect1> Colormap Files
<p>
Colormap files, as read by the <tt/cmap/ and <tt/vcmap/ commands,
are line-oriented text files.  Blank lines are ignored, as are
<tt/#/ comments.  The first nonblank, non-comment line gives
the colormap <it/size/ (number of entries).  Later lines may have the form
<verb>
  <it/R G B/
</verb>
giving red, green, and blue, each in the range 0 .. 1.
Typically there will be <it/size/ of these lines.  However the
colormap need not be written sequentially; a line like
<verb>
  <it/colorindex/:  <it/R G B/
</verb>
places that RGB value at that <it/colorindex/, in the range 0 .. <it/size/-1.
Later <it/R G B/ lines are assigned to <it/colorindex+1/, <it/colorindex+2/
and so on.  Also,
<verb>
  <it/colorindex/ := <it/oldcolorindex/
</verb>
copies the (previously-assigned) RGB value from <it/oldcolorindex/
and assigns it to <it/colorindex/.

<!----------------------------------------------------------------------  -->
<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 you can add and changed them by
using the <bf/options=/ keyword. 
In fact, arbitrary <it/bodytrans/ expressions can be used
for output.  In the following example a 32-body Plummer sphere is
created, which is then given a power-law mass spectrum (with slope -2) 
between 0.5 and 10 mass units, and animated:

<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 run1.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.
<p>
To make an animation, create an executable shell script <tt/movie1/ with 
for example the following commands:
<tscreen><code>
  #! /bin/csh -f
  #
  echo step 0
  echo update
  echo snapshot
  echo step 0.01
  echo update
  echo snapshot
  echo step 0.02
  echo update
  echo snapshot
  echo step 0.03
  echo update
  echo snapshot
  ...
</code></tscreen>
the Control Command <tt/async movie1/, and it will create files
<tt/snap.000.sgi, snap.001.sgi, ..../ and already with <tt/xv/ a movie
can be shown:
<tscreen><code>
  xv -wait 0 snap.???.sgi

</code></tscreen>

To make animated GIFs, here are some examples with common software, 
all with a default 0.1 sec delay between frames. Some animation
software (e.g. xanim) can change these:
<tscreen><code>
  convert -delay 10 -loop 0 snap.???.sgi try1.gif
  gifsicle -d 10 snap.???.gif > try2.gif

</code></tscreen>

The script will run asynchronously within partiview, so if you then
use the mouse to change orientation or zoom,
these actions (minus the location of the mouse of course)
will be nicely recorded in the snapshots.

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

<!--------------------------------------------------------------------------- -->
<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.
Now mostly solved via the <tt/Inertia/ toggle under the
<tt/More/ button from the Top Row Window.

</enum>

<!--------------------------------------------------------------------------- -->
<sect1> Some notes for newcomers to VirDir
<p>
Although starting <tt/virdir/ is very similar to <tt/partiview/,
<code>
   % parti gal2.cf
or, 
   % virir gal2.cf
</code>
the seasoned <tt/partiview/ user will need  to relearn a few modes to
get used to <tt/virdir/. In particular, at AMNH starting virdir will 
probably cause your console screen  (which is normally panel#1 on the
dome) to go dark with no visible command prompt. To regain control,
type the commands (blindly)
<tscreen><code>

   raise
   fly
   idle

</code></tscreen>
which will put <tt/virdir/ in fly and animation mode.
<p>
Here are some important modes, make sure you keep the mouse in the console window.
It is easy to get it lost in any of the other 6 displays which are only visible
on the dome.
<enum>
<item>
Pushing the Left and Right mouse buttons simultaneously will send the display
to the HOME position.

<item>
Left mouse button will toggle the Pause mode in animate/fly mode.

<item>
Holding the Ctrl-button down while moving the mouse will bring your point
of interest into view

<item>
Holding the Alt-button down while moving the mouse will rotate around your
point of interest.

<item>
The 'p' key

<item>
The middle mouse button toggles Head display vs. Center display.

<item>
Holding the Shift-button down while moving the mouse will change the 
available screen-space (works like a zoom).


</enum>

<sect> Glossary
<p>

<enum>

<item>
group: particles can be grouped with the <tt/object/ command. If multiple groups
exist, a separate <tt/Group/ row will be activated automatically.

<item>
data command, not to be confused with control command

<item>
control command, not to be confused with data command

<item>


</enum>


</article>