viewit v91.0 12/15/90 viewit v91.0 12/15/90 1 viewit v91.0 User's Guide December, 1990 1.0 Introduction 1 1.1 Overview 1 1.2 History 3 1.2.1 Revision Notes 5 1.3 Environment 7 1.4 Getting Started 8 1.4.1 Obtaining Viewit 8 2. General Description 9 2.1 Command/ Control Modes 11 2.2 The Register Stack 12 2.2.1 Register Variable Dimension 13 2.2.2 Register Operations Dimension 13 2.2.3 Complex Registers 13 2.3 Functions 14 2.3.1 Function Parameters 14 2.3.2 Vector Parameters 14 2.3.3 Monadic and Dyadic Functions 15 2.4 File Interface 15 2.5 Display Interfaces 16 3.0 Function Descriptions 18 3.1 Stack Manipulation 18 3.1.1 -push Stack Push 18 3.1.2 -pop Stack Pop 19 3.1.3 -xchg Register Stack Exchange 20 3.1.4 -glue Register Concatenation 21 3.1.5 -copy Register Copy 22 3.1.6 -swap Multi-Register Swap 23 3.1.7 -split and -merge Interlace and Deinterlace Registers 23 3.2 Storage Allocation 26 3.2.1 -dim Register Dimensioning 26 3.2.2 -size Register Allocation Size 27 3.2.3 -clr n Register Storage Deallocation 27 3.3 Space Filling Functions 28 3.3.1 -unif Uniform Values 28 3.3.2 -stuff Load Values From Command Line 28 3.3.3 -rand Uniform Deviates 28 3.3.4 -drand48 Better Uniform Deviates 29 3.3.5 -gauss Normal Deviates 29 3.3.6 -ramp Incrementing Values 29 3.3.7 -const Scalar Value 30 3.3.8 -i File Input 30 3.3.9 Interprocess Register Transfer 31 3.4 Dyadic Arithmetic 32 3.4.1 -add Addition 32 3.4.2 -mul Multiplication 32 3.4.3 -sub Subtraction 32 3.4.4 -div Division 32 3.4.5 -mod Remainder 33 3.4.6 -pow Power 33 3.4.7 Arithmetic Example 33 3.4.8 Complex Arithmetic 34 3.4.8.1 -cmul Complex Multiplication 34 3.4.8.2 -cadd Complex Addition 35 3.4.8.3 -conj Complex Conjugate 35 3.5 Dyadic Relational and Bitwise Functions 36 3.5.1 Dyadic Relational Functions 36 3.5.2 Dyadic Bitwise Functions 37 3.6 Common Monadic Functions 38 3.6.1 Trigonometric 38 3.6.2 Exponential and Logarithmic 38 3.6.3 Square Root and Square 38 3.6.5 Absolute Value and Sign 38 3.6.6 Rounding 39 3.6.7 Conversion 39 3.6.8 -linscl Linear Scaling 39 3.6.9 -rscl Linear Scaling over Specified Range 39 3.6.10 -zscore Z- Scoring 39 3.6.11 -truncate Truncation 40 3.6.12 -thresh Thresholding 40 3.7 Space Manipulation 3.7.1 -chunk Array Subset 41 3.7.2 -replace_chunk Subset Array Replacement 42 3.7.3 -duplicate Array Duplication 43 3.7.4 -translate Array Shifting 44 3.7.5 -center Array Centering 45 3.7.6 -reorder Dimension Reordering 45 3.7.7 -mirror Dimension Reflection 46 3.7.8 -interlace Odd/Even Shuffle Across Last Dimension 46 3.7.9 -scale Dimension Rescaling 47 3.7.10 -rotate Cube Rotation 48 3.8 Dimensionality Reduction 49 3.8.1 -reduce Reduction 49 3.8.1.1 -reduce b1 Linear Regression Reduction 50 3.8.2 -scan Scan 52 3.8.3 -sum1d Partial Reduction 52 3.8.4 -group Grouping of Leading Two Dimensions 53 3.9 Fourier Transform Spectral Methods 55 3.9.1 -ft, -ft1d, -ft2d Fourier Transform Operators 55 3.9.2 Filters and Windows 57 3.9.2.1 -ilpf Ideal Low Pass Filter 57 3.9.2.2 -blpf Butterworth Low Pass Filter 58 3.9.2.3 -dcfilt DC Filter 58 3.9.2.4 -radial Radial Distance 59 3.9.3 Phase Correction 60 3.10 Neighborhood Operator Functions 61 3.10.1 N-Dimensional Convolution Functions 61 3.10.2 Predefined Convolution Kernels 62 3.10.2.1 2-D Pre-Defined Convolution Kernels 62 3.10.2.2 3-D Pre-Defined Convolution Kernels 64 3.10.2.3 Convolution Performance Enhancement 64 3.10.3 Rank Order Neighborhood Functions 65 3.10.4 Statistical Neighborhood Functions 66 3.10.5 Adaptive Histogram Equalization 67 3.11 Back Projection 68 3.11.1 Two Dimensional Back Projection 68 3.11.2 Three Dimensional Back Projection 71 3.11.2.1 Direct Method 71 3.11.3 Projection Reconstruction Support Functions 74 3.11.3.1 Projection of a Circle 74 3.11.3.2 Hanning Window 75 3.11.3.3 Band Pass Filter 75 3.11.3.4 3 Point Second Difference Filter 75 3.11.3.5 3 Point Unweighted Smoothing Filter 75 3.11.3.6 3 Point Gradient 76 3.11.3.7 Base Line Correction 76 3.12 Rendering Functions 77 3.12.1 Height Reduction 77 3.12.2 Lighting 77 3.12.3 -movie Volume Cine 77 3.13 Multivariate Functions 80 3.13.1 -histogram Multivariate Histogram 80 3.13.2 -look_up Multivariate Transfer Functions 81 3.13.3 -cormat Multivariate Correlation Matrix Determination 82 3.13.4 -covarmat Multivariate Covariance 83 3.14 Matrix Functions 84 3.14.1 -identity_matrix 84 3.14.2 -vector Convert to Vector 84 3.14.3 -matmul Matrix Multiply 84 3.14.4 -eigen Eigen Vectors and Values of a matrix 85 3.15 Sorting and Indexing Functions 86 3.15.1 -sort Sort Values 86 3.15.2 -index Index Values based on Table 86 3.15.3 -index_table Create Index Table 86 3.15.4 -rank Rank 87 3.50 -plot NCAR Graphics Interface 88 3.50.1 -plot OPEN 88 3.50.2 -plot EZY title X*Y Plot w/ implied abscissa 88 3.50.3 -plot EZXY title X*Y Plot 89 3.50.4 -plot EZMY title Multiple X*Y Plot w/implied abscissa 90 3.50.5 -plot EZMXY title Multiple X*Y Plot 91 3.50.6 -plot EZCNTR EZ Contour Plot 92 3.50.7 -plot CONREC low high increment Contour Plot w/ level specification 93 3.50.8 -plot EZSRFC elevation aspect Surface Profile Plot 94 3.50.9 -plot EZVEC Field Plot 94 3.98 Command Line Control Functions 95 3.98.1 -sleep time 95 3.98.2 -loop n .... -endloop 95 3.99 Misc. Functions 96 3.99.1 -debug level 96 3.99.2 -status 96 3.99.3 -timer ON 96 3.99.4 Printing -print 96 3.99.5 Univariate Statistics -stats 96 3.99.7 Display Register Memory Allocation -show_reg 97 4.0 File I/O 98 4.1 File Input/Output Functions 98 4.1.1 RAW File Format 100 4.1.2YAHO1 File Format 102 4.1.3 YAHOXDR File Format 104 4.1.4 HDF Scientific Dataset File Format 105 4.1.5 FITS File Format 106 4.1.6 SISCO Input File Format 107 4.1.7 HDF Raster File Format 108 5.0 Display Interfaces 109 5.1 File Display Interface 109 5.2 VR Display Protocol 110 .c.5.3 VT Protocol 111 5.4 TK Protocol 113 5.5 DTM Protocol 114 5.6 X-Windows Display Protocol 114 6.0 Limiting the Number of Operations Dimensions with -nopdim 115 Appendix A Application Notes 117 A.1 NMR Image Reconstruction using Fourier Imaging Techniques 117 A.2 Signal Enhancement Techniques Using Fourier Domain Filtering 120 A.3 Three-Dimensional Projection Reconstruction using the Direct Filtered Back Projection Method for NMR Applications 122 A.4 Exploratory Visualization of 3-D Datasets using Volume Rendering Techniques 126 A.5 Principal Components of a Multivariate Array 127 .c.1.0 Introduction .c.1.1 Overview Perhaps, the most useful description of viewit is a "scientific calculator" for multidimensional arrays with extra "buttons" for signal processing, scientific visualization, image processing and multivariate analysis. In short, viewit is an array language with rich function support. The actual applications of viewit are to a large degree dependent on the background, creativity, patience and interests of the user. A calculator can be used for everything from balancing a checkbook, solving systems of equations or used for eigen system problems. The final product is dependent on the order of the "buttons" pushed and the user's knowledge of the techniques and methods used to push the buttons. Currently, viewit has enough parts to perform simple tasks like array arithmetic and more complex "buttons" for functions like Fourier transforms and back projection problems. With these "buttons" viewit could be used to balance a checkbook or perform reconstruction or restoration problems. Viewit has attempted to extend some of the concepts of traditional two dimensional image processing to N-dimensional arrays and supports functions like multidimensional neighborhood operators. A new user is encouraged to start with simple problems and perform some of the examples in this guide. A few application notes have been included as an appendix to this manual. New applications of viewit, viewit macros, citations, code chunks, bug reports, and suggestions are solicited and can be contributed to: viewit@ncsa.uiuc.edu or Clint Potter National Center for Supercomputing Applications Beckman Institute 405 N. Mathews Urbana, IL 61801 cpotter@ncsa.uiuc.edu A viewit electronic new letter is distributed on an irregular basis. A subscription may be requested from viewit@ncsa.uiuc.edu. Legalities: The University of Illinois gives no warranty, express or implied, for the software and/or documentation provided, including, without limitation, warranty of merchantability and warranty of fitness for a particular purpose. Trademark Acknowledgments: Alliant is a registered trademark and CONCENTRIX is a trademark of Alliant Computer Systems Corporation. Macintosh and Macintosh II are trademarks of Apple Computer Inc. UNIX is a registered trademark of AT&T. CRAY and UNICOS are registered trademarks and CRAY-2 and CFT77 are trademarks of Cray Research Inc. IBM PC is a registered trademark of International Business Machines Corporation. MS-DOS is a registered trademark of Microsoft Corporation.Model One/80 and Model One/380 are trademarks of Raster Technologies, an Alliant Company. Silicon Graphics is a registered tradem ark of Silicon Graphics, Inc. Sun is a registered trademark and Sun Workstation, Sun System 3, SunView, TAAC-1 are trademarks of Sun Microsystems, Inc. .c.1.2 History Viewit was conceived and developed by Clint Potter during June 1988 with the support of the National Center for Supercomputing Applications (NCSA), the Biomedical Magnetic Resonance Laboratory (BMRL) and the College of Medicine at the University of Illinois at Urbana/Champaign. It initially was developed to solve problems related to NMR imaging research at the Biomedical Magnetic Resonance Laboratory under the direction of Paul Lauterbur. Initial versions of viewit were developed at NCSA on Sun-4 Workstations belonging to the RIVERS project, under the direction of Bob Haber. During August of 1988, the code was extended to an Alliant FX-80 at NCSA. The first production users were members of the Biomedical Magnetic Resonance Laboratory. Haakil Lee and Xiaohong Zhou were early users and bug finders. The ideas for the architecture were probably lifted from a number of sources. APL programmers will notice a similarity in some of the functions in viewit like reduce and scan. The internal multidimensional data structures can probably be credited to using Norman Brenner's "fourt" Fourier transform routine for a few years. A Hewlett Packard HP-15c calculator was an inspiration for the general architecture. The HDF file format support is from the software development group at NCSA. A few of the algorithms are also adapted from "Numerical Recipes: The Art of Scientific Computing" by Press, Flannery, Teukolski and Vettering. A very few of the functions rely on access to the Numerical Algorithims Group library, but other routines could probably be substituted from the EISPACK or LINPACK libraries. During the fall and winter of 1988-1989, functionality was continually added to the viewit codes. During April of 1989, the codes were ported to the NCSA Cray 2 under UNICOS. In June, the codes were tested on the NCSA Cray XMP-48 under UNICOS. In September of 1989, a number of enhancements were added which included addition of the operations dimension concept to extend the utility of the code. Also additional multivariate analysis features were added. At the end of September, the V89.1 codes were made available to the public domain on the anonymous ftp server at NCSA. During 1990, over 100 additional functions and capabilities were added to the codes. These include added capabilities for volume rendering, additional complex model functions, X-Windows display support, sorting and indexing functions and hooks to the NCAR graphics library. Also during this time, the capabilities to run viewit interactively (with on-line help) has also been added. Rachael Brady at NCSA has been essential in adding many many new capabilities including some support for the Connection Machine. Patrick Moran at NCSA has developed a number of distributed display interfaces for viewit on the SGI workstations and added the support for DTM (Distributed Transfer Mechanism) developed by Jeff Terstriep at NCSA. The NCSA software tools group has added capabilities to NCSA Image, Datascope and Ximage that support viewit for distributed display to the desktop workstation. David Lawrance at NCSA has been essential for his invaluable suggestions, testing, applications development and training of new users. .c.1.2.1 Revision Notes V91.0 Functions No Longer Supported 1. -cube_rotate has been replaced by -rotate and -cmrotate. 2. -displ IVASGRAPH is no longer supported. 3. -height_weight is no longer supported. New Functions and Support 1. -band, -bior, -bxor 2. -reduce ceil_index 3. -cmul 4. -covarmat 5. -nbhd sum, -nbhd sum^2, -nbhd nf 6. -cmreorder, -cmrotate 7. ALICE support 8. -cmproj, -cmmovie 9. -svdc, csvdc 10. -send, -recv 11. Ultra framebuffer support 12. -glue 13. -reduce b1 14. ASCII output file format 15. NCAR Graphics Interface -plot 16. DTM Support 17. -movie, -rotate 18. -scan erode 19. -mod 20. -smooft 21. -copy 22. -toeplitz 23. -vector 24. -macro 25. HDF_RASTER support 26. X-Windows Display Support 27. -cadd 28. -conj 29. -split, -merge 30. -scan ceil Function Modifications 1. -filt1d SPHERE ro ri ro amd ri are normalized radius with maximum value of 1.0 .c.1.3 Environment Viewit is an entirely memory resident program that dynamically allocates memory for arrays. If large problems are to be solved, viewit needs to have access to large amounts of memory. It is possible to attempt the allocation of hundreds of megabytes of memory by just typing a few characters. Viewit prefers to run on machines with large amounts of memory in the supercomputer, super-mini, mini-super, and superworkstation classes. If smaller problems are to be solved, viewit can adequately run on 32bit small workstation class machines. Viewit also needs access to quality floating point performance. The internal register data structures for viewit use floating point data structures and most calculations are floating point calculations. Again, viewit likes to run on machines like supercomputers, but has been used on Sun 3 workstations. The machine environment depends largely on the problem to be solved. Viewit consists of a "C" code main driver and FORTRAN support routines. A full implementation of viewit also relies on access to a number of libraries including, NCSA HDF, NCAR Graphics, X-Windows, LINPACK, BLAS3, and NAG. If these libraries are not available, viewit may still be used but with only the loss of functionality that these libraries support. Viewit contains a large number of conditional complier dependencies that let the system be configured for a particular site. A barebones version of viewit may be made using just the C compliler. Viewit has been developed on UNIX or UNIX like environments. The network frame buffer protocols depend on the use of Berkeley socket calls and assume TCP/IP protocols. Viewit has been ported to a number of machines including Crays under UNICOS, Sun Workstations, Silicon Graphics Workstations, Alliant and Convex Minisupercomputers, and a variety of other machines. A handful of viewit functions have also been rewritten in C-Paris for the Connection Machine (-cmproj, -cmback, -cmreoder, -cmrotate, -cmproj, -cmmovie). .c.1.4 Getting Started .c..c.; .c..c.1.4.1 Obtaining Viewit A generic version of the distribution is available using anonymous ftp on the server ftp.ncsa.uiuc.edu (128.174.20.50. Note after 2/15/91 this will become 141.142.20.50). To obtain the releases use the login name of "anonymous" and your e-mail address as the password. Viewit releases are located in the unsupported/viewit directory on the server. To obtain the 91.0 release, use the command "cd unsupported/viewit/91.0" to set the current directory and transfer the README file to your directory. The README file contains installation notes. .c.2. General Description Viewit can be considered as a reverse Polish notation calculator (RPN) for multidimensional and multivariate arrays. Viewit was conceived as a software tool similar to a Hewlett Packard calculator with extra "buttons", or functions for signal processing, image processing, multivariate analysis and scientific visualization. Like an RPN calculator, viewit relies on a stack of 4 registers for manipulation of data. However, unlike most calculators, viewit's registers can hold large multidimensional arrays in addition to scalar values. A general overview of viewit is shown in figure 2.1 Command and control information can be passed to viewit using a number of modes. Some of these provide the capability for viewit to be used in a distributed processing environment. Viewit supports a variety of file formats for importing and exporting data to the register stack. Additionally I/O protocols are available for distributed interprocess communication. A handful of raster display devices and network frame buffer protocols are also supported for display of data within the register stack.  .c.2.1 Command/ Control Modes Viewit supports a number of operating modes that provide execution command and control flow to viewit. The simplest method, called command mode, allows viewit commands to be entered directly from the UNIX shell. Commands are passed as arguments in the viewit command string with a separation of at least one space between all functions and parameters. Arguments and functions are executed in the order they are entered. For example, the following command line would read an image file called image.hdf, scale the data between 0.0 and 255.0 and display the image on a remote workstation called kepler running a display server process. viewit -iformat HDF -i image.hdf -linscl 0.0 255.0 -displ VT kepler This command line consists of four functions. The -iformat function sets the input file format type to be expected by the -i function which reads a HDF file format named image.hdf. The file name for the -i function is specified as the first parameter to the -i function. The third function, -linscl, scales the data between 0.0 and 255.0 as specified by the first and second function parameters. Finally, the image is displayed to a remote workstation called kepler using the VT display protocol. Interactive mode provides the capability to run viewit interactively. This mode may be initiated by starting viewit without arguments as follows: u2 25% viewit viewit V91.0 12/15/90 viewit> Commands may then be entered at the "viewit>" prompt. Viewit also supports the DTM and ALICE command modes that are used for distributed control. DTM mode is used in conjunction with NCSA Image3 for the Macintosh. This allows commands for viewit to be entered within the Image3 notebook and are then passed to a remote process running viewit. ALICE mode supports the ALICE environment from the Jet Propulsion Laboratory. All of the command/control modes used in viewit rely on a unsophisticated parser that essentially performs no error or bounds checking. In this sense viewit should be considered "user hostile." Viewit executes functions on the command line from left to right and assumes that functions and parameters are separated by at least 1 space. Viewit allows the user to chain together functions in essentially any order. However, parameters for a specific function must usually be used in a specific order. Typically, the functions are used to load data to the registers, manipulate data in the registers and output to a file or display device. .c.2.2 The Register Stack Viewit uses a stack-based, reverse polish notation logic that is similar to that used on Hewlett Packard RPN Calculators. The memory model consists of a "stack" of four registers where each register is capable of storing a multi-dimensional floating point array. The registers are labeled ss1, ss2, ss3 and ss4, where ss1 is the top of the register stack. For example, storage is allocated for a 32x100x25 three dimensional array using the -dim function as shown in the following command: viewit -dim 3 32 100 25 -show_reg The current storage allocation for all four registers is shown by using the -show_reg function. In our example, memory for the stack has been allocated as follows: ss1: 32 100 25 ss2: ss3: ss4: Within the viewit architecture, dimension numbering is assumed to start at zero. In our example, dimension 0 has a size of 32 and is considered to be the leading dimension. Dimension 1 has a size of 100 and the last dimension, dimension 2, has a size of 25. .c.2.2.1 Register Variable Dimension For multivariate functions, the last dimension is considered to be the variable dimension. In the previous example, the register array could be considered to have 25 variables consisting of 32x100 two dimensional arrays of data. This is discussed in sec. 3.13. .c.2.2.2 Register Operations Dimension Most of the functions in viewit assume that an operation is to be performed using all of the dimensions in an array. It is possible to restrict an operation to a given number of leading dimensions using the -nopdim function to specify the number of operations dimensions. This feature is useful to restrict the dimensionality of the operation. For example, if only a two dimensional convolution was to be performed for each of the 25 32x100 arrays, the number of operations dimensions could be set to 2. Likewise, if a one dimensional convolution was to be performed the number of operations dimensions could be set to 1 and 2500 operations would be performed on a one dimensional array of 32 elements. This is discussed in sec. 6. .c.2.2.3 Complex Registers Viewit has been primarily designed for real floating point arrays. Occasionally, a viewit function calls for a complex data storage model. For these functions, the real part of the complex array is stored in the ss1 register and the imaginary part is stored in the ss2 register as follows: ss1: real part of a ss2: imaginary part of a ss3: real part of b ss4: imaginary part of b .c..c.2.3 Functions Operations on the register stack are performed using functions input on the viewit command line. The -dim and -show_reg functions were used in the previous example. A function is denoted by a dash preceding its name. Each function is conceptually similar to the buttons on a RPN calculator and functions are executed internally in the order they are entered on the command string. Intermediate results are stored in the register stack between each function execution. .c..c..c.2.3.1 Function Parameters Parameters that are specific to the function follow the name. In the previous example in sec. 2.2, the -dim function had a variable number of parameters that depended on the rank of the array. The first parameter was the rank of the array followed by the sizes of each dimension. The -show_reg function has no parameters. Parameters must be specified in the order as required by the function. .c..c..c.2.3.2 Vector Parameters A vector parameter is occasionally required by a function and consists of a vector of scalar values for each dimension in the function. For example, the -dim function has two parameters. The first is a scalar specifying the number of dimensions. This is followed by a vector parameter that provides the size of each dimension. Similarly, the -scale function resamples a multidimensional array according to a single vector parameter that specifies the scale change for each dimension. For example, if the array had two dimensions the function -scale 2.0 3.5 would increase the size of dimension 0 by a factor of 2.0 and dimension 1 by a factor of 3.5. The vector [2.0 3.5] is a single vector parameter for the function. .c..c.2.3.3 Monadic and Dyadic Functions Functions are defined as monadic if they operate only on the ss1 register. The -dim function is a monadic function that allocates storage for the ss1 register. Monadic functions have no affect on any other registers. Most of the trigonometric functions ( -sin, -cos, -tan, -asin, etc) used in viewit are considered to be monadic functions. Register functions are defined as dyadic if they operate on the ss1 and ss2 registers. For example, dyadic functions are used for array arithmetic. .c.2.4 File Interface Viewit supports a variety of file storage formats and data types, including NCSA HDF, XDR, FITS files and RAW file streams. Viewit's support of a variety of file formats allows the user to convert data between file formats by reading data from one file format and writing in another format or data type. For example, viewit can be used to read a file that that has a 1024 byte header followed by a three dimensional 64x64x64 array of binary floating point values and then output the file as an NCSA HDF scientific data format file: viewit -dim 3 64 64 64 -ioffset 1024 -iformat RAW -itype FLOAT \ -i infile -oformat HDF -o outfile Specific file formats and data types supported by viewit are discussed in sec. 4. .c.2.5 Display Interfaces Viewit supports a variety of display protocols and frame buffers. Typically, viewit is executed on a high end computer and data is displayed on a local workstation. The VT protocol uses a client/server model and Berkeley sockets to connect server processes to the viewit client kernel. The server processes typically have local functions for analysis of raster data. Prototype VT server processes have been developed for Sun Microsystems Inc. workstations using SunView. Prototype VT server processes also support the International Imaging System IVAS frame buffer, Sun Microsystems Inc. TAAC-1 Applications Accelerator and Silicon Graphics Workstations. Viewit also provides basic raster display capabilities for X-windows The VR, or virtual raster protocol, is designed for NCSA versions of telnet that support this protocol. Currently, versions are available for Sun Microsystems, Inc. Workstations and Apple Macintosh workstations. This protocol allows raster images to be displayed in conjunction with a telnet session.. The viewit display interface is discussed in sec. 5. 2.6 Help.c.; Interface Viewit supports a on-help system that provides a reference manula page for each function. The location of the help file is specifed during installation of viewit. To access help, the command "?" or "-help" is used. For example, viewit> ? will return a list of keyword for which help is available. Help for a specific keyword may be acessed by specifing a keyword. For example, viewit> ? -ft would provide a reference manual page on the -ft function. .c.3.0 Function Descriptions .c.3.1 Stack Manipulation The register stack is manipulated using functions called the stack manipulation functions. These functions push, pop and exchange the multidimensional register stack within viewit. .c.3.1.1 -push: Stack Push The -push function is similar to using the key on an RPN calculator. It "pushes" arrays down the stack by copying them from preceding registers. The ss1 register copies itself. For example, a three dimensional array could be allocated and pushed down the stack as follows: viewit -dim 3 64 64 64 -push -show_reg ss1: 64 64 64 ss2: 64 64 64 ss3: ss4: The ss1 register can now be manipulated without affecting the other registers. For example, a 2 dimensional array that is 256x256 is allocated as follows: viewit -dim 3 64 64 64 -push -dim 2 256 256 -show_reg The resulting register stack is then: ss1: 256 256 ss2: 64 64 64 ss3: ss4: Arrays are pushed further down the stack: viewit -dim 3 64 64 64 -push -dim 2 256 256 -push \ -dim 2 100 100 -push -show_reg with the resulting register stack: ss1: 100 100 ss2: 100 100 ss3: 256 256 ss4: 64 64 64 In this example, if the stack is further pushed, the three dimensional array is pushed beyond the stack depth and is lost. .c.3.1.2 -pop: Stack Pop The pop function "pops" the stack by copying from the bottom of the stack to the preceding registers. The ss4 register copies itself. For example, the register stack can be popped with: viewit -dim 3 64 64 64 -push -dim 2 256 256 -push \ -dim 2 100 100 -push -pop -show_reg After the -pop function is executed, the resulting register stack is: ss1: 100 100 ss2: 256 256 ss3: 64 64 64 ss4: 64 64 64 .c.3.1.3 -xchg: Register Stack Exchange The -xchg function exchanges the ss1 and ss2 registers without affecting the other registers. This can be demonstrated by extending our example: viewit -dim 3 64 64 64 -push -dim 2 256 256 -push \ -dim 2 100 100 -push -pop -xchg -show_reg The resulting register stack is now: ss1: 256 256 ss2: 100 100 ss3: 64 64 64 ss4: 64 64 64 .c.3.1.4 -glue: Register Concatenation The -glue function appends the data values in the ss2 register to the ss1 register. For example: -dim 1 3 -ramp -1 1 -push -dim 1 5 -ramp -1 1 -show_reg -glue \ -show_reg -print Results in the following: -dim 1 3 -ramp -1 1 -push -dim 1 5 -ramp -1 1 -show_reg ss1: 5 ss2: 3 ss3: ss4: -glue -show_reg ss1: 10 ss2: 3 ss3: ss4: -print i: 0, 0.000000 i: 1, 1.000000 i: 2, 2.000000 i: 3, 3.000000 i: 4, 4.000000 i: 5, 0.000000 i: 6, 1.000000 i: 7, 2.000000 In more than 1 dimension, both arrays are glued together as linear arrays and returned as a linear array which could be redimensioned. For example, -dim 2 3 3 -ramp -1 1 -push -dim 2 2 2 -ramp -1 1 -show_reg \ -glue -show_reg -print Results in the following: -dim 2 3 3 -push -dim 2 2 2 -show_reg ss1: 2 2 ss2: 3 3 ss3: ss4: -glue -show_reg ss1: 13 ss2: 3 3 ss3: ss4: -print i: 0, 0.000000 i: 1, 1.000000 i: 2, 2.000000 i: 3, 3.000000 i: 4, 0.000000 i: 5, 1.000000 i: 6, 2.000000 i: 7, 3.000000 i: 8, 4.000000 i: 9, 5.000000 i: 10, 6.000000 i: 11, 7.000000 i: 12, 8.000000 .c.; .c..c..c.;.c.3.1.5 -copy Register Copy The -copy function copies a specified source register to the destination register. For example, the following would copy the ss4 register to the ss2 register: -copy 4 2 .c.3.1.6 -swap Multi-Register Swap The -swap function swaps the order of registers according to the swap_order_vector parameter. For example, consider a register stack as follows: ss1: 64 64 64 ss2: 64 ss3: 512 512 ss4: 2 The command -swap 2 4 1 3 would rearrange the order of registers as follows: ss1: 64 ss2: 2 ss3: 64 64 64 ss4: 512 512 .c.3.1.7 -split and -merge: Interlace and Deinterlace Registers The -merge function provides the capability to interlace values between successive registers. For example, consider the following example: ss1: [ 1 1 1 1 ] ss2: [ 2 2 2 2 ] ss3: [ 3 3 3 3 ] ss4: [ 4 4 4 4 ] -merge 2 would consecutively interlace values in the ss1 and ss2 registers as in the following: ss1: [ 1 2 1 2 1 2 1 2 1 2 1 2 ] ss2: [ 2 2 2 2 2] ss3: [ 3 3 3 3 3] ss4: [ 4 4 4 4 4] An example of the use of this function is to combine real and imaginary values stored in the ss1 and ss2 registers. -merge 3 would consecutively interlace values in the ss1, ss2 and ss3 registers as in the following: ss1: [ 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 ] One potential use of this function is to combine 3 registers that may represent data for red, green and blue display channels. Similarly, -merge 4 would result in the following: ss1: [ 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 ] A potential use of this function is to combine 4 registers that may represent data for red, green, blue and alpha channels for a 32 bit display model. The -split function operates inversely to the -merge function and is used to deinterlace consecutive values stored in the ss1 register. For example, consider the following: ss1: [ 1 2 1 2 1 2 1 2 1 2 ] ss2: ss3: ss4: Since the size of the leading dimension of the ss1 register is 2, value would be split between the ss1 and ss2 registers as follows: -split ss1: [ 1 1 1 1 1] ss2: [ 2 2 2 2 2] .c.3.2 Storage Allocation Memory for the stack is dynamically allocated by using the -dim function or is automatically allocated by reading self defining file formats into the register stack. .c.3.2.1 -dim: Register Dimensioning The -dim function's first parameter is the number of dimensions in the multidimensional array. This is followed by the size of each of the dimensions in the array as specified by a vector parameter. Internally, a multi-dimensional array is stored so that the leading dimension in the parameter list increases the fastest. For example, consider the following array. It has a rank of 2 and the leading dimension is 3 and would be allocated with -dim 2 3 2. 3.1 1.2 4.3 1.4 5.5 9.6 Internally, viewit stores this array in linear memory as follows: 3.1 1.2 4.3 1.4 5.5 9.6 The data within the register could be reallocated as a one dimensional array of 6 elements without affecting the values in the register with -dim 1 9. The array could also be redimensioned with fewer elements. A -dim 2 2 2 would take the leading 4 elements from the linear memory and place them in a two dimensional array as follows: 3.1 1.2 4.3 1.4 If an array is redimensioned larger then the initial array in the register, the extra elements are filled with zeros. In this example, the original array was reallocated as a 4x3 array with -dim 2 4 3 and the resulting matrix is: 3.1 1.2 4.3 1.4 5.5 9.6 0.0 0.0 0.0 0.0 0.0 0.0 .c.3.2.2 -size: Register Allocation Size The -size function returns the size of each dimension of the ss1 register as vector. For example, ... -dim 3 64 50 5 -size -show_reg ... would return the vector [64 50 5] to the ss1 register. .c.3.2.3 -clr n: Register Storage Deallocation The -clr function is used for deallocation of storage for a specified register number. Execution of this function creates a null space in the register. The following viewit command string: viewit -dim 5 16 16 16 16 16 -push -clr 1 -show_reg would result in the following register stack: ss1: ss2: 16 16 16 16 16 ss3: ss4: .c.3.3 Space Filling Functions The space filling functions are used to create or load data values to arrays defined in the ss1 register. .c.3.3.1 -unif: Uniform Values To uniformly fill an array with a constant value, the -unif function is used. For example, the following command is used to create a 512x512 array where every element is equal to 3.14159: viewit -dim 2 512 512 -unif 3.14159 The -unif function has one parameter that is equal to the fill value. .c.3.3.2 -stuff: Load Values From Command Line The -stuff functions allows register values to be loaded directly from the command line to the ss1 register. For example, -dim 1 5 -stuff 1.1 1.2 1.3 1.4 1.5 would load the vector [1.1 1.2 1.3 1.4 1.5] to the ss1 register. .c.3.3.3 -rand: Uniform Deviates The -rand function fills an array with simple uniformly distributed random numbers generated using the UNIX rand() function. The range of numbers is 0 to (2**15)-1. To create a 512x512 array of random numbers, the following command line could be used: viewit -dim 2 512 512 -rand .c.3.3.4 -drand48: Better Uniform Deviates The -drand48 function fills an array with uniform random numbers that are distributed over the interval [0.0, 1.0] using the UNIX drand48() function. For example, to fill a 64x64x64 using the -drand48 function: viewit -dim 3 64 64 64 -drand48 .c.3.3.5 -gauss: Normal Deviates The -gauss function fills an array with normally distributed random numbers with a mean of 0.0 and a standard deviation of 1.0. The algorithm uses the UNIX drand48() function and the Box-Muller Method to generate uniformly distributed deviates. For example, to fill a 64x64 array with normal deviates: viewit -dim 2 64 64 -gauss .c.3.3.6 -ramp: Incrementing Values The -ramp function fills a space with incrementing integer values starting at zero with a period of n where n is defined as the first parameter in the ramp function. The values are repeated d times where d is the second parameter for the ramp function. For example, viewit -dim 2 4 4 -ramp 10 1 would fill the two dimensional 4x4 array as follows: 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 0.0 1.0 2.0 3.0 4.0 5.0 Viewit -dim 2 4 4 -ramp 4 4 would create the following array: 0.0 0.0 0.0 0.0 1.0 1.0 1.0 1.0 2.0 2.0 2.0 2.0 3.0 3.0 3.0 3.0 A continuous 2-D wedge function can be created: viewit -dim 2 256 256 -ramp 256 1 A discrete 2-D step tablet with 16 levels: viewit -dim 2 256 256 -ramp 256 4096 .c.3.3.7 -const: Scalar Value The -const function creates and allocates a scalar value in the ss1 register. For example, viewit -const 2.5 is equivalent to viewit -dim 1 1 -unif 2.5 .c.3.3.8 -i: File Input The -i function reads and loads a file to the register data structures. The actual format of the file that is loaded is based on the settings of the input file format (-iformat) and input data type (-itype). The -i function will automatically allocate memory and dimension registers if the input file format contains array dimension information. The syntax and operation of this function is discussed in sec. 4. .c.3.3.9 Interprocess Register Transfer -send ssn host port_number -recv ssn port_number where ssn is ss1, ss2, ss3, or ss4 registers. host is host name or internet address to transfer register data to. port_number is internet port number (i.e. 3500, 3501, etc..) The -send and -recv function are used for transferring register data between viewit processes running in a distributed environment. Data is transferred using a socket mechanism and the XDR protocol. Data transfer is initiated as follows: 1.) The -recv function is initiated in the viewit process that is to receive register data. In the following example, the ss1 register will receive data through port service number of 3500. -recv ss1 3500 on host: kepler 2.) From a client viewit process register data is sent to the server process using the send command. For example, the following would transfer the ss1 register to the viewit receiving viewit process on host kepler: -send ss1 kepler 3500 .c.3.4 Dyadic Arithmetic Arithmetic operations on two multidimensional arrays are performed using dyadic functions like -add, -sub, -mul, -div . These dyadic register functions perform elemental scalar addition, subtraction, multiplication or division on arrays defined in the ss1 and ss2 registers. .c.3.4.1 -add: Addition The -add function adds the values in the ss2 register to the values in the ss1 register element by element. -add: ss1 := ss2 + ss1 .c.3.4.2 -mul: Multiplication The -mul function multiplies the values in the ss1 register by the values in the ss2 register element by element. -mul: ss1 := ss2 * ss1 .c.3.4.3 -sub: Subtraction The -sub function subtracts the values in the ss1 register from the values in ss2 register element by element. -sub: ss1:= ss2 -ss1 .c.3.4.4 -div: Division The -div function divides the values in the ss2 register by the values in the ss1 register element by element. -div: ss1:= ss2 / ss1 .c.3.4.5 -mod: Remainder The -mod function returns the remainder of the ss2 register divided by the ss1 register on an element by element basis. For example: -dim 1 10 -ramp -1 1 -push -unif 3 -mod -print would return the following: viewit> -print -print i: 0, 0.000000 i: 1, 1.000000 i: 2, 2.000000 i: 3, 0.000000 i: 4, 1.000000 i: 5, 2.000000 i: 6, 0.000000 i: 7, 1.000000 i: 8, 2.000000 i: 9, 0.000000 .c.3.4.6 -pow: Power The -pow function raises the values in the ss2 register to the power as specified by the values in the ss1 register element by element. -pow: ss1:= ss2 ** ss1 .c.3.4.7 Arithmetic Example These functions assume that the dimensionality of the ss1 and ss2 registers are equal or that one of the registers is a scalar value. For example, to add two 256x256 constant filled arrays: viewit -dim 2 256 256 -unif 2.0 -push -unif 3.0 -add The resulting array is a 256x256 array with all elements equal to 5.0. Similarly, a constant could be added to a 256x256 array that would result in a 256x256 array with all elements equal to 5.0 as in the following: viewit -dim 2 10 10 -unif 2.0 -push -const 3.0 -add -print The -print function prints the values in the ss1 register as a stream of scalar ASCII values on the standard output device. .c.3.4.8 Complex Arithmetic The complex register storage model assumes the real part of a complex array is stored in the ss1 register and that the imaginary part is stored in the ss2 register. For operations that perform complex arithmetic, an additional complex array is assumed to be stored with the real part in the ss3 register and the imaginary part in the ss4 register. ss1: real ss2: imaginary ss3: real ss4: imaginary .c.3.4.8.1 -cmul: Complex Multiplication Complex multiplication using the complex storage model. ss1 := ss1*ss3 - ss2*ss4 ss2 := ss1*ss4 + ss2*ss3 ss3 := ss3 ss4 := ss4 .c.3.4.8.2 -cadd: Complex Addition Complex addition using the complex storage model. ss1 := ss1+ss3 ss2 := ss2+ss4 ss3 := ss3 ss4 := ss4 .c.3.4.8.3 -conj: Complex Conjugate Complex conjugation using the complex register storage model. ss1 := ss1 ss2 := -ss2 ss3 := ss3 ss4 := ss4 .c.3.5 Dyadic Relational and Bitwise Functions .c.3.5.1 Dyadic Relational Functions Relational functions are used like the dyadic arithmetic functions. For example, one can determine the elements that have the same value in the ss1 and ss2 register by using the -leq function: viewit -dim 1 10 -ramp -1 1 -push -unif 5.0 -leq -print Immediately, before the -leq function is executed the registers contain the following values: ss1: [ 5 5 5 5 5 5 5 5 5 5 ] ss2: [ 0 1 2 3 4 5 6 7 8 9 ] After execution the registers contain the following values: ss1: [ 0 0 0 0 0 1 0 0 0 0 ] ss2: [ 0 1 2 3 4 5 6 7 8 9 ] Similarly, boolean values are returned for all data values less than 5.0 if the -llt operator is used as in the following: viewit -dim 1 10 -ramp -1 1 -push -unif 5.0 -llt -print After execution the registers contain the following values: ss1: [ 1 1 1 1 1 0 0 0 0 0 ] ss2: [ 0 1 2 3 4 5 6 7 8 9 ] Other relational functions operate similarly and return a boolean values if the condition is true: -llt: ss1 := 1 if ss2 < ss1 else 0 -lle: ss1 := 1 if ss2 <= ss1 else 0 -leq: ss1 := 1 if ss2 == ss1 else 0 -lge: ss1 := 1 if ss2 >= ss1 else 0 -lgt: ss1 := 1 if ss2 > ss1 else 0 -land: ss1 := 1 if ss2 && ss1 else 0 -lor: ss1 := 1 if ss2 || ss1 else 0 .c.3.5.2 Dyadic Bitwise Functions The dyadic bitwise functions convert floating point register values to integer values and perform dyadic bitwise operations as follows. Bitwise and: -band ss1 := ss1 & ss2 Bitwise exclusive or: -bxor ss1 := ss1 ^ ss2 Bitwise inclusive or: -bor ss1 := ss1 | ss2 .c.3.6 Common Monadic Functions The common monadic functions include the basic transcendental functions. They operate only on the ss1 register. For example, the following will generate a 1 dimensional sinusoidal oscillating field in a two dimensional array: viewit -dim 2 256 256 -ramp 256 1 -linscl 0.0 15.70797 -sin .c.3.6.1 Trigonometric -sin: ss1 := sin(ss1) Sine -cos: ss1 := cos(ss1) Cosine -tan: ss1 := tan(ss1) Tangent -asin: ss1 := asin(ss1) ArcSin -acos: ss1 := acos(ss1) ArcCos -atan: ss1 := atan(ss1) ArcTan -atan2: ss1 := atan2(ss2, ss1) ArcTan(ss2/ss1) Note: All angle arguments are in radians. .c.3.6.2 Exponential and Logarithmic -log: ss1 := log(ss1) Natural Logarithim -log10: ss1 := log10(ss1) Common Logarithim -exp: ss1 := exp(ss1) Exponential .c.3.6.3 Square Root and Square -sqrt: ss1 := sqrt(ss1) Square Root -square ss1 := ss1**2.0 Square 3.6.4 Reciprocal -rcp: ss1 := 1.0/ss1 Reciprocal .c.3.6.5 Absolute Value and Sign -sign Sign if (ss1 > 0.0) ss1 := 1.0 if (ss1 = 0.0) ss1 := 0.0 if (ss1 < 0.0) ss1 := -1.0 -chs ss1 := -1.0 * ss1 Change Sign -abs: ss1 := abs(ss1) Absolute Value .c.3.6.6 Rounding -floor ss1 := floor(ss1) Round down -ceil ss1 := ceil(ss1) Round up .c.3.6.7 Conversion -degrees ss1 := ss1*180.0/PI Convert Radians to degrees -radians ss1 := ss1*PI/180.0 Convert Degrees to radians .c.3.6.8 -linscl: Linear Scaling The -linscl function finds the maximum (MAX) and minimum(MIN) data values in the ss1 register and rescales the data so that the minimum value is equal to the LT parameter and and the maximum value is equal to the UT parameter. -linscl LT UT : ss1 := (UT-LT)/(MAX-MIN)*(ss1-MIN)+LT .c.3.6.9 -rscl: Linear Scaling over Specified Range The -rscl function allows specification of MAX and MIN as parameters: -rscl LT UT MIN MAX : ss1 := (UT-LT)/(MAX-MIN)*(ss1-MIN)+LT .c.3.6.10 -zscore: Z- Scoring ; The -zscore function subtracts the mean of the array from each value and divides by the standard deviation of the array. -zscore ss1 := (ss1- MEAN)/STDDEV .c.3.6.11 -truncate: Truncation The -truncate function set values that are less than LT to LT and values and greater than UT to UT. -truncate LT UT if (ss1 < LT) ss1 := LT if (ss1 >= LT) and (ss1 <= UT) ss1 := ss1 if (ss1 > UT) ss1 := UT .c.3.6.12 -thresh: Thresholding The -thresh function is a boolean relational operator that returns true if a value is between the range specified by the LT and UT parameters. -thresh LT UT if (ss1 >= LT ) and (ss1 <= UT) ss1 := 1 else ss1 := 0 .c.; 3.6.13 Bit Manipulation These functions initially convert floating point values to integer and then perform a right or left bit shift by the number of bits (NBITS) parameter. -rshift NBITS ss1: ss1 >> NBITS Right Shift -lshift NBITS ss1: ss1 << NBITS Left Shift .c.;3.7 Space Manipulation The space manipulation functions are used to rearrange or resample multi-dimensional arrays that are defined in the ss1 register. .c.3.7.1 -chunk: Array Subset The -chunk function is used to extract a subset array from a larger array in the ss1 register. It is used to remove a "chunk" from a larger array. The -chunk function has two vector parameters. The first specifies the vector offset of the subspace. This is followed by a vector parameter specifying size of the subspace. This function operates on a array stored in the ss1 register and the result is returned to the ss1 register. The original array is destroyed. For example, consider the following one dimensional vector: [ 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 10.0] Suppose, that a new vector consisting of 5 elements was to be extracted from the original vector with an offset of 2 from the first element in the vector, creating: [3.0 4.0 5.0 6.0 7.0] This could be accomplished using: viewit ... -chunk 2 5 ... The chunk function can be extended to arrays of higher rank. For example, consider the following two-dimensional array: 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 10.0 11.0 12.0 13.0 14.0 15.0 16.0 17.0 18.0 19.0 20.0 21.0 22.0 23.0 24.0 25.0 Using -chunk 2 1 3 2 the following subset array could be created: 8.0 9.0 10.0 13.0 14.0 15.0 Similarly, the -chunk function can be extended to arrays of any rank. .c.; .c.3.7.2 -replace_chunk: Subset Array Replacement The -replace_chunk function operates inversely to the -chunk function and is used to replace a smaller sub-array within a larger array. It is a dyadic function that replaces the elements defined in the ss1 register with the array in the ss2 register starting at a given multidimensional offset. This is specified as a vector parameter to the function. For example, consider the following one dimensional arrays defined in the ss1 and ss2 registers: ss1: [0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0] ss2: [ -1.0 0.0 1.0 ] The following syntax would be used to replace the elements defined by the vector in the ss2 register to the ss1 register starting at an offset of 3 elements from the first element in the ss1 register: viewit ... -replace_chunk 3 .... After execution of the -replace_chunk function, the registers would contain the following: ss1: [0.0 1.0 2.0 -1.0 0.0 1.0 6.0 7.0 8.0 9.0] ss2: [ -1.0 0.0 1.0] Similarly, the -replace_chunk function can easily be applied to arrays of higher rank. For example, consider the following arrays defined in the ss1 and ss2 registers: ss1: 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ss2: 1.0 1.0 1.0 1.0 2.0 1.0 1.0 1.0 1.0 ... -replace_chunk 2 1 ... would result in the following: ss1: 0.0 1.0 2.0 3.0 4.0 5.0 6.0 1.0 1.0 1.0 0.0 1.0 1.0 2.0 1.0 5.0 6.0 1.0 1.0 1.0 ss2: 1.0 1.0 1.0 1.0 2.0 1.0 1.0 1.0 1.0 .c.3.7.3 -duplicate: Array Duplication The -duplicate function expands the rank of an array defined in the ss1 register by duplicating the array over the next dimension. For example, consider the following 1 dimensional array defined in the ss1 register: ss1: [1.0 2.0 3.0 4.0] A two dimensional array could be created using the -duplicate function. For example, -duplicate 2 would create the following: ss1: 1.0 2.0 3.0 4.0 1.0 2.0 3.0 4.0 The array could be duplicated 5 times with a -duplicate 5: ss1: 1.0 2.0 3.0 4.0 1.0 2.0 3.0 4.0 1.0 2.0 3.0 4.0 1.0 2.0 3.0 4.0 1.0 2.0 3.0 4.0 Similarly, the -duplicate function will operate on arrays of higher rank. .c.3.7.4 -translate: Array Shifting The -translate function performs a right shift with wrap around of the elements defined in a multi-dimensional array in the ss1 register. It is a monadic function that has one vector parameter that specifies the amount of translation for each dimension. For example, for one dimension consider the following: ss1: [0.0 1.0 2.0 3.0 4.0 5.0] A -translate 3 would result in: ss1: [3.0 4.0 5.0 0.0 1.0 2.0] The -translate function can be extended to any number of dimensions. For example, a two dimensional array is defined as follows: ss1: 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 0.0 1.0 2.0 3.0 4.0 5.0 Using -translate 2 1 would result in the following: ss1: 6.0 7.0 4.0 5.0 0.0 1.0 8.0 9.0 4.0 5.0 2.0 3.0 2.0 3.0 0.0 1.0 .c.3.7.5 -center: Array Centering The -center function has no parameters and is equivalent to the -translate function, except the array is always translated by 1/2 the number of elements in each dimension. If an array has an odd number of elements in a dimension, the translation value is rounded down. For example, consider the following two dimensional array: ss1: [ 1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 ] After execution of the -center function: ss1: [ 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 ] .c.3.7.6 -reorder: Dimension Reordering The -reorder function rearranges the order of the dimensions in a multi-dimensional array specified in the ss1 register. The function has a single vector parameter specifying the new order of dimensions. Dimension numbering begins with 0 and the leading dimension is considered to be the 0th dimension. For example, consider the following two-dimensional array: ss1: 0 1 2 3 4 5 6 3 4 8 Using the function -reorder 1 0 would result in the transpose: ss1: 0 5 1 6 2 3 3 4 4 8 Similarly, the -reorder function can be applied to higher dimensional arrays. In three dimensions the -reorder function is useful for examining orthogonal views of an array. For example, -reorder 2 0 1 -reorder 2 1 0 provide the "sagital" and "coronal" views from a dataset that is arranged as stacked transverse slices. .c.3.7.7 -mirror: Dimension Reflection The -mirror function reflects data across a single dimension. This is specified as a single scalar dimension parameter. Like the -reorder function, dimension numbering begins at zero. For example consider the following two dimensional array: ss1: 1 2 3 4 5 6 7 8 9 2 3 4 5 6 7 8 9 10 Using the function, -mirror 0 would result in the following: ss1: 9 8 7 6 5 4 3 2 1 10 9 8 7 6 5 4 3 2 Using -mirror 1 would reflect along the columns: ss1: 2 3 4 5 6 7 8 9 10 1 2 3 4 5 6 7 8 9 Similarly, the -mirror function can be applied to higher dimensions. .c.3.7.8 -interlace: Odd/Even Shuffle Across Last Dimension The -interlace function probably has limited utility beyond its original application to rearrange the odd and even slices that are acquired in a multi-slice NMR imaging experiment. Typically, all of the two-dimensional odd slices are collected and stored prior to collecting the even slices. The resulting slices are stored as a three dimensional array with the odd slices preceding the even slices. To reconstruct the array so that the slices are in the proper order, the odd and even slices must be interleaved or interlaced. The -interlace function has no parameters and can be used on arrays of any rank. For example, consider the following one dimensional array: ss1: [ 0 1 2 3 4 5 6 7 8 9 ] After execution of the -interlace function: ss1: [ 0 5 1 6 2 7 3 8 4 9 ] .c.3.7.9 -scale: Dimension Rescaling The -scale function is used to resample a multi-dimensional array by rescaling the size of the array using the interpolation method specified by the -set INTERPOLATE_METHOD function. With the -scale function, it is possible to "zoom" or "minify" multi-dimensional arrays. The -scale function has one vector parameter that specifies the scale change factor in each dimension. For example, in one dimension consider the following one dimensional array with 5 elements: ss1: [ 0 1 2 3 4 ] Using -scale 2.0 and linear interpolation the array would be resampled as a 10 element array as follows: ss1: [ 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.0 ] N-dimensional linear interpolation is the default interpolation method, but can be specified prior to the -scale function using the -set INTERPOLATE_METHOD function as follows: -set INTERPOLATE_METHOD LINEAR Nearest neighbor interpolation can also be specified as follows: -set INTERPOLATE_METHOD NNEIGHBOR In our example, this would result in the following: ss1:[ 0.0 0.0 1.0 1.0 2.0 2.0 3.0 3.0 4.0 4.0 ] The -scale function can be similarly applied to higher dimensions. For example, consider the following two dimensional array: ss1: 0 1 2 3 4 5 6 7 8 9 Using -scale 2.0 3.0 would create a 10x6 two dimensional array using bilinear interpolation, if the -set INTERPOLATE_METHOD function is set to LINEAR. Similarly, trilinear interpolation is performed in three dimensions and linear interpolation methods are extended to higher orders with increasing dimensionality of the array. .c.3.7.10 -rotate: Cube Rotation The -rotate is an experimental function that currently is limited to resampling three-dimensional arrays after a rotation. The -rotate function resamples a three dimensional array after rotation about dimension 2. The function has one parameter that specifies the rotation angle in degrees. For example, to rotate a two-dimensional image by 30 degrees, it may be considered as a 3 dimensional array. For example: viewit -dim 2 256 256 -ramp 256 1 -linscl 0.0 15.70797 -sin \ -dim 3 256 256 1 -rotate 30.0 will create a one dimensional sinusoidal oscillating field in a two dimensional array and then rotate the array by 30 degrees. Like the -scale function, the interpolation method used during resampling can be set using the -set INTERPOLATE_METHOD function prior to execution of -rotate. The function is also used in volume rendering applications to obtain various views as a function of the rotation angle. .c..c.3.8 Dimensionality Reduction Dimensionality reduction functions are used to reduce the rank of a multi-dimensional array. .c.3.8.1 -reduce: Reduction The primary dimensionality reduction function is -reduce. Conceptually, it is related to the reduction operator described in the APL language. It collapses data along dimension 0, the leading dimension, according to the reduction operator specified as the first parameter. For example, consider the following: ss1: [ 0 1 2 3 4 5 6 7 8 9 ] The function -reduce add will return a scalar value of 45.0 by adding the values across the leading dimension. Similarly, -reduce mul would take the product of the values resulting in a scalar value of 0.0. The -reduce function can be extended to higher dimensions. For example, consider the following two dimensional array: ss1: 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 5 The function -reduce add applied to this array would result in: ss1: [ 15 15 15 15 15 ] and is equivalent to the row sum. Besides the sum and product, a variety of other operators are supported by the -reduce function: -reduce add Sum reduction -reduce mul Product reduction -reduce floor Minimum value reduction -reduce ceil Maximum value reduction -reduce median Median reduction -reduce median_not_zero Median of values not zero reduction -reduce ceil_index Index of Maximum Value .c.3.8.1.1 -reduce b1: Linear Regression Reduction The function is a dimensionality reduction operator that applies a linear regression model across the leading dimension (dimension 0 of the array) and returns the b1 value. The model is: yhat= b0 + b1*x Where X is considered to be a normalized distance (0.0 to 1.0) along the leading dimension vectors of the array. For example., consider a one dimensional vector of 128 elements containing increasing integer values from 0 to 127. The "slope" of the vector is 127/1.0. u2 36% viewit viewit V89.9 Development 5/23/90 viewit> -dim 1 128 -ramp -1 1 -dim 1 128 -ramp -1 1 viewit> -reduce b1 -reduce b1 viewit> -print -print i: 0, 127.000000 Now consider the b1 reduction of a two dimensional array: viewit> -dim 1 128 -ramp -1 1 -duplicate 10 -dim 1 128 -ramp -1 1 -duplicate 10 viewit> -show_reg -show_reg ss1: 128 10 ss2: ss3: ss4: viewit> -reduce b1 -reduce b1 viewit> -print -print i: 0, 127.000000 i: 1, 127.000000 i: 2, 127.000000 i: 3, 127.000000 i: 4, 127.000000 i: 5, 127.000000 i: 6, 127.000000 i: 7, 127.000000 i: 8, 127.000000 i: 9, 127.000000 .c.3.8.2 -scan: Scan The -scan operator is not a dimensionality reduction operator, but is considered here because of its similarity to the -reduce function. It can be considered as a cumulative reduction operator. For example, consider: ss1: [ 0 1 2 3 4 5 6 7 8 9 ] Using the function -scan add will result in the cumulative sum as follows: ss1: [ 0 1 3 6 19 15 21 28 36 45 ] Like the -reduce function, the -scan function can also be applied to arrays of higher rank. Scan supports the following functions: -scan add Cumulative Sum -scan mul Cumulative Product -scan ceil Cumulative Maximum -scan erode erode_threshold Set values to 0.0 until the cumulative sum is greater than the erode_threshold value specified in the command line. .c.3.8.3 -sum1d: Partial Reduction The -sum1d function is a special case of the -reduce add function and partially collapses the leading or zeroth dimension by partial summation. ss1: [ 0 1 2 3 4 5 6 7 8 9 ] Using -sum1d 2 would result in the following where every two elements are added together: ss1: [ 1 5 9 13 17] Likewise -sum1d 4 would result: ss1: [ 6 22] The sum1d function can be similarly extended to arrays of higher rank. .c.3.8.4 -group: Grouping of Leading Two Dimensions The application of the -group function is currently limited to three dimensional arrays. The group function reduces the rank of a three dimensional array to two dimensions, by conceptually lifting slices off the top of the cube and placing them next to each other in row order. This function is used to create two dimensional mosaics of 3-D datasets. For example, consider a cube of 16 two-dimensional 64x64 arrays. The ss1 register is allocated as follows: ss1: 64 64 16 If -group 4 is executed, the ss1 register would be allocated as follows: ss1: 256 256 With the 16 64x64 two dimensional arrays arranged in the following order in the two dimensional space: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Using a -group 8 instead, would result in the register being allocated as follows: ss1: 512 128 With the two dimensional arrays arranged as: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 .c.; .c.3.9 Fourier Transform Spectral Methods Viewit supports a class of functions that are used in Fourier transform methods. These techniques are used extensively in signal processing for applications like reconstruction, enhancement and restoration. .c.3.9.1 -ft, -ft1d, -ft2d: Fourier Transform Operators The -ft function is a monadic function that performs a n-dimensional Fourier transform using a Cooley-Tukey prime factor FFT algorithm. The -ft function has three parameters with the syntax as follows: -ft REAL FWRD REAL COMPLEX BACK POLAR CMOD PSD The first parameter specifies that the Fourier transform is to be applied to a real or complex data array. For complex data, the real part of the array is stored in the ss1 register and the imaginary part is stored in the ss2 register. If the Fourier transform is applied to only real data and the REAL parameter is specified, the contents of the ss2 register will assumed to be zero and the imaginary ss2 register does not have to be explicitly set to zero or allocated. The second parameter indicates the direction of the Fourier transform. If it is set to "FWRD", the forward transform (exponential sign is -) will be performed. "BACK" will perform the inverse transform (exponential sign is +). The third parameter describes the type of output after the Fourier transform is performed. REAL specifies that the real part of the transform will be returned to the ss1 register and the imaginary part will be returned to the ss2 register. POLAR specifies that the complex data is to be immediately converted to polar complex notation after the transform and the complex modulus is returned to the ss1 register and the phase is returned to the ss2 register. The CMOD parameter will return only the complex modulus to the ss1 register and will not compute the phase. PSD will return the natural logarithm of the power spectrum to the ss1 register. The options for this parameter are summarized as follows: Parameter Result ----------------------------- COMPLEX -ft ss1: real ss2: imag POLAR -ft ss1: sqrt( real**2 + imag**2) ss2: atan( imag/ real) CMOD -ft ss1: sqrt( real**2 + imag**2) ss2: imag PSD -ft ss1: log( real**2 + imag**2) ss2: imag The -ft1d function is similar to the -ft function except that it performs only a one-dimensional Fourier transform of the leading dimension 0 of a multi-dimensional array. The parameter syntax is exactly like the -ft function. The -ft2d function is similar to the -ft1d function except that it performs two dimensional Fourier transforms on the leading two dimensions ( dimensions 0 and 1) of a multi-dimensional array. The parameter syntax is exactly the same as the -ft function. .c.3.9.2 Filters and Windows Viewit has a number of built-in functions that are useful for creating filters and apodization windows. These functions can be considered special cases of space filling functions that are primarily used for signal processing applications. .c.3.9.2.1 -ilpf: Ideal Low Pass Filter -ilpf is a multi-dimensional function that creates an ideal low pass filter in each dimension. It has one parameter that specifies the low pass cutoff relative to a radial cuttoff frequency in each dimension. For example, viewit -dim 1 10 -ilpf 1.0 would create the following array in the ss1 register: ss1: [ 1 1 1 1 1 0 1 1 1 1] Similarly, viewit -dim 2 10 10 -ilpf 0.3 would create the following: 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 1 .c.3.9.2.2 -blpf Butterworth Low Pass Filter The -blpf creates a multi-dimensional, radially symmetric, Butterworth low pass filter with a cutoff and order defined by the first and second parameters of this function. The filter is defined as follows: -blpf cutoff order := 1/ (1+ (f/cutoff)**order) For example the following would create a one dimensional second order Butterworth low pass filter with a cutoff of 0.2. viewit -dim 1 10 -blpf 0.2 2 The ss1 register would contain the following values: ss1: [ 1.00 0.50 0.05 0.012 0.0038 0.0016 0.0038 0.012 0.05 0.50] .c.3.9.2.3 -dcfilt: DC Filter The -dcfilt function is used to create a filter of uniform values in a multi-dimensional array except for the DC component which is given the value as specified as the first parameter for this function. This filter is used for DC filtering of a signal. For example, viewit -dim 1 10 -dcfilt 0.5 would create the following array in the ss1 register: ss1: [ 0.5 1 1 1 1 1 1 1 1 1 ] Similarly, in two dimensions: viewit -dim 2 5 5 -dcfilt 0.1 would create the following array: ss1: 0.1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 .c.3.9.2.4 -radial: Radial Distance The -radial function creates an array of radial distances from the DC component and is proportional to radial frequency. This function can be used to derive other filter functions. For example, viewit -dim 1 10 -radial would create the following array: ss1: [ 0.0 0.2 0.4 0.6 0.8 1.0 0.8 0.6 0.4 0.2] In two dimensions, viewit -dim 2 5 5 -radial would result in the following: ss1: 0.00 0.50 1.00 1.00 0.50 0.50 0.71 1.12 1.12 0.71 1.00 1.12 1.41 1.41 1.12 1.00 1.12 1.41 1.41 1.12 0.50 0.71 1.12 1.12 0.71 Needless to say, the filters that are included with viewit provide only basic signal processing capabilities and are defined rather loosely. However, high pass versions of these filters can easily be derived from these cases. For applications, that require stringent filter definitions, or require special purpose filters it may be appropriate to externally create these filters, or use viewit functions to derive a filter. .c.3.9.3 Phase Correction The phase correction functions are used for phase rotation of a spectrum by mixing the real and imaginary parts. The -phase_correct_1 function performs first order frequency dependent phasing according to Absorption Spectrum= Real* Sin(theta) + Imaginary* cos(theta) where theta is a frequency dependent phase term such that theta= RP + (w-w0)*LP where RP and LP are the zeroth and first order phase correction specified as two parameters to the phase_correct_1 function. The RP and LP parameters are specified in degrees and correspond to the RP and LP values on the SISCO NMR imaging system. The -phase_correct_1 function operates on the leading or zeroth dimension of the ss1 register. For example, the spectrum could be reconstructed and phased from the FIDs that have 256 samples generated by the SISCO system as follows: viewit -iformat SISCO -i file.fid -ft1d complex fwrd REAL \ -translate 128 0 -xchg -translate 128 0 -xchg \ -phase_correct_1142.52 -127.35 ... The RP value was determined to be 142.42 and the LP value was -127.35. After phase correction, the absorption spectrum is returned to the ss1 register and the dispersion spectrum is returned to the ss2 register. Reference: SISCO Operators Manual, Spectroscopy Imaging Systems Corporation, October, 1987 pp. 7.2-7.3. .c.3.10 Neighborhood Operator Functions The neighborhood operator functions are used to perform operations like convolution, rank order filtering and statistical filtering using relatively small neighborhoods or kernels. .c.3.10.1 N-Dimensional Convolution Functions The N-dimensional convolution functions convolve an array of any rank with a neighborhood or kernel with the same number of dimensions. The size of each of the dimensions of the kernel must be equal and odd. A multi-dimensional unweighted average kernel has been predefined: -nbhd UNWAVG ksize ksize specifies the size of the dimensions of the kernel and must be odd. The kernal is filled with constant values such that the sum of all elements in the kernel equal 1.0. A user-defined kernel can be loaded to the ss2 register and used for multi-dimensional convolution. The rank of the array defined in the ss2 register must be equal to that in the ss1 register. Also, the sizes of each of the dimensions in the ss2 register must be equal and odd. The syntax for the function is as follows: -nbhd SS2 The following example, will convolve a 3 dimensional Laplacian with a three dimensional array: viewit -dim 3 3 3 3 -iformat RAW -itype ASCII -i LAP.nbhd \ -push -iformat HDF -i test.hdf -nbhd SS2 ... The file LAP.nbhd is a user created ASCII file that contains the 3x3x3 kernel to be convolved with the three dimensional array defined in the HDF file named test.hdf. .c.3.10.2 Predefined Convolution Kernels .c.3.10.2.1 2-D Pre-Defined Convolution Kernels The following kernels have been predefined for two-dimensional convolution. Function Kernel Description -nbhd UNWA3 0.111 0.111 0.111 Unweighted 0.111 0.111 0.111 Smoothing 0.111 0.111 0.111 -nbhd gauss3 sigma Exponential Weighted If sigma = 1.0 the kernel is: 1.95 1.40 1.95 1.40 1.00 1.40 1.95 1.40 1.95 If sigma = -1.0 the kernel is: 0.51 0.71 0.51 0.71 1.00 0.71 0.51 0.71 0.51 -nbhd gauss5 sigma Exponential Weighted If sigma = -1.0 the kernel is: 0.20 0.36 0.44 0.36 0.20 0.36 0.67 0.82 0.67 0.36 0.44 0.82 1.00 0.82 0.44 0.36 0.67 0.82 0.67 0.36 0.20 0.36 0.44 0.36 0.20 -nbhd LAP43 0.0 -0.25 0.0 Laplacian -0.25 1.0 -0.25 0.0 -0.25 0.0 -nbhd VEDGE1 -1.0 0.0 1.0 Unweighted Vertical Edge -1.0 0.0 1.0 Enhancer -1.0 0.0 1.0 -nbhd VEDGE2 -1.0 0.0 1.0 Weighted Vertical Edge -2.0 0.0 2.0 Enhancer -1.0 0.0 1.0 -nbhd VLINE1 -0.5 1.0 -0.5 Vertical Line Enhancer -0.5 1.0 -0.5 -0.5 1.0 -0.5 -nbhd HEDGE1 -1.0 -1.0 -1.0 Unweighted Horizontal 0.0 0.0 0.0 Edge Enhancer 1.0 1.0 1.0 -nbhd HEDGE2 -1.0 -2.0 -1.0 Weighted Horizontal 0.0 0.0 0.0 Edge Enhancer 1.0 2.0 1.0 -nbhd HLINE1 -0.5 -0.5 -0.5 Horizontal Line Enhancer 1.0 1.0 1.0 -0.5 -0.5 -0.5 For example, a 3x3 Laplacian convolution operation can be performed on a 2-D uniformly distributed random noise field as follows: viewit -dim 2 128 128 -rand -linscl 0.0 255.0 -nbhd LAP43 .c.3.10.2.2 3-D Pre-Defined Convolution Kernels The following kernel has been predefined for three dimensional comvolution. The rank of the array in the ss1 register must be 3. -nbhd gauss4 sigma Exponential Weighted If sigma is -1.0 the 3x3x3 convolution kernel values are: 0.37 0.51 0.37 0.51 0.72 0.51 0.37 0.51 0.37 0.51 0.72 0.51 0.72 1.00 0.72 0.51 0.72 0.51 0.37 0.51 0.37 0.51 0.72 0.51 0.37 0.51 0.37 .c.3.10.2.3 Convolution Performance Enhancement The performance of most of the neighborhood operators is not computationally efficient due to the overhead in the current algorithm used to determine neighbors that is independent of the rank of the array. Because of this, a faster convolution algorithm has been specifically coded for the one, two and three dimensional cases. The use of the faster algorithm can be specified by using the parameter of 1 to the -set ALGORITH_METHOD function prior to calling the neighborhood convolution function as follows: -set ALGORITH_METHOD 1 This algorithm as currently implemented operates on values that are at least 1/2 ksize away from the boundary of the array. .c. .c.3.10.3 Rank Order Neighborhood Functions The rank order filtering functions sort the values in the neighborhood and replace the value at the origin of the neighborhood with the rank value determined by the icval parameter. All of the rank neighborhood functions operate on arrays of any dimensionality. For the general case, the rank operator has a syntax as follows: -nbhd rank ksize icval ksize determines the size of each dimension in the neighborhood and must be odd. icval determines the rank value replacement order. For example, consider that the rank operator is to be used on a three dimensional array with a neighborhood of 3x3x3 for median filtering. -nbhd rank 3 13 would replace the origin of the neighborhood with the median or middle value of the sorted values. This is called a median filter and has been implemented as a specific rank order filter with the syntax as follows: -nbhd median ksize Other commonly used rank order filter are the min and max filters which replace the origin of the neighborhood with either the minimum or maximum values in the neighborhood. -nbhd min ksize -nbhd max ksize .c.3.10.4 Statistical Neighborhood Functions The statistical neighborhood functions are like the rank order functions except that they replace the origin of the neighborhood with a specified statistical function. For example, the mean filter calculates the mean of all the neighbors ( this is the same as unweighted convolution). Similarly, the origin of the neighborhood can be replaced with the variance and the standard deviation. Mean Filter: -nbhd mean ksize Variance Filter: -nbhd variance ksize Standard Deviation Filter: -nbhd stddev ksize Neigborhood Correlation: -nbhd r ksize Returns local correlation matrix. Neighborhood Sum: -nbhd sum ksize Neighborhood sum of squares: -nbhd sum^2 ksize Neighborhood Z-score: -nbhd zscore ksize Neighborhood Fraction: -nbhd nf ksize Origin of neighborhood value divided by sum of neighbors. .c.3.10.5 Adaptive Histogram Equalization -nbhd AHE ksize This neighborhood operator performs adaptive histogram equalization for a neighborhood of size ksize for any multidimensional array defined in the SS1 register. 3.10.6 Neighborhood Multivariate Space -nbhd MVN_SPACE ksize .c.3.11 Back Projection The back projection functions are used to reconstruct a two or three dimensional sampled function from its projections. .c.3.11.1 Two Dimensional Back Projection The geometry defined for the two dimensional back projection function is defined in fig. 3.11.1. The -bkproj_2d function performs a parallel back projection of a set of projections defined as a two dimensional array in the ss1 register using the acquisition geometry defined as a one dimensional vector of theta values in the ss2 register. The theta values of the projection orientation are specified in radians. For example, consider an experiment that has 100 projections where each projection has 128 samples. The projections are loaded to the ss1 register as a two-dimensional array and a vector of theta values is loaded to the ss2 register. Memory would be allocated as follows: ss1: 128 100 ss2: 100 Each element in the ss2 register corresponds to the theta value specifying the projection orientation of the projection defined in the leading dimension of the ss1 register.  The bkproj_2d function has 7 parameters. The first two parameters specify the number of samples in each dimension of the resulting two-dimensional reconstruction space. The next two parameters specify the offsets of the area to be reconstructed. These are followed by two parameters that specify the size of the area. The last parameter indicates the interpolation method used during the back projection. This parameter is NNEIGHBOR for nearest neighbor or zeroth order interpolation and is LINEAR for linear or first order interpolation. For example, to reconstruct the entire normalized reconstruction space to a 100x100 array using linear interpolation the parameters for the function would be specified as follows: -bkproj_2d 100 100 -1.0 -1.0 2.0 2.0 LINEAR To reconstruct one quadrant of the normalized reconstruction space the following could be used: -bkproj_2d 100 100 0.0 0.0 1.0 1.0 LINEAR The back projection function can be used for two-dimensional projection reconstruction using the filtered back projection method. The following viewit command uses the filtered back projection method to reconstruct a circle from simulated projections. viewit -dim 1 127 -unif 1.0 -filt1d CIRCLE 0.5 \ (1) -ft real frwd REAL -push -radial -mul \ (2) -xchg -pop -xchg -push -radial -mul -xchg -pop -xchg \ (3) -ft complex back REAL \ (4) -duplicate 180 \ (5) -push -dim 1 180 -ramp -1 1 -linscl 0.0 179.0 -radians \ (6) -xchg -bkproj_2d 128 128 -1.0 -1.0 2.0 2.0 LINEAR (7) The steps performed are as follows: (1) Create one projection of a circle with 127 samples and a diameter of 0.5 the size of the projection. (2) (3) (4) Filter the projection by transforming to the Fourier domain and multiplying the real and imaginary parts by the |w| function and then back transform to the spatial domain. (5) Duplicate the filtered projection 180 times. (6) Create an angle table of theta values from 0 to 179 degrees and convert to radians. (7) Perform the two-dimensional back projection. References: A. Rosenfeld and A.C. Kak, 1982, Digital Image Processing, (Orlando, Fla.: Academic Press, Inc.), pp.369-383 .c.3.11.2 Three Dimensional Back Projection The geometry defined for the three dimensional back projection function is defined in fig. 3.11.2  .c.3.11.2.1 Direct Method The -bkproj_3d_fast function uses the direct method to back project a set of projections defined as a two dimensional array in the ss1 register using the acquisition geometry defined as a table of theta and phi values in the ss2 register. The theta and phi values are specified in radians. For example, consider an experiment that has 3600 projections and each projection is sampled 256 times. This projection data is loaded to the ss1 register as a two-dimensional array and a table of theta and phi values is loaded to the ss2 registers as follows: ss1: 256 3600 ss2: 2 3600 The zeroth and first elements of the leading dimension in the ss2 register correspond to the theta and phi values for the projection in the ss1 register. In other words, geometry defined by the rows in the ss2 register corresponds to the sampled projection along the rows in the ss1 register. The -bkproj_3d_fast function has 7 parameters. The first 3 parameters define the number of samples in each dimension of the resulting reconstruction volume returned to the ss1 register. The next three parameters specify a "zoom" factor about the center of the normalized reconstruction volume. The last parameter specifies the interpolation method used during back projection. For zeroth order or nearest neighbor interpolation, this parameter is NNEIGHBOR. For first order or linear interpolation LINEAR is specified. For example, to reconstruct the complete reconstruction space to a 100x100x100 array using linear interpolation the parameters for the function would be -bkproj_3d_fast 100 100 100 1.0 1.0 1.0 LINEAR To reconstruct only the center 1/8th of the normalized reconstruction volume the -bkproj_3d_fast function can be used to "zoom" each of the dimensions by a factor of 2.0 as follows: -bkproj_3d_fast 100 100 100 2.0 2.0 2.0 LINEAR The resulting reconstruction volume is sampled twice as much in each of the dimensions as the previous example. To achieve the same sampling resolution the "zoomed" array would be reconstructed to a 50x50x50 array as follows: -bkproj_3d_fast 50 50 50 2.0 2.0 2.0 LINEAR The following is one approach to implementing the complete 3D filtered back projection reconstruction problem for a simulated hollow sphere: viewit -iformat RAW -itype ASCII -dim 2 2 3542 -i angle.table \ -push -dim 2 65 3542 -unif 1.0 -filt1d SPHERE 0.9 0.5 \ -filt1d 2DIFF -bkproj_3d_fast 64 64 64 1.0 1.0 1.0 LINEAR ... An ASCII angle table representing the acquisition geometry for 3542 projections is first read from the file angle.table. This angle table is pushed down the stack to the ss2 register and memory is allocated in the ss1 register for 3542 projections that are sampled 65 times. The -filt1d SPHERE function is used to generate projections of a hollow sphere with an outer radius of 0.9 and an inner radius of 0.5 samples. The hollow sphere projections are then filtered using a 3 point second difference filter implemented as a one dimensional digital convolution using the -filt1d 2DIFF filter. Finally, the filtered projections are back projected to a 64x64x64 array with a zoom factor of 1.0 using linear interpolation. Notes: 1.) The -bkproj_3d function automatically weights each projection by sin(theta). 2.) The function -filt1d 2DIFF, as currently implemented, produces a result with the wrong sign. This results in a normalizes reconstruction value that also has the wrong sign. -chs may be used to rectify this. .c..c.3.11.3 Projection Reconstruction Support Functions The -filt1d function provides support for projection reconstruction using the filtered back projection methods. The functions perform a variety of operations that operate only on the leading dimension of an array. Note: Most of these are "clunky" functions that can be cleverly superseded by limiting the number of operations dimensions. .c.3.11.3.1 Projection of a Circle -filt1d CIRCLE R Multiplies projection of a circle or disk centered at the origin of the projection with a radius specified between 0.0 and 1.0. The leading dimension must be odd. For example, viewit -dim 1 127 -unif 1.0 -filt1d CIRCLE 0.5 Would create projections of a circle with a diameter of 64 samples. 3.11.3.2 Projection of a Hollow Sphere -filt1d SPHERE RO RI Multiplies projections of a hollow sphere with an outer radius of R0 and an inner radius of RI specified in samples by the ss1 register. The leading dimension must be odd. For example, viewit -dim 2 101 100 -unif 1.0 -filt1d SPHERE 0.75 0.50 would create projections of a hollow sphere with an outer radius of 0.75 and an inner radius of 0.5. .c.3.11.3.2 Hanning Window -filt1d LAI Multiples a one-dimensional cosine window with the ss1 register. .c.3.11.3.3 Band Pass Filter -filt1d BAND_PASS low high value Multiplies a notch filter with a notch specified between the low and high parameters with a value of value. For example, viewit -dim 2 10 3 -unif 1.0 -filt1d BAND_PASS 3 5 0.0 Would result in the following array in the ss1 register: ss1: 1 1 1 0 0 1 1 1 1 1 1 1 1 0 0 1 1 1 1 1 1 1 1 0 0 1 1 1 1 1 .c.3.11.3.4 3 Point Second Difference Filter -filt1d 2DIFF Convolves a one dimensional 3 point second difference filter ( -1.0 2.0 -1.0 ) with the leading dimension of the ss1 register. .c.3.11.3.5 3 Point Unweighted Smoothing Filter -filt1d 3PT Convolves a one dimensional 3 point unweighted average filter ( 0.3333 0.3333 0.3333) with the leading dimension of the ss1 register. .c.3.11.3.6 3 Point Gradient -filt1d GRAD Convolves a one dimensional gradient filter ( -1.0, 0.0 , 1.0) with the leading dimension of the ss1 register. 3.11.3.8 Area Normalization -filt1d AREA_NORM One dimensional area normalization. .c.3.11.3.7 Base Line Correction -filt1d BLC nelements Determines the mean of the last nelements along the leading dimension of the ss1 register and subtracts the calculated mean from each value in the leading dimension. .c.3.12 Rendering Functions Viewit provides a primitive toolbox of rendering functions that are used to support exploratory visualization of multi-dimensional arrays. .c.3.12.1 Height Reduction The -height_reduce function is a specialized reduction operator for three dimensional arrays. It returns the "depth" or the index of the first element that is greater than zero along the last dimension in the array ( dimension number is 2) of the ss1 register. The voxel value of an identically dimensioned array in the ss2 register is returned to the ss2 register. .c.3.12.2 Lighting -light elevation azimuth background The -light function is used to "light" a two dimensional height field by calculating the dot product between a unit lighting vector specified by the elevation and azimuth parameters and the local surface normal unit vector of the height field. Any dot product values less than the background parameter are truncated to the back ground value. .c..c.3.12.3 -movie: Volume Cine The -movie function provides the capability to create a movie or "cine" of a rotating 3-D volume. For each rotation angle (degrees) specified as a vector list in the ss2 register, -movie creates a 2-D projection based on the rotation angle. using the following algorithm: First rotate the 3D data set in ss1 about axis2 by the current angle (degrees) value. Second, multiply the result by the decay function exp((-alpha*x)/nx), where x is the pixel position along axis0 and nx is the number of values in axis0. If ERODE is requested, then perform a running sum along axis0, setting each pixel value to 0 until the cummulative sum exceeds erode_thresh. Finally, project the resulting 3D data set down to a 2D movie frame along axis0. The reduce_method flag specifies whether the reduction should be via pixel integration (ADD), maximum pixel value (MAX) or minimum pixel value (MIN). The result is placed in ss1 with each successive frame being stacked along axis2. The syntax for -movie is as follows: -movie alpha method erode_flag erode_thresh 2diff_FLAG alpha: defines the decay function. method: Reduction method ceil- Maximum add- sum ceil_index- index of maximum erode_flag: erode- Use erosion method. no_erode- Do not use erosion method. erode_thresh: erode threshold value 2diff_flag: 2DIFF- Calculate second difference. NO2DIFF- Do not calculate second difference. For example, -movie may be used to create a set of 36 projections of a 64x64x64 array using a weighted maximum intenstity projection as follows: viewit -dim 1 36 -ramp -1 1 -linscl 0.0 350.0 -push (1) -dim 3 64 64 64 -iformat RAW -itype UBYTE -i volume (2) -movie 1.0 ceil no_erode NO2DIFF This macro performs the following: 1.) Create table of rotation angle from 0.0 to 350 degrees in 10 degree steps and push to ss2. 2.) Load 64x64x64 array of unsigned bytes to ss1 from a file named "volume". 3.) Use -movie with alpha= 1.0 and project the maximum value along the weighted ray. Do not use the erosion technique and do not calculate second differences. After execution, a 64x64x32 array is returned to ss1. The leading 2 dimensions contain projections for each angle of rotation. This array may then be displayed as a "cine" loop using a number of display devices ( viewit_tool, vt, vt2, NCSA image, etc.) Note: 1.) A version of this algorithm exists for the Connection Machine. See the viewit Reference Manual under -cmmovie for more information. .c.3.13 Multivariate Functions A multivariate array is defined as a n-dimensional array where the last dimension is defined as the variable space dimension. For example, a three dimensional spatial array with variables of pressure and velocity could be loaded to viewit as an array with a rank of 4. If the spatial dimensions where sampled as a 64x64x64 array, memory for the ss1 register could be allocated as follows: ss1: 64 64 64 2 In this case dimension 3 (the last dimension) is the variable space dimension and contains two variables. . .c.3.13.1 -histogram: Multivariate Histogram The -histogram function is a n-dimensional, multivariate operator that returns a multivariate histogram of the ss2 register. The bins for the histogram are indexed by an array in the ss2 register where the size of each of the dimensions is equal to the number of bins for each variable. For example, consider calculating the histogram of a 1 variable, three dimensional space that is 64x64x64. viewit -i file -dim 4 64 64 64 1 -linscl 0.0 255.0 \ -push -dim 1 256 -unif 0.0 -histogram This command loads a three dimensional array and then redimensions the array as a multivariate array with 1 variable. The values are then scaled between 0 and 255 for creation of 256 bin levels. The array is push down to the ss2 register and a 1 dimensional array with 256 elements is dimensioned in the ss1 register and initialized. The histogram function is executed and a frequency histogram with 256 bin levels is returned to the ss1 register. The cumulative probability density function could then be determined using the -scan add function. A scatter plot can be considered as a two-variable frequency histogram. The -histogram function can be used to calculate this as follows: viewit -i pressure -dim 4 64 64 64 1 -linscl 0.0 255.0 \ -push -dim 4 64 64 64 2 -replace_chunk 0 0 0 0 -xchg -pop \ -push -i velocity -dim 4 64 64 64 1 -linscl 0.0 255.0 \ -xchg -replace_chunk 0 0 0 1 \ -push -dim 2 256 256 -unif 0.0 -histogram ... The first four lines load 64x64x64 three dimensional arrays of pressure and velocity to a four dimensional multiversity array where the [*, *, *, 0 ] is pressure and [*, *, *, 1] is velocity. The last line creates the two-dimensional array for the frequency histogram. After execution of the histogram function, this array contains the two variable frequency distribution where dimension 0 is binned on pressure and dimension 1 is velocity. The -histogram function can be applied in the same manner to any n-dimensional, multivariate case. .c.3.13.2 -look_up: Multivariate Transfer Functions The -look_up function is used as a multivariate transfer function to n-dimensional spaces. Prior to execution, an n-dimensional space is loaded to the ss2 register and a two dimensional look up table is loaded to the ss1 register. The first column along dimension 1 in the table is the abscissa value for the lookup table that is loaded in increasing order. The other columns are the ordinate values for the the variables in the multivariate space. The function has one parameter that specifies the interpolation method to be used during table look up. NNEIGHBOR specifies nearest neighbor or zeroth order interpolation and LINEAR specifies linear or first order interpolation For example, consider the following arrays loaded to the ss1 and ss2 register: ss1: [ 0.0 -1.0 0.2 -0.8 0.4 -0.6 0.6 -0.4 0.8 -0.2 1.0 0.0 ] ss2: [ 0.51 0.62 0.55 0.31 0.22 0.11 0.20 ] After execution of the -look_up the ss1 register would contain the following one dimensional array if the LINEAR parameter was specified. ss1: [-0.49 -0.38 -0.45 -0.69 -0.78 -0.89 -0.80] and the registers are allocated as follows: ss1: 7 1 ss2: 2 If a three column table was loaded to the ss1 register as follows: ss1: [ 0.0 -1.0 0.01 0.2 -0.8 0.02 0.4 -0.6 0.03 0.6 -0.4 0.04 0.8 -0.2 0.05 1.0 0.0 0.06 ] A 7x2 array would be returned to the ss1 register with the following contents: ss1: [ -0.49 -0.38 -0.45 -0.69 -0.78 -0.89 -0.80 0.0355 0.0410 0.0375 0.0255 0.0210 0.0155 0.0200 ] The -look_up function can be similarly extended to arrays of any rank. .c.3.13.3 -cormat: Multivariate Correlation Matrix Determination The -cormat function will calculate the correlation matrix between multiple variables in the variable dimension of the ss1 register and return the correlation matrix to the SS1 register. For example, consider an 64x64x64 array with 5 variables that has been loaded to the ss1 register as follows: ss1: 64 64 64 5 After execution of the -cormat function, a two dimensional array will be returned to the ss1 register that represents the real symmetric correlation matrix between the 5 variables as follows: ss1: 5 5 .c.3.14.4 -covarmat: Multivariate Covariance The -covarmat operates similar to the -cormat function, but returns the covariance matrix between variables. .c.3.14 Matrix Functions The following functions are traditional matrix operators and assume two dimensional arrays. The leading dimension (dimension 0) is assumed to be the column dimension of the matrix. .c.3.14.1 -identity_matrix Create identity matrix. For example, -dim 2 3 3 -identity_matrix would create the following array in the ss1 register: ss1: [ 1 0 0 0 1 0 0 0 1 ] .c.3.14.2 -vector: Convert to Vector The -vector functions converts an array of any rank to a one-dimensional vector. For example the 4x3 array in the following: ss1: [ 0 1 2 3 4 5 6 7 8 9 0 1 ] would be converted to a 1 dimensional array with 12 elements as follows: ss1: [ 0 1 2 3 4 5 6 7 8 9 0 1 ] .c.3.14.3 -matmul: Matrix Multiply Matrix multiplication ss1 := ss2 * ss1 Note: Uses F01CKF NAG Library routine. .c.3.14.4 -eigen: Eigen Vectors and Values of a matrix;. Returns to the ss1 register eigen values or eigen vectors of a real symmetric matrix in the ss1 register. -eigen vector: eigen vectors. -eigen values: eigen values. Note: Uses F02ABF NAG Library routine. .c.3.15 Sorting and Indexing Functions .c.3.15.1 -sort: Sort Values The -sort function sorts values in the ss1 register in ascending order. .c.3.15.2 -index: Index Values based on Table The -index function rearranges values in the ss1 register based on an index value in the ss2 register. ss1 := ss1[ss2] ss2 := ss2 For example consider the following: ss1 := [ 0 1 2 3 4 5 6 7 8 9 ] ss2 := [ 9 0 0 0 1 2 3 4 5 5 ] after execution of -index ss1 := [ 9 0 0 0 1 2 3 4 5 5 ] ss2 := [ 9 0 0 0 1 2 3 4 5 5 ] .c.3.15.3 -index_table: Create Index Table The -index_table function provides an alternative to directly sorting the elements of an array. It returns an array of indicesthat is in sorted order if the array is indexed by the table. For example ss1 := [ 0.513 0.175 0.308 0.534 0.947] after execution of -index_table ss1 := [ 1 2 0 3 4] An array can be sorted in ascending order through the following: -push -index_table -xchg -index .c.3.14.4 -rank: Rank The -rank function returns the rank order value of the elements in the ss1 register. .c.3.50 -plot: NCAR Graphics Interface The -plot functions provide a simple interface to the NCAR graphics plotting subroutine package. These functions allow simple X*Y plots, contour plots, surface plots and field plots of arrays. .c.3.50.1 -plot OPEN This function opens the NCAR metafile. The default filename for the metafile is gmeta. This function should precede any other plotting functions. .c.3.50.2 -plot EZY title: X*Y Plot w/ implied abscissa Produces a X*Y plot of the a vector of values in the ss1 register as a function of the index of the values. A title for the plot is specified as the second parameter to the function and must consist of all capital letters. Example: viewit -dim 1 100 -ramp -1 1 -linscl 1.0 100.0 -log10 \ -plot OPEN -plot EZY EZYDEMO -plot CLOSE .c.3.50.3 -plot EZXY title: X*Y Plot Produces a X*Y plot of a vector of values in the ss1 and ss2 registers. ss1: Y values ss2: X values Example: viewit -dim 1 100 -ramp -1 1 -linscl -300.0 300.0 -push \ -linscl 1.0 100.0 -log10 -plot OPEN -plot EZXY EZXYDEMO \ -plot CLOSE .c.3.50.4 -plot EZMY title : Multiple X*Y Plot w/implied abscissa Produces multiple X*Y plots of an array of values in the ss1 register as a function of the index of the array. A title for the plot is specified as the second parameter for the function Example: viewit -dim 2 100 5 -ramp -1 100 -linscl 0.0 100.0 -push \ -gauss -add -plot OPEN -plot EZMY EZMYDEMO -plot CLOSE .c.3.50.5 -plot EZMXY title: Multiple X*Y Plot viewit -dim 2 100 5 -ramp -1 100 -linscl -0.0 100.0 -push \ -gauss -add -push -dim 1 100 -linscl -100.0 100.0 -xchg \ -plot OPEN -plot EZMXY EZMXYDEMO -plot CLOSE .c.3.50.6 -plot EZCNTR: EZ Contour Plot Produces a contour plot of a two dimensional array in the ss1 register. Example: viewit -dim 2 64 64 -radial -center -linscl 1.0 100.0 -log10 \ -plot OPEN -plot EZCNTR -plot CLOSE .c.3.50.7 -plot CONREC low high increment: Contour Plot w/ level specification Produces a contour plot with specification of the contour levels. These are specified as 3 parameters that are the low, high and incremental values for the contour lines. Example: viewit -i mouse_smooth.hdf -linscl 0.0 100.0 \ -plot OPEN -plot CONREC 0.0 100.0 10.0 -plot CLOSE .c.3.50.8 -plot EZSRFC elevation aspect : Surface Profile Plot Produces a surface plot of a two dimensional array in the ss1 register. The elevation and aspect parameters specify the viewing geometry. Example: viewit -dim 2 100 100 -radial -center -push \ -unif 0.5 -llt \ -plot OPEN -plot EZSRFC 30 45 .c.3.50.9 -plot EZVEC: Field Plot Produces a field plot by drawing arrows for each data location. The ss1 and ss2 registers contain two dimensional arrays that specify the Y and X directions of the field to be plotted. Example: viewit -dim 2 16 16 -unif 0.0 -push -ramp -1 1 \ -plot OPEN -plot EZVEC -plot CLOSE .c.3.98 Command Line Control Functions These functions are used to provide control of execution of the viewit command line. .c.3.98.1 -sleep time Puts the viewit process to sleep for time in seconds. Uses the system sleep command. .c.3.98.2 -loop n .... -endloop Executes the functions between the -loop and -endloop functions n times. This command is used for looping within a viewit command line. .c. 3.98.3 -macro: macro file execution Is used to execute the viewit command string stored as an ASCII text file. For example, the file low_pass.mac could be created as follows: low_pass_filter.mac: -ft real fwrd REAL -push -unif 0.0 -push -blpf 0.2 2 -cmul -ft complex back REAL This macro could then then be called from within viewit as follows: ... -macro low_pass_filter.mac ... .c.; .i..c..c.3.99 Misc. Functions .c.3.99.1 -debug level Provides for debug reporting. Level 0 is for no debug output. A level of 1 provides minimal debug reporting and a level of 2 provides the highest level of debug output. .c.3.99.2 -status Reports of version information, elapsed wall clock time, user CPU time and system CPU time in seconds. .c.3.99.3 -timer ON Reports elapsed wall clock time, user CPU and system CPU time at each function step. -timer OFF Stops display of timer information. .c.3.99.4 Printing: -print Provides formatted ASCII output of the values in the SS1 register to the standard output device. .c.3.99.5 Univariate Statistics: -stats Provides a report of standard univariate statistics of the values in the SS1 register to the standard output device. .c. 3.99.6 Crude Raster Plotting Plotting: -graph ival LOCAL_SCALE GLOBAL_SCALE SCALE min max Produces a crude raster plot of the values in the leading dimension of the array as a function of position in the array. The ival parameter is the "color" value of the point to be plotted. The SCALE parameters specify the method of scaling the data. .c.3.99.7 Display Register Memory Allocation: -show_reg Reports the dimensionality or shape of the arrays in the register stack. .c.4.0 File I/O .c.4.1 File Input/Output Functions Viewit supports a number of file functions for loading data to the register stack. The -i function is used to open the data file, allocate storage for an array and read the file to the register stack. This function also performs any necessary data type conversions to internal floating point storage formats. The -i function is a space filling function that has one parameter that is a character string containing the name of the file. Several input functions are available to modify the operation of the -i function. These functions must be specified preceding the -i function in the viewit command line. The -iformat function specifies the input file format. The -itype function is available for specifying the type of data that is to be read. This is used for file formats that do not automatically specify the data type in the input file. The -ioffset function provides the ability to start reading data from the file at a given offset. The function has one parameter that usually specifies the offset in bytes. Viewit supports output file functions that are used for exporting data from the internal space registers to an external file. The output functions are used for saving data from the register stack to a file. The -o function is opposite of the -i function. It is used to open a output file, convert data from internal floating point data type to the output data type and write data from the ss1 register to an external file. The -oformat and -otype functions are similar to -iformat and -itype functions and specify the file format and data type to be written. The following table summarizes the characteristics of the file formats currently supported in viewit. FILE FORMAT CHARACTERISTICS ======================================= File Format 1 2 3 4 5 RAW N/A I/O N N skips bytes YAHO1 N-D I/O N Y none YAHOXDR N-D I/O Y Y none HDF N-D I/O Y Y none FITS N-D I N(a) Y none SISCO 1,2,3-D I N Y none HDF_RASTER_8 2 I/O Y Y none HDF_RASTER_8_WLUT 2 I/O Y Y none HDF_RASTER_24 2 I/O Y Y no CHARACTERISTICS 1. Maximum array dimensionality supported. 2. Viewit support for Input and/or Output. 3. Machine Independent File Format. 4. Internal Definition of array dimensions and data typing (self- defining 5. -ioffset affect. .c.4.1.1 RAW File Format RAW file formats consist of a stream of raw data elements, where the data type must be specified by the -itype function. RAW file formats are not self-defining and memory must be allocated prior to using the -i function. For example, suppose that a file consists of a 512x512 two-dimensional array of unsigned byte values. To read the file the following viewit command could be used: viewit -dim 2 512 512 -iformat RAW -itype UBYTE -i file.dat Viewit will continue to read data elements of the type specified until the space that has been allocated is filled. Viewit will internally perform all the necessary conversions between unsigned byte values and the internal floating point format. Viewit currently supports the following input data types that may be specified with the -itype function: RAW File Format Input Data Types Input Data Type Comments =============== ============================ UBYTE Unsigned Bytes BYTE Signed Bytes USHORT Unsigned Short Integers SHORT Signed Short Integers ULONG Unsigned Long Integers LONG Signed Long Integers FLOAT Floats DOUBLE Double Floats CFLOAT Complex Floats (real, imag) CSHORT Complex Short Integers(real, imag) CLONG Complex Long Integers (real, imag) VAXSHORT Vax short integers ASCII ASCII Character Representation The RAW input file format is very flexible for reading many files formats that are not specifically supported. By using the -ioffset function, the user is able to skip over the file header and directly read the data. For example, suppose that a file format contains a 256 byte header followed by a 64x64x64 floating point array. The array could be directly read with: viewit -dim 3 64 64 64 -iformat RAW -itype FLOAT -ioffset 256 \ -i test.dat ... Viewit supports the following output data types RAW File Format Output Data Types Output Data Type Comments ================ ============================= UBYTE Unsigned Bytes BYTE Signed Bytes USHORT Unsigned Short Integers SHORT Signed Short Integers ULONG Unsigned Long Integers LONG Signed Long Integers FLOAT Floats DOUBLE Double Floats CFLOAT Complex Floats (real, imag) ASCII ASCII Character Representation A RAW output data file format can be specified with -oformat. The output data type is specified with -otype. For example, to output a data file of raw unsigned bytes the following could be used: ... -oformat RAW -otype UBYTE -o file_name .c.4.1.2YAHO1 File Format The YAHO1 file type is a very simple, I/O efficient, self defining file format that keeps track of the shape and data type of the array within the file. The data in a YAHO1 format file is preceded by a simple header. The size of the header is dependent on the rank of the array. The first element in the header is a long 4 byte integer containing the number of dimensions in the array. This is followed by a vector of long 4 byte integers that specify the number of elements in each dimension. The last header element is a long integer that contains the data type ID as specified in Sec. 4.1.1. This is immediately followed by a data stream of the data type specified. This is illustrated as follows: NDIM Number of Dimensions NN_0 Size of 0th dimension NN_1 NN_2 . . . NN_NDIM-1 Size of last dimension. ID Data Type [Binary Data of type ID] The input and output data types supported by this data type are as follows: Input Data Type Comments ============== ========= UBYTE Unsigned Bytes BYTE Signed Bytes USHORT Unsigned Short Integers SHORT Signed Short Integers ULONG Unsigned Long Integers LONG Signed Long Integers INTEGER Signed Long Integers FLOAT Floats DOUBLE Double Floats CFLOAT Complex Floats (ss1=real, ss2=imag) CSHORT Complex Short Integers(ss1=real, ss2=imag) CLONG Complex Long Integers (ss1= real, ss2=imag) Output Data Type Comments ================ =========== UBYTE Unsigned Bytes BYTE Signed Bytes USHORT Unsigned Short Integers SHORT Signed Short Integers ULONG Unsigned Long Integers LONG Signed Long Integers FLOAT Floats DOUBLE Double Floats CFLOAT Complex Floats (ss1= real, ss2= imag) For example, a YAHO1 file with a floating point data file may be output as follows: -oformat YAHO1 -otype FLOAT -o file The file may then be input with -iformat YAHO1 -i file .c.4.1.3 YAHOXDR File Format A machine independent self-defining file format similar to YAHO1 except the header and data values are encoded using the XDR (external data representation) standard.. Data types supported for input and output of YAHOXDR files are as follows: Input Data Type Comments =============== ===================================== UBYTE Unsigned Bytes SHORT Signed Short Integers LONG Signed Long Integers FLOAT Floats CFLOAT Complex Floats (real, imag) CSHORT Complex Short Integers(real, imag) CLONG Complex Long Integers (real, imag) Output Data Type Comments =============== ===================================== UBYTE Unsigned Bytes SHORT Signed Short Integers LONG Signed Long Integers FLOAT Floats CFLOAT Complex Floats (real, imag) CSHORT Complex Short Integers(real, imag) CLONG Complex Long Integers (real, imag) For example, to output a YAHOXDR file using the float data type, the following could be used: ... -oformat YAHOXDR -otype FLOAT -o filename To input the file the following is used: -iformat YAHOXDR -i filename... .c.4.1.4 HDF Scientific Dataset File Format The HDF file format is another self-defining file type that supports multidimensional floating point arrays. It was developed by the software development group at NCSA and includes a library of subroutine calls that can access the files from the 'C' and FORTRAN languages. The primary advantage of HDF is its ability to move data between machines that use different internal representations of binary data. For, example, HDF supports automatic conversion between CRAY, IEEE and VAX floating point formats. Currently, HDF only supports floating point data types. To use viewit to read data from an HDF file: viewit -iformat HDF -i test.dat ... A HDF scientific dataset file format may be output with the following: ... -oformat HDF -o test.dat Viewit supports HDF scientific dataset types. This format are the default input and output file formats. Viewit support with the HDF library is required to use these functions. further information see: NCSA HDF User's Manual NCSA HDF Specification .c.4.1.5 FITS File Format The FITS file format is used primarily by the astronomical community for storing n-dimensional, regularly spaced arrays. The file format contains an ASCII header that specifies a number of parameters. Viewit searches this header for the NAXIS and BITPIX parameters as described by the FITS specification to determine the dimensionality and data type of a multidimensional array. To read a FITS file format file the following viewit command line could be used: viewit -iformat FITS -i test.dat ... Viewit does not support exporting of FITS files. For additional information on the FITS file format type see D.G. Wells, E.W. Greisen and R.H. Harten, "FITS: A Flexible Image Transport System," Astron. Astrophys. Suppl. Ser. 44, (1981) 363-370 Cray Note: The FITS file format is probably not supported. .c.4.1.6 SISCO Input File Format The SISCO file format is that supported by Spectroscopy Imaging Systems Corporation for use on their NMR imaging spectrometers. (Varian files will probably Data is usually stored as a one or two dimensional complex file that contains raw echo or fid data. Viewit will read the real part of the complex data to the ss1 register and the imaginary part to the ss2 register. For example, if the "np" vnmr acquisition parameter is set to 512 and the number of echos or fid's acquired is 301 using the "ni" vnmr acquisition parameter. The fid file could be read with the with the following: .c.; viewit -iformat SISCO -i test.fid ... The register stack would then be allocated as follows after execution of the -i function: ss1: 256 301 ss2: 256 301 ss3: ss4: .c.4.1.7 HDF Raster File Format NCSA supports a number of machine independent file formats that are primarily used for 2-D raster image data. HDF_RASTER_8 imports and exports 2-D raster datasets. HDF_RASTER_8 wlut provides the capability to store 2-D raster datasets with a color table that is stored as a 256x3 array in ss2. HDF_RASTER_24 provides support for 3x8bit RGB imagery where the data is imported and exported by a 3xnrowsxncols array in ss1. These file formats are primarily used for importing and exporting data between the NCSA software visualization tool suite (Image, Datascope, etc.) .c.5.0 Display Interfaces Viewit supports several interfaces to display multi-dimensional arrays as raster datasets using a variety of frame buffers and workstations. The simplest approach uses a file interface. Viewit is used to process data and to create an output file that is compatible with local raster display hardware and software. A higher level display interface, called the VR protocol allows viewit to remotely process and display data using a version of the telnet communications software that supports this protocol. Using this, a viewit command can be entered remotely and the results will be displayed on the local workstation without the necessity of file transfer. A higher level remote interface, called the VT protocol, uses a client/server process model and internet sockets between the viewit kernel and an interactive display tool environment. Viewit also supports the NCSA DTM protocol and the NCSA TK protocol. Viewit also supports basic raster display under X-windows. The display methods used in viewit are relatively simple and viewit has been modified to directly support a number of hardwired frame buffers. This approach usually provides the highest bandwidth channel between the frame buffer and the viewit process. However, the hardwired approach does not support a remote viewit process. .c.5.1 File Display Interface This interface is used to create an output file that is compatible with local display hardware and software. For example, the user's laboratory may have a commercial image processing and display system. The file output facilities of viewit are used to create a file that is compatible with the local display software. The NCSA software development group has developed several interactive workstation tools for basic display, layout and analysis of two-dimensional raster datasets. These tools have been developed for the Macintosh II, SUN workstations and IBM PCs. These tools are well documented and are available at little or no cost. More information on these tools can be obtained from: NCSA Technical Resources Guide .c.5.2 VR Display Protocol The Virtual Raster (VR) protocol was developed by the NCSA software development group for displaying raster images using a modified version of the telnet utility. Currently, versions exist for the Macintosh II and SUN Workstations that support the protocol. Using this utility, a user can remotely run viewit and directly display raster datasets at the local workstation. To use this protocol, the user starts the local telnet software and accesses the remote machine that is to run viewit. Viewit is then used to initially create a "raster window" on the remote machine, using the following: viewit -displ VR W xoff yoff xsize ysize The xoff and yoff parameters specify a pixel offset on the local workstation for a window of xsize by ysize to be created. For example, a 512x512 window starting at an offset of (64,64) in the local workstation environment, would be created using the following: viewit -displ VR W 64 64 512 512 The window has to be created only once. Raster data is then displayed to the window using the P parameter. For example, to then display a two dimensional array from an HDF format file called test.hdf: viewit -iformat HDF -i test.hdf -linscl 0.0 255.0 -displ VR P In this case, the data was first scaled between 0.0 and 255.0 to take advantage of the full 8 bit range of the raster window. -doff xoff yoff For example, the following would start the raster display at a location of (128,64) within the raster window: viewit -iformat HDF -i test.hdf... -doff 128 64 -displ VR P More information on the Virtual Raster protocol and the NCSA version of telnet that support this can be ordered from NCSA Technical Resources Catalog. .c..c.5.3 VT Protocol The VT protocol provides a high bandwidth remote raster display protocol currently supported. The VT protocol uses a client/server model and internet sockets to transfer data between a remote viewit client process and a local raster display server process. Prototype VT display server processes have been developed for the Sun Microsystems, Inc. workstations using the SunView environment (viewit_tool), the International Imaging Systems, Inc. IVAS frame buffer(ivas_tool), Sun Microsystems, Inc. TAAC-1 applications accelerator(button_boy, taac_tool) and Silicon Graphics Workstations using GL(vt, vt2). To use the VT protocol, first start the VT server process at the local workstation. For example, viewit_tool could be started within the SunTools environment from a workstation called bmrl and run as a background job with the following UNIX command line: viewit_tool >/dev/null & Then from within another window (shelltool, etc.), the user connects to the remote machine that is to run the viewit client kernel process using rlogin or telnet. A viewit command is then executed remotely using the VT protocol. For example, a two-dimensional array from an HDF format file called test.hdf would be displayed to the viewit_tool server process on the workstation named bmrl as follows: viewit -iformat HDF -i test.hdf -linscl 0.0 255.0 -displ VT bmrl The VT display protocol has only one parameter which is the network name of the workstation that has the remote server display process. The -doff function is provided to set a display offset within the raster display. The -doff function has two parameters with the following syntax: -doff xoff yoff For example, the following would start the raster display at a location of (128,64) within the raster window: viewit -iformat HDF -i test.hdf... -doff 128 64 -displ VR P .c.5.4 TK Protocol The TK protocol is used in conjunction with a Macintosh-II running NCSA Datascope V2.0. The protocol is used similarly to the VT protocol, where the user first starts Datascope as a server process on the Macintosh and then logs into the remote machine that is to run viewit. Viewit is initiated on the remote machine and data is passed directly to Datascope by specifing the internet name of the Datascope server Macintosh and the variable name to be used in Datascope. For example, a two-dimensional array from an HDF format file called test.hdf would be displayed to the datascope server process on the Macintosh with an internet address of 128.174.210.63 as follows: viewit -iformat HDF -i test.hdf -displ TK 128.174.210.63 test The data would be directly passed to datascope and given the variable name test within datascope. .c.5.5 DTM Protocol The DTM protocol allows viewit commands to be entered in a notebook on a local workstation running NCSA Image3. Viewit may be started remotely from within the Image3 calculations window using the startdtm() function. The -dtmwriteb function is used to return integer data to Image3. For example, the following was executed from within the calculations window in Image3. The startdtm command executes viewit from the /usr/unsupport/bin directory on a remote machine. When startdtm() is selected and the "enter" key is pressed the user is prompted for the remote machine name and user identification information. Using this, the user is essentialy connected to an interactive mode session of viewit through the calculations window of Image3. Data is returned to Image3 using the -dtmwriteb command in viewit. The dialog is shown as follows: startdtm("/usr/unsupported/bin/viewit") viewit V90.1 CP Development 11/19/90 -i /scr3/u11922/mouse_test.hdf -i /scr3/u11922/mouse_test.hdf DONE -linscl 0.0 255.0 -linscl 0.0 255.0 DONE -dtmwriteb -dtmwriteb DONE .c.5.6 X-Windows Display Protocol Viewit provides a basic raster display capability to support X-11 servers. For example, -displ X host_name will display to a X-11 server named host_name. Color tables may also be loaded with the following: -displ XLUT host_name .c.6.0 Limiting the Number of Operations Dimensions with -nopdim As discussed in Sec. 2.2.2 the number of operations dimensions can be restricted using the -nopdim function. This restricts the dimensionality of the functions to be performed. The -nopdim function has one parameter that specifies the number of operations dimensions. A specification of 0 resets the number of operations dimensions to include all the dimensions of the array. It is assumed that the operations dimensions are the leading dimensions of the array. For example, viewit -dim 3 100 100 25 -i filename \ (1) -nopdim 2 -linscl 0.0 255.0 \ (2) -nopdim 1 -nbhd median 3 \ (3) -nopdim 2 -reorder 1 0 \ (4) -nopdim 1 -nbhd median 3 \ (5) -nopdim 2 -reorder 1 0 (6) -nopdim 0 -stats (7) performs the following steps: (1) Input a 3 dimensional array that is 100x100x25 from a file called filename. (2) Restrict the number of operations dimensions to 2 and perform the linear scaling function 25 times for each 100x100 array. This will scale based on the maximum and minimum for each 100x100 array. (3) Restrict the number of operations dimensions to 1 and perform a one dimensional median filter on 2500 100 elements arrays. (4) Restrict the number of operations dimensions to 2 and transpose the 100x100 arrays 25 times. (5) Perform the one dimensional median filter on the other dimension (6) and transpose back to the original orientation. (7) Finally, remove restrictions on the operations dimensions to the whole array and compute univariate statistics using the entire 100x100x25 array. As currently implemented, the -nopdim function restricts the number of operations dimensions for functions that are monadic, real and retain dimensionality. Restricted operations dimensions for other classes of functions have limited support. .c.Appendix A: Application Notes .c.A.1 NMR Image Reconstruction using Fourier Imaging Techniques Background: NMR Fourier imaging techniques are used to encode the information for one direction on the imaging plane, by allowing the nuclear spins in the sample to evolve under the influence of a gradient pulse. To reconstruct an image from the Fourier Domain or "K" space, a Fourier transform could be used. Methods: The 2-D Experiment The Fourier transform functions within viewit are used to reconstruct an image from phase encoded FIDs. For example, consider that the user has used the SISCO system to acquire a two-dimensional phase encoded image with 256 phase encoding steps (ni=256) using slice selection techniques. Each fid is sampled 256 times (np=512). The SISCO file containing the fid data may be read with the following: viewit -iformat SISCO -i fid .... Memory will automatically be allocated for the registers as follows: ss1: 256 256 ss2: 256 256 To reconstruct the image, a two-dimensional Fourier transform of the complex FID data must be performed and the complex modulus of the absorptive and the dispersive terms may be taken. For example, the following macro could be used: viewit -iformat SISCO -i file.fid -ft complex fwrd CMOD \ -push -dcfilt 0.0 -mul -center The -dcfilt function and other filter operations can be used to overcome problems associated with offsets in the sampling of the FIDs. This would result in a bright or dark pixel in the center of the image that may cause display problems when the image is scaled for display. The 3-D Experiment Similarly, viewit may be used to reconstruct imaging data from a three dimensional imaging experiment. In this case, a three dimensional Fourier Transform must be performed. For example, suppose that an experiment uses 64 phase encoding steps in the X direction for every one of 64 y phase encoding steps. A total of 4096 FIDs are acquired and suppose that each fid is sampled 64 times. The SISCO file could be read with the following: viewit -iformat SISCO -i file.fid Because, the SISCO file system does not have a mechanism for recognizing multidimensional arrays the registers would be initially allocated as follows: ss1: 64 4096 ss1: 64 4096 To perform a three dimensional Fourier transform on the data the data must be first redimensioned as a three dimensional array as follows: viewit -iformat SISCO -i file.fid -dim 3 64 64 64 \ -xchg -dim 3 64 64 64 -xchg \ -ft complex fwrd CMOD -push -dcfilt 0.0 -mul -center Except for the redimensioning, the reconstruction is exactly the same as the two dimensional experiment. The 4-D Experiment Viewit can be used to reconstruct a four dimensional chemical shift imaging experiment. For example, assume that a 32x32x32x32 array is to be reconstructed. As in the 3-D experiment the array must first be redimensioned if the SISCO file system is used. viewit -iformat SISCO -i file.fid -dim 4 32 32 32 32 \ -xchg -dim 4 32 32 32 32 -xchg \ -ft complex fwrd CMOD -push -dcfilt 0.0 -mul -center The 2-D Multi-Slice Experiment Multi-slice imaging can be considered as sets of acquisitions collected in one experiment that result in a three dimensional array. A series of two-dimensional Fourier transforms must be performed on the set of slices. The -ft2d can be used to restrict the Fourier transform operation to the leading two dimensions in the three dimensional array. For example, consider that 10 256x256 slices are acquired. Viewit may be used to read a SISCO file as follows: viewit -iformat SISCO -i test.fid In this case, the SISCO file system considers this an "arrayed" experiment and memory would be allocated as follows: ss1: 256 256 10 ss2: 256 256 10 The -ft2d function can be used to perform 10 two-dimensional Fourier transforms as follows: viewit -iformat SISCO -i test.fid -ft2d complex fwrd POLAR \ -push -dim 2 256 256 -dcfilt 0.0 -duplicate 10 -mul \ -translate 128 128 0 -interlace The -dcfilt function is used to create a three dimensional array of 10 256x256 two-dimensional "DC" filters. Only two dimensions are translated, instead of three by using the -center function. Finally, the odd and even slices are interlaced using the -interlace function. References SISCO Operators Manual, Spectroscopy Imaging Systems Corporation, October, 1987 P. Mansfield and P.G. Morris, 1982, NMR Imaging in Biomedicine, (Orlando, Fla.: Academic Press, Inc.), pp. 117-122. .c.A.2 Signal Enhancement Techniques Using Fourier Domain Filtering Background: Signals can be conditioned using Fourier domain filtering techniques. For example, an image could be low-pass filtered to remove noise at high frequencies resulting in a "smoothing" of the images. Likewise, low frequencies could be high-pass filtered to "sharpen" edges or a specific range of frequencies could be modulated using a band-pass filter. Methods: Viewit is first used to transform a signal to the Fourier domain where multiplication by the filter function is performed. Finally, an inverse Fourier transform is used to transform the data back to the original domain. For example, the following could be used to low pass filter a multi-dimensional real signal using a Butterworth Low-Pass filter. viewit -i file.test -ft real fwrd REAL -push \ -blpf 0.2 2 -mul -xchg -pop -xchg -push -blpf 0.2 2 -mul \ -xchg -pop -xchg -ft complex back REAL This procedure will read a multi-dimensional real signal to the ss1 register and then perform a forward Fourier transform resulting in a complex result in the Fourier domain. The real part is contained in the ss1 register and the imaginary part is contained in the ss2 register. Multiplication of the real and imaginary parts by a second order Butterworth low-pass filter with a cutoff of 0.2 is performed by manipulating the stack. Finally, an inverse Fourier transform is performed on the complex data. Because of the implementation of the Fourier Transform within viewit, the data will be returned multiplied by a factor of the number of elements in the original multi-dimensional array. This procedure will operate on arrays of any rank. References: W.H. Press, B.P. Flannery, S.A. Teukolsky and W.T. Vetterling, 1986, Numerical Recipes: The Art of Scientific Computing, (New York: Cambridge University Press), pp. 381-453 .c.A.3 Three-Dimensional Projection Reconstruction using the Direct Filtered Back Projection Method for NMR Applications Background: The filtered three dimensional back projection is one method for reconstructing three dimensional datasets from one dimensional spatially resolved NMR spectra that are resolved by imposing a small linear gradient on the main magnetic field. By altering the direction of the gradients, projections or views of the object can be obtained in different directions. Projection reconstruction addresses the problem of recovering the object from the set of projections. Methods: In this procedure the filtered back projection method will be used to reconstruct three dimensional datasets from raw FID or ECHO projection data as generated by the SISCO NMR imaging system. The general outline for the procedure is as follows: 1.) Create the projections from raw FID or echo data. This procedure is essentially the same as reconstructing an NMR spectra. For example, phase correction can be performed after Fourier transformation and base line correction of the FID or ECHO data. 2.) Filter the projections using a 3 point second difference filter. 3.) Load the angle table that contains the acquisition geometry and direction of the gradient for each projection. 4.) Back project the filtered projections. For example, suppose that 3542 FIDS or echos are acquired by rotating the gradient as in figure 3.11.2 according to the angles defined by theta and phi. The gradient geometry is stored in an ASCII flat file with five columns. The first column is the theta angle and is followed by the phi angle value in radians. The remaining three columns express the actual DAC values used to adjust the gradient orientations for the X, Y, and Z directions. These are not needed for the actual reconstruction procedure. Now suppose a SPIN echo pulse sequence has been used to collect the echos which are sampled 512 times for both the real and imaginary parts ( SISCO parameter np=1024). The zeroth order phase correction parameter (RP) has been determined to be 142.52 degrees and the first order term (LP) is 0.0. To reconstruct the entire valid normalized reconstruction space the following could be used: viewit -iformat SISCO -i echo.fid \ (1) -filt1d BLC 64 -chunk 0 0 64 3542 -filt1d LAI -xchg \ (2) -filt1d BLC 64 -chunk 0 0 64 3542 -filt1d LAI -xchg \ (3) -ft1d complex fwrd REAL \ (4) -translate 32 0 -xchg -translate 32 0 -xchg \ (5) -phase_correct_1 142.52 0.0 \ (6) -filt1d 2DIFF -push \ (7) -dim 2 5 3542 -iformat RAW -itype ASCII -i angle \ (8) -chunk 0 0 2 3542 -xchg \ (9) -bkproj_3d_fast 64 64 64 1.0 1.0 1.0 LINEAR \ (10) -oformat HDF -o vol3d.file (11) The steps performed by this macro are: (1) Read complex echos from SISCO file named echo.fid. The registers are allocated as follows: ss1: 512 3542 ss2: 512 3542 (2) Perform base line correction of the real part of the echo by subtracting the mean of the last 64 points from every point in each echo. Low pass filter the echos to avoid alliasing by oversampling the projection in the time domain by selecting only the first 64 samples and then window using a cosine window (This is equivalent to a Hanning Low Pass Filter). Exchange the ss1 and ss2 registers. (3) Perform the same operations as (2) on the imaginary part of the echo. The registers are now allocated as: ss1: 64 3542 ss2: 64 3542 (4) Perform a complex one-dimensional Fourier transform on the echos. (5) Center each of the complex projections. (6) Phase correct the projections. (7) Filter the projections by convolving with a 3 point second difference filter and push the stack down to (8) load the ASCII angle table from file angle. (9) Get rid of the last three columns in the angle table. The back projection algorithm requires the size of the leading dimension in angle table be 2. Exchange the ss1 and ss2 registers. The registers are now allocated as follows: ss1: 64 3542 ( Filtered Absorption Projection) ss2: 2 3542 ( Angle Table) ss3: 64 3542 ( Dispersion Projection - Not used). (10) Perform the back projection to a 64x64x64 array with a "zoom" factor of 1.0 and use linear interpolation. After back projection the registers are allocated as follows: ss1: 64 64 64 ( Reconstruction Volume ) ss2: 2 3542 ( Angle Table ) ss3: 64 3542 ( Dispersion Projection ) (11) Write the reconstruction volume to a file named vol3d.file using the HDF file format. To "zoom" by a factor of 2.0 the following could be used: viewit -iformat SISCO -i echo.fid \ (1) -filt1d BLC 64 -chunk 0 0 128 3542 -filt1d LAI -xchg \ (2) -filt1d BLC 64 -chunk 0 0 128 3542 -filt1d LAI -xchg \ (3) -ft1d complex fwrd REAL \ (4) -translate 64 0 -xchg -translate 64 0 -xchg \ (5) -phase_correct_1 142.52 0.0 \ (6) -filt1d 2DIFF -push \ (7) -dim 2 5 3542 -iformat RAW -itype ASCII -i angle \ (8) -chunk 0 0 2 3542 -xchg \ (9) -bkproj_3d_fast 64 64 64 2.0 2.0 2.0 LINEAR \ (10) -oformat HDF -o vol3d.file (11) Note: The function -filt1d 2DIFF, as currently implemented, produces a result with the wrong sign. This results in a normalizes reconstruction value that also has the wrong sign. -chs may be used to rectify this. References: SISCO Operators Manual, Spectroscopy Imaging Systems Corporation, October, 1987 P. Mansfield and P.G. Morris, 1982, NMR Imaging in Biomedicine, (Orlando, Fla.: Academic Press, Inc.), pp. 133-142 C-M. Lai and P.C. Lauterbur: A gradient control device for complete three-dimensional nuclear magnetic resonance zeugmatographic imaging. J. Phys. Sci. Instrum., 13 pp. 747-750 (1980) NMR in Medicine and Biology pp. 123-154. .c.A.4 Exploratory Visualization of 3-D Datasets using Volume Rendering Techniques Background: Methods: Ray casting techniques used in volume rendering are a form of dimensionality reduction. The -reduce operator in viewit can be considered as a primitive operator for this technique. The appropriate method of dimensionality reduction is highly dependent on the nature of the object to be rendered. Two commonly used methods are finding the maximum value along a ray and calculating a weighted sum along a ray. These techniques are equivalent to using the -reduce ceil and -reduce add functions. To use the ceiling reduction technique to render a view along dimension 0 of a 64x64x64 array contained in the file cube, the following could be used: viewit -i cube -reduce ceil The ray cast could be weighted as a function of distance along the ray from the observer. This is equivalent to multipling the cube by a one dimensional weighting function as follows: viewit -i cube -push -filt1d LAI -mul -reduce ceil Multiple views of the array can be obtained by rotating about the dimension 2 using the -rotate function. For example, viewit -i cube -rotate 0 20.0 -filt1d LAI -mul -reduce ceil would rotate the cube 20 degrees before "depth" weighting and ceiling reduction. A movie of the rotation can be made by performing the above function for a number of rotation angles. This techinique is available using the -movie function. .c.A.5 Principal Components of a Multivariate Array Background: This application demonstrates the use of the matrix functions in viewit to determine the principal components of a multivariate array. Methods: The following technique will be used to determine all of the principal components of a multidimensional, multivariate array. For example, the following would determine the principal components of a 64x64 array with 18 variables. viewit -dim 3 64 64 18 -i file -dim 2 4096 18 -push \ (1) -covarmat \ (2) -eigen vector \ (3) -matmul \ (4 -dim 3 64 64 18 -o outfile (5) (1) A 64x64x18 array is loaded to the ss1 register and redimensioned as a 2D matrix with 18 variables. The array is pushed down the stack for use during the matrix multiplication step (4). (2) The 18x18 covariance matrix between the variables is calculated. (3) Determine all eigen vectors of the correlation matrix. (4) Matrix multiplication of linear combinations determined by eigen vectors by variables. (5) Redimension array to 64x64x18 after matrix multiplication. 18 principal components are returned in the variable dimension in ascending order of significance ( [*,*,17] is most significant).