                                                        11/19/95


                              P O V 2 M D L 

                               Version 1.0  

                    POV-Ray 2.x to MORAY 2.x Converter

                             by Thomas Baier





       Version 1.0 and later of POV2MDL are Shareware. Note that this 
       program is fully functional.



                            What does POV2MDL do?

       POV2MDL converts scene files from POV-Ray's POV to MORAY's MDL format.


                               Introduction

       POV-Ray 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 POV-Ray there were modellers available which supported
       graphical design of scenes. Certainly one of the first modeler
       is MORAY. For a lot of people it is one of the best POV-Ray modelers.
       Soon there was a request for a converter from POV-Ray to MORAY which
       would allow importing older, manually designed scenes.
       This is where the idea of POV2MDL was born. The program reads a 
       POV-Ray scene file and converts it to the MDL format of MORAY. 


                             What do you need?

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

       POV-Ray V2.0/2.2    (optional)
       MORAY V2.0 or higher

       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 POV2MDL and MORAY. Please use
       version 1.97 or higher.


                        Files produced by POV2MDL

       POV2MDL generates a MDL file, which can be read by MORAY V2.x.
       Additionally a LOG file will be generated which contains warnings
       that might be issued during conversion.


                             Running POV2MDL

       POV2MDL expects a filename as parameter in the commandline. The
       file should be a POV-Ray scene file in ASCII format.

       e.g.

              POV2MDL colors.pov


       After successfully reading the POV file, the MDL file will have 
       been generated in the same directory (e.g. colors.mdl). Syntax 
       errors in the POV file abort the conversion. Additionally a LOG 
       file (e.g. colors.log) may exist which contains possibly issued 
       warnings.


                          POV-Ray Search paths

       The environment variable "POV_INC" contains additional searchpaths
       for include files. 

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

       If an include file is not found during parsing, the conversion will 
       still be continued, but any declarations in the include file will 
       not be available. If these are referenced in a POV file, this will
       lead to a failure.


                            What is supported

       The following POV-Ray objects are supported:
         Box            Sphere         Cone           Cylinder
         Light_source   CSG            Heightfield    Bicubic_Patch
         Torus          Plane          Disc           Object
         Blob           Texture        Camera

       Bounding and clipping is not supported.

       The parser supports only POV-Ray 2.x syntax. POV-Ray 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 POV-Ray are ignored.

       If there is an object that is not convertable by POV2MDL, a short
       message will be written to the LOG file.


                                Converting

       The transformations are a special topic during conversion. The
       syntax of POV-Ray accepts transformations (scale, rotate and
       translate) at several locations and in several orders. MORAY on
       the other hand accepts object and texture transformations 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 POV-Ray or MORAY. If POV2MDL recognizes such a
       construction 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').


                                Some hints

       If you have problems converting a scene, try to render the scene with
       POV-Ray. If POV-Ray has problems, the chances that POV2MDL will have 
       problems, too. Conversely, if POV-Ray can render the file, POV2MDL will
       probably be able to read it, too. If not, I would appreciate hearing
       from you with a sample POV script showing the error. See the end of 
       this file for ways to reach me.

       If you have problems with memory try this:

       put these 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 on the DOS command-line enter this:

       set dos4gvm=@new4g.vmc   [RETURN]

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



                               For Techies

       POV2MDL is written entirely in C++. The parser was developed with
       Lex&Yacc, a class library manages all POV-Ray objects. The parser
       engine is absolutely independent from any MORAY modules and could
       be used for a wide variety of tasks.
       For example the POV-Ray syntax could be easily enlarged by some
       elements for animation. Nevertheless the output can be pure
       POV-Ray code.

       Every converter from POV-Ray 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 POV-Ray has (except
       POLYRAY).

       All known modelers for POV-Ray 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 POV-Ray.


                                Thanks to

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

                                   The future

       Further I have a POV-Ray to RAW 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 scene file and an error
       description.

       Thanks.


                              Use of POV2MDL

       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, POV2MDL 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
                        Internet: thbaier@ibm.net
                  Compuserve: 100527,3011 or GO GRAPHDEV


       Both the POV2MDL program and documentation are Copyright (c) 1995
       by Thomas Baier. You are not authorized to modify the program.
       "POV2MDL" is a trademark.


                               Registration

       If you enjoy this program, use it frequently, and can afford to
       pay a registration fee, then send $15 to my address above. 
       Please include your name and mailing address. 
       With this contribution you help me improve POV2MDL. With registration 
       you can expect a prompt response on questions or bugs. Thanks. 

                                Disclaimer

       POV2MDL 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 POV2MDL 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
       POV-Ray is a trademark of the POV-Team
       MORAY is a trademark of SoftTronics, Lutz + Kretzschmar


                                 History


       Version 0.5
       - syntax error with declared color_maps fixed

       Version 0.4
       - some bugs fixed
       - blobs added
       - camera

       Version 0.3
       - some bugs fixed
       - bug in CSG - transformations fixed
       - very old (!) bug in heightfield fixed

       Version 0.2
       - first Beta

