Getting started with Imalab and Scheme - PRIMA

Getting started with Imalab and SchemeDaniela Hall,GRAVIR-IMAG, INRIA Rhône-Alpes, 38349 St. IsmierDaniela.Hall@inrialpes.fr1 IntroductionThis document summarises the most important commands that are needed for Imalab and Scheme. Section 2 explainsthe imalab command line. Section 3 gives an overview of the Scheme syntax. Section 4 summarises the mostimportant notations in the interaction language Scheme. Section 5 explains how c++ functions are loaded and calledwithin Imalab. Section 6 explains the c++ interaction language. Section 7 explains how a new imalab process can bedeclared and defined. Section 8 explains the most common errors. In section 9 you find instructions on how to playwith the example files.Imalab is an interactive shell for image processing. This document gives basic information on using the shell;another tutorial explains how new image processing facilities can be added into Imalab.Commands typed into the Imalab shell can be expressed in C++ syntax or in Scheme syntax, according to yourpersonal preferences. The most complete documentation on Imalab is given by the home page:http://www-prima.inrialpes.fr/Imalab/This document is growing quickly; in particular, the old documentation written in French is replaced by up-to-dateinformation in English.For an introduction to Scheme please see W. Clinger and J. Rees: Scheme: Revised Report on the AlgorithmicLanguage Scheme. Available on-line athttp://www-prima.inrialpes.fr/Ravi/Scheme/The documentation is useful for recalling a particular command or syntax. The present document summarizes onlythe most common commands for the interaction with Imalab. It is incomplete and not as clearly explained as in theabove mentioned article.Imalab and Ravi use Scheme as interpreter language. Scheme is a LISP dialect and contains LISP’s featuressuch as dynamic list structures, automatic memory management, functional programming and dynamic typing. Thesefeatures are very useful for an interactive shell language. For more details see [1].When using C++ syntax for shell interaction, you have complete access to all functionalities of the Imalab workbench,including automatic memory management, Scheme data and functions. However, if you are to write sophisticatedscript files, it will be useful to have basic knowledge of Scheme: such script files include definitions of shellfunctions which are expressed in Scheme (cf. web page).For this reason, we encourage people to learn the basics of Scheme sooner or later. The Scheme programming languageis very simple and also very powerful. You are not required to take advantage of all the functional programmingtechniques accessible with scheme. The here presented basics are sufficient for your first year. If you do not want totouch on scheme, you may just as will use C++ syntax (Section 6) for this tutorial.2 Starting imalabImalab can be started with many different options. These options affect the initialisation. In particular they determinewhere the images are that are going to be used during the session, how these images are processed, how many screenpositions are displayed. The command is as follows:imalab [Options]1

¨¨2.1 Options-p starts in scheme mode, default is c++ mode. This option needs to stand before the other options.-ia starts in interactive mode (no imalab screen is initialised).-ppm, -tiff, -jpeg, -mpeg gives the image/sequence format.-dir name gives the directory where the images/sequences are searched.-file name specifies a file that contains the image filenames. 1 per line.-screen columnline columnline is a 2 digit number, -screen 31 gives a screen with 3 columns and¢¡£¤1¦¥line.Default is -screen 22. The screen positions are §numbered as follows:-load name loads the file name and executes it.-v verbose mode. Prints information on loaded files.Imalab has different modes:interactive mode: you can type commands in the shell. The default interaction language is c++ like. If youspecify the option -p, the interaction language is scheme. You can switch from c++ to scheme by typingscheme in the shell.continuous mode: the imalab screen is active. This mode has two sub modes.– movie mode: This mode displays an image sequence. The space key allows to switch between moviemode and step mode. Typing q switches to interactive mode.– step mode: the imalab screen is active. Single images are displayed. You can navigate through the imagesof a sequence by using the arrows of your keyboard. The space key switches to movie mode.2.2 Example Imalab commandsimalab -p -ia -ppm starts in scheme mode, interactive mode, and uses images in ppm format. No images arespecified by this command: you will load images manually. The -p option needs to be placed before the other options.Dis-imalab -p -ppm -dir name starts in scheme mode, uses all images with .ppm extension in name.plays the images as a sequence (continuous movie mode). For interaction with screen see section 2.3.imalab -p -mpeg2 /home/desdemona/hall/Walk1.mpg starts imalab in continuous movie modewith sequence Walk1.mpg. To go to interactive mode, type q while mouse is in imalab screen. For interaction withscreen see section 2.3.svideod-mpeg play -ab5 -- -dither color /home/desdemona/hall/Walk1.mpgimalabcreates a video daemon from a .mpg file (you might want to define an alias). This displays a toolbar on your screen.Click pause, rewind. Then start imalab. Imalab without arguments starts imalab in continuous movie mode with asequence given by the video daemon that must be running. An error is produced, if the video daemon is not running.svideod -d/dev/video1 -ab5imalabfirst start video daemon with camera on device /dev/video1, then start imalab. Imalab without arguments starts imalabin continuous movie mode with a sequence given by the video daemon that must be running. An error is produced, ifthe video daemon is not running.(continue) switches from interactive mode to continuous mode.2

(quit) ends imalab. This is equivalent to ctrl-d.Interrupt execution: type ctrl-c. If this does not get you back to the shell, type ctrl-c twice again.2.3 Imalab screenInteraction with the imalab screen are possible in continuous mode, not in interactive mode. To switch to continuousmode type (continue). For screen interaction, place the mouse cursor within the imalab screen window. Use thekeyboard to type commands.q quits continuous mode, goes to interactive mode. Typing (continue) in the shell brings you back to continuousmode.space switches between step mode and movie mode. The current-image and the following images are displayed.arrow up displays frame(t-10) (in step mode). The image cache is by default set to 60 images.arrow down displays frame(t+10) (in step mode)arrow right displays frame(t+1) (in step mode)arrow left displays frame(t-1) (in step mode)mouse click displays circle in all windows (in step mode)3 Basic SchemeA scheme expression can either be a variable or a procedure call.variablename displays the value stored in the location to which the variable is bound.A scheme command is structured as follows: opening parenthesis, function name followed by 0 or several parameters,closing parenthesis. This is true without exception; in particular, arithmetic operators are just functions. Examples:(function no params)(function with 1 parameter param1)(function with 2 parameters param1 param2)Parameters can be anything, numbers, variable names, functions, ... . Typical examples are:(list) function with no parameters, creates an empty list(sin 1.0) function with 1 numerical parameter, computes the sine of 1.0(* 2 5) function with 2 numerical parameters, computes product of 2 and 5(define a 0.0) function with 2 parameters, assigns the value 0.0 to a variable named a(+ 1 4.0 3.2) function with 3 (or more parameters), computes the sum of the parameters.Scheme functions always give a value, which may be of any type: in cases of numerical calculations this is the result.In other cases, the return value can be an object (i.e. an image, a list) or a boolean (#t notes true, and #f notes false).The return value of a function can be assigned to a new variable as follows:(define empty list (list)) initialises a variable with name empty list and assigns the return value of(list) to it.3

(define value (sin 1.0)) initialises the variable value to the sine of 1.0.(define product (* 2 5)) initialises the variable product to the result of (* 2 5)(define sum (+ 1 4.0 3.2)) initialises the variable sum to the result of (+ ...)(set! sum (+ sum product)) sets the variable sum to the value of (+ sum product). The functionset! requires that the variable is already initialised.First thing that people notice while working with scheme are the large number of parentheses in a scheme command.Function values need not necessary assigned to a variable. Often it is more convenient to feed a function result directlyas a parameter for an outer function.(sqrt (+ (* 2 2) (* 3 3))) returns the norm of the vector © .Comments: a semicolon ; comments the remainder of a line (equivalent to // in c++).4 Most frequently used scheme commands4.1 Assignment and display functions(define a 0.0) defines and initialises a global variable(begin body) encapsulates several commands to one expression.It exe-(define (funcname params) body) defines a function funcname with parameters params.cutes body on call.(set!a 4.0) sets a previously defined variable to a value.(let ((var1 init1) (var2 init2) ...) body ) same as begin but the order of the executionis guaranteed. This allows to initialises local variables recursiveley.(let* ((var1 init1) (var2 var1) ...)for the initialisation of other local variables.body) same as let, but allows to use local variables(display-l "a" " " 4.0 " n") produces a 4.00000The minus in display-l is part of the function name and not an operator. In fact, the minus in schemefunction names is used very often. It is a marker that the function is written in scheme. The minus in function namescan never be confused with the minus operator, because scheme uses the polish notation (operators are always the firstargument after a parenthesis).4.2 Other useful scheme specific functions(lambda (x) (+ x x)) This lambda expression evaluates to a procedure. When the procedure is later calledwith an actual argument, the body of the lambda expression is executed and returns its last expression. ((lambda(x) (+ x x)) 4) evaluates to 8.(for-each function alist) runs the function for each element in the list alist.(exact->inexact a) returns a as floating point number (conversion from int to double). Certain c++ functionscan require the conversion of their parameters.(inexact->exact a) returns a as integer (conversion from double to int). The value is rounded.4

(stringify obj) converts object obj to a string. Possible objects are char, int, double, but also variablesand functions that evaluate to char, int or double. stringify can be called with several parameters. Returnedis the concatenated string of all parameters.(define point (cons i j)) defines a pair (i .j).(pair?point) the type test typename? returns true.(car point) returns the car-field (the first field of the pair).(set-car! point 3) sets the car-field of point to 3.(cdr point) returns the cdr-field of point. This is the list of the last element.(set-cdr! point (list 5)) sets the cdr-field to 5.(cadr point) gets the 2nd element of point. This is equivalent to (car (cdr point)). Lists are alsopairs. You can use car to access the first element, cadr to access the second, ... , cadddr to access the fourthelement.(define clist (append alist blist)) appends the lists alist and blist and places the list inclist(list-ref alist num) returns element num of alist.(define filenames (list ))(for-each (lambda (prefix)(for-each (lambda (num)(set! filenames (append filenames (list (stringify prefix num ".ppm")))))(list 1 2 3 4)))(list "frontal" "side"))These commands produce following list ("frontal1.ppm" "frontal2.ppm" "frontal3.ppm""frontal4.ppm" "side1.ppm" "side2.ppm" "side3.ppm" "side4.ppm").4.3 I/O from/to filesI/O is done by ports. You can write or read characters from ports. A port can be connected to a file or the shell.(open-input-file filename) opens input file, returns input port(open-output-file filename) opens output file, returns output port, file is created if it does not exist.(close-input-port port) closes input port.(close-output-port port) closes output port.(display obj port) writes human readable version of object obj to port port.(write obj port) writes machine readable version of object obj to port port.(newline port) writes a newline to port.5

(read port) returns next object parsable from the given input port port.returned.If end of file is reached, eof is(read-char port) returns next character, updating port to point to the next character.(peek-char port) returns next character, without updating port.(eof-object?obj) tests if obj is a end-of-file object.(define out (open-output-file "filename.txt"))(display (+ 3 4) out)(newline out)(close-output-port out)The first line opens an output port with name filename.txt. The file is created if it does not exist. The result of(+ 3 4) is written to the file followed by a newline. The port is closed.4.4 Useful macros(for (i from to step) (begin body )) runs a for loop from to "!# with increment step.4.5 Defining new scheme functions(define (count param1)(for (i 1 (+ param1 1))(display-l i " n")))Here we define a scheme function with name count with one argument that displays on the shell the numbers from0 to param1 separated by a newline. begin starts the body of the function. for is a macro (see useful macros).display-l displays the printable version of objects to the shell.(count 100) This is the call of the newly defined function. It displays the numbers up to 100.(define (sumupto param1)(let ((sum 0))(for (i 0 (+ param1 1))(set! sum (+ sum i)))sum))Here we define a scheme function that sums all integers up to param1. let defines and initialises local variables.set! assigns new values to a variable. A scheme function always returns the value of its last statement. Writing thelocal variable name in the last line, means that its value is returned by the function. After the command (definesum (sumupto 10)) sum holds 55. If the last line is omitted, the call (sumupto 10) returns nothing.5 Functions written in C++5.1 Help functions(help-classes) displays all loaded classes. To access a particular class, you type (help num) with numreferring to the class that you are interested in. If the class that you are interested in is not in the list, you need to loadthe module with a (require ’modMissingModule).(help num) displays information about the item number num in the previously displayed list.If (help num) gives you a default message currently defined as function of 0 or more6

arguments, try (help ClassName FunctionName)./usr/local/include/PrimaVision/.If still not satisfied, look in the header files(help ClassName) displays all member functions of the class ClassName.(help ClassName FunctionName) displays information about the function FunctionName of theclass ClassName.(a-propos name) lists all functions, global variables and classes that contain the string name in theirname. This function is useful when you do not remember the exact name of a function.5.2 Interaction with imagesSee also example file point.scm (section 9).(require ’modModuleName) loads the module ModuleName. It must be a compiled module. Therequire call loads the modules located in the directories of *module-path*. The standard PrimaVisionmodules are modArray, modArrayBitmap, modArrayMatrix, modBitmap, modColorEncode,modFilter, modGeom2D, modList, modListBitmap, modeListGeom2D, modListMatrix,modMatrix, modRegionVS, modTGFilter. You should find the corresponding modName.x.scm andmodName.so in/usr/local/lib/Ravi/Site-Module.The *module-path* and the *ld-path* are set in /.ravi2/paths.scm.(load "test") or (load "test.scm") With the load command local test scripts can be loaded.The directories specified by *ld-path* are searched. File name extensions: Scheme files should have extension.scm. The load command will first look for several extensions.(define img (new TBitmapABGR 256 128)) the new function calls the constructor of the correspondingc++ class and returns a pointer to the object. The object is referenced.Deleting objects under scheme is not necessary. Scheme has automatic memory management. C++ objectsare deleted automatically by the garbage collector when the reference counter is zero. The garbage collector isautomatically called from time to time.(garbage) calls the garbage collector. This is only necessary when very large data structures are manipulatedand you risk to run out of memory before the garbage collector is called automatically.(define img (new-ppm "filename.ppm"))This loads an image from a filename. Typing the variable name without parentheses displays information about thevariable. This is a way to test if the loading is successful.(send img GetPixelFloat i j) The send function ”sends” a method call to a c++ object.the way to execute c++ class methods. (The GetPixelFloat method returns the pixel at position (i, j).This is(send img SetPixel value i j band) The channel band of pixel (i,j) of img is set to value.The order of the color bands can be machine dependent.(send img GetRedImage) returns the red byte image of a multi-band image, independent of the machine.(define float img (send img Convert kFloat)) converts the image of type TBitmapByte, TBitmapABGR,or TBitmapRGB to TBitmapFloat.7

(define byte img (send float img Float2ByteConvert min value max value)) convertsa float image to a byte image. The floating point values between min value and max value are assigned toint between 0 and 255.5.3 Calls of member functions and global functionsWe have several recursive implementations of Gaussian derivatives. The functions that are loaded by (require’modFilter) are global functions based on VanFliet’s article of 95. The functions loaded by (require’modTGFilter) are based on VanFliet’s article of 98. They are member functions of the class hierachy Gaussian-Filter. Gaussian derivatives are defined only for TBitmapFloat. See also example file filter.scm (section 9).(define result image (FGR dX2 float image 2.5)) computes the first derivative in X directionof float image with a sigma of 2.5 and stores it in result image. This is the call of the global functions of the modFiltermodule.(define base (new GaussianFilter5 2.5))(define result image (new TBitmapFloat 256 128))(send base FGR Lx float image result image)First a GaussianFilter5 object with sigma= 2.5 is created (The number 5 indicates, that 5 coefficients are used for thecomputation. The recursive filter approximation is closer to the original Gaussian derivative). The result image isallocated. If the dimensions are smaller than the float image you produce a segmentation fault. The last line computesthe first derivative in X direction and smoothes in y direction.5.4 Interaction with windows(init-screen-wh 1 3 256 128) initialises imalab screen with 1 row and 3 columns of image size 256 x128. The positions are $% '& .(affiche-pos img 0 #f) displays multi-band image img at position 0. (affiche is French for display)(affiche-byte img 1) displays TBitmapByte image img at position 1, using the default color map.(affiche-float img 1 factor) displays a TBitmapFloat at position 1. Negative values are displayedin yellow, positive values are green (default, these can be changed by the SetColorCoeff command). factor givesthe multiplication factor for the float values. I use factors between 0.1 and 100.0.(get-point num) Function returns point at position num in global variable point-list.the command waits for a mouse click within the imalab screen.If num is #f,(get-line num) Function returns line at position num in global variable line-list.command waits for a (button down, drag, button release)-event within the imalab screen.If num is #f, the(get-rectangle num) Function returns rectangle at position num in global variable rectangle-list. Ifnum is #f, the command waits for a (button down, drag, button release)-event within the imalab screen.information on drawing functions are obtained by (help X11Display). Here is an example:(define point (get-point #f))(define old fg (send screen SetForeground "red"))(send screen DrawCross (car point) (cadr point) 5)(send screen SetForeground old fg)(send screen Flush)8

¨¨¨SchemeC++(define c (+ a b)) c = a + b ;(require ’modModuleName) require modModuleName;(help functionname)help functionname(define img (new TBitmapByte w h)) img = new TBitmapByte(w,h);(define img (new-ppm filename)) img = new-ppm(filename);(send img SetPixel val i j)img.SetPixel(val, i, j);(define img2 (FGR dX2 fimg 2.5)) img2 = FGR dX2(fimg, 2.5);(define (func param) (begin body)) func = lambda (param) body;Table 1: Correspondence between c++ and scheme commands.These commands get a point, set the foreground color to red and store the old color in old fg, draw a cross withheight 5 pixels on the screen, set the old foreground color and flush the screen. Flush makes the changes visible.(draw-rectangle 0 "steelblue") draws the rectangle at position 0 of the rectangle-list in steelblueto the first position in the screen. You can use the color standard name. If you want to draw at another position withinthe screen, you need to compute the position with respect to the window’s upper left corner.6 C++ interaction languageAs said before we encourage people to use scheme as interaction language. In this section we explain the principlesof the c++ interaction language.Following commands are important:(toplevel-c++) switches from scheme mode to c++ mode.scheme switches from c++ mode to scheme mode.In table 1 we display corresponding commands in scheme and c++. The semicolon at the end of the line is optional.The c++ mode is convenient to call existing functions and create scripts that consist of a set of commands. It is possibleto define functions in c++ mode ... but these functions will have Scheme syntax!7 Define an Imalab processThis section is for the advanced scheme programmer. Imalab can define a process that treats images from a sequence.The default process is the no process, it simply displays the images of the sequence. You can include any imageprocessing task into a process.The global variable plugin-process-table contains a list of currently available processes. To switch betweenprocesses, use(set-process processname)(continue)To declare a new process you need to define four functions:process-init: initialises variables needed by the process. It is called once before the process starts. For instance,you can put the learning stage of a recognition process.process-image: function responsible for the processing of individual frames. It is called for each frame.process-display: function that displays results. It is called for each frame.9

¨process-step: Calls the functions process-image and process-display in a loop and loads the next image of thesequence.A new process is declared as follows (see example process.scm):(declare-process ’processname process-image process-display process-step)(process-init)8 Error messagesERROR - EVAL- undefined variable:The variable pre is undefined.preAfter you pressed enter, you see the prompt :> instead of the normal = . You miss a closing parenthesis.When (load "filename.scm") produces several pages of text there is a parenthesis error in filename.scm.*** ERROR: list-ref/tail - bad index 10 for list (1 2 3 4 5 6)index error in list-ref.Error in initializationERROR: for dlopen(...imalab tries to run with image sequence, but video daemon is not running. To work with single images or interactivemode, add option -ppm or -tiff or -jpeg to the imalab command. To work with sequences, start video daemonbefore starting imalab.(help TMatrix)= TMatrix unknown;the module containing TMatrix is not loaded. Load the module by (require ’modMatrix).rect= #TypeC(TRectangle *, 8286918)This is an indicator that the module modGeom2D (that contains TRectangle) is not loaded by scheme. Add(require ’modGeom2D)rect= .ERROR - pas de methode (MethodName . #TypeC(Classname *, number))The module that contains class Classname is not loaded by scheme. Add (require ’modModule).9 Example filesI have prepared some example files. As more examples are available, these will be added in this section.The ExampleScripts.tar on http://www-prima.inrialpes.fr/Imalab/Tutorial/ contains allscripts below. An imalab tutorial mode is under construction. Let $SCM DIR be the directory where this tutorialand the example files are located. Make sure that your are in the directory that contains the example files (type cd$SCM DIR if necessary). You exit imalab by typing (quit) or ctrl-d. Emergency stop is ctrl-c three times,followed by (quit) or ctrl-d.Example of using the help functions (file exhelp.scm).emacs exhelp.scm &imalab -p -ia -ppm10

Follow the instructions in exhelp.scm.Example of simple scheme functions (file numbers.scm).emacs numbers.scm &imalab -p -ia -ppmNow follow the instruction of numbers.scm.Example window interaction (file point.scm).emacs point.scm &imalab -p -dir . -ppmNow follow the instructions of point.scm.Example filtering of images (file filter.scm).emacs filter.scm &imalab -p -ia -ppmFollow the instruction of filter.scm.Example process (file process.scm).emacs process.scm &imalab -p -mpeg2 file.mpgtype q while mouse is in imalab window(mpeg2seek mpeg2-stream 0) positions mpeg2 stream on first frame.(load "process.scm") This defines and initialises a new process rectangleYou can use the keyboard events described in section 2.3 to interact with the screen (space to switch to step mode,arrows for navigation, q to return to shell).References[1] A. Lux. The imalab method for vision systems. In ICVS03, Graz, Austria, April 2003.11