Programming with VisionX File Functions

VisionX programs that are developed with the structured VisionX programming tools usually have the following structure:

1.

Declare global variables and VisionX file structures

2.

Define the prefixes for the command line parameters

3.

Start main program: parse command line and open files

4.

Main program body

5.

Close data files and exit

A basic VisionX program that illustrates all the main features of the structured VisionX programming tools is shown in Figure 1. Since this structure is similar for most VisionX programs, the example program may be used as a template for developing other programs.

 

Figure 1: Example VisionX program  

Any VisionX program should be able to deal with any VisionX file, and should accept the flexible VisionX command line structure. The following code walk through illustrates the five stage framework that is used in all structured VisionX programs.

1. Global declarations

Specify the VisionX include file and declare VisionX file structures.
The VisXV4.h file is required for every VisionX program Vutil.h is an optional file that contains a number of useful macros and various standard include files such as stdio.h, math.h and string(s).h.

#include "VisXV4.h"     /*  VisionX structure include file    */
#include "Vutil.h"      /* useful macros, stdio.h etc.        */
                        /*                                    */
VisXfile_t *VXin,       /* input file structure               */
           *VXout;      /* output file structure              */
VisXelem_t *vxlist;     /* VisX data structure                */

In general, every file is associated with a file structure ``VisXfile_t *'', also a data list ``VisXelem_t *'' is used to hold the data read from or to be written to files.

2. Command line parameters

Define the prefixes for the command line parameters.
The par structure contains a prefix, a value and a brief description for each command line parameter. Both positional (without prefix) and prefix spefication of command line parameters is supported. By convention "if=" specifies the primary input file and "of=" specifies the primary output file.

VXparam_t par[] =         /* command line structure      */
{
{   "if=",    0,          "input file  vcp: file copy"},
{   "of=",    0,          "output file"},
{   "-f",     0,          "frame-i/o option"},
{    0,       0,          0}, /* list termination */
};

#define  IVAL   par[0].val
#define  OVAL   par[1].val
#define  FFLAG  par[2].val

Each prefix is specified by two statements. For example, the string matched to the "of=" command parameter is referred to by OVAL in the program. The VXparse subroutine parses the command line and sets the .val elements of the par data structure to the text strings associated with the matched parameters. If the user does not specify the "of=" parameter then OVAL is set to a NULL string by VXparse.

3. Main program initialization

Parse the command line and open files.
The second argument to VXopen specifies if a file is to be opened for reading(0) or writing (1).

main(argc, argv)
int argc;
char *argv[];
{

    VXparse(&argc, &argv, par);   /* parse the command line   */
    VXin  = VXopen(IVAL, 0);      /* open input file          */
    VXout = VXopen(OVAL, 1);      /* open the output file     */

4. Main program body

There are two modes of processing VisionX files. Either the whole file may be read into a list structure or file "frames" may be read one at a time. The vcp program illustrates both of these modes. For complete file i/o the structure is:

     vxlist = VXread(VXin);    /* read data                  */

          /* do any modifications to vxlist or create     */
          /* a separate list for output                   */

     VXwrite(VXout, vxlist);   /* write data                 */

To process the data file one frame at a time the structure is:

     while ((vxlist = VXreadframe(VXin)) != VXNIL){
                                   /* for each frame read     */ 
         VXfupdate(VXout, VXin);   /* update global constants */
           /* do any modifications to vxlist or create   */
           /* a separate list for output                 */
         VXwriteframe(VXout,vxlist); /* write frame           */
         VXdellist(vxlist);          /* delete the frame      */
     }

In this case a new vxlist is created with each call to VXreadframe. Any global constants that are to be used for all frames are maintained in a list VXflist(VXout). The VXupdate command ensures that this list is maintained with any new global information that is extracted from the input file with the call to VXreadframe.

5. File closing and exit

Any well written program should close all opened files and exit with exit(0).

    VXclose(VXin);             /* close input file           */
    VXclose(VXout);            /* close output file          */
    exit(0);
}