README for using the iLab Neuromorphic Vision C++ Toolkit under Windows

 

The Cygwin porting: done by Ale Kanevsky, CS faculty of the Technion (Israel Institute of Technology), Haifa, Israel, email: sasha523@t2.technion.ac.il.

The MSVC++ porting: done by Ale Kanevsky and Lila Astrachen.

Supervisors: Tamar Avraham (email: tammya@cs.technion.ac.il) & Michael Lindenbaum (email: mic@cs.technion.ac.il, home page http://www.cs.technion.ac.il/~mic/), CS faculty of the Technion.

 

Please note: this port was completed as an undergraduate project, which now is finished. While we think that the provided material may be useful, it should be understood that it comes with absolutely no warranty of any kind. Also, the authors should if possible not be bothered with too many questions as they are now working on different projects. So, use this at your own risk!

Abstract

This porting is the result of an ordinary project course taken by us at the Technion (called Advanced Programming Beth).  The goal was to port the ezvision core of the iLab toolkit, to Windows platform. At this time, two portings were done: the first one with the help of Cygwin (the UNIX emulation layer for the Win32 platform), and the second was done under Microsoft Visual Studio .NET 2003 IDE, with the vital help of MinGW (the native Windows UNIX-style GCC compiler and DLL maker).

 

General Description

The ports are organized in two distinct folders: the first is called CygwinPorting and the second is called NativePorting, and each one contains the corresponding version of the porting. The CygwinPorting folder contains the command-line ezvision executable and 5 additional Cygwin DLLs (extracted from Cygwin installation) that are necessary to run the Cygwin porting executable “natively” on Windows (i.e., nothing more is needed to run it, and the whole Cygwin environment is required only if you want to compile the iLab code yourself or play with it). The NativePorting folder contains the Microsoft Visual Studio .NET 2003 project solution that produces the native Win32 ezvision executable after compilation. It contains the modified versions of the iLab code files and some necessary DLLs (made in MinGW) and their *.LIB interfaces for the solution. Also, a more or less comfortable visual launcher (with a help file) is included, to facilitate the running of ezvision (with the help of a dialog-based MFC application). The directory where the launcher executable resides contains two subdirectories: CE (stands for Cygwin Ezvision) and NE (stands for Native Ezvision) – they contain the respective versions of the ported ezvision executables and also the DLLs required by them at runtime. Also, right there is the launcher's help file that contains useful information about ezvision's and its own usage options.

 

General Usage Regulations (of Both Portings)

The ezvision program, when run on Linux, uses the XV program to display its result images. On Windows, the excellent freeware viewer called IrfanView should be used for that. Its installer is included in this folder. After you install this viewer, you must define an environment variable called IVPATH. For this, right-click the “My Computer” icon on your desktop, click “Properties”, then select the “Advanced” tab, click the “Environment Variables” button, and define the IVPATH variable in the user part of the panel. If your IrfanView is installed, for instance, in the C:\Program Files:\IrfanView directory, your IVPATH environment variable should be then: “C:\Program Files\IrfanView\i_view32.exe” (quotation marks are included in the variable's name). Of course, you don't need to install this software for ezvision to work, exactly as you do not need to have XV for it on Linux. In this case, you won't see the intermediate results that ezvision produces. Because all these programs are free, it is highly recommended that you install them (IrfanView on Win32 as well as XV on Linux). And anyway, since ezvision works mainly with PNM files (PBM, PGM and PPM formats), you won't be able to see even the results saved on the disk if you don't have IrfanView or programs like it, that know to display PNM files. So, roughly speaking, just install it.

Running ezvision.exe in a command-line style: for this, run a CMD shell instance from you Windows account. Then enter into the directory where the ezvision executable resides, and use it exactly as you would use it on Linux, as described by Dr. Itti at the iLab forum. I.e., the options syntax is exactly the same, except the fact that the file paths should be specified in the Windows style, of course (with a backslash delimiter between directories). Of course, the executable's name should not be preceded by the “./” Linux-style sequence.

Running ezvision.exe from the visual launcher: run the launcher application by double-clicking its icon, and then use its button panels to run ezvision in the manner you like the most. Four buttons are for some commonly used option combinations (at least by our project supervisors), and one more (Custom Launch) is intended for custom options running. Note that if you use this button, you should not add neither the executable's name nor the file name to the options line. Only the options themselves should be entered. Of course, if there is an options syntax error, ezvision will exit rapidly and you'll see nothing, so keep your options right and neat. You can toggle between ezvision versions – Cygwin one vs. MSVC++ one. The launcher has also a help file connected to it, that basically contains the same info as the ezvision help message does - it was just reorganized with some additions. There you can find all the necessary information about the options syntax and the visual launcher usage.

 

Compiling the Code and Making Necessary Changes (on Cygwin)

If you want to experience the compilation of the iLab code under Cygwin yourself, you need to do these things:

1)     Obtain the Cygwin emulation environment from http://www.cygwin.com. Install it according to their regulations. This package is pretty big and takes about 2 GB on disk (when fully installed). But after you finish your compilation, it can be deleted (or some of its components can get uninstalled if you want some functionality of the layer to remain), since the applications compiled on it can be run “natively” under Windows, with some additional DLLs extracted from the Cygwin installation (i.e., the layer is needed for compilation, but for running your exe, you need several of its DLLs, not having the need of the Cygwin BASH shell). For the compilation, I recommend you to install all the Cygwin components.

2)    Obtain the source code from the iLab CVS (NOTE: this has now changed to being an SVN server) server (you need to place the request for this on the forum, under a new topic, since it's a password-protected distribution). Alternatively, you can get the code from here, where I have already done all the changes described below (i.e., these changes should be applied to the original version of the code, not for mine). The CVS distribution is for the full saliency package, while I have compiled only its main program called ezvision. So you have to play only with the files the ezvision is built from, i.e.:

ArrayData.H

atomic.H

AttentionGuidanceMap.C

AttentionGuidanceMap.H

Beowulf.C

Beowulf.H

BitObject.C

BitObject.H

BitObjectDrawModes.H

Brain.C

Brain.H

ChannelBase.C

ChannelBase.H

Channels.C

Channels.H

ChannelsBeo.C

ChannelsBeo.H

ChannelsSurprise.C

ChannelsSurprise.H

CheckedIterator.H

ComplexChannel.C

ComplexChannel.H

Dims.H

ezvision.C

fancynorm.C

fancynorm.H

font.C

FrameGrabberMode.H

FrameRange.H

FrameSeries.C

FrameSeries.H

Image.C

Image.H

Image_All.H

Image_ColorOps.C

Image_ColorOps.H

Image_DrawOps.C

Image_DrawOps.H

Image_FilterOps.C

Image_FilterOps.H

Image_IO.C

Image_IO.H

Image_MathOps.C

Image_MathOps.H

Image_MonoOnly.C

Image_ShapeOps.C

Image_ShapeOps.H

Image_Transforms.C

Image_Transforms.H

ImageCache.C

ImageCache.H

ImageDisplayTypes.H

ImageSet.C

ImageSet.H

ImageSet_Ops.C

ImageSet_Ops.H

InferoTemporal.C

InferoTemporal.H

InstantiateAll.H

IORtypes.H

Jet.C

Jet.H

LeakyIntegrator.H

LeakyIntFire.H

LevelSpec.C

LevelSpec.H

log.C

log.H

mmx-sse.C

mmx-sse.H

ModelComponent.C

ModelComponent.H

ModelManager.C

ModelManager.H

ModelOptionDefs.C

ModelOptionDefs.H

ModelParam.C

ModelParam.H

OptionParser.C

OptionParser.H

OrientComputeTypes.H

ParamMap.C

ParamMap.H

PbmParser.C

PbmParser.H

Pixels.H

PngParser.C

PngParser.H

PngWriter.C

PngWriter.H

Point2D.H

Point2DT.H

Promotions.H

Pyramid_Ops.C

Pyramid_Ops.H

PyramidTypes.H

PyrBuilder.C

PyrBuilder.H

Range.H

Raster.C

Raster.H

RasterFileFormat.H

Rectangle.H

Retina.C

Retina.H

SaccadeController.C

SaccadeController.H

SaccadeControllers.C

SaccadeControllers.H

safecopy.H

saliency.C

saliency.H

SaliencyMap.C

SaliencyMap.H

ShapeEstimator.C

ShapeEstimator.H

ShapeEstimatorModes.H

shapeEstimatorWebpage.C

SharedPtr.H

SimulationViewer.C

SimulationViewer.H

SimulationViewerCompress.C

SimulationViewerCompress.H

SimulationViewerEyeMvt.C

SimulationViewerEyeMvt.H

SimulationViewerEyeMvt2.C

SimulationViewerEyeMvt2.H

SimulationViewerStd.C

SimulationViewerStd.H

SingleChannel.C

SingleChannel.H

SingleChannelBeo.C

SingleChannelBeo.H

SingleChannelSurprise.C

SingleChannelSurprise.H

SockServ.C

SockServ.H

StdBrain.C

StdBrain.H

StringConversions.C

StringConversions.H

SurpriseImage.C

SurpriseImage.H

SurpriseMap.C

SurpriseMap.H

SurpriseModel.C

SurpriseModel.H

TaskRelevanceMap.C

TaskRelevanceMap.H

TCPcliServ.C

TCPcliServ.H

TCPcommunicator.C

TCPcommunicator.H

TCPdefs.H

TCPmessage.C

TCPmessage.H

test-Image.C

TestSuite.C

Timer.H

TypeTraits.H

VisualBuffer.C

VisualBuffer.H

VisualCortex.C

VisualCortex.H

VisualCortexBeo.C

VisualCortexBeo.H

VisualCortexConfigurator.C

VisualCortexConfigurator.H

VisualCortexSurprise.C

VisualCortexSurprise.H

VisualFeatures.H

WinnerTakeAll.C

WinnerTakeAll.H

WTAwinner.H

XWindow.C

XWindow.H

Of course, this is the core, and if you manage to compile it, you may try to compile other kit components as well (though the success is not guaranteed by Cygwin). If you do manage to do this, it would be very nice, so please notify Dr. Laurent Itti about this too. Also, pay attention to the fact that I didn't tamper with all these funny network files (the Beowulf ones, they deal with cluster programming, and I am only an undergraduate student - so I didn't have a clue what to do with them J). I've managed to compile them on Cygwin, but Dr. Itti told me anyway that this stuff is not too usable on Windows, so just leave this aside. Also, some explicit instantiation files for function templates are included in the inst subdirectory of the source tree (the tree is called src3 on iLab). These files have the *.I extension. They are necessary too.

3)     Prior to making changes, organize your code in the following manner: if your compilation stuff is intended to be under some particular directory, say, Root, make three subdirectories in it: Sources, Objects, Scripts and Executables. Place the source files in the Sources directory. The Objects directory is intended to contain the *.o (object) files produced by the compilation of the sources (and 2 DLLs called fpuexcepts.dll and has_sse.dll that provide us with the feenableexcept and fedisableexcept functions that don't exist on Cygwin). This is highly recommendable, since, if you'll want to change some source file, you'll only need to recompile that file and redo the linking – the rest is unchanged. The Scripts directory contains various scripts to use while. I'll provide the scripts for compilation and linkage. The Executables directory should contain the various ezvision executables produced by the linkage scripts (I'll provide only one script for one executable, you may make your own scripts that produce your own executables too). This directory should contain the copies of the 2 DLL's mentioned above in order to allow the executable to run properly. I'll provide in this directory also the 5 DLLs from Cygwin installation that are necessary to run the executable natively (outside the Cygwin BASH shell). If the executable testing is to be made (as it should be), use the picture files from the Sources/tests/inputs subdirectory. The package provided by me is compliant to the above directory structure.

4)     When you compile or link your files using scripts, do this from the Scripts directory. Compile the sources using the compile.sh script (separate compilation with no linking). Then activate your linkage script (the one provided here or your own one). The script provided here is called link.sh and is of the following syntax:

g++ -ansi -Wall -Wstrict-prototypes -O4 -march=i686 -g -o ../Executables/<exe file name> <object files list> <fpu DLLs list> -L/lib/LINUX -L/usr/X11R6/lib  -lpng -lz -lm  -lXext -lX11  -lpthread

where <exe file name> is the name for the executable you want to produce, <object files list> contains all the necessary *.o files produced by the compilation, and <fpu DLLs list> contains the 2 independent DLLs made by me for FP-exceptions activation support (Cygwin doesn't have it). If your machine's architecture is not Intel Pentium 3, don't use i686 as the argument to the -march option - use the appropriate argument instead (see gcc docs for the values set). Pay attention that you might use also the -Wl,--noinhibit-exec option that causes your exe file to be made even if you have unresolved references in it (this is done to avoid the Beowulf files mess if you do not like them; alternatively, you just can exclude them and references to them from your project).

5)     In order to compile at least your ezvision core, you must make some changes to the source code due to some Cygwin peculiarities.

First of all, in all the files that include the <fenv.h> header, replace the <fenv.h> string with <mingw/fenv.h>.

In the file saliency.C, add the following lines after the inclusion directives:

extern "C" {

__declspec(dllimport) int feenableexcept(int excepts);

__declspec(dllimport) int fedisableexcept(int excepts);

}

In the file log.H, add the following lines after the inclusion directives:

extern “C” {

int snprintf (char *, size_t, const char *format, ...);

int vsnprintf (char *, size_t, const char *format, __builtin_va_list ap);

}

(due to the bug in Cygwin release – there are no appropriate declarations for these functions though they do exist).

These changes are absolutely required. If you don't make them, your program won't compile. The changes that are described below are highly desirable, though the exe could be run even if they are not made:

In the file Raster.C, in the Display function's body, delete all the contents and paste the following lines instead:

if (USING_XV) {

char command[FNAMELEN];

snprintf(command, FNAMELEN, "cmd /c %%IVPATH%% \"%s\" &", file);

system(command);

}

In this manner, the function now calls IrfanView program instead of XV, given that the IVPATH environment variable is provided as described in the above sections. Of course, you may define your own environment variable for calling its executable, for example, name it another way, or define it as leading only to the IrfanView folder and not to the program itself. Then you must change the snprintf line accordingly, of course. If you don't change the Display function in any way, nothing will be displayed since XV simply won't be found, but the program will save the results as needed.

In same file, in the waitForKey function's body, delete the contents and paste the following lines instead:

char tmp[100];

printf("<<<<< Continue? If yes, press <Return>, if no, type \"N\" and <Return> >>>>\n");

fgets(tmp, 100, stdin);

if ( strcasecmp(&tmp[0], "N\n") == 0 ) exit(0);

This is a little enhancement to the displaying-frames mode. In the original version, the program runs forever, here you can exit as you want by typing N or n and pushing Enter.

In the FrameSeriec.C file, in the computeFileName function's body, replace all the appearances of the front slash (the “/” character) in the string and character constants by the “\\” sequence – this is done in order to recognize correctly the file paths on Windows (“/” is a UNIX-style separator, of course). Beware that if you plan to work only from the Cygwin BASH shell, you should not make this change (by the way, because the UNIX style should be kept inside Cygwin, the call to IrfanView won't work anyway, because it accepts only the Windows-style filename strings. It should work though when you specify a filename that is present in the executable's directory at the same level, since in this case there are no front slashes in the path). But if this program is intended to run natively (outside the Cygwin shell), as it should be in most cases, this change is vital, because if you don't do it, the exe will find only the files at the same directory tree level along with it.

If you want to compile and link the Beowulf files properly – just to keep them for yourself, you must do the following changes:

Copy the file provided here (ethernet.h, placed in the NetHeaders subdirectory here) into the Cygwin installation's /usr/include/net subdirectory. I know this is a bit dangerous to tamper with system headers but I have managed to compile the files using this header that lacks on Cygwin. In the file SockServ.C, in the function called check, replace the line

unsigned int client_addrlen = sizeof(clientaddr);

with the line:

int client_addrlen = sizeof(clientaddr);

because Cygwin's g++ does not like the conversion from unsigned int to int.

In the ezvision.C file, you may change the calls to the Raster::waitForKey function in a manner that will allow you to pause the execution after every step even while not displaying frames (the original version does not do it). Just look at the changes that I've done and decide if you want them.

 

Compiling the Code and Making Necessary Changes (on MSVC++)

The MSVC++ porting is also supplied with all necessary code changes done by us, in the context of an ordinary C++ .NET project solution. The files that we worked to are basically the same as specified above (in the Cygwin section). The project solution produces a common Win32 command-line executable and you can use it as a standalone application. This standalone executable is provided besides the code project itself. For compiling, though, you must have also the VS .NET 2003 environment. The systems that the executable can surely be run on are Windows XP and Windows 2000. About the rest, we don't know. You might try running it on earlier versions of Windows and report about it to Dr. Laurent Itti in the case of success.

To compile the code or to play with it, you must take the following steps:

1)     Install the Microsoft Visual Studio .NET 2003 IDE on your computer. This is costly software but if you are a student you might have other options to get it rather than buying it (maybe through MSDN Academic Alliance). The IDE is necessary for compiling the code provided here. You can install only the C++ part of it (in case you are short on disk space). Otherwise, it's advisable that you install everything you can.

2)     Get the code from this site, of course. All the necessary changes have already been done in order to make it available for compilation within MSVC++. These changes were mostly about the code arrangement: because the original code is written in GNU style and makes heavy use of templates (both classes and functions), while separating template headers (declarations) and code files (body definitions). This cool feature is still not available in Visual Studio, so we needed to merge these things in a very ugly manner. Also, many standard GNU functions were used in the original code, and they of course were not available in the VS .NET environment. So we needed to bring these functions in by making DLLs containing them. This has become possible only thanks to the great MinGW porting of the GCC compiler to Windows, and to some additional GNU libraries' portings from available from GnuWin32 site (like POPT, LIBC and others) that were assembled for use with MinGW. The scheme was very simple: if there was already some ported library containing the needed function (from GnuWin32 or from MinGW environment itself), we just made a DLL from it using MinGW binutils like dlltool and others. Then, the appropriate function declarations were introduced into the code to make it possible to call them from their DLL. Fortunately, almost all GNU functions used by the ezvision core of the kit have already been ported in one or another manner before us, and we were lucky just having to make DLLs containing them. Generally, some GNU-style function that has not been ported to Windows yet can just be compiled with MinGW on Windows (though not every piece of code can), and then a DLL containing it can be done. This was the case with Linux FPU control functions called feenableexcept and fedisableexcept, for instance. Although we had to change a bit their code, the basic functionality was preserved.

3)     Once you have our organized MSVC++ solution, you can compile it and you'll get your executable cleanly. If you want to go around and add some things, you are welcome. Just don't forget to report to Dr. Laurent Itti about any success you've had in this field. The solution settings are important, do not change them otherwise you may get errors.  These are too long to explain, so just look inside the project settings yourself.

Basically, that's all! You are done and can start working. You can make any additional changes you'd like to, as long as they get compiled. Good luck!

Ale.