

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

The current version of the application is developed using liblua-5.1.1,
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.





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.

- When using the directory browser to look at images with the right mouse
  button, the window can be resized to the original image size with the F2 key,
  and to the previous size with the F1 key.  The escape key closes the window.

- The main viewer (not the preview) image size can be adjusted using the F3
  and F4 keys, or by resizing the window with the mouse.  The escape key closes
  the window.

- The image as displayed in the main viewer can be saved to a png file by
  pressing the F5 key.

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

- The backtick key "`" will hide and show the main viewer.

- Pressing control+return in the script editing window will execute the current
  script.



Common problems while building

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


- Another common problem people have when building occurs because they have an
  older version of libflam3.a which was installed on their system by the
  electricsheep package, and the qmake setup is configured to include these
  files first.  The error looks something like this:

.obj/mainwindow.o: In function `MainWindow::fieldEditedAction()':
/tmp/qosmic/src/mainwindow.cpp:977: undefined reference to `gaussian_filter'
/tmp/qosmic/src/mainwindow.cpp:980: undefined reference to `hermite_filter'

 The qosmic archive contains a more recent version of libflam3, so the easiest
 way to deal with this is to remove the older libflam3.a and it's header
 files, compile qosmic, and then reinstall the electricsheep package if
 necessary.


- 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 neccessary 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 depending on how your distribution
  installed Lua.



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.

