================================================================================ Qosmic - A cosmic recursive flame fractal editor.
This software is licensed under the GPL. You should have access to the source code; see http://www.fsf.org/licenses/gpl.html.
This is free software to edit and render flam3 fractals as described on http://flam3.com. The software links with and uses the flam3 libraries described there. This software can be used to create content for the electricsheep screensaver as described on http://electricsheep.org.
================================================================================
Building
Before building you will need to satisfy the library dependencies. Version 2.0.0 of the application is compatible with Qt 5.5, flam3 3.1.1, and Lua 5.2.2. Versions of flam3 < 3.1.1 are not compatible with this version of the application.
Version 2.0.0 of Qosmic was developed and tested using:
Qt-5.5 (http://qt.io/) Lua-5.2.2 (http://www.lua.org/) flam3-3.1.1 (https://github.com/scottdraves/flam3) libxml2-2.9.1 (http://www.xmlsoft.org/) libpng-1.6.8 (http://www.libpng.org/) jpeg-8c (http://www.ijg.org/)
================================================================================
Using the Editor
The interface is heavily mouse driven relying on either a click and drag motion or the mouse wheel for many controls. If you've used Apophysis, then some things about the editor should seem familiar. The main components consist of the triangle editor, the dock widgets, and the viewers. The triangle editor allows you to select and manipulate an xform element within a genome. The dock widgets contain controls elements that will adjust some property of the current genome or the currently selected triangle. The viewers display the current flam3 image.
Viewers:
There are three different windows that display flam3 images.
The preview widget is updated with a new image every time a setting is changed. It's generally smaller than the main viewer. This widget also has control elements bound to the mouse wheel and buttons. You may drag the preview image using the left mouse button to set the camera view. The scale can be set using the mouse wheel or by holding control with a click and drag motion. The right mouse button displays a popup menu where the preview image quality can be selected. The quality settings displayed in the popup menu can be changed using the viewer presets widget. The viewer presets widget can be accessed by clicking the wrench icon button in the image settings widget.
The main viewer displays the same image as the preview widget, but it's updated less frequently, and it's usually larger with higher image quality settings showing more detail. Updating of the main viewer can be disabled by closing it. The image quality for the main viewer can be set by using the mouse button bound to the popup menu here as well.
The third viewer is the one displayed when using the directory browser to view flam3 image (png) files by right clicking on the file. This only works when browsing directories using the 'Short View' mode. If you right click on a flam3 file, the directory browser will try to load a png image having the same name as the flam3 file. The key bindings for this viewer are the same as for the main viewer.
Selection:
There is a selection box in the triangle editor. By clicking in the editor with the control key held and dragging the mouse you can select a subset of triangles. When the selection is active all transformations are performed on the selection and its triangles. Hold the control key and single click in the editor without moving the mouse to disable the selection. Holding the control+shifts keys while selecting triangles or nodes will add them to the selection.
Undo/Redo:
There is a fifty level undo feature, and each genome has its own set of undo states. The current state can be added to the list of undo states by either clicking undo, or by pressing the control+spacebar keys. When a flam3 file is loaded the list undo states is cleared, and a new state is automatically added.
The figure editor and most of the widgets will also add states to the undo ring when you use them with the mouse. In general, if you can change something by clicking and dragging it, then it can be undone. The undo state is typically added when the mouse button is released. Changes using the mouse wheel aren't always saved on the undo stack.
An undo state is added at the current undo position, and higher positions are removed. This means that if you click undo and hit control+spacebar, then you will no longer be able to redo to where you were. There will be two versions of the current state available, and you are seeing the most recent state.
Here are some more hints:
Use lower quality settings until you get the image you want, then render your final image using higher quality settings if necessary.
Use viewer presets to quickly switch between different image quality settings.
Use scale and quality instead of zoom to gain more control over image quality and rendering times. Zoom changes both of these values at the same time. The flam3 developers suggest leaving zoom at zero since the electricsheep server will convert any sheep submitted to have a zoom of zero.
The mouse wheel can be used to modify the real editable values in the spin box control elements and also in the variations table. Holding shift scales by 1/10, and holding control scales by 10. The '[' and ']' keys will multiply and divide the default increment value by 10. These values can also be changed using the mouse to clicking on the spinbox arrows and moving the mouse up and down.
When focused on a spinbox, pressing Control+ will increase the number of decimal places shown, and Control- will decrease the number to at least one.
When focused on a spinbox, pressing return will update the preview using the current values.
The '\' key will globally disable automatic preview and viewer image updating when changing a spinbox value using the mouse wheel.
The maximum size of the preview image when docked can be set by sizing the preview when it is not docked.
Use the genome selector to view the current set of flam3 images and to select the current genome. There is always at least one genome in the set, and you can add a genome by importing it.
If a png file having the same base name as a flam3 file exists in the same directory as the flam3 file, the directory browser will generate an icon preview image and store it in the $HOME/.qosmic/icons cache. The icons directory cache is needed since scaling many image files can take a while.
When using the directory browser for the first time to view a directory containing flam3 files, the browser tries to find and generate icon sized preview images for each file. This may take a while if you have many flam3 files with corresponding images.
When the directory browser is in 'Short View' mode, using the right mouse button in the directory browser displays the image for a flam3 file if one exists. The middle mouse button toggles hidden files. Double clicking a file with the left mouse button loads the selected flam3 file, and holding the control key will append the genomes in selected flam3 file to the current set. Holding the control key while using the mouse wheel will change the size of any flam3 file icons displayed.
Add, duplicate, and remove triangles using the menu shown by holding the right mouse button in the editor. You can select a triangle by positioning the pointer over it when activating the menu.
The mouse wheel will rotate a triangle in the editor. Holding shift will rotate it less.
The mouse wheel with the control held will scale a triangle. Holding shift will scale less.
Using the mouse wheel while over the basis triangle will scale the editor view. Holding shift will scale less.
Hold the shift key and use the left mouse button to place the rotate/scale axes marker. The marker can be enabled in the by selecting 'mark' in the axis selection menu located below the triangle editor.
Closing the main preview, viewer, genome selector, and mutations windows will prevent their previews from updating.
The left mouse button in the mutations window selects the 'A' genome shown in the top left box. The right mouse button in the mutations window selects the 'B' genome shown in the top right box.
The middle mouse button in the mutations window copies the genome to the currently selected genomes list item.
There is drag and drop enabled for a few of the widgets. You can drag and drop items between the mutations widget and the genome selector. You can drag files from the directory browser into the genome selector. You can also drag items into the main viewer from the mutations and the genome selector widgets.
GIMP gradient files (.ggr) and CPT gradient files (.cpt) can be loaded in the palette widget. Select a directory containing your gradient files using the tool button in the browse tab. Then select a gradient from the gradients scroll list.
You can set the genome displayed at start-up by using the autosave feature. The autosave can be configured by clicking the wrench icon on the select genome widget. When enabled, this feature will save the current set of genomes to a file called '$HOME/.qosmic/autosave.flam3'. The autosave file can be updated when quitting the application or whenever an undo state is created.
Use the selection to simultaneously move, copy, and edit multiple triangles.
The density widget can be used to merge two different genomes in the current genome set. Use the star button in the density widget to apply the density settings of the second genome. Triangles is the second genome having a density of zero are not included when density settings are applied.
================================================================================
Keys
The main window and its dock widgets have the following bindings
F1 - Select the previous triangle F2 - Select the next triangle F3, Ctrl+Z, Ctrl+; - Undo F4, Shift+Ctrl+Z, Shift+Ctrl+; - Redo ;, Z - Scale the triangle editor scene in Shift+;, Shift+Z - Scale the triangle editor scene out Ctrl+Space - Push the current state onto the undo stack
Ctrl+A - Autoscale the figure editor Ctrl+K - Stop rendering Ctrl+R - Create a random genome Ctrl+N - Create a new default flame Ctrl+O - Open a flam3 file Ctrl+S - Save the current flame to a flam3 file Ctrl+I - Save an image of the current flame Ctrl+P - Quicksave the current flame and an image Ctrl+Q - Quit
Alt+1 - Select triangle 1 Alt+2 - Select triangle 2 Alt+3 - Select triangle 3 Alt+4 - Select triangle 4 Alt+5 - Select triangle 5 Alt+6 - Select triangle 6 Alt+7 - Select triangle 7 Alt+8 - Select triangle 8 Alt+9 - Select triangle 9
The following keys are bound when focused on a spinbox
[ - Increase the wheel or drag multiplier by ten ] - Decrease the wheel or drag multiplier by ten Ctrl+Shift+= - Increase the number of decimal places by one Ctrl+- - Decrease the number of decimal places by one Up - Increase the value by the current multiplier Down - Decrease the value by the current multiplier Return - Update the preview
When the triangle editor is focused the following keys are bound
Ctrl+LeftMouseButton+Drag - Enable the selection Ctrl+LeftMouseButton+NoDrag - Disable the selection
LeftMouseButton(on empty space)+Drag - Scroll the editor scene MiddleMouseButton+Drag - Scroll the editor scene Ctrl+MiddleMouseButton+Drag - Zoom the editor scene in/out Shift+LeftMouseButton - Place the coordinate mark if visible
Main viewer bindings (including the directory list image viewer)
F5 - Decrease the image size F6 - Increase the image size F7 - Scale the image to the previous size F8 - Scale the image to its original size F9 - Save the currently displayed image Esc - Close/Hide the viewer
Bindings for the script editor
Ctrl+1 - Open a script file Ctrl+2 - Save the current script Ctrl+3 - Save the script with a new name Ctrl+/, Ctrl+L - Comment a single line or selection Ctrl+?, Ctrl+Shift+L - Uncomment a single line or selection Tab - Indent the selection, otherwise tab Ctrl+Tab - Unindent the selection, otherwise tab Ctrl+Return - Run the current script
================================================================================
Thanks to:
Scott Draves for his flam3 library
Erik Reckase for his work on the flam3 library
Mark James for his Silk icon set http://www.famfamfam.com/lab/icons/silk/
The Apophysis developers for their interface design