Cichlid Usage

Cichlid is a distributed application, consisting of a client and servers. One client can connect to many servers at once; currently, the servers are not concurrent -- that is, only one client at a time can connect.

Invocation

Cichlid clients and the server back-end use a common command line parser. All of the command line options it understands are of one of the following forms:

The format of the options understood is similar to the standard X toolkit options, in that all options start with a single '-', followed by an identifier, and then an option argument if applicable. However, since the user code in Cichlid servers can take additional options and arguments, the format of those options is entirely up to the server author. The server library expects all of it's options to come first on the command line, and if any user options or arguments are to be specified, they should be placed after a "--" so that the server library knows not to mess with them. The server library will silently stop looking for options at the first occurence of a plain word, or a "--".

The options "-help", "--help", and "-?" are all understood by the client and by the server API as a cries for help from the user, and they will print a usage message with the options they accept. If server writers are going to be using command-line options, it is highly advisable for them to trap the server usage message and augment it with one that shows the extended options. (The server API provides facilities for this.)

Starting Servers

In order to get something interesting out of a Cichlid client, you'll want to start up some data servers to give it something to look at. For servers which do not take any extended options, the invocation syntax is:

The options understood by all servers are:

-port N
Listen on the specified port N, instead of the default port.
-maxrep N
Attempt to service only the first N connection requests, and then shut down.
-once
Service only one connection request and then exit. Equivalent to "-maxrep 1".
-quiet
Be quiet; don't print all the usual status messages.

Some more advanced servers may take command-line options of their own. To keep the server library's options seperate from other server options, the server library expects all of it's options to come first, followed by a "--", and then any options specific to the server. An example of this invovation style:

Starting Clients

After starting some number of servers, you can fire up a client. The client invocation syntax is:

Each server_spec is of the form [host][/port], excluding of course the empty string. Example invocations:

Currently, the default port is 22350, and the default host is "localhost". These are specified in lib/data_proto.h

Client Usage: How To Interact With Cichlid

Once it's up and running, the Cichlid client gathers data from each of the servers, and displays each set in an independent "graph". Input is taken from the keyboard and the mouse; currently, the input scheme is quite messy, though it's easy to work with once you get used to it.

The Keyboard

The keyboard is modeless; a given key always has the same function, though that function may or may not apply to only the currently selected graph. Many of the keys operate toggles; after changing a toggle, it's new value will be printed. Some pairs of keys also step through a fixed-sized list of options, where a lower-case letter goes to the previous value and an upper-case letter goes on to the next. To get a list of the current key bindings, push 'h'. A quick rundown of the current key bindings:

1-9 => Select graph
The given graph, if it exists and is connected to a server, will become the target of all graph-specific keyboard operations.
(shift) 1-9 => Look at graph
The client will place the "camera" in such a position that the given graph appears at the center of the window. This does not select the graph, however.
a => Toggle animation
This applies to the currently selected graph. By default, graph animation is off; this facilitates speedy camera orientation and setting tweaks, especially for complex datasets. When animation is on, data will be retrieved from the data server and the display will be updated. When animation is off, data requests will not be sent to the server, and the graph will remain static. Cichlid can take advantage of this fact on some platforms, and redraw graphs that it knows have not changed much more quickly than those that have.
b/B => Walk through available antialiasing modes
This allows the user to select from amoung the antialiasing modes supported on the current display. Right now, there are two types: "NONE", which is pretty obvious, and "SCENEx", which is 'x'-pass scene antialiasing. The more passes you use, the smoother the picture, but the longer the rendering time.
c/C => Step through coloring types
This applies to the current graph. Each graph object has a set of coloring modes associated with it to determine what color the elements are; they include some sort of 'user' mode, which gets the color info from the data server, and depending on the object type there may be other modes that color things based on position, size, etc.
d => Toggle color dithering
On many displays, the colors calculated by OpenGL cannot be displayed exactly. If dithering is enabled, the available colors may be alternated ("dithered") to appear more like the target color; otherwise, color will probably be truncated and smooth gradients may appear to have striations. Dithering does slow down rendering a little on some systems; it is enabled by default.
f => Toggle FPS counter (interval: N sec)
The "speed" of a Cichlid client display can be gauged somewhat coarsely by examining the number of frames-per-second it can draw. If this the FPS counter is enabled, every N seconds or so the Cichlid client will report the frame rate it averaged over that period. This can be used to quantify the relative speed of the client machine's rendering system, as well as the performance implications of various option settings. The time interval defaults to 2 seconds; this can be changed by editing client/window_config.h, under FPS_SAMPLE_MSEC.
F => Toggle full-screen mode
For demos, it's often handy to have a large display, without desktop items or window-system decorations getting in the way. Full-screen mode provides and easy way to achieve this, without having to manually resize windows. Unfortunately, it doesn't always work right; with some window managers, you still end up with a title bar and other controls. The actual code that handles the full-screen geometry calculations is in the GLUT library, so there's not much we can do about this portably.
g => Toggle guide lines / bounding boxes
When this per-graph option is enabled, "bounding boxes" -- boxes that outline the volume that each graph is allowed to draw in -- will be drawn with each graph. There is also a facility for "guide lines", which are object-dependent in meaning, though they aren't currently used. The bounding box parameters are in client/graph_config.h, and have "BBOX" in the name.
G => Toggle "ground" display
When this is enabled, the background will be drawn in a blue color, and a large pair of green polygons -- one facing up, and one facing down -- will be drawn in the plane that graph data generally thinks of as Z=0. This gives some sense of orientation to the scene, which can help for the "fly-through" motions. This is one of those random options that I look at and think, "why did I add this?"
l => Toggle scene lighting
Scene lighting modifies the colors of the scene's vertices, taking light source parameters into account. This adds lots of visual "depth cues", that can enhance the appearance of a scene considerably, at the cost of some rendering speed. By default, lighting is enabled, and Cichlid has some global ambient lighting as well as one "spot" light source that's just above the "top" of the camera. Lighting only modifies the colors at the vertices of a scene; the shading model determines the colors used to fill in the pixels of a polygon.
L => Toggle local/infinite viewer (for lighting calculations)
The lighting calculations are fairly expensive, but they can be sped up a bit by assuming that a light source is infinitely far away when determining direction, so that all "rays" from that source are parallel and thus the same direction from every vertex in a scene. Have the "local viewer" option disabled is the default, since it looks pretty good and it's faster; if this option is enabled, the 'flare' from the light source tends to be tighter, since the light source is next to the camera which is of course not infinitely far away.
m/M => Step through camera modes
Cichlid has several different methods of mapping mouse input (if the mouse is in camera-moving mode) to camera motion. The current modes are:
p => Toggle OpenGL mouse pointer
Some OpenGL-capable graphics systems don't have the capability to draw the window system's mouse pointer. As far as I know, this only applies to Voodoo cards running full-screen. This is a hack to work around that; it draws an OpenGL 'point' at the mouse cursor, so you can still make use of it.
r/R => Reset options & camera (R => and graphs) to defaults
This resets all of the window-level options to their default values, including the camera orientation. This is great if you get "lost". Pushing 'R' resets the window, and also resets each of the graphs to their default states. Note that using 'R' can be a bit dangerous, since it tosses out data; currently, using it will cause you to lose all labels that aren't changing, though new labels will appear at they are set, since labels are only sent on startup or when they're changed.
s => Toggle smooth shading
This option toggles the OpenGL shading model between flat shading, and smooth shading. Shading determines the color of the interior pixels of a polygon from the color information provided at the vertices. Flat shading just picks a color from one vertex and uses it to fill the shape, while smooth shading interpolates the colors across the shape. Flat shading can be quicker, though smooth shading can look much nicer, particularly if the polygons are visibly large. In Cichlid, currently, all of the vertices in a given polygon have the same color specified, so flat shading would seem the optimal choice; however, lighting calculations alter the color values, and since lighting is enabled by default, so is smooth shading.
S => Toggle showing of labels
This option toggles the display of labels on the currently selected graph. By default, all labels are displayed, but often it is desirable to switch them off since they can clutter up the display -- particularly in small windows, or when they're "far away". Since they don't scale with distance, labels tend to clump together unreadably as the camera is moved away. At some point in the future there will probably be a facility for intelligently displaying a subset of the labels, but for now it's a binary toggle.
t/T => Step through draw types
This modifies only the currently selected graph. Each graph object can have several different drawing methods associated with it. They determine which shapes are used to draw the object, and some draw types may be vastly quicker than others.
v/V => Step through mouse modes
This selects the operation of the mouse on the entire window. The currently supported modes are:
w/W => Write image to file (w=window size, W=large)
These cause a copy of the current display to be written to disk in the form of a 24-bit uncompressed PPM 'rawbits' file. If the window-size screen shot is selected, only a single redraw is needed, and the image will be written at the same size as the current client window. If the large screen-shot is selected, the image will be rendered in small chunks, composed into horizontal strips, which are written to disk in order to form the image. This can be quite slow, but it allows very large images to be generated. The image width is currently set to BIG_IMAGE_WIDTH in "client/window_config.h", and the height is set such that the large image will have the same aspect ratio as the current client window. The images will be named "dumpNNNN.ppm", with N starting at 1 and counting up, but existing images will not be overwritten.
(space) => Toggle wireframe / solid
This option determines whether or not the current graph's polygons will be filled or merely outlined. The default is to fill shapes; wireframe rendering is often faster, and can be handy for inspecting hidden surfaces.
[/'/] => Adjust camera auto-rotation speed, FOCUS mode only.
This option adjusts the speed at which the camera is rotated about it's focal point. Auto-rotation is active only if the current camera-mode is set to "FOCUS"; '[' and ']' bias the rotation toward opposite directions, while the single-quote key stops rotation outright. This can be useful for "hands-free" demos.
TAB => Toggle video capture
This option captures a series of images. The images will be stored in a pre-allocated buffer in memory, and written to disk when the buffer is full. Additionally, a frame-rate-limiter will attempt to keep the redraw rate as close to the desired rate as possible. Images will be written at the size of the client window when the capture was stared, and will be written to disk with the names, "capNNNNN.ppm", with N starting at 1 and counting up, overwriting any existing files of the same name. The capture parameters (FPS, duration) are set in "client/window_config.h".
^S => Toggle stereo rendering (if supported)
If the client executable was compiled with stereo support, this will toggle stereo rendering. The specifics of stereo rendering depend on the module that is used. Some require full-screen video, and currently no stereo modes support image capturing, antialiasing, or selection.
^Q/^A => Increase / decrease stereo eye separation
^E/^D => Increase / decrease stereo focal distance
These are the fairly self-explanatory parameters used in the stereo projections. These need to be adjusted manually to get a pleasing stereo image, depending on the camera position and the interesting points in the scene.
ESC => Quit
This causes the client to exit.

The Mouse

The mouse is used for many different things in Cichlid; the exact meaning of the five seperate inputs -- X axis motion, Y axis motion, and the three mouse buttons -- depends on the current "mouse mode", and possibly the current "camera mode". A brief rundown of the mouse modes:

"POINT"
This mode is used to "point" at things in the scene. A middle-mouse-button click in the other mouse modes acts as a shortcut to switch to the "POINT" mouse mode. Currently, it supports two actions: left-clicking on an individual data item causes an event notification to be sent to the server that provided it; right-clicking is similar, but it sends and information request about that item, and if information is provided, it will be drawn in a small callout box at the location of the click. Unfortunately, the drawing is done is preety cheesily, in that it uses the window-position of the mouse click to place the callout origin in 3-D space; a consequence is that _any_ change in the camera or graph position invalidates the callouts, so they all have to be erased.
"CAMERAMOVE"
In this mode, the mouse moves the camera relative to the scene, without altering the scene itself. The actual mapping of X/Y motion to camera position changes depends on the "camera mode", as well as the mouse buttons.
"DATAMOVE"
This allows the user to change the position and orientation of individual graphs -- the currently selected graph, in particular -- within the scene. While the left mouse button is held down, mouse motion will cause the selected graph to be moved in the plane of the screen. While the right mouse button is held down, vertical mouse motion will move the graph toward or away from the camera, while horizontal motion will spin the graph about it's normal.

Admittedly, user-interface isn't terribly well thought out; I needed some sort of UI, and the current one just fell out of the code.

Last modified: Tue Aug 24 16:19:07 PDT 1999