GRAPH3D(3D)

NAME
graph3d - a filter that makes a perspective projection of a 3-d polygons onto a 2-d plane

SYNOPSIS
graph3d options

DESCRIPTION
Graph3d is a filter which takes a set of 3-d polygons (or lines) as input, and performs a perspective projection onto a plane. Output can be generated for graph(1), X-windows(X11R3), postscript devices. Output for X windows can only be generated when your computer supports it. There are various options that affect the appearance of the plot. The projection is always scaled to fill the viewport, and relative scale is retained. Hidden line removal ( -hide) can be performed, see the section below for more. A border can be placed around the viewport ( -border). A box (a cubic polygon) that contains the plot can be drawn ( -box), or a set of axis can be produced ( -axis). A small labelled orienting axis can be produced ( -orient), it appears in the bottom right-hand corner of the viewport. The graph can be scaled in any direction, and arbitrarily rotated, using the -[xyz]scale and -[xyz]rotation options. There are four options, -left,-right, -front,-back, that give the X, Y, and Z rotations an appropriate set of values so that the origin is put at the left, right, front, or back, respectively. The origin is put at the left by default. Two forms of input are accepted. One form of input is in the style of the -b option of graph(1), where lines are lists of points terminated with a (possibly blank) label. The label, if it is not blank, is placed at the last point of the line. The other form of input is a 3d adaption of plot(5) format, and is produced by surface(3d). Text can be included in diagrams as mentioned above, i.e. by attaching it to points of the diagram. As well as positioning labels relative to the input points, labels can also be positioned relative to the viewport with a special input format for strings, which is: LABEL: <X-offset> <Y-offset> <...string...> An offset pair of 1 1 will place the label in the bottom left-hand corner of the viewport. Negative offsets are taken to be offsets from the other side of the viewport, thus an offset pair of 1 -1 will place the label in the top left-hand corner of the viewport. The numbers represent character spacing, thus an offset pair of 1 -2 will place the label just below one with an offset pair of 1 -1. Beware of negative X-offsets; they must be approximately equal to the length of the string for the string not to go outside of the viewport. Labels can also be specified on the command line, e.g. by including the four arguments ``-label 1 1 'Figure 1' '' on the command line. The label should be quoted if it has spaces in it.

USE UNDER X-WINDOWS
When running as an X-client, Graph3d can be used interactively in some respects. The rotation around the [xyz] axis can be changed by typing [xyz] for an increase, or [XYZ] for a decrease of 15 degrees. If you prefix the [xyz] or [XYZ] by a (multidigit, positive or negative) number, the rotation will be by that many degrees. The view will then be updated. The focus and plane distance can be adjusted by typing [fp] for increase, or [FP] for a decrease by a factor of 1.5. The effective values of these parameters are displayed in the top of your window.
Typing 'q' will exit.
Typing anything that is not understood by the program will ring the bell. Graph3d.

HIDDEN LINE REMOVAL
Graph3d performs hidden line removal by z-sorting polygons, and filling them as they are drawn.

  POSTSCRIPT OR X-WINDOWS OUTPUT ONLY FOR HIDDEN LINE REMOVAL
Hidden line removal is only effective with postscipt or X-windows output, as graph(1) does not provide for filling polygons. The postscript output of graph3d must be passed through pswrap(3d) before it can be printed (to add a prologue and epilogue).

  INPUT MUST BE 3 OR 4 CORNERED POLYGONS FOR HIDDEN LINE REMOVAL
To do hidden line removal, the input to graph3d must be in the form of polygons with either three or four corners. In the ascii-text style input, these are specified by a line with four of five points, where the last point is identical to the first.

  HIDDEN LINE REMOVAL ON OUTPUT OF SURFACE(3D)
If it is desired to do hidden line removal on the output of surface(3d), the -polygon option must be given to surface(3d), as its default is to produce grid-lines, not polygons.

OPTIONS
For all of the options, an unambiguous prefix will be accepted.

-2d Accept 2 dimensional input, program functions much like graph(1).

-3d Accept 3 dimensional input. This is the default.

-axis
    Produce a set of axis.

-back
    See -left below.

-border
    Put a border around the viewport. If this option is not used, an invisible border will be placed around the graph (i.e. four unjoined points). This is done to prevent enthusiastic programs such as graph(1) from rescaling in the X or Y dimension, such rescaling usually makes 3d projections very ugly.

-bounds
    Place a text string that lists the x,y, and z bounds in the upper left corner (label position 1 -1).

-box
    Produce a cubic polygon enclosing the set of points.

-focus <N>
    Scale the distance of the focus from the centre of the figure. If this distance is made too small, the resulting image will a star like apperance, and if there is bad karma, a floating point exception will result.

-front
    See -left below.

-graph
    Produce output suitable for display using

-help
    Print out all the options with short descriptions.

-hide
    Do hidden line removal. This is implemented by Z-sorting, and will fail for some shapes, but performs correctly for continuous surfaces, such as those produced by surface(3d).

-label <X> <Y> <string>
    puts <string> at the position X Y in the view co-ordinates. If <string> has any spaces or shell meta-characters in, it must be quoted. This is an alternate way of specifying labels, there is a fuller discussion of labels and positioning above.

-left -front -right -back
    Set the rotations so that the origin is in that position, and the Z-axis is vertical. These options correspond to the rotations (-65,0,30), (-65,0,-30), (-65,0,-150), and (-65,0,150), respectively.

-ligh_source
    Colour polygons in different gray values as if lit by a light source in direction <X> <Y> <Z>. Works only with -hide under X-Windows or for PostScript.

-noerase
    Don't erase the screen. Only used for plot style output.

-noinvisibleborder
    Don't delimit the viewport with four unjoined points.

-orient
    Produce a small labelled set of axis in the bottom right hand corner of the viewport.

-plane <N>
    Scale the distance of the projection plane from the projection focus. If zero is the number supplied, a parallel projection is performed instead of a perspective projection.

-ps Produce postscript output. This is the default output style when neither plot nor X windows are supported on your computer. This output must have a header and trailer attached before it can be printed. The output is integer valued, in a box of size 10000. The size of the box can be altered using the -ps_scale option. graph(1).

-ps_scale <N>
    Change the size of the box that postscript output falls within. The default is 10000 square.

-q1 -q2 -q3 -q4
    Put the graph in the appropriate quadrant of the output. This is useful for displaying up to four graphs simulataneously on a graphics device, but the -noerase options must be used for all but the first graph displayed.

-right
    See -left above.

show-rotations
    Print out the rotations that will used, and do nothing else. This is useful for finding out the defaults in order to make small adjustments.

-xfraction|-yfraction F
    Use fraction F of the viewport in the specified dimension.

-xlow|-ylow P
    Use only the viewport region above the value P (between 0 and 1) in the specified dimension.

-xrotation|-yrotation|-zrotation R
    Set the rotation about the specified axis to be R degrees.

-xscale|-yscale|-zscale S
    Scale the plot by a factor of S along the specified dimension.

-X  Produce output by connecting directly to an X server. The name of the display should be specified in the DISPLAY environment variable. This is the default output style when X windows is supported on your computer. The window which is produced can safely be moved, buried, iconized and resized without losing information. Resizing requires a full redraw of the picture and can be time consuming. Type 'q' in the window to exit graph3d.

-geometry G
    Give the window on the X display geometry G, where G is of the format <width>x<height>+<x-offset>+<y-offset>. Remember that (0, 0) is the top left corner of your X screen.

-font F
    Use font F when displaying text under X. Default is 9x13.snf. It should be a font from the X font library.

EXAMPLES

The program hat generated test data in the form of a ``mexican hat''.

hat 60 20 | surface -poly | graph3d -ps -box -border -hide -orient | pswrap | lpr -Pps

Plot a hat as a three-dimensional surface and display the
result on the laserwriter, with hidden line removal, with a
square border around the graph, with a small orienting axis,
and with the frame of the cubic polygon enclosing the graph.

AUTHOR
Tony Plate
X windows extension by Michel Berkelaar, michel@ele.tue.nl Copyright (C) 1989 Tony Plate This program and documentations may be freely distributed and used, provided that this copyright notice is retained intact. There is no warranty with this software.

SEE ALSO
graph(1) pswrap(3d) hills(3d) surface(3d)