perturbation based calculations
[maximus:emndl.git] / README
1 emndl git (2011-06-03)                  ______
2  ____________   ___   ________ ________/  /  /
3 /   ---__/   '''   \/   ___   /   ___    /  /__,
4 \______/___/___/___/___/  /___\_________/______)
5
6
7 about
8 =====
9
10 emndl renders the Mandelbrot Set transformed through an [1] exponential
11 coordinate transform.
12
13 [1] http://mrob.com/pub/muency/exponentialmap.html
14
15
16 quick start
17 ===========
18
19 prerequisites
20 -------------
21
22 This is not a complete list, but if I missed something let me know.
23
24 gcc, g++, libqd-dev      -- for building most programs
25 ghc/integer-simple, ...  -- for building emndl_autotune
26 bash, getopt (GNU), bc   -- for running
27 imagemagick              -- for image output
28 y4mscaler, mpeg2enc      -- for dvd output
29 ffmpeg                   -- for mkv outpout
30 ffmpeg2theora            -- for ogv output
31 ecasound, puredata       -- for video soundtracks
32
33
34 compiling
35 ---------
36
37 'make' will build everything apart from 'emndl_autotune'.
38
39 'make emndl_autotune' or 'cabal install' will build 'emndl_autotune',
40 but see below for further information.
41
42
43 installing
44 ----------
45
46 After compiling, 'make install prefix=~/opt' will install the programs
47 (excepting 'emndl_autotune') and the front end script into '~/opt/bin',
48 with the puredata sonification patches in '~/opt/share/emndl'.  Make
49 sure to install 'emndl_autotune' in the same prefix as the rest of emndl
50 so that the script can find it, or create a symlink to where 'cabal'
51 installed it.
52
53
54 running
55 -------
56
57 A directory is created for output, as well as a neighbouring log file,
58 both in the current working directory.  So, 'cd' somewhere you don't
59 mind putting these files, which may be relatively large.
60
61 For more information:
62 $ emndl.sh --help
63
64 A simple example:
65 $ emndl.sh --quality 7 --png --jpeg --depth 6 \
66   --re -1.241733127596417466318604 --im -0.1698965841028383922879327
67
68 If you have emndl_autotune compiled:
69 $ emndl.sh --auto 96 --png --jpeg
70
71 If you have some days to spare:
72 $ emndl.sh --quality 10 --depth 21 --png --jpeg --dvd --ogv \
73   --re -0.5988529658460445113700557999169873572638106766467118517477 \
74   --im -0.6627873418981974683919856287279365042423603984338094007074
75
76
77 emndl programs
78 ==============
79
80 emndl consists of a number of programs, plus a more user-friendly script
81 to drive the process from start to finish (described above).
82
83
84 emndl_autotune
85 --------------
86
87 emndl_autotune attempts to find interesting points in the Mandelbrot Set
88 that might look nice.  It takes one optional argument, being a positive
89 integer specifying how many bits of precision to use (the default is 128
90 bits).  Progress (including Unicode block graphics) is printed on stderr
91 with the final result on stdout for use by emndl.sh (or other programs).
92
93 Use it like 'emndl_autotune +RTS -N -RTS 80'.
94
95 emndl_autotune is implemented in Haskell, so far requiring a GHC built
96 with integer-simple (see the [2] hmpfr documentation on Hackage for the
97 rationale behind this awkwardness).  There is a .cabal file which can be
98 used by the cabal-install tool to automatically install the required
99 dependencies and compile emndl_autotune itself, run: 'cabal install'.
100 If you have the dependencies already, run: 'make emndl_autotune'.
101
102 [2] http://hackage.haskell.org/package/hmpfr
103
104
105 emndl_calculate
106 ---------------
107
108 emndl_calculate does the fractal iteration calculations.  Its arguments
109 are output raw data file name, iteration state raw data file name (for
110 future resumation of interrupted calculations), image width, outer
111 radius, and finally number of threads.  The coordinates of the center
112 point are passed through standard input in raw 'quad-double' format.
113
114 Use it like 'emndl_calculate out.emndl state.emndl 256 1024 2 < coords.qd'.
115
116
117 emndl_colourize
118 ---------------
119
120 emndl_colourize takes a raw 'float' data file containing the relative
121 distance estimate for each pixel (the distance estimate divided by the
122 pixel spacing at that point).  It outputs a raw 'rgb' data file with the
123 colour for each pixel.
124
125 Use it like 'emndl_colourize in.f out.raw'.
126
127
128 emndl_downscale
129 ---------------
130
131 emndl_downscale reduces the size of a raw 'float' image by a factor of 2
132 using a scaled geometric mean to preserve relative distance estimates.
133 It takes one argument, the width of the input image (which must be even,
134 and so must be its height).
135
136 Use it like 'emndl_downscale 128 < in.f > out.f'.
137
138
139 emndl_equalize
140 --------------
141
142 emndl_equalize is currently unused and undocumented.  FIXME
143
144
145 emndl_finalize
146 --------------
147
148 emndl_finalize extracts the raw 'float' image data from an iteration
149 file.
150
151 Use it like 'emndl_finalize in.emndl out.f'.
152
153
154 emndl_parse
155 -----------
156
157 emndl_parse takes two arguments specifying the real and imaginary parts
158 of a complex number.  These are output on stdout in raw 'quad-double'
159 format.
160
161 Use it like 'emndl_parse -1.75 0.001 > coords.qd'.
162
163
164 emndl_ppmtoy4m
165 --------------
166
167 emndl_ppmtoy4m takes a PPM stream on stdin and outputs a Y4M stream on
168 stdout.  It requires two arguments, being the width and height of the
169 PPM stream.  Error checking is minimal, but it's significantly faster
170 than 'ppmtoy4m' from 'mjpegtools'.
171
172 Use it like 'emndl_ppmtoy4m 640 480 < in.ppm > out.y4m'.
173
174
175 emndl_pretty
176 ------------
177
178 emndl_pretty takes raw 'quad-double' on stdin and outputs human-readable
179 numbers.
180
181 Use it like 'emndl_pretty < coords.qd'.
182
183
184 emndl_randomize
185 ---------------
186
187 emndl_randomize is currently unused and undocumented.  FIXME
188
189
190 emndl_unwarp
191 ------------
192
193 emndl_unwarp takes a series of downscaled and colourized exponential
194 strip images, and reverses the coordinate transform to turn them into
195 zooming videos.  It takes a file name stem as first argument, which has
196 '.00.ppm' appended to get the highest resolution strip image file name,
197 its dimensions (width must be a power of two, height must be a multiple
198 of width) determine the number of images that will be loaded.  The next
199 two arguments determine the size of the output PPM stream, and the final
200 fourth argument is the speed in pixels per frame.  PPM stream data is
201 sent to stdout - you will want to redirect it or (better, as it is
202 likely to be quite large) pipe it to an encoder, likewise raw stereo
203 32bit float audio data is sent to stderr.
204
205 Use it like 'emndl_unwarp emndl 320 200 3.21 > out.ppm 2> out.raw'.
206
207
208 author
209 ======
210
211 Claude Heiland-Allen
212 claude@mathr.co.uk
213 http://mathr.co.uk
214
215
216 bureaucracy
217 ===========
218
219 emndl -- exponentially transformed Mandelbrot Set renderer
220 Copyright (C) 2011  Claude Heiland-Allen <claude@mathr.co.uk>
221
222 This program is free software: you can redistribute it and/or modify
223 it under the terms of the GNU General Public License as published by
224 the Free Software Foundation, either version 3 of the License, or
225 (at your option) any later version.
226
227 This program is distributed in the hope that it will be useful,
228 but WITHOUT ANY WARRANTY; without even the implied warranty of
229 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
230 GNU General Public License for more details.
231
232 You should have received a copy of the GNU General Public License
233 along with this program.  If not, see <http://www.gnu.org/licenses/>.