                                                        12/20/94


                                  P O V 2 M R Y

                             Version 0.9 Public Beta

                       POVRAY 2.x to Moray 1.5x Converter

                            a "public domain program"

                                 by Thomas Baier








                               What makes POV2MRY

       POV2MRY converts POVRAY - scenery - files to the MORAY's MDL -
       format.


                                  Introduction

       POVRAY belongs certainly to the best raytracers and is freely
       available. The voluminous scriptlanguage makes the realization of
       complex sceneries with high imagequality possible. Soon after the
       publication of POVRAY there were modelers available, which
       support graphically building of sceneries. Certainly one of the
       first modeler is MORAY. For a lot of people it belongs to the
       best POVRAY - modeler. Of course the high quality of MORAY
       involves some limitations. Not all POVRAY - objects are supported
       and the generation of textures are only enough for easier
       requirements. Soon there was a call for a converter form POVRAY
       to MORAY, which makes the import of old manually builded
       sceneries possible. Exactly at this point POV2MRY starts. The
       program reads in a POVRAY - scenery and converts it to MORAY -
       MDL - format. Of course the converter has the same limitations as
       MORAY.


                                What do you need

       minimum 386 Compatibel PC
       DOS 3.3 or higher
       Windows 3.x or higher (Dos-Box)
       OS/2 2.x or higher    (Dos-Box)

       POVRAY Ver 2.0/2.2    (optional)
       MORAY Ver 1.50/1.53

       Copy the shipped files to an directory you want. Be aware that
       the program DOS4GW.EXE is available via path - statement. The
       dosextender is needed by POV2MRY and MORAY . Please use the
       version 1.95 or up.


                            Files produced by POV2MRY

       POV2MRY generates a MDL - file, which can be read in MORAY.
       Additional a LOG - file will be generated, which contains some
       warnings during converting.


                                 Running POV2MRY

       POV2MRY expects a filename as parameter in the commandline. The
       file should be a POVRAY - scenery - file in ASCCI - format:

              POV2MRY colors.pov


       After successful readin (syntaxerrors lead to an abort) the MDL -
       file will be generated in the same directory (f.e. colors.mdl).
       Additional a LOG - File (f.e. colors.log), which contains
       possible warnings.


                              set - variable POV_INC

       The set - variable "POV_INC" contains additionally searchpathes
       for used include - files. This feature behaves exactly in the
       same way as POVRAY does:

              set pov_inc=c:\povray;d:\moray\scenes

       If a include - file is not found, the readin is abort.


                                What is supported

       For the first not all POVRAY - objects and not all MORAY -
       objects are supported.

       Objects:

       Box
       Sphere
       Cylinder
       Light_source
       CSG
       Heightfield
       Bicubic_Patch
       Torus
       Plane
       Disc
       Object
       Texture
       Default
       Camera


       Camera:
       Location, Look_at and the length of th direction - vector is
       used.

       A big problem is parallelity of the location - vector and the sky
       - vector. Both programs have the prob. The error appears with
       "abnormal program termination" and is a floating point error
       (during calculating a normal vector). If you have the source of
       both programs it is easy to avoid this message, but i do not, and
       now the message "Warning: Look_at/Location vector parallel to
       Moray sky vector in xxx !" will be written and a little bit
       (0.001) will be add to the x - value of the location vector. If
       somebody has a better idea, please call me ;_))

       An other problem is the different dealing with default values for
       the camera. MORAY defines the up and sky - vector fix with
       <0,0,1>. POVRAY does it per default with <0,1,0>. MORAY defines
       the z - axis as hight, POVRAY defines the y - axis as default.

       f.e.:

       camera
       {
                location <10,10,10>
                look_at <0,0,0>
       }

       POVRAY defines the up an sky - vectors with <0,1,0> as default.

       MORAY defines the camera in this way (after export):

       camera
       {
                location  <1.000, -8.000, 5.000>
                direction <0.0,     0.0,  0.6667>
         ???--->sky       <0.0,     0.0,  1.0>  // Use right handed-system!
         ???--->up        <0.0,     0.0,  1.0>  // Where Z is up
                right     <1.3333,  0.0,  0.0>
                look_at   <0.000, 0.000, 1.000>
       }

       A POVRAY - scenery - file with default up and sky - vectors looks
       after converting, exporting to POVRAY and rendering a little bit
       strange. The image is mirrored by the horizotal and vertical
       axis. The MORAY - camera gives the same view. The converter will
       give you a message like this : "Sky-Vector is different form
       Moray's camera settings in Object xxx !"


       In this case the best way I can offer is to modify the wrong
       vectors.

       f.e.:

       camera
       {
                location  <1.000, -8.000, 5.000>
                direction <0.0,     0.0,  0.6667>
         !!!--->sky       <0.0,     1.0,  0.0>  // Use right handed-system!
         !!!--->up        <0.0,     1.0,  0.0>  // Where Z is up
                right     <1.3333,  0.0,  0.0>
                look_at   <0.000, 0.000, 1.000>
       }


       Texture:
       Normal items are ignored, because it is not supported by
       MORAY. Pigment and finish are only supported in the same way as
       MORAY does.

       Textureidentifiers will be not expanded, but the names will be
       imported.

       f.e.:

              #declare my_texture = texture { color GREEN }

              box { <0,0,0>,<1,1,1> texture {my_teyxture}}

       But if you want to export the scenery and raytrace, you have to
       care for the texture - includes or the declares (for the first).
       In next release i will have a better solution.

       Pigment and finish - identifiers will be expanded, the names will
       not be imported, but the single parameters will be converted.

        f.e.:

              box { <0,0,0>,<1,1,1> texture { pigment{ redmarble }
                                              finish { mirror }  }

       The default texture will be evaluate. The feature works in the
       same as POVRAY does. If "default" is defined, every object
       without a texture will get this texture.


       Bounding and clipping is not supported.
       The object "cone" is not convertable, because MORAY does not
       support the second radius.

       The parser supports only POVRAY 2.0 syntax. POVRAY 1.0 syntax is
       not supported. The exact syntax is described in POVRAY.DOC.

       The keyword "version" is totally ignored.

       All other objects and features of POVRAY are ignored.
       If there is a object, that is not convertable by POV2MRY, a short
       message will be written to the LOG - file.


                                   Converting

       The transformations are a special theme for converting. The
       POVRAY - syntax accepts transformations as scale, rotate and
       translate at several locations and in several orders. On the
       other side, MORAY accepts only object - transformations and
       texture - transformationes and only in a strict order (scale,
       rotate and then translate). This leads after converting to some
       strangs effects.

       The surprise appears, if a scale <a,b,c> follows a rotation. The
       converting to the form scale, rotate, translate can not be made
       complete. The result in MORAY could not be what you expect. A
       additional shear - vector would be helpfull, but it is not yet
       implemented in POVRAY and MORAY. If POV2MRY recognizes such a
       construct, the message "Warning: Inaccurate Matrix Operation
       (Shear Vector) in Object xxx !" will be written to the LOG -
       file. The problem does not appear if scaling by the form <a,a,a>
       follows.

       Implicite transformations and avoiding shear vectors:

       POVRAY - object - structure:

       OBJECT
       {
              FACE-PARAMETER
              FACE-TRANSFORMATIONS
              texture
              {
                     TEXTURE-PARAMETERS
                     TEXTURE_TRANSFORMATIONS
              }
              OBJECT_TRANSFORMATIONS
       }

       MORAY - object - structure:

       OBJECT
       {
              FIX-FACE-PARAMETER
              texture
              {
                     TEXTURE-PARAMETERS
                     TEXTURE-TRANSFORMATIONS
              }
              OBJECT-TRANSFORMATIONS
       }

       FACE - PARAMETER:
       Moray supports only fix parameters (f.e. box { <-1,-1,-1>,
       <1,1,1> }). At this point a implcite transformation could be
       happen. Fortunately this problem can be avoid by moving the
       implicite transformations to real transformations. The fix
       parameters of every object supported by MORAY can be seen, if you
       create a object and export it directly.

       FACE-TRANSFORMATIONS:
       This kind of transformation are not known by MORAY.

       To avoid the collection of FACE - TRANSFORMATIONs, OBJECT -
       TRANSFORMATIONs and TEXTRUE - TRANSFORMATIONs the general POVRAY
       - object - structure will be divided as follow:

        union
        {
                union
                {
                        OBJECT
                        {
                                FACE-PARAMETER
                        }
                        FACE-TRANSFORMAIONS
                }
                texture
                {
                        TEXTURE-PARAMETERS
                        TEXTURE-TRANSFORMATIONS
                }
                OBJECT-TRANSFORMATIONS
        }

        f.e.:

        POVRAY - scenery - file:

        ...
        box
        {
                <0,0,0>,<2,2,2>
                rotate <30,0,0>
                texture {my_texture}
                scale 4
                translate <3,2,1>
        }
        ...

       After converting, importing to MORAY and exporting to POVRAY:

        ...
        #declare ##box0 = box {
          <-1, -1, -1>, <1, 1, 1>
          translate <1.000000, 1.000000, 1.000000>
        }

        #declare #box0 = union {
          object { ##box0 }
          rotate <30.000000, 0.000000, 0.000000>
        }

        union {
          object { #box0 }
          texture {
            my_texture
            ...
          }
          scale <4.000000, 4.000000, 4.000000>
          translate <3.000000, 2.000000, 1.000000>
        }



       After solving all declare's:

        union
        {
                union
                {
                        box
                        {
                                <-1,-1,-1>,<1,1,1>
                                translate <1.000000, 1.000000, 1.000000>
                        }
                        rotate <30.000000, 0.000000, 0.000000>

                }
                texture
                {
                        my_texture
                        ...
                }
                scale <4.000000, 4.000000, 4.000000>
                translate <3.000000, 2.000000, 1.000000>
        }

       I think this would be the best way to avoid shear - operations. If
       you have a better way, please give me a mail.


                                Some hints

       If you have probs during converting, try to render the scenery
       with POVRAY. If POVRAY has probs, the chance is not bad, that
       PO2MRY has the same probs .

       If you have probs with memory, try this:

       put this 10 lines in to a file named new4g.vmc ...

       !.VMC file DOS4GW.EXE
       !This file shows the parameter values.
       minmem = 1024           At least 1024K bytes of RAM is required.
       maxmem = 8192           Uses no more than 8MB of phys. RAM
       !virtualsize = 32768     Swap file plus allocated memory is 32MB
       virtualsize = 16384      Swap file plus allocated memory is 16MB
       !To delete the swap file automatically when the program exits, add
       deleteswap
       !To store the swap file in a directory called SWAPFILE, add
       !swapname = c:\swapfile\dos4gvm.swp

       and write on the dos - command - line:

       set dos4gvw=@new4g.vmc   [RETURN]

       This is from the DOS4GW - documentation and will increase the
       virtual memory for DOS4GW.



                               For Techies

       POV2MRY is completly written is C++. The parser was developed
       with Ley&Yacc, a classlibrary manages all POVRAY - objects. The
       parser engine is totally independent from the MORAY - modul and
       can be used for a wide variety of tasks.
       F.e. the POVRAY - syntax can be easily enlarged by some animation
       - elements. The output would be pure POVRAY - code.

       Every converter form POVRAY to XXX is conceivable ..., but makes
       no sense, because i know no modeler or raytracer that follows the
       rules and features of POVRAY (exept VIVID or POLYRAY).

       All known modeler for POVRAY are very strict in using
       transformations. The work for a converter is very hard, and i am
       not sure it is worth. The converter could not support all feature
       of POVRAY.


                                     Thanks to

       Bernhard Baier
       Lutz Kretzmar (Moray)
       Erkki Sondergaard (POV-Team)
       Lex van der Sluijs (GUM)


                                   The future

       The next theme will be a pure POVRAY - texture - parser. I would
       publish this engine for free use. This engine makes
       texture - editors with POVRAY - import possible.

       Further i will think about a POVRAY to DXF - converter. First
       ideas are in my drawer.


                         If you find a strange situation

       If you have a scenery or object that is not convertable in the
       right way, or you find a bug or some strange behaviour, please
       send me a letter or e-mail with the scenery - file and an error
       description.

       Thanks.


                                 Use of POV2MRY

       You are welcome to make copies of this program and pass them on to
       friends or post this program on bulletin boards or distribute it
       via disk catalog services provided the entire distribution is
       included in its original, unmodified form. A distribution fee may
       be charged for the cost of the diskette, shipping and handling.
       However, POV2MRY may not be sold, or incorporated in another
       product that is sold, without the permission of Thomas Baier.

       You are welcome to contact the author:

                                  Thomas Baier
                                 Ammerseestr. 9
                                 85551 Kirchheim
                                     Germany
                             FidoNet: 2:2480/843.24
                           RenderRing: 511:3000/333.24
                              PCG-Net: 9:526/327.24

       Both the POV2MRY program and documentation are copyright (c) 1994
       by Thomas Baier. You are not authorized to modify the program.
       "POV2MRY" is a trademark.

                                   Disclaimer

       POV2MRY is provided "as is" without warranty of any kind, either
       expressed or implied. This program may contain "bugs" and
       inaccuracies, and its results should not be assumed to be correct
       unless they are verified by independent means. The author assumes
       no responsibility for the use of POV2MRY and will not be
       responsible for any damage resulting from its use.


                                   Trademarks

       OS/2 is a trademark of IBM
       Windows is a trademark of Microsoft
       DOS is a trademark of Microsoft
       Povray is a trademark of POV-Team
       Moray is a trademark of SoftTronics
