plot3d.1

来自「speech signal process tools」· 1 代码 · 共 715 行 · 第 1/2 页

.\" Copyright (c) 1993 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)plot3d.1	1.10 01 Oct 1998 ERL
.ds ]W (c) 1993 Entropic Research Laboratory, Inc.
.TH PLOT3D 1\-ESPS 01 Oct 1998
.SH "NAME"
plot3d \- interactive 3-d plots (perspective plots with hidden lines removed) of data from FEA files.
.SH "SYNOPSIS"
.B plot3d
[
.BI "\-d " depth
] [
\fB\-f "\fIfield\fB\^[\^\fIrange\fB\^]\^"\fR
] [
.BI "\-o " orientation
] [
.BI "\-r " range
] [
.BI "\-x " debug_level
] [
.BI "\-B " length , width , height
] [
.BR "\-I " { aAbBcCpP "}\ .\ .\ ."
] [
.BI "\-P " param
] [
.BI "\-R " bearing , elevation , rotation
] [
.BI "\-S " h_skew : v_skew
] [
.B "\-w " 
] [ 
.B "\-M "
.\" ] [
.\" .BI "\-t " text
.\" ] [
.\" .BI "\-H " text
.\" ] [
.\" .BI "\-V " text
.\" ] [
.\" .BI "\-W " geometry
.\" ] [
.\" .BI "\-X " range
.\" ] [
.\" .BI "\-Y " range
.\" ] [
.\" .BI "\-Z " range
]
.I file
.SH "DESCRIPTION"
.PP
.I plot3d
reads data from a specified field of an ESPS FEA file
and constructs a three-dimensional plot
of the data versus two independent variables.
A plot of data from the
.I re_spec_val
field of a FEA_SPEC file, for example,
could show time along one axis, frequency along another axis,
and spectral power density (or its log) along the third axis.
In general, the
.IR x -axis
corresponds to the order of records in the file,
the
.IR y -axis
corresponds to the order of elements in the field,
and the
.IR z -axis
represents the data values.
The three-dimensional plot is rendered in a window on the screen
as a perspective drawing.
.PP
The user has complete control
over the scaling, orientation, depth of perspective, and angle of view
of the plot.
These plotting parameters are set initially
by command-line options or values in an ESPS parameter file,
but they can be adjusted interactively
with mouse-operated sliders and other controls in a control-panel window,
or with mouse movements in the plot window.
Operating the controls
causes a wire-frame drawing of the bounding box of the plot
to move and change size accordingly,
and clicking on a button in the control-panel window
causes the plot to be redrawn with the new parameters.
The current set of parameters can be saved to a file so that other plots
may later be drawn with the same viewpoint.
Saved parameter sets may be loaded from a file at any time.
.PP
Data may be loaded from a file interactively;
the file name, range of records to be read, field name,
and range of items in the field may all be respecified.
.PP
A moving cursor, controlled by the mouse,
allows the coordinates of points of the graph to be read off numerically.
.PP
In addition to the display on the user's screen; the plot image may be
saved in a file, so that it can be printed or imported into a word processing
system.  The plot image can be saved as either PostScript or PCL.   It can
be directly sent to a printer, if there is no need to save the image file.
.SH "OPTIONS"
.PP
The following options are supported.  Values in brackets are defaults. 
.TP
.BI "\-d " depth " \fR[50]"
Depth of perspective.
A value of 0 corresponds to projection of the 3-dimensional plot
onto the 2-dimensional plotting surface from an infinite distance\c
.RI \*- i.e.
parallel projection.
Positive values of
.I depth
correspond to projection from inversely proportional finite distances
with the result that foreground features
are shown at a somewhat larger scale than features farther from the viewer.
The default value of 50 is reasonable for normal viewing distances.
Large values produce highly exaggerated perspective effects.
.TP
\fB\-f "\fIfield\fB\^[\^\fIrange\fB\^]\^"\fR ["re_spec_val[0:<\fIlast\fR>]"]
.TP
.BI "\-f " field
Name of a field in an ESPS FEA file
and range of elements in field to be plotted.
(Numbering of field elements starts with 0.)
The quotes are needed only
to suppress the shell's usual special interpretation of brackets.
The bracketed
.I range,
if present, may have any of the forms acceptable to
.IR range_switch (3-ESPSu).
.RS
.TP
.I element
A single integer specifies a single field element
(not at present useful with
.IR plot3d ).
.TP
.IB first : last
A pair of integers specifies an inclusive range of elements.
.TP
.IB first :+ incr
The form with the plus sign is equivalent to
.IB first : last
with
.IR last " = " first " + " incr.
.RE
.IP
If the specified range contains elements not present in the field,
the range is reduced as necessary.
.TP
.BI "\-o " orientation " \fR[L]"
Left-handed coordinate system ("L") or right-handed ("R")?
When the axes are in their default initial position,
record number increases with distance from the viewer,
element number increases from left to right,
and data values increase in the upward direction.
For some possible positions,
a mirror-reflected orientation may seem more natural.
Specifying
.I R
instead of
.I L
effectively reverses the direction of the
.I y
(element number) axis.
.TP
.BI "\-r " range " \fR[1:<\fIend of file\fR>]"
Range of records in the file to be read and plotted
(counting the first as number 1.)
The allowable forms for
.I range
are those for
.IR range_switch (3-ESPSu);
see the discussion of
.B \-f
above or the
.I range_switch
manual entry.
.TP
.BI "\-x " debug_level " \fR[0]"
Values greater than 0
cause various debugging messages to be printed as the program runs.
Larger values call out more messages.
The default level of 0 suppresses all debugging messages.
.TP
.BI "\-B " length , width , "height \fR[400,250,150]"
Dimensions, in pixels, of a rectangular box that bounds the 3-d plot
(except for axis labels and the like).
.TP
.BR "\-I " { aAbBcCpP "} . . ." " \fR[abcp]"
Initial actions, taken when the plot window is first brought up.
Draw axes (a, A), draw bounding box (b, B), bring up control panel (c, C),
or plot data (p, P).
A lower-case letters (a, b, c, p) invokes the action,
and upper-case (A, B, C, P) suppresses it.
.TP
.BI "\-P " param_file " \fR[params]"
Name of parameter file to be read initially.
.TP
.BI "\-R " bearing , elevation , "rotation \fR[45.00,35.26,0.00]"
Three angles of rotation (measured in degrees)
that describe the relative positions
of the 3-dimensional plot and the 2-dimensional plotting window.
The
.I bearing
and
.I elevation
determine the direction, relative to the 3-d
coordinate system, of the line normal to the window at its center.
Changing the bearing lets you look at the plot from various sides,
and increasing the elevation lets you look at it from the top.
The third degree of freedom,
.I ``rotation,''
corresponds to a rotation about the line normal to the window at its center
and for most purposes is probably best set equal to 0.
.TP
.BI "\-S " h_skew : v_skew " \fR[0,0]"
Changing
.I h_skew
moves the front parts of the plot one way horizontally
and the back parts of the plot the opposite way,
in proportion to the distance forward or back
with respect to the plane of the plot window.
The effect is somewhat similar to adjusting
.I bearing
.RB ( \-R
above) in that both adjustments
let you see more or less of the left or right side of the plot.
However, adjusting
.I h_skew
does not produce a rotation:
planes parallel to the plane of the plot window remain so.
Similarly, changing
.I v_skew
moves the front parts of the plot one way vertically
and the back part of the plot the opposite way.
The effect is somewhat similar to adjusting
.I elevation
in that both adjustments let you see more or less of the top of the plot.
However, adjusting
.I v_skew
does not produce a rotation of planes parallel to the plot window.
.TP
.B \-w
This option causes \fIplot3d\fR to attempt to connect to an
\fIxwaves\fR(1\-ESPS) running with its server mode enabled.   If
this connection is made, then \fIplot3d\fR will send cursor movement commands
to \fIxwaves+\fR to maintain cursor time alignment between the view in
\fIplot3d\fR and the view in \fIxwaves+\fR.   Note that \fIplot3d\fR has
no way of knowing if the files being viewed in \fIplot3d\fR and
\fIxwaves+\fR are related and if the time alignment makes sense.
A side effect of invoking this mode is to put the axis into time and
frequency display mode.   If the information in the displayed file
cannot support this mode then the \fB-w\fR option is ignored.   For
example, if the displayed file has no \fIrecord_freq\fR generic then then
it cannot send time cursor movements to \fIxwaves+\fR.   
If the displayed file, is not a
FEA_SPEC file, then it cannot send frequency cursor movements to
\fIxwaves+\fR.  
.sp
When this option is used, the environment variable \fBWAVES_HOST\fR is
read to determine the name of the host that is running the \fIxwaves\fR
server.   If \fBWAVES_HOST\fR is undefined, then the connection is
attempted to an \fIxwaves+\fR on the same host as \fIplot3d\fR is running
on.   The default socket port number of the attempt is determined by a
ESPS wide default which is compiled in.    If the environment variable
\fBWAVES_PORT\fR is defined, then its value is used instead as the
socket port. This program uses the facility of
\fIsend_xwaves\fR(3\-ESPS).  See its manual page for details.
.TP 
.B \-M
This option forces \fIplot3d\fP to paint everything in black and 
white (monochrome), useful if you're doing screendumps.  
.\" .TP
.\" .BI "\-t " text
.\" Title to be printed along the
.\" .IR y- axis.
.\" .TP
.\" .BI "\-H " text
.\" Title to be printed along the
.\" .IR x- axis.
.\" .TP
.\" .BI "\-V " text
.\" Title to be printed along the
.\" .IR z- axis.

.\" .TP
.\" .BI "\-X " range
.\" 
.\" .TP
.\" .BI "\-Y " range
.\" 
.\" .TP
.\" .BI "\-Z " range

.SH "ESPS PARAMETERS"
.PP
The parameter file is not required to be present,
as there are default values for all parameters.
If the file exists, the parameters below may be read.
These provide an alternative way of specifying quantities
that can also be determined by command-line options.
The general rule is that if a command-line option is specified,
it takes precedence;
if the command-line option is not specified,
then the parameter file is consulted;
and if a quantity
is not given either on the command line or in the parameter file,
then a default is used.
Eventually this program will support parameter-file entries corresponding
to all command-line options except
.B \-x
and
.BR \-P .
These parameters may also be adjusted interactively from the control panel.
Current values may be saved to a file,
and new values may be read from a file interactively.
(See the discussion of the
.I load params
and
.I save params
items on the
.I files
button menu under "Control Panel and Menus" below.
.TP
.I box_length \- integer
.TP
.I box_width \- integer
.TP
.I box_height \- integer
These correspond to the arguments
.I length,
.I width,
and
.I height
of the
.B \-B
option.
.TP
.I depth \- float
This corresponds to the argument of the
.B \-d
option.
.TP
.I horizontal_skew \- float
.TP
.I vertical_skew \- float
These correspond to the arguments
.I h_skew
and
.I v_skew
of the
.B \-S
option.
.TP
.I orientation \- string
This corresponds to the argument of the
.B \-o
option.