How to Write an AVS/Express Module

AVS/Express allows the user to write his/her own modules and use them together with the build-in library modules. Express provides three API's: C, C++ and FORTRAN to write the code. The example in this tutorial will use the C API.

I will write a module that reads a Uniform Field of floats and converts it to byte. The input parameter is InField and the output is OutField.

Step 1

Unzip and un tar the file express_module.tar.gz that has the basic directory structure I always use for my express projects. cd to the express_module directory.

Step 2

Start express. When it asks you to choose and initial application type, choose the default, Single-window DataViewer 3D. A Single-window application will pop up.

Step 3

From the main express window (network editor), go to the "Libraries" pull down menu and select Library Workspaces. Click on one of the workspaces. It will turn blue (selected). From the main menu go to the Object pull down menu and select "Add Module". The "Add Module" GUI will pop up. Change the name of the Object name to "Convert2Byte" and select the "C function" from the Add method frame. Click on Add. A method will be added. Name it "Convert2Byte" and name the C function, convert2byte_update. Click on Done. Select Next.

We will now add an input parameter "InField"

Select "other" from the Type pull down menu. Then go the the network editor window and select Accessories from the Libraries Menu. Click on the "Field Unif" module of the "Field Schema" library folder. In the Add Module GUI you will see that it will have the "Templates.NELIBS.NE_DV.Field_Schema.Field_Unif" selection added (clicking on the module makes this!, so don't click on anything else!). Click on Add. Rename it to InField. Select "Object is an exported parameter", select "By referenc &" in reference mode. This will enable the "Display input port" toggle button, select it. Click on Next Select "notify, read and req" from the selection frame. Click on Done.

Now we will add and output parameter "OutField".

Click again on the "Field Unif" module of the "Field Schema library folder. You will see again the type "Templates.NELIBS.NE_DV.Field_Schema.Field_Unif". Click Add. Change the name to OutField. Leave the reference mode as "By value". Select "Object is an exported parameter" and "Display output port". Click on Next, Select the "write" toggle button and Click on "Done".

Click on Next. The Final GUI of the Add Module process with appear.
For the "Process in which the object resides, select "user". Name the source filename: convert2byte.c. In Advanced properties build_dir type: $XP_PATH<1>/lbl_proj/convert2byte/c_src_files (note that this directory has to exist already). The Edit Source button should be enabled by this time. Click on it. Express will pop up a GUI saying that the files does not exist yet and will ask for your agreement in creating it. Say yes. A separate window with C code will appear. Save the code. Select Done in the Add Module GUI.

Now you will save the module.

Go back to the network editor, Library Workspaces and click on the Convert2Byte module you created. It will turn blue. From the Object meny select Save Objects. Save the Object in lbl_proj/convert2byte directory with a temporary name like: convert2byte_mods.v
At this moment all your work has been saved.

Now you can go to the lbl_proj/convert2byte directory and add a module to the library modules, so the next time you start express it will see it.

Edit convert2byte_mods.v

Add the following lines:

flibrary Convert2ByteMods {
module Convert2Byte<process="user",src_file="convert2byte.c",build_dir="$XP_PATH<1>/lbl_proj/convert2byte/c_src_files"> {
   omethod+req Convert2Byte(
      .InField+read+notify+req,.OutField+write) = "convert2byte_update";
   Field_Unif &InField;
   Field_Unif OutField;
};
};

Save this file again.

Create a new file named convert2byte.v with this content:

flibrary Convert2Byte{
	"../lbl_proj/convert2byte/convert2byte_mods.v" Convert2ByteMods;
};
Save this file.

Edit the lbl_proj/lbl_proj.v file and add a line
	"../lbl_proj/convert2byte/convert2byte.v" Convert2Byte;

To see your module in the LBL_PROJ library, first close Express (it reloads the new modules with it starts). Select "None" as your application. From the Network Editor Libraries Pull down menu select the Templates Library. On the right of the Libraries LBL_PROJ will appear.

Step 4

The next step is to fill in the code with the C API.