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

Building

Before building, you will need to have the following libraries installed on
your system:

Qt >=4.3.1      (http://www.trolltech.com/)
liblua          (http://www.lua.org/)
flam3 >= 2.7.17 (http://flam3.com/)

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

The current version of the application is developed using
qt-x11-opensource-4.5, flam3-2.7.18, liblua-5.1.3, libxml2-2.7.3, and
libjpeg-6b.

The application is also reported to build using the qt-copy patches from the
kdesvn server.

1. Download the source tar file using the link below, and unpack it.
2. Change into the qosmic directory and type ./build.sh
3. Type ./qosmic when the build process finishes.

If you have problems, then read the section below about common problems
building.
================================================================================

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 maniplate 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 files by right clicking on the file.  The key bindings here 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.


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 top of the stack.  Pressing the control+spacebar and
immediately clicking undo will add the current state once.

The figure editor and most of the widgets will also add states to the undo stack
when you use them with the mouse.  In general, if you can change something by
clicking and dragging it, then it can be undone.  Changes using the mouse wheel
are'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.

- 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 spin box, pressing return will update the preview using the
  current values.

- The '\' key will globally disable automatic preview and viewer image updating
  when changing a spin box 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 refreshes the listing.
  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.

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

- 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

There are a few key bindings used in different places.  Some of them don't have
a clickable tool icon.

The main window 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
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 flam3 file
Ctrl+Q  - Quit



When the triangle editor is focused the following keys are bound

PageUp,   ;       - Scale the scene in
PageDown, Shift+; - Scale the scene out

Ctrl+LeftMouseButton - Enable/disable the selection



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 - Un-comment a single line or selection
Tab                  - Indent the selection, otherwise tab
Ctrl+Tab             - Un-indent the selection, otherwise tab
Ctrl+Return          - Run the current script
================================================================================

Common problems while building/running


All of the building controls are contained in qosmic.pro.  To resolve a compile
error you should only need to edit qosmic.pro and run 'qmake && make' (assuming
that all of the required libraries are installed).

The qosmic.pro file is setup to use pkg-config by default.  If you don't have
pkg-config, or if it doesn't work on your system, then you'll need to edit the
qosmic.pro file to set the required library and include paths.  There are some
lines in the file that should need only some minor path changes for this to set
these for your system.

Many linux packaging systems will store the header files for libraries in
another package which are 'dev' packages (ie qt-4.3.1-dev.rpm).  These header
files are needed to build qosmic, so make sure the dev packages for the
libraries listed above are installed if they exist.

When using Debian Sid one must manually link qmake correctly against qmake-qt4
before compiling.  This may be a problem on other systems as well, so make sure
the qmake in your path is the one installed by Qt4.  You can run the following
command to relink qmake on Debian Sid before running build.sh.

$ sudo update-alternatives --config qmake


For the Lua dependency it may be necessary to adjust the include list in
qosmic.pro so the liblua header files can be found.  You may need to add
/usr/include/lua5.1 to the INCLUDEPATH variable.  You may also need to change
-llua in the LIBS variable to -llua5.1 and/or add the path of the library file
to the LIBS variable using the '-L/path/to liblua.so/' option depending on how
your distribution installed Lua.

Setting the system specific locations of libraries and their header files can be
a problem with any of the required dependencies.  The instructions for finding
the Lua libraries can also be used to find any other library's install points
(ie flam3).  Looking in qosmic.pro you'll notice that the INCLUDEPATH lists
/usr/include/libxml2 which is where the libxml2 header files are located on my
system.

If you see an error about qosmic being unable to find the flam3-palettes.xml
file, then you need to adjust the FLAM3_PALETTES variable in qosmic.pro so that
it points at the directory where flam3 installed this file.  Alternatively, you
can use the environment variable 'flam3_palettes' to do this.  Type './qosmic
--help' to see a list of supported environment variables.
================================================================================

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