This time we try to improve the code for the general 2D convolution routine. Three versions were compared for the convolution of a 2048x2048 image with a 5x5 kernel:

• a naive convert+macro based routine
• the routine from megawave 3
• a modified version, using only pointer arithmetics in the inner loop

I used the same simple profiling tools as before, with gprof:

• convol.c
• convol.h
• bench.c

measures

without compiler optimization

 %   cumulative   self              self     total           
time   seconds   seconds    calls   s/call   s/call  name    
39.33     25.36    25.36       10     2.54     2.54  _convol_macro
33.48     46.95    21.59       10     2.16     2.16  _convol_old
25.20     63.20    16.25       10     1.62     1.62  _convol_pointer
 1.99     64.48     1.28                             main
 0.00     64.48     0.00       30     0.00     2.11  convol

• full gprof output

with compiler optimization

 %   cumulative   self              self     total           
time   seconds   seconds    calls   s/call   s/call  name    
46.85     10.47    10.47       10     1.05     1.05  _convol_macro
26.35     16.36     5.89       10     0.59     0.59  _convol_old
24.43     21.82     5.46       10     0.55     0.55  _convol_pointer
 2.37     22.35     0.53                             main
 0.00     22.35     0.00       30     0.00     0.73  convol

• full gprof output

So, what?

• Well, the first remark is that the macro version is slow. This doesn't mean that the macro access is slow (it is very close to the syntax used in the "old" version), because the loops design is poor, in fact, with lots of if branches. It breaks the CPU prediction and the insctrucion pipelining (see the "unrolling" note, hereafter).
• then the pointer code is faster. 25% faster without compiler optimizations, only 5% faster with optimization. This advantage was observed for various image sizes, but it's not very significant. My guess is that the gain in pointer arithmetics (less variables and less operations in the inner loop) were compensated by the pointer aliasing problems (see the "restrict" note, hereafter).

These measures were obtained for a compilation with gcc-4.2. The results are similar with gcc-3.4; with gcc-2.95, the optimization of the "old" version seems inefficient, but the overall impression is the same.

alternatives?

I tried an orthogonal approach, looping first on the kernel, then on the image; as the kernel is supposed to be (much) smaller than the image, it would result in long and regular inner loops, which I expected to be more efficient. But then we can't use a 64-bit accumulator. Is this really needed?

Finally, the results were not convincing, because the loops needed lots of temporary variables, probably more than what the CPU registers allow. I keep it aside, it may be useful later.

miscellaneous remarks

integer indexes

I noticed that with gcc 4.2 on an x86_32 CPU, indexing the loops with an unsigned integer makes the code 30% slower than when we index the loops with a vanilla signed integer. Too me, it looks like a gcc optimization bug.

register starvation

x86 architecture has only 7 integer registers and it's easy to need more for nested loops with variable limits. A few extra registers would be of great help, and are likely to increase the code efficiency, but the x86 CPU family won't provide them.

restrict keyword

In C99, the restrict keyword provides hints to the compiler; it ensures (from the programmer's brain) that two pointers will never alias the same data, allowing better optimizations, and saving some registers. This may improve out pointer-based loops. But it's C99-only...

unrolling the loops

Partial unrolling of the loops usually uses more efficiently the modern CPUs superscalar and pipelining features. This is achieved by replacing a single-instruction loop

for (i = 0; i < imax; i++)
    do_stuff_with(i);

by a bunch of similar instructions inside the loop; for example, with 8 instructions in the loop

for (i = 0; i < imax % 8; i++)
     do_stuff_with(i);
for (i = imax % 8; i < imax; i += 8)
{
     do_stuff_with(i);
     do_stuff_with(i + 1);
     do_stuff_with(i + 2);
     do_stuff_with(i + 3);
     do_stuff_with(i + 4);
     do_stuff_with(i + 5);
     do_stuff_with(i + 6);
     do_stuff_with(i + 7);
}

The downside is that this is largely architecture-dependant. ATLAS uses build-time heuristics to do these optimisations.

I compared them on a convolution routine, with a 5x5 kernel used on a 2048x2048 image, using the gprof profiler.

• convol.c
• convol.h
• bench.c

without compiler optimization

All the source was compiled with simple default options, including -O0 to disable any compiler optimization.

 %   cumulative   self              self     total           
time   seconds   seconds    calls   s/call   s/call  name    
44.95     40.53    40.53       10     4.05     4.05  convol_macro
30.39     67.93    27.40       10     2.74     2.74  convol_convert
23.22     88.87    20.94       10     2.09     2.09  convol_getset
 1.44     90.17     1.30                             main

So, the XX_XY(img, x, y) has the worst performances here, and converting all the data to flt32 (convol_convert) before using simple macros is worse than using type casting on each call (convol_getset).

• full gprof output

with compiler optimization

All the source was compiled with -O2 compiler optimization.

 %   cumulative   self              self     total           
time   seconds   seconds    calls   s/call   s/call  name    
43.95     27.67    27.67       10     2.77     2.77  convol_macro
36.63     50.73    23.06       10     2.31     2.31  convol_getset
18.71     62.51    11.78       10     1.18     1.18  convol_convert
 0.71     62.96     0.45                             main

First, the performance is increased by 32% to 57% for the generic macro and the conversion + specific macro versions, but strangely decreased for the get/set functions.

Overall, converting all the data to a known type and using predictable array access macros is the best solution, probably because the conversion is very efficient and the macros translate to a very clear syntax, easy to optimize.

• full gprof output

and pointer arithmetics?

The macros still need one sum and one product for each data access; it could be simplified with pointer arithmetics, but for the moment these expected improvements have been mitigated by

• CPU limits : x86 platform has very few registers, so a complex loop requiring less a operations needing to keep track of more intermediate values may happen to be less efficient, finally, because it would need lots of memory movements in the CPU. calls is more likely to be efficiently optimized by the compiler.
• compiler optimization : a simple and clear code with few function calls is more likely to be efficiently optimized by the compiler.

• implement only the basic things, add extra features later if we really need them
• document and test everything
• maintain a clean coding style, inspired by this standard

u8image

This matches the original cimage type, reloaded. uint8 is a typedef for unsigned char; we also have uint16, uint32 (no uint64, no long long int in ANSI C), float32 and float64 for the other structures.

This structure is defined in [[mw4f lib/src/u8image.h]], with the implementation details in [[mw4f lib/src/u8image.c]] :

/**
 * 8-bit unsigned integer gray level image
 */
typedef struct s_u8image
{
     uint16 ncol;  /**< number of columns (dx) */
     uint16 nrow;  /**< number of rows (dy)    */
     uint8 * gray; /**< gray level plane       */
} mw_u8image;

/* create an image */
mw_u8image * mw_new_u8image(uint16, uint16);
/* delete an image */
void mw_del_u8image(mw_u8image *);
/* copy an array an image */
mw_u8image * mw_setdata_u8image(mw_u8image *, const uint8 *);
/* copy an image into an existing one */
mw_u8image * mw_copy_u8image(mw_u8image *, mw_u8image *);
/* copy an image into a new one */
mw_u8image * mw_clone_u8image(mw_u8image *);

/* get one value of an image */
int16 mw_getdot_u8image(mw_u8image *, uint16, uint16);
/* set one value of an image */
int16 mw_setdot_u8image(mw_u8image *, uint16, uint16, uint8);
/* fill an image */
uint8 * mw_fill_u8image(mw_u8image *, uint8);

/* write a text representation of an image to a file */
int32 mw_fwrite_u8image(FILE *, mw_u8image *);
/* read a text representation of an image from a file */
mw_u8image * mw_fread_u8image(FILE *);

So, what is different?

the structure

• ncol and ncol are unsigned; it makes sense for indices
• ncol and nrow are limited to 2^16; this means 2^32 image pixels, too much...
• no more allocsize; the number of pixels is easily computable from ncol and nrow, and the real allocation size shouldn't be exposed (sensible, and might be arch-dependant)
• no more scale; let's see later if we need it in the structure
• no more name or comment; same reasons
• no more {first|last}{col|row}; same reasons
• no more prev or next; I feel this information should only be handled by the movie structure
• mw_u8image is the type of the structure, not a pointer to the structure; so, we have to explicitly mention the pointer syntax, and I think improves the code readability

the functions

• mw_new_u8image allocates the structure and the array; there is no more mw_change_u8image; it seems that the previous "image resizing without realer" feature was not used a lot, and this kind of thing is a candidate for memory leaks; so, from now, we create an image, we delete an image, but we don't resign it on-the fly; in some cases, it may imply a performance loss, but the main performance focus is on the algorithms
• mw_{setdata|copy|clone}_u8image are handy shortcuts to duplicate some data
• mw_{getdot|setdot|fill}_u8image may not be used a lot; but it's a good way to start manipulating the images
• mw_{fwrite|fread}_u8image write or read a text representation of the images; I think it may be the preferred way to dump some data, for personal use, or maybe when there is no natural format (think about float images); text representation make it for perfect portability, readability, and make editing easy; for the moment I chose the JSON format for its flexibility and the availability of writing/parsing libraries; text format might be bigger and slower to process than a binary format, but we can gzip it, and... once again, the performance is in the algorithms, not in the i/o.

u16image, f32image, ...

Same, with another data type. See [[mw4f lib/src/u16image.h]]/[[mw4f lib/src/u16image.c]] and [[mw4f lib/src/f32image.h]]/[[mw4f lib/src/f32image.c]].

notes

All the new code is documented a la doxygen and tested with:

• static linting with splint +posixlib +weak -ansi89limits
• separate compilation with gcc -Wall -I. -pedantic -Werror -Wc++-compat -Wextra -Wfloat-equal -Wundef -Wshadow -Wpointer-arith -Wbad-function-cast -Wcast-qual -Wcast-align -Waggregate-return -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations -Wnested-externs
• unit tests with CUnit

In the future, these gray-level structures might be merged with the color images.

I also think about a "package", with all the basic operations one may want to perform on an image:

• add an image or a scalar to an image
• sub an image or a scalar from an image
• mul an image by an image or a scalar
• div an image by an image or a scalar
• max of an image
• min of an image
• mean of an image
• fmean of an image
• AND an image and an image or a scalar
• OR an image and an image or a scalar
• XOR an image and an image or a scalar
• AND an image and an image or a scalar

By the way, we stick to ANSI C, but overloading and default parameters would be really nice there; it's possible to implement sort of overloading in C with unions, but at the price of a code difficult to write, read, use and maintain. Maybe a C++ overlay later?

Actually, it is possible to make some sort of overloading in C, with unions. It's not elegant code, and may not be transparent for the user, but it's possible, and worth trying. I tried it.

image

So, here is the generic image structure; I don't know if it will stay in the code, we'll see.

This structure is defined in [[mw4f lib/src/image.h]], with the implementation details in [[mw4f lib/src/image.c]] :

/**
 * xx_image union
 */
typedef union u_xximage
{
     mw_u8image  u8;  /**< uint8  image */
     mw_u16image u16; /**< uint16 image */
     mw_f32image f32; /**< uint32 image */
} xximage;

/**
 * gray level image
 */
typedef struct s_image
{
     char dtype;   /**< data type stored */
     xximage img; /**< image union, for all supported dtypes */
} mw_image;

/* create an image */
mw_image * mw_new_image(uint16, uint16, char);
/* delete an image */
void mw_del_image(mw_image *);
/* copy an array to an image */
mw_image * mw_setdata_image(mw_image *, const void *);
/* copy an image into an existing one */
mw_image * mw_copy_image(mw_image *, mw_image *);
/* copy an image into a new one */
mw_image * mw_clone_image(mw_image *);

/* get one value of an image */
flt32 mw_getdot_image(mw_image *, uint16, uint16);
/* set one value of an image */
flt32 mw_setdot_image(mw_image *, uint16, uint16, flt32);
/* fill an image */
void * mw_fill_image(mw_image *, flt32);

/* write a text representation of an image to a file */
int32 mw_fwrite_image(FILE *, mw_image *);
/* read a text representation of an image from a file */
mw_image * mw_fread_image(FILE *);

the structure

• dtype is a marker, to know which kind of image we are dealing with
• img is an union of mw_u8imge, mw_u16image of mw_f32image

That's it. With that, depending on the value of dtype, we'll switch to the correct functions. Note that it doesn't increase the memory size, as all the `mw_xximage structures have exactly the same size. All it takes is, basically, one more allocation test, one switch () test and one more function call for each mw_xxx_image() function.

the functions

• mw_new_u8image, mw_del_image, mw_{setdata|copy|clone}_image are the same, nothing changed from the user point of view, except that you choose which kind of data type you want to use
• mw_{getdot|setdot|fill}_u8image can't be identical; in order to provide an unique interface, they take or return flt32 values; an user cast may be required here
• mw_{fwrite|fread}_u8image didn't change; we just embed the type-dependant format with some extra information :
  { "dtype" = "MW_UINT8", "img" = { "ncol" = 42, "nrow" = 42, gray = [ 1, 2, 3, ... ] } }, and we get a all-type image file format.

notes

By the way, all this code compiles perfectly on x86 and x86_64 systems (PC 32 and 64 bits) and HP-PA too; I should be able to test on some other architectures soon.

I still think it was a good idea, and it worked, but.... why not make it simple. KISS, Keep It Simple (Stupid!). I guess this pseudo-class design was a consequence of the previous codebase, and I used code tricks instead of imagination.

So, after a midnight revelation (yes, around 03:00, in bed...) and a few days rewriting (again...), the design is now simple, very simple:

new image design

The image definition is:

/**
 * generic image structure
 */
typedef struct s_image
{
/* TODO : add bit depth and channels */
     mw_dtype dtype;   /**< datatype of the stored values */
     uint16 ncol;      /**< number of columns */
     uint16 nrow;      /**< number of rows    */
     void * data;      /**< data array        */
} mw_image;

Yes, that's it. An image is:

• a data type (an integer, in fact, but users should only use MW_DT_XX macros)
• a number of rows
• a number or columns
• a data array

Later, we may introduce some other structure fields, if they are needed my many algorithms; but the best way could be to add a simple generic pointer, and let everyone use it as they like (or even register some alloc/dealloc/copy routines).

For color images, the idea is to add a uint8 nchn field for the number of channels; then, we have the following correspondances:

• 1 channel : grayscale image
• 2 channels : grayscale+alpha image
• 3 channels : RGB image
• 4 channels : RGB+alpha image

But it still is possible to define a 255 channels images, if it makes sense (for the algo and for the memory space).

user interface

This generic data array can be used in different ways:

• high-level, generic
  With the macro XY(img, x, y), you access the same point, but through less function calls, so it's faster. As it's in fact three nested ( ? : ) operations (to adapt the behaviour to the type), you can't use it as a lvalue, ie to update a value.
• high-level, specific
  For lvalues, or when you know for sure what's the dtype of your image, U8_XY(img, x, y), U16_XY(img, x, y), F32_XY(img, x, y) will work, but still at the cost of two indirections, one sum and one product.
• high-level
  With mw_image_getdot(img, x, y) and mw_image_setdot(img, x, y, value), you can access and update the point (x, y) in the img image. The functions take care of type casting and array position. This is easy, simple, but won't be very fast.
• lower-level In loops, when speed matters, you can still use a classic array syntax. But you will need to know the type used in the data array, and use type casting because it's not possible to use void pointers directly. It will have to look like ((uint8 *) image->data)[y * ncol + x], but you can also define first data = (uint8 *) image->data, then write data[y * ncol + x]. This also means that you wil need a switch () statement, to select between the possible types.
• lowest-level As usual, in C, lowers-level means pointers. Here also, if you cast image->data to the correct pointer type, everything is fine.

Some profiling is planned, to provide comparative measures of the performance of these levels.

code architecture

This change improves the code architecture, function calls, and dependencies. Now it's possible to implement generic image-processing algorithms without the hassle of dealing with subtypes, unions, and so on. The image file (TXT, PNG, tIFF...) read/write routines are also simplified:

fast loops

By the way, the images are stored by rows, X-style ((0, 0) is the upper-left corner). So, the efficient way to pass through all the pixels is:

uint8 * data;
uint16 nrow, ncol;

data = (uint8 *) image->data;
nrow = data->nrow;
ncol = data->ncol;
for (y = 0; y < nrow; y++)
    for (x = 0; x < ncol; x++)
        do_stuff_with(data[y * ncol + x]);

This ensures a better memory localisation, less CPU cache miss, ... a faster code.

If performance is a matter, pointer arithmetics will save one sum, one product, some tests and some registers at each loop, but the code will be a bit obfuscated:

uint8 * ptr, * stop;

ptr = (uint8 *) image->data;
stop = ptr + image->ncol * image->nrow;
while (ptr < stop)
    do_stuff_with((* ptr++));

So, updating the code, linting, the test code, testing and debugging took about ... 2 hours only. Good!

standard libraries

The first decision is to use only the standard and well-known, well-tested, well-distributed libraries to do it, and only #include the relevant headers; it may seem obvious, but it was not done like that until now. This means that:

• to build the megawave library, you need the headers for these libraries on your system: you will need the libxxx-dev packages on Debian-based linux distributions, or the libxxx-devel packages on RPM-based linux distributions; out of the linux world, I don't know yet...
• to use the megawave library, you need the run-time versions of these libraries (ie libxxx packages)

This should not be a problem, as packages systems handle the dependencies. We may also provide an "all-inclusive" binary version of megawave, for quick tests. And it would solve all sorts of API/compiler/standard compatability issues.

And by "standard libraries", I mean libpng, libtiff, libjpeg, jasper, giflib, netpbm, ...

By the way, I can't find any "standard" library for the BMP files. But who need BMP file?

structures and formats

The main question is then «how should we handle the multiplicity?». We currently have 3 internal raster image formats (based on uint8, uint16 and flt32); we may add sooner or later the other natural types (uint32, uint64 and flt64), counting to 6. If we implement the color images as different structures (which is not certain), it would double this number. Then, later, why not 3D-images (if they are not the same thing as movies).

The natural image file formats are png and jpeg. Legacy formats, like pnm, tiff, gif can be useful too. And jpeg2000. Same for scientific data formats like netcdf of dicom. And then we will have to think about extracting frames from mpeg, avc, vp (and variants), huffyuv (lossless) video?

Basically, we have many internal structures, and we want to be able to fill them from many different kinds of external files.

in / out matrix

Let's just consider 3 internal structures, and 3 file formats. The naive design, ie one function per input/output couple, looks like that:

design 1.dot design 1.svg

So, 9 functions for the moment, with lots of code duplication. Then, if we want to add one file format, we need to write 4 functions (the generic load_foo plus the three load_foo_xx interfaces), and modify 3 other ones (load_xximage). This will grow exponentially, the the result will be a lot of unmaintainable code.

multiple in / multiple out

One simplification is to remove the matrix, and allow direct dialogue between the "image" side and the "file" side.

design 2 direct.dot design 2 direct.svg

The it would be somehow more easy to add a new format, we still need to update many new functions each time we want to add support for a new format; this big "cross-interaction" at the center has to be removed.

front-ends

The same design, with front-ends added, limits the dependencies.

design 2 indirect.dot design 2 indirect.svg

Now, each time we add a new format, there is one new function to write (load_foo) and one to update (load_file). And the two different parts of the code ("image" and "file") are connected by a single interface.

One problem remains: the load_file functions must be able to return different outputs, depending on who called them.

This could be done by:

• returning a (void *) pointer; no type checking, dangerous, buggy, etc.
• filling a pointer passed as argument; doing so, the memory would be allocated in the "file" side of the code, then used in the other side, and the load_xx function would need to access mw_new_xximage, which means cross-dependencies.
• returning a generic mw_image; but this generic structure is an overlay, not a building brick for the mw_xximages

details

The solution is to split the process in two parts:

1. gather meta-information from the file (shape, data type, layers...), then create the empty mw_xximage structure and allocate the correct memory size
2. gather the image data, filled in the memory area whose address is passed as a parameter

This work-flow would look like that:

design detail.dot design detail.svg

This design is modular; for example,

• it's easy to change the way the image format is selected (parameter? file name extension? magic number?)
• it's possible to collect only the meta-data, or only the raster data
• for any new file format, we need to add two functions and update two functions
• for any new internal format, we just need to implement the same calls as the already-defined formats do

• they can only read grayscale images (color and alpha images will be available when the color image structures are defined)
• they only read 8bit or 16bit (no monochrome, 2bit or 4bit yet)
• they can write 8bit or 16bit grayscale
• a float image is converted to 16bit integer by multiplying it by 65535 (we assume float values are between 0 and 1)
• a png file is loaded into a float image by dividing it by 255 or 65535 (resulting in values between 0 and 1)

If explicitely requested, the file is converted to the desired datatype (8bit, 16bit unsigned integer, or float); else, the most appropriate image structure is selected, in a mw_image container.

It's not freezed, and some parts are likely to be modified in the future, but the main design is there.

Adding a new image format requires 3 new functions, and 4 changes in switch statements; adding a new image structure requires 4 changes in switch statements (and the functions mw_load_xximage() and mw_save_xximage()).

So, we now have the bare tools to start working on the algorithms:

• grayscale image formats
• native human-readable text i/o formats
• common lossless binary i/o formats

• we want some rich error/debug messages, including the file and line number, and...
• file and line number are provided by the ANSI C __FILE__ and __LINE__ macros, so...
• we must call the messages functions with a macro, but ...
• we sometimes need to send printf-like formatted messages, like ("the value is %i", foo), and ...
• ANSI C doesn't allow variadic macros, so ...
• we must use an intermediary function to format the message and store it in a temporary buffer, like DEBUG(vmsg("the value is %i", foo)), but ...
• the temporary buffer has a fixed length, and ...
• sprintf() may write after the end of this buffer, which would result in a crash.

So, as a workaround, we use an "ANSI C implementation of snprintf()". Various implementations exist, such as:

• http://www.jhweiss.de/software/snprintf.html
• http://www.ijs.si/software/snprintf/

For the moment, we use the latter one, because it's more compact.

Bad news : none of these implementations are free of splint or gcc warnings... so they have to be excluded from our code quality tests.

guide 1 : user guide

• html
• html gzipped
• html single file
• pdf (with links!)

guide 2 : system library

• html
• html gzipped
• html single file
• pdf (with links!)

LaTeX-html conversion is handled with HeVeA, but it is far from perfect; incompatibilitues with hyperref, poor html styling, .... Basically, LaTeX-html conversion is a broken issue as long as html is not a native TeX output format.

The correct solution could be using a markdown master format, converted to LaTeX and html with pandoc, but markdown (and even pandoc's markdown) is too poor for a guidebook (think about index, table of contents, references, ...).

This change is part of the will to be known better, distributed better, and used more.

As an early step, megawave is now listed in freshmeat and ohloh.

• megawave@math-info.univ-paris5.fr
  This list is an open discussion list, for the megawage community: users and developpers are wecome to share their questions, knowledge, ideas.
• megawave-info@math-info.univ-paris5.fr
  This list is an read-only low-traffic list; new releases, meetings and events will be announced here.

To subscribe to these lists, visit their web pages or send a mail to sympa@math-info.univ-paris5.fr with sub megawave or sub megawave-info as the title. The subscription is open; the archives are publicly available.

Don't expect it to be correct, able to run, or even able to compile. But it may sometimes be ok.

• the result
• the python patch (with two typos fixed)
• the css patch

• mwplight : the light preprocessor
• lib : the megawave kernel and library
• modules : all the modules

This documentation, with tons of exhaustive cross-references, includes

• all the source code, syntax-highlighted
• all the structures, with the structures members
• all the global variables and macros
• all the file inclusion graphs
• all the function call graphs

It is available as

• html, browsable online
• html, archived for download and offline use
• pdf, for printing

Note that the pdf documentation is huge with lots of details and hundredth of pages. I don't think it's worth printing; but il includes pdf hyperlinks for easy navigation. The best way to use this doc is the html format.

type definition, in [[mw3f kernel/lib/include/cimage.h]] :

typedef struct cimage {
  int nrow;
  int ncol;
  int allocsize;
  unsigned char *gray;    
  float scale;
  char cmt[mw_cmtsize];
  char name[mw_namesize];

  int firstcol;
  int lastcol;
  int firstrow;
  int lastrow;

  struct cimage *previous;
  struct cimage *next;
} *Cimage;

• nrow : number of rows (dy)
• ncol : number of columns (dx)
• allocsize : size allocated (in bytes) for the gray plane
• gray : the gray level plane (may be NULL)
• scale : scale of the picture (should be 1 for original pict.)
• cmt : comments
• name : name of the image
• firstcol : index of the first col not affected by left side effect
• lastcol : index of the last col not affected by right side effect
• firstrow : index of the first col not aff. by upper side effect
• lastrow : index of the first col not aff. by lower side effect
• previous : pointer to the previous image (may be NULL)
• next : pointer to the next image (may be NULL)

ccimage

type definition, in [[mw3f kernel/lib/include/ccimage.h]] :

typedef struct ccimage {
  int nrow;
  int ncol;
  int allocsize;
  unsigned char *red;    
  unsigned char *green;    
  unsigned char *blue;    
  float scale;
  char cmt[mw_cmtsize];
  char name[mw_namesize];

  int firstcol;
  int lastcol;
  int firstrow;
  int lastrow;

  struct ccimage *previous;
  struct ccimage *next;
} *Ccimage;

• nrow : number of rows (dy)
• ncol : number of columns (dx)
• allocsize : size allocated (in bytes) for the gray plane
• red : the red level plane (may be NULL)
• green : the green level plane (may be NULL)
• blue : the blue level plane (may be NULL)
• scale : scale of the picture (should be 1 for original pict.)
• cmt : comments
• name : name of the image
• firstcol : index of the first col not affected by left side effect
• lastcol : index of the last col not affected by right side effect
• firstrow : index of the first col not aff. by upper side effect
• lastrow : index of the first col not aff. by lower side effect
• previous : pointer to the previous image (may be NULL)
• next : pointer to the next image (may be NULL)

images and movies

• [[mw3f kernel/lib/src/cimage.c]] : 8bit gray image
• [[mw3f kernel/lib/src/ccimage.c]] : 8bit color image
• [[mw3f kernel/lib/src/fimage.c]] : float gray image
• [[mw3f kernel/lib/src/cfimage.c]] : float color image
• [[mw3f kernel/lib/src/cmovie.c]] : 8bit gray movie
• [[mw3f kernel/lib/src/ccmovie.c]] : 8bit color movie
• [[mw3f kernel/lib/src/fmovie.c]] : float color movie
• [[mw3f kernel/lib/src/cfmovie.c]] : float color movie
• [[mw3f kernel/lib/src/mimage.c]] : morpho gray image
• [[mw3f kernel/lib/src/cmimage.c]] : morpho color image

curves, polygons

• [[mw3f kernel/lib/src/curve.c]] : polygonal lines with integer coordinates
• [[mw3f kernel/lib/src/fcurve.c]] : polygonal lines with float coordinates
• [[mw3f kernel/lib/src/dcurve.c]] : polygonal lines with double float coordinates
• [[mw3f kernel/lib/src/polygon.c]] : polygons with integer coordinates
• [[mw3f kernel/lib/src/fpolygon.c]] : polygons with float coordinates
• [[mw3f kernel/lib/src/shape.c]] : shape structures for the flst

signal and wavelets

• [[mw3f kernel/lib/src/wmax2d.c]] : wavelet maxima structure
• [[mw3f kernel/lib/src/wpack2d.c]] : wavelet pack structure
• [[mw3f kernel/lib/src/wtrans1d.c]] : wavelet trans 1D structure
• [[mw3f kernel/lib/src/wtrans2d.c]] : wavelet trans 2D structure
• [[mw3f kernel/lib/src/fsignal.c]] : fload based signal structure

misc

• [[mw3f kernel/lib/src/list.c]] : float/double list and list of lists structures
• [[mw3f kernel/lib/src/rawdata.c]] : polyvalent rawdata format

custom types i/o

images and movies

• [[mw3f kernel/lib/src/cimage_io.c]] : wrappers for various formats i/o
• [[mw3f kernel/lib/src/ccimage_io.c]] : wrappers for various formats i/o
• [[mw3f kernel/lib/src/fimage_io.c]] : wrappers for various formats i/o
• [[mw3f kernel/lib/src/cfimage_io.c]] : wrappers for various formats i/o
• [[mw3f kernel/lib/src/cmovie_io.c]] : native cmovie format i/o
• [[mw3f kernel/lib/src/ccmovie_io.c]] : native ccmovie format i/o
• [[mw3f kernel/lib/src/fmovie_io.c]] : native fmovie format i/o
• [[mw3f kernel/lib/src/cfmovie_io.c]] : native cfmovie format i/o
• [[mw3f kernel/lib/src/mimage_io.c]] : native mimage format i/o
• [[mw3f kernel/lib/src/cmimage_io.c]] : native cmimage format i/o

curves, polygons

• [[mw3f kernel/lib/src/curve_io.c]] : native curve format i/o
• [[mw3f kernel/lib/src/fcurve_io.c]] : native fcurve format i/o
• [[mw3f kernel/lib/src/dcurve_io.c]] : native dcurve format i/o
• [[mw3f kernel/lib/src/polygon_io.c]] : native polygon format i/o
• [[mw3f kernel/lib/src/fpolygon_io.c]] : native fpolyvgon format i/o
• [[mw3f kernel/lib/src/shape_io.c]] : native shape format i/o

signals and wavelets

• [[mw3f kernel/lib/src/wmax2d_io.c]] : wavelet maxima i/o routines
• [[mw3f kernel/lib/src/wpack2d_io.c]] : wavelet pack i/o routines
• [[mw3f kernel/lib/src/wtrans1d_io.c]] : wavelet trans 1D i/o routines
• [[mw3f kernel/lib/src/wtrans2d_io.c]] : wavelet trans 2D i/o routines
• [[mw3f kernel/lib/src/fsignal_io.c]] : float signal i/o routines

misc

• [[mw3f kernel/lib/src/list_io.c]] : native list formats i/o
• [[mw3f kernel/lib/src/rawdata_io.c]] : native rawdata i/o

external standard formats i/o

• [[mw3f kernel/lib/src/bmp_io.c]] : Microsoft BitMap format
• [[mw3f kernel/lib/src/gif_io.c]] : Graphics Interchange fromat
• [[mw3f kernel/lib/src/img_io.c]] : IMG format
• [[mw3f kernel/lib/src/jpeg_io.c]] : Joint Picture Experts Group format
• [[mw3f kernel/lib/src/pgm_io.c]] : Portable GrayMap format
• [[mw3f kernel/lib/src/pm_io.c]] : Portable BitMap format
• [[mw3f kernel/lib/src/ppm_io.c]] : Portable PixMap format
• [[mw3f kernel/lib/src/tiff_io.c]] : Tagged Image File Format
• [[mw3f kernel/lib/src/notiff.c]] : placeholder if libtiff is not available
• [[mw3f kernel/lib/src/epsf_io.c]] : Encapsulated PostScript file format
• [[mw3f kernel/lib/src/ps_io.c]] : PostScript format
• [[mw3f kernel/lib/src/rim_io.c]] : RIM format
• [[mw3f kernel/lib/src/wave_io.c]] : Waveform Audio format

core

• [[mw3f kernel/lib/src/mw.c]] : various general-purpose functions
• [[mw3f kernel/lib/src/mw_main.c]] : main executable
• [[mw3f kernel/lib/src/mwio.c]] : external file formats i/o wrappers
• [[mw3f kernel/lib/src/module.c]] : module structure
• [[mw3f kernel/lib/src/module_io.c]] : module text descriptions i/o

utilities

• [[mw3f kernel/lib/src/ascii_file.c]] : utilities for manipulating text files
• [[mw3f kernel/lib/src/basic_conv.c]] : conversion routines between native formats
• [[mw3f kernel/lib/src/file_type.c]] : file format recognition
• [[mw3f kernel/lib/src/maketypeconv.c]] : build many-to-many format conversion routines using the existing ones
• [[mw3f kernel/lib/src/type_conv.c]] : automatically generated generic format conversion routines
• [[mw3f kernel/lib/src/unix_bsd.c]] : compatibility layer for BSD/UNIX

X system

• [[mw3f kernel/lib/src/window.c]] : connexion between megawave and the Wdevice X library
• [[mw3f kernel/lib/src/wpanel.c]] : X display custom toolkit
• [[mw3f kernel/lib/src/xmw_com.c]] : connexion between megawave and Xmegawave

Usage: mwplight [options] filename
Options:
  -a, --afile file    name of the A-file (main function of the run-time)
  -m, --mfile file    name of the M-file (source of the modified module)
  -t, --tfile file    name of the T-file (source of the module documentation)
  -i, --ifile file    name of the I-file (interface file for an interpretor)
  -n, --nfile file    name of the N-file (group and name of the module)
  -g, --group group   group the module belongs to (defaults to "unknown")
  -v, --version       print version information
  -d, --debug         debug flag
  -h, -?, --help      print usage help

  -a and -m options and the filename are required.

And no more environment variable is needed.

• [[mw3f Install]]
  build and install script
• [[mw3d data]]
  various data samples
• [[mw3d doc]]
  PDF/DVI versions of the guidebook volume 1 and 2; BibTeX bibliography
  • [[mw3d doc/src]]
    LaTeX documentation for each modules
• [[mw3d kernel]]
  megawave kernel (parser and libs)
  • [[mw3d kernel/mwp]]
    the megawave preprocessor
  • [[mw3d kernel/mwplight]]
    the megawave preprocessor, light version
  • [[mw3d kernel/lib]]
    kernel libraries
    • [[mw3d kernel/lib/src]] kernel libraries source
    • [[mw3d kernel/lib/include]] kernel libraries headers
      • [[mw3d kernel/lib/include/Linux]] custom (ANSI C) Linux headers
      • [[mw3d kernel/lib/include/Solaris]] custom (ANSI C) Solaris headers
  • [[mw3d kernel/shell]]
    various shell helper scripts
    • [[mw3d kernel/shell data]] file fragments for the preprocessor and interformat converters
  • [[mw3d kernel/Wdevice]]
    GUI lib
• [[mw3d src]]
  modules, and a partial module testsuite
  • [[mw3d src/compression]]
  • [[mw3d src/curve]]
  • [[mw3d src/examples]]
  • [[mw3d src/image]]
  • [[mw3d src/signal]]
  • [[mw3d src/wave]]
    mixed topical C modules codes and shell helper scripts

build sequence, megawave v3

• [[mw3f Install]]
  • [[mw3f kernel/shell/mwinstall]]
    • [[mw3f kernel/shell/mwsetenv]]
    • [[mw3f kernel/Install]]
      • [[mw3f kernel/Wdevice/Install]]
        • [[mw3f kernel/shell/mwconfig]]
        • make install
      • [[mw3f kernel/lib/Install]]
        • [[mw3f kernel/shell/mwconfig]]
        • make install
      • [[mw3f kernel/mwp/Install]]
        • [[mw3f kernel/shell/mwconfig]]
        • make install
      • [[mw3f kernel/mwplight/Install]]
        • [[mw3f kernel/shell/mwconfig]]
        • make install
      • make install
    • [[mw3f kernel/shell/cmw2_all]]
      • [[mw3f kernel/shell/cmw2]]
      • mwplight
      • cc/ar/ld
    • [[mw3f kernel/shell/mwmakedoc]]
    • cat
    • latex
    • latex2html
    • [[mw3f kernel/shell/mwmodlist]]
    • [[mw3f kernel/shell/mwmodinstall]]
    • [[mw3f src/Checkmodules]]

compilation and installation

• [[mw3f kernel/shell/mwinstall]] : install megawave
• [[mw3f kernel/shell/mwconfig]] : build a makefile from Makefile.in
• [[mw3f kernel/shell/cmw2]] : compilation of a module or macro
• [[mw3f kernel/shell/cmw2macro]] : compilation of a macro
• [[mw3f kernel/shell/cmw2_all]] : recursive compilation of the modules
• [[mw3f kernel/shell/cxmw2]] : compilation of an X binary
• [[mw3f kernel/shell/cxmw2debug]] : debug version of cmw2
• [[mw3f kernel/shell/mwcleandistrib]] : remove the temporary build files

documentation

• [[mw3f kernel/shell/mwcontrib]] : list the contributors of a modules or macro
• [[mw3f kernel/shell/mwcontrib_all]] : list the contributors of the modules or macro
• [[mw3f kernel/shell/mwdep]] : build a dependencies list for the documentation
• [[mw3f kernel/shell/mwdoc]] : enter the internal documentation system
• [[mw3f kernel/shell/mwdoclatex]] : build the documentation for a module
• [[mw3f kernel/shell/mwdocxdvi]] : display the documentation of a module
• [[mw3f kernel/shell/mwmakedoc]] : make a new updated version of the documentation
• [[mw3f kernel/shell/mwmodbibtex]] : run bibtex on the documentation

modules administration

• [[mw3f kernel/shell/mwmodcheck]] : check the consistency of a preprocessed module source
• [[mw3f kernel/shell/mwmodinstall]] : install a new modules set
• [[mw3f kernel/shell/mwmodlist]] : list the modulkes and macros
• [[mw3f kernel/shell/mwmodsearch]] : search for a module matching words
• [[mw3f kernel/shell/mwnewuser]] : create a directory hierarchy for a new user
• [[mw3f kernel/shell/mwrm]] : remove a module or macro
• [[mw3f src/Checkmodules]] : run some validity tests on some modules

utilities

• [[mw3f kernel/shell/mwarch]] : determine the host archiitecture
• [[mw3f kernel/shell/.mw2helplg_com]] : error handler for the other system scripts
• [[mw3f kernel/shell/mwsetenv]] : set up the environment for megawave (shell environment variables)
• [[mw3f kernel/shell/mwsysmaclist]] : list the system macros
• [[mw3f kernel/shell/mwecho]] : portable [[mw3f echo]]
• [[mw3f kernel/shell/mwisupper]] : is the first letter upper or lower case?
• [[mw3f kernel/shell/mwincvers]] : increment the version number
• [[mw3f kernel/shell/mwvers]] : megawave version number
• [[mw3f kernel/shell/mwwhere]] : tell where the module is
• [[mw3f kernel/shell/mwrnauthor]] : rename an author of a module

user scripts

wavelet compression

• [[mw3f src/compression/ezwave/Cfezw]] : options handler for color EZW compression
• [[mw3f src/compression/ezwave/Fezw]] : options handler for EZW compression
• [[mw3f src/compression/vqwave/Cfwivq]] : options handler for color wavelet decompression
• [[mw3f src/compression/vqwave/Cfwvq]] : options handler for color wavelet compression
• [[mw3f src/compression/vqwave/Fwivq]] : options handler for color wavelet decompression
• [[mw3f src/compression/vqwave/Fwlbg_adap]] : build a codebook for wavelet transformation
• [[mw3f src/compression/vqwave/Fwvq]] : options handler for color wavelet compression

shape recognition

• [[mw3f src/image/shaperecognition/CLEARBASE]] : clear the shape recognition directory
• [[mw3f src/image/shaperecognition/PUTTO_BASE]] : put an image in the shape recognition directory
• [[mw3f src/image/shaperecognition/READBASE]] : show infos about the shape recognition directory
• [[mw3f src/image/shape_recognition/RECOGNIZE]] : recognise a shape from the shape recognition directory
• [[mw3f src/image/shaperecognition/SRDEMO]] : demonstration of the shape recognition module

miscellaneous

• [[mw3f src/curve/matching/KM_DEMO]] : demonstration of the curve matching algorithms
• [[mw3f src/image/detection/VP_DEMO]] : demonstration of the curve alignment module
• [[mw3f src/image/io/Mkmovie]] : build a movie from an image sequence
• [[mw3f src/signal/Swtvdenoise]] : suite of modules invocations for denoising
• [[mw3f src/wave/packets/Wp2dcheck]] : check and demo of the 2D wavelet packets module

1. Maria is an image processing researcher. She wants to use, try or compare recent algorithms and methods.
2. Hakim is an image processing researcher. He wants to show and distribute his new algorithms and methods.
3. Hiroko is developing some image processing software or hardware; she wants to include recent and efficient algorithms.
4. Marc is a math teacher. He needs to show how various image processing tools work, and he needs a framework to help his students try things with this kind of tools.

For all af them, megawave intends to provide a solution.

splint test are also processed, in order to improve the code quality (type checking, buffer overflow, NULL pointers, ...). No errors are reported for splint +posixlib +weak -ansi89limits -bufferoverflowhigh and some additional markup is being added for a standard test (no +weak). There still is the issue of unsafe C90 sprintf() functions, but we may solve it through an external library in order to keep C/C++ compatability.

• browse the code through the simple ''darcs_cgi'' interface by visiting ''http://dev.39mm.net/darcscgi/megawave-4''
• browse the code through the fancy ''darcsweb'' interface by visiting ''http://dev.39mm.net/darcsweb/?r=megawave-4''
• get the current development version with ''darcs get --partial http://dev.39mm.net/darcs/megawave-4''

darcs get --partial http://dev.39mm.net/darcs/megawave-4

I added today a subversion frontend. So you can also get a local copy of the code with:

svn checkout http://dev.39mm.net/svn/megawave-4

The darcs -> svn sync is performed every night.