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