Getting started

Installing

Fractalshades is published on the Python Package Index (PyPI). To install the last published version and its dependencies, you should run: [1]

pip install pip setuptools --upgrade
pip install fractalshades

(The first line ensures your installation tools stay up-to-date)

To install directly the latest version from Github master:

pip install git+https://github.com/GBillotey/Fractalshades.git

This package relies on the following dependencies:

They should install automatically with pip.

A special case is gmpy2 as it needs the most recent versions of GMP, MPFR and MPC multi-precision arithmetic libraries. Detailed instructions are given below, depending on the OS used.

Installing GMP / MPFR / MPC: Windows users

Under Windows 64 bits, everything should work out of the box:

  • recent wheels of gmpy2 (rev >= 2.1.2) already ship the latest GMP / MPFR / MPC dlls.

  • fractalshades pre-built binaries wheels used by the pip tool (and available for the main python versions) contains a Cython extension built using MSVC and linked to these GMP/MPFR/MPC dlls.

Installing GMP / MPFR / MPC: Unix / Linux users

Under Unix / Linux, if your distribution does not include recent versions of GMP, MPFR and MPC you will have to install them manually:

sudo apt-get install libgmp-dev
sudo apt-get install libmpfr-dev
sudo apt-get install libmpfi-dev
sudo apt-get install libmpc-dev

Installing GMP / MPFR / MPC: Mac users

These instructions have been tested under Mac M1.

Once again, you will need recent versions of GMP, MPFR and MPC otherwise you will get an error complaining about missing gmp header files. This can be resolved by installing a few packages and adding the appropriate flags while installing them. Install using homebrew:

brew install gmp
brew install mpfr
brew install libmpc
brew install pkg-config

List all packages and check if they are installed correctly.

pkg-config —list-all

For each package installed, get the location:

pkg-config --cflags gmp
pkg-config —libs gmp

Do this for all packages and install using pip

env "CFLAGS= <ADD ALL FLAGS> “ pip install fractalshades

Examples:

env "CFLAGS=-I/opt/homebrew/Cellar/gmp/6.2.1_1/include -L/opt/homebrew/Cellar/gmp/6.2.1_1/lib
-lgmp -I/opt/homebrew/Cellar/mpfr/4.1.0-p13/include -L/opt/homebrew/Cellar/mpfr/4.1.0-p13/lib
-lmpfr -lgmp -I/opt/homebrew/Cellar/libmpc/1.3.1/include" pip install fractalshades

A 5-minutes guide to fractalshades

The best way to start is probably to have a look at the Gallery section. Download one of the examples from the GUI examples section (selection of links below), run it in an empty directory: good exploration !

python3 run_interactive.py

For advanced used you can also rely on batch mode, Fractalshades exposes 3 kinds of component each implementing a different functionality:

Tip: A click on “show source” in the GUI will generate a python script ready-to-run in batch mode.

Graphical user interface

As explained above, the GUI is launched by running a python scipt from an interpretor. You should get something similar to :

_images/GUI_overview.png

The following main components can be seen:

  • in yellow, the main toolbar. The tools section provides:

    • A png tag reader, which can open an image created by fractalshades and output the list of parameters used for the computation (each image file produced by the programm is tagged with useful information like the location of the image, the program version, the calculation parameters used)

    • A png to colormap converter : load an image, draw a line on it : the colors will be used to create a colormap

    • A tool to select a colormap from the templates available (see Colormaps: available templates ) with combo-box and a preview of the colormap selected.

  • in blue, the parameters window. The used parameters and their types are parsed from the python script, and a tailored editor is proposed based on the type (see fractalshades.gui.Fractal_GUI for details). The editor might be a simple text box, or for more complex objects a full pop-up or a dockable window.

    • Among these, 4 parameters which define the zoom will respond to the mouse events on the fractal image panel (x, y, xy_ratio, and the arbitrary precision in digits dps).

    • To view the scipt source code, click on “Show source”. This source code can be run directly in a python interpreter, it will calculate the same image in batch mode.

    • To view the current value of the parameters, click on “Show params”

    • To actually run the script, click on “run”.

    • On-going calculation can be also interrupted, this will become effective just after the current tile calculation is completed (allowing to display an intermediate result).

  • in red, the fractal image panel. It displays the last computed image (it is empty if no calculation has been run). It provides 3 kinds of user-interaction:

    • wheeling zooms / unzooms the static image

    • with a right-click you define a new zoom area that can be used for next calculation. (Double right clicking reset the zoom)

    • with a left-click, you can run some of the methods of the fractalshades.Fractal object (these are its methods tagged with a special decorator: @fractalshades.utils.interactive_options), the coordinates of the click will be passed. Current implementation of the deep zoom mandelbrot gives access to the coordinates, the cycle order, and a Newton search for nucleus.

  • in green, the info panel. It gives the current mouse position and zoom level (from the image panel).

  • in orange, the status bar. It provides information on the calculation progress (full precision orbit, series approximation, current tile, …)

Finding areas of interest

For the standard precision fractals, it is usually sufficient to navigate manually inside the fractal through the GUI:

  • left click, draw the new zoom rectangle, left click again to validate ; the coordinates in the parameters panel are updated automatically

  • press “run”. A new calculation will be run taking into account the updated parameters

For arbitrary precision exploration however, zooming repetively inside a deep minibrot can be tedious. For deep zooms in the Burning ship, it is even not always obvious to find a miniship. This is where the Newton search for the center of hyperbolic components comes handy :

  • right click on the image close the the estimated location of a target minibrot, select “Newton search”

  • Some parameters are needed to estimate the period of the influencing minibrot:

    • maximum iteration (this should be more than the period, you can pick 100000 as a starting point as calculation is fast)

    • radius in pixel (this is the size of a small ball - or ellipse in the case of the Burning ship) that will be iterated until it contains the critical point : this is the computed period. Usually, just keep the proposed value of 3 pixels.

  • a result table should pop-up. If all went well (the period has been estimated, a Newton calculation has been run and converged successfully) you should be provided the following new information:

    • calculation dps the precision used for the successful Newton search. Copy paste it in the parameter panel to use it for the next zoom

    • x_nucleus, y_nucleus the coordinates of the hyperbolic component center. Copy-paste also as the requested new center for the next image

    • nucleus_size, julia_size these are the estimation of the size of the hyperbolic component, and of its area of influence (embedded Julia). Usually the next zoom should be close to the embedded Julia parameter, copy-paste it as the new dx

  • for the non-holomorphic fractals (Burning-ship) you will get also 4 coordinate of the local skew transformation (skew_00, skew_01, skew_10, skew_11). Copy-paste in the parameter panel and set has_skew to True. (Each time the skew is modified the calculation need to be re-run to validate the choice, otherwise the screen coordinates will not match the view anymore). Not that this option is usuful also at low zoom level, some areas of the Burning ship are very skewed at a standard zoom level

  • press “run”

For those interested in the implementation details we shall recommend the paper quoted in fractalshades.models.Perturbation_burning_ship.

Unskewing streched areas

For the Burning ship and other non-holomorphic fractals, some areas are very skewed and it is desirable to apply an “unskewing matrice” (a linear 2x2 transformation that keep the areas constant but changes the angles). These 4 coefficients (skew_00, skew_01, skew_10, skew_11) can be provided in the GUI - for the arbitrary precision explorer, of passed to the relevant zooming method in batch mode, e.g., fractalshades.models.Perturbation_burning_ship.zoom

Rather than a tedious manual iteration to define the 4 coefficients of this matrix, fractalshades provides 2 way to computationaly define a local skew transformation:

  • When computing the center of an hyperbolic component (right-click, “Newton search”, this matrice is one of the calculation results - if this center is found

  • For areas where the “Newton search” fails, a skew matrice can still be defined from an escaping pixel: right click on the screen close to the area of interest and select “quick skew estimate”. A window will pop-up with the 4 coordinates of the skew transformation (algorithm based on the iteration of an infinitesimal ellipse until escape).

Once a new local skew is entered, remember to set has_skew to True and re-run the calculation. The navigation can continue from here, the unskewing transformation will be applied to both image rendering and mouse events.