User Manual
PDF version of the User Manual - a little outdated but still quite relevant.
Contents
General buttons
- Render – Start image rendering
- Stop – Stop rendering
- Select file paths – open window with setup for paths of additional files
- Load setting – load all fractal parameters from file
- Save settings – save all fractal parameters to file
- Load example - load example settings file
- Copy to clipboard - copy settings into clipboard as a text
- Paste from clipboard - paste settings text from clipboard
- Undo - undo all changes made since last rendering (100 levels of undo)
- Redo - redo changes
Select file paths window
- Destination image sequence – path and file name prefix for saved images. To the name will be automatically added a number of the image and extension ".jpg” or ".png"
- Background – path for the image which will be used as a image background.
- Environment map – path for the image which will be used as a fake reflection.
- Ambient occlusion colour map – path for the image which will be used as a colour map for ambient occlusion effect.
- Animation path – file in which will be stored recorded flight path.
- Keyframe sequence - path and file name prefix for key-frame files.
Settings files are text files which can be also edited using simple text editors. It is important to keep proper file syntax and names of parameters. Default settings are stored in $HOME/.mandelbulber/settings/defaut.fract file.
Fractal tab
Fractal parameters - Formula
Fractal formula type - Selection for fractal formula type
- Trigonometric (Mandelbulb)
<math> r = \sqrt{x^2+y^2+z^2}\\ \alpha\ = atan2(y,x)\\ \beta\ = -atan2(z,\sqrt{x^2+y^2})\\ x=r^p cos (p \beta\) cos (p \alpha\) + a\\ y=r^p cos (p \beta\) sin (p \alpha\) + b\\ z = r^p sin (p \beta\) + c </math>
- Trigonometric with calculation of analytic DE – is the same like the Trigonometric formula but distance estimation is calculated by analytic formulas. This formula is faster than Trigonometric but less accurate for low power fractals and Julia fractals
- Polynomic power 2
<math> newx = (x^2-y^2) \left (1.0 - \frac{z^2}{x^2+y^2}\right )\\ newy = 2xy \left (1.0 - \frac{z^2}{x^2+y^2}\right )\\ newz = -2z \sqrt{x^2+y^2}\\ x = newx+a\\ y=newy+b\\ z=newz+c </math>
- Polynomic power 2 – minus z
<math> newx = (x^2-y^2) \left (1.0 - \frac{z^2}{x^2+y^2}\right )\\ newy = 2xy \left (1.0 - \frac{z^2}{x^2+y^2}\right )\\ newz = 2z \sqrt{x^2+y^2}\\ x = newx+a\\ y=newy+b\\ z=newz+c </math>
- Hypercomplex
<math> newx = x^2 - y^2 - z^2 - w^2\\ newy = 2(xy-wz)\\ newz = 2(xz-yw)\\ neww = 2(xw-yz)\\ x = newx+a\\ y=newy+b\\ z=newz+c\\ w=neww </math>
- Quaternion
<math> newx = x^2 - y^2 - z^2 - w^2\\ newy = 2xy\\ newz = 2xz\\ neww = 2xw\\ x = newx+a\\ y=newy+b\\ z=newz+c\\ w=neww </math>
Pseudo code:
if(x > foldingLimit) x = foldingValue - x elseif(x < -foldingLimit) x = -foldingValue - x if(y > foldingLimit) y = foldingValue - y elseif(y < -foldingLimit) y = -foldingValue - y if(z > foldingLimit) z = foldingValue - z elseif(z < -foldingLimit) z = -foldingValue - z length = sqrt(x2 + y2 + z2) if(length < minRadius) { x = x * fixedRadius2 / minRadius2 y = y * fixedRadius2 / minRadius2 z = z * fixedRadius2 / minRadius2 } elseif(length < fixedRadius) { x = x * fixedRadius2 / length2 y = y * fixedRadius2 / length2 z = z * fixedRadius2 / length2 } x = x * scale + const.x y = y * scale + const.y z = z * scale + const.z
- Default parameters:
- scale = 2.0
- foldingLimit = 1.0
- foldingValue = 2.0
- fixedRadius = 1.0
- minRadius = 0.5
- Kaleidoscopic IFS - Function Systems
z.x = abs(z.x); z.y = abs(z.y); z.z = abs(z.z); for i = 0 to IFS_number_of_vectors { z = RotateVector(IFSRotation[i], z); //rotate vector z length = z dot IFSDirection[i]; dot product of z vect. and symmetry vect. if length < IFSDistance[i] { z -= IFSDirection[i]*(2.0*(length-IFSDistance[i])*IFSIntensity[i]); //mirroring z vector relative to IFSDirection symmetry vector } } z = RotateVector(IFSMainRotation, z - IFSOffset) + IFSOffset; //main rotation z = z * IFSScale; //scale z = z - IFSOffset * (IFSScale - 1.0); //offset
- Hybrid - Mixed formula. Setup on Hybrid tab. For many hybrid formulas is recommended to enable Linear DE mode, especially when quality of rendering is poor.
- Julia mode - enable rendering of 3D Julia fractals
- Julia x, Julia y, Julia z - Julia constant
- Power – power value of fractal formula
- z_{n+1} = z_{n}^{p} + c
- p - power
- Fractal constant factor - multiplies c constant value by given factor
- z_{n+1} = z_{n}^{p} + f*c
- f - factor
Folding
- Tglad's folding mode - add Tglad's folding function to selected fractal formula
if(x > foldingLimit) x = foldingValue - x elseif(x < -foldingLimit) x = -foldingValue - x if(y > foldingLimit) y = foldingValue - y elseif(y < -foldingLimit) y = -foldingValue - y if(z > foldingLimit) z = foldingValue - z elseif(z < -foldingLimit) z = -foldingValue
Example of Mandelbulb power 8 (Trigonometric) with folding function:
- Folding limit, Folding value - parameters for Tglad's folding
- Spherical folding mode - add spherical folding function to selected fractal formula
length = sqrt(x2 + y2 + z2) if(length < minRadius) { x = x * fixedRadius2 / minRadius2 y = y * fixedRadius2 / minRadius2 z = z * fixedRadius2 / minRadius2 } elseif(length < fixedRadius) { x = x * fixedRadius2 / length2 y = y * fixedRadius2 / length2 z = z * fixedRadius2 / length2 }
- Fixed radius, Min radius - parameters for Spherical folding mode
- Kaleidoscopic IFS folding mode - mix selected formula with Kaleidoscopic IFS formula. All parametrs have to be set on IFS tab
Engine
Ray-tracing parameters
- Max. iterations – maximum number of iterations of fractal formula. Higher value gives higher amount of details. This value is taken into consideration whether Maxiter threshod mode is activated or not.
- Min. iterations - minimum number of iterations which allows ray marching to stop. It is useful to reduce details in areas with high estimated distance and low number of iterations
- Detail level - factor for dynamic threshold (to stop ray-marching) based on estimated distance. Higher value gives sharper details.
Detail level = 1.0 is an equivalent to minimum details size = 1 screen pixel
- DE step factor – Distance Estimation step factor - quality of ray marching. Lower value gives better quality (avoiding of overstepping) but slower rendering. For most fractals optimal value is between 0.5 and 1.0. For some hybrid fractals it should be lower than 0.2.
How to get optimal value of DE step factor:
When DE step factor is too high, it is visible on image. The quality is then poor, some details are missed, and a lot of black spots are visible. But when this factor is too low, rendering speed is very low and quality is not better than when this factor is optimal.
For finding the optimal DE value there is a very helpful histogram of number of ray-marching steps (green one in Histograms window)
Histogram of DE steps is very thin and starts almost from zero. It means that the ray-marching algorithm always finds fractal surface in few steps but it is very probable that last steps go inside the fractal (overstepping). The image will be distorted.
Histogram is too wide and starts from high values (is moved to the right). It means that the ray-marching algorithm always needs many steps to find fractal surface. Image will look good but rendering will be very slow.
Histogram is thin but not too thin. Image quality is good and rendering is fast.
- LQ - automatic evaluation of DE step factor to get low quality image
- HQ - automatic evaluation of DE step factor to get high quality image
- Smoothness - controls smoothness of surface shading. Higher value gives less details on surface
- Maxiter threshold mode - ray marching stops when it achieves required maximum number of iterations (maximum iter). Shape of fractal is a little different than in distance estimation threshold mode. Program doesn't control detail level automatically.
- Interior mode - enables rendering of fractal interiors. The fractal is rendered as a thin skin. It works very well with limits. Rendering with this mode is extremely slow.
- Dynamic DE correction - sometimes improves quality of rendering
- Linear DE mode - it is recommended to enable this for many hybrid formulas, especially when quality of rendering is terrible.
- Const, DE threshold - instead of Detail level, there is used constant estimated distance threshold. Amount of details will not depend on image resolution.
- Minimum / Maximum render distance - limits visibility distance. It can be used for optimise rendering time.
Limits
- Enable limits – fractal will be cut according to entered slicing planes
- x_min, y_min, z_min, x_max, y_max, z_max – coordinates of cross-section planes
IFS tab
Parameters on Kaleidoscopic IFS tab are used when there is selected Kaleidoscopic IFS formula or there is enabled IFS folding mode.
All Kaleidoscopic IFS parameters correspond to parameters in program code:
z.x = abs(z.x); z.y = abs(z.y); z.z = abs(z.z); for i = 0 to IFS_number_of_vectors { z = RotateVector(IFSRotation[i], z); //rotate vector z length = z dot IFSDirection[i]; dot product of z vect. and symmetry vect. if length < IFSDistance[i] { z -= IFSDirection[i]*(2.0*(length-IFSDistance[i])*IFSIntensity[i]); //mirroring z vector relative to IFSDirection symmetry vector } } z = RotateVector(IFSMainRotation, z - IFSOffset) + IFSOffset; //main rotation z = z * IFSScale; //scale z = z - IFSOffset * (IFSScale - 1.0); //offset
General IFS parameters
- Scale - general scale of IFS formula (IFSScale)
- Rotation alfa, beta, gamma - main rotation angle of IFS formula (IFSMainRotation)
- Offset x, y, z - offset vector for scaling and main rotation (IFSOffset)
- abs(x), abs(y), abs(z) - enables/disables absolute value functions for each axis. These functions make additional mirroring of IFS formula
Symmetry vectors
It is possible to define up to 9 independent symmetry vectors
- symmetry x, symmetry y, symmetry z - directions of symmetry vectors (IFSDirection[i])
- alfa, beta, gamma - rotation angle of IFS formula before mirroring for each symmetry vector (IFSRotation[i])
- distance - distance of "mirrors" from the origin (IFSDistance[i])
- intensity - intensity of vector reflection. 1.0 - normal mirroring, 0.0 - symmetry vector disabled
- enable - whether the symmetry vector will be used
- Normalize symmetry vectors - set length of symmetry vectors to 1.0. Note: All vectors are automatically normalized after pressing Render button
- Normalize offset vector - set length of offset vector to 1.0
Hybrid tab
- Within the Hybrid tab it is possible to combine different formulas to generate hybrid fractals that inherit the characteristics of each of their formulas.
- Using the "Iterations" boxes, you can specify how many times each formula is calculated before the program proceeds to the next formula.
- When the "Cyclic loop" checkbox is checked, the program returns to the first formula when it completes the last specified formula. If "Cyclic loop" is unchecked, the first formulas are calculated and in sequence, and then Formula #5 (which must be enabled) is repeated.
- For each formula it is possible to define the power or scale parameter.
Note: for most of hybrid formulas it is necessary to reduce "DE step factor" to avoid the overstepping effect (many black spots or heavy noise on image).
Mandelbox tab
Parameters on Mandelbox tab are used when Tglad's (Mandelbox) IFS formula is selected or IFS folding mode is enabled.
All Mandelbox parameters correspond to parameters in the program code:
//cubic folding //x axis if(x > foldingLimit) //positive folding plane x = foldingValue - x elseif(x < -foldingLimit) //negative folding plane x = -foldingValue - x //y axis if(y > foldingLimit) //positive folding plane y = foldingValue - y elseif(y < -foldingLimit) //negative folding plane y = -foldingValue - y //z axis if(z > foldingLimit) //positive folding plane z = foldingValue - z elseif(z < -foldingLimit) //negative folding plane z = -foldingValue - z length = sqrt(x2 + y2 + z2) //spherical folding if(length < minRadius) { x = x * fixedRadius2 / minRadius2 y = y * fixedRadius2 / minRadius2 z = z * fixedRadius2 / minRadius2 } elseif(length < fixedRadius) { x = x * fixedRadius2 / length2 y = y * fixedRadius2 / length2 z = z * fixedRadius2 / length2 } //scaling x = x * scale + const.x y = y * scale + const.y z = z * scale + const.z
Main Mandelbox Parameters
- Scale - scale parameter for Mandelbox formula (scale)
- Folding limit - limit value for cubic folding (foldingLimit)
- Folding value - offset value for cubic folding (foldingValue)
- Fixed radius - parameter for spherical folding - higher limit value (fixedRadius)
- Min radius - parameter for spherical folding - lower limit value (minRadius)
Rotation of Mandelbox folding planes
- Main rotation alfa, beta, gamma - rotation angle of actual vector after each iteration
- Enable rotation of each folding plane - enables independent rotation of each folding plane
- Negative plane alfa, beta, gamma - rotation angles for negative folding planes
- Positive plane alfa, beta, gamma - rotation angles for positive folding planes
Mandelbox colouring parameters
Colour texture of Mandelbox surface is calculated as a sum of six independent components
- Resultant absolute value component - factor for colour component generated from absolute value of last x, y and z values.
- X, Y, Z plane component - when folding occurs on x, y or z axes, the value from these edit fields is added to the colour value.
- Min, fixed radius component - when spherical folding occurs on minRadius or fixedRadius limit, the value from these edit fields is added to the colour value.
View tab
Viewpoint coordinates
- x, y, z - coordinates of the target for the camera (viewpoint)
- alpha (yaw), beta (pitch), gamma (roll) - rotation angle of the camera around the target point
- Close up (zoom) - distance between the camera and the target point
- perspective (FOV) - Field Of View. It controls camera perspective depth. When FOV = n, then if the object is n times closer to the camera, then it is n+1 times larger. If there is enabled Fish eye projection or Equirectangular projection and when FOV = 1 then view angle will equals 360 degree.
- Perspective projection - selection between three types of perspective projection
- Arrows on the left side - rotates the camera around the viewpoint
- Arrows on the right side - moves the viewpoint
- Reset view - according to actual view angle and FOV value it calculates initial camera position
- Forward - moves the viewpoint forward
- Backward - moves the viewpoint backward
- Step for camera movement multiplied by DE - viewpoint (camera) will be moved by the distance equals to the distance from the fractal surface multiplied by this factor
- Absolute distance mode - switch between moving the viewpoint (camera) by the distance dependent on actual distance to the fractal surface and by the Absolute movement distance. When this is unchecked, the movement distance is automatically adapted.
- Absolute movement distance - movement distance which is used when the Absolute distance mode is checked
- Rotation step in degrees - defines rotation step of camera for rotation arrows
- Mouse click close-up ratio - specifies how many times the viewpoint will be closer to the indicated point
- Enable zoom by mouse click - enables zooming of image using mouse pointer
- Go close to indicated surface - when enabled, then viewpoint will be moved very close to the fractal surface and zooming will be done by reducing Close up (zoom) parameter
- Rotation without using gamma angle - when disabled, there will be used also gamma angle for camera rotation
Tip: in 'Absolute distance mode', clicking 'Forward' then 'Backward' returns you to the same point, whereas doing this in relative mode you may end up in a different place because the DE values may be different.
Shaders tab
Shading effects
- Brightness - image brightness
- Gamma - image gamma
- Shading - intensity of shading effect based on angle of incidence of light
- Direct light - intensity of the main light source
- Specularity - intensity of light specular reflection
- Ambient - intensity of simple ambient light
- Ambient occlusion - intensity of ambient occlusion effect
- Ambient = 2.0, example images rendered with only ambient occlusion effect
- Glow - intensity of glow effect
- Reflect - intensity of environment map reflection. Texture for this effect has to be specified using Select file paths window in Environment map edit field.
- Ambient occlusion quality - this value specifies how many rays will be used for ambient occlusion effect based on rays
- quality = 1 -> 8 rays
- quality = 3 -> 64 rays - recommended value
- quality = 5 -> 165 rays
- quality = 10 -> 645 rays
- quality = 30 -> 5702 rays (extremely slow rendering)
- Shadows - enables rendering of shadows
- Ambient occlusion - enables of rendering ambient occlusion effect based on tracing of many rays. This option offers the highest quality of ambient occlusion effect but it is the slowest. For this effect there is used colour map texture specified in Select file paths window in Ambient occlusion colour map edit field
- Ambient occlusion fast mode - enables fast algorithm for ambient occlusion effect based on orbit traps. It works only with Trigonometric formulas
- Not DE shading mode - enables special algorithm for calculating shading effects which not use distance estimation. This algorithm is slow but always works very well.
- example: hipercomplex formula has not accurate distance estimation, so with starndard method shading looks poor
- Textured background - when it is enabled, as a background will be used spherical wrapped texture specified in Select file paths window in Background edit field
Colour palette
- Coloured surface - enables colouring algorithm for the fractal surface
- Random seed - actual random seed for randomly generated palette
- Colour speed - speed of colour varying
- Random palette - randomises the colour palette
- Get palette from image - gets palette from selected JPG file (photos, images with interesting colours). Palette is grabbed from circular area shown on image below.
- Offset - shifts colours
Colours
- Glow colour 1 - colour of low intensity glow area
- Glow colour 2 - colour of high intensity glow area
- Background colour 1 - colour of left top corner of image background
- Background colour 2 - colour of right bottom corner of image background
Apply changes button
The Apply changes button refreshes the image after changing of shading parameters. With this function it is possible to make final correction even when rendering of image is finished. Below is the list of parameters which can be corrected after image rendering
- Shading effects
- brightness
- gamma
- shading
- direct light
- secularity
- ambient
- ambient occlusion (value)
- glow
- reflect
- Colour palette
- colour speed
- random palette
- get palette from image
- offset
- Lights
- main light source colour
- main light source intensity
- lights visibility
Lights tab
Main light source
The main light source is connected with the camera. When camera is rotated then also main light is rotated. Position of main light source is relative to the camera.
- Horizontal/vertical angle relative to camera - position of the main light source is specified by two angles.
- If horizontal angle = 0, then the light is placed on the back of the camera
- If horizontal angle = 180, the the light is on the front
- If horizontal angle = -90, the light is on the left, and when +90, then on the right
- If vertical angle = 0 then the light is on the same height as a camera.
- If vertical angle = 90, then the light is on the top, and when -90 then on the bottom.
- Colour - colour of the main light source
Common parameters
- Distribute / update lights - updates of auxiliary lights parameters and distribute random lights. Distribution of random lights can take several minutes.
- Number of aux. lights - number of auxiliary lights (predefined and random) which will be rendered
- Manual placement distance - when predefined light is placed using mouse pointer, this is light distance from fractal surface. Light is not placed directly on surface, but in front of the indicated point.
- To place lights by mouse pointer there has to be selected "Set position of aux. light #x" in Mouse click function combo box in Mandelbulber Render Window
Light brightness balance
- Main light intensity - intensity of the main light source
- Auxiliary lights intensity - intensity of the light form auxiliary light sources
- Lights visibility - intensity of glow around light sources
Random lights parameters
- Random seed - random seed for lights distribution
- Maximum distance from the fractal - random lights are placed not further from the fractal surface than this distance value
- Distribution radius of lights - maximum distance from Centre of distribution where lights can be placed. If there is not possible to place lights inside the sphere of this radius, because of Maximum distance from the fractal surface restriction, the program will automatically increase this radius.
- Centre of distribution X, Y, Z - the centre point for random light distribution. To set this point by mouse pointer there has to be selected "Set position of centre for random lights" in Mouse click function combo box in Mandelbulber Render Window
Predefined lights
- x, y, z - position of the light. To place lights by mouse pointer there has to be selected "Set position of aux. light #x" in Mouse click function combo box in Mandelbulber Render Window
- intensity - intensity of the light
- colour selector - colour of the light
- Enable - enables light source
Image tab
Image parameters
- image width / height - resolution (size) of rendered image
Stereoscopic rendering
- Distance between eyes - the distance between virtual eyes. Higher value gives more visible depth effect.
- Enable stereoscopic rendering - enables rendering of stereoscopic images. If it is enabled, there will be rendered 2 separate images and automatically connected side by side.
Image saving
- Save JPG - saves image in JPG format (JPEG quality = 100%)
- Save PNG - saves image in PNG format (lossless)
- Save PNG 16-bit - saves image in PNG format with 16-bit colour channels
- Save PNG 16-bit + Alpha - saves image in PNG format with 16-bit colour channels and additionally with alpha channel (transparent background and glow effect)
- Autosave / animation image format - sets format for images saved during rendering of animation or saved in auto-save mode
- Auto-save - enables automatic saving of images in folder specified in Select file paths window in Destination image sequence edit field
Post effects tab
All post-effects can be added after rendering of image. These effects are based on information stored in z-buffer.
Fog
This effect simulates fog which limits visibility range
- Enable fog - enables fog effect
- Fog colour - colour of fog
- Visibility - Maximum visibility distance.
- To set this point by mouse pointer there has to be selected "Set fog visibility distance" in Mouse click function combo box in Mandelbulber Render Window
- Front - distance where the fog starts to be visible.
- To set this point by mouse pointer there has to be selected "Set fog front distance" in Mouse click function combo box in Mandelbulber Render Window
Screen space ambient occlusion
This effect simulates ambient occlusion. This algorithm is much faster than Ambient occlusion effect from Shaders / Shadings effects, but quality is lower and there is no possibility to simulate coloured illumination.
- Screen space ambient occlusion enable - enables SSAO effect
- Update image - updates (re-renders) image after changing of effect quality
- Quality - quality of SSAO effect
Depth of field
This effect simulates Depth of Field effect.
- Depth of field enable - enables Depth of field effect
- Update DOF - updated Depth of field effect after changing focus or radius
- Focus - focus distance
- Radius - strength of DOF effect
Time line window
The Timeline window allows you to view, add, edit and delete keyframes for an animation. Use the timeline together with the "Animation" tab to create animations in which many parameters can be interpolated.
Please visit the Getting Started section to read tutorial about creating animations
Command line mode
Mandelbulber program can be started from command line interface (CMD or terminal) or from some *.bat or bash script. Command line mode works on Linux and also on Windows
Syntax
mandelbulber [options...] [settings_file]
Options:
- -nogui
- start program without graphical user interface
- -lowmem
- start program in low memory consumption mode. When this mode is enabled, there is no possible to change intensity of shaders or correct post-processing effects after the rendering of image is finished
- -flight
- render flight animation according to animation parameters located in settings file
- -keyframe
- render keyframe animation according to animation parameters located in settings file
- -start N
- start rendering of animation from frame number N
- -end N
- rendering will end on frame number N
- -format FORMAT
- specifies output image format
- jpg - JPEG format
- png - PNG format
- png16 - 16-bit PNG format
- png16alpha - 16-bit PNG with alpha channel format
[settings_file] - file with fractal settings (program also tries to find file in ./mandelbulber/settings directory when the path is not specified)
When settings_file is put as command argument then program will start in noGUI mode
Examples
- mandelbulber "menger sponge.fract"
- renders image according to parameters stored in "menger sponge.fract" file located in %USER/.mandebulber/settings directory. Final image will be saved in directory specified in "Select files/paths window" (default is %USER/.mandebulber/images directory). This image path is also taken from settings file.
- mandelbulber -keyframe -start 100 -end 300 -format png16 "D:\anims\animation.fract"
- renders keyframe animation according to parameters stored in "animation.fract" file located in "D:\anims\animation.fract" directory. Animation will be rendered starting from frame numer 100 and will ended on frame number 300. Images with rendered frames will be saved in PNG 16-bit format.