emndl-0.1 released

emndl-0.1 released

video (53MB Ogg Theora) and image (2.5MB PNG) centered at
-0.5988529658460445113700557999169873572638106766467118517477 +
-0.6627873418981974683919856287279365042423603984338094007074 i

Download the source tarball: emndl-0.1.tar.gz

Or get the development version: https://gitorious.org/maximus/emndl

emndl renders the Mandelbrot Set transformed through an exponential coordinate transform. Output options include tall thin images, and zoom videos made from the image strips by inverting the coordinate transformation. emndl is written mostly in C, C++ and Bash, with an optional "autotune" program written in Haskell that attempts to find parameter points that result in interesting images. emndl_autotune currently requires a GHC built with integer-simple (not the default integer-gmp) so that the MPFR bindings work correctly.

Here is the README for emndl-0.1:

emndl 0.1 (2011-04-22)                  ______
 ____________   ___   ________ ________/  /  /
/   ---__/   '''   \/   ___   /   ___    /  /__,
\______/___/___/___/___/  /___\_________/______)


about
=====

emndl renders the Mandelbrot Set transformed through an [1] exponential
coordinate transform.

[1] http://mrob.com/pub/muency/exponentialmap.html


quick start
===========

prerequisites
-------------

This is not a complete list, but if I missed something let me know.

gcc, g++, libqd-dev      -- for building most programs
ghc/integer-simple, ...  -- for building emndl_autotune
bash, getopt (GNU), bc   -- for running
imagemagick              -- for image output
y4mscaler, mpeg2enc      -- for dvd output
ffmpeg                   -- for mkv outpout
ffmpeg2theora            -- for ogv output


compiling
---------

'make' will build everything apart from 'emndl_autotune'.

'make emndl_autotune' or 'cabal install' will build 'emndl_autotune',
but see below for further information.


installing
----------

After compiling, 'make install prefix=~/opt' will install the programs
(excepting 'emndl_autotune') and the front end script into '~/opt/bin'.
But installing is not strictly necessary, you can simply run the script
(you may have to set your PATH environment variable or provide a path to
it in your shell).


running
-------

A directory is created for output, as well as a neighbouring log file,
both in the current working directory.  So, 'cd' somewhere you don't
mind putting some files (some of which might end up large, depending on
the options).

For more information:
$ emndl.sh --help

A simple example:
$ emndl.sh --quality 7 --png --jpeg --depth 6 \
  --re -1.241733127596417466318604 --im -0.1698965841028383922879327

If you have emndl_autotune compiled:
$ emndl.sh --auto 96 --png --jpeg

If you have some days to spare:
$ emndl.sh --quality 10 --depth 21 --png --jpeg --dvd --ogv \
  --re -0.5988529658460445113700557999169873572638106766467118517477 \
  --im -0.6627873418981974683919856287279365042423603984338094007074


emndl programs
==============

emndl consists of a number of programs, plus a more user-friendly script
to drive the process from start to finish (described above).


emndl_autotune
--------------

emndl_autotune attempts to find interesting points in the Mandelbrot Set
that might look nice.  It takes one optional argument, being a positive
integer specifying how many bits of precision to use (the default is 128
bits).  Progress (including Unicode block graphics) is printed on stderr
with the final result on stdout for use by emndl.sh (or other programs).

Use it like 'emndl_autotune +RTS -N -RTS 80'.

emndl_autotune is implemented in Haskell, so far requiring a GHC built
with integer-simple (see the [2] hmpfr documentation on Hackage for the
rationale behind this awkwardness).  There is a .cabal file which can be
used by the cabal-install tool to automatically install the required
dependencies and compile emndl_autotune itself, run: 'cabal install'.
If you have the dependencies already, run: 'make emndl_autotune'.

[2] http://hackage.haskell.org/package/hmpfr


emndl_colourize
---------------

emndl_colourize takes a raw 'float' data file containing the relative
distance estimate for each pixel (the distance estimate divided by the
pixel spacing at that point).  It outputs a raw 'rgb' data file with the
colour for each pixel.

Use it like 'emndl_colourize in.f out.raw'.


emndl_downscale
---------------

emndl_downscale reduces the size of a raw 'float' image by a factor of 2
using a scaled geometric mean to preserve relative distance estimates.
It takes one argument, the width of the input image (which must be even,
and so must be its height).

Use it like 'emndl_downscale 128 < in.f > out.f'.


emndl_equalize
--------------

emndl_equalize is currently unused and undocumented.  FIXME


emndl_finalize
--------------

emndl_finalize extracts the raw 'float' image data from an iteration
file.

Use it like 'emndl_finalize in.emndl out.f'.


emndl_initialize
----------------

emndl_initialize creates a blank iteration file (named by the first
argument), sized by the second (width) and third (height) arguments.
The fourth argument controls the outer radius.  The coordinates of the
center point are passed through standard input in raw 'quad-double'
format.

Use it like 'emndl_initialize 0.emndl 128 1280 256 < coords.qd'.


emndl_iterate
-------------

emndl_iterate takes an iteration file (second argument) and iterates
the points in it, with output to a new iteration file (third argument).
The first argument controls the maximum number of iterations.  This
allows you to increase the number of iterations without having to start
again from scratch.  Exit code is 0 (more iterations needed), 3 (number
of iterations might be ok), or 1 (an error occurred).

Use it like 'emndl_iterate 10000 in.emndl out.emndl'.


emndl_parse
-----------

emndl_parse takes two arguments specifying the real and imaginary parts
of a complex number.  These are output on stdout in raw 'quad-double'
format.

Use it like 'emndl_parse -1.75 0.001 > coords.qd'.


emndl_ppmtoy4m
--------------

emndl_ppmtoy4m takes a PPM stream on stdin and outputs a Y4M stream on
stdout.  It requires two arguments, being the width and height of the
PPM stream.  Error checking is minimal, but it's significantly faster
than 'ppmtoy4m' from 'mjpegtools'.

Use it like 'emndl_ppmtoy4m 640 480 < in.ppm > out.y4m'.


emndl_pretty
------------

emndl_pretty takes raw 'quad-double' on stdin and outputs human-readable
numbers.

Use it like 'emndl_pretty < coords.qd'.


emndl_randomize
---------------

emndl_randomize is currently unused and undocumented.  FIXME


emndl_unwarp
------------

emndl_unwarp takes a series of downscaled and colourized exponential
strip images, and reverses the coordinate transform to turn them into
zooming videos.  It takes a file name stem as first argument, which has
'.00.ppm' appended to get the highest resolution strip image file name,
its dimensions (width must be a power of two, height must be a multiple
of width) determine the number of images that will be loaded.  The next
two arguments determine the size of the output PPM stream, and the final
fourth argument is the speed in pixels per frame.  PPM stream data is
sent to stdout - you will want to redirect it or (better, as it is
likely to be quite large) pipe it to an encoder.

Use it like 'emndl_unwarp emndl 320 200 3.21 > out.ppm'.


author
======

Claude Heiland-Allen
mailto:claudiusmaximus@goto10.org
http://claudiusmaximus.goto10.org


bureaucracy
===========

emndl -- exponentially transformed Mandelbrot Set renderer
Copyright (C) 2011  Claude Heiland-Allen <claudiusmaximus@goto10.org>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

One known bug in this release: if emndl_autotune is installed in a different prefix to emndl.sh, the script won't find it and the --auto flag will error out.