------------------------------------------------------------------------------ NCSA Polyview 3.1 Release Notes Gilles Bourhis Software Development Group National Center for Supercomputing Applications University of Illinois at Urbana-Champaign 605 E. Springfield Avenue Champaign, IL 61820 gbourhis@ncsa.uiuc.edu $Date: 93/08/24 10:31:08 $ ------------------------------------------------------------------------------ INTRODUCTION ============ This is the official release of NCSA Polyview 3.1. What is Polyview 3.1? o Polyview 3.1 is a software tool for interactive visualization and analysis of 3D geometrical structures. Polyview 3.1 reads data files in NCSA HDF Vset format and automatically derives animation sequences based on available information. Script-based and graphical user interfaces complement each other in a seamless fashion to allow the easy creation of movie-style animations. Polyview 3.1 also supports ``What You See Is What I See''-style collaborative work among geographically remote Polyview users over a wide-area network. o Polyview 3.1 will run on any Silicon Graphics workstation running IRIX 4.0.1 or later. It uses OSF/Motif for its user interface and IRIS GL for its advanced 3D rendering capabilities. o Polyview 3.1 is a minor upgrade to Polyview 3.0. It provides some bug fixes like correct picking vertices and correct viewing parameters in the RenderMan output facility. There are also some improvements (upgrade to HDF 3.2, easier DTM connection) and some new features like save in rgb format (SGI image format). Polyview 3.0 was a major upgrade to NCSA Polyview 2.0 and was designed by Marc Andreessen. It provides an entirely new and improved user interface, many new features, and lots of bug fixes. However, those of you who have used Polyview 2.0 should feel right at home: the basic layout of the program is the same, mouse actions are the same, scripts should be backwards compatible, data handling is largely the same, and so on. Polyview 2.0 was designed by Brian Calvert. ------------------------------------------------------------------------------ HOW TO DOWNLOAD POLYVIEW 3.1 ============================ To download Polyview 3.1, follow these steps, starting at a Unix prompt: (1) % ftp ftp.ncsa.uiuc.edu (2) Enter username 'anonymous' (without the quotes). (3) Enter password 'yourname@yourmachine' (without the quotes). (4) ftp> cd /SGI/Polyview3.1 (5) ftp> binary (6) ftp> get polyview.Z (7) ftp> quit (8) % uncompress polyview.Z (9) % chmod 755 polyview ------------------------------------------------------------------------------ DOCUMENTATION AND DEMONSTRATION FILES ===================================== These release notes document the differences between Polyview 2.0 and 3.1 and explain how to use the new features provided in Polyview 3.1. If you are unfamiliar with Polyview, you should first read the Polyview 2.0 documentation (anonymous FTP to ftp.ncsa.uiuc.edu in /UNIX/PolyView/PolyView2.0/docs) and then read this file. Demo scripts and datasets are available via anonymous ftp to ftp.ncsa.uiuc.edu in /SGI/Polyview3.1/examples. Files with the extension '.script' are Polyview scripts; files with the extension '.hdf' are HDF Vset files. You will need both sets of files to run the Polyview demos. (Be sure to download the HDF files in binary mode by typing 'binary' at the ftp prompt.) For a basic introduction to Polyview 3.1, download 'coil.script' and 'coil.hdf' and then start Polyview with the command 'polyview -i coil.script'. After you have watched the animation sequence in 'coil.script', you can experiment with the user interface, examine the script and its commands, and run the other sample scripts. ------------------------------------------------------------------------------ QUESTIONS OR PROBLEMS ===================== If you have questions or problems with this release, please contact polyview@ncsa.uiuc.edu; we'd love to hear about them. However, since Polyview 3.1 is an unfunded project and we have only limited resources for supporting it, we may not be able to respond to your questions and problems as quickly or as thoroughly as we would like. If you would like to help fund maintenance and development of Polyview (and thus provide us with the resources to definitely handle any questions or problems you may have), please call Gilles Bourhis at (217) 244-0013 or send email to gbourhis@ncsa.uiuc.edu. ------------------------------------------------------------------------------ INPUT DATA FORMAT ================= Polyview takes HDF Vset format (now is a subset of HDF3.2 or later). Vset is designed specifically for unstructured data where connectivity is explicit. This means to render the surface, you must supply connectivity list as well as the coordinates. Polyview can only handle polygonal data. Using HDF-UCD library (libucd.a) to generate HDF Vset format if you have unstructured or structured cell data. Polyview 3.1 is compatible with HDF UCD 1.1. You can find HDF UCD library and source code in directory SGI/HDF-UCD on this server. ------------------------------------------------------------------------------ NEW FEATURES ============ New user interface ------------------ Polyview has a new Motif-based user interface. This makes interacting with Polyview more convenient and user-friendly. New features of the user interface are detailed below. Main window ~~~~~~~~~~~ The main (status) window now contains a menubar, a command entry area (which replaces the previous shell-based command line), and a command history list. As you enter commands into Polyview via the command line or by working with the various parts of the user interface, they are stored in the command history list, where they can be 'recalled' with a simple mouse double-click. The main window's menubar contains the following (new) entries: o File->Load Script: This option pops up a Motif file selection box from which you can choose a Polyview script file to run. o File->DTM In/Out: See the section on ``Collaborative Polyview'' below. o Options->Audible: Choose this entry if you want to experiment with an ``audible'' user interface: various actions in Polyview will generate sound via the sound hardware in the IRIS Indigo or Personal IRIS 4D/35. (If you have a different model IRIS, no sound will be generated.) o Options->Hardware Dither: Choose this entry if you want to disable hardware dithering in Polyview's GL windows. We recommend you leave this option enabled. Polyview window ~~~~~~~~~~~~~~~ The polyview window now contains a menubar, as well as a couple of additional Motif widgets. o The 'Active' toggle button indicates whether or not this polyview window is currently active. Only one polyview window will be active at any time. This toggle will accurately reflect the internal state of Polyview at all times: if you do something in a non-active polyview window, that window will become active and the toggle will correspondingly be automatically set. You can also set the toggle explicitly to make any polyview window active. o See the section on ``Collaborative Polyview'' below for details on the 'Blast Image' pushbutton. The polyview window's menubar contains several new features: o File->Load Vset pops up a dialog box from which you can select both the HDF Vset data file you wish to load into the polyview window as well as the identities of various data elements in that data file. For example, instead of entering 'data x-axis coord1' on the command line (as you may have had to do with Polyview 2.0), you can just type 'coord1' in the text entry field next to 'X Axis Vdata name' in the dialog box. (Do *not* press Return/Enter in the dialog box unless you are ready to load a file, as this will trigger the 'OK' button and cause a sequence of file-loading commands to be sent to Polyview.) o File->Send Vset: see ``Collaborative Polyview'' below. o File->Save HDF opens a dialog box in which you can name an HDF image output file. As in Polyview 2.0, the name will have a numeric value inserted into it, as with Polyview 2.0; e.g., foo.hdf will become foo0000.hdf (for the first image), foo0001.hdf (for the second image), and so on. o File->Save Ray opens a dialog box in which you can name a file that will become a Rayshade 4.0 input file. Rayshade 4.0 is a high-quality raytracer (image renderer) available to the public via anonymous FTP to princeton.edu (in /pub/Graphics/rayshade.4.0). o File->Save RenderMan opens a dialog box in which you can name a file that will become a RenderMan input ('rib') file. This file can then be fed to Pixar's PhotoRealistic RenderMan software to create very high quality renderings of Polyview scenes. (For more information on RenderMan, contact Pixar, 1001 West Cutting Boulevard, Richmond CA, 94804, (415) 236-4000.) o File->Save RGB opens a dialog box in which you can name a file that will become an image file in rgb (using SGI "libimage.a") format. You can later see this picture with tools like "ipaste". Render allows you to specify various attributes for the rendered scene. Particularly significant are the following new features. o Render->Draw->Hidden Edges is a new drawmode. Hidden edges are ``faked'' by drawing the object with black polygons and then drawing the edges in color. o Render->Line Width pops up a small dialog box in which you can set the line width for drawmodes 'edges', 'hidden edges', and 'outlined faces'. o Render->Outline Color pops up a small dialog box in which you can set the outline color for drawmode 'outlined faces'. This is useful for contrasting the outlines with your current palette and dataset. o Render->Vertex Spheres pops up a small dialog box in which you can manipulate the 'spheres at vertices' feature. When using drawmode 'vertices', if 'sphere size' is not 0.000 then spheres (rather than points) will be drawn, with the specified radius. 'sphere depth' controls the quality (number of polygons) of the spheres. Depth 1 corresponds to cubes. Caution: high sphere depths take a *long* time to draw. o Props->Legend puts a strip representing the current colormap in the upper left corner of the polyview window. As with Polyview 2.0, holding down the left mouse button and moving the mouse draws a selection rubber-band on the window. The shift key plus the left button does the same thing, but a new selection will have an ``exclusive or'' effect. (Experiment with this to find out what that means.) The middle button causes object rotation. The shift key plus the middle button causes object zoom. Caution: the window system will not tell Polyview that the shift key has been pressed or released if the mouse pointer is outside the GL (3D) drawing area when the press or release occurs, and Polyview may correspondingly become confused. If this happens, just tap the shift key after moving the mouse pointer inside the GL drawing area to reset Polyview's internal state. Palette window ~~~~~~~~~~~~~~ The palette window now contains a menubar. o File->Load HDF/Raw: These options pop up a dialog box in which you can specify a palette file to load. o File->Save HDF/Raw: These options pop up a dialog box in which you can specify the name of a palette file to save. o Palette: There are some new default palettes. 'All Yellow' may be useful when using lighting in your scene, as using only a single color in the scene increases lighted rendering speed substantially. (Any palette with the same value in all entries will cause this performance increase.) o Backdrop: You can select from an assortment of colored and shaded backdrops for the active polyview window. Info window ~~~~~~~~~~~ The info window now consists of a Motif text widget. There are several differences from the original scheme because of this: o Text in the info window can be cut and pasted into other windows on the screen. o Information for all selected elements (vertices, faces, or objects) is thrown into the window at once (although a scrollbar is present in case all the information doesn't fit in the window). o Because all information is thrown into the window at once, there is a ``reasonableness limit'' (currently set to 300) on the number of selected elements for which information is displayed. This is to keep updating the info window from taking forever. Since we can't imagine anyone usefully selecting hundreds of elements at a time in any case, we don't think this will be a problem. Time window ~~~~~~~~~~~ The time window is essentially unchanged (except for its new Motif look and feel). New functionality ----------------- RGB Mode and Palette Fiddling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Polyview runs entirely in RGBmode now. Palette fiddling may be somewhat slower than before, since the scene is now redrawn each time the palette is changed. Hardware Lighting ~~~~~~~~~~~~~~~~~ Polyview supports hardware lighting now. Currently, only one light is supported. Six commands can be used to activate/position the light: light one light two light three light x light y light z Control over the lights is also available in the Render menu in a polyview window. In addition, the lighting can be made to affect both sides of polygons. This is generally preferred to ``single-sided'' lighting, and so it is the default. The commands 'light twoside on' and 'light twoside off' can be used to turn twosided lighting on and off. On most SGI platforms there will be a substantial rendering performance impact while running with lighting on and with a multicolor palette (as compared to running without lighting). This performance drop is intrinsic to the graphics hardware and cannot be avoided by Polyview. To help decrease this drop in performance, there is a new palette entry, 'all yellow'. It can be selected from the palette window menu as usual or with the command 'palette use allyellow'. When running with this palette (which consists of only one color) or a similar palette, rendering speed with lighting will be considerably faster than with multicolor palettes. Vertex Spheres ~~~~~~~~~~~~~~ Polyview 3.1 allows you to represent vertices as spheres. These spheres can be of variable size and complexity, and can be lighted. To display vertices as spheres, first do 'draw vertices'. Then do 'sphere size 0.1', where 0.1 is the desired radius of each sphere in your world coordinate system. You can also do 'sphere depth 3' to adjust the complexity (depth of tesselation, aka number of polygons) of each sphere, where 3 is the desired depth. The default sphere depth is 2. Value 1 collapses the spheres into cubes, which can be desirable in their own right. Theoretically depth can range up to 30, but numbers higher than 4 or 5 will cause inordinately slow redrawing rates for most datasets. The spheres will be given the colors the vertices normally have, and if lighting is enabled they will be shaded appropriately. Line Width and Outline Color ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You have full control over the width of lines used in drawmodes 'edges', 'hidden edges', and 'outlined faces' via the 'draw linewidth' command. The default linewidth is 1; higher widths (especially 2, 3, or 4) may be useful in some situations. Keep in mind that these are pixel widths, so no matter how small or large the *object* is in the window, the line width remains constant with respect to itself. Palette Fiddling ~~~~~~~~~~~~~~~~ Palette fiddling works the same as in Polyview 2.0, with two exceptions. First, since Polyview 3.1 uses RGB mode at all times, each time the palette is fiddled all polyview windows must be redrawn in order to have the altered palette take effect; so, performance takes a necessary hit. Second, every palette fiddle produces an instance of the new 'palette fiddle' command, which is added to the history list on the fly; thus, palette fiddling can now be part of a script file. Outlined Faces ~~~~~~~~~~~~~~ The rendering code used for drawmodes 'outlined faces' (and now 'hidden lines' also) has been substantially revised to give better visual results for all datasets from all viewing angles and distances. This should eliminate any problems with lines ``breakin up'' in 'outlined faces' mode. Backdrops ~~~~~~~~~ A new command, 'backdrop', lets you place colorful smooth-shaded backdrops behind your image in place of the standard black backdrop. Possible backdrops are: backdrop solid [black|white|grey|blue|red] backdrop shaded [rgby|rgblue|rbblack] backdrop [horizon|sky|streak|smear] [blue|red|green|yellow] Props ~~~~~ Grids, shadows, and boxes look a little different (and, we hope, better) now. In addition, there is a new prop, 'legend'; this is simply a palette strip placed in the upper left corner of the window. Time Animation Bouncing ~~~~~~~~~~~~~~~~~~~~~~~ A new command, 'time bounce [on|off]' can be used to enable bouncing in the animation modes. With bouncing enabled, an animation sequence (e.g. 'time forward') will change direction (forward to reverse or vice versa) when reaching the n'th of n frames (if moving forward) or the 1st frame (if moving backward). Try it; you'll know what I mean. Blocking Time Forward/Backward ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Two new commands are available for time-based animation. They are 'timeblock forward' and 'timeblock reverse'. Normally, 'time forward' and 'time reverse' are used to step through a number of frames automatically. However, these commands don't ``block''; that is, cause Polyview's script interpreter to wait until they're finished before going on to the next command. 'timeblock forward' and 'timeblock reverse', however, cause Polyview to animate through the specified number of frames before doing anything else. For the timeblock commands, you must supply an argument, framecount; e.g., 'timeblock forward 12'. Pause Command ~~~~~~~~~~~~~ Another new animation-control command is 'pause', which allows you to effectively cause Polyview to freeze for a specified amount of time in the middle of a script. 'pause' requires an argument, which is the number of time units to pause (20 time units to a second). HDF Image Output ~~~~~~~~~~~~~~~~ Polyview now supports a vastly superior color quantizing algorithm to convert the 24-bit (or pseudo-24-bit) screen image into an HDF 8-bit raster image for 'save image'. The algorithm is by Wu from the book Graphics Gems II (ed James Arvo, pub Academic Press), and is the most efficient algorithm for very-high-quality quantization that I know of. (If you think you know of a better algorithm, please let me know.) Renderman and Rayshade Output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Two new commands, 'save ray' and 'save renderman', allow you to save the current scene into Rayshade 4.0 and Pixar RenderMan files, respectively. Rayshade 4.0 is a high-quality raytracer (image renderer) available freely to the public via anonymous FTP to princeton.edu (in /pub/Graphics/rayshade.4.0). RenderMan files can be fed to Pixar's PhotoRealistic RenderMan software to create very high quality renderings of Polyview scenes. (The RenderMan output feature in Polyview 3.1 is still experimental and is not guaranteed to work. For more information on RenderMan, contact Pixar, 1001 West Cutting Boulevard, Richmond CA, 94804, (415) 236-4000.) ------------------------------------------------------------------------------ COLLABORATIVE POLYVIEW ====================== Polyview includes support for NCSA's DTM (Data Transfer Mechanism), a network protocol designed to support transmitting and receiving scientific data and messages over a wide-area network, such as the Internet. Polyview can communicate with other clients that use DTM or with other instances of Polyview on the network. Introduction to Collaborative Work .................................. The term 'collaborative session' means a situation wherein two or more people are hooked together over the network for collaborative work. In general, we assume that a telephone conversation is occurring simultaneously with a collaborative session, allowing participants in the session to keep in touch with what each person is doing. This removes the need for each collaborative tool (e.g. Polyview) to provide the baseline personal communication capabilities. Polyview's collaborative support is part of an ongoing effort at NCSA's Software Development Group to develop collaborative tools for scientists and researchers who wish to work together on data exploration and analysis over long distances via a wide-area network. This effort is ongoing, and suggestions for future capabilities are more than welcome (mail polyview@ncsa.uiuc.edu). Sending Raster Images To NCSA Collage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Polyview provides support for sending raster images of the current scene to a DTM client capable of receiving them. One such client is NCSA Collage for X Window System platforms (obtainable via anonymous ftp to ftp.ncsa.uiuc.edu in /Collab/XCollage/Collage1.2Beta). Connection .......... If you have a Collage client running on an X workstation and it's ready to receive DTM data, and you have a scene in Polyview (on another machine) that you wish to send to the Collage session, choose File->DTM Out from the main Polyview window's menubar and type 'machinename:8888' (where 'machinename' is the name of the machine running Collage and '8888' is the port that Collage is listening on), and press 'Activate'. (If you are connecting to an ongoing collaborative session, you should connect to the DTM server rather than to an individual Collage client. Existing members of the collaborative session will be able to tell you which port to connect to.) Sending Images .............. Once you have connected and are back in the polyview window containing your 3D scene, you can press the 'Blast Image' button (below the menubar) to send the current scene to Collage as a raster image. Pressing the 'Blast Image' button causes Polyview to execute the 'blast image' command, which is equivalent to the 'save image' command except that 'blast image' uses DTM. Similarly, 'blast mode continuous' is equivalent to 'save mode continuous' and can be used to tell Polyview to send a new raster image over DTM every time the window is redrawn, and 'blast mode single' or 'blast stop' can be used to turn off the continuous image blasting. If you operate with 'blast mode continuous', Collage will replace the Polyview image (rather than opening a new window) each time a new image is received; thus, Collage can actually display animation sequences provided by Polyview as fast as the network will allow. Polyview-To-Polyview Collaboration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Polyview provides support for ``What You See Is What I See'' collaboration among multiple users at remote geographical locations. Polyview allows you to distribute both data and program commands among multiple Polyview instances. (In this context, 'instance' means a running instantiation of Polyview.) So, for example, that a Polyview instance running in Michigan can send its 3D data directly to a Polyview instance running in Texas, over the Internet. The researcher in Texas could spin the object with the mouse and then animate through a sequence of frames, and the Michigan Polyview would automatically follow suit in exactly the same manner. Hooking Up Two Polyview Instances ................................. Let's follow the steps two Polyview users, ``Bill'' and ``Ted'', take to hook up two Polyview instances. Bill and Ted decide to collaborate: (1) Bill and Ted each start up Polyview on their respective workstations (bill.cs.tech.edu and ted.cs.tech.edu). Bill tells his machine to listen for a connection from Ted's machine: (2) Bill chooses 'File->DTM In' from the menubar, types ':8888' (without the quotes) into the dialog box, then presses 'Activate'. [In general, any number in the range 7000 to 9999 is probably going to be safe to use; 8888 is an arbitrary choice.] The listener should not give a machine name before the colon : he listen on his machine. Ted tells his machine to talk to Bill's machine: (3) Ted chooses 'File->DTM Out' from his Polyview menubar, types 'bill.cs.tech.edu:8888' (without the quotes) into the dialog box, then presses 'Activate'. Bill and Ted are now connected. Using Polyview Collaboratively .............................. When two Polyview instances are connected (as described above), anything that happens in one instance is echoed in the other instance, and vice versa. Since 3.1, you don't need to explictly send the data : when a user load datas from a file, it is distributed to the other instance. However, if a user has already loaded datas before beeing connected, he can send them choosing File->Send Vset from his polyview's window menubar. Let's watch Bill and Ted again. Bill opens a polyview window: (1) Bill chooses Windows->Open Polyview from his main window's menubar. A polyview window opens in both Bill and Ted's Polyview instances. Bill loads a dataset: (2) Bill chooses File->Load Vset from his polyview window's menubar. He chooses 'coil.hdf' and presses 'OK'. Bill sees the coil, and some seconds after, Ted sees the coil. Ted rotates the coil: (3) Ted yells, ``Hey Bill, I'm gonna rotate it.'' By holding down the middle mouse button and moving the mouse, Ted rotates the coil to a new position. When he releases the mouse button, the new position is sent automatically to Bill's Polyview instance, which rotates the coil to match. Bill changes the drawing mode: (4) Bill yells, ``Hey Ted, I'm gonna change the drawing mode.'' Bill chooses Render->Draw->Outlined Faces from the polyview window's menubar. The drawing mode changes for both Bill and Ted. Bill and Ted can go on to do things like animate through time sequences via the time window, fiddle with the palette in the palette window, add props or lighting to the scene, etc. Notes On Using Polyview Collaboratively ....................................... o Generally, it will prove to be confusing if both people do things in Polyview at the same time. You'll benefit by switching ``control'' back and forth as the collaborative session progresses. o Polyview's pick/select feature will work collaboratively, but it currently requires that both instance's polyview windows be the same size in order for results to be the same in both instances. So, if you're going to collaborate and still expect to use pick/select, don't resize the window. o Although Polyview supports multiple polyview windows at a time, it currently only makes sense to have one polyview window open during a collaborative session. o You can certainly run two Polyview instances on a single workstation and connect them, e.g. to experiment with Polyview's collaborative capabilities. In this case, you can leave the host address out of all DTM port ID's (e.g. ':1393' rather than 'mymachine.cs.tech.edu:1393'). You should know that some combinations of Silicon Graphics hardware and software (for example, the author's Indigo XS with IRIX 4.0.2) do not handle multiple GL windows very well. Thus, you may see exploding polygons and other undesirable graphics effects. These will not break Polyview, but if this happens, just keep in mind that it's not *our* fault that it's happening. o Polyview 3.1 also accepts DTM SDL (Surface Description Language) 3D data. Polyview's Vset/Vdata class is still experimental and has not yet been released as part of DTM proper. If you want to use Polyview to view 3D data being generated by a simulation (e.g. from a Cray or an RS/6000), we currently recommend you use SDL. See the DTM documentation for more details (anonymous ftp to ftp.ncsa.uiuc.edu in /Collab/DTM). Using 3+ Polyview Instances Collaboratively ........................................... If you want to link up more than two Polyview instances, you will have to use a DTM ``server'' (nammed collage_server). A DTM server is a process that manages a collaborative session among multiple DTM clients; each DTM client connects directly to the server, and all data sent to the server by one client is distributed to all the other clients. Doing Polyview-to-Polyview collaboration through a server has not been tested at NCSA due to resource constraints. However, there is no reason that it shouldn't work, and you are encouraged to experiment. You can obtain NCSA's DTM server via anonymous FTP to ftp.ncsa.uiuc.edu in directory /Collab/XCollage/Collage1.2Beta. ------------------------------------------------------------------------------ KNOWN PROBLEMS ============== Pick/select on large datasets occasionally causes coredumps within the GL library. We have been unable to determine whether this is a Polyview problem or a problem with the system software. There is no PostScript output facility. There should be. ------------------------------------------------------------------------------