genf v0.1 - A program for creating wire-frame objects for POV-Ray.

This is genf, a program for creating wire-frame objects for use with POV-Ray. I wrote this program partly as a way to learn a little more about using POV-Ray in general and partly because I was bored. It was based very loosely on the genb program (found on the POV-Ray ftp site) by Pascal Roobrouck. genf reads in a configuration file that describes the type of frame to create and outputs an include file in POV-Ray 2.0 format.

BUILDING GENF:

genf was written on a Linux system and contains very little OS specific code, so it should build on or port fairly easily to any Unix OS. I don't know if it will port to MS or Mac environments, since I've never programmed on those OSs.

To build genf you should only need to run "make". This will compile the 4 object modules and then link them into the single genf executable. If anyone has any problems building this, please email me, especially if you have a fix for the problem.

USING GENF:

Using genf is simple: just run

      genf -c <config_file>

genf will output to standard out the values it will use to create the frame(s) and write to a file the actual frame definition. The format of the output file will be discussed later. This output file is an include file intended to be used by some other .pov file for parsing and displaying with POV-Ray itself. The object genf creates is centered on the origin so it can be translated and rotated based on that assumption.

Example image of genf generated objects There are a couple of .genf configuration files in the distribution:


Also, there is frame.pov which you can use to sample the results of running genf with each of the sample configuration files. Just uncomment the appropriate object line and run with POV-Ray.

THE CONFIGURATION FILE:

genf has only one command line argument: -c config_file. You can see this by running "genf -?". The config_file is a set of configurable options, such as the type of frame to build, what object to use for joints, whether or not to connect joints across the length of the frame, and so forth. There are quite a few configurable items and its questionable whether using this program is any easier than creating the objects yourself, however I think its easier to use this program. Then again, its probably alot easier to use a modeller. To each his own.

The configuration file uses a very simple syntax. First of all, any line that starts with two pound signs "##" is a comment. Comments must begin at the start of the line, not after configuration items. Blank lines are ignored as well.

All other lines contain keyword/value pairs. The "keyword" is a configurable item, and the value is what you want to set the keyword to. For example, the keyword "shape" is used to determine the basic shape of the frame and "cone" is a possible value for the shape keyword. Keywords and their associated values are seperated by a colon, such as

   shape:cone

Don't use leading or trailing spaces in the keyword. Spaces may or may not be used in values, depending on the type of value needed.

Not all keywords make sense for all frames. If a value is set for a keyword that is not used by genf to create a particular frame it is simply ignored.

Keywords, their possible values and their defaults:

This is the list of keywords, what they are used for, the possible values that can be used, and the default value if no value is specified in the configuration file. It will probably help to look at the default.genf sample configuration file. This file contains all the keywords and their default values in a properly formatted configuration file.

Keyword Used for... Valid Values Default
shape Type of frame to make Box, Cone (case insensitive) Box
outfilename name of include file for genf to write to any valid filename frame.inc

Keywords that are valid for any shape:

Keyword Used for... Valid Values Default
id unique identifier for objects created by genf any string 1
rodradius Radius of individual rods (cylinders) in the frame float value .01
joint object to use for vertices where rods meet any valid POV-Ray object none (no visible joint)
texture texture to use for frame any valid POV-Ray texture Silver_Texture
elements number of shape's to put end to end to create this frame integer value 1
length length of single element float value, in POV-Ray units 1
crossends connect the vertices across the length of the shape with rods? True, False (case sensitive) True
joinlength connect vertices opposite each other across the length of the shape with rods? True, False (case sensitive) True

Note: crossends is used with offset to determine which vertices to connect, whereas joinlength simply connects vertices exactly opposite each other. For cones the offset can be any value but for boxes the offset is always 1, which has the effect of making an "X" along the sides of the box. Offset is defined in the next section.

Keywords valid only for cones:

Keyword Used for... Valid Values Default
radius1 radius of left end of cone (centered on -x axis) float value 1
radius2 radius of right end of cone (centered on +x axis) float value 1
points1 number of vertices on left end of cone integer value 2
points2 number of vertices on right end of cone integer value 2
offset when crossing the length of the cone, how far offset should the second endpoint be from the first? integer value 0
coneendshape torus or cylinder with its center cut away (so you have either a rounded ring on the end of the cone, or a sharp edged ring) torus/cylinder (case insensitive) cylinder
coneendthickness thickness of ring on end of cone float value .1

Keywords valid only for boxes:

Keyword Used for... Valid Values Default
width Z direction of box float value 1
height Y direction of box float value 1

Notes:

OUTPUT FILE FORMAT:

The POV-Ray .inc file that genf outputs will specify at the top of the file the name of the object to be used in your .pov file. For example, the file generated by the default.genf configuration file looks like this:

// This file generated with the genf utility.
// (c) 1996 Michael J. Hammel
//
// Box Frame Object: genf_box1
//

After this header will be a number of objects that are created prior to creating a final union of all objects that becomes the object "genf_box1". You only need concern yourself with the name of the object listed in the header. Make sense? Play with it awhile, it will. :-)

Questions or comments are welcome: mjhammel@csn.net

You can also check out my home pages for all the info I've been gathering regarding POV-Ray. I'm new at it, so the info may not be of much help to the experts, but its a good place to look if you're just getting started.

My Home pages starts at http://www.csn.net/~mjhammel/.



Michael J. Hammel <mjhammel@csn.net>
Created: January 29, 1996
Updated: June 8, 1996