The Personal Web Pages of Chris X. Edwards

vmaster - man page

SYNOPSIS

vmaster [-h] | [-f] [-o] [-a ratio] [-c point] [-d color] [-p size] [-s angle] [-t point] [-v point] [-z factor] [-] [files...]

DESCRIPTION

vmaster inputs a data stream of formatted text representing basic 3d geometry and returns an output stream of text which defines a 2d scene. The input data defines a model consisting of visible 3d lines and invisible 3d triangular surfaces which can be used to block visibility. Various command line options establish initial viewing parameters such as vantage information and opacity policy (hidden line removal).

OPTIONS

-a: Aspect ratio of the output. This isn't working yet. The idea is to have entities that are outside of the view pyramid be culled before HLR. The aspect ratio of the final output would be important to do this. As it stands, vmaster outputs all entities, whether they can possibly be visible or not.
-c point: Camera point. The default is (0,0,1). point can be expressed as three floating point numbers delimted by any character that won't cause confusion as a possible number component. The three numbers represent the location in space of the viewer's eye position in X, Y, Z coordinates.
-d color: Show deleted lines. Makes hidden lines visible as another color. This is useful for seeing what the hidden line removal and shallow angle cull are deleting. The color format is completely arbitrary since the user defined value for color is simply passed back out as output in the appropriate place. Although not mandatory, this option is designed to be used with gradu as the rendering tool. It produces the correct gradu color property changing commands using the supplied color. See the output stream samples and the gradu documentation.
-f: Faces only. This option is for data supplied only as triangles. The normal data input model of vmaster allows for opaque triangular faces to be independent of visible lines. This option gives models where these two things are intrinsically linked an automatic way of generating the corresponding lines. With this option, all triangular faces specified are accompanied by three implied visible lines representing the triangle's vertices. Note that in meshes of linked triangles with many points in common, this option may produce copious redundant line error messages which can safely be ignored.
-h: Help and usage message.
-o: Opacity flag. This turns on the hidden line removal (HLR) algorithm causing visible lines which are obscured by opaque triangular faces to be modified to be accurately occulted by the obstructions.
-p size: Pierce point marks. When a visible line penetrates the surface of an opaque triangular face, some of the line may remain visible. This option is designed for use with the gradu plotting program. It sets up the necessary commands to place a circular mark at the point of entry of such line/triangle interactions. The size argument is a number in model coordinates. See the output stream samples and the gradu documentation.
-r angle: Camera roll or twist. Generally, 2d scenes are composed assuming that the 3d model's positive Z coordinate corresponds to a real world "up" sense. Regardless of where in space the camera is, the positive Z will be aligned with the positive Y in the 2d output. This can be affected by turning the camera. The angle is a number in degrees to twist the view. THIS ISN'T IMPLEMENTED YET.
-s angle: Shallow angle cull. The idea of this option is to remove a particular class of irrelevant lines from display consideration before any further hidden line processing. The class in question are lines whose endpoints are used by exactly two triangular faces which are situated at a generally similar angle. The degree of similarity is specified by the threshold angle. The exceptions to this are lines which form a defining visible edge. This is espe cially well suited to curved shapes like cylindersand spheres. With this option, a geodesic shpere would be rendered roughly like a simple circle yet preserve all of it's opacity properties. Without this option, a geodesic sphere would be rendered as a circle covered with triangular divisions.
-t point: Target point. The default is (0,0,0). point can be expressed as three floating point numbers delimted by any character that won't cause confusion as a possible number component. The three numbers rep resent a locationin space in X, Y, Z coordinates along the viewer's line of sight.
-z factor: This activates and controls the perspective properties of the output. It is similar to the way lens length operates on a camera. THIS ISN'T IMPLEMENTED YET.

INPUT SYNTAX

vmaster is designed to accomodate a wide variety of sensible input styles constrained by some simple rules. Input streams are parsed line by line. Any line containing a # or a ! character is considered a comment and completely ignored. The master delimiter character is space. Other irrelevant characters are converted to space and can be used freely implying that the data fields can be delimited by any characters that won't cause confusion. All valid input is numerical. Each line contains a group of numbers delimited by non-numerical characters. Numerical characters include: ".", "-", "+", "e", and "E". Commas should not be used as fraction markers or as part of a number in any way.

The quantity of numerical fields controls how the input data is interpreted. There are valid entry cases for 2, 3, 4, 6 and 9 numeric fields per line which correspond to the following scheme:

two-: [pointID1 pointID2] defines a line by endpoint IDs.
three-: [pointID1 pointID2 pointID3] defines a triangular face by vertex IDs.
four-: [pointID X Y Z] defines a point associated with a point ID
six-: [X1 Y1 Z1 X2 Y2 Z2] defines a visible line directly from coordinates.
nine-: [X1 Y1 Z1 X2 Y2 Z2 X3 Y3 Z3] defines an opaque triangular face directly from coordinates.

Blank lines and lines with unresolvable numbers of fields are ignored.

OUTPUT FORMAT

The output format generally has the format of:

       line X1,Y1 X2,Y2

If the -p option is set, pierce points are output with the following format:

        mark (X,Y) 4 <user size>

The 4 is a point style used by gradu and the size is the size entered as an option argument.
If the -d option is set, color changing information is supplied in the following format:

       p c <user color>
       line X1,Y1 X2,Y2
       p c white

This shows that for every hidden line that is rendered, there are three lines of output. The first is to set the color to the user value, the second is the line, and the third is to set the color back to white which is the default.
This data can be piped to gradu without further modification or used in some other less integrated way.

EXAMPLES

Input Format Examples

       # Defining points with 4 fields
       1  2.000E+01 3.500E-01 0.000E+00
       2  2e-2 3.5e+1 2.3e-1
       point 3 (6,-3,12)
       #4 (6,-3,12) is ignored because # creates a comment
       p=4;x=34;y=16.4;z=-10.3;
       # Defining a line with 2 point IDs
       2 4
       p1 to p3
       # Defining a tri with 3 point IDs
       1 2 3
       [1~2~3]
       # Defining a line with explicit coordinates
       (2,-3.4,12) to (4,0.5,-3.2)
       6.004e-02   6.110e+01   8.800e+01   4.000e+01    5.500e+01 1.300e-02
       # Defining a tri with explicit coordinates
       0 0 0 0 1 0 1 0 0
       (1,7,-3) (2,-3,11) (6,12,4)

Typical Output Format

       line 2.04724,0.535433 4,2
       line 0,-1 1.33333,0
       p c green
       line 1,3 1,4
       p c white
       line 1,4 1,6
       mark (1.48343,2.48343) 4 0.3
       p c green
       line 1,2 1.48343,2.48343
       p c white

Command Line Example-

[~]$ vmaster  -o  -f  -c  -.4,-.7,1 -d blue -s 15 project.txt |\
> gradu -x -10 -y -10 -X 10 -Y 10 -s 640x480 -t gif  >  project.gif

This command will cause the project.txt file to be read assuming that it contains only trifaces. Lines will be added around each triface automatically from the -f. The hidden line removal will be activated with -o. The deleted lines will be noted with "blue" in the format described above. Any line coincident with the vertices of two triangles whose angle between each other is 15 degrees or less, will be rendered as deleted (blue). The text output will be piped to gradu which will create a 640x480 gif of the image. See gradu documentation for more details.

BUGS

Sometimes the pierce points don't show up where they should on lines that don't clearly pierce the inside of the triangle.

Some cases when calculating pierce points the program discovers that the angle between the line and the tri is zero or so small that a piercing is really unlikely. This should just never happen and it's handled a bit crudely now.

As always, error checking/handling is VERY weak!!!

Some small things just aren't finished yet. The zoom factor and perspective calculations seem like a big thing not finished, but really it's pretty close.

ACKNOWLEDGEMENTS

This program and my ability to create it owe a big debt of gratitude to my amigo, Dr. Seth Rogers, whose deep computer wisdom has been rescuing me from my own ambitions since 1981.

Thanks also to Matt Seto for checking in on me and being interested enough to send me some models to play with.

AUTHOR

This marginally useful program was written by:
Chris X Edwards
<chris @ xed.ch> LWM - 2002.04.05

Return to Main Page *** Return to vmaster Page

This page was created with only free, open-source, publicly licensed software.
This page was designed to be viewed with any browser on any system.

Chris X. Edwards ~ May 2002