NAG's IRIS Explorer ™ - Frequently Asked Technical Questions

1. What are the MCW and MDW? [answer]
2. How can I customise the look of IRIS Explorer? [answer]
3. How can I write a sequence of files without having to manually change the filename for each one? [answer]
4. How can I create a volume from a series of images? [answer]
5. How can I change the line thickness for geometry displayed in Render? [answer]
6. I have a button widget attached to an input parameter port on my module. How can I tell when the button has been pressed? Getting the value of the parameter [calling cxParamLongGet()] always returns a value of zero. [answer]
7. I've got a series of data files and I'd like to be able to read them one after another into my map. They're called foo.dat.0, foo.dat.1, ...foo.dat.20. How can I do it? [answer]
8. How can I make an animation of a scene displayed in Render? [answer]
9. How can I get Render to save the current view of a scene? [answer]
10. How can I save the image in Render? [answer]
11. How can I add pieces of simple geometry (possibly textured) such as cubes, cylinders, cones and spheres to my scene in Render? [answer]
12. I can't seem to get transparency to work when displaying geometry in Render. [answer]
13. Can I prevent a module from firing on every change so that I can make a number of changes and have the module fire once? [answer]
14. When I connect GenerateColormap my visualisation has only a single colour, why is this? [answer]
15. When I write my own modules, can I manipulate the control panel widgets from within the user function? [answer]
16. Changing the zoom factor in "DisplayImg" has no effect, why is this? [answer]
17. If my machine does not support OpenGL (e.g. I am using an X terminal emulator), is there an alternative that IRIS Explorer can use for rendering? [answer]
18. Can IRIS Explorer run on systems with parallel processors? Will I see a performance improvement? [answer]

Answers

1. What are the MCW and MDW? [Top]

   The innermost layer of an IRIS 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 IRIS 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 (IRIS Explorer) data with other modules, and maintaining data consistency (a la XDR). This layer also handles communications 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.

2. How can I customize the look of IRIS Explorer? [Top]

   Under UNIX, IRIS Explorer, Data Scribe and the Module Builder are all X/Motif applications, and have several resources that 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 (assuming the system is installed in /usr/explorer).

   The categories in which the modules reside are defined in the file "Explorer.config" in the top-level IRIS Explorer directory. Note that a module can reside in more than one category. Also, categories can be either a directory reference or specify modules individually. In the latter case, the module files must exist in a directory listed in the module search path, also defined in the same file.

3. How can I write a sequence of files without having to manually change the filename for each one? [Top]

   It's often useful to be able to generate a series of file names automatically - for example, when generating output lattices in a loop. In fact, most modules that take parameters and use them as filenames call the function cxFilenameExpand(3E) to convert tildes, environment variables and so on into a complete path. This function also accepts extra codes [after the fashion of strftime(3)], for embedding the current date (time, etc) into a file name. In addition, the special code %n is replaced by an incrementing integer. So, specifying the output filename in a parameter as myfile.%n will generate files named myfile.0, myfile.1, etc.
   
   From within a user's module, the index can be set using cxFilenameIndexSet(3E) or cxFilenameIndexIncrement(3E).

4. How can I create a volume from a series of images? [Top]

   It's often useful to be able to collate a set of images into a volume. For example, the images could be slices from a MRI scan through a 3D object, and there is a need to reconstruct the object in 3D space.

   The simplest method (under UNIX) is to use WriteAnimation. It writes incoming 2D lattices into a single 3D image in FIT format. The FIT file can then be read in by ReadImg, which outputs the data as a 3D lattice. Alternatively, if the images are already on disk as .rgb files, use the ReadImages module, which reads in a series of these files and composes them into a 3D lattice.

   If you already have the component lattices in IRIS Explorer and simply want a module that stacks them, you must write a new module. Although you could use the module builder, it's easier to use the LatFunction module, which enables simple creation and manipulation of lattices via a script written in the Shape language. The script is passed to the module and interpreted by it, which bypasses the traditional edit-compile-link cycle, leading to more rapid development.

   Here is a script that takes two lattices and stacks them together to create a new lattice with a dimensionality which is one greater than that of either of the input lattices.

   foo := scalar_lattice_in(First_In)
   bar := scalar_lattice_in(Second_In)
   baz := outside([foo, bar])
   First_Out := scalar_lattice_out(baz)

   The input lattices must be the same size otherwise LatFunction will complain with a - somewhat obscure - error message. The lattices are stacked in the slowest varying dimension - e.g., if both the input lattices have dimensions of 8 by 8, then the output lattice will have dimensions of 2 by 8 by 8. The stacking direction can be switched to the fastest varying dimension using the inside command - i.e., to get a lattice that's 8 by 8 by 2, change the third line to

   baz := inside([foo, bar])

   See Chapter 10 of the Module Writer's Guide for more information on the LatFunction module and the Shape language.

5. How can I change the line thickness for geometry displayed in Render? [Top]

   There are two ways of achieving this.

   Some of the default rendering options can be changed using a configuration File. This file should be named .Renderrc and should be in your home Directory. The default line width is 1; to set it to some other value (2, say), use a ".Renderrc" file containing the following lines:

   #Inventor V2.0 ascii
   DrawStyle {
   LineWidth 2
   }

   See the Render help file for details of other options.

   Additionally, a module has been written by NAG to achieve this, called "LineEdit". Ask your NAG contact for details on how to download this module.

6. I have a button widget attached to an input parameter port on my module. How can I tell when the button has been pressed? Getting the value of the parameter [calling cxParamLongGet()] always returns a value of zero. [Top]

   A button widget always delivers the same data value to the parameter, which means that the value of the parameter is useless in deciding whether the button has been pressed.

   Instead, call cxInputDataChanged(). This returns a non-zero value if new data has arrived on the input port - i.e. if the button has been pressed. Note that it checks to see if the status of the data has changed from old to new - not if its value has changed.

   Note that calling this routine doesn't change the status of the data. Instead, if the status has changed, then it can be reset to old by calling cxInputDataGet().

7. I've got a series of data files and I'd like to be able to read them one after another into my map. They're called foo.dat.0, foo.dat.1, ...foo.dat.20. How can I do it? [Top]

   We can use the For module to step through parameter values in a map.

   Here, we can use it to step through the numeric part of these filenames,by setting Start Value to 0.0, End Value to 20.0 and Step Value to 1.0. Connect For's Current Value port to the input filename port on the module that reads the data files (the module might complain that it can't read in the file named 0.00000, but we can ignore this). Now open the Parameter Function editor on the reader module. Highlight the input filename parameter (you should see a connection from For.Current Value, aliased to A). For the parameter function, type in

   "foo.dat." + (string)(long)A

   By default, A comes in as a parameter of type double (e.g. as 0.00000); we need to cast that to a long (e.g. to 0) and then to a string (e.g. to"0") before we can concatenate it to the base of the filename.

   The reader will build the filename in its parameter function editor,read the file and pass the data onto the next module in the map. To close the loop, make a connection from the Firing Done port of the final module in the map to the Fire port of the For module; hitting Refire on the For module will then cause it to start stepping through the values.

8. How can I make an animation of a scene displayed in Render? [Top]

   The answer to this question has two parts - how to create the animation,and how to save it.

   The display model in Render is of a camera pointing at a scene consistingof a collection of geometric objects (lines, surfaces, spheres, etc). The animation could be produced in a number of ways, such as moving the camera around a static scene, keeping the camera fixed while the scene changes, moving one of the objects within the scene, etc. Some of these examples are illustrated in the demo maps. For example, the flythru map features a flight around a scene containing a coloured surface, while the vslice map illustrates a changing scene which contains a slice that moves through a vector field. Finally, the animateIso map features a camera moving around a scene that is changing as new isosurfaces are created.

   Making the camera move can be done using the AnimateCamera module. Essentially, this takes a set of key camera positions and directions (which can be given to the module when it is in 'Learn' mode, or read in from a file, as in the case of the demo maps) and interpolates between them to produce a smoothly varying viewpoint. The module allows for user control over the step size and delay when creating the animation, as well as other parameters.

   Other modules can be used to create a changing scene. IRIS Explorer's support for loops in maps allows parameters to step through a sequence of values - for example, the For module generates iterations of a variable which can be connected to other modules in the map. Thus, in the vslice map, it is the slice number that is being varied, while in the animateIso map it is the isosurface threshold value.

   Having created the animation, how can it be saved? The Render module can be put into a mode where each change to its display (whether caused by a change in the camera, or a change in the scene) causes the image to be snapped and written to its Snapshot output port. If this port is connected to the WriteAnimation (UNIX), WriteMovie (SGI only) or WriteAVI (Windows) module, the image will be added either to an animation (in the FIT format) or to a movie (in the SGI moviefile format) or to an AVI file respectively. By default, however, Render does not automatically snap its image each time it changes. A parameter port named Snap On Redraw controls Render's behaviour. To turn it on, connect it to a port that outputs a non-zero parameter. For example, use the WidgetsIntegerSlider module, which was designed for use in precisely this situation (see its help file), and set the slider to some non-zero value. So, make the following connections:

   Render::Snapshot -> WriteAnimation::Input (or WriteMovie::Input, or WriteAVI::Image)
   WidgetsIntegerSlider::IntegerSlider -> Render::Snap On Redraw

   Type a filename into the text slot on WriteAnimation; the currently rendered image will be written to that file, and each time that image changes, the new image will be added to the animation. Note that the resolution of the animation is determined by the size of the Render window when the first image was snapped.

9. How can I get Render to save the current view of a scene? [Top]

   Render uses an interaction model of a camera pointing at a scene. By default, when Render starts up the camera is oriented to point at the origin of its internal coordinate system. You can change camera parameters to get a better view of the scene. However, when the map is saved, information about this new view is lost (upon reloading the map, the camera is pointing at the origin once again).

   The view is represented as a geometry type within IRIS Explorer. So it can be saved in a file by bringing up the WriteGeom module and connecting

   Render::Output Camera -> WriteGeom::Input

   Type a filename into the text slot on WriteGeom; the current view will be written to that file. Each time the view is changed, this file is rewritten. To restore the view, use ReadGeom. Connect

   ReadGeom::Output -> Render::Input Camera

   The camera will jump to the view stored in the file; this view can be restored once again by refiring ReadGeom - e.g. by causing it to reread the file.

10. How can I save the image in Render? [Top]

    Render has a port named Snapshot which it uses to output its currently rendered image (in the form of a lattice). If this port is connected to the Input port of the WriteImg module, the image can be saved as a file (currently, WriteImg supports the creation of image files in the TIFF, FIT or SGI formats). By default, however, Render does not automatically snap its image on each refiring. Its behaviour is controlled by a parameter port named Snap. This has a pushbutton widget attached to it, but the widget is hidden to reserve all the space on the control panel for the rendered image.

    The image may be snapped by wiring a parameter controlled by a pushbutton widget on another module to the Snap parameter port on Render; pushing the button on the upstream module will then trigger the Snap parameter. A good choice for the upstream module is WidgetsButton (this was designed for use in precisely this situation - see its help file). So, make the following connections:

    Render::Snapshot -> WriteImg::Input WidgetsButton::Button -> Render::Snap

    Type a filename into the text slot on WriteImg; the currently rendered image will be written to that file. Note that the resolution of the image is determined by the size of the Render window when the image was snapped.

11. I'd like to be able to add pieces of simple geometry (possibly textured, as in the nice images in issue 1 of this newsletter) such as cubes, cylinders cones and spheres to my scene in Render. Is there a module that can help? [Top]

    Since IRIS Explorer is built on top of Inventor, it's easy to add extra Geometry to a scene - just read it in from an Inventor file using the ReadGeom module and pass it directly to Render. The file can be created using any Inventor-based application (such as SGI's Showcase 3.x) to build, colour and texture the objects. IRIS Explorer modules can be written to accept input geometry, manipulate it (either using calls to the cxGeo* routines in the IRIS Explorer API, or - if Inventor is installed on the system - using the Inventor API directly) and pass it out again. See, for example, the module PutGeom.

12. I can't seem to get transparency to work when displaying geometry in Render. [Top]

    Objects in Render can be picked and their material properties edited via the material editor. Properties that were not specified when the object was created may be changed in this way. Transparency values can range from 0.0 (opaque) to 1.0 (completely transparent).

    The appearance of objects having nonzero transparency values can be affected by the type of transparency that is currently selected via the Viewing pull-down menu in Render. By default, this is set to screen door transparency. Although this is the cheapest type, and even works on machines that don't have special hardware, it can produce some odd artefacts, especially when transparent surfaces are stacked.

    Selecting other types (see the Render help file for details) can change the appearance of the scene quite dramatically!

    In addition, it might be helpful to switch Render into single buffering mode (via the Draw Style item on Render's pop-up menu), since some machines sacrifice colour resolution when double buffering the display.

13. Can I prevent a module from firing on every change so that I can make a number of changes and have the module fire once? [Top]

    Yes. By default, any change on a module input (including the controls) causes the module to "fire" (i.e., execute). The only exception to this is modules that have an "Output?" menu (e.g., GenerateColormap). This menu is designed specifically to allow the user to make a number of changes (in "build" mode) then apply them by switching into "Run" mode.

    For modules without such a menu, the simplest solution is to disable the module (by right-clicking on the title bar and selecting "Disable"), make the required changes, then enable the module again (using the same process).

    If you are writing your own module you get the latter suggestion by default. You can employ the Build/Run approach (as in "GenerateColormap") by using the API routines and a parameter to control the "flushing" of output data.

14. When I connect GenerateColormap my visualisation has only a single colour, why is this? [Top]

    First, you must ensure that GenerateColormap is connected properly. Normally, the "Data In" input port should have the lattice being rendered (so that the colour scale matches the data range). The "Colormap" output should be wired to the "Colormap Input" port of the module being used to generate the visualisation geometry (e.g. Contour).

    Note that GenerateColormap module has an "Output?" menu. Whilst this shows "Build" (the default), you can make changes to the colour map without firing the downstream modules. To apply the current colour map, switch this menu into "Run" mode. Note that in this mode, EVERY change to a control will cause the downstream modules to fire.

15. When I write my own modules, can I manipulate the control panel widgets from within the user function? [Top]

    Yes. There is quite a rich set of API routines to control each widget. These are named cxInWdgtxxx and cxInputxxx, where xxx represents the function. These functions include:

    • hide/show the widget
    • enable/disable the widget
    • get/set the value contained by the widget
    • interrogate the widget for its value
      
      
16. Changing the zoom factor in "DisplayImg" has no effect, why is this? [Top]

    In order for operations to work on an image in the DisplayImg module, the image must be selected, even if only one image is loaded (you can "fan-in" many images to display in one copy of DisplayImg). Ensure that you select the image by clicking on it with the left-hand mouse button, before making any changes.

17. If my machine does not support OpenGL (e.g. I am using an X terminal emulator), is there an alternative that IRIS Explorer can use for rendering? [Top]

    Yes. The display modules in IRIS Explorer (e.g. Render) can either use OpenGL or X (via the Mesa 3-D graphics library) for rendering. The former option (which is the default) usually gives faster rendering speeds, but can only display on X displays that support the GLX extension. The latter option displays on a wider variety of hardware.

    Choose the rendering option by setting the CXGLTYPE environment variable to OPENGL or MESAGL. IRIS Explorer uses this to determine the location to search for display-based modules.

18. Can IRIS Explorer run on systems with parallel processors? Will I see a performance improvement? [Top]

    Yes, IRIS Explorer does run on a multi-processor machine. Because each IRIS Explorer module is an individual process, the Operating System (or more accurately, the load balancing mechanism of the operating system) decides which module to run on which processor. In this way, the performance of an IRIS Explorer map will be improved by running on multi-processor systems.