
                              MANDELBULBER 2.13-2

1. What is Mandelbulber
-----------------------

In summary, Mandelbulber generates three-dimensional fractals.
Explore  trigonometric, hyper-complex, Mandelbox, IFS, Kleinian  and many other
3D fractals.  Render with a great palette  of customizable materials  to create
stunning images and videos. The possibilities are literally   i n f i n i t e !

2. Project Members and Links
----------------------------

PROJECT LEADER:  Krzysztof Marczak
PROJECT MEMBERS: Sebastian Jennen, Graeme McLaren, Bernardo Martelli,
                 Robert Pancoast, knighty, makemeunsee, Marius Schilder,
                 Ryan Hitchman, Jeff Epler, Martin Reinecke, Quazgaa

CONTACT:         buddhi1980@gmail.com
DOWNLOAD:        https://sourceforge.net/projects/mandelbulber/
DEVELOPMENT:     https://github.com/buddhi1980/mandelbulber2/
COMMUNITY:       http://www.fractalforums.com/mandelbulber/
                 https://www.facebook.com/groups/mandelbulber/
FANSITE:         http://www.mandelbulber.com
                 http://www.mandelbulber.org

LICENCE:         GNU GPL v3.0

3. REQUIREMENTS
---------------

- Linux OS with installed Qt 5 libraries (version >5.7)
- very fast CPU (recommended 3GHz, 4 cores)
- 2GB RAM

4. COMPILING
------------

packages needed to RUN
    libqt5gui5 libpng16-16, libgsl2 liblzo2-2 libgomp1 libqt5multimedia5
    libqt5multimedia5-plugins libsndfile1 liblzo2-2

packages needed to COMPILE
    build-essential qt5-default libpng-dev qttools5-dev qttools5-dev-tools
    libgsl-dev libgomp1 qtmultimedia5-dev libqt5multimedia5-plugins
    libsndfile1-dev liblzo2-dev

Installing packages on Ubuntu, Debian stable (jessie) or Mint: 
sudo apt-get install build-essential libqt5gui5 qt5-default libpng16-16 \
    libpng-dev qttools5-dev qttools5-dev-tools libgomp1 libgsl-dev \
    libsndfile1-dev qtmultimedia5-dev libqt5multimedia5-plugins liblzo2-2 \
    liblzo2-dev

Compiling from source:
cd makefiles
qmake mandelbulber.pro
make all
cd ..

4.1. Alternative compilation with cmake

note: compilation with cmake is only beta and not feature complete

In order to compile OpenEXR with cmake the ECM should be present
to install on Debian / Ubuntu:
sudo apt-get install extra-cmake-modules

4.2 Optional packages

TIFF:     install libtiff5-dev to have TIFF format support
EXR:      install libopenexr-dev to have EXR format support
QGAMEPAD: for gamepad support qt is required in version 5.7 and above

4.2.2 OpenCL

Mandelbulber can utilize OpenCL to accelerate rendering.
To compile Mandelbulber with OpenCL support, the headers need to be present.
These can be obtained with the package: opencl-headers
To use an OpenCL device you need to install a current driver for the CPU/GPU.

Compiling from source:
cd makefiles
qmake mandelbulber-opencl.pro
make all
cd ..

For more information, please study the handbook (see chapter Usage).

5. INSTALLATION
---------------

Run the install script:
./install
(This will also run the compilation)

6. TESTED ON
------------

- Debian Stretch x64
- Ubuntu 17

- gcc 7.3
- clang 4.0.1-10
- msvc17

- Qt 5.9.2

7. USAGE
--------

The main documentation is the PDF file  Mandelbulber_Manual.pdf,  which you can
find in this very folder.
Also you can open it from Mandelbulber under: [Menu > Help > User Manual]
A lot of useful information you can find  in the tooltips.  Just hover with the
mouse pointer over the edit fields.
More useful material can be found in the wiki documentation for old
Mandelbulber (v1) here: http://wiki.mandelbulber.com/index.php?title=Main_Page

8. COMMAND LINE INTERFACE
-------------------------

The program can be used "headless" from the console. This way the program can
be integrated in scripts or toolchains and even be run without a x-server
completely.

Usage: ./mandelbulber2 [options] settings_file

Options:
  -h, --help             Displays this help.
  -v, --version          Displays version information.
  -n, --nogui            Starts the program without a GUI.
  -o, --output <N>       Saves rendered image(s) to this file / folder.
  --logfilepath <N>      Specify custom system log filepath (default is:
                         ~/.mandelbulber_log.txt).
  -K, --keyframe         Renders keyframe animation.
  -F, --flight           Renders flight animation.
  -X, --never-delete     Never delete data, instead Exit CLI application.
  -s, --start <N>        Starts rendering from frame number <N>.
  -e, --end <N>          Stops rendering on frame number <N>.
  -L, --list             Lists all possible parameters '<KEY>' with
                         corresponding default value '<VALUE>'.
  -f, --format <FORMAT>  Image output format:
                          jpg - JPEG format (default)
                          png - PNG format
                          png16 - 16-bit PNG format
                          png16alpha - 16-bit PNG with alpha channel format
                          exr - EXR format
                          tiff - TIFF format
  -r, --res <WxH>        Overrides image resolution. Specify as width and
                         height separated by 'x'
  --fpk <N>              Overrides frames per key parameter.
  -S, --server           Sets application as a server listening for clients.
  -H, --host <N.N.N.N>   Sets application as a client connected to server of
                         given host address (Host can be of type IPv4, IPv6 and
                         Domain name address).
  -p, --port <N>         Sets network port number for netrender (default 5555).
  -C, --no-cli-color     Starts program without ANSI colors, when execution on
                         CLI.
  -q, --queue            Renders all images from common queue.
  -t, --test             Runs testcases on the mandelbulber instance
  -b, --benchmark        Runs benchmarks on the mandelbulber instance, specify
                         optional parameter difficulty (1 -> very easy, > 20 ->
                         very hard, 10 -> default). When [output] option is set
                         to a folder, the example-test images will be stored
                         there.
  -T, --touch            Resaves a settings file (can be used to update a
                         settings file)
  -V, --voxel <FORMAT>   Renders the voxel volume. Output formats are:
                          slice - stack of PNG images into one folder (default)
                          ply - Polygon File Format (single 3d file)

  -O, --override <...>   <KEY=VALUE> overrides item '<KEY>' from settings file
                         with new value '<VALUE>'.
                         Specify multiple KEY=VALUE pairs by separating with a
                         '#': <KEY1=VALUE1#KEY2=VALUE2>. Quote whole expression
                         to avoid whitespace parsing issues
                         Override fractal parameter in the form
                         'fractal<N>_KEY=VALUE' with <N> being index of fractal
  --stats                Shows statistics while rendering in CLI mode.
  --help-input           Shows help about input.
  --help-examples        Shows example commands.
  --help-opencl          Shows commands regarding OpenCL.

Arguments:
  settings_file          file with fractal settings (program also tries
                         to find file in ./mandelbulber/settings directory)
                         When settings_file is put as a command line argument
                         then program will start in noGUI mode<settings_file>
                         can also be specified as a list, see all options with
                         --help-input
