# Fraktaler 3

fraktaler.mathr.co.uk

A fast cross-platform deep zoomer for hybrid escape time fractals.

Developed on Debian, also supports Android and Windows, as well as running in the web browser.

# 1 Theory

See deep zoom.

# 2 Wisdom

Fraktaler 3 uses “wisdom” to know which backends are best to use for calculating fractals in different circumstances.

# 2.1 Graphical Configuration

v2 and later support wisdom configuration in the graphical user interface, for earlier versions you need to run obscure terminal commands and edit text files.

When Fraktaler 3 is run for the first time, it has defaults just for the CPU backend. The currently used backends are highlighted in yellow.

screenshot

To populate it with the currently available hardware, check the enumerate unlock checkbox and click the enumerate button. The unlock checkbox prevents accidental activation of this feature.

screenshot

The hardware devices are then listed in individual columns:

screenshot

This hardware has two CPU-based backends, one using Portable Compute Library (PoCL for OpenCL), and one using the regular builtin CPU support. As these both use the same underlying hardware, put them both in the same group (top line cpu0):

screenshot

Now only the fastest of the cpu0 backends is used:

screenshot

The backends can also be renamed. This doesn’t affect anything other than what is displayed, unlike the group names in the line above.

screenshot

To benchmark the currently enabled hardware (you can disable devices or per-type backends with the checkboxes), check the benchmark unlock checkbox and click the benchmark button.

screenshot

This takes about 2 minutes per hardware device.

screenshot

Once benchmarking has finished, the table is populated with speeds. Speeds are displayed logarithmically: an increase of 1 unit in displayed value corresponds to a factor of 2 increase in pixels per second.

screenshot

On this hardware the CPU is about 5x slower than the GPU, so it can be more ergonomic to disable the CPU backends completely:

screenshot

Finally, save the wisdom configuration. If the file is named wisdom.toml and is saved in the default directory, it will be loaded automatically on startup.

# 2.2 Command Line Configuration

Before v2, and on systems without GUI, the wisdom can be configured from the command line.

fraktaler-3 -W

will enumerate the hardware, overwriting the default wisdom file unless -w alternate-wisdom.toml is specified.

Then edit the saved wisdom file in a text editor to do the hardware grouping, backend naming, and dis/enabling tasks.

To benchmark, run

fraktaler-3 -B

adding -w alternate-wisdom.toml if you don’t want to process the default wisdom file.

Finally, batch and interactive usage will use the default wisdom file, unless -w alternate-wisdom.toml is specified.

# 4 Videos

In reverse chronological order. Other software used typically includes zoomasm, ffmpeg, imagemagick, bash, gnu imp.

Made with Fraktaler 3 Version 0 (pre-release) unless otherwise stated.

# 4.1 Creamed Whip

Creamed Whip video still

Made with Fraktaler 3 Version 2 (pre-release) and Zoomasm 4 (pre-release).

Page: Creamed Whip

Download: archive.org (768MB)

# 4.2 The 22-Legged Ant

The 22-Legged Ant video still

Page: The Ant With 22 Legs

# 4.3 lockaccum

lockaccum video still

Warning: some parts are a bit stroboscopic.

Page: lockaccum

Download: archive.org (852MB)

# 4.4 Rocks

Rocks video still

Page: Rocks

Download: archive.org (990MB)

# 4.5 Rainstorm

Rainstorm video still

Page: Rainstorm

Download: archive.org (2.8GB)

# 4.6 Tree Core

Tree Core video still

Page: Tree Core

Download: archive.org (1.5GB)

# 4.7 Cerebral Infection

Cerebral Infection video still

Page: Cerebral Infection

Download: archive.org (600MB)

# 4.8 Twosday

Twosday video still

Page: Twosday

Download: archive.org (965MB)

# 4.9 Zigzag

Zigzag video still

Page: Zigzag

Download: archive.org (3.1GB)

# 4.10 Non-Smooth

Non-Smooth video still

Page: Non-Smooth

Download: archive.org (177MB)

# 5 Bugs

These bugs are not fixed yet in any version (released or unreleased):

  • extreme OpenCL settings can cause GPU timeouts, on Linux this can exit desktop session losing unsaved data in all open applications; workaround: don’t use a GPU that is used for display; workaround: set Interactive OFF in X config (NVIDIA only, may inhibit system responsiveness);

  • fails to launch on Android 4.4.4 due to missing symbol localeconv required by libgmp.so, later versions of Fraktaler-3 for Android explicitly require Android 5 Lollipop API level 21, 2014;

  • clipboard support is not fully functional in the live web version;

  • rotating display or using split screen feature skews fractal in Android 7.1;

  • fractal is not accurately framed when zooming off-center, or pixelation or other distortion may occur, when reuse reference is active and/or lock maximum iterations to period of reference is active; workaround: disable reuse reference and disable lock maximum iterations to period of reference (this will be slower but more accurate).

# 6 History

# 6.1 Version 0

2021-12-10 : project started.

# 6.2 Version 1

2023-03-13 : version 1 released. 423 git commits since version 0.

# 6.2.1 Bugs In Version 1

These bugs are all fixed in later versions:

  • zooming out too far crashes program:

    terminate called after throwing an instance of 'std::length_error'
      what():  vector::_M_default_append
    Aborted
    

    fixed in v1.1

  • high powers may render incorrectly (iteration bands due to overflow); workaround: reduce bailout escape radius; partially fixed in v1.1 with workaround: disable low range type float in wisdom;

    Example power 5 location: fraktaler-3-power-5.f3.toml

    Bad image with version 1:

    fraktaler 3 version 1 power 5 bad

    Good image with version 1-4 or later (prerelease):

    fraktaler 3 version 1-4 power 5 ok

  • high powers may render incorrectly (perturbation glitches); no workaround; fixed in v1.1

    Example power 100 location: fraktaler-3-power-100.f3.toml

    Bad image with version 1:

    fraktaler 3 version 1 power 100 bad

    Good image with version 1-4 or later (prerelease):

    fraktaler 3 version 1-4 power 100 ok

  • non-central reference (e.g. translation after Newton zooming) can cause badly framed batch mode renders (looks fine in interactive mode); do a small batch render to check before large render; workaround: save, delete reference real imag period from toml, reload; fixed in v1.1

    Example location: fraktaler-3-batch-noncentral-v1-bad.f3.toml / fraktaler-3-batch-noncentral-v1-workaround.f3.toml

    Badly framed image with version 1:

    fraktaler 3 version 1 batch noncentral reference bad

    Well-framed image with version 1.1 (or v1 using workaround delete reference from toml):

    fraktaler 3 version 1.1 batch noncentral reference ok

  • combining multiple settings files in batch mode may not work reliably leading to bad images (formula is reset to default Mandelbrot if file doesn’t have any formula); workaround: combine by hand into one toml file; fixed in v1.1

  • bad wisdom file causes abnormal program exit; for example, if a number type has no associated devices:

    terminate called after throwing an instance of 'std::out_of_range'
      what():  [error] key "device" not found
     --> unknown file
        |
     23 | [type.float]
        | ~~~~~~~~~~~~ in this table
    Aborted
    

    workaround: delete type entirely if there are no devices for it; fixed in v1.1

  • smooth iteration count is incorrect for powers other than 2; only visible if colouring raw data externally; no workaround; fixed in v1.1

    Example power 4 location: fraktaler-3-power-4.f3.toml

    Example palette for KF2+: fraktaler-3-power-4.kfp

    Bad image with version 1 (colourized with KF2+):

    fraktaler 3 version 1 power 4 bad

    Good image with version 1-4 or later (prerelease) (colourized with KF2+):

    fraktaler 3 version 1-4 power 4 ok

  • EXR images saved by interactive mode are too bright (frames are summed instead of averaged) and flipped vertically workaround: adjust exposure (stops = -log2(subframes)) and flip in post; fixed in v1.1

    Example with 16 subframes (same location as above): fraktaler-3-batch-noncentral-v1-workaround.f3.toml

    Bad image with version 1:

    fraktaler 3 version 1 gui export bad

    Good image fixed with post processing in GNU IMP (-4 stops exposure adjustment, vertical flip):

    fraktaler 3 version 1 gui export fixed in post

    Good image also results from version 1-5 or later (prerelease);

  • loading parameters in interactive mode may cause image size confusion; fixed in v1.1 (image size in interactive mode is locked to window size)

  • adjusting reflection/rotation in transformation dialog is not intuitive; fixed in v1.1

  • auto stretch fails when reflection is active; workaround: disable reflection and flip image in post; fixed in v1.1

  • Newton zooming fails when reflection is active; workaround: disable reflection; fixed in v1.1

  • Newton zooming may enable reflection; doesn’t cause further issues in v1.1;

  • batch mode reported tile count progress uses tiles started rather than finished; fixed in v1.1

  • interactive mode progress reporting is misleading sometimes; fixed in v1.1

  • cancelling tiles rendering on CPU without OpenCL takes too long; fixed in v1.1

  • wisdom benchmarking does not take account of hardware map (have to delete device for all types to prevent device being benchmarked) fixed in v1.1

Bugs found in later versions may also be found in this version.

# 6.3 Version 1.1

2023-03-20 : version 1.1 released. 18 git commits since version 1.

# 6.3.1 Bugs In Version 1.1

These bugs are fixed in later versions:

  • large reference (for example beyond the left tip of the needle) leads to bad images; workaround:
    1. shift the view so that the reference is not too large and the fractal is visible;
    2. enable reuse reference in the algorithm dialog;
    3. frame the view to your liking;
    4. when it happens again after zooming deeper, disable reuse reference and repeat from step 1;
    fixed in v1.2 and v2.1

# 6.4 Version 1.2

2023-07-13 : version 1.2 released. 10 git commits since version 1.1.

  • fix bad rendering to the left of the needle.

  • fix typo in wisdom stopping.

  • documentation improvements.

  • use build-scripts for third-party dependencies.

  • upgrade third-party dependencies to latest versions.

# 6.4.1 Bugs In Version 1.2

These bugs are fixed in later versions:

  • live web version does not work (missing ccall symbol).

    fixed in v1.2.1 and v2.1

Bugs found in later versions may also be found in this version.

# 6.5 Version 1.2.1

2023-07-14 : version 1.2.1 released. 2 git commits since version 1.2.

  • fix build for web with current emscripten versions.

Built for web only, as 1.2 is unaffected on other platforms.

# 6.5.1 Bugs In Version 1.2.1

Bugs found will be listed here.

# 6.6 Version 2

2023-03-31 : version 2 released. 59 git commits since version 1.1.

# 6.6.1 Bugs In Version 2

These bugs are fixed in later versions:

  • large reference (for example beyond the left tip of the needle) leads to bad images; workaround:

    1. shift the view so that the reference is not too large and the fractal is visible;
    2. enable reuse reference in the algorithm dialog;
    3. frame the view to your liking;
    4. when it happens again after zooming deeper, disable reuse reference and repeat from step 1;

    fixed in v1.2 and v2.1

  • BLA steps text entry doesn’t work properly; workaround: set desired BLA steps in the perturb iterations field, edit BLA steps text entry, reset pertub iterations field to previous value;

    fixed in v2.1

# 6.7 Version 2.1

2023-07-14 : version 2.1 released. 14 git commits since version 2.

# 6.7.1 Bugs In Version 2.1

Bugs found will be listed here.

# 7 Future

# 7.1 Version 1.3

Will fix bugs in version 1.2.1.

# 7.2 Version 2.2

Will fix bugs in version 2.1.

# 7.3 Version 3

Main work planned:

  • (DONE) more flexible colouring.

  • (DONE) return of information window (present in early pre-releases).

  • (DONE) batch mode graphical user interface.

# 7.3.1 Version 3 Beta

Please test the beta releases here and provide feedback:

Known issues:

  • documentation is incomplete or otherwise out of date.

  • Android version can sometimes end up in fantasy locations, where trying to recreate the image from its supposed parameters fails. Possibly related to extensive use of multi-touch navigation?

  • no on-screen keyboard in Web version on Android, making it impossible to edit various options; tested with Fennec f-Droid browser; workaround: use Android version.

  • Web and Android versions should not have “quit when done” option in render window.

  • no ARM builds for Windows: I have no way to test them.

  • any more issues you find and report will be listed here and hopefully fixed before the full release.

Final release expected early July 2024.

# 7.4 Ideas

Some ideas for features that may or may not ever be implemented.

# 7.4.1 Soon

  • Linux

    • check everything works on Debian
  • Windows

    • check everything works in Wine

    • check everything works in Windows 11 VM

    • check everything works in Windows on hardware

  • Android

    • check everything works on Android 7 tablet
  • Web

    • check everything works in Firefox ESR on Debian

    • check everything works in Chromium on Debian

    • check everything works in Firefox ESR on Windows

    • check everything works in Chromium on Windows

    • check everything works in Fennec f-Droid on Android

# 7.4.2 Later

  • Linux

    • desktop entry with icon

    • Debian package

    • build instructions for other distributions

  • Windows

    • GUI on ARM is missing

    • aarch64 crashes in Wine on rpi3

    • armv7 untested (no multi-arch on rpi3)

    • stdio vs cmd shell vs msys terminal

  • Android

    • fantasy locations with multitouch zooming?

    • log crashes somehow and start with option not to restore persistence

  • Web

    • export/import parameters to/from URL hash (base64)

    • think of a way to make default canvas size vary (fill browser window)

  • FreeBSD

    • see if support is possible / easy
  • macOS

    • find someone to do any work required
  • bundle examples in app and allow unpacking somewhere?

  • batch enhancements

    • batch mode Newton zooming

    • “are you sure” program close confirmation dialog

  • check sRGB (un)packing when EXT_color_buffer_float is not used

  • more exciting default colouring

  • very high resolution support (images larger than maximum OpenGL texture size)

  • do proper filtering when downscaling large image to small window

  • optional delay before recolouring tiles after parameters change, instead of immediately on every adjustment; optionally infinite delay with button (+ keyboard shortcut) to force recolour

  • optional delay before recalculating fractal after settings change, instead of automatically on gesture end; optionally infinite delay with button (+ keyboard shortcut) to force recalc

  • optimizations (mainly: reduce GPU round-trips - currently tiles are computed with OpenCL, downloaded to host, uploaded to OpenGL for colouring, then downloaded for assembly into larger image, which is then uploaded to OpenGL again for display…)

  • improve keyboard navigation in user interface

  • option to select sub-region for auto stretch de analysis

  • transform dialog issues

    • auto stretch de should update preview transform before rendering starts

    • rotation slider should update preview

    • rotation slider interacts strangely with stetch

  • location dialog issues

    • changing values (particularly zoom depth) should update preview transform before rendering state
  • in interactive mode, sort tiles by distance from center of image, and compute nearest ones first

  • first launch wizard / tour of UI

    • or maybe a video tutorial series
  • research atom domain size estimates for non-Mandelbrot fractals

  • research Misiurewicz domain size estimate for non-Mandelbrot fractals

  • a way to specify default values, ranges, preferred widgets, etc

    • consider FragM-style annotations in comments

    • or mega-widget combining (log) sliders, colour selector, etc

  • load images for colouring

    • 1d gradients

    • 2d images

    • texture arrays (videos imported using ffmpeg?)

  • low/high bailout, stripe colouring, etc:

    • expose low precision version of formula to colouring shader

    • expose low precision version of C coordinates to colouring shader

  • colouring post processing pass custom GLSL

    • exposure

    • tone mapping

    • colour adjustment

    • vignette

    • text overlay

    • etc

  • zoom depth and other text overlay without GLSL hacks

    • custom font loading

    • format strings (double mantissa + int exponent)

    • option for zoom depth as double exponent (log of zoom)

  • headless colouring

    • OSmesa software OpenGL

    • OpenCL colouring snippet

  • custom transformation GLSL

    • given pixel coordinates, calculate coordinates in unit disk where magnitude 1 corresponds to corners of image

    • low discrepancy sequences (based on plastic number)

    • derivatives for DE colouring

    • INPUTS

      • i:[0,w), j:[0,h)

      • w, h

      • sample, nsamples

      • frame, nframes

      • log(zoom)

      • random seed

      • skew matrix

    • OUTPUTS

      • x, y

      • dxi, dxj, dyi, dyj

      • also needs inverse transformation to find i,j given x,y for interaction from GUI

    • LIBRARY

      • low discrepancy sequence

      • dual numbers

      • prng hash

      • default transformations

        • rectangle

        • exponential map

        • Riemann sphere / equirectangular

    • OUTPUT

      • need to analyze for BLA radius

      • analyse derivatives to see if sufficient precision?

    • PARAMS

      • introspected uniforms
  • embed Lua scripting

    • adjustment of OpenGL colouring parameters

    • zoom and pan by image coordinates

    • Newton zoom by image coordinates

    • autoskew DE function

    • provide access to raw subframe(s) data

    • provide access to raw histograms

    • provide access to output image RGB histograms (HDR)

    • port Rodney’s colouring palette auto-white balance

    • control batch rendering for non-standard videos

    • needs a way to wait for actions to finish

    • needs a way to interrupt/resume scripts if necessary

    • needs a way to ask for user to peform actions in case full automation is not possible (e.g. a Julia morphing helper tool)

  • port feature-finder from Imagina

    • autofocus mode for scroll wheel
  • fix OpenCL GPU timeouts

    • maximum time target per kernel invocation (e.g. 100ms)

    • limit total number of steps per kernel

    • 1D kernel manually initialized in Z order

    • either initialize or load in progress iterations from buffer

    • either output raw data or store in progress iterations to buffer

    • atomic counter to get index for in progress output

    • stop when in progress buffer is empty

    • ping-pong two in-progress buffers

    • automatically compacted (reduce memory bandwidth)

  • automatic tile size adjustment w.r.t device count and image size

  • eventually merge with zoomasm for all-in-one program

  • fix IO

    • CLI should have an option to save TOML from argument (which could be an image)

    • report estimated file size before saving

    • check available disk space and warn before saving if too low) (especially with zoom out sequence)

  • optimize MPFR memory allocation

    • period detection

    • root finding

    • size calculation

  • optimize conformal formulas

    • use complex numbers instead of matrices

    • Mandelbrot set / multibrot only?

    • disable stretch transformation

  • computation adjustments

    • compute analytic dDE/dij (see Cheritat’s wiki)

    • replace NF,T with final Z > R, degree for better interpolation?

    • exponential smoothing, consider interactions with BLA

    • interior colouring via (convergent, periodic) exponential smoothing

    • iteration count per step vs per +c

    • reference compression

  • number type wisdom

    • compute sizeof and take memory availability into account

    • report/limit memory used for reference and BLA

  • extend colouring algorithms

    • port nice algorithm from Rodney, parameterized

    • allow custom OpenCL source for colouring snippet (no parameters)

    • use OSMesa to do colouring without a DISPLAY

  • compat with other software

    • KFR location import, including metadata from image files

    • KFR location export, including metadata to image files

    • KFP palette import (with default GLSL implementation copied from KF)

    • KF custom GLSL import mode (see zoomasm)

    • custom GLSL export for zoomasm

  • image export

    • EXR with (downscaled) preview image

    • set JPEG export quality

  • save log/linear histogram options in GUI settings; log by default

  • exponential map

    • DE direction is relative to strip (not really a bug in fraktaler-3, should be possible to fix zoomasm)

    • option to change stretch factor (default 2)

    • option to make conformal (adjust stretch factor based on image size)

    • report stretch factor

    • make GUI interactions sensible

    • implement within custom GLSL?

    • change skew matrix over radial direction for zoom+skew animation (needs to have rate limited to avoid “sonic boom”)

  • history browser

    • sqlite3 database

    • handle multiple concurrent sessions (PID + start time)

    • auto-store thumbnails

    • maximum total size limit for thumbnails (prune at random?)

    • undo / redo by copying previous states

  • autosave/resume

    • metadata file with append-only log (updated last in case of power failure)

    • mmap reference orbit file

    • mmap 1 raw subframe file

    • (atomically) sync every few minutes and when done

    • mmap accumulated subframes file

    • (atomically) sync after subframe accumulated (rate limited)

    • resume from saved data

    • SIGHUP to batch process triggers autosave and continue

    • SIGINT/TERM trigger autosave and exit

    • Windows equivalents to signals?

    • GUI controls for batch rendering?

  • mandelbrot-perturbator annotations overlay

  • cross-hair cursor when over fractal

  • target cursor when Newton zooming is activated

  • touchscreen improvements

    • double tap to activate Newton zooming
  • time-based ETA reporting

    • single image

    • Newton zooming

    • zoom out sequence

  • check website for new version (button in GUI)

  • tutorial on using with Zoomasm

  • wishlist: Nova, Magnet (suggested by Alex)

  • wishlist: smooth scrolling zoom animation

  • high DPI display support

    • automatically adjust UI scale on first launch
  • check non-ASCII paths

  • make saved files appear in OS recent files list