oOo Explorer Frequently Asked Question List oOo ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Version 0.2 Last Altered 12th April 1992 - G.C. !!!!! Please Redistribute this Article !!!!!! + Introduction + ~~~~~~~~~~~~~~~~ This document contains answers to some Frequently Asked Questions (FAQs) asked of the Explorer Modular Visualisation Environment (MVE). The latest update of this can always be obtained by FTP from : UK Site : ftp.epcc.ed.ac.uk (129.215.56.29) ( US Mirror : swedishchef.lerc.nasa.gov (139.88.54.33) ) If you wish to be part of the Explorer mailing list, comment on this FAQ, add/alter/CORRECT any questions, or have any suggestions, please email: explorer-request@castle.ed.ac.uk, or gordonc@epcc.ed.ac.uk Where relevant and possible, the sources of information are listed after the answers - many of the questions stem from those on the mailing list. Direct quotes are indented. N.B. The compilers of this FAQ are independent of SGI (developers of Explorer) - this also means that any inaccuracies are most probably our own faults ! Thanks to the XUG and the X FAQ for ideas. - Gordon Cameron (Edinburgh Parallel Computing Centre) gordonc@epcc.ed.ac.uk - Chris Thornborrow, Matthew White (EPCC) Key : ~~~~~ + : New since last update * : Changed since last update @ : Bug question (+ fix) + Topics + ~~~~~~~~~~ A) TOPIC: GENERAL INFORMATION A.1) What is Explorer ? A.2) What platforms will Explorer run on/what are the requirements ? A.3) How can I get Explorer ? A.4) Modules, Maps & Ports - What are they ? A.5) What is the Map Editor/Librarian ? A.6) What Data Formats can Explorer handle ? A.7) What is the Data Scribe ? A.8) What is the Module Builder ? A.9) What are the MCW and MDW ? A.10) What is an MVE ? A.11) What other MVEs are there ? A.12) Is there any overlap between ImageVision and Explorer ? - B) TOPIC: RUNNING EXPLORER B.1) Why does Explorer crash immediately ? + B.2) Can I run Explorer on one machine and display on another ? B.3) Can I run modules on different machines ? B.4) How can I start Explorer with a prefined map ? B.5) Can I run Explorer in batch mode (i.e. without the GUI) ? B.6) Will Explorer work with very large data sets ? B.7) When does a module fire ? B.8) Why does Explorer run slowly on my system ? B.9) How can I customize the look of Explorer ? - C) TOPIC: USING EXPLORER with the MAP EDITOR C.1) Why does Explorer ignore all my input ? @ C.2) Why can't I start a GenerateColormap module ? C.3) How can I stretch the librarian scrolling list ? C.4) How can I slice into an iso-surface ? C.5) How can I render translucent solids ? C.6) Why can I not get LatFunction to work ? +@ - D) TOPIC: USING THE DATASCRIBE D.1) Why does the help file not reflect the actual widget ? @ - E) TOPIC: USING THE MODULE BUILDER - F) TOPIC: PROGRAMMING MODULES F.1) How can I wake Explorer on events ? F.2) What has happened to the routine cxInputPortStateGet ? @ - G) TOPIC: MODULES AVAILABLE/WANTED G.1) Where can I get PD modules ? + - H) TOPIC: FURTHER INFORMATION H.1) Where can I obtain documentation (e.g. Module Writers' Guide) ? * H.2) Is there a mailing list/FTP site ? * H.3) Is there a relevant newsgroup ? H.4) Why are the electronic PostScript files incomplete ? * - I) TOPIC: MISCELLANEOUS I.1) How can I add/correct or comment on Q&As on the FAQ ? I.2) Where can I find a list of bugs ? + - + Full Q&As + ~~~~~~~~~~~~~ ====================================================================== A) TOPIC: GENERAL INFORMATION ====================================================================== A.1) What is Explorer ? IRIS Explorer is an application creation system and user environment that provides visualisation and analysis functionality for computational scientists, engineers, and other investigators. It is especially useful for those whose needs are not met by commercial software packages. Also, IRIS Explorer's Graphical User Interface (GUI) allows users to build custom applications without having to write a single line of code. [from IRIS EXPLORER - Technical Report(SGI)] ---------------------------------------------------------------------- A.2) What platforms will Explorer run on/what are the requirements ? Explorer is included at no cost with each Silicon Graphics workstation. Explorer can be ordered for existing workstations at a nominal media charge. It is also available from Cray Research for Cray Research computers, and it is hinted that the package will be ported soon(#:-} to other platforms. On SGI platforms, requirements are that the machine have a 24 bit plane (or virtual 24 bit plane) frame buffer i.e. All except Personal Irises with 8 bit planes. In addition, 16MB is the minimum memory requirement, although 24 megs is recommended, especially when the data sets to be visualised are particularly large. In particular, you must be running version 4.0.1 of the OS, or higher. [Leo Blume(SGI) and Release Notes for Explorer] ---------------------------------------------------------------------- A.3) How can I get Explorer ? Contact your local SGI supplier for details of what Explorer is available on, and how to obtain it. ---------------------------------------------------------------------- A.4) Modules, Maps & Ports - What are they ? A MODULE is a single software tool for performing a particular task. Explorer is shipped along with a wide range of modules to perform tasks such as data input, rendering, image processing and manipulation. Each module has associated input and output PORTS which control the flow of data in and out of the module. Modules are connected together to form pipelines which perform specific higher level tasks. The collection of such modules and the links between them are referred to as Explorer MAPS. The function of the map is implicitly defined by the functions of the modules and their interconnectivity. ---------------------------------------------------------------------- A.5) What is the Map Editor/Librarian ? The Map Editor and Librarian are the two main windows that are used when you use Explorer. The MAP EDITOR is a graphical tool for assembling the maps by picking modules and joining them together in an intuitive manner. The editor will only allow the connection of input/output port pairs of the same data type, so Explorer is a `strongly typed system'. The map editor is effectively the interactive prototyping environment of Explorer. The LIBRARIAN is the tool which allows you to browse through existing modules and maps, to choose those which you wish to use with the map editor. ---------------------------------------------------------------------- A.6) What Data Formats can Explorer handle ? Explorer works on 5 main types of data : Parameter : Scalar values such as integers and doubles. Lattice : A Generalized multi-dimensional array. Pyramid : Combines lattices with connectivity information in a hierarchical structure. Geometry: A general, hierarchical, geometric description. Unknown : An uninterpreted stream of bytes The first four types will be consistent between modules perhaps executing on different machine architectures, whereas the last unknown type does not have this feature (unless the user adds XDR-like data conversion him/herself). ---------------------------------------------------------------------- A.7) What is the Data Scribe ? The DataScribe is a graphical utility to allow the user to build templates which can convert data between formats - this is typically used to convert a customized user data file into a lattice(say) and vice versa. These data conversion templates, when completed, constitute modules in Explorer which can be used in the same fashion as any other module. ---------------------------------------------------------------------- A.8) What is the Module Builder ? The Module Builder is a graphical utility to aid in the creation of Explorer modules, by helping you define which data types the module has on its input and output ports, which widgets correspond to which parameters, and how the module will look when placed in the Map Editor. The Module Builder can also automatically generate one of the extra layers of wrapping around the core function, namely the Module Data Wrapper (MDW). ---------------------------------------------------------------------- A.9) What are the MCW and MDW ? The innermost layer of an Explorer module is the computational algorithm which provides the base functionality. This is surrounded first by the Module Data Wrapper (MDW) - which can be generated automatically by the Module Builder - and this performs the conversion of data from Explorer format at ports to the algorithm's internal format, and vice versa. The outermost layer is the Module Control Wrapper (MCW) which is the layer responsible for communicating the module's input and output (Explorer) data with other modules, and maintaining data consistency (a la XDR). This layer also handles comms with the local controller and the firing mechanism. The MCW is necessary whereas the MDW may be bypassed by the programmer if desired, allowing direct access to data at the ports. ---------------------------------------------------------------------- A.10) What is an MVE ? A Modular Visualisation Environment (MVE) is a package for data visualisation consisting of a user interface allowing linking of modules in a pipeline. Explorer is an example of an MVE. [ Chris Thornborrow, EPCC ] ---------------------------------------------------------------------- A.11) What other MVEs are there ? Other MVEs include : AVS - now marketed by AVS (see comp.graphics.avs) apE - originally developed by Ohio Supercomputer Centre Khoros - developed by University of New Mexico (see comp.soft-sys.khoros) It would probably be more correct to define Khoros as a MAB (Module Application Builder) , as it is not aimed solely at visualisation. ---------------------------------------------------------------------- A.12) Is there any overlap between ImageVision and Explorer ImageVision is an object oriented image processing library that currently has about 70 image processing functions. The architecture of ImageVision is designed to handle virtually any size and data typed image. The ImageVision library runs on all SGI machines and on a Cray. The image processing modules of Explorer were developed using ImageVision, and these modules in Explorer map directly to single ImageVision objects. [Nancy Cam - SGI] ====================================================================== B) TOPIC: RUNNING EXPLORER ====================================================================== B.1) Why does Explorer crash immediately ? The main reasons that Explorer will crash on startup (on an SGI machine) are : a) Wrong OS b) Incorrect installation a) Explorer on an SGI requires IRIX v4.0.1 or later. b) If you use the "-r" option on "inst" when installing Explorer, the X11 resource default files do not get installed correctly. Similarly, if you NFS mount /usr/explorer from a file server, these default resource files are not installed on your machine. If you must install Explorer somewhere other than /usr/explorer, first create /usr/explorer as a symbolic link to a directory somewhere else, then install Explorer. If you have installed Explorer with "inst -r" or if you NFS mount it from another machine, you can set up the necessary symbolic links for the X11 app-default files and the shared libraries by using the command (as root): inst -f /usr/explorer/lib/inst/explorer This will establish symbolic links in /usr/lib for those files that must be present on every machine that runs Explorer. This is explained in section 2.3.1 of the Release Notes. (from SGI) [SGI] ---------------------------------------------------------------------- B.2) Can I run Explorer on one machine and display on another ? Explorer itself can run on one machine and display on ANY other machine running an X server. However, the modules Render and DisplayImg will only display/function on machines with GL hardware. The Module Builder and Datascribe can run and display on any X terminal. Since Explorer/Module Builder/DataScribe are X Motif applications, to get these to run externally and display on your local workstation running an X server, set your display variable on the external machine before executing the program in the usual fashion. e.g. a) On Local Machine : xhost + b) On Remote Machine : setenv DISPLAY :0.0 explorer ---------------------------------------------------------------------- B.2) Can I run modules on different machines ? Modules within an Explorer map can execute on different machines, provided that those machines have the execution environment of Explorer ported to them. For example, in a network of 5 SGI w/stations, each of the 5 modules of an Explorer map can be running on a different workstation. This is achieved by pulling up a librarian for each of the machines on which you wish to execute modules. The librarian for these machines will show which modules are available, and these can be placed in a map in the same manner in which local modules are placed. Everything will `look' the same, except that the remote modules will fire and execute on the remote machines - this could be referred to as a form of coarse grain parallelism. At present, the execution environment is ported to SGI and Cray platforms, so modules can only execute on these machine types. ---------------------------------------------------------------------- B.3) How can I start Explorer with a prefined map ? To run explorer with a predefined map, type : explorer -map ,and the map will appear in the Map Editor when it starts up. ---------------------------------------------------------------------- B.4) Can I run Explorer in batch mode (i.e. without the GUI) ? Version 1.0 does not have a non-GUI capability. There are designs being kicked around, but we believe that a totally non-GUI solution is not the full answer, since the "answer" produced by an Explorer map may in fact be an image that you want to view. On the other hand, some Explorer maps may only filter data, produce geometry into a file and not incorporate viewing at all. This "batch mode" would be useful for very long animation runs, for example. Khoros also lets single modules to run "standalone". We don't see this as a requirement for Explorer, except that it could make module debugging simpler -- one of our short-term goals. Being able to debug a module without all of Explorer hanging around would be really nice, especially as debugging tools take more and more resources from the machine. [ Bob Brown - SGI ] ---------------------------------------------------------------------- B.5) Will Explorer work with very large data sets ? The easiest option if you have very large modules is to purchase more memory, but this only extends so far. Large data sets: This is a general weakness of data flow systems. We have a few ideas for helping out, but it becomes very complicated when you want to preserve a conceptually simple programming model. Can we offer an alternative execution model (that is, how things really compute and share data) yet maintain a simple programming model (that is, how the user states what is wanted). [ Bob Brown - SGI ] ---------------------------------------------------------------------- B.6) When does a module fire ? Module inputs can be optional or required, and if the former then the module can happily fire without any input on that port. If the port is required, then a module won't fire until it has data on that port. When new data arrives at a required port, then the module fires. Question: We reckon that it would be `nice to have' a template matching type operation at the input of each module, so that intelligent decisions can be made as to WHEN to fire a module. e.g. don't fire a module when ANY of its inputs change, but be able to choose how a module will fire and how many of its inputs are REQUIRED before a successful fire - this sort of thing would be useful in animations involving multiple file reads. [ Gordon Cameron - EPCC ] The reply : We spent a lot of effort on this in the design phases, and came up with an overly powerful scheme that would be practically unusable, so it did not appear in V1.0. The degree of flexibility that can be offered seems too great, particularly when youconsider the possibility of being able to programmatically add and delete ports. Of course, using cxInputDataChanged judiciously will let you essentially write your own inner firing rules. However, this may break future versions of the firing algorithm. Also, if you have a non-MDW module and never issue a cxInputDataGet call on a port with new data, cxInputDataChanged will always report that there is new data on the port. You must use cxInputDataGet to change the port data state from "new" to "old". [ Bob Brown - SGI ] ---------------------------------------------------------------------- B.7) Why does Explorer run slowly on my system ? [ Jack Gallant - Caltech ] The overhead of X windows and Motif is not insignificant. Two factors can really slow down Explorer: insufficient memory and NFS mounting /usr/explorer. The first one we can help out with, but the second one is out of our hands for the most part (having local copies of the shared libraries can help, though). [ Bob Brown - SGI ] ---------------------------------------------------------------------- B.8) How can I customize the look of Explorer ? Explorer, and the Data Scribe and Module Builder are all X/Motif applications, and have several resources which can be altered so that the tools' appearance can be customised. Look at the explorer directory [/usr/explorer]/lib/X11/app-defaults to see what's what. (The directory enclosed in square brackets is the home of Explorer on your system). ====================================================================== C) TOPIC: USING EXPLORER with the MAP EDITOR ====================================================================== C.1) Why does Explorer ignore all my input ? A possibility is that you have closed the main Explorer window, and an error has been generated - if you have closed the small gui window, then the error diagnostic will not appear on the screen, and the entire interface will appear to hang. However, opening the gui window again will rectify matters. [ Leo Blume - SGI ] ---------------------------------------------------------------------- C.2) Why can't I start a GenerateColormap module ? If you have applications running that have allocated colormap cells, then the number of cells available to GenerateColormap is reduced, so that only one (or perhaps no) GenerateColormap will be able to execute. One way round this is to reconfigure the X server, and this is described in Appendix B of the User Guide (also supplied electronically with the release) - what you end up doing is in effect choosing a different visual. ---------------------------------------------------------------------- C.3) How can I stretch the librarian scrolling list ? You can't #:-} , at least not in Explorer 1.0 [ Roy Hashimoto - SGI ] ---------------------------------------------------------------------- C.4) How can I slice into an iso-surface ? Full Question : I've tried orthoslice, it will move the slice plane into the data but the full iso-surface is still there, the outside is not cut away. [ Gus Williams ] Answers: The slices generated by Orthoslice won't cut away the isosurface. Orthoslice and IsosurfaceLat generate completely independent geometry that is composited in the renderer. It might be nice, though, to have this capability in the future. For the present, you can use SampleCrop to do that or just adjust the transparency on the isosurface so that you can see through it to the cutting plane. [ Leo Blume - SGI ] ...you can use CropLattice to crop the lattice before taking the isosurfaces. I'm not sure how it could be done any other way with the standard module set. [ Robert Skinner - SGI ] ---------------------------------------------------------------------- C.5) How can I render translucent solids ? You can pass your data through the module VolumetoGeom and then on to the Render module. VolumetoGeom makes use of a technique known as "splatting" to visualise volumes like this - a good reference is : Hierarchical Splatting: A Progressive Refinement Algorithm for Volume Rendering by David Laur and Pat Hanrahan. ..and this paper appeared at SIGGRAPH '91. ---------------------------------------------------------------------- C.6) Why can I not get LatFunction to work ? Explorer has a known bug in LatFunction...The following is a long answer, and will be condensed in time. Problem a) - Why can I never get LatFunction to work? The problem is that if LatFunction's "Program File" typein does not refer to an existing file, then the module's interpreter gets confused and will never work correctly on any program file thereafter. Unfortunately, the empty string (the default when LatFunction is brought up from the librarian) is such an invalid name and will confuse the module. Thus, the symptom you will see is that the user instantiates a LatFunction module, types in a file name, and gets errors. e.g. float f[2,3,4]; Second_Out := First_In; yields the error message : [Unbound symbol: First_In] This identifies problem a) - when you instantiate LatFunction, it tries to read file "" and fails. Solution a) All you have to do is instantiate a LatFunction module with the Program File name in place. You can do this by duplicating the brain-dead LatFunction -- the new LatFunction<2> will work as expected (delete the old module after duplicating a new one). You can also save the LatFunction module with typed-in name in a map and load that map. Also, LatFunction-based modules (see the MWG, chapter 4) are less prone to this problem for two reasons. This makes them easier to work with than plain LatFunction. The first reason is that LatFunction-based modules typically have a filename specified, so these will work even when dragged from the librarian. The second :reason is that they typically have required port data, so they will not fire when instantiated, thus giving you time to type the right filename. ========================================================== Problem b) - Why does LatFunction give me the "[Unbound symbol:...]" error message and refuse to work ? This is the same as problem a). The "[Unbound symbol: ...]" message is LatFunction's way of saying that it is confused. Solution b) As solution for Problem a). ========================================================== Problem c) - Why does LatFunction sometimes give an error "[Unbound symbol:...]" on some line after I edit my file, but then not give the error the next time I read in the file? This is related to problems 1 and 2. In this case the parsed program is referenced incorrectly and the interpreter exhibits the same type of confusion as before. However, this error is recoverable by reparsing the Shape program file (type in the "Program File" typein). Solution c) Reparse the Shape program file (type in the "Program File" typein). [SGI] ====================================================================== D) TOPIC: USING THE DATASCRIBE ====================================================================== D.1) Why does the help file not reflect the actual widget ? In some cases, the DataScribe can get confused with consistency between .doc and .help files, but there is a workaround. The following Q&A from the list illustrates a specific example. Original Question : I created a module using the data scribe which had a file browser widget. When I edited the .help file produced the following lines were present .. pbmascii -- Text Note that the widget is described as text, not file browser. Is this deliberate - I can see how it would be as the file browser widget is really an elaborate text widget ? [ Chris Thornborrow - EPCC ] Solution : This looks like a bug. dot-help files are derived from dot-doc files. When you do a "Save" from the datascribe, it appears to not rewrite the doc file (even if you changed a widget type, say, from Text to File Browser) but it does regenerate the help file from the doc file. I tried your example and that is what happened. My guess is that you had previously saved when "pbmascii" was really a Text widget, then you changed it to a browser and saved again. Remove your dot-doc file and do a Save again from datascribe. That should fix things up. Or, if you've already edited the doc file, bring up the module builder on your module and select "Update Document" under the "Build" menu. [ Bob Brown - SGI ] ====================================================================== E) TOPIC: USING THE MODULE BUILDER ====================================================================== ====================================================================== F) TOPIC: PROGRAMMING MODULES ====================================================================== E.1) How can I wake Explorer on events ? I would like wake-up Explorer on the following event: one descriptor is ready for reading/writing [ F. Lapique ] This has to be done using X directly. The following details how : In Version 1.0 Explorer the only way to do this is through X windows. Make your module an X module (in the Build Options... window in the module builder) and then you can use the XtAddInput mechanism to register a callback procedure with the scheduler. The Xt manual describes how to use XtAddInput; it is relatively simple and straightforward. We don't have code examples, but if you have trouble, let me know and I'll write one up. Another user has reported success at doing this. Be aware that execution highlighting will not occur when your callback is called. This is because the module isn't "really" firing. In fact, you should not call cxOutputDataSet() or cxOutputDataFlush() from the callback. Instead, if you want to send data downstream, use cxFireASAP() from the XtAddInput() callback to schedule the firing of your computation routine, and maintain some state that lets that routine know what's what. The next version generalizes this mechanism by adding a cxAddInput routine that works the same way, but doesn't (necessarily) use X windows. (We haven't announced a release schedule for the next version). [ Bob Brown - SGI ] ---------------------------------------------------------------------- E.2) What has happened to the routine cxInputPortStateGet ? There is no such routine, and it shouldn't appear in the documentation. To emulate the stated effect, do : cxInputConnectsGet() // To tell if port is connected cxInputDataGet() // returns 0 for no data cxInputDataChanged() // to find if data there is new or old [ Dave Foulser - SGI ] ====================================================================== G) TOPIC: MODULES AVAILABLE/WANTED ====================================================================== G.1) Where can I get PD modules ? There are a few modules available by anon. FTP, including one to enable/disable geometry information. Many more modules should appear very soon. See the FAQ header for FTP addresses etc... ====================================================================== H) TOPIC: FURTHER INFORMATION ====================================================================== H.1) Where can I obtain documentation ? Compressed electronic copies of Postscript documents are supplied with the release of Explorer. Only certain chapters and an Appendix appear in the directory [/usr/explorer]/doc/userguide, though. You can obtain the complete User Guide, Module Writer's Guide and Module Definitions guide by getting in touch with SGI, who can supply bound copies. The electronic source for the Module Writer's guide is now available by anon. FTP !! (see header for addresses) The contact number I have for info on SGI is (415) 960-1980. ---------------------------------------------------------------------- H.2) Is there a mailing list/FTP site ? At present there is an Explorer mailing list for discussion on all aspects of the package. The list was started in March of '92, and has around 250 subscribers (not including feeds) - several of the developers of Explorer are subscribed, so the list provides a good forum for discussion which may change the shape of future versions. To join the list, or to get further details, send some mail to : explorer-request@castle.ed.ac.uk There is also an FTP site which contains archives of postings to the explorer mailing list, as well as many other things including a User List and an up to date FAQ(this!), and it is hoped that this site will develop into a store for PD modules in time. There are a few modules here just now, but many more are expected soon. The site can be contacted as : ftp.epcc.ed.ac.uk (129.215.56.29) , and supports anonymous FTP. The explorer directory is /pub/explorer. In addition, Jeff Hanson has kindly mirrored this site in the US as : swedishchef.lerc.nasa.gov (139.88.54.33)) ---------------------------------------------------------------------- H.3) Is there a relevant newsgroup ? At present (31st March 1992) there is no newsgroup specifically for the discussion of Explorer-related issues, although this may well change in the near future. However, the groups comp.sys.sgi and comp.graphics.visualization are certainly useful, and often relevant #:-} ---------------------------------------------------------------------- H.4) Why are the electronic PostScript files incomplete ? The SGI Explorer is supplied with a directory /doc, which contains the userguide in PostScript form. This is missing Chapter 1 and the first Appendix. The explanation SGI give is as follows : Chapter 1 is the "Getting Started" guide that comes with the Explorer CD or tape. The missing appendix contains the module manual pages, which are accessible via the Unix "man" command. The release notes are on-line and can be viewed by using the "grelnotes" command. The Module Writer's Guide is not in the software distribution in this release because of differing production schedules for the software and documentation. It may be included in future releases. (from SGI) The Module Writers' Guide is now available by FTP in electronic version. ====================================================================== I) TOPIC: MISCELLANEOUS ====================================================================== I.1) How can I add/correct or comment on Q&As on the FAQ ? Mail explorer-request@castle.ed.ac.uk . Simple ! I.2) Where can I find a list of bugs ? A few bugs are listed in this FAQ. Others can be found by looking at the file in the /pub/explorer/bugs directory at the FTP site.