1EVOLVOTRON USER MANUAL 2====================== 3 4Evolvotron is interactive "generative art" software to evolve 5images/textures/patterns through an iterative process of random 6mutation and user-selection driven evolution. 7 8On starting the application, a grid of images is displayed. 9Resize or maximise the application if you like, but the more 10pixels have to be calculated, the slower it will be. 11(For the default 2D image mode, you will need a fast machine or patience. 12For the optional animation mode, you will need both.) 13 14Simply repeat the following until bored: 15 - Click (singleclick) on an image you like to 16 spawn the next generation of its mutant offspring. 17 - Wait until variations on it are regenerated in sufficient 18 detail that you can decide which one you like best again. 19 20IMPORTANT: Initially you should select images with some sort of variation. 21If you select a uniform image, you may get stuck in a degenerate zone with 22little to mutate and therefore little chance of escape to more interesting 23images. You can always reset/restart from the "File" menu (the difference is 24that "reset" also resets the mutation parameters to their default values). 25Selecting one of the "warp" options from a context menu (right-click on 26an image) can also help by introducing an additional opportunity for 27mutation on subsequent spawns. 28 29Note that various spirals, grids and tiles, although complex looking, 30are actually implemented by a single function node and may leave you stuck too. 31 32COMMAND LINE OPTIONS 33==================== 34The following are equivalent: 35 - evolvotron --grid 12x8 36 - evolvotron --grid=12x8 37 - evolvotron -g 12x8 38 39GENERAL OPTIONS 40--------------- 41 42 -a, --autocool 43 Enable autocooling by default, and cause resets of mutation 44 parameters to re-enable autocooling if it was disabled. 45 46 -F, --fullscreen 47 Start in "fullscreen" mode (NB for Qt on X11 this means 48 a screen-filling borderless/undecorated window is used; 49 it's not simply maximising the window, and it's not the 50 sort of framebuffer hijacking used by SDL games). The Qt 51 documentation claims some window managers may not be entirely 52 cooperative with this (in which case sorry, you're on your own). 53 evolvotron actions which bring up dialog boxes (e.g save) seem 54 to generally behave fairly sensibly but child windows 55 (e.g enlargements or dialogs) can show some "interesting" behaviour. 56 Fullscreen mode can be toggled within the application using "F" key. 57 The "Esc" key will also exit it. 58 59 -g, --grid <cols>x<rows> 60 Sets size of the grid of image display cells in the main application area (defaults to 5x6) 61 62 -h, --help 63 Print summary of command line options and exit. 64 65 -j, --jitter 66 Enable sample jittering. Samples will be made at a random position 67 within a pixel instead of on a regular grid, providing some antialiasing. 68 69 -m, --multisample <multisample grid> 70 Enables additional antialiasing passes. 71 Specifying 2 or 3 will provide an additional pass with 2x2 or 3x3 samples per pixel. 72 Specifying 4 (or higher) will provide a 2x2 and a final 4x4 pass. 73 Specifying 1 provides the default behaviour of one sample per pixel. 74 For best rendering quality also specify -j. 75 76 -M, --menuhide 77 Start with menu and status bar hidden. Nice with --fullscreen. 78 Hiding can be toggled within the application using ctrl-m. 79 The Esc key will also bring them back. 80 81 -p, --spheremap 82 Images are produced by sampling the underlying 3D function on the 83 latitude-longitude grid of a sphere. The resulting images should be 84 usable as spheremaps/spherical environment maps. Animations vary 85 the radius of the sphere. NB when in spheremap mode, 86 middle mouse button adjustments do not yet behave like you'd expect. 87 88 -S, --startup <function_filename> 89 Specify a function filename (evolvotron's XML format) to load on startup 90 (or reset). The option can be provided multiple times, and this is 91 also the interpretation of any positional arguments. Startup functions 92 are placed in the grid from left to right, top to bottom. 93 94 -U, --shuffle 95 Use in conjunction with -S / --startup options, to display the specified 96 functions in random order, both on application startup and on each 97 reset of the application. 98 99ANIMATION OPTIONS 100----------------- 101 102 -f, --frames <frames> 103 Number of frames in animations (defaults to 1 i.e no animation) 104 105 -l, --linear 106 Vary z linearly with time rather than sinusoidally. 107 Sinusoidal variation generally looks better when animations are "bounced" 108 forwards and backwards, but this option is useful when generating slices to 109 use as volumetric textures. 110 111 -s, --fps <framerate> 112 Rate at which frames are displayed per second (integer). (Defaults to 8). 113 114POWER-USER & DEBUG OPTIONS 115-------------------------- 116 117Note that the usual Qt/X11 options 118(for example, -geometry <width>x<height> option to set on-screen size in pixels) 119are processed and removed before evolvotron options are checked. 120 121 -D, --debug 122 Puts the certain aspects of the app into a more debug oriented mode. 123 Currently (ie this may change) it simply changes function weightings 124 so virtually all function nodes are FunctionNoiseOneChannel. By itself 125 this is a pretty pointless thing to do, but in conjunction with the -X 126 options it's useful for examining the behaviour of specific functions. 127 128 -E, --enlargement-threadpool 129 Use a separate thread pool for computing enlargements. 130 Using this option ensures computation of enlargements 131 continue to make some progress even while the main grid 132 is being actively worked on. However, this will be at 133 the expense of main grid rendering performance. 134 Without this option, enlargements' final high-resolution 135 renderings are invariably lower priority than computation 136 for images in the main grid. 137 See also the -N option to control the priority of threads 138 in this pool. 139 140 -n, --nice <niceness> 141 Sets additional niceness (relative to the main application thread) 142 of the compute (rendering) thread(s). 143 It's useful to run compute threads at a slightly lower priority 144 ("nice 4" is the default without this option) than the main (GUI) 145 part of the program (but note that this means other normal/lowish 146 priority tasks running on your machine may slow evolvotron down 147 a bit more than expected). 148 149 -N, --Nice <enlargement niceness> 150 Sets additional niceness (relative to the main application thread) 151 of the compute thread(s) computing enlargements (default value is 8). 152 Only effective in conjunction with -E option. 153 154 -t, --threads <threads> 155 Sets number of compute threads. 156 If this is not specified, then as many compute threads are created 157 as there are processors on the system (unless this cannot be 158 discovered in which case only a single compute thread is created). 159 Non-linux builds will likely not include code to determine processor count 160 (suitable patches gratefully received). 161 162 -u, --unwrapped 163 Modifies -F behaviour so that the specified "favourite" function 164 is NOT wrapped by space/colour transforms. NB For functions without leaf nodes 165 or parameters (e.g FunctionSphericalToCartesian) this doesn't 166 leave any scope for variation or future mutation. 167 Function name recognition is case sensitive. 168 Example: 169 $ evolvotron -F FunctionKaleidoscope -u 170 171 -v, --verbose 172 Verbose mode, writes various things to application stderr. 173 This is primarily intended to assist debugging. 174 This option used to be useful for getting a list of supported function 175 names for use with the -F option, but those can also be inspected 176 via the Settings dialogs. 177 178 -x, --favourite <functionname> 179 Force a specific "favourite" function type to be used at the top level 180 of all function trees. The specified function is still wrapped 181 by spatial and colour warping functions which may disguise 182 it considerably. A list of all the function names understood 183 by evolvotron is output during app startup when the -v option 184 is specified. Function name recognition is case sensitive. 185 Example: 186 $ evolvotron -F FunctionSpiralLinear 187 188MOUSE CONTROL 189============= 190 191LEFT-CLICK 192---------- 193A left-click on an image in the main window spawns the mutant offspring 194of that image to all the other (non-locked) displays in the grid. 195 196RIGHT-CLICK CONTEXT MENU 197------------------------ 198Right clicking on an image gets you a few more options: 199 200 - "Respawn" regenerates just the current image from whatever it was 201 spawned from (and using recolour or warp, if that's what was used 202 to produce it). 203 The main use of this is to make your grid of images look nice 204 for screendumps, by regenerating any which aren't up to scratch. 205 NB May not work as expected after an "undo". 206 207 - "Spawn" is the same as clicking an image. It generates mutated 208 images to all unlocked images in the grid. 209 210 - "Recolour" to produce different coloured variants of the selected image 211 212 - "Warp"'s sub-options produce variants of the image which have been 213 zoomed/rotated/panned. 214 215 - "Lock" to prevent an image from being overwritten by spawns from other 216 images (select again to toggle). 217 218 - "Enlarge" to produce a blow-up of the image in a single window. 219 Submenu items select either a freely resizable window or 220 a scrollable view of a fixed size image. 221 If the application is running in fullscreen mode (NB this is 222 NOT the same as a simply "maximised" window) then the enlarged 223 image will also be fullscreen (the "Resizeable" mode is probably 224 what you want in this case as the image will automatically be 225 rendered at the correct resolution). 226 227 - "Save image" to save the image in a file (.ppm or .png). 228 You generally want to save an enlarged image: if you 229 save a small image from the grid, the size you see on the screen 230 is the size you get in the file. Save isn't allowed until the 231 full resolution image has been generated; if you try to save too 232 early a dialog box will be displayed telling you to try again later. 233 234 - "Save function" to store the function to an XML file. 235 236 - "Load function" to load a stored function from an XML file. 237 NB if the file was saved from a different version numbered 238 evolvotron, a warning message will be generated. 239 Save/load of functions is an experimental feature and you should 240 not count on future versions of evolvotron being able to load 241 files saved from old versions, or producing the same image 242 from a loaded function. Attempting to load functions from later 243 versions into earlier versions is even less likely to succeed. 244 245 - "Simplify" prunes the function tree of redundant branches where 246 possible (the same action can be applied to all images from 247 the main "Edit" menu). This doesn't change the appearance of 248 the image, but may make it recompute faster. 249 250 - "Properties" brings up a dialog box containing some information 251 about the image (e.g the number of function nodes it contains). 252 253MIDDLE MOUSE BUTTON 254------------------- 255[NB This feature will probably only be of practical use to those with high-end machines]. 256 257You can use the middle mouse button to drag-adjust individual images. 258This is useful for "final composition" type tweaks, e.g centering an 259image's most interesting feature, or just for satisfying your curiosity 260about what's off the edge of the image. 261 262It also works on enlarged images, although it's virtually unusable without 263a bit of practice on smaller, faster ones (just boldly make the adjustment 264you want, release the button... and wait). 265 266Changes made can be rolled-back on the main Edit/Undo menu item, 267one drag-action at a time. 268 269An unmodified middle-mouse drag pans the image around following 270the mouse motion. 271 272A SHIFT-middle drag zooms the image in and out with scaling 273proportional to the distance from the centre of the image. Beware of 274generating huge zooms by clicking too near the centre of the image. 275 276An ALT-SHIFT-middle drag is similar but anisotropic: the scaling 277may be different in X and Y. Warning: this technique is very 278sensitive and can be quite tricky to use! In particular, 279if you initially click near the centre axes of the image the zoom factor 280can be HUGE, so the best way to start using this is to click about halfway 281on a diagonal between the image centre and a corner and gently move in and 282out radially. Dragging from one side of the image to the other flips it over 283(the degenerate case of infinite zoom at the centre is handled cleanly I think). 284If it all goes horribly wrong, undo and try again. 285 286A CTRL-middle drag rotates the image about its centre. 287 288A CTRL-ALT-middle drag shears the image (the best way to see what 289this does is to click in the corner of an image and move the mouse 290horizontally or vertically). 291 292KEYBOARD CONTROL 293================ 294 295There are some keyboard shortcuts. 296 297MAIN WINDOW 298----------- 299 300- "r"/"t"/"x" perform various starts of reset/restart. 301 302- "q" quits the application. 303 304- "u" (and also Ctrl-z) does an undo. 305 306- "f": full-screen mode (on X11, Qt does this by asking the 307window manager for a screen-filling undecorated window, and the 308documentation contains some dire warnings about problems with broken 309window managers). See also "-F" command line option. 310Fullscreen mode propagates to enlarged image display windows. 311NB The application may completely disappear from the screen for 312a brief interval while switching mode. 313 314- "m" : hides status and menu-bar hiding, which can be nice when 315in full-screen or window-maximised mode. See also "-M" 316command line option. Also note that while the menu bar 317is hidden, most of these keyboard shortcuts won't function 318as they're tied to the menu system. 319 320- Esc : exits full-screen and/or menu-hiding mode, putting the 321application into its normal default state. 322 323ENLARGEMENT WINDOWS 324------------------- 325The image display windows created by selecting "Enlarge" from a 326context menu also have a couple of keyboard operations: 327 328- "f" : [NB only available with fullscreen build option] toggles 329full-screen mode. When returning to normal mode, if the main app 330window was fullscreen then it will also drop back to normal mode. 331 332- Esc : [NB only available with fullscreen build option] 333completely closes a fullscreen-mode enlargement window. 334 335GUI ELEMENTS 336============ 337 338MAIN MENU BAR 339------------- 340- File menu: 341 Items to restart, reset and quit the application. 342 The difference between restart and reset is that reset 343 sets the mutation parameters back the their default values. 344 The "randomize function weights" version of restart scrambles 345 the relative probability of the various function types (if you 346 think evolvotron just keeps generating the same kinds of 347 images give it a try). The "restart with specific function" 348 item duplicates the functionality of the "-x" and "-X" command-line 349 options. 350- Edit menu: 351 "Undo" lets you undo certain actions: e.g spawn, 352 middle-button adjustment, simplification and lock/unlock. 353 There is a large but limited number of levels of undo. 354 "Simplify" is of curiosity value only: it prunes redundant 355 branches from images ("junk DNA"); this may help them recompute 356 faster but at the cost of there being less mutatable material. 357- Settings menu: 358 "Mutations" brings up a dialog to modify the amount 359 of change spawned images are subject to. 360 (See "advanced usage" below.) 361 "Functions" brings up a dialog to modify the relative probability 362 of functions being used. By default all functions are equally 363 likely except for iterative functions and fractals, which are 364 almost but not completely suppressed. But if you think there 365 are too many spirals or grids (or not enough fractals) then this 366 is the place to adjust the frequency with which they appear. 367 If the software was built with the fullscreen option, 368 that can also be controlled from this menu. 369 "Favourite" brings up a dialog which allows you to select a specific 370 function type to always be used as the root node of any new functions. 371 The function can be wrapped by some other random stuff, or unwrapped. 372 See also the -X and -x command line options. 373- Help menu: 374 Items to bring up documentation, and the usual "About" box 375 (which includes the license). 376 377STATUS BAR 378---------- 379An area on the status bar shows how many compute "tasks" are 380outstanding (or "Ready" when there are none). When two task 381totals are reported, the first is for the main grid and the 382second for any enlargements being computed. 383Each "task" is the recomputation of an image at some resolution. 384Tasks are prioritised by their number of pixels (small image 385implies higher priority). This is why, if the main grid is still 386recomputing, recalculations of enlargements will appear to freeze 387after they have reached a certain resolution, at least until other 388lower resolution tasks have completed. 389 390The status bar also provides some control over the "autocool" 391mechanism which reduces mutation strength with time. 392See the advanced usage section below. 393 394TIPS 395==== 396- Don't start a session with any preconceived ideas about the kind 397 of image you want to get out of it. You will be disappointed. 398- I get the best results when I click the image which most 399 immediately catches my eye as they start appearing. If you stop 400 to think about it too much then things seem to go downhill. 401- If you seem to be just getting the same old spirals and grids 402 all the time, stop clicking on spirals and grids! 403 (The same goes for random mush). 404- Don't get too hung up on using the warp and middle-mouse drag 405 adjustments every iteration... use those tools for final 406 polishing of your masterpiece. 407- You can quickly cycle through a lot of initial images (until 408 you find one with real potential) by bashing on Ctrl-r to 409 repeatedly restart. 410- To add variety to an image's mutations, nudge it with a small 411 middle-mouse drag. This introduces a top level transform, and 412 therefore more parameters to be varied. 413- Enlargements take a long time to complete their final 414 high-resolution rendering pass (especially with multisampling 415 enabled). Most convenient practice seems to be to go away and 416 leave them to complete, then come back and save them later. 417 Continuing to click away on the main grid effectively starves 418 them of CPU, unless the -E command-line option is used. 419 420ANIMATION 421========= 422As of version 0.2.0 evolvotron contains some experimental support 423for generation of animations (although so far the results have been 424pretty disappointing IMHO, but it's still early days). 425 426NB THIS IS EVEN MORE COMPUTATIONALLY AND MEMORY INTENSIVE THAN 427THE STATIC IMAGE MODE. 428 429Simply supply a -f <frames> command line option and evolvotron will 430generate animated sequences with the specified number of frames. 431These will be displayed at the frame rate specified by the 432optional -s <framerate> option (default 8). So "evolvotron -s 24" 433will generate 3 second long animations. Animations reverse direction 434at each end to avoid a sudden jump. 435 436If you save an animation as PPM or PNG, multiple files will 437be saved with .fnnnnnn (where nnnnnn is the zero-filled frame 438number) inserted in each filename before the filetype qualifier. 439 440For example, if you enter foo.ppm as the filename to save, 441files foo.f000000.ppm, foo.f000001.ppm... will be saved. 442If you have the ImageMagick tools you can convert these to 443an animated GIF playing at approx. 8 frames per second with: 444 445$ convert -delay 12 foo.f??????.ppm foo.gif 446 447ADVANCED USAGE 448============== 449Evolvotron's idea of an image is a function which converts 450XYZ co-ordinates to an RGB colour (however we can only display 451a 2D plane for now so the input Z is fixed to zero, or varied 452with time when animating). 453 454The image functions are constructed from trees of function nodes. 455(In the mathematical expression 1+(2*x) the "+" and the "*" would 456be function nodes.) Evolvotron's functions tend to correspond to 457geometric or colour-space operations or anything else which can be 458applied to a 3D vector. 459 460By mutating the structure of the function tree (adding random 461branches, for example) and the values of the constant embedded 462within it, the image can be changed. 463 464The mutation parameters are under control from the dialogs accessible 465via the Settings menu, and the "autocool" mechanism exposed in the 466status bar also has some influence. 467 468There are two kinds of mutation: perturbations to the magnitude of constants, 469and structural mutations which re-arrange the function tree of an image. 470Four types of structural mutations are currently implemented: 471 - replacement of a function branch by a new random stub (a "Glitch" mutation). 472 - a random shuffle of a node's sub-nodes 473 - insertion of random nodes between a node and it's sub-nodes 474 - the substitution of a node with one of a different type, 475 with sub-nodes unaffected where possible). 476 477The probability (per function node) of these mutations is controlled 478from spinboxes on the "Mutation Parameters" dialog (expressed as 479chances-in-a-hundred), as is the size of perturbations to constants. 480 481It is useful to think of the perturbations to constant parameters as 482being a thermal effect (hence the "heat" and "cool" buttons), while 483structural alterations are more drastic and are caused by high energy 484gamma rays or something (hence "irradiate" and "shield" buttons to 485adjust the probability of structural mutations). 486 487So why would you want to change the mutation parameters from the initial 488defaults ? Basically, if you're getting too much variation in spawned images 489(this tends to happen after many generations of images, by which time the 490function trees have grown quite large and therefore are experiencing a lot 491of mutations) then cool and/or shield. 492If all the images look too similar, heat and/or irradiate. 493 494The "autocool" mechanism (enabled from the statusbar or mutation parameters 495dialog) automatically reduces the strength of mutations from the base 496values with successive generations. The cooling can be cancelled by 497disabling autocooling or pressing the "Reheat" button to zero the number 498of generations counted for cooling. The effect of the cooling is a compound 499halving of the mutation strength after some number of generations (this number 500is the "half-life" controllable from the mutation parameters dialog). 501Note that if autocooling is enabled then eventually, after a number of 502iterations more than many multiples of the half-life has passes, spawned 503images will differ very little from their parents (hence the need for "reheat"). 504 505There is also a dialog accessible from "Functions..." on the "Settings" menu. 506This allows control over the relative proportions in which functions occur. 507There is a tab showing the relative weighting of all functions (log-2 scale: each 508tick halves the probability of the function occurring), and additional tabs 509for various classifications of function for quicker access. 510The "Randomize" button on each tab assigns random weightings and helps 511increase the uniqueness of your session. 512 513The "Functions" dialog also has a "Dilution" tab which allows the average 514function-tree branching ratio to be controlled (by changing the proportion 515of trivial zero-branch functions added): note that using a high branching 516ratio results in very complex images which will take a long time to compute, 517while reducing the ratio results in simple, boring images. 518 5193 types of function node are considered fundamental: constant nodes 520(which return a constant), identity nodes (which return their 521position argument) and transform nodes (which transform their position 522argument by random parameters). On the "Dilution" tab of the "Functions" 523dialog there are two slider controls to affect things related to these: 524 - "proportion constant" controls the proportion of diluting fundamental nodes 525 which are constants. Changing this from its default value of 0.5 doesn't 526 actually seem to have much effect. 527 - "proportion transforms" sets the proportion of non-constant nodes diluting 528 which are transforms (as opposed to identity nodes). 529 The main effect of this is that images are less commonly obviously centred 530 on the origin or aligned with the axes. I think this is a good thing, so 531 the value is at 1.0 by default. 532 533OTHER EXECUTABLES 534================= 535This release also builds some other command-line driven (non-GUI, non-interactive) utilities. 536Consult the man pages for full details. 537 538evolvotron_render reads a XML function description from its standard input and renders it to the 539file specified. 540 541evolvotron_mutate reads an XML function description from its standard input and outputs a mutated version. 542A command line option allows the "genesis" situation of creating a random function description with no input. 543 544EXAMPLES 545-------- 546 547Evolving and mutating on the command line: 548 549$ evolvotron_mutate -g | tee fn.xml | evolvotron_render /tmp/xxx.ppm ; display /tmp/xxx.ppm 550 551$ cat fn.xml | evolvotron_mutate | evolvotron_render -j -m 4 /tmp/xxx.ppm ; display /tmp/xxx.ppm 552 553Animating a function ani.xml saved from evolvotron in animation mode: 554 555$ cat ani.xml | evolvotron_render -f 100 -v -s 256 256 ani.ppm ; animate ani.f??????.ppm 556 557FUTURE DEVELOPMENTS 558=================== 559Please check the TODO file first before you send me suggestions! 560 561Please don't ask me to port evolvotron to proprietary platforms. 562You are of course Free under the terms of the GPL to do so yourself, 563but please read 564 http://www.fefe.de/nowindows/ 565first. 566 567THANKS 568====== 569To those who have contributed feedback, suggestions and patches: 570 - Dmitry Kirsanov 571 - Jonathan Melhuish 572 - Karl Robillard 573 - Linc Davis 574 - Paolo Greppi 575 - Marcin Wojtczuk 576 - Michael Sterrett 577 - Massimiliano Guastafierro 578 - Goetz Waschk 579 - Forrest Walter 580 - "chr_bl" at web.de 581 582And to the anonymous Linspire reviewer who perhaps came up with the best 583summary of evolvotron yet: "Fascinating. Utterly pointless, but fascinating." 584 585The friezegroups wouldn't have been possible without 586http://michaelshepperd.tripod.com/resources/groups.html 587 588Thanks to www.di.fm, www.somafm.com and Trance4Ever for music to code to. 589 590Thanks especially to a SIGGRAPH conference panel many years ago (likely 591including Karl Sims, the pioneer in this area) who first got me interested 592in this stuff. 593 594WHY ? 595===== 596I have always admired those who have the skill to wield a pen or paintbrush 597and fill a sheet of paper or a canvas with some striking image from their 598imagination. Unfortunately I lack the patience to learn such skills, 599and probably the necessary manual dexterity and imagination too. 600 601Evolvotron, and several predecessors developed on and off over a decade 602since I first came across the idea, are an attempt to compensate for 603this using the skills I do have i.e some mathematical sensibility 604and the ability to write working code (well, sometimes). If you like 605an image it produces, then as far as I'm concerned that's as satisfying 606a result as if you liked something I'd drawn myself. 607 608Tim Day 609