It

by
Christian Mannes, Mannes Technology
christ@mannes-tech.com

User's Guide

Preliminary Version

Introduction

It lets you visualize complex functions under iteration.

Choosing a Function and Setting Parameters

You can choose which function to iterate by selecting from the popup menu labelled "Function". The first time you select a function, all parameters are set to their default values, the range is set to a reasonable default, and the mode is set to parameter space (you can restore these default values later by clicking the Defaults button.
There are common parameters shared by all functions and parameters that are associated with each particular function. The common parameters/controls are:

Range: x and y - the piece of the complex plane you are looking at.
Resolution: width and height of the image, measured in pixels
Parameter space: each function can be iterated in parameters space or dynamical space. Checking and unchecking the parameter space checkbutton switches between the two. Notice that settings in either space are kept and do not normally influence each other - in fact, it is best to think of the two versions as distinct functions.
Sandbox: clicking this button, lists of points can be drawn on top of the regular image. This is used for example, to draw rays, equipotentials, or orbits of points. Each function can have its particular sandbox algorithm, which can be changed anytime (see below).
Thumbnail size: size of the preview image that appears as you right-mouse-click in parameter space.
Keep aspect ratio: when clicked, changing the resolution in either dimension automatically changes the resolution in the other dimension in order to maintain the current aspect ratio. Unchecking this lets you produce distorted images.
Axes: toggles whether to draw axes on top of the image.

Each function also has a number of function-specific parameters that appear below the common parameters. These vary from function to function and should be (but most are not) documented under Help->Function Info.

Iterating a Function

When you are satisfied with the parameter settings, hitting Start will begin computing the image. Hitting it again - if it changes its label to Stop - will abort the calculation (if you are lucky). Depending on the algorithm (see below), you may see previews of the final image during crunching.
Right-mouse clicking the Start button will compute the image uninterruptably - which often offers speed gains.

Choosing the Algorithm

It offers more than one way to compute images. You can select the algorithm used to compute pictures using the Algorithms menu. This only makes sense when executing escape-time algorithms.

Linear will compute each pixel using straight escape-time.
Refine is a variant of linear that displays previews of the image at lower resolutions as you go. This is useful especially if the picture takes a long time. However, "Refine" eventually calculates each pixel.
["Boxes" is an algorithm that successively subdivides the image into boxes. When all four corners of a box have the same escape-time, the algorithm colors the whole box accordingly without calculating interior pixels. This can be a huge time-saver, especially for images with large "black" regions, but produces only an approximation. Moreover, "Boxes" should only be used with polynomial functions.]
Inverse Iteration, which only works for dynamical space, is the inverse iteration method, useful to draw Julia sets.

Selecting, Zooming and the History

To zoom into a picture, you first have to select an area to zoom into. This is done by dragging the mouse over the region of interest. As you do so, a rectangle is drawn that shows the current region, along with its coordinates. Clicking into an area outside of the selection resets the selection. The selection normally maintains the current aspect ratio. However, you can select an area with an arbitrary aspect ratio by holding down the control-key while dragging.

To zoom into the selected region, you simply hit the Zoom button.

It maintains a list of previously computed images. Everytime you compute one, a button representing that image is added to the bottom of the display. Clicking that button returns you to that image and the associated parameter settings. You can remove any of those buttons - and the history position it represents by control-clicking it

BUG: when you have many of these little previous images (i.e. when the shelf is filled up), the program crashes. You can clean up often so this doesn't happen, but unfortunately, it always ends up having too many and crashing.

Interactions between Parameter and Dynamical Space, and Orbits

Certain operations only make sense in one or the other space. These operations that differ depending on whether you are in parameter space or in dynamical space are:

Parameter space: right-mouse clicking (and dragging) shows, in the upper-left corner of the display, a thumbnail-sized image of the Julia-set corresponding to the point the mouse is at. In addition, an orbit diagram is shown. Those two displays are superimposed. In order to suppress the Julia-set, hold down the control key. To suppress the orbit diagram, hold down the shift key.
If you switch to dynamical space after having right-mouse-clicked, a (function-specific) "parameter" will be set ot that point.

Dynamical space: right-mouse clicking/dragging shows the orbit of the current point, that is, draws a line from the current point p to f(p), where f is the current function. Holding down the shift key makes the orbit longer, that is, draws a line from p to f(p), and from here to f(f(p)) and so forth. Holding down control makes the orbit even longer, shift-control makes it the longest.

(DISABLED) You can also see the orbit of a set of points by holding down the control key and moving the mouse around. Doing this forms a free-hand drawing which defines the set of points. You can apply the function to those points by hitting any key.

Colormaps

(For escape time algorithms) Each pixel in an image is coded as a number from 0..255, representing the number of steps it took for the corresponding point to "escape". Each pixel value is associated with a color of the current colormap. You can change the color scheme by selecting one from the colormap menu. To preview a colormap, check Preview in the color menu.

Colormaps are stored in the maps subdirectory of the directory where you installed It. Each colormap is an ASCII file containing exactly 256 lines, each of the form:
    <red> <green> <blue>
where <red>, <green>, and <blue> are values from 0 to 255 inclusively. Thus for example,
    0 0 0
would be black,
    255 255 255
would be white,
    255 0 0
would be red, and so forth.

Summary of mouse operations

Over Image	Move	Left click/drag	Right click/drag
-	Show coordinates	Select (current aspect ratio)	Parameter space: Julia set + orbit diagram Dynamical space: Orbit
Shift	-"-	-"-	Parameter space: Julia set Dynamical space: long orbit
Control	-"-	Select (any aspect ratio)	Parameter space: Critical Orbit Dynamical space: longer orbit
Shift-Control	-"-	-"-	Parameter space: - Dynamical space: very long orbit

History Buttons	Click
-	Restore history position
Control	Delete history position

Saving

From the File menu, you can do the usual open and save operation. When you save/saveAs, the current image and all its parameter settings are saved (but not the entire history).
You can also save as GIF. This menu item writes out the current image in GIF format.
You can also save as EPS. This menu item writes out the current image in EPS format. (It's a custom made algorithm for saving, which saves A LOT of space, but consequently takes quite long to print)

Adding and removing functions or algorithms to It (Very incomplete documentation here. Just some tips)

( All names of files here are in the path .../It/src/file, assuming you have put all the files in a directory called It/).
The development menu allows you to quickly start up an editor and edit the file that implements functions (of course, you can also edit it in the usual way). This file is called FUN.cc, and it is the ONLY file you have to touch in order to add or remove a function or an algorithm. The only exception to this rule is the file Rays.cc, which contains the algorithm to compute rays and equipotentials due to Christian Henriksen and Xavier Buff (might be an old version).

If you make any changes to any of these files, you need to recompile the program. (Just type make from a shell)

The file FUN.cc contains several examples of different functions and different algorithms, hoping that you will be able to deduce the possibilities that It has just browsing around the file and trying things. I'll just give some tips here.
Each new function starts with the word CLASS. It starts with the global declarations of variables. Then come the parameters that will appear in the interface.
Then the defaults for these parameters.
You will then see that several predefined functions are called. As an example, the function
    byte iterate(double x, double y)
        ............
    return(n)
where n is a number between 0 and 255, runs through each pixel in the screen (x,y), does whatever you want, and returns a color for it.
All this functions are defined in the files Function.h (and Function.cc). If you don't know what you are doing, I recomend not to change this file.

At any time you can use the conditionals
if (PARAMETER_SPACE) .... else ..........
or
if (DYNAMICAL_SPACE)... else...........

There is a quite special function called sandbox which is meant for you to implement there any algorithm you want, tipically for drawing orbits or lists of points.
The function that you need to call for drawing a point (x,y) (inside the range) on the screen in a certain color n is
setPixel(invX(x), invY(y), n)

Whatever sandbox does it will do it on the parameter space or dynamical plane picture that would be there if sandbox weren't cliked.
As an example, the function StandardReal has a sandbox algorithm that plots several orbits, thought for drawing boundaries of herman rings (when
the parameters are appropiate) by plotting the critical orbits.

BUG: at this moment there is a maximum mumber of functions (those starting with CLASS) that you may have. I think it is eight or so. Having more than those makes the program crash.

I am concious that this is not a lot of information, but hopefully it is enough to get you started. Have fun!