Data visualization with the AVS Interface routines version 3.0 Jan Kraak Computing Centre University of Groningen P.O. Box 800 9700 AV Groningen The Netherlands email: J.Kraak@rc.rug.nl November 1994 (c) Copyright 1994, University of Groningen Groningen, The Netherlands Abstract The AVSI_routines establish an easy to use interface between the visualization system AVS and FORTRAN, C or PASCAL application programs to apply basic 1D, 2D, 3D and 4D data visualization techniques for scalars, vectors and combinations. The use of these routines does not require any knowledge of AVS fields and networks, only some basic AVS knowledge is required. For instance, the FORTRAN 77 call AVSI_3D_scalar_real_uniform ('Isosurface', 'iso', dim1, dim2, dim3, s3) or the C equivalent AVSI_3D_scalar_real_uniform ("Isosurface", "iso", dim1, dim2, dim3, s3); displays 3D real scalar data sampled at a uniform grid as an isosurface. This isosurface can further be manipulated by the usual AVS point-and-click interface. Isosurface is one of the 15 visualization techniques for 3D real scalar data, including three types of Volume Rendering, Bubbleviz, Line Contour, Orthogonal Slice and Brick. If desired, the networks and fields generated by the AVSI_routines can form a starting point to explore the full flexibility of AVS. It is possible to activate AVS at a remote host, without the need to have AVS at the local platform. Special features include module generation, client-server mode and CLI-script file generation. The AVSI software suite, developed at the University of Groningen, is available as public domain software with makefiles for SGI, Convex, CM-5, HP, Sun, DEC and IBM/RS-6000 platforms. It will be contributed to the International AVS Center. The quickest way to learn how to use the AVSI_routines is to install the AVSI software suite, run some example programs and look at the results, as described in chapter 5. Parts of this document originate from the paper "AVS Interface Routines", that was presented at the AVS'94 Users Conference, Boston Massachusetts, May 2-4 1994. Table of contents Chapter 1 Introduction 1.1 Why AVS Interface? 1.2 Visualization techniques 1.2.1 One scalar techniques 1.2.2 One vector techniques 1.2.3 Two scalars techniques 1.2.4 One scalar and one vector techniques 1.3 FORTRAN 77, C, PASCAL, CM Fortran and C* 1.4 New visualization techniques 1.5 Installation and examples Chapter 2 Specification of AVSI_routines 2.1 General remarks 2.1.1 Initialize AVSI 2.1.2 Meaning of AVSI_routine name 2.1.3 Visualization technique and file name 2.1.4 Data parameters 2.1.5 Grid parameters 2.1.6 A few remarks about using AVS 2.2 One scalar routines 2.2.1 1D_scalar 2.2.2 2D_scalar 2.2.3 3D_scalar 2.2.4 4D_scalar 2.3 One vector routines 2.3.1 2D_vector 2.3.2 3D_vector 2.4 Two scalars routines 2.4.1 2D_ss 2.4.2 3D_ss 2.5 One scalar and one vector routines 2.5.1 2D_sv 2.5.2 3D_sv 2.6 Auxilary routines 2.6.1 Define internal AVSI parameters 2.6.2 Remove AVSI_files 2.7.3 Script files and macros Chapter 3 Example programs 3.1 FORTRAN 77, all platforms 3.2 C , SGI, Convex, HP 3.3 PASCAL , HP 3.4 CM Fortran, CM-5 3.5 C* , CM-5 Chapter 4 Advanced use 4.1 Network editor 4.2 Adding modules to AVSI_network 4.3 Own network as new visualization technique 4.4 Partial functioning of AVSI_routines 4.5 Remote AVS 4.6 Client-server mode 4.7 Module generation 4.8 CLI-script file generation with macros Chapter 5 Installation and use of example programs 5.1 Installation of the AVSI software suite 5.2 Make commands to run example programs in directory avsi 5.3 How to use AVSI in an arbitrary directory Appendix A Survey of AVSI_routines A.1 Initialization A.2 One scalar routines A.3 One vector routines A.4 Two scalars routines A.5 One scalar and one vector routines A.6 Auxiliary routines Acknowledgements I would like to thank my collegues Rob de Bruin, Maarten van Gelder, Jan Hemel, Doeko Homan, Peter van Laarhoven, Tjeerd van der Meer and Haijko Wind for their assistance with the preparation of this document and the implementation of the AVS Interface. Ian Curington (AVS Inc) told me how to open the Network Editor. Chapter 1 Introduction 1.1 Why AVS Interface? Novice AVS users often have difficulties with importing data in AVS. Adaption of data to the AVS field format, which frequently requires reformatting or writing a specific data import module, establishes a serious obstacle. It also takes quite some time to master the construction of relevant networks. Although the Data Viewer is a good aid to learn network construction, it still requires data to be in AVS format. At the University of Groningen, most of the potential AVS users produce visualization data by programs written in FORTRAN, C or PASCAL. In order to help these users to learn how to apply AVS to their data in a short time, a library of AVS Interface Routines is developed (abbreviated to AVSI_routines) that does not require any knowledge of AVS fields and networks to display several data types defined for structured grids through the basic data AVS visualization techniques. Another design objective was to facilitate transfer from the AVSI_routines to the Network Editor, in order to apply other or more sophisticated AVS functions. AVSI_routines, that are implemented in FORTRAN 77, are very similar to traditional high-level graphics routines. E.g. the FORTRAN 77 call AVSI_3D_scalar_real_uniform ('Isosurface', 'iso', dim1, dim2, dim3, s3) or in C AVSI_3D_scalar_real_uniform ( "Isosurface", "iso", dim1, dim2, dim3, s3); visualizes the 3D real scalar data defined at a uniform grid as an isosurface. However, an essential difference is that one only has to specify the visualization technique (e.g. Isosurface) and that attributes of the technique (e.g. the iso level and viewing parameters) have to be specified by means of the AVS point-and-click interface and NOT by calls to attribute specifying routines, as is the case for traditional graphics libraries. So, AVSI_routines are far more easy to use interactively than traditional graphics routines. The working of AVSI_routines is quite simple. Firstly, an AVS field files are generated and secondly a network file according to the visualization technique. Finally AVS is started, using the network and the AVS field to display the data. By means of the AVS point-and-click technique, one can then change the visualization. Clicking the EXIT button stops AVS. After that the application program continues. A more efficient way to use AVS is described in section 4.6. Chapter 2 describes the routines in some detail. Example programs in chapter 3 illustrate the use and the visualization techniques of the AVSI_routines. 1.2 Visualization techniques AVSI_routines establish a programmer's interface to the most frequently used 1D, 2D, 3D and 4D data visualization techniques in AVS. Data can be scalars, vectors or combinations of scalars and vectors, that are computed or sampled at structured grids. The dimension of the grid is equal to the number of independent variables of the data. Most of the techniques work alike for uniform, rectilinear and irregular grids. At present, only the real data type is supported. The various techniques are shortly described below. If the name of the technique is not self-explanatory, one or more essential modules of the network implementing this technique, are given in parentheses. Chapter 2 provides more information about the AVSI_routines. 1.2.1 One scalar techniques Scalar data of one independent variable are visualized through the Graph Viewer as - Single Line - Area - Scatter - Bar Presently there are seven techniques for 2D scalar data: - Surface, Colored_Surface (FIELD TO MESH) - Contour (GRAPH VIEWER) - Image, Image_GrayScale (IMAGE VIEWER) - 3D_Bar_Chart (3D BAR CHART) - Threshold_Contour (THRESHOLD SLICER) 3D scalar data can be visualized by 15 techniques: - Histogram - Isosurface, Colored_Isosurface - Line_Contour (CONTOUR TO GEOM) - Threshold_Slice - Volume_Rendering_Tracer (TRACER, DISPLAY TRACKER) - Volume_Rendering_X-ray (X-RAY) - Volume_Rendering_Cube (CUBE, DISPLAY TRACKER) - Bubbleviz - 2D_Line_Graph (GRAPH VIEWER) - Arbitrary_Slice - Orthogonal_Slice - Orthogonal_Surface - Three_Orthogonal_Slices (three different modules ORTHOGONAL SLICER) - Brick Program fexample1.f (FORTRAN 77, section 3.1) and the equivalent program cexample1.c (C, section 3.2) illustrate these techniques. 3D slices sampled from 4D scalar data by the module TIME SAMPLER can be visualized by: - Isosurface - Bubbleviz - Volume_rendering. 1.2.2 One vector techniques Vectors of two and three independent variables (2D and 3D) can be visualized by five techniques taken from the Data Viewer: Hedgehog, Colored_Hedgehog, Streamlines, Colored_Streamlines and Particle_Advection. Because AVS only accepts 3D vectors, a third vector component equal to 0 is added to 2D vectors by the AVS interface. See the example programs in section 3.1 and 3.2. 1.2.3 Two scalars techniques Two scalar quantities defined at a uniform 2D grid can be visualized by two separate images. Two scalars in 3D can be visualized by Colored_Isosurface. One variable is visualized as an isosurface and the other as a color on that isosurface, using the module ISOSURFACE. 1.2.4 One scalar and one vector techniques The technique for one scalar and one vector quantity in 2D is Contour_Hedgehog. In 3D a Isosurface is combined with Hedgehog or Streamlines. 1.3 FORTRAN 77, C, PASCAL, CM Fortran and C* AVSI_routines are programmed in standard FORTRAN 77. Lower case letters and names longer than 6 characters are the only deviations from the FORTRAN 77 standard, which are supported by a lot of modern FORTRAN 77 compilers. Therefore, the AVSI_routines can be installed at almost any platform having a FORTRAN 77 compiler. By means of the c_to_f77 interface, which is transparent to the user, one can call the AVSI_routines from C in a similar way as from FORTRAN, see the program cexample1.c in 3.2. The c_to_f77 interface is generated by the AVS utility program f77_binding, described in appendix H of the Developer's Guide. This interface is tested for Silicon Graphics(SGI), Convex and Hewlett Packard (HP) platforms. Without the c_to_f77 interface, one can call the AVSI-routines DIRECTLY from C, e.g. for DEC, Sun, IBM and CM-5. This is compiler dependent, see the C* example in section 3.5 and make commands in section 5.2. At Hewlett Packard (HP) and Silicon Graphics (SGI) platforms, AVSI routines can be called from PASCAL, see HP-example in section 3.3. Because arrays in FORTRAN are stored differently from arrays in C, the routine AVSI_transpose() has to be called when using AVSI_routines from C. Similarly, use AVSI_transpose_ in PASCAL. CM Fortran and C* are programming languages for parallel computing at a CM-5. Sections 3.4 and 3.5 illustrate the use of AVSI in these languages. 1.4 New visualization techniques The AVSI_routines support the basic visualization techniques for scalar and vector data in AVS. Sometimes, the networks corresponding to these techniques are too restricted and have to be extended with other modules using the Network Editor. One can for instance add modules for annotation, modules that generate geometries or modules for animation, e.g. a series of 3D time samples. After that, the modified network can be added to AVSI network directory (specified by AVSI_initialize) and be used as a new visualization technique. See section 4.3. 1.5 Installation and examples The AVSI_routines, that are developed at the University of Groningen (The Netherlands), are freely available for non-commercial use from the anonymous FTP-server ftp.rug.nl. See chapter 5 for details. This chapter also shows how to run example programs. The AVSI_routines will be contributed to the International AVS Center (avs.ncsc.org) in order to make them available for the AVS community. Chapter 2 Specification of AVSI_routines 2.1 General remarks With the AVSI_routines one can visualize scalars and vectors (or combinations) that are computed or sampled at uniform, rectilinear or irregular grids. There are no AVSI_routines for unstructured grids. Name and parameters describe the field and the network being generated. For C programmers: The following description is meant for FORTRAN 77, so strings have single quotes (') and array indices are in parentheses (). Apart from a few syntactic differences, the use of the AVSI_routines is similar for C. In C strings are in double quotes (") and array indices are in square brackets [ ]. See survey in Appendix A. 2.1.1 Initialize AVSI The AVS Interface has to be initialized by the next call: AVSI_initialize(net_dir, file_dir, display, AVS_options) net_dir = network directory, containing networks for visualization techniques. See section 5.1 and 5.3. file_dir = directory for files generated by AVSI, e.g. '.' or '/tmp'. display = display name / I.P. address of workstation:0.0 This overrides the current setting of the DISPLAY environment variable, which is used for display=' '. AVS_options = AVS command line options like: -nohw for workstations without hardware rendering and X-terminals. -gamma <...> gamma-factor for the brightness of AVS output windows (except Geometry Viewer) produced with a hardware renderer. Advice: start with empty string. Consult the chapter "Starting AVS" of the AVS User's Guide for options, if AVS does not work as desired. Remarks: - See section 4.5 for use of AVS at remote host. - If string parameter = '*' you are prompted for to type in the parameter. Note: This option does not work for every C compiler. 2.1.2 Meaning of AVSI_routine name Parts of the name of a AVSI_routine describe the data sort and the grid (mapping) type. The name has the following general form: AVSI_ndimD_data_type_grid ndim = describes the data and grid dimension ndim = 1..4 data = data sort with values: scalar - for scalar (1-vector) data vector - vectors, 2D vectors have components (vx, vy) 3D vectors have components (vx, vy, vz) ss - two scalars sv - combination of scalar and vector See section 2.1.4. type = data type, at present only real grid = type of the grid at which the data are computed or sampled. See 2.1.5. grid can be uniform, rectilinear and irregular. These are structured grids. AVSI does not support unstructured grids. 2.1.3 Visualization technique and file name The first parameter (vis_tech) of an AVSI_routine is a character string defining the visualization technique for data and grid. The following description of the routines provides the available techniques for each routine. For vis_tech = '*', a menu of available techniques is displayed, from which one can be chosen, see section 3.1. The second parameter (file) is a character string, forming the first part of file names that are generated by the AVSI_routine in the directory specified by the second parameter of AVSI_initialize. The second part of a file name is one of the next extensions: .net for network file (ASCII format) .fld for field description file (ASCII format) .data for visualization data file (Fortran UNFORMATTED format) .rect for file with x (, y (and z)) values of a rectilinear grid (Fortran UNFORMATTED format) .irreg for file with coordinates of an irregular grid (Fortran UNFORMATTED format) .cli for CLI command file .avs for AVS startup file at a remote computer (ASCII format) see section 4.5. .f for FORTRAN 77 source file of module, see section 4.7 .make for makefile of module, see section 4.7 Remark: If string parameter = '*' you are prompted to type in the parameter. 2.1.4 Data parameters ndim (see 2.1.2) decribes the dimension of the grid at which the data are computed or sampled. The third parameter of an AVSI_routines (dim1, integer) specifies the number of grid points in dimension 1. Similarly, dim2 specifies the number of grid points in dimension 2. Etc. 1D scalar data are transferred by the array s1 with length dim1. 2D scalar data are transferred by the two dimensional array s2(dim1, dim2). Similar for 3D and 4D. 2D vectors are transferred by the arrays vx2(dim1, dim2) and vy2(dim1, dim2) and 3D vectors by vx3(dim1, dim2, dim3), vy3(dim1, dim2, dim3) and vz3(dim1, dim2, dim3). These parameters also apply to data = ss and data = sv. 2.1.5 Grid parameters The grid points must be specified by cartesian coordinates. A point of a 2D grid is specified by the indices i and j, with i = 1...dim1, j = 1...dim2. Point (i,j) of a 2D uniform grid has coordinates (i,j). These coordinates do not have to be specified when using an AVSI_routine. Point (i,j) of a 2D rectilinear grid has coordinates (x(i), y(i)), where x(i) is the element i of an array x of length dim1. Similar for y(i). The arrays x and y must be specified. Point (i,j) of an 2D irregular grid has coordinates (xi2(i,j), yi2(i,j)), where xi2(i,j) is an element of the two dimensional array xi2 declared as DIMENSION xi2(dim1, dim2). Similar for yi2(i,j). The user must specify the arrays xi2 and yi2. 1D, 3D and 4D grids are defined in the same way. The example program fexample2.f in the AVSI software suite, described in chapter 5, demonstrates the use of rectilinear and irregular 3D grids. The next examples of a 2D grid with dim1 = 3 and dim2 = 3, illustrate the three different grid types. Uniform j | 3 | (1,3) (2,3) (3,3) 2 | (1,2) (2,2) (3,2) 1 | (1,1) (2,1) (3,1) --------------------------- 1 2 3 i Rectilinear j | 3 | (1,2.7) (1.5,2.7) (2.1,2.7) 2 | (1,1.3) (1.5,1.3) (2.1,1.3) 1 | (1,1) (1.5,1) (2.1,1) ------------------------------- 1 2 3 i Irregular j | 3 | ( .9,2.7) (1.6,2.5) (2.4,2.1) 2 | (1.1,1.3) (1.5,1.4) (2.1,1.5) 1 | ( 1,1) (1.4,1) (2.0,1) --------------------------------- 1 2 3 i 2.1.6 A few remarks about using AVS The AVSI_routines start AVS default without the Network Editor. Module parameters have default values. The left window contains the module list (Top LevelStack) of the network that implements the specified visualization technique and below that there is the control panel of one of the modules of the network (indicated by a red button in the list). The visualization technique 'Isosurface' initially shows the control panel of the module ISOSURFACE, containing a dial for the isolevel. Rotating this dial changes the iso level. Clicking another module button in the module list results in another control panel. See the AVS User's Guide for more details about using AVS. Most AVSI_routines use the Geometry Viewer. The 1D routines and a few other routines apply the Graph Viewer. The 2D techniques 'Image' and 'Image_GrayScale' use the Image Viewer. Some experience with these AVS Viewers is required for the use of the AVSI_routines. Apply the Data Viewers pull down menu (in the upper left part of the AVS screen) to see the control panel of one of the Viewers. Some of the visualization techniques, e.g. vector techniques, initially show an empty Geometry Viewer window. The description of the relevant routines tells what to do to obtain a picture. Section 3.1 contains a Fortran 77 program with AVSI_calls. Section 3.2 contains a similar program in C and section 3.3 a similar PASCAL program. Use AVSI_def_network to apply the Network Editor, see section 2.6.1. It is also possible to activate the Network Editor in the visualization method menu, see section 3.1. 2.2 One scalar routines 2.2.1 1D_scalar AVSI_1D_scalar_real_uniform (vis_tech, file, dim1, s1) AVSI_1D_scalar_real_rectilinear (vis_tech, file, dim1, s1, x) vis_tech = 'XY_Graph' Data are visualized as a line diagram (Simple Line) by the Graph Viewer that has three additional techniques: Area, Scatter and Bar. Use the Graph Viewer control panel to activate one of these 1D_techniques. The Graph Viewer also has options for axes and labels. 2.2.2 2D_scalar AVSI_2D_scalar_real_uniform (vis_tech, file, dim1, dim2, s2) vis_tech = 'Surface' Data values in the gridpoints are mapped to heights above grid plane, which define a 3D surface. The Z scale dial of the FIELD TO MESH control panel scales the mapping from data to heights. vis_tech = 'Colored_Surface' The only difference with Surface is that at same time the gridvalues are color coded. vis_tech = 'Contour' The Graph Viewer draws by default 5 contour lines which connect points with the same data values (level). The Graph Viewer has options to change the number of contour lines and their level values, see Graph Viewer/Contour Level Selection. vis_tech = 'Image' The data values in the grid points are coded in color, as defined by a color map (module GENERATE COLORMAP) and displayed as an image by the Image Viewer. Activate the control panel of the Image Viewer and click the Normalize button to let the image fill the window. Several image processing techniques e.g. edge detect, convolve and display histogram, are available in the Image Viewer. Use AVSI_def_minmax to ensure that the data range for the colormap is the same for different images, see 2.5.1. vis_tech = 'Image_GrayScale' Instead of colored image a gray scale image. vis_tech = '3D_Bar_Chart' The data values are mapped to the lengths of bars of a so-called 3D bar diagram. vis_tech = 'Threshold_Contour' A contour level corresponding to level 1 is drawn. If the data range does not contain 1, the window is empty initially. AVSI_2D_scalar_real_rectilinear (vis_tech, file, dim1, dim2, s2, x , y ) AVSI_2D_scalar_real_irregular (vis_tech, file, dim1, dim2, s2, xi2, yi2) vis_tech = 'Surface' vis_tech = 'Colored_Surface' vis_tech = 'Contour' vis_tech = 'Threshold_Contour' See remarks for AVSI_2D_scalar_real_uniform. 2.2.3 3D_scalar AVSI_3D_scalar_real_uniform (vis_tech, file, dim1, dim2, dim3, s3) AVSI_3D_scalar_real_rectilinear (vis_tech, file, dim1, dim2, dim3, s3, x , y , z) AVSI_3D_scalar_real_irregular (vis_tech, file, dim1, dim2, dim3, s3, xi3, yi3, zi3) vis_tech = 'Histogram' A histogram of the data values is drawn by the Graph Viewer. vis_tech = 'Isosurface' Draws an isosurface that connects points having the same data value (level). The iso level can be changed by moving the vertical line in the color legend, or by rotating the isolevel dial of the ISOSURFACE control panel. vis_tech = 'Colored_Isosurface' Same as Isosurface, but now the surface is colored according to the color legend. vis_tech = 'Line_Contour' A variant of Isosurface. The isosurface is now formed by lines instead of surface patches (Isosurface). vis_tech = 'Threshold_Slice' See documentation of module THRESHOLD SLICER. vis_tech = 'Volume_Rendering_Tracer' See documentation of module TRACER. vistech = 'Volume_Rendering_X-ray' See documentation of module X-RAY. vistech = 'Volume_Rendering_Cube' See documentaion of module CUBE. vis_tech = 'Bubbleviz' Data values are coded simultaneously as color and as the radius of small spheres. Initially, the Geometry Viewer window is empty because the default value of the Radius Scale (see control panel of module BUBBLEVIZ) is zero. vis_tech = '2D_Line_Graph' The Geometry Viewer visualizes the values in a plane perpendicular to one of the axes by color. The Graph Viewer displays the values along a movable line (Graph Select) in that plane as a Simple Line. vis_tech = 'Arbitrary_Slice' Data values in an arbitrary plane are color coded. vis_tech = 'Orthogonal_Slice' Data values in a plane perpendicular to one of the coordinate axes are color coded. For uniform grids, this technique can be used to animate a sequence of 2D data. vistech = 'Orthogonal_Surface' Data values in a plane perpendicular to one of the coordinate axes are color coded and mapped to a surface. vis_tech = 'Three_Orthogonal_Slices' This technique for uniform grids visualizes the data by color in the three planes perpendicular to the coordinate axes. Rotating the Slice Plane dial of one the ORTHOGONAL SLICE control panels moves one of the planes. Rotate the object to see all planes in color. This technique was developed by dr. R. Verstappen, University of Groningen. vis_tech = 'Brick' The data values on the sides of a brick are color coded using texture mapping. The form of the brick can be changed by the BRICK control panel. Some workstations have hardware texture mapping. If not, use Software Rendering (under the Camera button of the Geometry Viewer). 2.2.4 4D_scalar AVSI_4D_scalar_real_uniform (vis_tech, file, dim1, dim2, dim3, dim4, s4) vis_tech = 'Isosurface' vis_tech = 'Bubbleviz' vis_tech = 'Volume_Rendering' 3D cross sections of the 4D data set (apply time-step dial of module TIME SAMPLER) are displayed according to techniques described in section 2.2.3. 2.3 One vector routines 2.3.1 2D_vector AVSI_2D_vector_real_uniform (vis_tech, file, dim1, dim2, vx2, vy2) AVSI_2D_vector_real_rectilinear (vis_tech, file, dim1, dim2, vx2, vy2, x , y ) AVSI_2D_vector_real_irregular (vis_tech, file, dim1, dim2, vx2, vy2, xi2, yi2) For all visualization techniques the window of the Geometry Viewer is empty at first. Click Channel 0, Channel 1 and Channel 2. vis_tech = 'Hedgehog' Vectors can be visualized as arrows. At first, only one vector is drawn. Click Line, Circle, Plane, etc. to display more vectors. vis_tech = 'Colored_Hedgehog' Arrows are colored according to their lengths. vis_tech = 'Streamlines' vis_tech = 'Colored_Streamlines' vis_tech = 'Particle_Advect' Particles released at equidistant time steps are drawn (Advect Batch). See AVS module documentation for more details. 2.3.2 3D_vector AVSI_3D_vector_real_uniform (vis_tech, file, dim1, dim2, dim3, vx3, vy3, vz3) AVSI_3D_vector_real_rectilinear (vis_tech, file, dim1, dim2, dim3, vx3, vy3, vz3, x, y, z) AVSI_3D_vector_real_irregular (vis_tech, file, dim1, dim2, dim3, vx3, vy3, vz3, xi3, yi3, zi3) vis_tech = 'Hedgehog' vis_tech = 'Colored_Hedgehog' vis_tech = 'Streamlines' vis_tech = 'Colored_Streamlines' vis_tech = 'Particle_Advect' See remarks for 2D vectors in section 2.3.1. 2.4 Two scalars routines 2.4.1 2D_ss AVSI_2D_ss_real_uniform (vis_tech, file, dim1, dim2, s12, s22) AVSI_2D_ss_real_rectilinear (vis_tech, file, dim1, dim2, s12, s22, x , y ) AVSI_2D_ss_real_irregular (vis_tech, file, dim1, dim2, s12, s22, xi2, yi2) vis_tech = "Image_Image' Both matrices are coded in color as an image. 2.4.3 3D_ss AVSI_3D_ss_real_uniform (vis_tech, file, dim1, dim2, dim3, s13, s23) AVSI_3D_ss_real_rectilinear (vis_tech, file, dim1, dim2, dim3, s13, s23, x , y , z) AVSI_3D_ss_real_irregular (vis_tech, file, dim1, dim2, dim3, s13, s23, xi3, yi3, zi3) vis_tech = 'Colored_Isosurface' The scalar values in s13(dim1, dim2, dim3) are visualized as an isosurface, whereas the values in s23(dim1, dim2, dim3) are coded in color on top of the isosurface. See description of the module ISOSURFACE. 2.5 One scalar and one vector routines 2.5.1 2D_sv AVSI_2D_sv_real_uniform (vis_tech, file, dim1, dim2, s2, vx2, vy2) AVSI_2D_sv_real_rectilinear (vis_tech, file, dim1, dim2, s2, vx2, vy2, x, y) AVSI_2D_sv_real_irregular (vis_tech, file, dim1, dim2, s2, vx2, vy2, xi2, yi2) vis_tech = 'Contour_Hedgehog' The scalar values in s2(dim1, dim2) are visualized as contour lines and the 2D vectors defined by vx2(dim1, dim2) and vy2(dim1, dim2) as arrows. 2.5.2 3D_sv AVSI_3D_sv_real_uniform (vis_tech, file, dim1, dim2, dim3, s3, vx3, vy3, vz3) AVSI_3D_sv_real_rectilinear (vis_tech, file, dim1, dim2, dim3, s3, vx3, vy3, vz3, x, y, z) AVSI_3D_sv_real_irregular (vis_tech, file, dim1, dim2, dim3, s3, vx3, vy3, vz3, xi3, yi3, zi3) vis_tech = 'Isosurface_Hedgehog' The scalar values are displayed as an isosurface and the 3D vectors as arrows. vis_tech = 'Isosurface_Streamlines' The scalar values are displayed as an isosurface and the 3D vectors as streamlines. 2.6 Auxiliary routines 2.6.1 Define internal AVSI parameters AVSI_def_rsh(com) com is character string that defines the remote shell command for remote AVS, see 4.5. Default: com = 'rsh'. Remark: com='remsh' at HP-platforms. AVSI_def_debug(idebug) idebug = 1 generates debug output. Default idebug = 0 : no debug output. AVSI_def_bias (ibias) ibias (integer) defines the number of bytes to be skipped at the beginning of an UNFORMATTED data file. Default ibias = 0. See documentation of module READ FIELD. AVSI_def_maxstrl(istrln) istrln (integer) defines the maximum length of strings used by the AVSI_routines. Default istrln = 80. AVSI_def_dev(idev) idev .. idev+3 (integers) are the device numbers of AVSI_files. Default idev = 50. AVSI_def_maxdim (mdim) mdim = the maximum number of gridpoints along a grid dimension. Default mdim = 1024. AVSI_def_not(cnot) cnot (character *1) is the 'not-character' that can be the first character of the parameters vis_tech and file of AVSI_initialize. See 4.4 for applications. Default cnot = '_'. AVSI_def_minmax(rmin, rmax) rmin and rmax are the lower and the upper limit of the field data, see the AVS field description file. Default : rmin = minimum data value. rmax = maximum data value. Useful for vis_tech = 'Image' or 'Image_GrayScale'. AVSI_def_fieldformat(form) form is a character string defining the format of the .data field file. form = 'UNFORMATTED' (default) or 'ASCII'. See remark 4) in section 4.5. AVSI_def_network(inetwork) inetwork = 1 shows the Network Editor. See also section 3.1. Default no Network Editor, inetwork = 0. 2.6.2 Remove AVSI_files AVSI_remove_local(lrm) All files in the directory file_dir (AVSI_initialize) are removed after use. lrm is a string defining the (local) remove command. Default lrm = 'rm'. AVSI_remove_remote(rrm) All files in the directory remote_dir (AVSI_remote) are removed after use. rrm is a string defining the remote remove command. Default rrm = 'rm'. See section 4.5. AVSI_remove Removes local and/or remote files after use by means of the command 'rm'. 2.6.3 Script files and macros AVSI_script_open(script_file) Opens the script file script_file. AVSI_script_string(string) Writes character string to the script file. AVSI_script_macro(macro, nparm, parm) Writes macro to script file, in which nparm parameters as defined by parm(1) .. parm(nparm) are substituted. The macros reside in the network directory defined by AVSI_initialize. AVSI_def_macrochar(char) char (character *1) defines the macro substitution character, default = '&'. AVSI_script_close Closes script file. See section 4.8. Chapter 3 Example programs Section 5.2 describes how ro run these examples. 3.1 FORTRAN 77, all platforms This program, called fexample1.f in the AVSI software suite, demonstrates the basic AVS visualization techniques in FORTRAN 77 for scalar data at uniform grids. All routines calls in the example program display a menu of available visualization techniques (first parameter = '*'), from which one can choose. E.g. AVSI_2D_scalar_real_uniform displays the following menu: >>> Visualization methods for AVSI_2D_scalar_real_uniform >>> 0 : Continue, no visualization >>> 1 : Surface >>> 2 : Colored_Surface >>> 3 : Threshold_Contour >>> 4 : Image >>> 5 : Image_GrayScale >>> 6 : 3D_Bar_Chart >>> 7 : Contour >>> 8 : Only field, no visualization >>> Enter visualization number (0- 8) : (add - sign for Network Editor) Example: 1 shows the data as a Surface. -1 shows Network Editor with a network for the Surface method and a window with the Surface visualization of the data. program fexample1 dimension s1(10), s2(20, 20), s3(10, 10, 10), vx2(10, 10), vy2(10,10) integer i, j, k c call AVSI_initialize (netdir, localdir, display_name, avsoptions) c AVSI prompts for display_name and AVS-options ('*'): call AVSI_initialize ( './networks', '.', '*', '*') c >> 1D >> make graph of y = x * x for x = 1, 2,..,10 do 100 i = 1, 10 100 s1(i) = i * i c prompt for visualization method call AVSI_1D_scalar_real_uniform ('*', '1Ds', 10, s1) c fixed visualization method: c call AVSI_1D_scalar_real_uniform ('XY_Graph', '1Ds', 10, s1) c >> 2D >> display data in s2(20, 20) (generated by ZPRMDS) c on a uniform grid call ZPRMDS(s2) call AVSI_2D_scalar_real_uniform ('*', '2Ds', 20, 20, s2) c >> 3D >> display data is s3(10, 10, 10) c on a uniform grid do 200 i = 1, 10 do 200 j = 1, 10 do 200 k = 1, 10 z = -0.4 * i * i + 4 * i z = z * (-0.4 * j * j + 4 * j) z = z * (-0.4 * k * k + 4 * k) s3(i,j,k) = z 200 continue call AVSI_3D_scalar_real_uniform ('*', '3Ds', 10, 10, 10, s3) c >> 2D << display 2D vectors in vx2(10, 10), vy2(10, 10) c on an uniform grid do 300 i = 1, 10 do 300 j = 1, 10 vx2(i,j) = 1. vy2(i,j) = .5 * j 300 continue call AVSI_2D_vector_real_uniform ('*', '2Dv', 10, 10, vx2, vy2) end 3.2 C for SGI, HP, Convex This section shows a C program, called cexample1.c in the AVSI software suite. The program displays, like the program in 3.1, scalar data at uniform grids. The use of AVSI_routines in C is similar to FORTRAN apart from some syntactic differences. This due is to the use of internal c_to_f77 interface routines, which requires the availability of AVS software. AVSI_routines can also be called DIRECTLY from C, which is platform dependent. See example in section 3.5 and make commands in section 5.2. String-prompting ("*") works for SGI and C, but not for Convex. main() { float s1[10], s2[40] [20], s3 [10] [10] [10], vx2 [10] [10], vy2 [10] [10]; int i, j, k; AVSI_initialize("./networks", ".", "*", "*"); /* let AVSI_routines transpose matrices in situ */ AVSI_transpose(); /* 1D scalar data in s1 (y=x*x, x=1...10) */ for (i=1;i<11;i++) s1[i-1]=i*i; AVSI_1D_scalar_real_uniform("*", "1Ds", 10, s1); /* 2D scalar data in s2 */ for (i=1;i<41;i++) for (j=1;j<21;j++) s2 [i-1] [j-1] = i+j; AVSI_2D_scalar_real_uniform("*", "2Ds", 40, 20, s2); /* 3D scalar data in s3 */ for (i=1;i<11;i++) for (j=1;j<11;j++) for (k=1;k<11;k++) s3 [i-1] [j-1] [k-1] = i*j*k*(1-0.1*i)*(1-0.1*j)*(1-0.1*k); AVSI_3D_scalar_real_uniform("*", "3Ds", 10, 10, 10, s3); /* 2D vectors in vx2, vy2 */ for (i=1; i<11; i++) for (j=1; j<11; j++) { vx2 [i-1] [j-1] = 1.0; vy2 [i-1] [j-1] = 0.5*j; } AVSI_2D_vector_real_uniform("*", "2Dv", 10, 10, vx2, vy2); } 3.3 PASCAL, HP This section shows an example of AVSI_routines called from PASCAL, for Hewlett Packard workstations. Also possible for SGI, see section 5.2. >>>>> Install AVSI with make pascal program pdemo; type arr10 = array [1..10] of real; arr40_20 = array [1..40,1..20] of real; arr10_10_10 = array [1..10,1..10,1..10] of real; strng = string[80]; var s1 : arr10; s2 : arr40_20; s3 : arr10_10_10; prompt, net_dir, file_dir, fle :strng; i, j, k, i10, i20, i40 : integer; z : real; procedure AVSI_initialize(var txt1,txt2,txt3,txt4:strng); external FTN77; procedure AVSI_transpose; external FTN77; procedure AVSI_1D_scalar_real_uniform(var txt1,txt2:strng; var dim1:integer;var s:arr10); external FTN77; procedure AVSI_2D_scalar_real_uniform(var txt1,txt2:strng; var dim1,dim2:integer;var s:arr40_20); external FTN77; procedure AVSI_3D_scalar_real_uniform(var txt1,txt2:strng; var dim1,dim2,dim3:integer;var s:arr10_10_10); external FTN77; begin fle := 'pascal_test'; i10 := 10; i20 := 20; i40 := 40; { initialize AVSI: } net_dir := './networks'; file_dir := '.'; prompt := '*'; AVSI_initialize(net_dir, file_dir, prompt, prompt); { define transposition for Pascal calls } AVSI_transpose; { make XY_Graph of y= x * x for x = 1, 2,...,10 } for i := 1 to 10 do s1[i] := i * i; AVSI_1D_scalar_real_uniform(prompt, fle, i10, s1); { display 2D data in s2: } for i := 1 to 40 do for j := 1 to 20 do s2[i,j] := i + j; AVSI_2D_scalar_real_uniform(prompt, fle, i40, i20, s2); { display 3D data in s3: } for i:=1 to 10 do for j := 1 to 10 do for k:=1 to 10 do begin z := -0.4 * i * i + 4 * i ; z := z * (-0.4 * j * j + 4 * j); z := z * (-0.4 * k * k + 4 * k); s3[i,j,k] := z; end; AVSI_3D_scalar_real_uniform(prompt, fle, i10, i10, i10, s3); end. 3.4 CM Fortran, CM-5 Program pfdemo_cm5.f in AVSI software suite, for CM-5 parallel computer. program pfdemo c This program demonstrates how to visualize data in c parallel array sp at the CM-5 with the CM Fortran compiler. c Because AVSI is based upon serial arrays, the data in sp must c be copied to the serial Front End array s2. c c This program uses AVSI_remote, because AVS is not avaible c at the CM-5. Remark that it is possible to write remote c modules with CM/AVS. c c declare CM parallel array: real, array (40,20) :: sp cmf$ layout sp (:news, :news) c declare FE serial array s2 for AVSI: dimension s2(40,20) c initialize AVS Interface: c call AVSI_initialize (netdir, localdir, display_name, avsoptions) call AVSI_initialize ('./networks', '.', '*', '*') c define remote AVS host: c call AVSI_remote(remote_host, remote_user,remote_dir) c mind that the file .rhosts at the remote host must contain a line with c call AVSI_remote('*', '*', '~') c generate 2D data in parallel array sp: forall (i = 1 : 40 , j = 1 : 20) sp (i, j) = i + j c >>> copy to serial Front End array s2 <<<: call CMF_FE_ARRAY_FROM_CM(s2, sp) c visualize 2D data call AVSI_2D_scalar_real_uniform('*', '2Ds', 40, 20, s2) C Remark that, because of a bug in the CM Fortran compiler, c sometimes AVS is not started. If so, c open window at remote computer and give commmand: c avs -network ./2Ds.net c to start AVS. end 3.5 C*, CM-5 Program pcdemo_cm5.cs in AVSI software suite. This program does NOT use the c_to_f77 interface routines. Because F77 routines are directly called: - use lower case names; - add underscore (_) to function name; - add string lengths to end of parameter list; - use pointers for integer parameters as dim1. AVSI_routines can also be called directly for e.g. Sun and IBM platforms. /* C* compiler of CM-5, structured to serial, remote AVS */ #include #include #include /* work around a compiler bug .....*/ int xargc; char **xargv; /* work around a compiler bug.....*/ shape [100] [100] S; main() { float s2 [100] [100]; char cip[20], avsopt[80], host [20], user [20]; int dim1, dim2; float : S field; time_t timeofday = time ((time_t *) 0); printf("enter display name for workstation\n"); gets(cip); printf("enter AVS options\n"); gets(avsopt); avsi_initialize_("./networks", ".", cip, avsopt, 10, 1, strlen(cip), strlen(avsopt) ); printf("enter remote host name\n"); gets(host); printf("enter remote user name\n"); gets(user); avsi_remote_(host, user, "~", strlen(host), strlen(user),1); /* let AVSI_routines transpose matrices in situ */ avsi_transpose_(); /* remove local and remote files generated by AVSI, /bin/rm is remove for CM-5 of Univ. of Groningen */ avsi_remove_local_("/bin/rm",7); avsi_remove_remote_("rm",2); /* make Image of 2D data in s2 */ with (S) { field = prand() & 1 ; read_from_pvar((float *) s2, field); } dim1=100; dim2=100; /* april 1994 > due to CM Fortran compiler error : AVS startup file may be illegal, if so start AVS with command, see section 3.4 */ avsi_2d_scalar_real_uniform_("Image", "2Ds", &dim1, &dim2, s2, 5, 3); } Chapter 4 Advanced use 4.1 Netwerk editor After using the AVSI_routines for some time, problaby you want more AVS functionality by means of the AVS Network Editor. An AVSI call generates a network called .net, that uses a field according to the description file .fld. The network file and the field file are in working directory specified by the second parameter of AVSI_initialize. You start AVS in the working directory (e.g. by the command avs &) and choose the Network Editor from the main menu. Read the network in (Read Network botton) and you will get the same picture as using the AVSI_routine call. Now you can add or replace modules. It is also possible to activate the Network Editor with a call to AVSI_def_network, see section 2.6.1. See also section 3.1 to activate the Network Editor in the visualization method menu. 4.2 Adding modules to AVSI_network The next examples show fragments of networks to which a module, indicated by >>>, is added. For more details see the AVS module documentation. READ FIELD | >>> DOWNSIZE | ....... ....... | GEOMETRY VIEWER | >>> IMAGE TO POSTSCRIPT Some networks already contain IMAGE TO POSTSCRIPT. ....... | >>> GENERATE AXES | | | --------| | GEOMETRY VIEWER >>> LABEL ....... | | ---GEOMETRY VIEWER READ FIELD | |----------- . | . VOLUME BOUNDS <<< . | |----------- | GEOMETRY VIEWER READ FIELD | |--- STATISTICS <<< | ....... READ FIELD | |--- PRINT FIELD <<< | ....... READ FIELD | |--- WRITE FIELD <<< | ....... 4.3 Own network as new visualization technique. You can use your own network or an adaption of some existing AVSI_network as a new visualization technique. Each AVSI_routines has a so-called visualization method specification file (VMSF) called .mth in the directory specified by the first parameter of AVSI_initialize. Such a file has for each method one line with three items. Item 1 is the the name of the method as give by the user, item 2 the name of the corresponding network and item 3 specifies the network type. Item 3 must be -2 for self-made networks (including the module READ FIELD). So one has to move the network to the AVSI_network directory (defined by the first parameter of AVSI_initialize) and add one line to the VWSF to make the network available through an AVSI_routine. 4.4 Partial functioning of AVSI_routine An AVSI_routine normally generates a field and a network and starts AVS. If the first character of the visualization technique is '_', only an AVS field is generated (on condition that dim1 >= 2). AVS is not started and no network is generated. A series of fields, generated in this way, can be used for animation purposes. AVS is not started if the first character of the (second) file parameter is equal to '_'. The AVSI_routine generate a field (on condition that dim1 >= 2) and a network. No field is generated for dim1 = 0. No .data file is generated for dim1 < 0, abs(dim1) = number of gridpoints. These three options can be combined. Remark: the 'not'-character '_' can be changed by AVSI_def_not, see 2.5.1. 4.5 Remote AVS An important aspect of the AVS interface is that one can activate AVS at a remote platform through the AVSI_routines. Applications: - use of AVS without AVS at local platform; - compute data at high performance computer and visualize at another platform with AVS; The only thing to do, is to add the following call after AVSI_initialize to your program: AVSI_remote( remote_host_name, remote_user_name, remote_file_dir) The effect of this call is that the files generated by the AVSI_routines are copied to the directory remote_file_dir of the remote platform (specified by host_name and user_name) by internal calls to 'remote copy'. Next, AVS is started at the remote computer by 'remote shell commands' using a startup file (with the extension .avs). AVS displays the results at the workstation specified by AVSI_initialize. The partial functioning as described in 4.4 also applies to remote use. See section 5.2 how to start the example program fremote.f and other programs demonstrating the use of remote AVS. Remarks: 1) Be sure that there is an entry with the hostname name of your platform and your user name in the .rhosts file of the remote platform. 2) Use AVSI_def_rsh('remsh') at HP-platforms. 3) If an AVSI_remote string parameter = '*', you are prompted to type in the string. 4) Apply AVSI_def_format('ASCII') for exchange between platforms with different binary representations (Big-endian and Little-endian, see documentation of READ FIELD). This applies to exchange with DEC workstations. 4.6 Client-server mode In the examples given thus far, each AVSI_routine starts the program AVS with the system call 'avs -network ....'. At the end of a call, the user has to exit/stop AVS. With a number of AVSI_calls in the same application program, this starting and stopping of AVS takes quite some time. However, AVS is used only during a short time, which is an advantage if you have only a limited number of AVS licenses! A more efficient way is to start AVS for once with the option -server in a seperate window, and to let each AVSI_routine send a CLI-command like 'net_read ...' to AVS. This techniques is described in Chapter 5 "Command Language Interpreter" of the AVS Developer's Guide. The program /usr/avs/examples/avs_client.c demonstrates how to send CLI-commands to AVS as server from a seperate client program, see also page 5-2 of the AVS Developer's Guide. To make this technique available for the AVS Interface, an adaption was made of avs_client.c. The AVSI software suite, described in chapter 5, contains the FORTRAN 77 program fclient.f that demonstrates this so called client-server approach. The client program fclient.f sends CLI-commands to de AVS server. cclient.c is a similar C program. The AVS server can run at the same workstation (local) as the client program or at a remote platform. The AVSI Interface must be intialized by respectivily AVSI_init_client_local (net_dir, file_dir, server_process_number) and AVSI_init_client_remote(local_net_dir, local_file_dir, remote_host_name, server_port_number, remote_user_name, remote_file_dir) AVSI_close stops AVS at the end of the application program. Before the start of the application program, AVS has to be started in a separate window with the command 'avs -server '. AVS responds with the message: AVS server process is , port is: The local AVS server requires the and the remote AVS server the . See for more details comments in the example programs in section 5.2. Note: Thus far, the client-server mode is only tested for for Silicon Graphics (SGI) platforms. 4.7 Module generation Efficiency considerations sometimes require that one has to convert a program with an AVSI_routine call to an AVS data input module that generates the same AVS field as the AVSI_routine. This module replaces the READ FIELD in the network generated by the AVSI_routine. The advantages of modules are: - fast field reading (in AVS INTERNAL format instead of DATA PARSING format); - the possibility to add widgets for module parameters for easy use. The AVS Module Generator can be applied to generate the skeleton of an AVS module (in FORTRAN 77, C and C++) to which code for data (de)allocation, pointer computation, data computation etc. has to be added. This is not a trivial task. This is the reason why a restricted form of module generation was added as a special feature to AVSI. Presently module generation only applies to scalar data at uniform grids and FORTRAN 77. AVSI module generation is active if one prefixes the second parameter of an AVSI_routine with '_M'. The AVSI_routines then generates the FORTRAN source of a module with an empty data generation subroutine, to which only code for data generation has to be added. AVSI generates code for data (de)allocation and pointer computation. Also a makefile is generated to compile and link the module. The next example program fmodule.f illustrates module generation. program fmodule integer dim1, dim2 parameter (dim1 = 40, dim2 = 20) dimension s2(dim1, dim2) call AVSI_initialize('./networks', '.', ' ', ' ') c generate 2D matrix s2: call gen_dat(dim1, dim2, s2) c module generation: call AVSI_2D_scalar_real_uniform('Image', '_Mmodule', 40, 20, s2) end subroutine gen_dat(dim1, dim2, s2) integer dim1, dim2 dimension s2(dim1, dim2) c >>>>>> data generation source code integer i, j do 20 i = 1, dim1 do 20 j = 1, dim2 20 s2(i,j) = i + j c <<<<<< data generation source code end The above AVSI call generates the files in the directory specified bij the second parameter of AVSI_initialize: _Mmodule.fld : AVS field description _Mmodule.data : data for AVS field _Mmodule.net : network file with module READ FIELD _Mmodule.f : FORTRAN 77 source of data input module _Mmodule _Mmodule.make : make file for _Mmodule The module source file _Mmodule.f contains the following empty data generation subroutine: c >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> c ----------------------------------------------------------------- subroutine _Mmodule_dat(dim1, dim2, s) c ----------------------------------------------------------------- integer dim1, dim2, dim3, dim4 dimension s (dim1, dim2) c insert here code for subroutine that generates scalar data s for c uniform field: print *,'**************************************************' print *,'*** add source code for subroutine _Mmodule_dat ***' print *,'**************************************************' end c <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< Add the data source generation code of subroutine gen_dat to this empty subroutine and remove the print statements. Use the next command to make AVS module _Mmodule : make -f _Mmodule.make Replace the module READ FIELD in network _Mmodule.net by the module _Mmodule in the Network Editor: READ FIELD >>> _Mmodule | GENERATE COLORMAP | | | COLOR RANGE------| | | ------ | | | COLORIZER | IMAGE VIEWER | IMAGE TO POSTSCRIPT This modified network displays the same picture of data s2 as the AVSI_routine. 4.8 CLI-script file generation with macros Animations and other applications like the positioning of a large number of images in a scene with the Image Viewer, often require a very specific sequence of module parameters changes that is difficult to realize with AVS. To implement such specific parameter changes, one can let a program generate a script file with a sequence of CLI_commands (see chapter 5 of the AVS Developer's Guide) for module parameters settings. An advantage of this approach is that modification and repetition of the sequence is easy. Then AVS is started with the next command: avs -cli "script -play