You are designing a module that will select one data variable, or channel, from an array that has a number of data variables. Arrays in Explorer are called lattices. The module is a simple selector with no limits on the range, and uses only float data. Here is a brief description of the structure you need in the new module, which you will call ChannelSelector.

It should take in all the data variables from the input lattice and put out values for only one data variable. It should have a widget for selecting a particular data variable. It needs an input port, an output port, some defined variables for the lattice data and coordinate values, and a computational function to select out the data values for a specific channel.

The example shows how you can create a channel selector module with a C function or a Fortran subroutine. The module accepts input data in the form of an Explorer lattice. You need not be concerned with lattices now, except to note that as a matter of convention, the variable names in this function correspond closely with the variable names in the cxLattice data type structure.

To find out more about lattices, read Chapter 3, “Using the Lattice Data Type.”

   long sizes(long,long *);

   channel(long nDim, long *dims, long *nDataVar, long which,
   float *dataIn, float *dataOut)
{
   int i,numElems,sel;
      numElems = sizes(nDim,dims);

/* use a legal range for the data */

    sel = which;
    if(sel < 0){
    sel = 0;
    else if(sel >= (*nDataVar)){
    sel = (*nDataVar)-1;
 }

/* copy the data */

  for(i=0;i<numElems;i++){
  dataOut[i] = dataIn[i*(*nDataVar)+sel];
 }
 *nDataVar = 1;
}

   long sizes(long nDim,long *dims)
{
  long foo,i;
  foo= 1;
  for(i=0;i<nDims;i++)
  foo *= dims[i];
    return(foo);
}

c
  subroutine channel(ndim,dims,nvars,which,datain,dataout)
  implicit none
  integer nvars,ndims
  real    datain(nvars,1),dataout(1)
  integer dims(ndims),which
  integer numElems,i,j,sizes
c
   numElems = sizes(ndims,dims)
c
   j = min(max(1,which),nvars)
c
   do i=1,numElems
      dataout(i) = datain(j,i)
   end do
c
   nvars = 1
   return
   end
c
c
    integer function sizes(ndims,dims)
    implicit none
    integer ndims,dims(ndims),i
    sizes = 1
    do i=1,ndims
       sizes = sizes * dims(i)
    end do
    return
    end

The method for building modules is the same for both languages, although some of the information you enter varies according to whether the user function is written in C or Fortran. Because the similarities are so great, this tutorial presents the process for users of both languages together. Where the activities for the two language diverge, the differences are clearly marked and parallel instructions are given for each language.

Make sure you are in the testMod directory, then start up the Module Builder:

mbuilder

The Module Builder main window appears (see Figure 1-1 and Figure 1-2). Click in the Module Name slot to select it and delete the default, then type in the module name ChannelSelector. In the next slot, enter the name of the file that contains the user function:

You can also specify include files, additional libraries or your own Makefiles, but none are required for building the ChannelSelector module. To learn more about these options, read through“The Include Files” and “User Makefiles” in Chapter 2.

Figure 1-1. The Module Builder Window for C Users

Figure 1-2. The Module Builder Window for Fortran Users

The Module Builder creates a number of files as you go through the construction process. The Module Builder automatically saves all the module characteristics, or resources, that you have just specified in the module resource (.mres) file before it builds the module. This is a binary file and cannot be accessed directly.

You can use “Save Resources” on the File menu to save your work at any time during the module construction phase. It is a good idea to save your work periodically if you expect to be interrupted or if you are building a very complex module.

To quit the Module Builder at any time once it has been invoked, click on the File menu on the main window and select “Quit” (see Figure 1-3).

Figure 1-3. Module Builder File Menu

Click on the first button, Input Ports, to bring up the Input Ports window (see Figure 1-4).

---

Note: The window is initially displayed with only one text slot. Click on the slot to highlight it and press <Enter> to produce a new text slot.

---

The module requires an input port that will accept data in the form of the lattice data type.

Click the Output Ports button to bring up the Output Ports window (see Figure 1-6). The module needs an output port so that it can pass the data from the selected channel downstream to the next module.

Figure 1-6. The Output Ports Window

To create the output port:

For more information about input and output ports, read “Creating Ports” in Chapter 2.

The Function Arguments window defines each function argument in the user function. Each function argument must be connected to an input or output item. You list the function arguments in their calling sequence, as shown in Figure 1-8 and Figure 1-9.

To define the function arguments:

For more information about the data types and reference mechanisms, read “Defining Function Arguments” in Chapter 2.

These are the function arguments for the C function

These are the function arguments for the Fortran subroutine.

Figure 1-8 shows the argument names, data types, and references you enter if you are building your module around the C user function.

Figure 1-8. The Function Args Window for C Users

Figure 1-9 shows the argument names, data types, and references you enter if you are building your module around the Fortran user function.

Figure 1-9. The Function Args Window for Fortran Users

Each port must be connected with one or more function arguments, so that the incoming data can be routed to the correct function argument and the outgoing data can be directed to the correct output port.

The connections are identical for C and Fortran user functions.

To break a connection, simply click on both ends of the connection, as in the Map Editor.

The popup menu in Figure 1-11 shows one connection from the input port (top-level Lattice Structure) to the output port.

Figure 1-11. Input Port Popup Menu

It also shows four connections from lattice components, such as the number of dimensions (Num Dimensions), to function arguments. The Output port has three connections passing into it, although the port menu is not shown. The details of the data type structures are explained in Chapters 3 through 7.

Making the Right Connections

The correct connections are critical to the proper operation of the module. In this example, the values affected by the function arguments are passed separately to the lattice structure on the output port. The values for all members of the lattice data type not explicitly linked to function arguments are passed directly from the input port to the output port as default values.

For more about connecting ports and function arguments, read “Connecting Arguments to Ports” in Chapter 2

To build the Channel module correctly, you must make these connections. They are the same for the C and the Fortran modules.

Input		Lattice Structure to port Output: Lattice Structure Num Dimensions to argument nDim Dimensions Array to argument dims (switch off Copy by pressing the yellow button) Num Data Variables to argument nDataVar Data Array to argument dataIn
Which		Value to argument which (see option menu on right)
<<Storage>>		“Select” to argument dataOut, then set the storage value (see Figure 1-12 or Figure 1-13).
nDataVar		“Select” to port Output: Num Data Variables
dataOut		“Select” to port Output: Data Array

Using the Pseudoports

<<Storage>>, <<Constant Value>> and <<Extern>> are “pseudo-ports.” When you connect one to a function argument, you use the second item on the function argument popup menu (shown on the left) to define the value for the pseudo-port. In this example, you need to define the storage value. The value is different for C and Fortran modules.

To set the storage size for dataOut, click the menu item “Set storage size” and enter the text shown in Figure 1-12 and Figure 1-13 for the C and Fortran modules respectively. There is a default setting which you should delete first.

This text is expected by the code that the Module Builder generates when the module is built. In this example, a routine is called to compute the number of floating (C) or real (Fortran) values that must be allocated for the dataOut function argument.

Figure 1-12. Setting Storage Size for C Users

Figure 1-13. Setting Storage Size for Fortran Users

You can enter comments after the values if you wish, to remind you and explain to others why you chose this value.

When you have filled in all the popup windows and made all the connections you need, click OK to save the configuration and close the window.

You can create your own menu bar options for the module control panel. For this module, you will create a File menu with a “Quit” option.

You can click on the Control Panels button to bring up the prototype control panel again. You will see that it now has a File menu on its menu bar. Click File to see the “Quit” option.

This completes the construction of the module. The next stage is to build the module and install it in Explorer so that you can use it in a map.

The Module Builder Build menu provides lets you set defaults and build the module. To check the build options for the Channel module, select “Options” from the Build menu. The Build Options window appears (see Figure 1-17).

Figure 1-17. Build Options Menu

You want to accept all the current defaults. You want the Module Builder to:

Click OK to accept the default options and close the window.

For more information about build options, read “Using the Build Menu,” in Chapter 2.

The Build command is on the Build menu (see Figure 1-18).

You can now run the Map Editor by typing explorer at the shell prompt, and launch the ChannelSelector module from the Module Librarian.

To see how it works, connect these modules: ReadImg to Channel to DisplayImg. Read in the image file /usr/explorer/data/image/flowers2.rgb and select each of the color channels, 1 to 3, in turn.