NIH IMAGE MACRO LANGUAGE NOTES


        By: Jeremy R. Young, Palaeontology Dept., The Natural History Museum, London
        Email: jy@nhm.ac.uk


        1. DOCUMENTATION OF THE MACRO LANGUAGE
        1. The NIH-Image manual, appendix A provides a description of the macro language and menu by menu explanation of the commands.
        2. Reference card - this comes as a macro/text file with NIH-Image and gives an alphabetic listing of the commands.
        3. Inside NIH-Image, a supplementary manual written by Mark Vivino which explains many features of the macro language with examples. This also documents the alternative approach of writing user.p Pascal Code to compile with Image.
        4. Example macros - numerous macro files come with NIH-Image and provide examples of most commands in use (N.B. One way of using these for reference is to import them into a Word-Processor, then all the files can concatenated into a single, very long, file and keywords searched for).
        5. This document - an `alternative' reference file designed to help people who want to use the macro language for biometric work and have no Pascal experience.


        2. GETTING STARTED WITH IMAGE MACROS
        1. Launch Image
        2. Open an Image file
        3. Open an Image Macros file
        4. Do a SaveAs giving another name (to be on the safe side)
        5. Experiment - writing new macros etc. in the text window; loading with the load macros commands (special menu, cmnd-9); activate the image window and test operation.


        3. SYNTAX
        {}- anything inside curly brackets is ignored by the macro language. N.B. Not terminating the brackets will result in errors such as the macro continuing into the next macro.
        [] - array indices. E.g. rUser[1]. In a macro name defines key which will activate the macro, e.g. Macro 'Test [T]'.
        ()- many uses including: conventional uses in mathematical and logical statement e.g. 25:=(7-2)*5; procedure calls e.g. procadd(a,b); function parameters e.g. GetPixel(x,y).
        '..'    - declares a string, used in various functions, e.g. Write('string').
        ;- ends a statement, omission will cause error messages, usually referring to the next line in the macro.
        rtn- always(?) optional, many statements can be included on one line, providing they are separated by semi-colons. Also blank lines can be left in macro files to improve readability.
        ,- separate variables - e.g. when declaring, in procedure calls, in function calls. E.g. GetPixel(x,y).
        space - Usually optional between items, but cannot be introduced within items. Compulsory between string items e.g. SetOptions('Area Mean').
        :- a few special uses.
        '\'- carriage return, useable in most message writing functions.
        :=- arithmetic equals, = can only be used in boolean logic statements. Thus a:=2+3; vs IF a=5 THEN...
        case - Image is not case sensitive, all identifiers (variable and command names etc.) can be written in upper or lower case, e.g. KILLROI or killroi or KillRoi.


        4. PARTS OF A MACRO FILE
        4.1 Var statements
        = declaration of variables
        - placed at the beginning of macros or procedures
        - comments placed on the same line are an easy way of documenting variables

        4.2 Macros
        = Discrete programs called by the operator from within NIH-Image
        - Cannot be nested, call each other etc.... So, if the same code needs to be used in different macros use procedures.

        4.3 Procedures
        = sub-programs called by macros.
        - need to be listed before the macro(s) or procedures that call them
        - using procedures can greatly shorten macro files, improve the general structure of the programming, and simplify revision/development of macro files.
        - it is often helpful when writing macro files that make complex use of procedures to include a simple test macro for each procedure.
        - procedures can be called from inside other procedures, so long as they listed beforte them in the macro file (if not an error will be returned when the macro file is loaded).

        4.4 Comments - anything in curly brackets - {}
        - these do not slow macro execution and do speed macro debugging and rewriting.

        4.5 Menu Manager commands
        - these are included in macro names, the main ones are
        Macro '(-';    create a dividing line in the menu
        Macro 'Test /6'; assign command key 6 to the macro (not very useful as Image already uses most command keys).


        5 VARIABLES
        5.1 Global variables (declared at beginning of macro file)
        - Initially zero, and reset every time macros are loaded.
        - Allow values to be passed between macros.
        - Also often convenient if several macros call the same procedure.
        - If an initiating macro is run then they can conveniently store constants (e.g. hscale, vscale, pi).

        5.2 Macro variables (declared at beginning of macro)
        - Initially zero, and reset whenever the macro is run.
        - Are available to procedures called by the macro.
        - Are not available to other macros.

        5.3 Procedure variables (declared at beginning of proc, OR in procedure statement, e.g.procedure procadd(x,y) - x & y are implicitly declared.
        - Initially zero, reset whenever the procedure is called
        - Only available within the procedure.

        5.4 Measurement Arrays (rLength[], etc.)
        - Although primarily provided for storing the results of measurements these arrays can be used for many purposes and are worth considering as alternatives to variables.
        - Initially zero, when Image is launched.
        - Values NOT reset by loading macros (cmnd-9).
        - Cannot be used in procedure calls - e.g. procadd(rX[4],rY[4]) will return an error message.
        - SetCounter(n) resets values between n and current value of rCount (higher and lower values are unaffected).
        ResetCounter is equivalent to SetCounter(1)
        - Measure issues a SetCounter(rCount+1).
        - Measure; ...; ResetCounter(rCount-1); will have the effect of doing a measure then disposing of the results without affecting anything else.
        - ShowResults only shows values up to rCount, but higher array values are accessible to macro calls.

        5.5 rUser Arrays (rUser1, rUser2)
        - Initially zero, when Image is launched.
        - Values are never reset; unaffected by SetCounter, ResetCounter, etc.


        6. VARIABLE TYPES
        Boolean - These can have two values 0-false or 1-true. Attempting to give boolean variables other values will produce error messages when the values are called in boolean statements.
        Real - real numbers, e.g 2.345
        Integer - whole numbers, e.g. 1,4,8. N.B. By default real numbers rare converted to integers with rounding. The functions Round(n), Trunc(n) and Abs(n) are available for further control.



        7. LOGIC and LOOPs
        7.1 CONDITIONAL OPERATION<BR>     IF THEN BEGIN
            .
            .
            END ELSE BEGIN
            .
            .
            END;
        - Extra complexity can be added by ELSE IF statements etc.
        - The boolean statements can use the operators = < > <= >= with either boolean or numeric variables. If AND or OR statements are used then the sub-statements must be put in braces, e.g. IF (a>5) OR (a<15) THEN...
        - BEGIN and END are not needed if there is only a single statement, e.g. IF .... THEN a:=a+5; instead of IF .... THEN BEGIN a:=a+5; END;

        7.2 CONDITIONAL LOOPS
            REPEAT
            .
            .
            UNTIL ;


            WHILE DO BEGIN
            .
            .
            END;
        - These two forms are different in syntax but very similar in practice.
        - can be complex.

        7.3 INCREMENTAL LOOP
            FOR COUNTER:=VAR TO VAR DO BEGIN
            .
            .
            END;
        - counter should be an integer variable, it will be incremented by one at the end of each loop.
        - Complex arithmetic statements are allowable instead of simple variables/values in the FOR ... TO ... DO statement.
        - The counter can have its value changed by statements inside the loop; e.g. IF found THEN counter:=100;


        8. INTERACTION
        8.1 Getting input from the operator
          - The number of options here is strictly limited, but with ingenuity quite a lot is possible...
        • Button Returns true/false depending on whether the operator is pressing the mouse button. E.g. IF button THEN .... or REPEAT ... UNTIL Button
        • GetMouse(x,y) Returns the mouse co-ordinates.
        • WaitForTrigger Delays macro operation until the mouse button is pressed. E.g. FOR n:= 1 TO 10 DO BEGIN WaitForTrigger; GetMouse(x,y); PutPixel(x,y,1); Wait(0.2); END; By combining WaitForTrigger and GetMouse(x,y) sophisticated conditionality can be written.
          GetNumber('prompt',default)           Gives a simple dialog box to allow input of number. E.g. newy:=('Please input new value',oldy);
        • cmnd-'.' Stops the macro, after it has finished the command it is working on - there may be a delay if it is a complex command (e.g. a convolution), in these cases it is necessary to hold the cmnd-'.' until the macro stops.

        8.2 Displaying output
        Numerous functions display output graphically but the following are specially designed for macro output;

        8.2.1 GRAPHIC FUNCTIONS DEPENDANT ON "CURRENT-LOCATION"
        • MOVETO(X,Y) - sets current-location, as used in the subsequent functions. N.B. Current-location is not set by the mouse position.
        • LineTo(x,y) - Draw line from current-location to (x,y)
        • DrawNumber(n) - Draw number at current-location
        • DrawText('text') - Draw text at current-location
        • Write(e1,e2,..) - Draw text and/or numbers at current-location
        • WriteLn(e1,e2,..) - Draw text and/or numbers at current-location, but with redefinition of curren location.

        8.2.2 NON-GRAPHIC OUTPUT
        • SHOWMESSAGE(E1,E2,..) - displays message in values window. The message will stay after the macro has run until the values window is redrawn - e.g. by use of one of the measuring tools. Useful for displaying progress of a macro, debugging, etc.
              To start a new line use -'/'
              To specify format of number use value:f1:f2 - f1 sets field width, f2 specifies no. of decimal places. The default value of f2 is 4, and changing f2 for display of one value does not affect subsequent values.
        • PutMessage(e1,e2,..) - displays message in a dialog box. Useful for warning messages.
        • Beep - issues a beep. Unsophisticated but often handy.
        • ShowResults - Open the results window


        9. MISSING FEATURES/THINGS YOU CANNOT DO
        • Access numerous constants - many constants can be set, e.g. SetScale(scale,units) but only a very few can be read, and some constants can be neither read nor written. E.g. Pixel aspect ratio, can only be set via the Set Scale dialog box and can only be determined by a macro by measuring a square ROI.
        • Access results Image must know but doesn't want to tell you - a variation on the above. Essentially the only results you can get are those which special routines have been written to provide you with. Other results are unobtainable even if they may have been calculated - e.g. Measure will return the maximum pixel value found, but not the location of this pixel, so forget that as a peak finding approach.
        • Access extra Maths functions - the range of Maths functions provided by NIH-Image is limited, but carefully selected, consult your maths texts to remember how to derive the others. E.g. arctan is provided but not arcsin or arccos. But tan(a)=sin(a)/cos(a) and sin(a)2=1-cos(a)2, so you can get round that shortcoming.
        • Access Maths constants - no mathematical constants are defined. Define them in the macro or write out the number each time. (N.B. pi=3.141592654)
        • Define new arrays - instead exploit the measurement and rUser arrays.
        • Define irregular ROIs - only square and line ROIs can be defined from within the macro language. This is restricting if for instance you have used macro routines to identify a sequence of points defining an object and would then like to measure it.
        • Import data into the measurement arrays.
        • Retrieve overwritten pixels - there is no overlay available in Image so e.g. writing text on an image removes data pixels. The alternative is to work on a duplicate Image, use RevertToSaved (cmnd-R) etc. - there are lots of useful window handling commands in Image.
        • Scroll or zoom windows - tough, you just have to do this using the tools (N.B. cmnd-U unzooms the current window).
        • Work on the plot, or histogram (or any non-image windows), the macro language works essentially on image windows and you cannot e.g. draw results on the plotprofile - although it is possible to make an image file with a picture of the plot and then work on that - see the plotting macros which come with Image.

        Return to: top,
        Main COCCOBIOM Page