MeshView Release 1.0 Department of Computer Science Indiana University July 1994; minor doc updates April 1997 INTRODUCTION ------------- This is an initial release of MeshView, an interactive viewing program for two-dimensional manifolds embedded in 3D or 4D. It is written in OpenGL and X/Motif. It has been successfully compiled on SGI's under IRIX 5.2 and 6.3 and should be able to run on any workstation that supports OpenGL and X/Motif. FEATURES -------- -- Reads Geomview/OOGL(developed at the Geometry Center, University of Minnesota) MESH, OFF and LIST file formats. -- Rotates/translates/scales objects in 3D and 4D interactively under mouse control. -- Applies 3D and 4D rolling ball models to accomplish rotations. (See Technical Reports 319 and 406, Computer Science Department, Indiana University, available by anonymous ftp from ftp.cs.indiana.edu in the directory pub/techreports.) Corresponding articles are: A.J.~Hanson, ``The Rolling Ball,'' in {\it Graphics Gems III\/}, ed. David Kirk, pp.~51--60 (Academic Press, San Diego, 1992). A.J. Hanson and R.A. Cross, ``Interactive Visualization Methods for Four Dimensions,'' in Proceedings of {\it Visualization '93\/}, San Jose, CA, Oct 25--29, 1993, pp.~196--203 (IEEE Computer Society Press, Los Alamitos, CA, 1993). A.J.~Hanson, ``Rotations for $N$-dimensional Graphics,'' in {\it Graphics Gems V\/}, ed. by Alan Paeth, pp.~55--64 (AP Professional, Cambridge MA, 1995). -- Momentum option available on all motions. -- Optionally draws faces, edges, vertices, normals, palette, a single lighting vector, and a reference set of 4D axes. -- Supplies a wide range of color palette options for 4D depth color coding. -- Supplies an interactive parametric space "picker" (or point locator) for a MESH file or list of MESH files. Any individual mesh in a set of loaded patches can be selected in turn. -- Saves system state for later recovery, including current 3D and 4D viewing matrices, camera setting, background color, light direction and rendered ppm image of the current scene. This is useful for reconstructing the state of an illustration for a publication. -- Loads palettes and saved system states. -- Uses two different colors (or one color) for front-facing and back-facing surfaces. This feature is quite useful when rotating in 4D. -- Supports 3D perspective and orthogonal projections. -- 4D orthogonal and polar perspective projections. -- Supports a choice between applying the 4D rolling ball to the current screen coordinates of the object's 3D projection (context-free, the default), or applying to the object's local 3D coordinate system context (use the "axes" display to help show the context). The latter is useful for looking at different sides of the object's 3D projection while performing a 4D rotation. This is needed mostly to accommodate a 2D mouse interface, and would not be as useful for a 3D mouse interface. -- Includes a selection of example geometry files, including 4D flat torus, Steiner surface (RP2 embedded in 4D), 4D Fermat surfaces and a lot more. (see README file in the data directory for details) -- Supplies online help. POSSIBLE FEATURES FOR FUTURE RELEASES ------------------------------------- -- Stereo extensions -- CAVE extension -- General scene extensions, surface textures, other OpenGL features -- Constrained navigation submanifolds for camera view motion -- Volumetric (3-manifold) object display -- 3D/4D geodesic generator. -- 3D/4D manifold walker. -- Static and dynamically recalculated 4D occlusion markings on surfaces projected to 3D, like knot crossings of 3D knotted curves projected to 2D. -- Automatic manifold patch sewing to support complicated ad hoc topologies. -- Cutting using primitives like plane/sphere/cylinder/... in 3D/4D. -- Nice image generator for publications. Antialiasing, large-than-buffer size, transparency, stereo pairs. -- Support 3-manifolds embedded in 4D/5D, volume rendering of simple tessellations. -- Animation from files, parametric coordinate transformations, 3D and 4D orientation key frames, topological key frames, etc. -- Scheme-like extensible user language interface, for external modules, animation scripts, and so on. SOME OF OUR DESIGN GOALS ------------------------ -- Fast. Use display lists in OpenGL. Enhance the Geomview/OOGL MESH and OFF file formats. User can specify color per object or color per vertex. -- Small. Keep as simple and independent as possible. -- Portable. Use OpenGL and X/Motif. -- Freely distributable. -- Nice hardcopy generator and easily saveable state for later refinement of a view. INSTALLATION ------------ Unpack the distribution package by 'zcat MeshView.1.0.tar.gz | tar xvf -', or by 'gunzip MeshView.1.0.tar.gz' and then 'tar -xvf MeshView.1.0.tar'. It will create a directory 'MeshView.1.0'. Go to src directory, type 'make'; (the executable file 'meshview' already in src directory was compiled under IRIX 5.2) Modify 'mw', a shell script driver for MeshView, to include local dependencies. INVOCATION ---------- Type 'mw ... ', where standard Motif options are those like : -geometry 1000x800, etc, and filenames can be names of geometry files, setting files or palette files in any order. Geometry files are loaded sequentially and added into an object list. But only the last setting file is used if more than one is supplied and only the last palette file is used if more than one is supplied. You can of course load files after you start MeshView, 'mw' is the simplest way to start. Control-d is the quick shortcut to immediately pop the data-loading dialog. Note that all menus on the top menu bar are "tear-off" style and can be positioned where convenient. MOUSE/KEYBOARD CONTROLS ----------------------- Below, (u,v) denotes the right-handed Cartesian coordinates of the mouse. -- 3D viewing controls : leftbutton : 3D rotation (3D rolling ball) R3(u,v) middlebutton : 3D translation in x-y plane T3(u,v,0) rightbutton : 3D translation along z axis T3(0,0,-v) Shift+right : 3D rotation around z axis R2(u) -- 3D lighting controls : (you can see the light ray by Ctrl+l) Ctrl+left : 3D rotation (3D rolling ball) R3(u,v) Ctrl+middle : 3D rotation around z axis R2(u) -- 4D controls : Shift+left : xyw rotation (4D rolling ball) R4(u,v,0) Shift+middle : xzw rotation (4D rolling ball) R4(u,0,-v) -- r : (Reset) It resets 4D and 3D matrices and 3D light direction, and it stops momentum. -- c : (Center) It resets 3D rotation and translation matrices, and it stops momentum. -- t : Stops momentum. -- Keyboard short-cuts for menu items : Ctrl+d load data Ctrl+s load setting Ctrl+c load palette Ctrl+t save setting Ctrl+i save as ppm Esc quit Ctrl+f toggle drawing of faces (default on) Ctrl+e toggle drawing of edges (default off) Ctrl+v toggle drawing of vertices (default off) Ctrl+n toggle drawing of normals (default off) Ctrl+b toggle drawing of palette (default off) Ctrl+l toggle drawing of lighting (default off) Ctrl+a toggle drawing of axes (default off) Ctrl+1 draw two sides of face use same color (default) Ctrl+2 draw two sides of face use different color Ctrl+3 4D depth color coding (you can see the palette by Ctrl+b) Ctrl+g smooth shading (default) Ctrl+h flat shading Ctrl+p 3D perspective projection (default) Ctrl+o 3D orthogonal projection Ctrl+w projecting along w-axis from 4D to 3D (default) Ctrl+x projecting along x-axis from 4D to 3D (rotating the objects in x-w plane by 90 degrees before apply other 4D rotations) Ctrl+y projecting along y-axis from 4D to 3D (rotating the objects in y-w plane by 90 degrees before apply other 4D rotations) Shift+p : 4D orthogonal projection (default), Shift+o : 4D polar projection , (use 'polar distance' scale on 'setting panel' to adjust the parameter) Ctrl+z projecting along z-axis from 4D to 3D (rotating the objects in z-w plane by 90 degrees before apply other 4D rotations) Ctrl+m toggle momentum (default on) Ctrl+q toggle context-free (default on) Shift+s pop up setting panel Shift+k pop up picker panel LEARNING THE ROLLING BALL ------------------------- To understand the basic philosophy of the rolling ball interface, start with a 3D object such as square.3mesh. Use only the left mouse button (3D rolling ball): pulling the mouse in the +x (screen-right) direction tilts the 2D object so that the left edge comes towards the viewer, acquiring positive z-components, and the right edge dips away from the viewer into the screen, acquiring negative values of z. Pushing the mouse in the +y direction (screen-up) tilts the lower edge out into positive z and the upper edge into the screen in the negative z direction. Now load a solid 3D object like sphere.3mesh or torus.3mesh. These objects automatically have vanishing 4th components (call it w) at every point when loaded, just as the flat objects had vanishing z-components. Now use only the SHIFT-LEFT (4D rolling ball) mouse button: pulling the mouse in the +x (screen-right) direction tilts the 3D object in 4D so that the left side is acquiring a positive w component and getting squashed in x, while the right side is tilting away in w, getting a negative w component. Turn on 4D depth pseudo- coloring to make this dramatically apparent (Ctrl+3, Ctrl+b) - the left side turns red while the right turns blue with the default colormap. Pulling the mouse in the +y direction (screen-up) gives the bottom a positive w and the top a negative w component while squashing the whole object in the y direction. The shift-left mouse control generates x-w and y-w 4D rolling ball rotations. Now use only the SHIFT-MIDDLE mouse button, which generates x-w and z-w 4D rolling ball rotations. Moving the mouse in the +x direction has the same effect as shift-left, but pulling the mouse down (screen-down direction) pushes the BACK side of the object out into positive w, and the FRONT side acquires a negative w component. pushing the mouse up (screen-up direction) has the opposite effect. If a 3D mouse is available, all 3 of these motions, or any linear combination, are available at once and the splitting into the two shift-left and shift-middle controls is not needed. The default mode, in which all 4D rolling ball motions are referred to the screen-based xyz coordinate system with z out of the screen, is the most natural one to emulate a 3D mouse. However, when only a 2D mouse is available, an alternate mode is provided that can be quite useful: deactive the "Context_free" check box on the "Motion" menu. This will allow the user to rotate the object to any 3D orientation (using mouse-left or mouse- shift-right), but now shift-left will follow the object's original x-y axes, and rotate the object in 4D as though the 2D mouse were a 3D mouse moving in the object's own original x-axis direction, NOT the current screen x. Analogous behavior occurs for y motions and for shift-middle x and y mouse motions. Turn on the drawing of xyzw axes to see the different effects. GEOMETRY FILE FORMATS --------------------- (1) MESH (.mesh) Syntax: (can have comments anywhere between # and the end of the line) [4][u][v][C][C][N]MESH[C][C] # key words [r g b a] [r g b a] # RGBA colors for the whole object nu nv # mesh dimensions x y z [w] [nx ny nz] [r g b a] [r g b a] # for vertex[0,0] ... # nx*ny vertices, in the order of # v[0,0], v[1,0], ..., v[nu-1,0] # v[0,1], v[1,1], ..., v[nu-1,1] # ... # v[0,nv-1],v[1,nv-1],..,v[nu-1,nv-1] Explanation of characters: 4 : Vertices are 4D, each consists of 4 floating values. If not present, vertices are 3D and MeshView automatically set 0.0 to the w component. 4 and N cannot both be present. u : The mesh is wrapped in the u-direction, so v[0,j] is connected to v[nu-1,j] for all j. v : The mesh is wrapped in the v-direction, so v[i,0] is connected to v[i,nv-1] for all i. C (before MESH) : Each vertex includes one RGBA(floats between 0 and 1) color for front-facing face. The color for back-facing face is {1-r,1-g,1-b,a}. CC (before MESH) : Each vertex includes two RGBA colors, one for front-facing face, one for back-facing face. N : Each vertex includes a surface normal vector(3 floats). Cannot be present if the object is 4D. C (after MESH) : Whole object has one RGBA color for front-facing faces. The color for back-facing faces is {1-r,1-g,1-b,a}. CC (after MESH) : Whole object has two RGBA colors, one for front-facing face, one for back-facing face. (C before MESH and C after MESH cannot both be present) The order of key characters is insignificant except for the 'C' before or after MESH. And key characters are case insensitive except MESH should be capitalized. This format is a natural choice for parametric surfaces and runs faster than off file format. (2) OFF (.off) Syntax: (can have comments anywhere between # and the end of the line) [4][C][C][N]OFF[C][C] # key words [r g b a] [r g b a] # RGBA colors for the whole object Nvertices Nfaces Nedges # Nedges not used x y z [w] [nx ny nz] [r g b a] [r g b a] # for vertex[0] ... # Nvertices vertices, from v[0] ... # to v[Nvertices-1] Nv i[0] ... i[Nv-1] # Faces, Nv = #vertices on this face # i[0],...,i[Nv-1] are vertex indices # in the range 0..(Nvertices-1) ... # Nfaces faces, from f[0] # to f[Nfaces-1] The meaning of characters is the same as in mesh file format. This format is the most general one, can represent many kinds of surfaces, especially those that have been punched or sewed from several pieces. (3) LIST (.list) Syntax: (No comments are allowed) LIST # keyword # list of file names, including the whole path or # the path from the directory this .list is in. . . . (4) Comments: There are lots of data files in the data directory, and we also include C files that we used to generate those data files in the data/obj-makers subdirectory. In terms of speed (especial under two-color drawing mode), MESH = MESHC = MESHCC >(faster than) CMESH = CCMESH OFF = OFFC = OFFCC > COFF = CCOFF, and *MESH* > *OFF*. By using LIST AND MESHC, you can get a surface that has multiple colors and still runs fast. PALETTE FILE FORMAT (.pl) ------------------- Syntax: (No comments are allowed) PALETTE # Keyword r g b # red, green and blue components between 0 and 1 r g b . . . See the files in the palette directory. The default palette is a palette of rainbow (default.pl). SETTING FILE FORMAT (.set) ------------------- Syntax: (No comments are allowed) SETTING # Starting keyword FOV # field of view, between 5 and 150 NEAR # near clip plane, between 0.1 and 40 FAR # far clip plane, between 0.1 and 40 SCALE # scale of the objects, between 0.1 and 10 SPECULAR # specular, between 0 and 1 SHININESS # shininess exponent, between 1 and 300 BGRED # red component of background color, between 0 and 1 BGGREEN # green component of background color, between 0 and 1 BGBLUE # blue component of background color, between 0 and 1 BGALPHA # alpha component of background color, between 0 and 1 LIGHTPOS <3 floats> # light direction, a point on the unit sphere 4DMAT <16 floats> # 4D rotation matrix 3DROTMAT <16 floats> # 3D rotation matrix in homogeneous coordinate sys 3DTRANMAT <16 floats> # 3D translation matrix in homogeneous coordinate sys The order of keywords is insignificant, and partial lists are ok. See default.set in the setting directory for the default values. This file is very helpful for saving and regenerating scenes. KNOWN BUGS ---------- -- Not all Geomview/OOGL MESH, OFF and LIST files are accepted. For examples, files with braces { or }, or in OFF, colors specified for faces, or in MESH, Z and U prefixes. CREDITS ------- MeshView 1.0 was written initially by Hui Ma (current address Jeff_Ma@ccm.sc.intel.com) and designed by Andrew Hanson (hanson@cs.indiana.edu) and Hui Ma, at Department of Computer Science, Indiana University at Bloomington. Andrew Hanson is in principle the current maintainer. Alternative anonymous ftp sources are geom.umn.edu and ftp.cs.indiana.edu, directory pub/hanson. Any suggestions, comments and bug reports can be sent to hanson@cs.indiana.edu and will be greatly appreciated. NOTES ----- The only SGI-dependent call in the current code is sginap(), which is used to implement a 1/100 second delay. Equivalent system-dependent calls should be substituted in other configurations. We also have a version of MeshView that supports the Logitech 3D mouse and head tracker on SGI machines. To use the true 4D rolling ball model, you have to use a 3D mouse. Contact the authors for further details. We acknowledge NCSA as the original source of several of the color palettes included as examples with MeshView.