Pink 0.9

Conventions for developing Pink operators

This page describes the function format for the Pink Image Processing Library


To facilitate development, particularly to facilitate others understanding/improoving your code we use general guidelines for the functions in Pink. These guidelines ease particularcly the front-end development, as less types there are less templates are necessary. If your functions could be transformed in one of the declared formats, it should be. If, however your function cannot respect any of the known formats (for example, the size of the result image is different than the size of the input image), feel free to omit them.

Programming Languages

Pink functions can be written in C, C++ and Python. Scripts written in Tcl or Bash are discouraged as they make the library more difficult to use and to compile/port. Also except for the Python documentation generation (which is done by a Python script) you should not invoke any script of any language during the compilation. This concerns yacc/bison/lex/flex, sed, swig or any preprocessing languages. These languages would make the compilation more complex, and would obligate the potencial developper to learn and master more and more programming/preprocessing languages.

Image types

Pink deals mostly with black and white images, but color images are also supported, at least as a format. The main image structure is xvimage. In C++ xvimage is represented by the ujoi<pixel_type> object. ujoi<> can be converted (casted) in xvimage* in constant time and memory, so C++ functions can call C without penalties. There are some shortcuts to image types. At the time of writing the following image types exist in Pink:

struct xvimage; // represents all the supported image types in C format

class ujoi<unsigned byte>  <=> char_image     // represents a byte image
class ujoi<unsigned short> <=> short_image    // represents a short image
class ujoi<int>            <=> int_image      // represents a int image
class ujoi<float>          <=> float_image    // represents a float image
class ujoi<double>         <=> double_image   // represents a double image
class ujoi<fcomplex>       <=> fcomplex_image // represents a complex image
class ujoi<dcomplex>       <=> dcomplex_image // represents a complex image

General conventions

C functions

To avoid incompatibilities between C and C++ the C functions should not allocate memory for the result image. Three types of C pink operators are declared. These functions are automatically wrapped to Python. For non conventional functions an additional C++ wrapper function has to be written.

C++ functions

Pink functions written in C++ should use the functional paradigm. That is they should have only constant parameters, and return a value or an image. If they need to return more then one value as a result, they should definitely use 'struct' instead of modifying the paremeters:

result_type pink_cpp_function( const T0 t0, const T1 t1, ..., const Tn tn )

There are several things to note about this declaration:

The function should test the images on the input. If it can, for example, only work with 2D images, it should test the dimensions of the input at the beginning. In the case that the image detects an error it should call the 'error' macro, with the most complete description of the errors detected. The error macro declaration can be found in the beginning of the c++ functions.

Python scripts

Python scripts are called directly from python. These scripts should respect the format of the wrapped function to simplify the utilization of the library. Generally a python function looks like:

def pink_python_function(t0, t1, t2, ..., tn)

If there is an image parameter, t0 should be an image parameter. In the end the functions should return the result with the 'return' statement. Possible errors should be raised.

ujoimro, 2011