DataFile Statement Syntax
The Fractal Science Kit fractal generator dataFile statement is 1 of the statements used in the properties section of the program instructions to define the program's Properties.
The dataFile statement defines a file format and includes controls on the properties page to select a dataset within a file. The selected dataset is loaded into a data table; a 2-dimensional array allowing access by the program instructions. The file can be composed of a number of datasets as illustrated in the following description:
<DataSetName> {
<Header>
<DataRow>
<DataRow>
...
}
<DataSetName> {
<Header>
<DataRow>
<DataRow>
...
}
...
Each dataset has a name, an optional header, and a set of data rows. The header is a set of comma separated keyword assignments. The data rows have a fixed number of entries separated by 1 or more spaces and can be integer, floating point or complex numbers. Leading and trailing spaces are ignored. Complex numbers must be given in the form a+bi or a-bi where a and b are floats, and cannot contain spaces. The semi-colon (;) character is used to add comments to your code. All characters to the right of a semi-colon character are ignored. Do not use { or } characters within comments as this will confuse the compiler.
The specifics of the file format are given by the dataFile statement.
The syntax of the dataFile statement is:
dataFile <Name> {
path = <Quoted string>
type = <Quoted string>
suffix = <Quoted string>
columns = <Integer>
header = <Boolean>
enabled = <Boolean expression>
visible = <Boolean expression>
}
The <Name> must be a valid identifier.
The path field is a quoted string that gives the path of the default file. The path should be given as a fully qualified path to the file, or a path relative to the My Files folder in the Fractal Science Kit Home folder. path is a required field.
The type field is a quoted string that gives the type of the data within the file. The type is used in error messages and the Open Dialog to identify the file type. type is a required field.
The suffix field is a quoted string of 1 or more characters that gives the file suffix. suffix is a required field.
The columns field gives the number of entries in each row of data. If columns is 0, or omitted, the columns is calculated from the 1st row of data.
The header field is True or False and indicates whether the data is preceded by a header row. If header is False (or omitted), the file is assumed to have no header row. If header is True, the 1st row in the dataset is a set of keyword assignments (Keyword=Value) separated by commas. Keyword must be a valid identifier and Value must resolve to a number.
The enabled field is used to disable the dataFile controls based on the value of other options.
The visible field is used to hide the dataFile controls based on the value of other options.
The data in the dataset is loaded into a 2-dimensional array named <Name>[,]. If a header row is included, a set of constants are defined, named <Name>.<Keyword>; one for each of the keyword assignments found in the header.
The data values and the keyword values must resolve to a number. However, you are allowed to use defined constants (e.g., enum values). For example, you could use True or ShapeTypes.Circle in the dataset and the associated constant will be loaded into the dataset properly.
A file referenced by a dataset must be distributed with any program that uses it. It is recommended that you store these files in the folder My Files located in the Fractal Science Kit Home folder. You can organize your dataset files by placing them in a folder that you create under the My Files folder (e.g., My Data Files). Files located in the hierarchy under My Files will be referenced using a relative path to the file rather than a fully qualified path which is highly specific to your machine. See Sharing Programs for details.
IFS Files
The dataFile statement can be used to load IFS files created for Fractint. There are many of these files available on the Internet.
These files have the following syntax:
<Name> {
<A> <B> <C> <D> <E> <F> <Probability>
<A> <B> <C> <D> <E> <F> <Probability>
...
}
<Name> {
<A> <B> <C> <D> <E> <F> <Probability>
<A> <B> <C> <D> <E> <F> <Probability>
...
}
...
Each file contains 1 or more named IFS fractals. Each fractal has a <Name> and a set of affine transformations each assigned a probability or weight. The affine transformation coefficients are given by <A>, <B>, <C>, <D>, <E>, and <F>. The probability assigned to the transformation is <Probability>. The sum of the <Probability> values assigned to each transformation within a dataset should be 1.
The Affine Transformation is given by:
xNew = <A>*xOld + <B>*yOld + <E>
yNew = <C>*xOld + <D>*yOld + <F>
Or, if you prefer:
z = Complex( \
<A>*z.x + <B>*z.y + <E>, \
<C>*z.x + <D>*z.y + <F> \
)
Or, using the built-in Affine object:
a = Affine(<A>,<B>,<C>,<D>,<E>,<F>)
z = Affine.TransformPoint(a,
z)
Example:
fern {
0.85 0.04 -0.04 0.85 0.0 1.6 0.85
0.2 -0.26 0.23 0.22 0.0 1.6
0.07
-0.15 0.28 0.26 0.24 0.0 0.44 0.07
0.0 0.0 0.0 0.16 0.0
0.0 0.01
}
In this example the IFS fractal is named fern and it has 4 affine transformations. Each transformation is assigned a probability value; the last number in each row.
Here is a dataFile statement to load files of this type:
properties:
dataFile DataTable {
path = "Examples.ifs"
type = "IFS"
suffix = "ifs"
columns = 7
}
The file Examples.ifs is located in the My Files folder and is loaded by default. The type of the file is given as IFS and the suffix as ifs. Each row is declared to have 7 entries. There is no header row.
As a result of this statement, a data file control is included on the properties page that allows users to select an IFS entry from the default file or another file of their choice. The resulting IFS data is loaded into a 2-dimensional array named DataTable[,] for use by the program.
Here is the entire program:
global:
count = Array.Dim1(DataTable[,])
const Complex indexLUT[10000]
const Affine s[count]
Complex w[count]
'
' Initialize Affine array s[] and weight array w[].
'
for (i = 0, i < count, i += 1) {
offset = Array.Offset(DataTable[,], i, 0)
Array.Copy(DataTable[,], offset, s[], i, 6)
w[i] = DataTable[i, 6]
}
Math.GenerateIndexLookupTable(w[], count, indexLUT[])
iterate:
attractorIndex = Math.GenerateIndex(indexLUT[])
z = Affine.TransformPoint(s[attractorIndex], z)
properties:
dataFile DataTable {
path = "Examples.ifs"
type = "IFS"
suffix = "ifs"
columns = 7
}
A dataFile is defined to load the data into an array named DataTable[,]. In the global section of the program, we use the DataTable[,] array to initialize an Affine array named s[] and an array of weights w[]. The variable count is set to the number of transformations and we generate an index lookup table based on the assigned weights to speed up the index generation in the iterate section. The iterate section generates a random index and returns the transformed point.
The example above would generate the following controls on the properties page for the program:
The file Examples.ifs is located in the My Files folder and begins with:
IFS01 { ; Ross Hilbert
-0.169225 -0.229266 -0.787657 -0.258816 0.035434 0.445461
0.162537
-0.007031 0.050585 -0.052328 -0.680332 0.558257
0.963715 0.011883
-0.077803 -0.647023 0.246688 0.461137 -0.260859
0.507350 0.147031
0.441425 -0.824308 -0.141759 0.266943 0.097420
0.915267 0.011883
0.766743 0.338774 0.247275 -0.069142 -0.403497
-0.192043 0.162537
0.048832 0.563893 0.020075 0.383974 -1.113731
0.001607 0.011883
-0.174737 -0.075845 -0.190723 -0.790907 -0.308948 -0.479586
0.147031
-0.097946 0.180974 0.453164 -0.847343 -0.841354 -0.373266
0.011883
-0.597518 -0.109508 0.540381 0.327958 0.368063
-0.253417 0.162537
-0.041802 -0.614477 0.032253 0.296358 0.555474
-0.965322 0.011883
0.252540 0.722868 -0.055965 0.329770 0.569808
-0.027764 0.147031
-0.343479 0.643333 -0.311405 0.580400 0.743935
-0.542001 0.011883
}
IFS02 { ; Ross Hilbert
-0.035625 0.004225 -0.157418 0.442870 0.132149
-0.296118 0.011729
0.371084 -0.736755 0.156775 0.018637 0.418243
-0.437218 0.095015
0.624183 0.275611 0.595273 -0.188856 -0.884903
-0.389651 0.218828
0.041769 -0.010576 0.329078 -0.284442 -0.688446
0.583941 0.007761
0.154140 -0.385649 0.047857 -0.217776 0.190371
0.262504 0.011729
-0.321313 0.352238 0.242981 -0.647367 0.169521
0.580819 0.095015
-0.827613 0.025749 0.242922 0.333114 0.779899
-0.571524 0.218828
-0.305874 0.251622 -0.128366 0.133062 -0.161485 -0.888182
0.007761
-0.118515 0.381425 0.109561 -0.225094 -0.322520
0.033615 0.011729
-0.049771 0.384517 -0.399756 0.628730 -0.587764 -0.143600
0.095015
0.203430 -0.301360 -0.838195 -0.144258 0.105004
0.961174 0.218828
0.264105 -0.241046 -0.200711 0.151380 0.849931
0.304241 0.007761
}
...