Fractility

Users manual

Fractility - User Manual

Welcome to Fractility! This is a real-time, interactive fractal art generator. You can manipulate visuals by using your mouse, keyboard, and the dedicated control panel.

The application has two windows:

• Main Window: Shows the fullscreen visual output.

• Control Panel: A separate window containing all the sliders, buttons, and options to customize the effect.

Quick Start & Keyboard Controls

These are the most important keys for controlling the application.

• U Key: Toggles the Control Panel's visibility. If you can't see your controls, press 'U'.

• R Key (Hard Reset): Resets all parameters (transforms, colors, variations, etc.) to their default state and redraws the initial pattern. Use this when you get stuck or want a clean slate.

• T Key (Soft Reset): Resets only the visual pattern but keeps all of your current transform and color settings. This is great for seeing how your current settings affect a fresh image.

Mouse Controls

The mouse is your primary performance instrument.

Translation (Moving the Image)

First, select what you want to move using the checkboxes in the UI. Then, click and drag with the left mouse button.

• Move Checkboxes: Use the "Move" checkboxes in the UI to select which layers are affected by your drag. You can select multiple layers at once.

Scale & Rotation

• Mouse Wheel: Controls the Post-Scale (zooms the final image).

• Shift + Mouse Wheel: Controls the Post-Rotation (rotates the final image).

• Ctrl + Mouse Wheel: Controls the Pre-Scale (zooms the underlying space).

• Ctrl + Shift + Mouse Wheel: Controls the Pre-Rotation (rotates the underlying space).

The Control Panel: A Detailed Guide

Here is a breakdown of what each section in the control panel does.

Start Pattern

This section controls the initial image that the feedback loop starts with.

• Start Pattern Dropdown: Choose between "Gradient + Grid" or the "Circles" pattern.

• Show Start Grid/Show Circles Checkboxes: These are contextual. They appear when their parent pattern is selected and let you toggle the pattern overlay on or off, leaving just the base gradient.

• Gradient Controls: Four color pickers let you set the color for each corner of the starting gradient.

• Circle Controls: These appear when "Circles" is selected.

  • Count: The number of circles tiled across the screen.

  • Radius: The size of each circle.

  • Softness: The blurriness of the circle edges.

Variations

This is the core of the fractal engine.

• Top Dropdown (A): Selects the first fractal algorithm.

• Bottom Dropdown (B): Selects the second fractal algorithm.

• Mix: Blends between the output of Variation A (at 0.0) and Variation B (at 1.0).

Feedback

This section controls the overall behavior of the feedback loop.

• Amount: Controls the length of the "trails" or "motion blur." A high value (0.08) creates long, smooth trails. A lower value creates sharper, faster motion. This control is very touchy and should be used in small amounts

  • Here's a quick summary of how to use the new feedback range feature:

 What it is: You now have two new spinboxes labeled "Feedback Range" (Min and Max) located just below the "Feedback Amount" slider.

   How it Works: These spinboxes directly control the minimum and maximum values of the "Feedback Amount" slider above them.

   Platform Defaults: The system automatically sets different default ranges depending on your platform:

• Desktop: Defaults to a wide range (e.g., 0.0 to 0.1) for broad control.

• Web/Mobile: Defaults to a very tight range (e.g., 0.0 to 0.02) to give you the fine-tuning needed to correct for precision differences on those devices.

   How to Use:

1. For Presets: When you load an old preset, it will use your platform's default range. When you save a new preset, your custom min/max range values are saved with it.

2. For Tweaking: If you find a "sweet spot" for feedback, you can use the range spinboxes to "zoom in" in that area. For example, setting the range to 0.01 and 0.02 will make the entire "Amount" slider only move between those two values, giving you extremely precise control.

   Automatic Clamping: If you change the range, the "Amount" value will automatically be clamped to fit inside it. For example, if "Amount" is 0.05 and you set the "Feedback Range" min to 0.07, the "Amount" will instantly jump to 0.07.

• Seamless Tiling: When checked, the image wraps around the edges for an infinite scrolling effect.

• Reset on Drag: When checked, the pattern will perform a "Soft Reset" every time you release the mouse button after dragging.

Transforms

These controls allow for precise, non-mouse adjustments.

• Pre-Transforms: Affect the coordinate space before the fractal math is applied.

• Post-Transforms: Affect the final image after the fractal math.

• The "Move" checkboxes in this area select these layers for mouse-drag control.

Wave Controls

These two sections (A and B) appear when "Wave" is selected in the corresponding Variation dropdown.

• Frequency: The number of waves.

• Amplitude: The intensity or height of the waves.

• Speed: The speed and direction of the wave animation.

Color Grading

These controls are applied to the final image to boost the colors.

• Brightness: Adjusts the overall lightness and darkness.

• Contrast: Increases or decreases the difference between light and dark areas.

• Saturation: Adjusts the intensity of the colors, from grayscale to vivid.

Exploring Fractals in 3D

You can now view and manipulate your fractal creations on different 3D shapes!

Activating 3D View

• Simply check the "3D View" checkbox at the top of the controls. This will switch the main display from the 2D fractal to the 3D object.

• Uncheck the box to return to the 2D view.

Shape & Appearance

• 3D Shape: Use the dropdown menu in the "3D Shape" section to choose the object your fractal is mapped onto (Sphere, Cube, Quad, Prism, Torus).

• Normal Strength: This slider controls how "bumpy" the fractal looks on the 3D surface. Higher values create deeper-looking details.

💡 Lighting Controls

Adjust how the 3D shape is lit:

• Light X/Y Angle: Rotate the main light source horizontally (Y Angle) and vertically (X Angle) to change where highlights and shadows fall.

• Light Power: Controls the brightness of the light.

• Color Picker: Changes the color tint of the light.

• Enable Shadows: Toggles the shadows cast by the light and the subtle ambient occlusion effect (darkening in crevices) on or off.

🎥 Camera Controls

Adjust your view of the 3D object:

• Cam Distance: Zooms the camera in or out from the object.

• Cam X Rotate: Tilts the camera up or down.

• Cam Y Rotate: Orbits the camera left or right around the object.

• Cam FOV (Field of View): Adjusts the camera lens angle, making the view wider or narrower (like a wide-angle or telephoto lens).

🖼️ Background Options

• 2D Background: When checked, the live 2D fractal view will be displayed behind the 3D object (make sure the 3D viewport's background is transparent). When unchecked, the background will be a solid gray color.

💾 Saving

• When you are in 3D View, pressing the Save Image button will now save what you currently see in the 3D viewport.

• If the "2D Background" option is checked, the saved image will include the 2D fractal behind the 3D object.

• If you switch back to 2D View, the Save Image button will save the high-resolution 2D fractal as before.

Saving Your Image

• Resolution Dropdown: Select the resolution for your saved image (from 1K to 8K).

• Save Image Button: Opens a file dialog to save the current visual as a high-resolution PNG file. The filename will default to the current date and time.

Tips for MAC users

After downloading the Fractility app and unzipping, move to Applications folder (replace older version if you have an existing version installed).

Open Fractility app and you will receive a warning saying "Fractility" Not Opened. Apple could not verify “Fractility” is free of malware that may harm your Mac or compromise your privacy. 

Click "Done" and open your system Settings.

Go to "Privacy & Security" and scroll all the way to the bottom.

You should see a message saying that "Fractility" was blocked to protect your Mac.

Click the "Open Anyway" button.

A message appears saying Open "Fractility". Apple is not able to verify that it is free from malware that could harm your Mac or compromise your privacy. Don’t open this unless you are certain it is from a trustworthy source.

Click the "Open Anyway" button.

You should then see another message saying Privacy & Security. You are attempting to open an app that may cause harm to your Mac or compromise your privacy. An Administrator’s Touch ID or password is required to allow this.

Use Touch ID, or click "Use Password…" and enter your system password.

Fractility will now open and you can use it to create.

Please note: You will have to follow these procedures each time you install Fractility on Mac.

List of changes 

10-27-25 V1.4 Features ---Implemented 3D mesh objects --- Implemented GPU-based normal map generation. --- Added 3D light controls (rotation, energy, color, shadows).---Added 3D camera controls (distance, rotation, FOV). --- Added option to show the 2D fractal as a background in 3D view. ---Added SpinBoxes to 3D UI controls
------------------------
10-23-25 V1.3 After talking to my wife Dawn about my program  she helped me come up with a new idea to help with the feedback issue. I have added Feedback Range (Min and Max) sliders. These spinboxes directly control the minimum and maximum values of the "Feedback Amount" slider above them which should really help where the feedback make a "muddy" image. While I was working on feedback I also fixed the sliders to work how they should ... Before they worked in reverse 1 = nothing .99 get feedback. Now 0 = nothing and .1 get feedback. Unfortunately This will break any old presets you may have. But by default you should still get some image back even if it is not exact.... Play with the new spin boxes. I have also added 10 new rep-tile variations that can be found under the type dropdown. They are T-tetromino, Sierpinski Carpet, Gosper Island, Carpet (Corners), Carpet (Cross), Pentagonal Tile, Diagonal Carpet, Penrose Star, Hex Tile, and Twindragon Tile

------------------------

10-22-25 V1.2 There were 2 additions to the Rep-Tile variation Sphinx and a Custom 2x2 with variables. 

------------------------

10-21-25 V1.1 Started adding Rep-Tile variations starting with L-tromino. Added Trigonometric variations ArcTangent, Cosine, Hyperbolic Cosine, Hyperbolic Sine, and Tangent. 

------------------------

10-20-25 V1.0 added version number to UI and preset. Added new Apollonian variation that is based on apollonian gasket but it is different. 

------------------------

10-19-25 V0.94 Added preset/parameter file/clipboard export/import.  See the bottom of the ui screen.  Please note clipboard options are disabled on web due to security restrictions by itch.io . 

------------------------

10-16-25  V0.8 Added image loading and Perlin noise for background images.

------------------------

10-12-25 added mobius variation and bug fixes with circle pattern. 

------------------------

10-10-25 Added X/Y mirror and kaleidoscope variations. 

------------------------

10-8-25 Improved color grading so it does not iterate. Added mirror and kaleidoscope options . Changed the UI dock, should work better with with mobile and Mac. I know it may be a little to big now but would rather it be to big than to small.