                                                        03/28/96


                              P O V 2 M D L

                               Version 1.2

                    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 POV2MDL does

       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 modelers 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 Ver 2.0/2.2    (optional)
       MORAY Ver 2.x

       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.95 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 successful read (syntax errors abort conversion) the MDL
       file will have been generated in the same directory (e.g.
       colors.mdl). Additionally a LOG file (e.g. colors.log) will exist
       which contains possibly issued warnings.

       For importing textures only into moray 2.0 there is a command line
       option: -t

       e.g.
              POV2MDL -t colors.pov

       Only textures (used and not used) are converted.
       Attention: some texture definitions are not ready for converting
       with POV2MDL:

       e.g.
                #declare Jade = pigment { ..... }

       POV2MDL converts only complete texture definitions. In this case
       you have to complete the definition with a texture statement:

       e.g.
                #declare Jade_Txt = texture { pigment { Jade } }



                          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. Any declarations in the include file will be 
       not be available.


                            What is supported

       First of all not every object known to POV-Ray or MORAY is supported.

       Supported Objects:

         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 and 
       POV-Ray 3.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
       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').


                                Some hints

       If you have problems converting a scene, try to render the scene with
       POV-Ray. If POV-Ray has problems, the chances are that POV2MDL will
       have them, too.

       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 write on the dos - command - line:

       set dos4gvm=@<path_where_new4g.vmc_is_located>\new4g.vmc   [RETURN]

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



                               For Techies

       POV2MDL is entirely written in C++. The parser was developed with
       Lex&Yacc, a class library manages all POV-Ray objects. The parser
       engine is absolutely independent of 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 maybe
       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
             WWW: http://ourworld.compuserve.com/homepages/thbaier
                   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 me $15. 
       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


                                 History

       Version 1.2
       - fixed bug in cone output

       Version 1.1
       - added -t option for texture output only
       - naming of POV2MDL generalized

       Version 1.0
       - First public release

       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

