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

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/)
libxml2         (http://www.xmlsoft.org/)
libjpeg         (http://www.ijg.org/)
flam3 >= 2.7.11 (http://flam3.com/)

The current version of the application is developed using qt-x11-4.3.4,
flam3-2.7.11, liblua-5.1.2, libxml2-2.6.30, 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

There is currently no manual.  My advice is to play around with it.  The
interface is heavily mouse driven, and it relies on the mouse wheel for many
controls.  Here are some hints:

- Set the final image size first.

- Use lower quality settings until you get the image you want.

- You can double the scale and decrease the zoom by 1 to reduce the rendering
  time.

- The mouse wheel can be used to modify the real editable values in the
  spin boxes and 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.

- When focused on a spin box, pressing the space bar or return will render the
  preview using the current values.  Some spin boxes do not automatically
  update the preview when you change their values, so you must press the
  space bar when changing the value.  This is the case for all of the editable
  spin box fields in both the camera and image settings.  This allows the you
  to change more than one camera/image setting before rendering a preview.

- 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 left mouse button in the directory browser displays the image for a
  flam3 file if one exists.  The middle mouse button refreshes the listing.

- Add and remove triangles using the menu shown by holding the right mouse
  button in the editor.

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

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

- When setting a triangle's color using the gradient in the color
  selector, the main viewer is updated when the mouse button is released.

- 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 the viewer presets to quickly switch between final image sizes and image
  quality settings.

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

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

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 - Show/Hide the main viewer

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 files
Ctrl+Q  - Quit



Main viewer bindings (including the directory list image viewer)

F5  - Scale the image to the previous size
F6  - Scale the image to its original size
F7  - Decrease the image size
F8  - Increase the image size
F9  - Save the currently displayed image
Esc - Close / Hide the viewer



Bindings for the script editor

Alt+1               - Open a script file
Alt+2               - Save the current script
Alt+3               - Save the script with a new name
Alt+4, Ctrl+L       - Comment a single line or selection
Alt+$, 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


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

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

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/lau5.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
in 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, and positive feedback can be
sent to bitsed(at)u.washington.edu.

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