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