
               -=> Fractint to POV-Ray v0.5 <=-

                  -=> by David Grossman <=-

                        -=> 1/3/94 <=-


Requires:

        Fractint v16 or later
        POV-Ray 2.0 or later
        Some familiarity with both

Introduction:

     Fractint to POV-Ray ( hereafter referred to as 'FRCT2POV' ) 
reads a specified parameter set from a Fractint parameter file 
and performs the required rotation and scaling in order to 
reproduce the identical image in POV-Ray with the 'mandel' 
pigment specification. This allows one to map a fractal 
Mandelbrot image onto an object in POV-Ray without using an 
image_map of a gif. The original Fractint Mandelbrot can be 
unevenly scaled, rotated and skewed ( non-perpendicular edges ) 
and FRCT2POV will still be able to convert it. FRCT2POV will also 
attempt to convert the Fractint color map into a POV-Ray 
compatible 'color_map'. 
     There are a number of advantages to using the 'mandel' 
texture instead of an image_mapped Fractint gif. One advantage is 
that all detail in the Mandelbrot set is retained over all areas. 
An 'image_map' of a Mandelbrot 'gif' obtained from Fractint will 
be of inferior quality when mapped onto an object. Negligible 
extra memory is needed to do a 'mandel' texture when compared to 
the amounts required by a 'image_map', especially large images or 
multiple images. Another advantage is the fact that the number of 
times a color map is repeated can be modified in POV with the 
frequency keyword whereas in Fractint this frequency is fixed. 
The 32767 upper limit on the maximum number of iterations in 
Fractint is not imposed in POV-Ray. ( This limit would only 
affect the extremely 'deep' mandelbrots but in general is not 
very important. ) True-color (24 bit) images with anti-aliasing 
can also be obtained with POV-Ray. ( I am not sure how Fractint 
works in true-color mode. ) Of course there are many 
disadvantages to the POV-Ray 'mandel' texture compared with the 
Fractint Mandelbrot. One important disadvantage is that POV-Ray 
limits the number of entries in the 'color_map' to 20. This 
doesn't mean you can only use 20 colors but that you can only 
have 20 color 'nodes'. See the POV-Ray documentation on this 
subject. Another disadvantage is that POV-Ray doesn't support any 
of the 'goodies' that are included in Fractint. From all of the 
'basic options' that Fractint supports, only the maximum number 
of iterations can be used. None of the 'extended options' are 
supported. ( Color cycling is supported in a different manner. ) 
None of the Mandelbrot 'parameters' are supported either. 
Although this may seem very limiting, many of the 'Mandelbrot 
set' images that are commonly seen are just basic Mandelbrots 
with an interesting color map applied. There are infinite 
possibilities for creating beautiful fractal textures. In POV-
Ray, rendering time increases depending on the location in the 
Mandelbrot set when using the 'mandel' texture. When using an 
'image_map', the set does not have to be calculated as it is 
rendered. If you only want to do a planar Mandelbrot image, an 
'image_map' may still be the way to go. If you want a complex or 
very large object to have a Mandelbrot texture, then a POV-Ray 
'mandel' pigment will be the best solution.

Notes on Fractint input files:

     FRCT2POV assumes that the specified parameter is a 
Mandelbrot. ( It doesn't check. ) The only information that is 
read from the parameter file is the parameter name, 'corners=', 
'maxiter=', 'colors='. This means that you can have an 
interesting mandelbrot with all of the cool Fractint options such 
as biomorph, decomposition, log palette, etc. and still be able 
to convert the basic Mandelbrot to POV-Ray. ( The POV-Ray 
Mandelbrot will not look exactly the same as the Fractint version 
but it will represent the same location in the set. ) 
     The color map can be specified in the parameter file as a 
file name 'colors=@filename.map', it can be encoded, or it can be 
specified on the command line.

Notes on color map conversion:

     Fractint to POV-Ray converts Fractint color maps by finding 
the largest intervals that can be represented by a smooth color 
transition between two fixed colors. These colors are then 
assigned as POV-Ray color_map entries. Due to the fact that 
Fractint color maps are rounded to the nearest factor of 4, the 
conversion process is not perfect. It calculates the maximum 
error that occurs when determining the smooth color transition 
and if this error is less than a specified value, it saves the 
endpoint colors as 'nodes' or color_map entries. This error 
starts at the value specified by 'mm=' and is then increased 
until the color map can be converted with less than or equal to 
twenty entries. ( this limit is imposed by POV-Ray ) If the 
maximum error is increased past a limiting value of 20 and the 
color map entries exceed 20 ( no relation to the previous '20' ) 
the color map is not written. If the error becomes too big then 
the color_map will bear little resemblance to its original 
Fractint map. The default starting value for the starting 
'maximum error' value is 4. Color maps that are converted at this 
value are very accurate.

Notes on output files:

     FRCT2POV output files consist of a 'header' which states 
which file, parameter, and color map was converted as well as the 
'#declare'd names and '.inc' file name. The time and date that 
the file was converted is also shown. ( File 'header' information 
can be turned off if desired. ) By default, the POV 'color_map' 
is embedded in the '#declare'd texture. ( The color_map can be 
'#declared' and then used in the '#declare'd texture if desired. 
) The '#declare'd names can be specified or defaulted to the name 
of the converted parameter and color map.
     This version of FRCT2POV '#declare's the Mandelbrot as a 
'pigment' rather than a 'texture'. In the new POV ( 2.0 or later 
) 'pigment' implies 'texture'. In later versions of FRCT2POV, a 
'texture' may be '#declare'd with embedded 'normal', 'finish' and 
additional transformation specifications.
     The specified Mandelbrot set is first translated to the 
origin. Then is rotated and scaled. ( If required )
     Some rotated and skewed Mandelbrot sets require two sets of 
rotations and scaling. In this case, the first rotation orients 
the set to the optimum position to 'skew' the image with the 
subsequent scaling. The image is then rotated and then scaled to 
its final position. ( The fact that unskewed, rotated Mandelbrots 
are still subjected to the unskewing rotation and scaling is due 
to numerical inaccuracies when testing for perpendicular axes. 
This problem will be fixed in the next version. )
     By default, the Mandelbrot image is scaled to fit the area 
bounded by the lines x= +/-1 and y= +/-0.75 . This allows you to 
scale the texture accurately. ( Note that this window aspect 
ratio is the same as the most common video modes used in Fractint 
and POV-Ray )

Installation:

     Please see the file INSTALL.TXT for installation 
instructions.	

Fractint to POV-Ray file list:

     Please see the file FILELIST.TXT for information on the 
Fractint to POV-Ray package files.

Operation:

     FRCT2POV is operated from the command line. Like POV-Ray, 
parameters are read first from an initialization file and then 
from the command line. An additional initialization file may be 
specified on the command line and will be read after the default 
ini file and before the command line parameters. ( only one 
additional '.ini' file is supported in this version. )

Sample Scenes:

     There are a number of sample scenes included under the names 
'f2pscn?.pov'. The first sample scene 'f2pscn0.pov' is just a 2-D 
representation of the specified Mandelbrot that is viewed in such 
a way that it recreates the identical image from Fractint. See 
the file 'filelist.txt' file for more information on the other 
scenes.
     These scenes '#include' the file 'frct2pov.inc' and use the 
name frct2pov for the texture name. When you convert a fractal 
with Fractint to POV-Ray, the program outputs the 'frct2pov.inc' 
file. ( unless you tell it not to ) This file '#include's the 
output file you just converted and re'#declare's the texture name 
of that texture. All you have to do to trace a test scene is to 
convert a parameter and then trace the scene. No editing is 
required. You can always edit the 'frct2pov.inc' file to specify 
a previously created texture.

Procedure:

     The first step in creating a Mandelbrot texture in POV-Ray 
is to run Fractint, create a Mandelbrot image with the desired 
color map. ( see the Fractint documentation on these subjects ) 
Then save it to a parameter file by using the 'B' key. Specify a 
parameter file to hold your Mandelbrots and use the same 
parameter file for all of your FRCT2POV conversions. ( You can 
have multiple images in a parameter file. ) You can specify your 
parameter file in the FRCT2POV '.ini' files so you do not have to 
enter it in at the command line. In the 'save colors?' section 
you can enter 'y' to save your current color map, or specify a 
file name. These are the only necessary parameters. Note that any 
color map specified on the command line will override the color 
map specified in the parameter.
      The next step is to run 'FRCT2POV.EXE' with the correct 
command line parameters. ( See the following discussion on 
command line parameters. )
	The final step is to '#include' the outputted file into 
whatever scene file you want to use it in and specify the 
'#declare'd texture name in your object's texture statement. You 
can add 'normal' and 'finish' statements to the texture 
statements. You can also trace any of the sample scenes without 
any editing.

IMPORTANT NOTE!

    FRCT2POV and POV-Ray do not check to see if they are 
overwriting an output file. If you want to save a previously 
created scene or texture you must specify different output file 
names on the FRCT2POV and POV-Ray command lines or rename the 
previously created output files.

Quick reference:

     See the file 'frct2pov.ini' for a quick reference to all 
FRCT2POV parameters.

Parameter Syntax:

	All parameters must be specified in the form 'xx=parameter'. 
On the command line they are separated by spaces. e.g.

frct2pov pf=fractals.par pn=mymandel ce=y ff=3 do=n

	In the '.INI' files, each parameter must begin on a new line 
with no leading spaces. Everything after the first space 
encountered is ignored.

IMPORTANT NOTE!

     FRCT2POV only looks for parameters it understands and 
ignores everything else. If you misspell a parameter 
specification prefix ( 'ff=' ), FRCT2POV will not notify you of 
the error but will ignore it. ( Future versions will notify you 
of these errors. ) This is why you can have all sorts of extra 
baggage in the '.ini' file without causing an error.

	Flag parameters ( on/off only ) are specified with a 'y' or 
a '1' for on and a 'n' or a '0' for off 'yes' and 'no' are also 
acceptable ( FRCT2POV only looks at the first letter ).

Parameters: ( shown with defaults )

//      input parameters

in=none     INitialization file name

   This parameter is only used from the command line. It 
specifies a second initialization file that is to be read after 
the default 'frct2pov.ini' file. This can be used to specify 
parameters for a frct2pov parameter set. ( Note that since this 
file is read after the 'frct2pov.ini' file, only parameters that 
need to be changed should be included in this file. )

//      input/output paths
     
fp=c:\fractint    Fractint Path

   specifies the path to the Fractint .par and .map files.
   
pp=c:\povray     Pov-ray Path

   specifies the path to the location of .inc file output.

//      Fractint input parameters
   
pf=f2p.par     Parameter File name   ( filename.par )

   specifies the name of the Fractint parameter file. 

pn=f2p01    Parameter Name     ( alphanumeric with no spaces )

   specifies the name of the parameter in the specified '.par' 
file that is to be converted.

cf=none     Color map File name  ( filename.map )

   specifies the name of the Fractint color map ( '.map' ) file 
that is to be converted. If this parameter is 'none' or is blank, 
the color map file name is as specified in the parameter text. If 
no color map is specified in the parameter text and is not 
specified on the command line then no color map is output.

//      POV-Ray output parameters

ti=none     Texture Include file name  ( filename.inc / .??? )

   specifies the name of the '.inc' texture file that is to be 
output. If this parameter is 'none' or is blank then the texture 
include filename is taken from the first 8 characters of the 
parameter name. Be careful to take this into consideration when 
creating output files! The parameter names 'mymandel1' and 
'mymandel2' will output the same texture file 'mymandel.inc'.

tn=none     Texture Name    ( alphanumeric with no spaces )

   specifies the name of the '#declare'd texture. If this 
parameter is 'none' or is not specified it defaults to the name 
of the converted parameter. Since Fractint allows parameters to 
begin with numbers and POV-Ray doesn't, names that begin with 
numbers are prefixed with 't_'.

cn=none     Color map Name    ( alphanumeric with no spaces )

   specifies the name of the '#declare'd color map. If this 
parameter 'none' or is not specified it defaults to the name of 
the converted color map. Since Fractint allows parameters to 
begin with numbers and POV-Ray doesn't, names that begin with 
numbers are prefixed with 'c_'. If the color map name is the same 
as the parameter name then it is prefixed with 'c_'.

//      output options

wt=yes     Write Test include file   ( yes/no )

   specifies whether the 'frct2pov.inc' file is written.

ih=yes     Include Header  ( yes/no )       

   specifies whether the header conversion information is written 
to the texture include file.

ce=yes     Color map Embed   ( yes/no )

   specifies whether the color map is written directly into the 
Mandelbrot 'pigment' instead of declared. ( prevents errors if 
multiple color maps are declared in the same '.pov' or '.inc' 
file.

ta=no     Texture include Append   ( yes/no )

   specifies whether the texture '.inc' file is appended to an 
existing file. ( allows you to make libraries of mandelbrot 
textures similar to 'textures.inc' and 'stones.inc'. ( Remember 
that all '#declare'd names must be unique. )

do=yes     Display Output   ( yes/no )

   specifies whether the outputted file is displayed after it is 
written. ( implemented as a dos 'type filename.inc | more' 
command )

ab=yes     display About information     ( yes/no )

   You can disable the output of the Fractint to POV-Ray 
'about' information. This information is only outputted to the 
screen and not to any files.

mm=4     Maximum Error start value  ( 2, 19 )

   specifies the minimum starting value for the tolerance in 
color map conversion. ( see the 'Notes on color map conversion' )

//    texture options

mi=0    Maximum number of Iterations ( integer > 0 | 0 for none )

   specifies the maximum number of iterations that are performed 
in creating the Mandelbrot texture. If this parameter is '0' or 
unspecified its value is taken from the parameter text. If it is 
not specified in the parameter text it is given a default value 
of 32640.( see the Fractint documentation for more information on 
this topic )

ff=1     Frequency Factor      ( nonzero )

   specifies a multiplication factor that is written to the POV-
Ray 'frequency' specification. This adjusts the number of times 
the color map is repeated. The default frequency that is output 
is calculated to duplicate the color distribution in the original 
Fractint image. In POV-Ray, this distribution can be changed 
whereas in Fractint it cannot. ( except in different ways such as 
with a logarithmic palette which is not possible in POV-Ray )( 
see the POV-Ray documentation for more information on this topic 
)

ph=0     PHase      (  >=0 & <=1  )

   specifies the starting point of the POV-Ray color map. 
Effectively duplicating the ability to 'cycle' the POV-Ray color 
map as can be done in Fractint ( see the Fractint documentation 
for the topic of color cycling and the POV-Ray documentation for 
the topic of 'phase' )

xw=2      X-Window size     (  real >0 )
yw=1.5    Y-Window size     (  real >0 )

   specifies the horizontal and vertical size of the output 
texture in POV-Ray space. The window specified by the X and Y-
Window sizes determine the region in which the specified 
Mandelbrot resides. The ratio of X-Window to Y-Window should be 
the same as the aspect ratio of the video mode in which the 
Mandelbrot was created in Fractint for the image to be converted 
accurately. ( for most video modes this ratio is 4/3 ) ( Note 
that the Mandelbrot texture extends infinitely beyond this window 
size. )


//      manual parameter input

Manual parameter input allows you to create a Mandelbrot texture 
include file without a Fractint parameter file. However, you must 
specify a Color map File name ( cf= ) in order to output a color 
map. In order to use manual parameter input, either WIdth or 
Magnification must be specified. 

xc= X-Center     ( real )
yc= Y-Center     ( real )

   specifies the where the center of the Mandelbrot texture is 
located in Mandelbrot space. Many books provide center/width 
information about their Mandelbrot images. ( only used with WIdth 
and MaGnification )( note that only values within the proximity 
of the actual Mandelbrot set produce interesting results )

wi= WIdth     ( real )

   specifies the width of the desired Mandelbrot in Mandelbrot 
space.

mg= MaGnification   ( real )

   specifies the magnification of the desired Mandelbrot in 
Mandelbrot space. ( this specification overrides WIdth if both 
are given )


Coming soon:

( may be included in later versions depending on user response )

provisions for POV-Ray 'filter' specs
less restrictive file name specs
multiple .ini files may be specified
ability to pass on parameter comments to the '.inc' file header

or= ORientation      image aligned with specified axes.

xtl= X-Top-Left      for manual input ( not really necessary )
ytl= Y-Top-Left
xbr= X-Bottom-Right
ybr= Y-Bottom-Right
xbl= X-Bottom-Left
ybl= Y-Bottom-Left

ca= Color map include Append      
mo= Mandelbrot Only
co= Color map Only
ci= Color map Include filename

embedable texture and transformation specs:

finish {}
normal {}
scale <>
rotate <>
translate <>
#include "colormap.inc" 
//  user specifiable comment lines in texture

Other texture types may be included in the package.

Starfield textures ( with options )
Cloud textures  ( with options )


Fractint to POV-Ray history:

v0.5      First and possibly only version.


Legal information:

     Please see the file 'f2plegal.txt' for this information.


Thanks to:

The creators of POV-Ray and Fractint for their fantastic 
programs.


Distribution information:

     Although I am distributing this program as 'free-ware', I am 
asking for a small donation as I have spent a lot of extra time 
creating sample parameters, scene files, and documentation. I 
have also incorporated many features that were originally planned 
for later versions. If you find this program useful I would 
appreciate it if you would send me five or ten dollars ( or more 
if you want ). Instead of or in addition to money, I would also 
like to see your raytraces. You could send them to me in the mail 
or upload them to the raytracing BBS 'You Can Call Me Ray' or to 
America Online.

    You can reach me on America Online as DavidG6784, on Internet 
as DavidG6784@aol.com or on 'You Can Call Me Ray' as Dave 
Grossman. See the POV-Ray documentation for information on the 
YCCMR BBS. All questions will be answered promptly and any 
comments would be appreciated.

    If you decide to send a donation and/or copies of your work  
( 3.5" 1.44M media is preferred ), my address is:

     David Grossman
     2516 Prairie Ave #1C
     Evanston, Il. 60201-2285


