Installation

Right now there is no easy, out of the box solution to install QMGA, sorry.

See the README file for some hints. If it this does not help you, feel free to contact me under the following email address:

qmga at users.sourceforge.net

Usage

General

Here we see a screenshot of QMGA.

Toolbar: Color

OpenGL Color Settings

This button opens the following dialog:

Here it is possible to make settings on the color scheme used by OpenGL.

The following picture shows the effect of ambient light on a sphere. It comes from all directions and is reflected in all directions, thus destroying any 3D impression:

The next picture shows the effect of diffuse light, which comes from a certain point in space and is reflected in all directions.

Again the next picture shows the effect of specular light, which comes from a certain point in space like diffuse light, but is reflected like on a mirror.

If all light sources are put together and the intensities are somewhat balanced the sphere looks like this.

The value for ``shininess'' decides, how big the reflection appears.

Color of the Coordinate System

Each of these three buttons opens a dialog to pick a color. The chosen color is then applied to the according axis of the small coordinate system inside the render area as well as to the button itself and some other elements linked to the corresponding direction.

Color Axis

The first set of coordinates shows the director of the mesophase as calculated beforehand. The second can be edited by the user. The two buttons ``D'' and ``U'' define, which vector is used for colorization purposes.

Toolbar: Camera Position

This toolbar contains four sets of controls. Three for angle manipulation and one for zoom.

Angle Setting

Here $\alpha$ represents the rotation around the x-axis in a chain of three successive rotations ($\alpha$: x-axis, $\beta$: y-axis, $\gamma$: z-axis). The following description is the same for all three angles.

The spinbox widgets are continually updated when the objects are rotated. The boxes can also be used to spin the objects, but as they represent rotations executed in a chain, the actual axis around which the individual rotation takes place is NOT the axis one might guess on first thought. The reason for these spinboxes is to recreate a certain angle triplet ( $\alpha,\beta,\gamma$). Until now there is no built-in functionality to save such triplets other than the one used at the time of closing QMGA which is restored on the next start. Others triplets have currently to be saved the old fashioned way (pen and paper).

The dial can be used to rotate the objects around the x,y,z axis as shown by the small coordinate system in the render area (if activated).

The purpose of the line edits is to rotate around the corresponding axis by a certain angle. To do so one writes the desired rotation angle into the line and presses ``enter''. It is possible to enter negative angles.

Zoom Setting

This spin box shows and sets the actual zoom value. The value is saved/restored with program termination/startup. The value is also continuously updated, when the zoom is changed e.g. by mouse wheel usage.

Toolbar: Open/Save

Open Configuration File

The button opens a system file browser, but the path can also be typed directly into the line edit.

Notice: There is no restriction as to how the loaded file has to be called (e.g.: no specific .xyz extension is required), so be sure that the file is the one you want to load. Wrong file formats currently result in an error message on the command line.

Save Screenshot

This button opens a small message box giving the name of the file(s) to be saved and asks permission to do so.

Size of Screenshot

These two line edits are used to define the size of the screen shot (in pixel units). One of the line edits is grayed out were the other can be written into. The value of the grayed line edit is calculated using the aspect ratio of the render area. While resizing the program window the editable value stays constant and the grayed is constantly recalculated as the aspect ratio changes.

The ``$\times$'' symbol is actually a button that toggles which of the line edits is editable and which is not.

Name and File Format of Screenshot(s)

If the toggle buttons ``png'' and ``eps'' are turned on (either one of them or both) a file of the appropriate format is saved to disk, when the save button is pressed. An error box appears if no file format is specified.

The line edit holds the base name that is to be used for the saved file. It is extended by .png or .eps depending on the format.

(Note: Two files are saved if both formats are specified, of course...)

Toolbar: Video Settings

Opening Video File

This button and line edit work in the same way as the ``normal'' open file. The only difference is the handling of the specified file.

Video File Range

The ``player'' assumes, that all successive files are named the same except for an .xxxxxxxxxxx index number at the end.

The three line edits shown here specify with which file to start, with which to stop and how to increment the index.

Example:

Loaded ../test/dummy.0000

The whole directory contains files up to dummy.5000.

start = 0; stop = 1000; step = 1

This results in the playback of all files in the range from dummy.0000 to dummy.1000.

If, for example, step is changed to 10 only every 10th file is loaded (0,9,19,...).

This functionality is useful to avoid error messages when the index is not continuous and to speed up replay, when the timescale is too large.

Number of Digits

This line edit specifies the index endings number of digits. The value is internally used and quite important.

e.g.: If the file is called file.00000000 #digits is 8.

Toolbar: Video Controls

Capture

If this toggle button is on, all played frames are written to disk with a name (and position) based on the one specified in the screenshot line edit.

Direction

These buttons decide whether the trajectory is played froward or backward.

Standard Controls

Play, Pause, Stop. Not much to say about these.

Progress-Slider and LCD

The slider shows the overall position of the playback based on the input made in ``start'' and ``stop''. It can also be used to seek to another position in the trajectory e.g. by dragging it with the mouse. The LCD shows the number of the file that is currently shown.

Toolbar: View

Toggle Full Render, Coordinates and Colormap

The first toggle button switches between full and stick render view. The second button switches the coordinate system in the lower right corner on and off. The third button switches the colormap on and off and the last button switches the bounding box representation on and off.

Model Parameters and Switch Models

The left button opens the following dialog:

In this table the user is able to define all parameters for all models that are in use. The first two lines are in sync with the two toolbars on the main window and always shown here. All additional lines depend on the systems shown so far, because if a loaded system needs more models as are defined right now new models are created. On the other hand if a new system needs fewer models NON are removed! All models after the first two are initialized as spheres with radius 1 and are not saved to file at program termination.
Note again, that when a new file is loaded that makes use of fewer models than the file before the unused models are shown here nonetheless. No model is deleted while the program is running, but if a file is loaded that needs more models new ones are created and old ones are overwritten.

The middle button enables the right button which is a switch to toggle the whole system between model 1 and model 2. This switch overwrites the model settings made in the file. The whole system is imposed with either model 1 or model 2.

Slice and Fold

The left button (knife) causes the render area to react to the settings in the slice window:

Every slider has a range of thrice the bounding box to be able to also slice systems that are shown in an unfolded state. The leftmost button in each row of the dialog resets the slider settings and the second one fixes the distance between two sliders of the same direction.
The right button (accordion) folds an unfolded system into the bounding box, when enabled and unfolds it again, when disabled. Note that it is not possible to unfold a system that is saved in a folded state.

To do so anyway a trajectory has to be given where the first file has to start entirely in the bounding box. This functionality is not yet implemented, but may follow in a later release.

Optimization

The first button (opt) enables some optimization routines which help to speed up the visualization of large closely packed systems (starting about $10^{4}$ Particles maybe less). With smaller systems visualization will become slower (!). So it is best to try out, if neccessary (e.g. when rendering is slow...). The second button (lod) enables automatic level of detail adjustment, when the render performance is poor. Be aware, that this is not an immediate effect. It takes some render cycles to gradually lower the render quality starting from back to front.

The toolbox sets how detailed each object is represented. The range is from poor to good in five steps. In a normal session (whatever normal is) it is sufficient to work with a medium setting of 3. On a printout it might be desirable to use 5 for smooth edges. Poor is only useful for very large systems or for very slow hardware. The next picture shows the difference:

One might want test the settings by checking the frames per second toolbar.

Toolbar: Frames per Second (fps)

Current fps

This display shows the corrent frames per second as calculated by the render engine. The accuracy for very high frame rates is not very good because of the linitation to one millisecond time quantization in the measurement. The highest value shown is thereby 1000 fps, where the measurement is capped.

Mean fps

With every new fps value the mean is taken over all values, to increase the accuracy if one wants to know how fast a system is rendered.

Reset and Benchmark

The reset button resets the mean fps value to zero. If the benchmark checkbox is checked it also starts a series of random rotations which might be used for benchmarking purposes.

Number of Frames

The value of this spinbox gives the number of frames shown (rotations done) when a benchmark is started.

Model Parameter

x,y,z: These are the parameters used for ellipsoids. E.g. x=y=z=1 results in a sphere with a diameter of 1. x=y=1; z=0.2 results in an ellipsoid made of a sphere by flattening it along the z-axis by a factor of five.

d,l: These are the parameters used for spherocylinders. d is the diameter of the sphere and l is the length of the cylinder between the two halves.

Notes:
For internal reasons x=y=z=0 is not allowed, even if spherocylinders are shown.
If $l=0$ the model is interpreted as an ellipsoid and x,y,z are used. d,l are ignored.
If $l\ne0$ the model is interpreted as a spherocylinder and d,l are used whereas x,y,z are ignored, except for the mentioned constraint.

Tree View

The tree view shows two root directories. The local hard disk (/) and the remote computers root (ssh/). The local root can be double clicked to open a standard file tree. Files can be opened via drag and drop into the render area, or by double clicking them with the left mouse button. This feature should work and needs no special treatement.

The remote connection needs some configuration beforehand to work.

Internally this functionality is based on ``ssh'' and ``scp'' to manage network connections so these tools must be present on the local system. On the remote system ``cd'' and ``ls'' must be present and ls has to be able to accept the switch ''-l'' for long view. Also it must be possible to start programs on the remote machine via ssh (try: ssh user@host ls -l).

Another thing is, that the specified user has to be able to log on to the specified host WITHOUT BEEING ASKED FOR A PASSWORD!

1. Create a key pair on the local machine, if there is none present, yet:
   $ ssh-keygen -t dsa -f ~/.ssh/id_dsa -C "you@example.com"
   Generating DSA keys: Key generation complete.
   Enter passphrase (empty for no passphrase): (If you use a passphrase you will need an ssh-agent! search the net...)
   Enter same passphrase again:
   Your identification has been saved in ~/.ssh/id_dsa
   Your public key is:
   1024 35 [really long string] you@example.com
   Your public key has been saved in ~/.ssh/id_dsa.pub
   $
2. Make sure the public key is in the ~/.ssh/authorized_keys file on the hosts you wish to connect to.
   The following command appends your public key to the authorized_keys file on the remote host.
   $ cat ~/.ssh/id_dsa.pub | ssh you@other-host 'cat - >> ~/.ssh/authorized_keys'
   you@other-host's password:
   $
3. Verify that DSA authentication works:
   $ ssh you@other-host
   (Should not ask for a password and log on to ``other-host''.)

After this the connection should work. As with local files remote files can be dragged and dropped or double clicked. Note, that remote files are copied (via scp) to the local machine and stored in the ``scp-tmp'' directory of the qmga installation. The tree view window shows how much data is stored in this directory and offers a button to delete it all (when viewing a lot of rather large files the data will grow very fast...).

Also note, that files with the same name are overwritten in the tmp directory.

About this document ...

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 -no_navigation qmga-manual.tex

The translation was initiated by Adrian Gabriel on 2007-07-03