<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> Partiview (PC-VirDir): Commands</TITLE>
<LINK HREF="partiview-5.html" REL=next>
<LINK HREF="partiview-3.html" REL=previous>
<LINK HREF="partiview.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="partiview-5.html">Next</A>
<A HREF="partiview-3.html">Previous</A>
<A HREF="partiview.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4. Commands</A></H2>
<P>There are two types of commands in <CODE>partiview</CODE>:
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 <CODE>add</CODE> command prefix. (Likewise, a control command
may be given where data is expected, using the <CODE>eval</CODE> prefix.)
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<H2><A NAME="ss4.1">4.1 Control Commands</A>
</H2>
<P>
<P>(see partibrains.c::specks_parse_args)
<P>Control Commands are accepted in the Command window, and in some other contexts.
Generally, <CODE>partiview</CODE> 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 <CODE>add</CODE>.
<P>
<P>
<H2><A NAME="ss4.2">4.2 I/O commands</A>
</H2>
<P>
<P>
<DL>
<DT><B>read <I>specks-file</I></B><DD><P>Read a file containing Data Commands (typical suffix <CODE>.cf</CODE> or <CODE>.speck</CODE>).
<P>
<P>
<DT><B>async <I>unix-command</I></B><DD><P>Run an arbitrary unix command as a subprocess of <CODE>partiview</CODE>.
Its standard output is interpreted as a stream of control commands.
Thus <CODE>partiview</CODE> can be driven externally, e.g. to record an animation
(using the <CODE>snapshot</CODE> command), or to provide additional GUI controls.
Several <CODE>async</CODE> commands can run concurrently.
<P>
<DT><B>add <I>data-command</I></B><DD><P>Enter a Data Command where a Control Command is expected,
e.g. in the text input box. For example,
<PRE>
add 10 15 -1 text blah
</PRE>
adds a new label "blah" at 10 15 -1, or
<PRE>
add kira myrun.out
</PRE>
loads a starlab output file.
<P>
<DT><B>eval <I>control-command</I></B><DD><P>Processes that control command just as if the <CODE>eval</CODE> prefix weren't there.
Provided for symmetry: wherever either a control command or a data command
is expected, entering <CODE>eval</CODE> <I>control-command</I> ensures that it's
taken as a control command.
<P>
<P>
<DT><B>add filepath (data-command)</B><DD><P>Determines the list of directories where all data files, color maps, etc.
are sought. See the <CODE>filepath</CODE> entry under
Data Commands.
<P>
</DL>
<P>
<H2><A NAME="ss4.3">4.3 Object group commands</A>
</H2>
<P><CODE>Partiview</CODE> 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.
<P>Many Control Commands apply to the <I>currently selected</I> group.
<P>Groups always have names of the form g<I>N</I> for some small positive <I>N</I>;
each group may also have an alias.
<P>
<DL>
<DT><B>g<I>N</I> </B><DD><P>Select group g<I>N</I>. Create a new group if it doesn't already exist.
<P>
<DT><B>g<I>N</I>=<I>alias</I> </B><DD><P>Assign name <I>alias</I> to group g<I>N</I>.
<P>
<DT><B>object <I>objectname</I></B><DD><P>Likewise, select object <I>objectname</I>, which may be either an alias name
or g<I>N</I>.
<P>
<DT><B>g<I>N</I> <I>control-command</I></B><DD><P>
<DT><B>object <I>objectname</I> <I>control-command</I></B><DD><P>Either form may be used as a <I>prefix</I> to any control command
to act on the specified group, e.g. <CODE>object fred poly on</CODE>
<P>
<DT><B>gall <I>control-command</I></B><DD><P>Invoke the given <I>control-command</I> in all groups.
For example, to turn display of group 3 on and all others off, use:
<BLOCKQUOTE><CODE>
<PRE>
gall off
g3 on
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>on</B><DD><P>
<DT><B>enable</B><DD><P>Enable display of currently selected group (as it is by default).
<P>
<DT><B>off</B><DD><P>
<DT><B>disable</B><DD><P>Turn off display of current group.
<P>
</DL>
<P>
<H2><A NAME="ss4.4">4.4 View commands</A>
</H2>
<P>View commands affect the view; they aren't specific to data groups.
<P>
<DL>
<DT><B>fov <I>float</I></B><DD><P>Angular field of view (in degrees) in Y-direction.
<P>
<DT><B>cen[ter] <I>X Y Z</I> [<I>RADIUS</I>]</B><DD><P>Set point of interest. This is the center of rotation in
<CODE>[o]rbit</CODE> and <CODE>[r]otate</CODE> modes. Also, in <CODE>[o]rbit</CODE> mode,
translation speed is proportional to the viewer's distance from this point.
The optional <I>RADIUS</I> (also set by <CODE>censize</CODE>) determines the size
of the marker crosshair, initially 1 unit.
<P>
<DT><B>censize [<I>RADIUS</I>]</B><DD><P>Set size of point-of-interest marker.
<P>
<P>
<P>
<DT><B>where <I>(also)</I> w</B><DD><P>Report the 3-D camera position and forward direction vector.
<P>
<DT><B>clip <I>NEAR</I> <I>FAR</I></B><DD><P>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 <I>FAR</I>/<I>NEAR</I> ratio exceeds 10000 or so.
<P>To set the far clip range without changing the near, use a non-numeric
near clip value, e.g. <CODE>clip - 1000</CODE>.
<P>
<P>
<DT><B>jump [<I>X Y Z</I>] [<I>Rx Ry Rz</I>]</B><DD><P>Get or set the current position (XYZ) and/or viewing (RxRyRz) angle.
<P>
<DT><B>readpath</B><DD><P>Read a Wavefront (<CODE>.wf</CODE>) file describing a path through space.
<P>
<DT><B>rdata</B><DD><P>Synonym for readpath.
<P>
<DT><B>play <I>speed</I>[f]</B><DD><P>Play the currently loaded (from <CODE>readpath</CODE>/<CODE>rdata</CODE>) camera animation
path, at <I>speed</I> 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 <I>speed</I>-th frame, without regard to real
time.
<P>
<DT><B>frame [<I>frameno</I>]</B><DD><P>Get or set the current frame the <I>frameno</I>-th.
<DT><B></B><DD><P>
<P>
<DT><B>update </B><DD><P>Ensures the display is updated, as before taking a snapshot.
Probably only useful in a stream of control commands from an <CODE>async</CODE>
subprocess.
<P>
<DT><B>bgcolor <I>R G B</I></B><DD><P>Set window background color (three R G B numbers or one grayscale value).
<P>
<DT><B>cen[ter] [<I>X Y Z</I> [<I>RADIUS</I>]]
int[erest] [<I>X Y Z</I> [<I>RADIUS</I>]]</B><DD><P>Set point of interest. This is the center of rotation in
<CODE>[o]rbit</CODE> and <CODE>[r]otate</CODE> modes. And, in <CODE>[o]rbit</CODE> mode,
translation speed is proportional to the viewer's distance from this point.
The optional <I>RADIUS</I> (also set by <CODE>censize</CODE>) determines the size
of the marker crosshair, initially 1 unit.
<P>
<DT><B>censize [<I>RADIUS</I>]</B><DD><P>Set size of point-of-interest marker.
<P>
<P>
<P>
<DT><B>focallen <I>distance</I></B><DD><P>Focal length: distance from viewer to a typical object of interest.
This affects stereo display (see below) and navigation: the speed of
motion in <CODE>[t]ranslate</CODE> and <CODE>[f]ly</CODE> modes is proportional to this
distance.
<P>
<DT><B>stereo [on|off|redcyan|glasses] [<I>separation</I>]</B><DD><P>Stereo display. Also toggled on/off by typing <CODE>'s'> key in graphics window.
Where hardware allows it, <CODE>stereo glasses</CODE> selects
CrystalEyes-style stereo. All systems should be capable of
<CODE>stereo redcyan</CODE>, which requires wearing red</CODE>green or red/blue glasses.
Useful <I>separation</I> values might be 0.02 to 0.1, or -0.02 to -0.1 to swap
eyes. See also <CODE>focallen</CODE> 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.
<P>
<DT><B>snapset <I>FILESTEM</I> [<I>FRAMENO</I>]</B><DD><P>Set parameters for future <CODE>snapshot</CODE> commands.
<I>FILESTEM</I> may be a printf format string with frame number as
argument, e.g. <CODE>snapset pix/%04d.ppm</CODE>, generating image names
of <CODE>pix/0000.ppm</CODE>, <CODE>pix/0001.ppm</CODE>, etc.
If <I>FILESTEM</I> contains no % sign, then <CODE>.%03d.ppm.gz</CODE> is
appended to it, so <CODE>snapset ./pix/fred</CODE>
yields snapshot images named <CODE>./pix/fred.000.ppm.gz</CODE> etc.
<P>Frame number <I>FRAMENO</I> (default 0) increments with each snapshot taken.
<P>
<P>
<DT><B>snapshot [<I>FRAMENO</I>]</B><DD><P>Capture a snapshot image of the current view.
Use <CODE>snapset</CODE> to specify the output image name.
Default format is <CODE>snap.%03d.tif</CODE>.
<P><CODE>Partiview</CODE> generally invokes the ImageMagick program <CODE>convert(1)</CODE>,
which must be installed and be on the user's $PATH. <CODE>Convert</CODE> determines
the type of image (jpeg, sgi, bmp, etc.) based on the file suffix.
<P><CODE>Convert</CODE> is not needed if the <CODE>snapset</CODE> <I>FILESTEM</I> ends in
<CODE>.ppm.gz</CODE> (invokes gzip rather than convert) or <CODE>.ppm</CODE>
(no external program required).
<P>
</DL>
<P>
<P>
<H2><A NAME="ss4.5">4.5 Particle Display Commands</A>
</H2>
<P>These commands affect how particles (in the current group) are
displayed.
<P>
<DL>
<DT><B>psize <I>scalefactor</I></B><DD><P>All particle luminosities (as specified by <CODE>lum</CODE> command)
are scaled by the product of two factors:
a <I>lumvar</I>-specific factor given by <CODE>slum</CODE>,
and a global factor given by <CODE>psize</CODE>.
So the intrinsic brightness of a particle is
<I>value-specified-by-</I><CODE>lum</CODE>
* <I>slum-for-current-lumvar</I>
* <I>psize-scalefactor</I>.
<P>
<DT><B>slum <I>slumfactor</I></B><DD><P>Data-field specific luminosity scale factor, for current choice of
<I>lumvar</I> as given by the <CODE>lum</CODE> command.
A <I>slumfactor</I> is recorded independently for each data field, so
if data fields <CODE>mass</CODE> and <CODE>energy</CODE> were defined, one might say
<BLOCKQUOTE><CODE>
<PRE>
lum mass
slum 1000
lum energy
slum 0.25
</PRE>
</CODE></BLOCKQUOTE>
having chosen each variable's <I>slumfactor</I> for useful display,
and then freely switch between <CODE>lum mass</CODE> and <CODE>lum energy</CODE>
without having to readjust particle brightness each time.
<P>
<P>
<DT><B>ptsize <I>minpixels</I> <I>maxpixels</I></B><DD><P>
<P>
<P>
<P>
<DT><B>polysize [on|off] [a|s|r]</B><DD><P>
<DT><B>polylum</B><DD><P>
<DT><B>polyminpixels</B><DD><P>
<DT><B>color</B><DD><P>Specify how particles are colored.
Generally, a linear function of some data field of each particle
becomes an index into a colormap (see <CODE>cmap</CODE>, <CODE>cment</CODE>).
<DL>
<DT><B> color <I>colorvar</I> [<I>minval maxval</I>] </B><DD><P>Use data field <I>colorvar</I> (either a name as set by <CODE>datavar</CODE>
or a 0-based integer column number) to determine color.
Map <I>minval</I> to color index 1, and <I>maxval</I> to
the next-to-last entry in the colormap (<I>Ncmap-2</I>).
The 0th and last (<I>Ncmap-1</I>) colormap entry are used for
out-of-range data values.
<P>If <I>minval</I> and <I>maxval</I> are omitted, the actual range of
values is used.
<P>
<DT><B> color <I>colorvar</I> exact [<I>baseval</I>] </B><DD><P>Don't consider field <I>colorvar</I> as a continuous variable;
instead, it's integer-valued, and mapped one-to-one with
color table slots. Data value <I>N</I> is mapped to
color index <I>N+baseval</I>.
<P>
<DT><B> color <I>colorvar</I> -exact </B><DD><P>Once the <CODE>exact</CODE> tag is set, it's sticky. To interpret
it as a continuous, scalable variable again, use <CODE>-exact</CODE>.
<P>
<DT><B> color const <I>R G B</I> </B><DD><P>Show all particles as color <I>R G B</I>, each value in range 0 to 1,
independent of any data fields.
</DL>
<P>
<DT><B>lum</B><DD><P>Specify how particles' intrinsic luminosity is computed:
a linear function of some data field of each particle.
<DL>
<DT><B> lum <I>lumvar</I> [<I>minval maxval</I>] </B><DD><P>Map values of data field <I>lumvar</I> (<CODE>datavar</CODE> name or
field number) to luminosity.
The (linear) mapping takes field value <I>minval</I> to
luminosity 0 and <I>maxval</I> to luminosity 1.0.
<P>If <I>minval</I> and <I>maxval</I> 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 <CODE>psize</CODE> and <CODE>slum</CODE> scale factors, and further
scaled according to distance as specified by <CODE>fade</CODE>, to compute
apparent brightness of points.
<P>
<DT><B> lum const <I>L</I> </B><DD><P>Specify constant particle luminosity <I>L</I> independent of
any data field values.
</DL>
<P>
<DT><B>fade [planar|spherical|linear <I>refdist</I>|const <I>refdist</I>]</B><DD><P>Determines how distance affects particles' apparent brightness (or "size").
The default <CODE>fade planar</CODE> gives 1/r^2 light falloff, with r measured
as distance from the view plane. <CODE>fade spherical</CODE> is also 1/r^2,
but with r measured as true distance from the viewpoint.
<CODE>fade linear</CODE> <I>refdist</I> gives 1/r light falloff -- not physically
accurate, but useful to get a limited sense of depth.
<CODE>fade const</CODE> <I>refdist</I> gives constant apparent brightness
independent of distance, and may be appropriate for orthographic views.
<P>The <I>refdist</I> for linear and const modes is that distance <I>r</I>
at which apparent brightness should match that in the 1/r^2 modes --
a distance to a "typical" particle.
<P>
<DT><B>labelminpixels</B><DD><P>
<DT><B>labelsize</B><DD><P>
<DT><B>lsize</B><DD><P>
<DT><B>point[s] [on|off]</B><DD><P>Turn display of points on or off. With no argument, toggles display.
<P>
<DT><B>poly[gons] [on|off]</B><DD><P>Turn display of points on or off. With no argument, toggles display.
<P>
<DT><B>texture [on|off]</B><DD><P>Turn display of textures on or off. With no argument, toggles.
<P>
<DT><B>label[s] [on|off]</B><DD><P>Turn display of label text on or off. With no argument, toggles.
<P>
<P>
<DT><B>txscale <I>scalefactor</I></B><DD><P>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 <CODE>polysides</CODE> is 4.
<P>
<DT><B>polyorivar</B><DD><P>Report setting of <CODE>polyorivar</CODE> data-command, which see.
<P>
<DT><B>texturevar</B><DD><P>Report setting of <CODE>texturevar</CODE> data-command, which see.
<P>
<DT><B>laxes [on|off]</B><DD><P>Toggle label axes. When on, and when labels are displayed,
shows a
<P>
<DT><B>polyside(s)</B><DD><P>Number of sides a polygon should have
<P>
<DT><B>fast</B><DD><P>see also <CODE>ptsize</CODE>
<P>
<DT><B>ptsize</B><DD><P>makes more sense than <CODE>fast</CODE>.
<P>
<DT><B>gamma</B><DD><P>
<DT><B>alpha [float]</B><DD><P>Get or set the alpha value.
<P>
<P>
<P>
<P>
<DT><B>speed</B><DD><P>For time-dependent data, advance datatime by this many time units
per wall-clock second.
<P>
<DT><B>step [<I>timestep</I>]</B><DD><P>For time-varying data, sets current timestep number.
Real-valued times are meaningful for some kinds of data including those
from starlab; for others, times are rounded to nearest integer.
<P>
<DT><B>step [+|-]<I>deltatimestep</I></B><DD><P>If preceded with a plus or minus sign, adds that amount to current time.
<P>
<P>(note that <CODE>fspeed</CODE> has been deprecated)
<P>
<DT><B>run</B><DD><P>
<DT><B>tfm </B><DD><P>
<DT><B>kiractl </B><DD><P>viewing control options for kira (starlab)
formatted data that have been read in with
the <CODE>kira</CODE> Data Command.
<DL>
<DT><B> kira node {on|off|root} </B><DD><P>Show or hide center-of-mass nodes for multiple stars.
With <CODE>on</CODE>, show CM nodes for each level in a binary tree.
With <CODE>root</CODE>, show only the top-level CM node for each multiple.
<P>
<DT><B> kira ring {on|off|root} </B><DD><P>Show circles around multiple stars; <CODE>on</CODE> and <CODE>root</CODE> as above.
<P>
<DT><B> kira tree {on|off|cross|tick} [<I>tickscale</I>] </B><DD><P>Show lines connecting pairs of stars at each binary-tree level
in a multiple group. With <CODE>cross</CODE>, also show a perpendicular
line -- a tick mark -- which crosses at the CM point,
and whose length is <CODE>tickscale</CODE> (default 0.5) times the
true separation of the pair.
With <CODE>tick</CODE>, just show the tick-mark with no connecting line.
<P>
<DT><B> kira size [sep|semi] [<I>ringscalefactor</I>] </B><DD><P>Determines 3-D size of circles when <CODE>kira ring on</CODE>.
With <CODE>kira size sep</CODE>, ring diameter is scalefactor * instanteous
separation. With <CODE>kira size semi</CODE>, ring radius is scalefactor * a
(the semimajor axis of the two-body system, or <CODE>|a|</CODE> for
unbound orbits). Using <CODE>semi</CODE> gives typically more stable-looking
rings, though they will pop if they become marginally (un-)bound.
Default: <CODE>kira size semi 1.5</CODE>.
<P>
<DT><B>kira scale <I>ringscalefactor</I></B><DD><P>Another way to set the scale factor for <CODE>kira size</CODE> above.
<P>
<DT><B> kira span <I>minpix</I> <I>maxpix</I> </B><DD><P>Sets screen-space (pixel) size limits on rings.
They'll never get smaller than radius <I>minpix</I> nor larger than
<I>maxpix</I>, regardless of true 3-D size. Thus even vanishingly
tight binaries can always be visibly marked.
Default: <CODE>kira span 2 50</CODE>.
<P>
<DT><B> kira track <I>id</I>|on|off </B><DD><P>As particle <I>id</I> 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.
<CODE>kira track off</CODE> disables tracking, and <CODE>kira track on</CODE>
re-enables it.
Use the <CODE>p</CODE> key or mouse button 2 to pick a particle
(or CM node if <CODE>kira node on</CODE>) to see its numeric <I>id</I>.
Transient center-of-mass nodes (shown if <CODE>kira node on</CODE>)
can be tracked while they exist.
</DL>
<P>
<P>
<P>
<P>
<P>
<DT><B>move on|off</B><DD><P>
<P>
<P>
<DT><B>fwd</B><DD><P>
<P>
<DT><B>datawait on|off</B><DD><P>For asynchronously-loaded data (currently only <CODE>ieee</CODE> data command),
say whether wait for current data step to be loaded.
(If not, then keep displaying previous data while loading new.)
<P>
<DT><B>cmap <I>filename</I></B><DD><P>Load (ascii) filename with RGB values, for coloring particles.
The <CODE>color</CODE> command selects which data field is mapped to color index
and how.
<P>
<DT><B>cment</B><DD><P>
<P>
<P>
<DT><B>rawdump</B><DD><P>
<DT><B>see</B><DD><P>
</DL>
<P>
<H2><A NAME="ss4.6">4.6 Particle subsetting & statistics</A>
</H2>
<P>
<DL>
<P>
<DT><B>clipbox ...</B><DD><P>
<DT><B>cb ....</B><DD><P>Display only a 3D subregion of the data -- the part lying within the clipbox.
<DL>
<DT><B>cb <I>xmin ymin zmin xmax ymax zmax</I> </B><DD><P>Specified by coordinate range.
<DT><B>cb <I>xcen,ycen,zcen xrad,yrad,zrad</I> </B><DD><P>Specified by center and "radius" of the box.
Note no spaces after the commas!
<DT><B>cb <CODE>off</CODE> </B><DD><P>Disable clipping. The entire dataset is again visible.
<DT><B>cb <CODE>on</CODE> </B><DD><P>Re-enable a previously defined clipbox setting.
</DL>
<P>
<DT><B>thresh</B><DD><P>Display a subset of particles, chosen by the value of
some data field. Each <CODE>thresh</CODE> command overrides
settings from previous commands, so it cannot be used to
show unions or intersections of multiple criteria.
For that, see the <CODE>only</CODE> command. However, unlike <CODE>only</CODE>,
the <CODE>thresh</CODE> criterion applies to time-varying data.
<DL>
<DT><B>thresh <I>field</I> <I>minval</I> <I>maxval</I> </B><DD><P>Display only those particles where
<I>minval</I> <= field <I>field</I> <= <I>maxval</I>.
The <I>field</I> may be given by name (as from <CODE>datavar</CODE>)
or by field number.
<DT><B>thresh <I>field</I> <CODE><</CODE><I>maxval</I> </B><DD><P>
<DT><B>thresh <I>field</I> <CODE>></CODE><I>minval</I> </B><DD><P>Show only particles where <I>field</I> is <=
or >= the given threshold.
<DT><B>thresh [off|on]</B><DD><P>Disable or re-enable a previously specified threshold.
</DL>
<P>
<DT><B>only[=+-] <I>fieldname</I> <I>value</I> <I>minvalue-maxvalue</I> <<I>value</I> ><I>value</I> ...</B><DD><P>
<DT><B>thresh</B><DD><P>
<P>
<DT><B>clearobj</B><DD><P>Erase all particles in this group. Useful for reloading on the fly.
<P>
<DT><B>every <I>N</I></B><DD><P>Display a random subset (every <I>N</I>-th) of all particles.
E.g. <CODE>every 1</CODE> shows all particles, <CODE>every 2</CODE> shows about half of them.
Reports current subsampling factor, and the current total number of particles.
<P>
<DT><B>hist <I>datafield</I> [-n <I>nbuckets</I>] [-l] [-c] [-t] [<I>minval</I>] [<I>maxval</I>]</B><DD><P>Generates a (numerical) histogram of values of <I>datafield</I>,
which may be a named field (as from <CODE>datavar</CODE>) or a field index.
Divides the value range (either <I>minval</I>..<I>maxval</I>
or the actual range of values for that field) into <I>nbuckets</I>
equal buckets (11 by default). Uses logarithmically-spaced
intervals if <CODE>-l</CODE> (so long as the data range doesn't include zero).
If a clipbox is defined, use <CODE>-c</CODE> to count only
particles within it. If a <CODE>thresh</CODE> or <CODE>only</CODE>
subset is defined, use <CODE>-t</CODE> to count only the chosen subset.
<P>
<DT><B>bound</B><DD><P>Reports 3D extent of the data.
<P>
<DT><B>datavar</B><DD><P>
<DT><B>dv</B><DD><P>Report names and value ranges (over all particles in current group)
of all named data fields.
<P>
<P>
</DL>
<P>
<H2><A NAME="ss4.7">4.7 Boxes</A>
</H2>
<P>
<DL>
<DT><B>showbox <I>list of integer box level numbers...</I></B><DD><P>
<DT><B>hidebox <I>list of integer box level numbers...</I></B><DD><P>
<DT><B>box[es] [off|on|only]</B><DD><P>Turn box display off or on; or display boxes but hide all particles.
<P>
<DT><B>boxcmap <I>filename</I></B><DD><P>Color boxes using that colormap.
Each box's level number (set by <CODE>-l</CODE> option of <CODE>box</CODE> data-command,
default 0) is the color index.
<P>
<DT><B>boxcment <I>colorindex</I> [<I>R G B</I>]</B><DD><P>Get or set the given box-colormap index. E.g. <CODE>boxcment 0</CODE>
reports the color of boxes created with no <CODE>-l</CODE> specified.
<P>
<DT><B>boxlabel [on|off]</B><DD><P>Label boxes by id number
(set by <CODE>-n</CODE> option of <CODE>box</CODE> data-command).
<P>
<DT><B>boxaxes [on|off]</B><DD><P>Toggle or set box axes display mode.
<P>
<DT><B>boxscale [float] [on|off] </B><DD><P>
<DT><B>gobox <I>boxnumber</I></B><DD><P>
<DT><B>goboxscale</B><DD><P>
<DT><B>menu fmenu</B><DD><P>
<P>
<P>BEGIN CAVEMENU
pos P1 P2
wall P1
hid [P1]
show [P1]
h [P1]
demandfps [P1]
font
help
?
END CAVEMENU
<P>
<P>
<DT><B>datascale</B><DD><P>
</DL>
<P>
<H2><A NAME="ss4.8">4.8 Data commands </A>
</H2>
<P>
<P>(see also partibrains.c::specks_read)
<P>Lines starting with <CODE>#</CODE> will be skipped. The following Data Commands
can be placed in a data file.
<P>Control Commands can be given, if prefixed with the <CODE>eval</CODE> command.
<P>
<P>
<DL>
<P>
<DT><B>
read <I>file</I> </B><DD><P>read a <CODE>speck</CODE> formatted file. Recursive, commands can nest. (strtok ok??)
<P>
<DT><B>
include <I>file</I></B><DD><P>read a <CODE>speck</CODE> formatted file.
<P>
<DT><B>ieee [-t time] <I>file</I></B><DD><P>read a IEEEIO formatted file, with optional timestep number (0 based).
Support for this type of data must be explicitly compiled into the program.
<P>
<DT><B>
kira <I>file</I> </B><DD><P>read a <CODE>kira</CODE> formatted file. See the <CODE>kiractl</CODE> Control
Command to modify the looks of the objects.
<P>
<DT><B>object <I>gN=ALIAS</I></B><DD><P>Defines/Selects a particular group number (N=1,2,3....) to an ALIAS. In
command mode you can use <CODE>gN=ALIAS</CODE>. Any data following this command
will now belong to this group.
<P>
<DT><B>object <I>ObjectName</I></B><DD><P>Select an existing group. Following data will now belong to this group.
<P>
<DT><B>sdbvars <I>var</I></B><DD><P>Choose which data fields to
extract from binary sdb files (any of: <CODE>mMcrogtxyzSn</CODE>) for subsequent
<CODE>sbd</CODE> commands.
<P>
<DT><B>sdb [-t time] <I>file</I></B><DD><P>Read an SDB (binary) formatted file, with optional timestep number (0 based).
<P>
<DT><B>box[es] <I>....</I></B><DD><P>Draw a box, using any of the following formats:
<P>
<DL>
<DT><B> <CODE>xmin ymin zmin xmax ymax zmax</CODE> </B><DD><P>
<DT><B> <CODE>xmin,xmax ymin,ymax zmin,zmax</CODE> </B><DD><P>
<DT><B> <CODE>xcen,ycen,zcen xrad,yrad,zrad</CODE> </B><DD><P>
<DT><B> <CODE>[-t time] [-n boxno] [-l level] xcen,ycen,zcen xrad,yrad,zrad </CODE> </B><DD><P>
</DL>
<CODE>level</CODE> determines color.
<P>
<DT><B>annot <I>[-t timestep] string ...</I></B><DD><P>
<P>
<P>
<DT><B>tfm </B><DD><P>Object-to-world transformation. Either
<I>tx ty tz rx ry rz</I> or 16 numbers for 4x4 matrix.
(<I>something> must contain <CODE>* </CODE> a e r</I>)
<P>
<DT><B>eval <I>command</I></B><DD><P>execute a Control Command.
<P>
<DT><B>feed <I>command</I></B><DD><P>Synonymous for <CODE>eval</CODE>
<P>
<DT><B>VIRDIR <I>command</I></B><DD><P>Synonymous for <CODE>eval</CODE>
<P>
<P>
<DT><B>filepath <I>path</I></B><DD><P>A colon-separated list of directories in which datafiles, color maps, etc.
will be searched for. If preceded with the <CODE>+</CODE> symbol,
this list will be appended to the current <I>filepath</I>.
<P>
<DT><B>polyorivar <I>indexno</I></B><DD><P>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
<CODE>polyorivar </CODE><I>indexno</I>
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 <CODE>polyorivar</CODE> is specified but some polygons should still lie in the
screen plane, use values <CODE>9 9 9 9 9 9</CODE>.
<P>
<DT><B>texture [-lmnMDB] <I>txno file.sgi</I> </B><DD><P>
<DL>
<DT><B> -l(inear) </B><DD><P>
<DT><B> -m(ipmap) </B><DD><P>
<DT><B> -n(earest) </B><DD><P>
<DT><B> -M(odulate) </B><DD><P>
<DT><B> -D(ecal) </B><DD><P>
<DT><B> -B(lend) </B><DD><P>
</DL>
<P>
<DT><B>texturevar <I>fieldno</I></B><DD><P>To make polygons be textured:
<UL>
<LI>Use a series of <CODE>texture</CODE> data-commands to provide a table
of textures, each named by a small integer <I>texture-index</I>;</LI>
<LI>Create a data field in each particle whose value is the
<I>texture-index</I> for that particle's polygon</LI>
<LI>Use data-command <CODE>texturevar </CODE><I>fieldno</I> to specify which
data field that is.</LI>
<LI>Use control commands to enable drawing polygons and textures,
and to give the polygons nonzero size.</LI>
</UL>
It doesn't matter whether the texture-index data field is given a datavar name.
<P>If a particle's texture-index field's value doesn't correspond to anything
defined by a <CODE>texture</CODE> command, then its polygon is drawn as if
texturing were disabled.
<P>
<DT><B>coord <I>name ... 16 world-to-coord tfm floats (GL order)</I></B><DD><P>
<DT><B>dataset <I>indexno datasetname</I></B><DD><P>Give names to multiple datasets in IEEEIO files (read with <CODE>ieee</CODE> command).
<I>indexno</I> is an integer, 0 being the first dataset.
<P>
<DT><B>datavar <I>indexno name [minval maxval]</I></B><DD><P>Name the variable in data field <I>indexno</I>. The first data field is index 0.
If provided, <I>minval maxval</I> supply the nominal range of that data variable;
some control commands (<CODE>lum</CODE>, <CODE>color</CODE>) need to know the range of data
values, and will use this instead of measuring the actual range.
<P>
<DT><B>datatime <I>time</I></B><DD><P>Label subsequent data with this <I>time</I> (a non-negative integer).
<P>
<DT><B><I>Xpos Ypos Zpos Var0 .... </I></B><DD><P>These lines, with XYZ positions in the first 3 columns, will make up the bulk
of the dataset. The 4th and subsequent columns contain the values of the
datavariables as named with the <B>datavar</B> commands. Note that
data variables are 0-based.
<P>
</DL>
<P>
<H2><A NAME="ss4.9">4.9 Textures</A>
</H2>
<P>
<P>
<H2><A NAME="ss4.10">4.10 Coordinates and Coordinate Transformations</A>
</H2>
<P>
<P>
<HR>
<A HREF="partiview-5.html">Next</A>
<A HREF="partiview-3.html">Previous</A>
<A HREF="partiview.html#toc4">Contents</A>
</BODY>
</HTML>