http://www.sgi.com/tech/relnotes/explorer.html (Silicon Surf Promotional CD, 01/1995)4 Known Problems and Workarounds
- 1 - 1. Introduction Note: These release notes describe IRIS Explorer version 2.2, which incorporates changes from versions 2.0 and 2.1. Version 2.2 runs on IRIX 5.2 or higher. The IRIS Explorer product is a system for combining components called modules to create powerful customized visualization applications. Modules linked this way form an IRIS Explorer Map. Modules in a map can execute on a collection of networked computers, with IRIS Explorer providing the distributed application framework. The explorer utility (Map Editor) is the primary way to interact with modules that are cooperating as an aggregate Explorer application. The Map Editor creates and destroys modules, makes and breaks connections between modules, and operates controls for the modules. The mbuilder utility (Module Builder) builds new Explorer modules from existing subroutines written in C, C++, or Fortran (even without source). With the Module Builder, you can create graphical user interfaces for modules without reprogramming their source code. The dscribe utility (DataScribe) helps you make modules to convert your data files to and from Explorer's internal formats without programming. You can also use the DataScribe to write out data from Explorer modules to disk without programming. IRIS Explorer is included at no cost with each Silicon Graphics workstation. Explorer can be ordered for existing workstations at a nominal media charge (see the documentation ordering information below). Explorer is also available from DuPont Pixel for SPARC workstations, and from Numerical Algorithms Group, Ltd., for Cray Research computers, SPARC workstations, and several other types of workstations. The Explorer documentation is available as a separate product from Silicon Graphics. It is a full-color, three- volume set: IRIS Explorer User's Guide IRIS Explorer Reference Pages IRIS Explorer Module Writer's Guide To order the documentation (product code M4-EXPLR-2.0), call: 1-800-800-SGI1 if you are in North America. - 2 - If you are outside North America, please contact your sales representative or your service provider. Additional information is available from PostScriptO files included in the explorer.man subsystem, as well as from online man pages for modules and all Explorer routines. Note: Packaged with these release notes is a separate sheet that contains the Software License Agreement. This software is provided to you solely under the terms and conditions of the Software License Agreement. Please take a few moments to review the Agreement. This document contains the following chapters: 1. Introduction 2. Installation Information 3. Changes and Additions 4. Known Problems and Workarounds 5. Documentation Errors 1.1 Release_Identification_Information Following is the release identification information for IRIS Explorer: Software Option Product IRIS Explorer Version 2.2 Product Code SC4-EXPLR-2.0 System Software Requirements IRIX 5.2 Related Library Requirements IRIS Inventor 1.1.2 (for non-OpenGL systems) IRIS Inventor 2.0 (for OpenGL systems) 1.2 Hardware_Requirements The minimum memory requirement is 24MB; 32MB is recommended. When visualizing very large datasets or using many modules, you need more physical memory to efficiently perform the calculations without virtual memory paging (swapping). A 24-bit plane (or a virtual 24-bit plane) frame buffer is required for this product. This includes all Silicon Graphics workstations except Personal IRIS systems with 8 - 3 - bitplanes. Z-buffering is required for proper rendering. Systems that do not have z-buffering are IRIS Indigo XS, Indigo XS24, and some models of Personal IRIS with G-level graphics. Two-sided lighting support is desirable for properly rendering some geometries. Graphics models that do not support two-sided lighting include Personal IRIS systems and systems with IRIS-4D/GTX graphics. Additionally, Indigo Entry and XS systems do not display two-sided lighting in Explorer. Indigo-quality audio is required for correct operation of certain modules in the sgi_modules subsystem. All such modules have Audio in their names. Video hardware is required for the correct operation of certain modules in the sgi_modules subsystem. All such modules have Video in their names. Reality Engine graphics are required for correct operation of the RealityRender module from the sgi_modules subsystem. 1.3 Online_Release_Notes After you install the online documentation for a product (the relnotes subsystem), you can view the release notes on your screen. If you have a graphics system, select ``Release Notes'' from the Tools submenu of the Toolchest. This displays the grelnotes(1) graphical browser for the online release notes. Refer to the grelnotes(1) man page for information on options to this command. If you do not have a graphics system, you can use the relnotes command. Refer to the relnotes(1) man page to access online release notes. 1.4 Product_Support Silicon Graphics, Inc., provides a comprehensive product support maintenance program for its products. If you are in North America and would like support for your Silicon Graphics-supported products, contact the Technical Assistance Center at 1-800-800-4SGI. - 4 - If you are outside North America, contact the Silicon Graphics subsidiary or authorized distributor in your country. - 1 - 2. Installation_Information This chapter lists supplemental information to the IRIS Software Installation Guide. The information listed here is product-specific; use it with the Installation Guide to install IRIS Explorer. 2.1 IRIS_Explorer_Subsystems The IRIS Explorer distribution includes these subsystems: explorer.links.* IRIS Explorer local environment, including shared libraries and X Window System application defaults files. This subsystem is the minimum required on any system running Explorer modules. All other subsystems can be accessed by mounting, via NFS, a remote file system containing those subsystems on your workstation. explorer.sw.eoe IRIS Explorer Map Editor, DataScribe, run-time dynamic shared objects and associated controllers. This is the basic execution environment for the Map Editor and DataScribe subsystems. explorer.sw.modules IRIS Explorer module executables. This release includes approximately 160 modules. See also the subsystems explorer.sw.sgi_modules and explorer.sw.unsupported_modules for other modules. explorer.sw.sgi_modules IRIS Explorer module executables for device dependent features, such as audio and video operations. This release includes approximately 20 such modules. explorer.sw.unsupported_modules IRIS Explorer module executables contributed by users. These modules are provided as-is without support from Silicon Graphics. This release includes approximately 75 such modules. explorer.sw.dev IRIS Explorer module development environment, including the Module - 2 - Builder utility. This includes header files and other utilities required to create new Explorer modules. explorer.sw.source IRIS Explorer module source code for approximately 170 Explorer modules, which you can customize and/or use for coding examples. explorer.sw.data IRIS Explorer sample data files. These are needed to run the tutorials in Chapter 1 of the IRIS Explorer User's Guide. In addition, several other datasets are included for your use. explorer.sw.data_geosphere Earth images from The GeoSphere Project and projection conversion software. These images are three projections approximately 512x1024 in size, of ``the cloudless earth'' images, produced by Tom Van Sant, Inc., and are redistributed here with permission. explorer.man.doc The IRIS Explorer User's Guide and the IRIS Explorer Module Writer's Guide, in PostScript form, suitable for online viewing or printing. The contents of the IRIS Explorer Reference Pages document are contained in other explorer.man subsystems. explorer.man.man IRIS Explorer utility, application programming interface (API), and header file man pages (sections 1, 3, and 4) from the IRIS Explorer Reference Pages document. API routines new to IRIS Explorer 2.2 are only documented in their online manual pages. explorer.man.modules IRIS Explorer module man pages. Many of these manual pages are also in the IRIS Explorer Reference Pages. Modules new to IRIS Explorer 2.2 are only documented in their online manual pages. - 3 - explorer.man.relnotes IRIS Explorer release notes (this document). explorer.man.sgi_modules IRIS Explorer module man pages for modules contained within the explorer.sw.sgi_modules subsystem. Many of these manual pages are also in the IRIS Explorer Reference Pages. Modules new to IRIS Explorer 2.2 are only documented in their online manual pages. explorer.man.unsupported_modules IRIS Explorer module man pages for modules contained within the explorer.sw.unsupported_modules subsystem. Most of these modules are new to Explorer 2.2 and hence are only documented in their online manual pages. 2.2 IRIS_Explorer_Subsystem_Disk_Space_Requirements This section lists the subsystems (and their sizes) of the IRIS Explorer option. If you are installing this option for the first time, the subsystems marked ``default'' are installed if you use the ``go'' menu item in inst. To install a different set of subsystems, use the ``install,'' ``remove,'' ``keep,'' and ``step'' commands in inst to customize the list of subsystems to be installed, then select the ``go'' menu item. Note: The listed subsystem sizes are approximate. Refer to the IRIS Software Installation Guide for information on finding exact sizes. Subsystem Name Subsystem Size (512-byte blocks) explorer.links.dev 59 explorer.links.eoe 13 explorer.man.doc 7459 explorer.man.man 1738 explorer.man.modules 659 explorer.man.relnotes 81 explorer.man.sgi_modules 62 explorer.sw.data 7534 explorer.sw.data_geosphere 4551 explorer.sw.dev 6658 - 4 - explorer.sw.eoe 28996 explorer.sw.modules 21648 explorer.sw.sgi_modules 8896 explorer.sw.source 17338 explorer.sw.unsupported_modules 23418 __________________ Total 129110 2.3 Installation_Method All of the subsystems for IRIS Explorer can be installed using IRIX installation. You do not need to use the miniroot. Refer to the IRIS Software Installation Guide for complete installation instructions. 2.3.1 Linking_IRIS_Explorer If you have insufficient space under /usr for the subsystems you intend to install, you can create an empty directory in a disk partition containing sufficient space, and create a symbolic link to it from /usr/explorer. To do this, use the following commands (replacing x with the name of a partition containing sufficient space): mkdir /x/explorer ln -s /x/explorer /usr/explorer Then, run inst as usual. Do not use the -r option with inst. If you already have Explorer installed, you must remove it before creating the symbolic link mentioned above. Otherwise inst will delete your symbolic link as it installs the software, resulting in a broken installation. You can remove Explorer by using the command versions remove explorer 2.3.2 NFS-Mounting_IRIS_Explorer You can NFS-mount /usr/explorer from another system onto your own workstation. Ask your system administrator to set this up for you. Your system administrator may use the -r option with inst when installing Explorer on the file server. If you NFS-mount Explorer, you must still install the links for X Window System application default files and Explorer shared libraries. To do this, you can use inst (as root), once the NFS mount is established: inst -f /usr/explorer/lib/inst/explorer - 5 - You are prompted with a menu of options. Select ``go'' to install the correct set of symbolic links onto your workstation. To remove these links in the future, type: versions remove explorer.links 2.4 Prerequisites Version 2.2 of IRIS Explorer is designed to be compatible with IRIX 5.2, and will not work on earlier versions of IRIX. The motif_eoe subsystem is required for Explorer to run. Even if Explorer is installed on a graphics-less server and used via the X Window System to open windows on a graphics- full workstation, the motif_eoe software must be installed on that server in order to have the shared libraries available. You must have a compiler to develop new Explorer modules; therefore, you must have the IRIS Development Option (IDO) if you want to create new modules. However, a C-like array language interpreter that does not require IDO (the LatFunction module) is provided with Explorer for prototyping simpler modules. For displaying the output of the Render, DisplayImg, and TransformGen modules, a display is required that renders the Graphics Library or OpenGL. These modules do not render to a purely X Window System display. IRIS Inventor, execution-only, is required to run modules that produce or consume geometry datasets. Thus Inventor 2.0 subsystem inventor_eoe.sw.inventor is a prerequisite of explorer.sw. The correct version of Inventor to install depends on whether OpenGL is available for your system. IRIS Inventor version 2.0, execution-only, is required for OpenGL systems (Indigo, Indigo^2, Indy and VTX, Reality Engine, and RE2 graphics). IRIS Inventor version 1.1.2, execution-only, is required for non-OpenGL systems (Personal IRIS, GT(X) and VGX(T) graphics). Both Inventor execution- only subsystems can be loaded from the Inventor 2.0 distribution, where they have names inventor_eoe.sw.inventor and inventor_eoe.sw.1_1. The development option for Inventor (inventor_dev.sw) is not required to write modules that produce geometry using Explorer's cxGeometry library, but it is required to write modules that read or manipulate Inventor geometry objects directly. - 6 - 2.5 Configuration_Files The default preferences file for Explorer is /usr/explorer/Explorer.config. It contains the default locations of modules and maps, establishes module categories, and sets the shared memory arena size. You can customize your own preferences by editing the sample.explorerrc file in /usr/explorer and saving the updated copy under the name .explorerrc in your home directory. 2.6 Other_Installation_Information Modules built under Explorer version 2.0 or 2.1 will run in Explorer 2.2. Module resource files, map files, DataScribe script files, and saved lattice or pyramid files have not changed in structure between versions 2.0 and 2.2. Note: IRIS Explorer version 2.2 is incompatible with IRIS Explorer version 1.0 in certain areas: o Modules built under version 1.0 must be recompiled and relinked for use with version 2.2. The command protocol used between the components of an Explorer program has changed significantly from version 1.0, causing this incompatibility. If you have developed your own modules, rebuild each of them: 1. Update the module resource file (see below) 2. Remake the Makefile with the command: make Makefile Rebuild your modules with: make install 3. Module resource files, saved map files, DataScribe script files, and saved pyramid files have changed in structure between version 1.0 and 2.0, but not from version 2.0 to 2.2. Version 2.2 can read any of these version 1.0 files with some loss in efficiency. It is recommended that you update these files with the provided program cxupdate. See the cxupdate manual page for details. Once files have been converted, they are in 2.x native format and can be - 7 - read more efficiently by this release. Geometry created by modules using Inventor 2.0 cannot be handled by Inventor 1.x based modules. You must rebuild the Inventor 1.x based modules, as detailed above. Geometry files produced by Inventor 1.x modules (eg, Explorer 2.0 or 2.1 modules) can still be read in Explorer 2.2. In order to uncompress and print these PostScript documents, you use the zcat and lp commands. For instance, to print chapter 5 of the IRIS Explorer User's Guide, you could use a command of the form: /usr/bsd/zcat /usr/explorer/doc/userguide/Chap5.ps.Z | lp - 1 - 3. Changes_and_Additions This chapter lists the changes and additions in IRIS Explorer since the 2.0 release. 3.1 General o Support for Open Inventor is provided. The Explorer ``geometry'' data type, which is really an Inventor scene graph, now uses the OpenGL-based Open Inventor (Inventor 2.0) on OpenGL-capable machines. On machines that do not support OpenGL (Personal IRIS, GT(X), and VGX(T)), the Explorer geometry library relies upon Inventor version 1.1.2. o There are new modules for volume rendering, pyramid manipulation, feature extraction, color editing and video input. o There are many new unsupported modules. Capabilities include color manipulation, axes, multi-channel lattice support, readers and feature extraction for molecular chemistry, readers and writers for many image formats, finite element pyramid readers and manipulators, computational fluid dynamics operations, gnuplot and Mathematica interfaces, world mapping and cartography, as well as many others. Most of the unsupported modules are also distributed in source form so that you may customize and modify the modules as needed. Many of these modules are written and contributed by Explorer users. None of these modules is supported by Silicon Graphics. o Explorer now supports Motif drag and drop, in which module file icons or filename strings may be dragged onto the Map Editor, Module Builder, or Data Scribe. o RenderLite has been removed from the module suite. 3.2 Map_Editor o The default font for the Map Editor has been changed to a Helvetica font in the default font set. This reduces system disk usage by not requiring installing of optional X Window fonts. o Modules may now be replaced through a menu item on the module mini control panel. Module replacement preserves connections and widget values, launching a new disabled module in place of the old one. This feature is used - 2 - primarily by module developers. o Automatic replacement by the Map Editor of modules that have exited is more robust. o The Explorer log window responds to user input. It may be edited, cleared, or marked as view-only (the default). o The scrolled list widget is more robust regarding the selection of items and module control of selected items. o Modules' connections may now be deleted and restored through a menu item on the module mini control panel. The user may select input, output, or all connections for deletion or replacement. This action operates on all selected modules (highlighted white in the Map Editor). 3.3 Scripting_Language Documentation for all scripting commands may be found by typing (help) at the skm prompt when Explorer is started with the scripting option. For instance, start Explorer as follows and then ask for help at the prompt. explorer -script - skm> (help) A few commands in the Skm scripting language have been modified, as follows: display The display command is now renamed explorer-display. start Now accepts an optional hostname on which to start the module. start-map Now accepts an optional hostname on which to start the map. The following new commands have been added to the Skm scripting language: connection-list Return the list of connections to a module. duplicate Duplicate one or more modules. - 3 - filename-to-parts Split a filename into the four parts host, directory path, file base name, and suffix. get-module-x-y Return the location of a module mini control panel in the Map Editor. get-pfunc Return the parameter function for a particular module port. module-to-filename Return the filename of the module executable. module-to-host Return the host on which the module executable resides. param-list Return the list of parameter ports of a module. pfunc-list Return the list of parameter functions (pfuncs) of a module. set-module-x-y Move a module mini control panel to a specified location in the Map Editor. set-pfunc Set the parameter function for a particular module port. set-x-y Set the insertion point in the Map Editor. 3.4 Module_Suite o The Render, RenderRemote, and other cxGeometry modules now use Inventor 2.0 on OpenGL-capable systems (VTX, Indigo family, and RealityEngine). On Personal IRIS, GT(X), and VGX(T) systems, the Render and RenderRemote modules continue to use Inventor 1.1. There are three main feature changes in the Inventor 2.0-based modules in addition to using OpenGL. Popup menus now use overlay planes so as not to induce redrawing of rendered scenes. There are bounding box and reduced polygon modes during camera changes. And Render is capable of off-screen rendering (although it still requires and uses graphics hardware to do this). - 4 - o BoundBox and other modules now use the cxParamColor API calls to set the color of an object from a text typein widget. Other modules that use the API include Annotation, BoundBoxPyr, DisplayImg, Legend and WireFrame. o The ClipPyr module now accepts compressed pyramids on input. It has been improved to cap clipped cells. It also provides a slicing plane when Intersect and Interpolate modes are chosen. The new module is substantially faster than previous versions. o The CompressPyr module is now able to compress pyramids containing elements not identified in the default dictionary. Previous versions produced compressed pyramids with incorrect face normals in some cases. o The ExteriorPyr module now finds the exterior of 2D, as well as of 3D, pyramids. o The GenLat module reflects the newer mathematical function library and produces a 255 byte value instead of 254 in the default, sinusoidal operational mode. o The HistNormImg module reflects the behavior of a new ilHistNorm operator in the ImageVision library. The new operator seems to normalize byte images to a smaller range than 0-255, yielding different output than in previous versions of Explorer. o The ILController module has better support for user- defined image processing operators. It is also distributed in source code form for easier modification. o The Interpolate module has been fixed to remove a memory error that leaked data on each firing. o The LatFunction module no longer has problems stacking a sliced array. The previously erroneous behavior was apparent when performing operations of the form: y := x[0]; z := [y]; The LatFunction module is able to output data on parameter ports as well as lattice ports. o The PyrToGeom module now employs the code of ExteriorPyr when displaying 3D pyramids in dimension 3 - 5 - mode. This can reduce the number of polygons substantially, resulting in much faster rendering. o The SampleCrop module has been fixed to remove a memory error that leaked a copy of the input lattice on each firing. o The ScaleXYZ module is improved to correctly scale the X, Y, and Z dimensions of a lattice with one, two, or three coordinate dimensions. o The ShrinkPyr module now accepts compressed pyramids on input. o The SliceLat and SlicePyr modules now interpret the 4x4 slicing plane transformation matrix in the same way as ClipPyr, LatToGeom, Transform, and TransformGen. o The Triangulate3D module now uses a hash table to represent adjacent tetrahedra, yielding a considerable space reduction for large input data sets. o The VideoInput module is distributed in source form for easier modification or use as a coding example. o These new modules have been added to the module suite: AdjustColor This module corrects an RGB image to be NTSC/PAL compliant in color space. It does it by reducing the saturation. AnimFile This module generates sequences of filenames, using two strings and an integer. Axis This module annotates a geometric, rendered image that was constructed from an Explorer 3D Uniform Lattice. BendBox This module is similar to the BoundBox module used for bounding lattice data except that it allows more direct control of the bounding box produced and produces a pyramid, similar to the WorldMap module, which can be used with the Projector module so that it is transformed in the same manner as - 6 - the data. ChannelAnimate This module selects a single channel from a vector lattice and outputs it as a scalar lattice. If desired, ChannelAnimate will walk sequentially down each channel in the input lattice and output each as a separate scalar lattice in an animation fasion. ChannelMerge This module takes data from up to five scalar or vector lattices and merges the data portions of each into a single vector lattice. ColorBin This module allows the user to generate a color table that consists of discrete intervals, unlike GenerateColormap which generates a continuous colormap. ColorEditor This is a utility module to assist the user in selecting and editing colors. ColorXform This module is a LatFunction-based module for interactively combining color channels in an image. CullPyr This module outputs a subset of an input pyramid dataset. The subset consists of nodes and related cells having data within (or outside of) a specified range. CullPyr can be used in conjunction with LatToPyr to removed blanked data from a lattice. ExportImage This module writes an Explorer image lattice in various file formats. EyeBackbone This module extracts the backbone elements from a PDB file. EyeBalls This module inputs an Explorer Chemistry Pyramid and generates various ball and stick molecular geometries. - 7 - EyeCrystal This module reads the crystallographic coordinates and connectivity information of a CSS format crystal file, converts the coordinates to cartesian, and builds a Chemistry Pyramid. EyeESP This module reads the grid data of a MOPAC electrostatic potential file and generaters a uniform Explorer lattice. EyeG92 This module reads the the data of a Gaussian 92 log file, determines the number of iterations, and builds a Chemistry Pyramid of the selected iteration. EyeMonteCarlo This module inputs a uniform Explorer lattice and calculates the volume of a selected piece using a Monte Carlo integration. EyeMopac This module reads the Cartesian coordinates of a Mopac output file and builds a Chemistry Pyramid. EyeMopacRxn This module reads a Mopac output file and generates a Chemistry Pyramid of the selected reaction coordinate. EyeMopacVib This module reads a Mopac output force file and generates the vibration of the selected eigenvalue. EyeRibbons This Geometry module is an implementation of the Ribbons Algorithm by Mike Carson. EyeSybyl This module reads the molecular data of a Sybyl mol file and builds a Chemistry Pyramid. FE2Zdata This module creates a pyramid in 3D from two coordinates and a data value used as the Z coordinate. FEPyrBox This module creates a bounding box geometry for a pyramid. It is - 8 - similar to BoundBoxPyr. FERead This module reads a specialized compressed pyramid representation for finite element models. FileList This module displays in a scrolling list widget a list of file names that match a given pattern. FileListBrowse This module displays in a browsing scrolling list widget a list of file names that match a given pattern. FileListExtended This module displays in an extended scrolling list widget a list of file names that match a given pattern. FileListMultiple This module displays in a multiple scrolling list widget a list of file names that match a given pattern. Heat_flux This module is a LatFunction-based module that computes a simple heat-flow calculation. ImportImage This module reads an image in one of various file formats and outputs it as an Explorer image lattice. Islice This module interpolates an (n-1)- dimensional slice from an n- dimensional lattice. Map This module reads the CIA World Bank II map database and generates geometry. Mathematica This module provides an interface to the symbolic mathematical manipulation program Mathematica. MeshDfm This module reads in a 3-based or 4-based deformation mesh file and outputs a pyramid data structure. MiniVas This module records animations to a Lyon-Lamb MiniVas video controller. - 9 - Projector This module transforms data with geographic coordinates into one of several standard map projections. ReadAnsys This module reads Ansys finite element data files to produce pyramid output. ReadMarc This module reads MARC output t16 or t19 data files to produce pyramid output. ReadMesh1 This module reads in a Mesh data file to produce pyramid output. ReadMultiPlot3D This module reads a multi-blocked Plot3D file and outputs each block as a separate lattice. It also allows iblanked files to be read, but ignores the iblank information. ReadNastran This module reads a Nastran xdb file. ReadQuake This module reads an earthquake data file and outputs a pyramid suitable for input to the CropQuake module. ReadSEGY This module reads a SEGY file and outputs a lattice. ReadXplor This module reads X-PLOR format electron density maps and generates a volume lattice. Readsocklat This module reads floating point vectors from a TCP/IP connection- based socket into a lattice. RotateCamera This example module generates a camera using a fixed rotation. SampleXYZ This module is a LatFunction-based module to subsample a 3D lattice with a different sample rate in each dimension. ScaleDelays This module is a LatFunction-based module for scaling the Z coordinate of a 3D dataset. See also the - 10 - ScaleXYZ module for scaling one, two, or three coordinate dimensions. SpherToCartes A LatFunction-based module for computing Cartesian coordintes from spherical coordinates. See also the Projector module. TestIL Sample ImageVision library module for combining image processing filters into a single module. This module performs a Blur and then a HistEqual operation. ToCoord A LatFunction-based module for converting between Explorer lattice coordinate types. Known to have problems dealing with perimeter coordinates. Transform This module applies a transformation matrix to the coordinates of lattice and pyramid input data, rotating and translating in any number of dimensions. It accepts the standard 4x4 matrix output of TransformGen for 3D transformations. VideoInput This module captures the input video via the StarterVideo or VideoLab device either in single frame or live mode. ViewGeom This module shows an iconic representation of the Inventor scene graph for a geometry. VolumeRender This module renders 3D uniform byte volumes using slicing planes parallel either to the lattice coordinate axes or to the viewing plane. WatchFile This module watches for modifications to a file and fires its Filename port when the file changes. - 11 - WorkBench This module supplies a single number which can be fed into other modules, such as the slice number for OrthoSlice, to allow fine control over numeric parameters. WorldMap This module reads a compressed version of the CIA World Data Bank II map database and produces a two-layer pyramid which contains a cropped, decimated map, in units of degrees longitude and degrees latitude, containing only those features selected by the user. buildMOPAC Creates a byte lattice of the input for an execution of MOPAC. This modules reads a standard chemistry pyramid and generates the MOPAC input file. The user can choose which Hamiltonian to use. cfd These modules incorporate common Computation Fluid Dynamics techniques. The modules are recognizeable by their naming scheme, which ends in FunXXX, where XXX is a three digit number. particles This module creates a point at each grid location in an n-dimensional grid. The point may be depicted as a single pixel, tetrahedron or sphere. readGCM This module reads a very specific format of a global climate model. Data courtesy of Los Alamos National Laboratory. readKuwait This module reads a datafile with several time steps of smoke information generated with the Global Climate Model from Los Alamos National Lab. readVolume This module reads a volume dataset in a specialized binary format. warpImage This module takes an image and wraps it on a sphere. It assumes - 12 - that the image is linear in latitude and longitude. 3.5 Control_Panel_Editor o The default font for the Control Panel Editor has been changed to a Helvetica font in the default font set. This reduces system disk usage by not requiring installing of optional X Window fonts. o The Scroll List widget is now resizable in the CPE. 3.6 Module_Builder o The default font for the Module Builder has been changed to a Helvetica font in the default font set. This reduces system disk usage by not requiring installing of optional X Window fonts. o The Module Builder now includes label information for option menu items and radio box items when it creates a prototype document file. o Changing the name of an input parameter no longer deletes the widget information associated with that port. The widget is preserved through name changes to the input parameter. o The Additional Install Files file list in the Build/Options window now shows the default .shp file for LatFunction-based modules and is more robust. o The Module Builder changes its working directory whenever a new module resource file is opened, including on startup. This can prevent erroneous writing of Makefiles in the directory from which the Module Builder was first started. o The Module Builder now correctly finds a usable temporary directory. o The Module Builder no longer allows a pyramid to be constrained to have zero layers. All pyramids must be constrained to have at least one layer. o The Fortran logical type argument has been restored to the list of allowable Fortran user function argument types. - 13 - o A bug has been fixed in which the Module Builder incorrectly assigned a variable's type to the shorter of two user defined types having a common prefix. 3.7 DataScribe o The default font for the DataScribe has been changed to a Helvetica font in the default font set. This reduces system disk usage by not requiring installing of optional X Window fonts. 3.8 Module_Development_Environment o Input and output port constraint checking is applied to all ports with constraints, fixing a bug in which checking ceased at the first unconstrained port. o Port constraint checking on missing data structures now correctly indicates when a missing structure is required. o The automatically generated API routines for all Explorer data types now delete any array before resetting its pointer in a *Set() call. The array can be preserved by temporarily zeroing its pointer during invocation of the *Set() call. o The manual pages describing automatically generated API routines have the same name as the data type. This is true for the supported data types cxLattice, cxPyramid, cxPick, cxParameter, cxGeometry, and cxUnknown, as well as all user-defined types. o The cxInputDataRelease routine now releases the last cached input on a port having only one input. Previously this cached data set was not released. o Colors may now be specified as text strings in module control panels using one of several formats. The cxParamColor* API routines convert from string parameters to valid color descriptions. As an example, the BoundBox module uses this feature to change the default color of its wires. o A new environment variable is available to control the execution of modules that use the Inventor library, due to the absence of OpenGL support on Personal IRIS, GT(X), and VGX(T) machines. If the CXGLTYPE environment variable is set to opengl, the local controller - 14 - searches /usr/explorer/opengl/modules for Inventor- based modules, while if CXGLTYPE is set to irisgl, it searches /usr/explorer/irisgl/modules. If the variable is not set, the local controller computes which directory to search based on a hardware inventory of the local machine. Thus if the DISPLAY environment variable is set to display on another machine not running the same type of Inventor and GL, the CXGLTYPE variable should be used to communicate this difference to Explorer. o Silicon Graphics does not support development of Explorer modules that use Inventor 1.x directly (this is the only way to develop Inventor-based modules on the IRIS GL platforms Personal IRIS, GT(X), and VGX(T)). However, you may be able to develop such modules with the following instructions. The symbol InventorVersion must be defined when imake creates the module Makefile. The appropriate way to do this is to define the environment variable CXGLTYPE to have the value irisgl before making the Makefile. The cxmkmf script will then take the appropriate actions to create an Inventor 1.1.2-compatible Makefile. (If you do not set CXGLTYPE, an OpenInventor Makefile will be generated by default.) For instance, when in the directory in which to make the module, use the following C shell commands: setenv CXGLTYPE irisgl make Makefile make This procedure is not supported, but is provided here as a service to our users. o The cxmkmf command accepts zero, two, or four arguments in making a module or type Makefile. o These new specialized API routines have been included: cxConnMaxInd Determine the maximum one-based index of all connections in a connection list. cxConnRemap Remove connections to a cleaned pyramid layer. cxCoordTransform Apply a homogeneous transformation matrix to all - 15 - coordinates. cxHSVtoRGB Convert color values from hue/saturation/value to red/green/blue. cxParamColorFloatGet Convert a string color parameter into floating point RGBA format. cxParamColorFloatSet Convert floating point color values into a string color parameter. cxParamColorPackedGet Convert a string color parameter into a packed integer format. cxParamColorPackedSet Convert a packed color value into a string color parameter. cxPyrActivePrev Flag as active/inactive the elements at the next higher pyramid layer. cxPyrConCompare Compare two sets of vertices for equivalence of a certain type. cxPyrLayerClean Remove selected items from one layer of a pyramid. cxPyrRefIndexGet Find the pyramid dictionary index of a compressed pyramid element. cxPyrVertOrder List the vertices on a pyramid face in their natural order of traversal. cxQmeshCoords Interpolate coordinates from grid points to cell centers. cxQmeshData Interpolate data values from grid points to cell centers. cxQmeshNextInd Step through triangle vertices in a quadrilateral mesh. cxQmeshNumPoints Return the number of points in a quadrilateral mesh with interpolated centers. cxQmeshNumTris Return the number of triangles in a quadrilateral mesh with - 16 - interpolated centers. cxQmeshTris Generate polygon vertex indexing to create a quadrilateral mesh using cell centers. cxRGBtoHSV Convert color values from red/green/blue to hue/saturation/value. 3.9 Miscellaneous o Modules that set widget values now get the correct parameter value when they refire. But the cxInputDataChanged(3E) flag indicating a changed parameter value is not correct. These modules should not try to optimize execution based on the changed flag of widget parameters. o The shared memory arena is no longer limited to 256 megabytes in version 2.2. Moreover, the shared memory arena may now reside on an NFS-mounted disk. The location of the shared memory arena is determined by the tempdir variable in your .explorerrc file. See Appendix A of the IRIS Explorer User's Guide for more information. 3.10 Changes_between_Explorer_versions_1.0_and_2.x There were many changes made between release 1.0 and 2.0 of Explorer. This section summarizes those changes for the benefit of users upgrading directly from Explorer 1.0. The IRIS Explorer User's Guide and IRIS Explorer Module Writer's Guide give much more detailed information about the changes. 3.10.1 General o There are many new modules-providing better pyramid support, more feature extraction capabilities, audio and video hardware control-as well as many new readers. o Pyramid data can now be compressed. That is, regularity in the cell or face structure can be factored out and described in a new ``pyramid dictionary,'' then those descriptions can be used over and over again within the pyramid. o You can add new data types to the system by way of a data typing language and compilation system. An accessor library is automatically generated for new - 17 - types. The Explorer types (lattice, pyramid, and so on) are defined in this scheme, and the description files for those types accompany the distribution. o A new firing algorithm provides better support for animations and simulations by allowing for frame-based synchronization and controlled cycles. o A new, powerful scripting language lets you drive maps from a command program. This scripting language is based on the popular language named Scheme. o A new built-in type, cxGeneric, can hold any of the Explorer data types, whether it is built-in or user- defined. o A new built-in type, cxPick, can hold picking information from the Render module for transport back up into a map. o Support for IRIS Inventor is provided. The Explorer ``geometry'' data type is revealed to be an Inventor scene graph. 3.10.2 Map_Editor o Explorer now has a textual scripting language, based on the popular Scheme language. It allows you to start modules, create maps, set parameters, and so on. Additionally, all of the control and data structure capabilities of the Scheme language are available to the script writer. Scripts can be read from files, from the keyboard, or from a pipe, and can be generated by modules or from menu bar items. o Creating applications is more fully supported. In particular, you can create a map containing one or more groups, customize their control panels, maximize them, and save the map. Then, the map can be executed as if it were a shell script, by typing its name. If the map filename does not end in .map, it is executed without a map editor or Librarian, as if it were a custom application. o The firing algorithm has been enhanced in several ways: a frame-based implementation exerts better control over the sequencing of module firing, yet maintains the fully distributed decision logic of version 1.0. This algorithm allows, for example, the Render module to know when it has completed the creation of a new, complete image. It also allows for controlled cycles, - 18 - or loops, in Explorer maps. Designated modules called ``controller modules'' have special logic for deciding when to continue or terminate a cycle in a map. These modules have a slightly different look, with an additional button that identifies them as controllers. Additionally, some connections in maps are special, too, in that they carry loop control information. These connections are colored differently from normal wires. o Fan-in of multiple wires to a single input port now behaves correctly in the firing algorithm. Each wire is treated almost as if it were a separate port, and the firing algorithm defers the execution of a module until all the necessary data on its input links is available. This has an impact on the implementation of some modules; see Section 3.7, ``Module Development Environment,'' for details. o Connections can now be made between widget parameter ports and non-widget parameter ports. These wires are identical to normal wires between ports, and behave correctly within the Explorer firing algorithm. Correspondingly, parameter functions (pfuncs) correctly participate in the firing algorithm. o The small top-level Explorer window is gone. The functionality it provided has been moved to the Map Editor menus. o Module standard output and error messages are now captured in a special logging window. This window can be shown or hidden either globally, collecting output from all modules, or on a per-module basis. Additionally, it can be configured to pop to the top whenever a module generates output. o Map files and groups can now have help files. For groups, the help file can be accessed in the same way as that for modules. For maps, the help file can be accessed only from the Librarian pressing button three on the mouse when the cursor is over the map item. o The Librarian can now save its state. If you rearrange categories or create new ones, you can save this configuration in a separate file which you can then integrate back into your personal Explorer configuration file (~/.explorerrc). o The Librarian now has a ``New Host...'' item in its Hosts menu. Selecting this allows you to type the name - 19 - of a new host to participate in this Map Editor session. o The modules' mini-control panel menus now have an item named ``Interrupt''. When selected, it sends a keyboard-style interrupt signal to the module that is trapped by the wrapper and results in immediate termination of the user function. This is useful for recapturing control of modules that have ``run away'' with your processor. However, no mechanism is provided to allow the user function to capture control when this happens and hence, storage leaks might occur. Any data that has been placed on output ports is flushed, and NULL data is flushed out on the others. o The Librarian now allows you to access modules' help files without launching them. This is accomplished via a menu that pops up when you press button three on the mouse over a module or map name. This menu shows the directory from where the module comes, along with items to launch the module and display its help file. o The Librarian now allows you to quickly scroll to a particular place in the list of modules using the keyboard. By typing the first few letters of a module name quickly while the mouse is in a category window, the module matching those keystrokes is scrolled to the top of the list. o Librarian categories can now be created based on more criteria. Now you can define a category in your configuration file by specifying a regular expression, as you would in the UNIX shell, to match module names. You can also specify the full pathname of a directory, and Explorer adds all modules in that directory to that category. These apply to the ``category'' statement in configuration files. o The .explorerrc configuration file has a new statement, ``scriptfile''. Its argument is the name of an Explorer scripting language file that is to be loaded by the Map Editor on startup. o The .explorerrc configuration file's ``modulepath'' statement no longer has the -append option; this is now the default. To remove all entries from the existing module path simply use this command with nothing after it. To place new directories at the beginning of the list use the ``-prepend'' option. - 20 - o Execution highlighting can now adapt to rapid firing situations by suppressing some blinking. When this happens, the yellow highlighting remains turned on, even though the module might be rapidly firing successively. When the firing rate drops, the module highlighting reverts to the normal mode. Reducing the amount of flashing allows continued interactivity in the Map Editor. o Groups of ImageVision Library (IL) modules can now be saved and converted into a single module comprising a single chain of IL operators. To accomplish this, create a map of only image processing modules, group it, create a custom control panel for it, then save it. A prompt asks you if the map should be saved as a single IL module. 3.10.3 Module_Suite o Module control panels that previously had file selectors now only have text type-in fields. They have file browsers available through a menu item on the menu bar of the maximized control panel. o You can now have any number of instances of the GenerateColormap module present, though due to the limitations of colormap entries in the X Window System, not all of them might have active palette windows. o The isosurfacing modules have been rewritten to use a different algorithm. This implementation can generate strips of triangles in its output, resulting in better rendering performance. o The image processing modules now follow the automatic type promotion rules used by the ImageVision Library product. Previously, they clamped data to the range 0 to 216-1 for short data and 0 to 28-1 for other data types. o The PickLat and ProbePyr modules have been removed from the module suite. o These new modules have been added to the module suite: AnimateCamera Key frame animation driver for the Render module. - 21 - Annotation Add text information to the Render module. AudioIn Capture audio (on audio-capable IRIS workstations) and produce a lattice of sampled sound. AudioOut Produce audio output (on audio- capable IRIS workstations) from an input lattice of sampled sound. Ball Produce an output geometry comprising spheres at each data point in an input lattice. BoundBoxPyr Produce a wireframe bounding box for a pyramid. BrowseFile Present the contents of an ASCII file in a scroll list widget. ChannelSelect Select out a single channel from an input lattice. ClipPyr Clip a pyramid by an arbitrary clipping plane. ComposePyr Compose a pyramid from multiple input lattices. CompressPyr Convert a pyramid into a compressed form. ExpandPyr Expand a compressed pyramid into a non-compressed form for modules that cannot handle compressed pyramids. ExteriorPyr Eliminate the shared faces in a pyramid. FileList Present a filtered list of files in a directory. For Loop controller for DO-loop-style map cycles. GenerateVideo Write images to one of several types of video devices. - 22 - GnuPlot Provide an interface to the popular GnuPlot graphing program. Note: This module is not supported by Silicon Graphics, Inc. GNU software is provided free of charge by the Free Software Foundation. SGI does not provide support or service to GNU software. The source code to GnuPlot is provided as a part of the IRIS Explorer distribution. Legend Generate a colormap legend for the Render module. MinMax Compute and display the minimum and maximum data values in a lattice. Mixer Mix and match data and coordinates from input lattices to produce a new output lattice. MoleculeBuilder Interactively edit a molecule pyramid. MopacView Read a MOPAC data file and produce a lattice. MultiChannelSelect Select or rearrange data channels in a lattice. MultiSlice Produce multiple orthoslices of a lattice. PrintParam Print the value of a cxParameter data structure. PrintPick Print the value of a cxPick data structure. PseudocolorImg Combine an 8-bit image with a colormap to create a full-color image. QueryLat Query the value of an input lattice at a particular point selected interactively in the Render module. - 23 - ReadAVSfld Read an AVS field file into a lattice. ReadAVSimage Read an AVS image file into a lattice ReadAVSucd Read an AVS unstructured cell data file into a pyramid. ReadAVSvol Read an AVS volume file. ReadAudio Read an AIFF file into a lattice ReadHDF Read an HDF input file. ReadImages Laminate multiple image files into a 3D lattice ReadMovie Reads an SGI movieplayer file and produces multiple lattices (versions 2.1 and later only) RealityRender Volume renderer for the RealityEngine. RenderRemote A version of the Render module that can open its rendering window on a different display. Repeat A loop controller module for controlled repeat-style loops. SamplePyr Subsample a pyramid by systematically or randomly discarding cells. ScaleXYZ Scale coordinates of a lattice with one, two, or three coordinate dimensions. ShrinkPyr Shrink the cells of a pyramid structure. SLiceLat Create an arbitrary slice of a lattice, going directly to geometry. SlicePyr Create an arbitrary slice of a pyramid. - 24 - Streakline Create a streak line through a velocity-based 3D lattice. Switch Selectively propagate or do not propagate data through a map. Triangulate2D Generate a Delaunay triangulation from a 2D lattice. Triangulate3D Generate a Delaunay graph of 3D data. Trigger Provide a barrier capability, propagating data based on a particular condition. Vectors Generate a vector plot from a vector field input. VideoControl Control an external video device. VideoDevice Route images to an external video device. VideoLabInWin Capture VideoLab input into a window and produce a grabbed image output lattice. VideoLabOut Route an image lattice or portion of the screen to a VideoLab device. VideoStarterIn Grab images from an SGI Starter Video device. VideoStarterInWin Display Starter Video images in a drawing area. VideoStarterOut Send image lattices to a Starter Video device. While Loop controller for WHILE-style loops. WriteAnimation Write a FIT animation file from a series of input images. WriteAudio Write an AIFF file from a lattice. WriteMovie Writes an SGI movie file from a series of input images (versions 2.1 and later only). - 25 - o The Render module has several new geometry input ports. On input, there is now a second 3D geometry input port, named Annotation. Geometry wired to this port behaves the same as normal geometry, except that it is always displayed in front of all geometry received in the normal input port. Another input port, named Screen, accepts geometry and displays it in 2D in front of all other inputs. The coordinate space for this input port is always 1 to +1 in the shorter of the two axes. The longer axis may resolve coordinates outside this range. In any case, the coordinate (0,0) is the center of the window. o The Render module can send out its camera position as a geometry object on an output camera port. Camera geometry objects can also be sent into this module on the Input Camera port. o The Render module has a new parameter port, Snap on Redraw, which, when set to non-zero, causes the module to send out an image lattice of its window each time it rerenders its scene. o The Render module and the DisplayImg module have output ports for picking. This data structure carries information about user mouse picks. o The Render module can now read a configuration file, .Renderrc. Refer to the help information or manual page for Render for details. 3.10.4 Control_Panel_Editor o Dial and slider widgets can now have truly integer values. o Control panels can now have decoration widgets. Horizontal and vertical separator lines are supported, as well as rectangular frames and text labels. o Widgets now have a stacking order, allowing widgets in control panels to be placed explicitly above or below others. This is particularly useful when used with decoration widgets. o There is a new widget: Scroll list. This widget has a set of API calls and supports multiple-line text. You can add or remove items dynamically from the widgets, and you can select multiple items at the same time. - 26 - o Maximized control panels can now have custom menu bars. Menus on menu bars can have items that set parameters, invoke Explorer scripting commands, invoke UNIX shell commands, or cause the system to quit. o When selecting widgets to move around, you can use a shift-select or drag box mechanism to select more than one widget. Then, these widgets can be moved around in unison. o Widgets can be hidden and revealed programatically. They can also be enabled and disabled. Disabled widgets appear grayed-out; hidden widgets are not visible. The control panel editor allows widgets to be hidden on module startup. o Many widgets can be selected for resizing horizontally, vertically, or both, in the control panel editor. o You can now dynamically add items to or remove items from option menu widgets. In version 1.0, once the number of items in the option menu had been set up in the control panel editor, the module could not increase it or decrease it. 3.10.5 Module_Builder o The Module Builder now allows only one main panel to be active at a time. o Pyramids on input ports can now have a limited set of constraints applied to them. o Lattices on input ports can now be constrained to require either a data section, a coordinate section, or both. Hence, lattices without one or the other, within the bounds of designated constraints, are allowed. o The Module Builder supports the creation of a loop controller module. The controller status setting is located in the Build/Options panel. o When making connections in the Connections panel, targets that are allowed after selecting a source item are highlighted in a way similar to I/O ports in the Map Editor. o When making connections to an output port in the Connections panel, all unspecified structure members are highlighted with a different color text. When all - 27 - members appear in black text, the output data set is fully wired. o A Hook Functions panel is now accessible from the Options menu. This panel allows you to define the hook functions for the module being built. Previously, this table had to be hand-coded. 3.10.6 DataScribe o Reading an input file until end-of-file is detected is now supported. o Support for arrays of sets is included. That is, an element of an array glyph can be an aggregate structure. o The DataScribe no longer supports ASCII or binary templates that contain either multiple lattices or a mixture of lattices and other glyph types. The DataScribe now correctly handles Fortran record structured binary input files. The DataScribe now supports pattern scans covering more than 8192 bytes. 3.10.7 Module_Development_Environment o Non-MDW modules no longer need a hand-coded UserFuncTable or HookFuncTable. These are automatically generated from the module resources. o All modules, whether they have a data wrapper or not, now have input and output port constraint checking applied to them. o Several new API routines relating to loop control are included: cxLoopBreak, cxLoopCtlr, cxLoopIteration, and cxLoopControlArc. o The routine cxGeoVolumeDefine has been renamed cxGeoOctTreeDefine. Additionally, a new splat enumeration value for texture mapping the splats has been included. o The supported data types, cxLattice, cxPyramid, cxPick, cxParameter, cxGeometry, and cxUnknown, have automatically generated API libraries that add to the list of functions that can be called on them. The manual pages describing these routines have the same name as the data type. - 28 - o A new environment variable is available to control the compilation and linking of modules. If the DEBUG environment variable is set, the module Makefile is generated to compile and load all files with the -g option. This must be set before building the module Makefile to have an effect. o The command cxmkmf replaces the version 1.0 command cxmkmodmf for generating module and user-defined-type Makefiles. o The timer mechanism (cxTimerAdd) and the file descriptor select mechanism (cxInputAdd) can be used identically in either X Window System or non-X Window System modules. o These new specialized API routines have been included: cxInputDataRelease Releases the data on an input port so that it no longer is available if the module needs to fire again. cxScriptCommand Sends an Explorer scripting language program to the Map Editor for interpretation. cxDataCheck* A set of routines for controlling checking and error actions for memory allocation problems. cxParamPathnameGet Reads a parameter port and resolves its value as a file pathname, converting environment variable references or tilde notation use for home directories. cxOutputDataRelease Releases data cached on an output port. cxInputAdd/Remove Adds and removes a user file descriptor to the module scheduler, resulting in a user function being called when the file descriptor has data to read. cxGeoReceive Allows a module to read Explorer geometry input and to convert it into an IRIS Inventor scene graph. Once in this form, the - 29 - scene graph is amenable to manipulation via IRIS Inventor. cxGeoInventorDefine Convert an IRIS Inventor scene graph into an Explorer geometry object. cxGeoLightModelAdd Allows a specific lighting model to be attached to a geometry object. o Several API routines that deal with input ports now have analogs that work on all connections to a given port. These routine names are the same as the originals, except that they add a V to the end of the name. The values generated by these routines are vectors of values analogous to the single values generated by the non-vector versions. Examples of these new routines are cxInputDataChangedV, cxInputDataGetV, cxInputDataConnIDGetV, and cxInputDataReleaseV. 3.10.8 Miscellaneous o Explorer configuration files can now be executable scripts. If your configuration file is marked as executable, Explorer runs it as a program and reads the standard output as the configuration information. If the first line of the file contains the string #!CPP, the entire file is processed through the C preprocessor and the entire set of environment variables are predefined to the preprocessor. o A limited performance report capability is available. When this capability is enabled, modules report CPU and memory use after each firing of the user function. The only way at present to enable it is with the ``(perf- report-on)'' scripting command. o Modules can have ports typed as ``Generic,'' meaning that any type of data can be accepted on that port. No built-in type constraint checking is applied to these ports; if a module can accept only a particular set of types, it must check itself and reject (cxInputDataRelease) data that it cannot handle. Several modules (for example For, Switch, and Trigger) have generic ports. o Files generated by Explorer now have custom IRIS WorkSpace icons. - 30 - o The default base address of the shared memory arena has been moved; it is now 0x50000000. All shared memory arenas are limited to 256 megabytes in version 2.0. o There are many new modules-providing better pyramid support, more feature extraction capabilities, audio and video hardware control-as well as many new readers. o Pyramid data can now be compressed. That is, regularity in the cell or face structure can be factored out and described in a new ``pyramid dictionary,'' then those descriptions can be used over and over again within the pyramid. o You can add new data types to the system by way of a data typing language and compilation system. An accessor library is automatically generated for new types. The Explorer types (lattice, pyramid, and so on) are defined in this scheme, and the description files for those types accompany the distribution. o A new firing algorithm provides better support for animations and simulations by allowing for frame-based synchronization and controlled cycles. o A new, powerful scripting language lets you drive maps from a command program. This scripting language is based on the popular language named Scheme. o A new built-in type, cxGeneric, can hold any of the Explorer data types, whether it is built-in or user- defined. o A new built-in type, cxPick, can hold picking information from the Render module for transport back up into a map. o Support for IRIS Inventor is provided. The Explorer ``geometry'' data type is revealed to be an Inventor scene graph. - 1 - 4. Known_Problems_and_Workarounds This chapter describes the known problems with release 2.2 of IRIS Explorer and, where known, ways to work around them. 4.1 Map_Editor o Explorer, because it is a multiprocess application, can consume a substantial number of processes and file descriptors, depending on its use. Under these circumstances, it is advisable to increase the UNIX kernel's maximum number of processes (NPROC) and file descriptors (NOFILES). See Appendix A of the IRIS Explorer User's Guide for more information. o When modules that contain file browser widgets are run remotely, the widgets show files that are available only on the local machine. To correctly enter a remote filename in this case, the name must be correctly typed into the text field without the benefit of the browsing capability. All Explorer modules have been modified to remove the file browser from the control panel, moving it instead to the module menu bar. o The ``Interrupt'' item on module menus interrupts user functions with the UNIX signal SIGUSR1. User functions must not interfere with the capturing of this signal. Modules that are multithreaded, such as the image processing modules on multiprocessors, will not properly clean up the parallel threads when interrupted with this feature, and may fail on subsequent firings. o If a module control panel with a drawing area is made full-screen with the window manager maximize button, then restored to its previous size, drawing areas might not be informed of the correct size. If this happens, resizing the window slightly corrects the display. o If a module with a maximized control panel is saved as part of a map, the size of the saved control panel becomes its new minimum size. Thus if you maximize a control panel, make it much larger, save the map, and reload the map, you will not be able to resize the control panel to be smaller. The workaround is to use the module menu-bar Replace command to replace the module. Since this command fails to duplicate control panel information, the replaced module will have a control panel with default size. o Modules that have parameter functions on their inputs cannot be duplicated or copied from the cut buffer - 2 - without an error message complaining about can't find upstream module. o The (destroy) and (disconnect) scripting language commands are not synchronous. Hence, if you re-create a link or module immediately after destroying it, an error might occur in the naming of the new item. o If you save a portion of a map containing nested loops, and save both loop controllers but not the entire inner loop, relaunching that map might cause the incorrect module to be selected as the loop controller. o When running an application with only maximized control panels visible, selecting the Motif menu ``Close'' item causes the control panel to go away, but the map programs continue to run. You must use the shell command ps to find and destroy the processes. Sending a kill to the process named gui should suffice. You should define a ``Quit'' menu bar item to exit the application, and then use it to exit the application. o Map files may contain out of date directory path information for modules. If a module executable is moved to a location different than that given in a map file, the map's path to the module will not be updated. Operations that depend on this path information will cease to work; these include module replacement, module help, and module credits. Module launching will continue to work correctly, but loading and then saving the map will not update the path. The workaround is to edit the map file to replace the quoted path string for the module with the new path or with the symbol NULL (not in quotes). 4.2 Firing_Algorithm_Anomalies o In version 2.1, widget values set programmatically (e.g. with cxInWdgtDblSet) would change the widget, but would not change the port value if the Fire Now menu was selected. This has been partially fixed. The correct value now appears on the port but the values returned from cxInputDataChanged and cxInputDataChangedV may be inconsistent. It is best to assume that all widget values have changed. Note that the new widget values set programmatically were never intended to appear on the port until the next time the module fires. - 3 - o Button widgets are always marked as ``new data'' when a module starts execution, even if the initialization hook function calls cxInputDataGet on that port. o Nested loops perform correctly in most cases, but certain loop wirings can cause problems. In particular, a loop control module cannot receive data both from within its loop and from within an inner loop. The data from the inner loop must be wired to that loop's controller, then on to the outer loop controller. Routing all data through the inner controller allows the inner controller to send consistent control information to the outer loop controller. In addition, if an outer controller receives data from an inner loop, you must route all data going to the outer controller through the inner controller. Failure to do so causes the outer controller to receive data at different loop nesting depths, which it might be unable to handle. 4.3 Shared_Memory_Anomalies o If a module dies while allocating shared memory, it locks the arena memory allocator, preventing other module operations. This has the appearance of the map failing to fire after a module has died unexpectedly. It is best to save your map and restart Explorer when this happens. o When the disk containing the shared memory arena fills up during the execution of an Explorer map, there might be no error reported, but the execution of the map stalls. This condition will often only manifest itself via system error messages in the console window. 4.4 Module_Suite o In Render, Personal IRIS systems support only screen door transparency. o In Render, two-sided lighting does not work on IRIS Indigo systems with Entry or XS graphics, even though the systems have this capability. This problem is exhibited when the Render module is run on one system and displays on a second, using DGL (distributed graphics library). This problem results in displays that are completely dark on one side and correctly lit - 4 - on the other. o In Render, selecting geometry objects received on the Screen input port does not always work correctly. Highlights and manipulators might be placed incorrectly. The Transform Sliders can be used to position these objects accurately. o In Render, the snapped output image contains a fine white border of pixels that are not part of the rendering window. o The Render module is sensitive to some X Window System application defaults. For example, setting ``*borderWidth:2'' causes the module to redraw itself improperly when its window is resized. o The Render module may print to standard output a terse message of the form ``id XX not found,'' where XX is an integer. This sometimes happens during disconnection of a wire or destruction of a Render module. o The Render module commonly has problems allocating all colormap entries and may print to standard output a message of the form ``Warning: Cannot allocate colormap entry for LimeGreen.'' o Render and other modules that receive geometry slowly accumulate memory, possibly causing some fragmentation of memory. The problem is that each Inventor scene graph node has a name and the small names accumulate in the process that transcribes in geometry. The names are now block allocated, so the fragmentation problem isn't as severe as it was formerly, but it can still cause problems if the module receives very large geometries many times. There is no workaround to this problem, although we have increased the block size of the names somewhat to push the failure point further out. o Modules from Explorer version 2.1 should run in the version 2.2 Map Editor without recompilation or relinking. However, some version 2.1 image processing modules (names end in Img) may exit when run in the 2.2 Map Editor. o In Contour, taking contours of large volumes with many slices might consume excessive memory. o The GenerateColormap module does not compute ideal control points for colormaps given all possible lattice - 5 - colormap inputs. In particular, it might not place control points close enough together if the input lattice has discontinuities in one or more of the color channels. Additionally, it might not pick ideal slopes for control points even when given smooth inputs. The module sometimes produces a colormap with zero opacity, resulting in completely transparent objects. Refiring the module one or more times often resets the opacity back to the desired values. o The IsosurfacePyr module exits abnormally when given the dataset /usr/explorer/data/pyramid/shuttle.pyr as input. The module is unable to accept this form of compressed input. o In LatFunction, an error pop-up might appear when no data exists on an optional port that is referenced in the Shape script. o In LatFunction, the Shape script might be incorrectly interpreted when it is newly read after changing the script file. With the cursor in the Program file type-in slot, press; this causes LatFunction to reread the script and usually fixes the problem. o If the MultiSlice module needs to readjust the Offset widget back into the range of the number of slices on its input, it does not recompute the slicing places. You must adjust the Offset value manually to a valid value for the module to recompute its output. o Geometries saved by WriteGeom will not have the shape hints normally used to view geometry in Render. Therefore an Inventor scene graph saved via WriteGeom and viewed with ivview may not appear identical to the same geometry viewed in Render. Add to the saved geometry the shape hints documented in the man page for Render. 4.5 Control_Panel_Editor o The Control Panel Editor (CPE) does not retain all information concerning a widget's properties when switching between widgets. If you change a widget from a radio button to an option menu, the radio buttons' labels are not applied to the new option menu. This occurs also for other widget combinations. - 6 - o Very long labels for Radio Button and Option Menu widgets can confuse the CPE. In this case, the editor displays a long label, but the bank of option boxes is incorrect, obscuring the buttons. 4.6 Module_Builder o In the Connections panel, you cannot wire to any lattice in the layers of a pyramid other than the first. o It is too easy to make wiring mistakes in the Connections panel. In particular, you can wire a (char *) parameter value in a port to a (char) function argument, resulting in a compile-time error if you let the module builder create your function prototype. o You cannot set the value of a constant wired to an output port structure member. Instead, wire the constant to a function argument and from there to the output port. o Using strings as function parameters is confusing. A function argument in a C or C++ user function that is to receive a character string from a parameter port must be specified (in the Function Args panel) as type ``char'' and reference ``Array.'' In a Fortran user function, the function argument must be specified as a ``character'' and a ``Scalar.'' o You can create a user-defined data type that contains so many members that the menu for it in the Connections panel is taller than the height of the screen. If this happens, apply the keyword ``closed'' to nested structures within the new type; this prevents the Module Builder from expanding them out in this menu. 4.7 DataScribe o Under some circumstances the DataScribe will delete a glyph's name (and replace it with an empty string) on reading a DataScribe module. Attempting to perform wiring or array component selection in the presence of an empty name may cause the DataScribe to dump core. o In some cases using the Array Component glyph (the cross-hatched green icon in a vector glyph) will cause DataScribe to dump core. - 7 - o There are several minor annoyances in version 2.2 due to design incompatibilities with Motif 1.2. Things such as glyphs that appear the wrong size, incorrect window sizing, etc, are due to this problem. These problems are typically minor and pose no impediment to correct usage of the software. o You can overlap templates in the DataScribe slightly. This can occur under special circumstances if you close and then open a template that is followed by another open template. If you save the module, clear the DataScribe, then read in the script again, the overlap disappears. The overlap is slight and does not impair use. o Templates and glyphs must have unique names. When you append a template or glyph, you can create a script with a duplicate name. You must change the new template or glyph names to avoid collisions with existing components in the script. The parser can, at times, fail to detect the duplicate components. o The value of the nDim glyph in an output lattice glyph should not be altered. o The response time is slow while editing names for parameter glyphs because the CPE must be notified of changes during this processing. You do not need to enter a carriage return when typing names and values in the DataScribe; therefore, the CPE must process each character separately. o Glyph names must not include spaces. This can confuse the parser. o In the save pop-up dialog, if you select OK without selecting or entering a filename, no prefix is assigned and the files are saved with their default suffix only. o In the Control Panel Editor, the Cancel button does not cancel widget editing (that is, editing the widget type, dimension, position), and it reverts back to the beginning of the editing session. Editing in the CPE does not have any widget addition or deletion semantics. You can add and delete parameters only through the DataScribe, not through the Control Panel Editor. o Drag-and-drop into output templates is unreliable if the input pane has been hidden. Glyphs can still be added to the template by selecting the template, then - 8 - selecting the desired items in the palette while holding down the key. 4.8 Libraries_and_Module_Building_Environment o Linking modules that contain C++ source files gives a linker warning indicating that the C++ library was not used and could be removed from the link line. This happens because the module control wrapper (MCW) prelinks against the C++ library. No action is necessary. o Explorer modules are not marked for QuickStart by the loader. You may observe a slightly longer startup time than would have been possible with a quickstarting executable. o If you create a new data type with two unlabeled members having the same name at the same scoping depth from their shared parent types, the wrapper code generator might try to call an API routine that doesn't exist, resulting in a module compilation error. The workaround is to label the members with unique names or change the member names so that they are unique. o Using the Workshop Performance Analyzer tool on Explorer modules is not currently supported. o Modules written in Fortran that happen to call routines from the Explorer Geometry API (eg, cxGeo* calls) may exit when run. In these cases there will be no resulting error message identifying the cause of the module death. The module exits because a symbol is undefined, but the situation is further confounded by an absence of linker (ld) or run-time loader (rld) error messages identifying the undefined symbol. Because Fortran modules call an interface routine found in libcx.so or libcxX.so, which then calls the cxGeo routine in libgeometry.a, the correct ordering of the symbols on the link line is one of userFunc.o -lcx -lgeometry userFunc.o -lcxX -lgeometry Because User Library symbols are placed before the Explorer system libraries on the link line, the actual order reverses the cx and geometry libraries. This yields an undefined symbol at run time. - 9 - The workaround is simple. Authors of Fortran geometry modules must place the symbols -L$(CXLIBDIR) $(LIBAPI) before $(GEOMETRYLIBS) in the User Libraries field of the Module Builder main window. Authors of Fortran geometry modules using X Windows must instead add the symbols -L$(CXLIBDIR) $(LIBAPI_X) For instance, a User Libraries line that read $(GEOMETRYLIBS) mylib.a would now read as one of the following two lines, depending on the absence or presence of X Windows code in the module: -L$(CXLIBDIR) $(LIBAPI) $(GEOMETRYLIBS) mylib.a -L$(CXLIBDIR) $(LIBAPI_X) $(GEOMETRYLIBS) mylib.a - 1 - 5. Documentation_Errors This chapter lists the documentation errors in the version 2.0 IRIS Explorer User's Guide, IRIS Explorer Reference Pages, and IRIS Explorer Module Writer's Guide. These documents are shipped unchanged from version 2.0. In addition to their hardcopy form, the documents are included online in the /usr/explorer/doc directory. In order to uncompress and print these PostScript documents, you use the zcat and lp commands. For instance, to print chapter 5 of the IRIS Explorer User's Guide, you could use a command of the form: /usr/bsd/zcat /usr/explorer/doc/userguide/Chap5.ps.Z | lp 5.1 User's_Guide o Chapter 3 mentions the ProbePyr module, which is no longer shipped with Explorer. The SlicePyr and ClipPyr modules can be used as a replacment. o The PickLat module has been removed from Explorer. Instead use the user picking function in Render along with the QueryLat module. 5.2 Reference_Pages o cxLookupCreate may return a negative one value for lookup points outside the domain of a uniform lattice, when it is supposed to clamp the point to the uniform domain. o The UserFuncs(4E) man page does not mention the create hook function, which is called after the module is created, but before it is first enabled. In particular, the widget parameters are not set when the create hook function is called, so the module is restricted to performing actions independent of widget values. 5.3 Module_Writer's_Guide o The files /usr/explorer/src/MWGcode/Pyramid/C/GeneratePyr.c and /usr/explorer/src/MWGcode/Pyramid/Fortran/GeneratePyr.f were missing in version 2.0, but are now present. o The API description for cxPyrCompress was missing a function argument, which is now included in the online man page. - 2 - o The scrolled list widgets may not update their maximized Motif window list when changed with a call to cxInWdgtScrollList*. However, the diminutif control panel items are updated.