================================================================================
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 install the prerequisite libraries.  Version
1.6.0 of the application is compatible with Qt 5.5, flam3 3.1.1, and Lua 5.2.4.
Versions of flam3 < 3.1.1 are not compatible with this version of the
application.

Version 1.6.0 of Qosmic was developed and tested using:

Qt-5.5.1            (http://www.qt.io/)
Lua-5.2.4           (http://www.lua.org/)
flam3-3.1.1         (http://flam3.com/)
libxml2-2.9.3       (http://www.xmlsoft.org/)
libpng-1.6.19       (http://www.libpng.org/)
libjpeg-turbo-1.4.2 (http://libjpeg-turbo.virtualgl.org/)


1. Install prerequisite libraries listed above.
2. Download and unpack the source archive, and cd into the source directory.
3. Edit qosmic.pro to select qmake options appropriate for your system.
4. Run qmake
5. Run make
6. Run ./qosmic when the build finishes.

================================================================================

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 key, wheel, or drag multiplier by ten
]            - Decrease the key, 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



The following keys are bound when focused on a variation value editor

[            - Increase the key or drag multiplier by ten
]            - Decrease the key or drag multiplier by ten
Ctrl+Shift+= - Increase the number of decimal places by one
Ctrl+-       - Decrease the number of decimal places by one
Alt+Up       - Increase the value by the current multiplier
Ctrl+Up      - Increase the value by the current multiplier*10
Shift+Up     - Increase the value by the current multiplier/10
Alt+Down     - Decrease the value by the current multiplier
Ctrl+Down    - Decrease the value by the current multiplier*10
Shift+Down   - Decrease the value by the current multiplier/10
Up           - Move up
Down         - Move down
Right        - Move right or expand tree
Left         - Move left or collapse tree
Space        - Edit the variation value
Delete       - Set the value to zero
Backspace    - Set the value to zero
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


This program is licensed under the GNU GPL Version 3.  See the COPYING file
for details.  Questions, concerns, suggestions, bug reports, and patches
can be sent to bitsed(at)gmail.com.
================================================================================