This is the README file for

   vrml2pov, version 0.7

        Copyright (C) 1998-2003 by Paul Thiessen, Chemical Graphics
                                        paul@chemicalgraphics.com
                                http://www.chemicalgraphics.com/paul

Please see the LEGAL file for information on how this software may be used.
This software is available via the WWW at

http://www.chemicalgraphics.com/paul/vrml2pov

Please see the supporting web pages for information on features, philosophy,
and bug reports.

This implementation of (a subset of) VRML97 is based on:

	    The Virtual Reality Modeling Language
	  International Standard ISO/IEC 14772-1:1997
     Copyright (c) 1997 The VRML Consortium Incorporated.

More information on the VRML standard may be obtained at www.vrml.org, and on
POV-Ray at www.povray.org.

Molscript and Ribbons users: please see the web site for information on using
vrml2pov with output from these programs. Molscript users will also want to
pay careful attention to the "-b" option as discussed below.

-----------------------------------------------------------------------------

In this file, I, the author, attempt to explain (or rationalize) the use and
some of the features of the vrml2pov program. First, the usage:

The basic usage is simple, i.e. "vrml2pov scene.wrl scene.pov" will convert
the VRML97 file 'scene.wrl' into a POV-Ray file 'scene.pov'. It should also
work with VRML 2.0, but not VRML 1.0.

The complete usage statement is below. Two filenames are required, and all
switches are optional.

vrml2pov [-v] [-t] [-h #] [-l #] [-p #] [-b] vrml_file pov_file

where
  -v gives a verbose output (mainly for debugging)
  -t prints out the final node tree after parsing and expansion of PROTO's
  -h sets headlight brightness (generally from 0-1, e.g. -h 0.8;
       if not specified, default is based on # other lights present)
  -l sets line radius for IndexedLineSet (default 0.05)
  -p sets point radius for PointSet (default 0.05)
  -b turns on backface culling - requires first node to be Viewpoint
       (and currently only applies to IndexedFaceSet)

Now, a longer explanation of these options is in order:

-v

This verbose output shows a little of what vrml2pov is doing - i.e., what
nodes it's reading from the VRML file, and what it's outputting to the POV
file. Included in this output are warnings about possibly non-obvious
behaviour, so if you think something is not being converted properly, check
this output for a possible explanation of why.

-t

This is also a sort of debugging option. It prints out the node tree
constructed from the VRML file, *after expansion of PROTO statments*. In other
words, this is the scene of only standard nodes that is passed to the POV
output generator. Use this if you think your VRML scene is not being parsed
properly, and you want to figure out just what your VRML file contains
according to vrml2pov.

-h

This is the headlight brightness. Many VRML files don't come with built-in
light sources (and in fact vrml2pov in this version doesn't recognize VRML
lights, anyway), so this option allows you to control the brightness of the
headlight - a light at the same position as the camera. A headlight
brightness of 0.4, for example, will place a light_source { ... rgb
0.4*<1,1,1> } in the POV scene. The headlight color is always white.

-l, -p

VRML nodes IndexedLineSet and PointSet are implementation-dependent nodes that
are intended to output thin lines or single points. In VRML browsers, these
are just single-pixel width lines or points, but in POV scenes there is no
such thing as a "pixel". Lines and points here are rendered as thin cylinders
or small spheres; since there is no obvious way to compute the radius of
a line or point that will appear "very thin" in any given POV scene, these
options allow you to adjust them to whatever works best.

-b

This option requires a fair bit of explanation, so bear with me. "Backface
culling" is an optimization trick that VRML uses to speed up polygon
rendering. Basically, it removes polygons that face away from the viewer,
since those are often on the backside of objects and are not visible anyway.
While certainly useful for VRML browsers, in my opinion this goes against the
whole POV-Ray "concept," because if polygons are removed, objects will not
cast shadows that you would expect based on their perceived solidity, and
similarly, if seen by reflection will be incomplete. Also, because these
cullings are done before the POV scene is output, they are effective only for a
SINGLE camera location - thus if the camera is translated even slightly, the
scene will look wrong. (However, the camera can still be rotated about its
location point.) So, unless this option is given, vrml2pov always includes
all polygons in an object like an IndexedFaceSet (which is currently the only
type of object on which culling can be done).
  However, there are some programs that rely on backface culling tricks to
render properly, such as the 2-color helix ribbons that Molscript generates -
in fact, this is the reason why I put this somewhat troublesome option in here
at all. So this option must be used in such cases to force backface culling to
be done, with caution and at the risk of incurring the problems mentioned above.
  If backface culling is to be done, the first node present in the VRML file
*must* be a Viewpoint node. I realize this might sometimes be a pain in the
you-know-what, and may be "fixed" in later versions. The reason for this is
that the calculations required for backface culling depend upon the
viewpoint position, so this must be known in advance, before things like
IndexedFaceSet are converted into POV objects. These faces are then simply
left out of the POV scene, and of course cannot be dynamically recalculated as
the camera is moved around later on.

-----------------------------------------------------------------------------