                                                        01/06/95


                                  P O V 2 M R Y

                             Version 0.91 Public Beta

                       POVRAY 2.x to Moray 1.5x Converter

                            a "public domain program"

                                 by Thomas Baier








                               What makes POV2MRY

       POV2MRY converts scene files for POVRAY to MORAY's MDL- format.


                                  Introduction

       POVRAY certainly belongs to the best raytracers and is freely
       available. The voluminous script language makes the realization of
       complex scenes with high image quality possible. Soon after the
       release of POVRAY there were modelers available, which supported
       graphical design of sceneries. Certainly one of the first modeler
       is MORAY. For a lot of people it is one of the best POVRAY modeler.
       Of course the high quality of MORAY involves some limitations. Not
       all objects of POVRAY are supported and the abilities in design of
       textures are sufficently only for elementary requirements. Soon
       there was a request for a converter from POVRAY to MORAY which
       would make the import of older, manually designed scenes possible.
       Exactly at this point POV2MRY started. The program reads a POVRAY
       scene file and converts it to the MDL format of MORAY . 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 a directory of your choice. Make sure
       that the program DOS4GW.EXE is available via the PATH variable.
       The DOS Extender 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 by MORAY.
       Additionally a LOG file will be generated which contains warnings
       that might be issued during conversion. If you use textures via
       declare, all used textures are written to a ANC - File. ANC means
       Additional iNClude - File.


                                 Running POV2MRY

       POV2MRY expects a filename as parameter in the commandline. The
       file should be a POVRAY scene file in ASCII format.

       e.g.

              POV2MRY colors.pov


       After successful read (syntax errors abort conversion) the MDL
       file will have been generated in the same directory (e.g.
       colors.mdl). The ANC - File will be generated (e.g. colors.anc).
       Additionally a LOG file (e.g. colors.log) will exist which
       contains possibly issued warnings.


                              set - variable POV_INC

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

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

       If an include file is not found reading will be aborted.


                                What is supported

       First of all not every object known to POVRAY or MORAY is supported.

       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 the direction vector is
       used.

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

       Another problem results from the different default values for the
       camera definition. MORAY defines the up and sky vector fixed with
       <0,0,1>. POVRAY does it per default with <0,1,0>. MORAY defines
       the z-axis as height, POVRAY defines the y-axis as height.

       e.g.:

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


       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 scene file for POVRAY with default up and sky vectors looks a bit
       strange after conversion, reexport to POVRAY and rendering.
       The image is mirrored horizotally and vertically. The camera view in
       MORAY gives the same view. The converter will issue a message
       like:  "Sky-Vector is different form Moray's camera settings in
       Object xxx !"


       In this case the best solution is to modify the wrong vectors.

       e.g.:

       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>
       }

       In the next release i will have a better solution.


       Texture:
       Normal modifications are ignored because they are not supported
       by MORAY. Pigment and finish modifications are supported as fas
       as MORAY does.

       Additional the ANC - file is created, which contains all used
       texture - declares. After exporting the scene you can add this
       file as include - file.

       e.g.:

              #declare my_texture = texture { color GREEN }

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

       Pigment and finish identifiers will be expanded. The names won't
       be imported but the single parameters will be converted.

        e.g.:

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

       The "default" texture statement will be evaluated. The feature
       works the same as it does with POVRAY. If "default" is defined
       every object without a texture will have 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 an 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
       syntax of POVRAY accepts transformations (scale, rotate and
       translate) at several locations and in several orders. MORAY on
       the other side accepts only object and texture transformationes
       and only in a strict order (scale, rotate and then translate).
       This leads to some strangs effects after conversion.

       The surprise appears if a scale <a,b,c> follows a rotation. The
       conversion to the sequence scale, rotate, translate can not be
       made complete. The result in MORAY will not be what you expected.
       An additional shear vector would be helpful but is not yet
       implemented in POVRAY or 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 when the scaling vector is of the
       form <a,a,a> (equal to 'scale a').

       Implicite transformations and avoiding shear vectors:

       object structure of POVRAY:

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

       object structure of MORAY:

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

       FACE - PARAMETER:
       Moray supports only fix parameters (e.g. box { <-1,-1,-1>,
       <1,1,1> }). At this point an implicite transformation could
       happen. Fortunately this problem can be avoided moving the
       implicite transformations to real transformations. The fix
       parameters of every object supported by MORAY can be seen by
       creating an object in MORAY and exporting it directly.

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

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

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

        e.g.:

        scenery file for POVRAY:

           ...
           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
       this becomes:

           ...
           #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 evaluating 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>
        }

       In this release now i use the trick to avoid all shear
       operations.

       e.g.

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

           }
           ...

       The converter translates the object in to following structure:

           object
           {
                    box
                    {
                        <0,0,0>,<2,2,2>
                        texture {my_texture}
                        rotate <90,80,70>
                    }
                    scale <4,3,2>
                    translate <3,2,1>
           }


                                Some hints

       If you have probs converting a scene try to render the scene with
       POVRAY. If POVRAY has probs, the chances are not too bad that
       POV2MRY will have either.

       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 entirely written in C++. The parser was developed with
       Lex&Yacc, a class library manages all POVRAY objects. The parser
       engine is absolutely independent from the MORAY modul and could
       be used for a wide variety of tasks.
       For example the POVRAY syntax could be easily enlarged by some
       elements for animation. Nevertheless the output can be pure
       POVRAY code.

       Every converter from POVRAY to XXX is conceivable ..., but makes
       no sense, because I am not aware of other modelers or raytracers
       that follow the rules and have the features POVRAY has (exept
       VIVID and/or POLYRAY).

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


                                     Thanks to

       Bernhard Baier
       Lutz Kretzschmar         (Moray)
       Erkki Sondergaard        (POV-Team)
       Lex van der Sluijs       (GUM)
       Andreas Lagotzki         (RR)

                                   The future

       The next project will be a pure POVRAY texture parser. I would
       publish this engine for free use. Such an engine would make
       texture editors be able to import POVRAY textures.

       Further I have a POVRAY to DXF converter in mind. 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 the POV-Team
       Moray is a trademark of SoftTronics


                                 History

       Version 0.91
       - problem with pigment in textures.inc solved
       - if pigment contains nonsupported items, no texture is written
       - parser optimized
       - additional ANC - file is written. It contains all used textures
       - problem with composite solved
       - avoiding all shear operation within a object definition
       - heightfields now correct imported

       Version 0.9
       - first release

