================================================================================
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.  Currently,
version 1.4.8 of the application is compatible with versions of Qt4 >= 4.5 and
of Lua >= 5.1.  Versions of flam3 >= 2.8 are not compatible with this version
of the application.  Version 1.4.8 of Qosmic was developed and tested using:

Qt-4.6.0     (http://www.trolltech.com/)
liblua-5.1.4 (http://www.lua.org/)
flam3-2.7.18 (http://flam3.com/)

flam3 dependencies:
libxml2-2.7.3 (http://www.xmlsoft.org/)
libjpeg-7    (http://www.ijg.org/)

1. Download and unpack the source archive, and cd into the source directory.
2. Edit qosmic.pro to configure the qmake build system to suit your environment.
3. Run the ./build.sh script
4. Run ./qosmic when the build finishes.

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

Using the Editor

The best way to begin is by playing with it.  The interface is heavily mouse
driven, and it relies on 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 control elements which can adjust some
property of the current genome.  Some control elements are bound to properties
of 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 while moving the mouse.
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 main viewer has the same image as the preview widget, but it's updated less
frequently, and it's usually larger so more detail can be seen.  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.  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 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 shift key while
selecting triangles or nodes will add them to the selection.


Undo/Redo:

There is a fifty level undo feature.  The current state can be added to the list
of undo states by either clicking undo, or by pressing the control+spacebar.
When a flam3 file is loaded the list is cleared, and a new state is
automatically added to the head of the ring.

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 saved on the undo stack.

An undo state is added at the current undo position, and higher positions are
forgotten.  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 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.

- 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 a folder called .icons.  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, so this may take a while if you have many
  flam3 files.

- 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.
  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.

- Holding the control key while using the mouse wheel will also change the size
  of the previews displayed in the genomes widgets.  Holding control+shift will
  change only the width of the previews.

- 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 middle mouse button to place the rotate/scale
  origin marker.  The  marker can be enabled in the by selecting 'mark' in the
  'Center On' group of the 'Edit Triangle' window.

- Closing the preview, viewer, and mutations windows will prevent them from
  updating.

- The left mouse button in the mutations window selects a genome and moves it
  to the first box.

- The middle mouse button in the mutations window copies the genome from the
  editor to the first box.

- The right mouse button in the mutations window copies the genome to the
  editor.

- 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 saving to a file called
  '.qosmic.flam3' in your home directory.

- Use viewer presets to quickly switch between different image quality settings.

- The maximum size of the preview image when docked can be set by sizing the
  preview when it is not docked.

- Use the selection to simultaneously move and edit multiple triangles.

- Use the genomes widget to view the current set 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.

- 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



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

MiddleMouseButton+Drag      - Scroll the editor scene
Ctrl+MiddleMouseButton+Drag - Zoom the editor scene in/out
Shift+MiddleMouseButton     - 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+4, 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

- 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 2.  See the COPYING file
for details.  Questions, concerns, suggestions, bug reports, and patches
can be sent to bitsed(at)gmail.com.
================================================================================
