"Points" Manual

The program "points" is a simple OpenGL application that I have written. It is useful for displaying three-dimensional point sets, such as results from cosmological simulations, or three-color diagrams for stars, or anything else you can imagine. It is fast, cheap, and simple to use. For instance, on a 200Mhz SGI O2000 processor, it can display up to about 2 million points with a reasonable level of interactivity. A tarred and gzipped version of points is now freely available.

The point of "points" is that you can plot your particles in three-dimensions and then navigate through them. You specify the data file and the properties of your display in an input file. When you run "points" a window with your data comes up and you can play with it. You can also output the current image to a .tiff image file. (The program imconv or xv can then translate this file to a .gif file or whatever you prefer).

Aside from point sets, "points" can also handle other things, like general polygon surfaces or vector fields. It is also designed to be easily patched to include whatever extra features you might desire. Although this design is primarily for my own benefit, anybody who knows a little OpenGL should be able to alter the program to do what they want.

Installation

1. Download the tarball and unpack it with gzip and tar
2. Type "./configure"
3. Obey the instructions of the error messages configure gives you (a common one for RedHat users is that "--libdir=-L/usr/X11R6/lib" should be an argument to "configure")
4. Type "make"
5. If you get an error that gluTessBlagBlah is not a symbol, than you need to install a more correct version of Mesa (RedHat ships with Mesa-3.4.2, which incurs this failure). Mesa-5.0 works as of Dec 2002.
6. Type "make install"
7. Test the demos in the demo directories

The Input File

The call to "points" is of the form:

points [infile] [-geometry =WxH+X+Y]

where "infile" is the name of your input file. The optional "-geometry" flag will place the window where you want it. This file is processed line by line, where each line is of the form:

[tag name] [tag values]

Below we list the possible tag names and values:

• Point Data Input Tags: These tags control the input of the positions and colors of all the points. "points" can subsample the points if you like.
  • pointfile [filename1] [filename2] ...: The file names of the lists of coordinates. These should be a C-type binaries containing four-byte real numbers (C-type "float"). It should consist only of a list of x, y, z values. Thus a list of two particles, one at (1., 1., 1.) and the other at (2., 2., 2.), would be described by a file containing the values: 1., 1., 1., 2., 2., 2.
  • velocityfile [filename1] [filename2] ...: The file names of the lists of velocities. If this tag is not "NULL", the program draws lines at each position in "pointfile" in the direction specified by velocityfile. Again, these files should be C-type binaries containing four-byte real numbers (C-type "float"). It should consist only of a list of vx, vy, vz values. Thus a list of two vectors, one equal to (1., 0., 0.) and the other equal to (0., 1., 1.), would be described by a file containing the values: 1., 0., 0., 0., 1., 1. Combined with the example pointfile above, and if velocityscale is set to 1., the two vectors are from (1., 1., 1.) to (2., 1., 1.) and from (2., 2., 2.) to (2., 3., 3.).
  • velocityscale [value1] [value2] ...: Scale factors to apply to the velocity lines specified by the corresponding velocityfile.
  • numpoints [number1] [number2] ...: The number of points in each pointfile. If set to zero, will try to detect number of particles based on file size. (Default to 0).
  • colorfile [filename1] [filename2] ...: A list of colors for all the points. This should be a C-type binary containing four-byte real numbers (C-type "float"). It should consist only of a list of red, green, blue, and opacity values, each between 0 to 1. A list of three particles, one red, the other green, and the last one blue (all totally opaque), would look like: 1., 0., 0., 1., 0., 1., 0., 1., 0., 0., 1., 1. (If this file is not specified or named "NULL", all particles are plotted as white and totally opaque). Opacity makes no difference unless you use "Blend On" on the menu bar.
  • pickfile [filename1] [filename2] ...: If not "NULL", these files are ASCII files containing the same number of lines as there are points in the corresponding pointfile. If this file exists, then you are able to "pick" a point and get the information on the corresponding line in the pickfile. You just put the mouse over the point you want to pick, and then press the spacebar. As easy as that!
  • subsample [number1] [number2] ...: Subsamples each list of particles by this factor. Subsampling is done randomly. This number need not be a factor of numPoints. (Default to 1).
  • pointsize [size1] [size2] ...: Size of point (or line) to use in each file. This is a pixel size, not an absolute size, so it will not change depending on your distance. (Default to 1).
  • pointcolor [r1] [g1] [b1] [a1] ...: Change the default red, green, blue, and opacity colors for each pointfile. These get used when colorfile is not defined or called "NULL". (Default to 1., 1., 1., 1.).
• Polygon Data Input Tags: These tags control the input of the positions of vertices and the face specifications for general polygon surfaces, with less than seven vertices per polygon.
  • vertexfile [filename1] [filename2] ...: The filename of each file of vertices. Should be the same format as a pointfile. For instance, three vertices arranged in a right isosceles triangle in the x-y plane would be: 0., 0., 0., 1., 0., 0., 0., 1., 0.
  • polyfile [filename1] [filename2] ...: The filename of each polygon file. Each file contains a list of integers, with the following format: [nverts1] [vert1_1] ... [vert1_nverts1] [nverts2] [vert2_1] ... [vert2_nverts2] ... That is, it is a series of faces, specified by the number of vertices in that face followed by the index of each vertex in that face. These should be given in counterclockwise order. Not coincidentally, this is exactly the format output by IDL's shade_volume routine. One would thus connect the above triangle as: 3, 0, 2, 1.
  • numvertices [number1] [number2] ...: Sets the number of vertices in vertexfile. If set to zero, will try to detect number of vertices based on file size. (Default to 0).
  • numpoly [number1] [number2] ...: Sets the number of polygon vertex specifications in each polyfile. If set to zero, will try to detect number of vertex specifications based on file size. (Default to 0).
  • polycolor [r1] [g1] [b1] [a1] ...: Sets the ambient color of each surface. Diffuse and specular remain white. (Default to 1., 1., 1., 1.).
• Image Geometry Tags: These tags control the window size and the initial viewing position.
  • windowsize [width] [height]: The width and height of the display window, in pixels. If only width is specified, height is assumed to be the same. (Default to 400).
  • scale [value]: Overall scale of the plot, which affects the default parameters of pos, center, zclip, and ortho, as well as the size of the steps that you take when you move. For instance, if your data is from -10. to 10., you probably want to set scale to 20. and leave everything else unchanged.
  • pos [x] [y] [z]: Sets the initial viewing position of the observer. (Default to 0. 0. 4.*scale).
  • center [x] [y] [z]: Sets the initial rotation center of the observer. (Default to 0. 0. 0.).
  • fvec [x] [y] [z]: Sets the direction of the vector pointing into the screen. Automatically normalizes this vector, so make sure length is greater than zero. (Default to 0. 0. -1.).
  • uvec [x] [y] [z]: Sets the direction of the vector pointing vertically on the screen. Automatically normalizes this vector, so make sure length is greater than zero. (Default to 0. 1. 0.).
  • projection ["perspective" or "orthographic"]: Do you want perspective projection or orthographic? Orthographic gives no noticeable advantage in performance. (Default to "perspective").
  • zclip [near] [far]: Near and far clipping planes. (Default to 0.1*scale 60.*scale).
  • fov [angle]: Field of view angle, in degrees. For perspective projection only. (Default to 20.).
  • aspect [value]: Aspect ratio (y/x). For perspective projection only. (Default to 1.).
  • ortho [left] [right] [bottom] [top]: Boundaries of an orthographic projection. (Default to -1.*scale 1.*scale -1.*scale 1.*scale).
• Boundary Properties: These tags control the properties of a boundary cube centered around the point (0.,0.,0.), of a specified size.
  • boundarysize [size]: If greater than zero, "points" draws a wireframe cube of this size around the center of the data. (Default to 0).
  • boundarycolor [red] [green] [blue]: Sets the components of the color of the boundary. (Default 0. 1. 1.).
  • boundarycenter [x] [y] [z]: Sets the center of the boundary. (Default to initial rotation center).
• Ruler Properties: These tags control the properties of a "ruler," which takes the form of a cube at a fixed distance in front of you. Its orientation remains fixed with respect to the data.
  • rulersize [size]: If greater than zero, put a cube at a fixed distance along your line of sight of this size. (Default to 0).
  • rulercolor [red] [green] [blue]: Sets the components of the color of the ruler. (Default 0.5 0. 0.5).
  • rulercenter: Position of the ruler in viewer coordinates: x to your right, y up, z into the screen. (Default 0. 0. 0.5*scale)
• Extra Objects: Points has an easy way to add objects to the code, if you are willing to program in OpenGL. Here are some examples:
  • cube[indx] [size] [x] [y] [z] [red] [green] [blue]: Put a cube of the specified size and color centered on the specified point. For example, if you want two cubes, both centered at zero, with different sizes, and one green and one red, you need the lines: "cube0 1. 0. 0. 0. 0. 1. 0.", and "cube1 2. 0. 0. 0. 1. 0. 0.". Each cube must have a unique index.
• Miscellaneous:
  • outfile [filename]: default output .tiff file. If this is specified, points automatically saves and exits immediately. Thus this provides a very crude way of making animations. (Default: sample.tif).
  • clearstring [color]: A value of "white" makes the background white instead of black. This can be useful for making postscript files.

The Menu

"points" provides a menu by clicking the right mouse button. The entries are explained below. You may not understand what some of the things do until you read about navigation and rotation in the next section.

• Image Submenu:
  • Save Image: Saves the current frame as a TIFF image. The name is that set by an earlier "Save Image As ..." or by the input parameter "outfile".
  • Save Image As ...: Saves the current frame as a TIFF image. Prompts user for name.
  • Blend On/Off: Turns on/off transparency.
  • Point Smooth On/Off: Makes points round/square.
• Objects Submenu:
  • Show/Hide Ruler: Show or hide the ruler, accordingly.
  • Show/Hide Boundary: Show or hide the boundary, accordingly.
• Recenter Submenu:
  • Recenter to Front: Moves the rotation center to a position in front of you. Also picks up the rotation center point, and shows the sphere at the rotation center.
  • Recenter to Center: Returns the rotation center to the [xyz]center. Also drops the rotation center point.
  • Show/Hide Recenter Sphere: Show or hide the sphere at the rotation center, accordingly.
  • Pick Up/Drop Recenter: Either pick up or drop the rotation center, accordingly. When you pick it up, it moves with you, like the ruler does. When you drop it, it stays put.
• Recenter Submenu:
  • Movement More: Increase the speed of navigation by a factor of 2.
  • Movement Less: Decrease the speed of navigation by a factor of 2.
  • Body/Camera Rotation Axes: The mouse controls the rotation of the data set. You can make it rotate about its own x and y axes (Body) or about the viewer's x and y axes (Camera).
• Reload: Reloads the data, in case any of the source files have changed. (Note you can't change the window size this way). This does not reposition the camera.
• Restart: Reloads the data and repositions the camera, in case any of the source files have changed. (Note you can't change the window size this way).
• Quit: Duh.

Navigation and Rotation

The nice thing about "points" is that it lets you fly around in the data set. You do this by using the keyboard. Two things to remember: first, the "shift" key pressed with any other control key makes you go ten times faster; second, you can also control the movement amount by using the "Movement More" and "Movement Less" options on the menu (available by pressing the right mouse button).

To move backwards and forwards, use "a" and "z", respectively. To turn around and change your viewing angle, use "h", "j", "k", and "l." "vi" users will find this very comfortable. To move left, right, up, or down, use "y", "o", "i", or "u". That is, just move your hand up a row of keys from the standard "vi" position, and do what comes natural. That's all you need to know!

To rotate the whole data set around the center press the left and/or middle mouse buttons. Pressing the left button requires you to move the mouse left or right; pressing the middle button requires you to move the mouse backwards and forwards. You can press both buttons and rotate around both axes at the same time.

It is sometimes desirable to change the rotation center. The most useful thing to do is to use the menu option "Recenter to Front," which will move the rotation center so it is right in front of you. It will also show you a sphere representing the center. Now, as you move around, the sphere will be fixed in front of you. Put it down at the place you want to rotate around, and select "Drop Carry Recenter" to put it down. To make the sphere disappear, use "Hide Recenter Sphere." You can return the rotation center to its original point using "Recenter to Center."

Another way of moving the rotation center is by using keyboard commands. Use "Show Recenter Sphere" to show the sphere. Now, to move it left, right, up, or down, with respect to you, use "7", "8", "9", or "0". (vi lives forever!). To move it back and forth, use "w" and "2".

Often, the first view you specify in your input file is an inconvenient one, since you have specified it "blind," without knowing exactly how it would look. If you want your view to start somewhere else which is more convenient, the best way to do it is to navigate until you find a view which you like, and then press the slash ('/') key. This will output the set of commands which must go in your input file (the "center", "pos", "fvec", and "uvec" lines) to reproduce that view. Then just copy those four lines into your input file and you will be all set the next time.