There are two types of commands in partiview:
Control Commands and Data Commands.
Probably the most visible difference between the two is that every Control
Command returns feedback to the user, whereas Data Commands
are interpreted without comment unless an error occurs.
Some situations, e.g. the command-entry text box, expect to receive
Control Commands; others, e.g. files (.cf, .speck, etc.) named on
the command line or specified by read or include commands,
are expected to contain Data Commands.
However, it is always possible to enter a Data Command
where a Control Command is expected,
using the add command prefix, e.g. you could type in the text box:
add 0 0 0 text The Origin
eval prefix:
1 0 0 text X=1
eval bgcolor 0.3 0.2 0.1
See also the previous starlab example.
(see partibrains.c::specks_parse_args)
Control Commands are accepted in the Command window, and in some other contexts.
Generally, partiview gives a response to every Control Command,
reporting the (possibly changed) status.
Typically, if parameters are omitted, the current state is reported.
Some commands apply to particles in the current group (see Object group commands); others affect global things, such as time or display settings.
Data Commands can also be given, if prefixed with add.
Read a file containing Data Commands (typical suffix .cf or .speck).
Run an arbitrary unix command (invoked via /bin/sh) as a subprocess of partiview.
Its standard output is interpreted as a stream of control commands.
Thus partiview can be driven externally, e.g. to record an animation
(using the snapshot command), or to provide additional GUI controls.
Several async commands can run concurrently.
Examples are given later. Warning: you cannot interrupt a started command,
short of hitting ESC to exit partiview.
Enter a Data Command where a Control Command is expected, e.g. in the text input box. For example,
add 10 15 -1 text blahadds a new label "blah" at 10 15 -1, or
add kira myrun.outloads a kira (starlab) output file.
Processes that control command just as if the eval prefix weren't there.
Provided for symmetry: wherever either a control command or a data command
is expected, entering eval control-command ensures that it's
taken as a control command.
Determines the list of directories where all data files, color maps, etc.
are sought. See the filepath entry under
Data Commands.
Partiview can load multiple groups of particles,
each with independent display settings, colormaps, etc.
When more than one group is loaded, the Group Row appears on the GUI,
with one toggle-button for each group. Toggling the button turns
display of that group on or off. Right-clicking turns the group unconditionally on,
and selects that group as the current one for other GUI controls.
Many Control Commands apply to the currently selected group.
Groups always have names of the form gN for some small positive N; each group may also have an alias.
Select group gN. Create a new group if it doesn't already exist.
Assign name alias to group gN.
Note there must be no blanks around the = sign.
Likewise, select object objectname, which may be either an alias name or gN.
Either form may be used as a prefix to any control command
to act on the specified group, e.g. object fred poly on
Invoke the given control-command in all groups. For example, to turn display of group 3 on and all others off, use:
gall off
g3 on
Either one will enable the display of the currently selected group (as it is by default).
Either one will turn off the display of the current group.
View commands affect the view; they aren't specific to data groups.
Angular field of view (in degrees) in Y-direction.
Set point of interest. This is the center of rotation in
[o]rbit and [r]otate modes. Also, in [o]rbit mode,
translation speed is proportional to the viewer's distance from this point.
The optional RADIUS (also set by censize) determines the size
of the marker crosshair, initially 1 unit.
Set point of interest. This is the center of rotation in
[o]rbit and [r]otate modes. And, in [o]rbit mode,
translation speed is proportional to the viewer's distance from this point.
The optional RADIUS (also set by censize) determines the size
of the marker crosshair, initially 1 unit.
**** why is center/interest commented out in the first example. Originally this command was documented twice, the first one has /interest commented out.
Set size of point-of-interest marker.
Report the 3-D camera position and forward direction vector.
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 FAR/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. clip - 1000.
Get or set the current position (XYZ) and/or viewing (RxRyRz) angle.
Read a Wavefront (.wf) file describing a path through space.
Synonym for readpath.
Play the currently loaded (from readpath/rdata) camera animation
path, at 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 speed-th frame, without regard to real
time.
Get or set the current frame the frameno-th.
Ensures the display is updated, as before taking a snapshot.
Probably only useful in a stream of control commands from an async
subprocess.
Resize graphics window. With no arguments, reports current size.
With one argument, resizes to given width, preserving aspect ratio.
With two arguments, reshapes window to that height and width.
With complete X geometry specification (no embedded spaces),
e.g. winsize 400x350+20-10,
also sets position of graphics window, with +X and +Y measured from
left/top, -X and -Y measured from right/bottom of screen.
Detach graphics window from GUI control strip and optionally
specify position of control strip. With full or hide,
makes graphics window full-screen with GUI visible or hidden, respectively.
With neither full nor hide, the graphics window
is detached but left at its current size.
The +XPOS+YPOS is a window position in X window geometry style,
so e.g. detach full -10+5 places the GUI near the
upper right corner of the screen, 10 pixels in from the right
and 5 pixels down from the top edge.
If you don't mind typing blindly, it's still possible to enter
text-box commands even with the controls hidden;
press the Tab key before each command to ensure that
input focus is in the text box.
Use Tabdetach fullEnter
to un-hide a hidden control strip.
Set window background color (three R G B numbers or one grayscale value).
Focal length: distance from viewer to a typical object of interest.
This affects stereo display (see below) and navigation: the speed of
motion in [t]ranslate and [f]ly modes is proportional to this
distance.
Stereo display. Also toggled on/off by typing 's' key in graphics window.
Where hardware allows it, stereo glasses selects
CrystalEyes-style quad-buffered stereo. All systems should be capable of
stereo redcyan, which requires wearing red/green or red/blue glasses,
and of cross (crosseyed), which splits the window horizontally.
left and right show just that eye's view,
and may be handy for taking stereo snapshots.
Useful separation values might be 0.02 to 0.1, or -0.02 to -0.1 to swap
eyes. See also focallen command, which gives the distance to
a typical object of interest: left- and right-eye images of an object
at that distance will coincide on the screen.
Virtual-world eyes will be separated by distance
2 * focallen * separation, with convergence angle
2 * arctan(separation).
See also the winsize and detach commands
for control over graphics window size and placement.
Beware: some systems which support hardware ("glasses")
stereo also require that the display be set to a
stereo-capable video mode. Partiview does not do this
automatically. For example, on stereo-capable SGI Irix systems,
you may need to type (to a unix shell)
/usr/gfx/setmon -n 1024x768_96s to allow
stereo viewing and something like /usr/gfx/setmon -n 72
to revert. Otherwise, turning partiview's stereo on
will just show the left eye's view -- displacing the viewpoint
but nothing else.
-n FRAMENO] FILESTEM [FRAMENO]Set parameters for future snapshot commands.
FILESTEM may be a printf format string with frame number as
argument, e.g. snapset pix/%04d.ppm, generating image names
of pix/0000.ppm, pix/0001.ppm, etc.
If FILESTEM contains no % sign, then .%03d.ppm.gz is
appended to it, so snapset ./pix/fred
yields snapshot images named ./pix/fred.000.ppm.gz etc.
Frame number FRAMENO (default 0) increments with each snapshot taken.
Capture a snapshot image of the current view.
Either give snapshot an explicit filename,
or else specify a file format string with snapset
and then let snapshot fill in the frame number.
With neither FRAMENO nor FILENAME,
snapset adds one to the previous frame number.
If FILENAME contains an @ sign, then snapshot records a stereo pair of images, using current stereo, focallen, etc. settings. The left-eye and right-eye views are saved in files with any @ replaced with L and R respectively.
If built with the JPEG and/or PNG libraries, partiview can write those types of images directly (determined by suffix: jpg, jpeg, png, ppm).
Writing other image types, it generally invokes the ImageMagick program convert(1),
which must be installed and be on the user's $PATH.
Convert is never needed if the snapset FILESTEM ends in
.ppm.gz (invokes gzip rather than convert) or .ppm
(no external program required).
These commands affect how particles (in the current group) are displayed.
All particle luminosities (as specified by lum command)
are scaled by the product of two factors:
a lumvar-specific factor given by slum,
and a global factor given by psize.
So the intrinsic brightness of a particle is
value-specified-by-lum
* slum-for-current-lumvar
* psize-scalefactor.
Data-field specific luminosity scale factor, for current choice of
lumvar as given by the lum command.
A slumfactor is recorded independently for each data field, so
if data fields mass and energy were defined, one might say
lum mass
slum 1000
lum energy
slum 0.25
lum mass and lum energy
without having to readjust particle brightness each time.
Specifies the range of apparent sizes of points,
in pixels. Typical values might be ptsize 0.1 5.
The graphics system may silently impose an upper limit
of about 10 pixels.
Display polygons, or don't.
Multiplier for polygon size. Default is zero (!), so you must set polysize to something else before polygons will show up.
point-size] [area | radius]Choose which attribute determines the radius of a particle's polygon.
By default, it is point-size, a pseudo-attribute which varies with
the brightness of points (so adjusting the slum slider scales polygons too).
Each polygon's 3-D radius is the polysize scalefactor times its particle's
given attribute (whether an actual particle attribute or point-size). Or,
if the area keyword is specified, then the radius is the square root
of attribute * scalefactor. area is useful if the attribute represents
a luminosity; in that case, the polygon total brightness (which is proportional
to its screen area) becomes proportional to the attribute / distance^2.
Specify a minimum screen radius for polygons, in pixels. If smaller than this, they are not drawn.
off|on|arrow]Draw a vector at each point, determined by triple of attributes specified by vecvar data command.
With "arrow", draws an arrowhead on each vector, with 3-D size equal to
the vector's length times the 'arrowscale' (second parameter to vecscale command). The arrowhead always
lies in the screen plane, so its size gives a cue to the vector's
true 3-D length (e.g. when the vector is viewed nearly end-on,
even a small arrowhead can look longer than the vector does).
This also means that arrowheads flip orientation when a vector
passes through being seen nearly end-on.
Example:
datavar 0 mass datavar 1 vx datavar 2 vy datavar 3 vz vecvar vx eval vec on eval vecscale 0.5 ... eval vec arrow eval vecscale 0.5 0.125 # show arrow at tip of each vector
Set scale of vectors drawn by vec, as multiple of the triple of attributes specified by data-command vecvar.
Arrowhead size is set by a new second parameter to "vecscale". Defaults are 1.0 and 0.25, meaning that arrowheads are a quarter the main vector's length.
Set the opacity of all vectors. If too many are overlapping, a small value (e.g. vecalpha 0.1) will help see through more of them.
Specify how particles are colored.
Generally, a linear function of some data field of each particle
becomes an index into a colormap (see cmap, cment).
Use data field colorvar (either a name as set by datavar
or a 0-based integer column number) to determine color.
Map minval to color index 1, and maxval to
the next-to-last entry in the colormap (Ncmap-2).
The 0th and last (Ncmap-1) colormap entry are used for
out-of-range data values.
If minval and maxval are omitted, the actual range of values is used.
Don't consider field colorvar as a continuous variable; instead, it's integer-valued, and mapped one-to-one with color table slots. Data value N is mapped to color index N+baseval.
Once the exact tag is set (for a particular data-field),
it's sticky. To interpret that data field as a continuous, scalable
variable again, use -exact.
Show all particles as color R G B, each value in range 0 to 1, independent of any data fields.
Note: if colorvar is named rgb565 or rgb888, it is interpreted specially: as a 16-bit (rgb565) or 24-bit (rgb888) integer containing the red, green and blue color values in 5-6-5 or 8-8-8-bit encoding. Red is most significant.
Specify how particles' intrinsic luminosity is computed: a linear function of some data field of each particle.
Map values of data field lumvar (datavar name or
field number) to luminosity.
The (linear) mapping takes field value minval to
luminosity 0 and maxval to luminosity 1.0.
If minval and maxval are omitted, the actual range of values is mapped to the luminosity range 0 to 1.
Note that the resulting luminosities are then scaled by
the psize and slum scale factors, and further
scaled according to distance as specified by fade, to compute
apparent brightness of points.
Specify constant particle luminosity L independent of any data field values.
Determines how distance affects particles' apparent brightness (or "size").
The default fade planar gives 1/r^2 light falloff, with r measured
as distance from the view plane. fade spherical is also 1/r^2,
but with r measured as true distance from the viewpoint.
fade linear refdist gives 1/r light falloff -- not physically
accurate, but useful to get a limited sense of depth.
fade const refdist gives constant apparent brightness
independent of distance, and may be appropriate for orthographic views.
The refdist for linear and const modes is that distance r at which apparent brightness should match that in the 1/r^2 modes -- a distance to a "typical" particle.
Labels computed to be smaller than this screen size (pixels) are suppressed.
lsize (alias labelsize) sets the 3-D height of labels. If the text was created with a
text -size textsize option, the scalefactor is multiplied by that to determine
the 3-D size.
Turn display of points on or off. With no argument, toggles display.
Turn display of points on or off. With no argument, toggles display.
Turn display of textures on or off. With no argument, toggles.
Turn display of label text on or off. With no argument, toggles.
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 polysides is 4.
Report setting of polyorivar data-command, which see.
Report setting of texturevar data-command, which see.
Toggle label axes. When on, and when labels are displayed, shows a set of red/green/blue (X/Y/Z) axes to indicate orientation.
Number of sides a polygon should have. Default 11, for fairly round
polygons. For textured polygons, polysides 4 might do as well,
and be slightly speedier.
see also ptsize
Specifies range of apparent (pixel) size of points. Those with computed sizes (based on luminosity and distance) smaller than minpixels are randomly (but repeatably) subsampled -- i.e. some fraction of them are not drawn. Those computed to be larger than maxpixels are drawn at size maxpixels.
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 gamma 1 through gamma 2.5 or so.
Larger values raise the apparent brightness of dim things.
Get or set the alpha value, in the range 0 to 1; it determines the opacity of polygons.
For time-dependent data, advance datatime by this many time units per wall-clock second.
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, step also stops datatime animation. (See run.)
If preceded with a plus or minus sign, adds that amount to current time.
(note that fspeed has been deprecated)
Continue a stopped animation (see also step).
Object-to-world transformation. May take 1, 6, 7, 9 or 16 parameters: either scalefactor, or tx ty tz rx ry rz scalefactor>], or 16 numbers for 4x4 matrix, or 9 numbers for 3x3 matrix. See Coordinates and Coordinate Transformations.
With no numeric parameters, reports the current object-to-world transform.
Use tfm -v to see the transform and its inverse in several forms.
Normally, navigation modes [r]otate and [t]ranslate
just adjust the viewpoint (camera). However,
if you turn move on, then [r]otate and [t]ranslate
move the currently-selected object group instead,
e.g. to adjust its alignment relative to other groups.
([o]rbit and [f]ly modes always move the camera.)
To indicate that move mode is enabled,
the control strip shows the selected group's name in
bold italics, as [g3].
Use move off to revert to normal.
The tfm command reports the current object-group-to-global-world
transformation.
For asynchronously-loaded data (currently only ieee data command),
say whether wait for current data step to be loaded.
(If not, then keep displaying previous data while loading new.)
Load (ascii) filename with RGB values, for coloring particles.
The color command selects which data field is mapped to color index
and how.
Colormaps are text files, beginning with a number-of-entries line and followed by R G B or R G B A entries one per line; see the Colormaps section.
Load colormap as with cmap command. But use this colormap
only when the given data field is selected for coloring.
Thus the cmap color map applies to all data fields for which
no vcmap has ever been specified.
Report or set that colormap entry.
All particle attributes (not positions though) are written to a dump-filename. Useful for debugging. Warning: it will happily overwrite an existing file with that name.
Enable, disable, or report the status of any warp data-command set up for the current group.
If it exists, particles's positions can change with time, in a handful of canned ways
built into the warp command. See the warp entry under Data Commands.
see cb below.
Display only a 3D subregion of the data -- the part lying within the clipbox.
Specified by coordinate ranges. Note only spaces are used to separate the 6 numbers.
Specified by center and "radius" of the box. Note no spaces after the commas!
Specified by coordinate ranges.
off Disable clipping. The entire dataset is again visible.
on Re-enable a previously defined clipbox setting. It will also display the clipbox again
hide Hide the clipbox, but still discard objects whose centers lie outside it.
Display a subset of particles, chosen by the value of
some data field. Each thresh command overrides
settings from previous commands, so it cannot be used to
show unions or intersections of multiple criteria.
For that, see the only command. However, unlike only,
the thresh criterion applies to time-varying data.
Display only those particles where
minval <= field field <= maxval.
The field may be given by name (as from datavar)
or by field number.
<maxval >minval Show only particles where field is <= or >= the given threshold.
Disable or re-enable a previously specified threshold.
Scans particles (in the current timestep only!), finding those where
datafield has value value, or has a value in range
minvalue <= value <= maxvalue, or whatever.
Multiple value-ranges may be specified to select the union of several sets.
The resulting set of particles is assigned to (only=), added to
(only+) or subtracted from (only-) the thresh selection-set.
Also display just particles in that selection-set, as if see thresh
had been typed.
The net effect is illustrated by these examples:
Show only particles of type 1, 2, 3 or 5.
After the above command, shows only the subset
of type 1/2/3/5 particles AND have mass between 2.3 and 3.5.
(Note that to take the intersection of two conditions,
you must subtract the complement of the latter one.
Maybe some day there'll be an only&.
selexprShow just those particles in the selection-set selexpr.
Predefined set names are all, none, thresh and pick,
and other names may be defined by the sel command.
The default is see all. Using the thresh or only
commands automatically switch to displaying see thresh.
Note that you can see the complement of a named set,
e.g. all except the thresh-selected objects, with
see -thresh.
selname = selexprCompute a logical combination of selection-sets and assign them
to another such set. The set membership is originally assigned by
thresh or only commands. Yeah, I know this doesn't make sense.
Need a separate section to document selection-sets.
selexprCount the number of particles in the selection-set selexpr.
Erase all particles in this group. Useful for reloading on the fly.
Display a random subset (every N-th) of all particles.
E.g. every 1 shows all particles, every 2 shows about half of them.
Reports current subsampling factor, and the current total number of particles.
Generates a (numerical) histogram of values of datafield,
which may be a named field (as from datavar) or a field index.
Divides the value range (either minval..maxval
or the actual range of values for that field) into nbuckets
equal buckets (11 by default). Uses logarithmically-spaced
intervals if -l (so long as the data range doesn't include zero).
If a clipbox is defined, use -c to count only
particles within it. If a thresh or only
subset is defined, use -t to count only the chosen subset.
Reports 3D extent of the data. With w, reports it in
world coordinates, otherwise in object coordinates.
Report names and value ranges (over all particles in current group) of all named data fields.
Turn box display off or on; or display boxes but hide all particles.
Color boxes using that colormap.
Each box's level number (set by -l option of box data-command,
default 0) is the color index.
Get or set the given box-colormap index. E.g. boxcment 0
reports the color of boxes created with no -l specified.
Label boxes by id number
(set by -n option of box data-command).
Toggle or set box axes display mode.
BEGIN CAVEMENU
pos P1 P2
wall P1
hid [P1]
show [P1]
h [P1]
demandfps [P1]
font
help
?
END CAVEMENU
(see also partibrains.c::specks_read)
Data Commands can be placed in a data file.
Lines starting with # will be skipped.
Control Commands can also be given, if prefixed with the eval command.
read a speck formatted file. Recursive, commands can nest. (strtok ok??)
Note that read is also a Control Command, doing exactly the same thing.
read a speck formatted file.
Read a IEEEIO formatted file, with optional timestep number (0 based). Support for this type of data must be explicitly compiled into the program.
read a kira formatted file. See the kiractl Control
Command to modify the looks of the objects. Only present if Starlab is compiled
into partiview.
Add (or change) a named variable of the environment variables space of partiview. Enviroment variables, like in the normal unix shell, can be referred to by prepending their name with a $. Note there probably is not an unsetenv command.
Defines/Selects a particular group number (N=1,2,3....) to an ALIAS. In
command mode you can use gN=ALIAS. Any data following this command
will now belong to this group.
Select an existing group. Following data will now belong to this group.
Choose which data fields to
extract from binary sdb files (any of: mMcrogtxyzSn) for subsequent
sdb commands.
Read an SDB (binary) formatted file, with optional timestep number.
(Default time is latest datatime, or 0.)
Read a .pb (binary) particle file, with optional timestep number.
(Default time is latest datatime, or 0.)
A .pb file contains (all values 32-bit integer or 32-bit IEEE float):
Draw a box, using any of the following formats:
xmin ymin zmin xmax ymax zmax xmin,xmax ymin,ymax zmin,zmax xcen,ycen,zcen xrad,yrad,zrad [-t time] [-n boxno] [-l level] xcen,ycen,zcen xrad,yrad,zrad level determines color.
mesh [-t txno] [-c colorindex] [-s style]Draw a quadrilateral mesh, optionally colored or textured. Following the mesh line, provide a line with the mesh dimensions: nu nv
Following this comes the list of nu*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 -t texture was
specified, then two more fields give its u and v texture coordinates.
Options:
-t txno Apply texture number txno to surface. In this case, each mesh vertex should also include u and v texture coordinates.
-c colorindex Color surface with color from integer cmap entry colorindex.
-s style Drawing style:
filled polygonal surface (default)
just edges
just points (one per mesh vertex)
Draw an ellipsoid, specified by:
Xcen Ycen Zcen Center position in world coordinates
-c colorindex Integer color index (default -1 => white)
-s style Drawing style:
filled polygonal surface (default)
3 ellipses: XY, XZ, YZ planes
latitude/longitude ellipses
point cloud: one per lat/lon intersection
-r Xradius[,Yradius,Zradius] Radius (for sphere) or semimajor axes (for ellipsoid)
-n nlat[,nlon] Number of latitude and longitude divisions. Relevant even for plane style, where they determine how finely the polygonal curves approximate circles. Default nlon = nlat/2 + 1.
Sets the spatial orientation of the ellipsoid. May take any of three forms:
If absent, the ellipsoid's coordinate axes are the same as the world axes for the group it belongs to.
A 3x3 transformation matrix T from ellipsoid coordinates to world coordinates, in the sense Pworld = Pellipsoid * T + [Xcen, Ycen, Zcen].
A 4x4 transformation matrix, as above but for the obvious changes.
Load a Wavefront-style .obj model. Material properties are
ignored; the surface is drawn in white unless -c colorindex
in which case it's drawn using that color-table color.
Also if -texture (alias -tx) is supplied,
the surface is textured using whatever texture coordinates are
supplied in the .obj file. The model is displayed at all times
only if marked -static; otherwise it's displayed only
at the time given by -time timestep or by the most recent datatime.
A subset of the .obj format is accepted:
-- vertex position
-- vertex texture coordinates
-- vertex normal
-- face, listing just position indices for each vertex.
The first v line in the .obj file has index 1, etc.
-- face, listing position and texture coordinates for each vertex of the face.
-- face, listing position, texture-coordinate, and normal indices for each vertex.
-c colorindex option (integer index
into the current cmap colormap), or white if no -c is used.
If texturing is enabled -- if the .obj model contains vt entries,
and the -texture option appears, and that numbered texture exists --
then the given texture color multiplies or replaces the -c color,
according to the texture options.
Object-to-world transformation. May take 1, 6, 7, 9 or 16 numbers: either scalefactor or tx ty tz rx ry rz [it/scalefactor/] or 16 numbers for 4x4 matrix, or 9 numbers for 3x3 matrix. See Coordinates and Coordinate Transformations.
Normally the transform is to world coordinates;
but with optional camera prefix, the object's position
is specified relative to the camera, useful to place
legends in a fixed position on the screen.
In camera coordinates, (0,0,0) is the viewpoint,
x=y=0 at screen center, and negative z extends forward.
Try for example
tfm camera -3 -3 -20 0 0 0
0 0 0 text -size 20 Legend
execute a Control Command.
Synonym for eval.
Synonym for eval.
A colon-separated list of directories in which datafiles, color maps, etc.
will be searched for. If preceded with the + symbol,
this list will be appended to the current filepath.
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
polyorivar 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.
Actually, unit vectors aren't essential; making them different lengths yields non-circular polygonal disks.
If polyorivar is specified for the group, but some polygons should
still lie in the screen plane, use values 9 9 9 9 9 9 for those polygons.
If enabled with the vec a.k.a. vectors control command,
partiview can draw a vector, or an arrow, based from each point.
A triple of consecutive data fields define the vector,
whose length can be scaled with the vecscale command.
Use the vecvar data command to specify the first (x component)
of the triple of fields.
See partiview/data/vectordemo.cf and vector.speck for an example.
A single-channel image would normally be used as luminance data.
With -a, the image is taken as opacity data instead
(GL_ALPHA texture format).
For 1- or 3-channel images, compute the intensity of each pixel and use it to form an alpha (opacity) channel.
Use additive blending. This texture will add to, not obscure, the brightness of whatever lies behind it (i.e. whatever is drawn later).
Use "over" compositing. This texture will obscure features lying behind it according to alpha values at each point.
Multiply texture brightness/color values by the colormap-determined color of each particle.
The textured polygon's color is determined entirely by the texture, suppressing any colormapped color.
Probably not very useful.
If polygon-drawing and texturing are turned on, use the given field (datavar name or number) in each particle to select which texture (if any) to draw on its polygon.
Give names to multiple datasets in IEEEIO files (read with ieee command).
indexno is an integer, 0 being the first dataset.
Name the variable in data field indexno. The first data field has
indexno 0.
If provided, minval maxval supply the nominal range of that data variable;
some control commands (lum, color) need to know the range of data
values, and will use this instead of measuring the actual range.
Label subsequent data with this time (a non-negative integer).
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:
Options to warp data command:
"Rotation period". Sets timescale of motion, in frames (f) or seconds (s).
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 degree given (default 1), uses 3*degree attributes as polynomial coefficients, as p=p0+(t/period0)*field[coef0..coef0+2]+(t/period0)^2*[coef0+3..coef0+5]+...
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.
For disk-galaxy style: gives time range over which warp applies.
For disk galaxy style: sets time at which particles are in their original positions.
Disk galaxy style: Add constant to rotation angle.
Provide object-to-disk coordinate transform (in "disk" coordinates, the disk lies in X-Z plane). 9 or 16 numbers.
Provide disk-to-object transform. 9 or 16 numbers.
Disk galaxy style: set radius of rigidly-rotating inner region, and transition to constant-velocity region
Disk galaxy style: Keep the given 3-D point, or a point at the given disk radius, fixed. E.g. track the sun.
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).
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).
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 datavar commands. Note that data variable (field) numbers are 0-based.
To read Kira output, in human-readable or binary tdyn form, use the
``kira kirafilename'' data-command.
The particles read in have the following attributes:
positive integer worldline index for single stars
(matching the id in the kira stream).
For non-leaf (center-of-mass) tree nodes, id is a
negative integer.
Mass, in solar mass units (see ``kira mscale'' control command).
Number of stars in this particle's subtree. 1 for isolated stars, 2 for binaries, etc.
base-10 log of temperature (K)
Luminosity in solar-mass units. (Note this is linear, not log luminosity.)
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.
Is this star still a member of (bound to) the cluster?
id of root of subtree. For single stars, rootid = id.
bit-encoded location of star in subtree.
0 for stars.
For nonleaf nodes, this is the semimajor axis or instantaneous
separation (according to ``kira sep'').
This field isn't multiplied by the scale factor given in
kira sep; it gives the actual distance in kira units.
Square root of mass/Msun. Might be useful for luminosity scaling.
Mass ratio for center-of-mass nodes. Zero for stars.
The H-R diagram can be invoked via the More... menu (upper left)
or by the 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 kira hrdiag range command or with keystrokes.
Keystroke commands in the H-R window:
Adjust the (b)rightness (dot size) of the dots plotted for each star. Small b brightens (enlarges); capital B shrinks.
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.
Zoom out (v) or in (V) by 33%. The point under the cursor becomes the center of the view.
Viewing control options for kira/Starlab
formatted data that have been read in with
the kira Data Command.
All control commands begin with kira too.
Show or hide center-of-mass nodes for multiple stars.
With on, show CM nodes for each level in a binary tree.
With root, show only the top-level CM node for each multiple.
Show circles around multiple stars; on and root as above.
Show lines connecting pairs of stars at each binary-tree level
in a multiple group. With cross, also show a perpendicular
line -- a tick mark -- which crosses at the CM point,
and whose length is tickscale (default 0.5) times the
true separation of the pair.
With tick, just show the tick-mark with no connecting line.
Determines 3-D size of circles when kira ring on.
With kira size sep, ring diameter is scalefactor * instanteous
separation. With kira size semi, ring radius is scalefactor * a
(the semimajor axis of the two-body system, or |a| for
hyperbolic orbits). Using semi gives typically more stable-looking
rings, though they will pop if they become marginally (un-)bound.
Default: kira size semi 1.5.
Synonym for kira size above.
Sets screen-space (pixel) size limits on rings.
They'll never get smaller than radius minpix nor larger than
maxpix, regardless of true 3-D size. Thus even vanishingly
tight binaries can always be visibly marked.
Default: kira span 2 50.
As particle 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.
kira track off disables tracking, and kira track on
re-enables it.
Use the p key or mouse button 2 to pick a particle
(or CM node if kira node on) to see its numeric id.
Transient center-of-mass nodes (shown if kira node on)
can be tracked while they exist.
Set/check the mass scale factor.
Starlab dynamical mass values are multiplied by this factor
for reporting to the user. Normally 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 number''
will be ignored unless number ends with an exclamation point (!).
So with no !, the user (or .cf script) provides a default value;
use ! to override the original mass scale.
Track interactions between particles.
As the cluster evolves, whenever any star matching
selection-expression selsrc encounters (is a member of
the same kira tree as) another particle, then the other
particle is added to the seldest set. If seldest
and selsrc are the same (or if ``= selsrc'' is omitted),
then kira int computes the transitive closure of the
interaction set.
Otherwise, only stars that encounter members of the initial
selsrc set become members of the seldest set.
Example:
The clicked-on star(s) become members of the pick set.
Save a copy in the new set named x.
Accumulate encounters in the set x.
Increase brightness of members of x.
Extend trails from these set members.
Leave trails behind particles selected by selexpression
(see the 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:
Makes trails grow behind all particles (including CM nodes, if they're displayed)
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.
threshold when masses are larger than 1.5
These two commands (a) select all stars exceeding 1.5 solar masses and (b) extend trails behind them.
Erase current trails, but let them continue to accumulate as time passes.
Set how many time-points are kept for each particle's trail, initially 50.
toggle to turn HR Diagram on or off. Initially off.
set limits on the HR Diagram axes.
To make polygons be textured:
texture data-commands to provide a table
of textures, each named by a small integer texture-index;texturevar fieldno to specify which
data field that is.poly, polylumvar, polysize)
to enable drawing polygons and textures,
and to give the polygons nonzero size.polysides to specify
4-sided polygons -- a bit faster to draw than default 11-gons.For each particle, if the value of its texturevar'th field either
(a) doesn't match the value in some texture command or
(b) the file named in that texture command couldn't be read,
then its polygon is drawn as if texturing were disabled.
Matrices as for the 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 (tx ty tz rx ry rz [it/scalefactor/], as accepted by the tfm and jump commands) are interpreted as
Pworld = Pobject * scalefactor * rotY(ry) * rotX(rx) * rotZ(rz) * translate(tx,ty,tz)
Colormap files, as read by the cmap and vcmap commands,
are line-oriented text files. Blank lines are ignored, as are
# comments. The first nonblank, non-comment line gives
the colormap size (number of entries). Later lines may have the form
<it/R G B/giving red, green, and blue, each in the range 0 .. 1. Typically there will be size of these lines. However the colormap need not be written sequentially; a line like
<it/colorindex/: <it/R G B/places that RGB value at that colorindex, in the range 0 .. size-1. Later R G B lines are assigned to colorindex+1, colorindex+2 and so on. Also,
<it/colorindex/ := <it/oldcolorindex/copies the (previously-assigned) RGB value from oldcolorindex and assigns it to colorindex.