SURFACE(3D)

NAME
surface - a filter that constructs 3-d lines for a surface described by a 2-d matrix

SYNOPSIS
surface options

DESCRIPTION
Surface is a filter which takes a 2-d matrix of real numbers as input. The values of the entries in the matrix are considered as height (the ``Z'' direction), and a list of points in 3-d which describe the 3-d surface is output. Lists of points can be passed through the filter graph3d(3d) for perspective projection (with optional hidden line removal) onto a plane and subsequent plotting. The two dimensions of the matrix are plotted on the horizontal (X) axis and depth (Y) axis, and the values in the matrix itself are positions on the height (Z) axis. There are two ways that surface can describe the 3-d surface, one is with polygons, and the other is with grid lines. The description with polygons is neccessary if it is desired that graph3d(3d) do hidden line removal. If the surface is described with grid lines, there are options to produce only the lines in the X or Y direction. An alternative mode of operation is to translate the numbers in the matrix into a particularly compact representation. This representation is a percent representation, and only uses two characters per number, while expressing accuracy up to 0.001 percent. This mode is enabled by the -brief option and is intended for the display of probability matrices; a sqaure matrix having dimension up to 25 can be displayed on standard 80 column terminal, without confusing wrapping of lines. In this mode, the numbers in the matrix should range between 0.0 and 1.0. The format of the data file should be two integers, r and c which give the row and column dimensions of the matrix respectively, followed by lines of numbers, which are the values in the matrix.

An alternative format is the row dimension followed by a `*'. If this format is used the program will read rows until it cannot read any more integers. The option -sqaregrid can be useful with the input format, it will adjust in the y direction the length of the surface such that the grid is square. N.B. Any input remaining after the matrix has been read is copied to the output. If the input file contains other material than the matrix, the -delimit option can be used to specify a string, two of which delimit the material in the file to be used. Any deviation from the expected format will result in the program printing a message and giving up.

OPTIONS

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

-ascii
    Use ascii format (i.e. human readable real numbers) for the output.

-binary
    Generate the output in binary representation (single precision). This can save alot of CPU time by not reading and writing thousands of reals in ascii. This is the default.

-brief
    Display the matrix with numbers in a very brief format. This can be used to display up to 25 numbers on a single line. The numbers in the matrix should all be between 0.0 and 1000 to use this option. Most accuracy is obtained for numbers between 0.01 and 1.0.

-delimit delimiter
    Search for a line containing the string delimiter in the input, and output the matrix found after that. Copy input following the matrix to the output, up to, but not including another line containing the string delimiter. There may be other text on the line containing delimiter , this is ignored and not copied, no matter if it comes before or after the delimiter.

-grid
    Display the surface using full grid lines.

-histogram
    Display the surface in a histogram format, with blocks. The output will be squares centred on the points specified in the input. In the non-histogram display mode the points in the input are shown at the intersections of lines. Thus, if -histogram is specifed, the X and Y co-ordinates of the output will range slightly outside of the specifed bounds of the surface.

-polygon
    Represent the surface with square panels rather than grid lines. It is neccessary to use this option if it is desired that graph3d do hidden line removal.

-squaregrid
    Adjust the upper Y bound of the surface that the grid is square. This is done before transposition, if transposition was requested.

-suppresstext
    Don't copy extra material following the matrix to stdout.

-transpose
    Transpose the matrix. This option can be combined with any of the modes of display.

-triangle
    Presently unimplemented. Represent the surface with triangular panels. This option is only useful if -histogramis not specified, and is ignored if -histogramis specified.

-unit
    Interpret the matrix as describing a surface on the unit square. This is an abbreviation for -x 0 1 -y 0 1.

-x <low> <high>
    Specify the bounds in the X dimension of the surface being described. The defaults are 0 for the lower bound and the number of points in the X direction for the upper bound.

-xlines
    Display the surface using only the grid lines in the x-direction.

-y <low> <high>
    Specify the bounds in the Y dimension of the surface being described. The defaults are 0 for the lower bound and the number of points in the Y direction for the upper bound.

-ylines
    Display the surface using only the grid lines in the y-direction.

EXAMPLE
hills 40 10 | surface -poly | graph3d -plot -border | plot -T4014 > /dev/tty??
Plot some hills test data as a three-dimensional surface and display the result on a Tektronics 4014 console (substitute the device name for /dev/tty??), with a border around the diagram. The z axis is scaled by a factor of 15, making it much taller.
hat 60 20 | surface -unit -poly| graph3d -ps -box -border -hide | 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, and with the frame of the cubic polygon enclosing the graph. The surface is assumed to describe the unit square.
hat 60 20 | surface -unit | graph3d-tek
Plot a hat and display the result on an xterm running in tektronics mode, which graph3d-tek will endeavour to find. The surface is assumed to describe the unit square. See the manual page for graph3d-tek for further information.

AUTHOR
Tony Plate 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
hat(3d) hills(3d) graph3d(3d) graph3d-tek(3d) pswrap(3d) hills(3d)