Documentation

1. Starting new block
2. Implementing the block
3. Internal parameters
4. IO Types
5. Available macros and methods

Starting new block

1. The blocks are written in C++ and compiled and linked into a shared, dynamically linked library.
2. The best way to start, is to use a perl script, available in ##blocks/util/XaiBlock2HTML## directory - ##create_block.pl##
3. The script requires two things: a block specification file and a template directory. The latter can be found in ##blocks/util/BlockTemplate##. Just copy the template directory to a place where You want to work on Your block.
4. The block specification file is a little more cumbersome. Here is an example specification (covering all possible options):

   block IPLSmooth { path = "/OpenCV"; description = <<"MAINDESC" The function cvSmooth smooths image using one of several methods MAINDESC inputs = [ { name = ipl_image; description = ""; type = IOOpenCVIPL } ]; outputs = [ { name = ipl_image; description = ""; type = IOOpenCVIPL } ]; parameters = [ { name = smoothtype; description = "Type of the smoothing"; type = EnumParameter; values = { CV_BLUR_NO_SCALE = CV_BLUR_NO_SCALE; CV_BLUR = CV_BLUR; CV_GAUSSIAN = CV_GAUSSIAN; CV_MEDIAN = CV_MEDIAN; CV_BILATERAL = CV_BILATERAL; }; default = CV_BLUR_NO_SCALE }, { name = param1; description = "The first parameter of smoothing operation"; type = IntegerParameter; default = 3; }, { name = param2; description = "The second parameter of smoothing operation"; type = IntegerParameter; default = 0; } ]; }

Implementing the block

1. The constructor

   This constructor was automatically generated simply from the above specification.

   IPLSmooth::IPLSmooth() { name = "IPLSmooth"; path = "/OpenCV/Image_Processing_and_Analysis/"; description = "The function cvSmooth smooths image using ..."; inputs.clear(); outputs.clear(); // Inputs addInput(Input("ipl_image", "", new IOType<IplImage>())); // Outputs addOutput(Output("ipl_image", "", new IOType<IplImage>())); // Parameters EnumParameter* par0 = new EnumParameter("smoothtype"); par0->setValue("CV_BLUR_NO_SCALE"); par0->addValueForKey("CV_BLUR", CV_BLUR); par0->addValueForKey("CV_BLUR_NO_SCALE", CV_BLUR_NO_SCALE); par0->addValueForKey("CV_GAUSSIAN", CV_GAUSSIAN); par0->addValueForKey("CV_MEDIAN", CV_MEDIAN); par0->addValueForKey("CV_BILATERAL", CV_BILATERAL); addParameter(par0); IntParameter* par1 = new IntParameter("param1", 3); addParameter(par1); IntParameter* par2 = new IntParameter("param2", 0); addParameter(par2); output_image = NULL; }

2. The run() method

   This method is more tricky, since it contains the logic of the block. If the method needs to maintain state between the calls (iterations of algorithm) the variables representing the state must be declared as private fields of the class in the blocks header file. It is best to keep the code of this method as optimal as possible. Especially such things as memory allocation or initialization should be done only when necassary (preferably once). For instance the first block of this method, allocates a new IplImage structure. Note, that it cannot be done before the actual execution of the algorithm, since otherwise we wouldn't know some of the parameters of the actual input data, such as size or depth. If the block that provides this input is for instance a AVI file reader, this block will adapt to its resolution and depth. Next step is the extraction of input data from the inputs. This will be more detailed in the section on the type system of Xai, for now, we can see that we have to take the input we want using simple index (inputs is a std::vector object). The input has a pointer to the output that is connected to this input and from this output we can extract the interesting information. After we have input data, we can extract current values of internal parameters of the block. There exists only a limited amount of parameter types, so some convienience macros are defined to help with there extraction. When we have the inputs and parameters we can now perform the actual operation of the block, here it is simply the cvSmooth() method from OpenCV library. Finally, we assign the obtained result to the proper outputs of the block. When the method is finished, the blocks that wait on this output will be able to use it.

   void IPLSmooth::run(void) { // // Get the input image // IplImage* input_image = GET_INPUT_DATA(IplImage, 0); // // Create new image with proper parameters depending on input image // if(!output_image_created) { CvSize input_img_size; input_img_size.width = input_image->width; input_img_size.height = input_image->height; int depth = input_image->depth; int nchannel = input_image->nChannels; output_image = cvCreateImage(input_img_size, depth, nchannel); XAILOGCPP(XAIINFO, getName()<<": Creating output image "); output_image_created = true; } // // Get internal parameter values // int smoothtype = GET_ENUM_PARAM_VALUE("smoothtype"); int param1 = GET_INT_PARAM_VALUE("param1"); int param2 = GET_INT_PARAM_VALUE("param2"); // // Perform the operation // cvSmooth(input_image, output_image, smoothtype, param1, param2); // // Assign the output data // SET_OUTPUT_DATA(IplImage, 0, output_image); }

3. The reset() method

   The reset() method is called when the algorithm is stopped. So in order to avoid memory leaks in the blocks, each block should release all memory that he allocated in method run().

   void IPLSmooth::reset() { output_image_created = false; if(output_image != NULL) { cvReleaseImage(&output_image); output_image = NULL; } }

Internal parameters

Input and Output types

Available macros and methods