The Features page gives a high level view of what the program can do and introduces concepts some of which will be elaborated here, going more deeply into the operational details.
In all instances where you can use the Alt modifier, the program is written so that, if you have a Meta key, you can use that instead of Alt to the same effect. This fact is not belabored, but it may be of help to folks running variants of Unix with non-PC keyboards. (Actually, you may need to recompile it. For some reason, on my system, any time I do a right button click (with any sort of mouse), the resulting event modifiers say that the meta key is depressed; so I can't really test with the meta logic enabled.)
These appear at the bottom of the program's main window. They allow you to monitor and modify a parameter selected from the Parameters Menu, which just consists of a bunch of radio buttons. They are divided into five groups. The top group control the 3D to 2D viewing tranformation. The second group controls the sizes of things as they are drawn. The middle group control the 1D projection for the roving eye. The second to last group are some appearance parameters which control how stickers are drawn. The last group specifies some miscellaneous parameters which control behaviours of the program. Which parameter is displayed and is modifiable via the GUI is determined by which radio button is selected on the Parameters Menu.
You can drag the slider knob with the mouse. You can also make it move by clicking with the mouse on the slider bar or by hitting arrow keys on the keyboard. You can also type a new value directly into the numeric field displayed above the slider.
In many cases, what the parameters mean can best be explored by varying them with slider and observing the effects. (To vary the scale parameter, use the Toggles Menu to disable its automatic update.)
You can move either of the centers (relative to which stickers are being rendered) by dragging any one of the stickers associated with that center. To do this, you can drag with any mouse button, but you must hold down both the Control and Alt modifier keys when you start the drag. This somewhat cumbersome procedure is deliberate because it is not something you are likely to be doing all that frequently and it prevents accidental drags of a center which can be annoying. (Before introducing the Ctrl-Alt- modifier requirement, I found that, when I was working the cube rapidly, some of my intended clicks were being seen as drags and messing up the display when I intended for the centers to coincide. This 'feature' prevents annoying mistakes.) If you complete a drag and then regret it, the undo command will reverse it.
During animation, the rendering algorithm is not 'correct' for the situation when the centers are separated but are close enough that the two groups of stickers overlap. It is not clear what a correct algorithm would be in this case. Nor does it seem reasonable to configure the program this way. When you are dragging a center, the rendering is based only on which stickers are in- or out-facing (all the out-facing ones being drawn last). So there are no strange effects when you drag one group of stickers over (or under) the other. Similarly, when twisting the whole cube the simple in/out algorithm can be and is used. Strange effects can be observed if you separate the centers with the two groups overlapping and then do a single-slice twist with full sized stickers. (I do not regard this a problem worth solving. It was hard enough to find an algorithm which does work correctly when the centers do coincide!)
To tumble the cube, depress two mouse buttons with the cursor near one of the centers. (If you set the Drag Threshold on the Parameters Menu to a small number like 3.0, you can also do this drag with one button; but the default, which effectively disables one button dragging, is recommended.) When you move the mouse the cube will tumble in an intuitive fashion. This tumbling mechanism cannot result directly in any rotation of the image in the projection plane. (It appears to do so when you move the cursor around on the circle whose radius results in a 180 degree turn; but what you are really changing is the axis about which it has been rotated.) To rotate the image, press both buttons down when the cursor is well away from a center near the periphery of the cube's rendering. Then the rotation depends on the angular position of the mouse cursor relative to the (nearer) center.
When the eyepoint is on the z-axis as with the first 3 built-in configurations, the eyepoint's azimuth is unstable. You can get any direction around the compass with only the slightest movement. When you are tumbling from this situation, the picture remains stable because the 2D rotation is also twisting around like crazy to compensate. Fortunately, the sum of the eyepoint's azimuth and the 2D rotation angle does behave continuously with respect to eyepoint position when it is near the z-axis. It is somewhat unfortunate that the first three 'canned' configurations all correspond to this singular situation which arises when the elevation of the eyepoint is a right angle. If you are trying to understand how azimuth and elevation affect the picture, it is easier to start with the eyepoint down near the xy-plane. I.e., with an elevation near zero.
To turn a slice with the mouse, click on any of its stickers. Clicks with mouse button 1 (usually left) result in counterclockwise turning. Clicks with any other mouse button (usually right) result in clockwise rotation. Note that, by default, the resulting direction corresponds to how you perceive it in the 2D image, as opposed to how you might imagine it looking at the cube in 3D from the outside. The 3D direction and the image direction are consistent for out-facing faces, but reversed for the in-facing ones. The default may seem wrong to some folks; but, for the purposes of the 4D to 3D analogy, it should be realized that a Flatlander is incapable of making the in-facing/out-facing distinction for stickers or faces. Anyway, for anyone who feels strongly that direction should be in terms of the 3D external view, there is a checkbox on the Toggles Menu to select this behaviour.
You do not have to click on a sticker to twist a slice. Roughly speaking, any click is resolved to refer to the nearest face center (2D distance). However, to facilitate turning hidden faces (as may occur with a configuration like #5) with mouse clicks, clicks that miss all stickers and which occur near the periphery or farther away are constrained to apply only to in-facing faces. Clicks which are not on any sticker and which occur nearer the cube center (possible with shrink) can apply to any face, whichever is nearer (at its face center). If the eyepoint is on a coordinate axis (as with the first 3 'canned' configurations, the centers of the faces nearest and farthest from the eyepoint coincide, so a click nearest them (but not on the one facing the eyepoint) is ambiguous. This is resolved in favor of the near one if the click is above the horizontal line through the center in the 2D display and for the far one otherwise. (For the z-axis, it's mnemonic!: above - up, below - down)
You can command twists by typing BFUDLR characters on the keyboard. By default, these commands refer to the FCS directions. E.g., if you type "B", the face that turns is that for which the face sticker is color B (i.e., the one that was facing in the b-direction on initialization). There is a checkbox on the Toggles Menu which will cause the keyboard characters to be interpreted in terms of the MCS. For an example with MCS, if you type "B", the face that turns is that which currently faces in the positive y direction (i.e., the b-direction).
You can command twists by clicking on the BFUDLR characters under the coordinate system tattles. Such twists and behave relative to MCS or FCS depending on which set of BFUDLR characters you click on. Direction depends similarly on which mouse button is used for the click.
If you hold down the shift key when commanding a twist by any means, it will reverse the direction of the resulting twist. This is primarily useful for twists commanded from the keyboard, for which the unshifted direction is clockwise. It is also a necessity for someone with a one-button mouse.
Note that, during the animation of a twist, there are some stickers for which which side of the sticker is visible from the eyepoint changes during the animation. Such a sticker is seen edge-on at that instant. The center with respect to which the sticker is drawn changes at this time. As they go edge-on, the display of such stickers disappears naturally; and, as the turn proceeds, they reappear relative to the other center, appearing to jump from one group of stickers to the other.
After commanding a twist by any means, if you depress a mouse button before the animation finishes, you can take over control of the animation by dragging the mouse. (The Drag Threshold does not apply to these drags.) When there is only one out-facing face (as with the first three built-in configurations), the control of the turning of either slice with the same axis is determined by the angular position of the mouse cursor relative to the corresponding center. (Try moving the mouse cursor in circles around the center.) Otherwise and for all other faces, control is obtained by mouse motion in the direction perpendicular to the (projected) axis of the face. It 'feels' like the face is attached to a cylinder along that axis and you are rolling it by dragging the mouse over it.
You can also control animation by dragging in either of the 1D projection areas, in which case the angle of the turn depends only on horizontal motion. (You don't even have to keep the mouse cursor in the 1D area.)
Suppose you draw a unit vector from the origin along each of the three axes in 3D. You could think of this as a little tripod whose legs are at right angles. Now project this into 2-space based on the current viewing parameters. (Excepting 3D Viewing Distance: This projection is done orthogonally.) The label ("x", "y", or "z") for the corresponding axis is drawn at the end of each leg of the tripod. It is color coded to correspond to the sticker which is displaced from the center in the direction in which the axis faces (which may be different for the MCS and FCS tattles). If one of these labels falls atop another, the program draws on top the label corresponding to the leg whose endpoint is closer to the eyepoint. When all three tripod legs have their endpoints closer to the eyepoint in 3D than the apex where the legs meet, the legs are all drawn in white. If there exists any leg whose endpoint is farther away than the apex, then the one whose endpoint is farthest away remains in white, but the other two are drawn in the color of the face sticker facing in the opposite direction from the white leg. Both of the corresponding vectors lie in a plane parallel to the face with that face sticker and that face is out-facing. Without this coloring feature, it is sometimes difficult to tell whether one of the legs is angled toward the eyepoint or away. Try tumbling the cube while watching these indicators to get a better idea how this works. Do it when the cube is not in correct orientation with respect to the MCS to see how the MCS and FCS tattles differ.
The color coding of the BFUDLR characters under the FCS tattle always remains the same, independent of orientation changes, because the orientations of corresponding face stickers actually define the FCS. On the other hand, the color coding on the BFUDLR characters under the MCS tattle do change depending how the cube is oriented in the MCS. In particular, the color of a character is the color of the face sticker presently displaced from the origin in the direction the letter specifies in the MCS. Both tattles are maintained continuously while you do a drag to alter cube orientation. If you twist a center slice, the FCS tattle is maintained in accordance with the twist animation. However, color coding for the directions corresponding to the moving face cubies under the MCS tattle is suppressed while a center slice twist animation is in progress because its state is changing in a manner that does not admit continuous representation.
The Scale Limit Parameter is actually an upper bound for the scale to be used. When you drag a center toward an edge of the window, the program will automatically reduce the scale it uses internally so that there is no attempt to draw outside the window. When you drag back toward the middle, the picture will grow again until the scale in use reaches the specified Scale Limit. When auto-Scaling is enabled and you change window size, the Scale Limit is set to largest value that works for the current displacement of the centers from the edges of the window. When you disable auto-Scaling, the program ceases to modify the parameter value, and its value becomes whatever was current at the time. You can always try manipulating the scale with the slider, but the program will still not allow you to make the scale it actually uses too large. However, you can always shrink as much as you like, even when auto-Scaling is in effect. If the auto-Scaling remains enabled, such adjustments will be cancelled when you change the window size.
If the size-change-as-you-drag phenomenon is disconcerting to you, you can disable auto-Scaling and then either reduce scale or increase window size to give yourself some margin.
To move the 2D eyepoint for the Rover, hold down the Control key. Then the up and down arrows control motion forwards and backwards. E.g., when you first hit the up key the eyepoint will start moving forward relative to the current heading. The speed will double each time you hit a same key. The motion will stop when you hit the key for the opposite direction. Backing up is similar. The left and right keys result similarly in motion perpendicular to the current heading - i.e., sidestepping. This sideways motion is useful for getting information from parallax effects.
Adjustment of heading and view angle feel somewhat similar to the above. For these adjustments you must hold down the Alt key. The up and down keys affect view angle (which also makes the image grow or shrink as does moving forwards or backwards). The left and right keys adjust heading (which also makes the image move sideways as does sidestepping). A big difference is that you get no parallax effects since the eyepoint remains fixed.
(Note that, without either the Control or Alt modifiers, the arrow keys may be used to control the slider.)
Similar to arrow adjustment, there are four types of drag which can be used in the Rover 1D projection area. When you initiate one, the choice can be specified through a 2-button button-gesture or by use of modifier keys. If you press button 1 down and then click button 2, that gesture is called "1-click-2". If you press button 2 down first, then 1, and finally release 2, that gesture is called "roll-2-to-1".
To move rover sideways, do 1-click-2 or Control-drag. To move forwards/backwards, do roll-2-to-1 or Control-Shift-drag. To adjust rover heading, do 2-click-1 or Alt-drag. To adjust the view angle, do roll-1-to-2 or Alt-Shift-drag.
In addition to dragging with the mouse, there is another method for controlling the position and heading of the rover with the mouse. This method is called "Drive Mode", as it is more nearly analogous to driving a vehicle.
Mouse button 1 is the brake. Button 2 or button 1 with the Shift modifier depressed is the accelerator. To start, click the accelerator when the mouse cursor is in the rover 1D projection area. The speed of the rover doubles each time you click the accelerator.
Steering is controlled by the position of the mouse cursor relative to the horizontal center of the display. (There is a little mark there on the horizontal line which marks the top of the rover 1D projection area.) Think of the cursor as being attached to the top of a steering wheel (or a flight control stick).
Drive Mode is enabled by default, but there is a check box on the Toggles Menu which can be used to disable the feature. It can be nuisance if you try to use a button 2 click in the rover projection area to start a twist. (If you tend to make this mistake, you might want to select the check box which makes rover changes undoable rather than disable the Drive Mode feature.)
The rover will stop moving if hits a boundary of the 2D area. It will also stop if you move the mouse cursor out of the rover projection area.
There is no reverse direction mode for driving the rover. However, if you do get it stuck up against a boundary, you can still use one of the forwards/backwards adjustment methods to back off. You can also use heading adjustment to get the rover pointed back inwards
While driving the rover, you can still use keyboard commands to change the Rover View Angle. (Actually, you can do almost anything with the keyboard while the rover is moving - e.g., scramble, twist.)
It appears that the primary factor influencing the performance of the program is the size of the window, or, more precisely, the sizes of the stickers being drawn. Indeed, the time spent in the graphics subsystem would seem to dominate all other considerations.