Macro Command Reference

The next section contains a partial listing of commands which require parameters. Commands not using parameters are not listed. Parameters must be specified in the indicated order, enclosed in parentheses, and separated by commas. All parameters must be on the same line as the command. Each command must be on a separate line.

Anything that appears in any of the menus may also be used as a command. Those commands that do not require parameters are not listed here. Some, such as 'automatic_undo' toggle a feature on or off. For these commands, using the same command a second time turns the feature back on.

Unless noted otherwise, all parameters can be omitted. This causes the current default setting to be used. However, parameters cannot be skipped. Thus, if you wish to set parameter #3, for example, you also must set parameters #1 and #2.

If a fatal error occurs, the macro is automatically terminated and an error message is displayed showing what line caused the error.

Commands with no parameters are entered as a single word, e.g. erase . Semicolons are optional if there is only one statement per line.

If images are in separate windows, the desired image should be selected before selecting coordinates. Otherwise, the coordinates may be calculated relative to some other image. These coordinates could be well off screen and result in unknowingly corrupting some other image. For example:

image(2);

select(100, 100, 200, 200);

This does not apply to functions like image[][][][], red[][][][], etc. in which the image number is specified.

abs

Returns absolute value of a number

Command	Parameter#	Refers to
acosh	1	value

Returns inverse hyperbolic cosine of a value.

Command	Parameter#	Refers to
asinh	1	value

Returns inverse hyperbolic sine of a value.

Command	Parameter#	Refers to
atanh	1	value

Returns inverse hyperbolic tangent of a value.

Command	Parameter#	Value	Refers to
automaticundo	1	0	never backup image, free backup buffer
		1	manually backup image when user hits Alt-B
		2	Backup image after every major command

Controls undo behavior

b Predefined variable for reading and setting blue component of a pixel in current image.

Ex.: b = r*0.8 + g*0.2 + b*0.1;

Command	Parameter#	Refers to
backgroundcolor	1	red
	2	green
	3	blue

Sets the background color to the color containing the specified red, green, and blue components.

Ex:

        backgroundcolor(255,255,255);

backgroundvalue see bcolor

Command	Parameter#	Refers to
bcolor	1	pixel value

Sets the background color to the specified pixel value, bypassing the conversion from red, green, and blue.

Ex:

        bcolor(255);

between between(a,b,c);
Returns 1 if a$\ge$b and a$\le$c, otherwise returns 0.

blue Predefined variable for reading blue component of pixel of an image. Can only appear on right side of an equation.

Ex.: b = blue[1][0][x+5][y-4];

brightness see color

Command	Parameter#	Refers to
cbrt	1	value

Returns cube root of a value.

Command	Parameter#	Refers to
cdensity	1	x coordinate
	2	y coordinate
	3	diameter

Measures the density of a circular region centered at (x,y) with the specified diameter. The result will depend on whether the image pixel values have been calibrated, and on the settings of the variables COMPENSATE and INVERT, which are automatically set in the densitometry dialogs. These variables reflect whether the pixel calibration is to be used and whether the maximum signal is black or white (Sec.12). They can also be set in a macro. `cdensity' returns the sum of the calibrated density value for each pixel inside the circle, corrected for image depth. Useful for creating macros to measure dot blots and 96-well plates. See also `rdensity'

changebrightness see color

changecolordepth see convert

changecolormap see palette

changepalette see palette

Command	Parameter#	Refers to
changepixelvalues	1	intensity change
	2	red change
	3	green change
	4	blue change

Adds the specified intensity, red, green, and blue to the image or selected region.
Ex.: changepixelvalues(-10,20,30,40);
Adds 20, 30, and 40 to red, green, and blue and also subtracts 10 from intensity.

Command	Parameter#	Refers to
changesize	1	x factor
	2	y factor

Changes size of current image. Both x and y factors must be $>$ or $<$ 1.
Ex.:changesize(0.5, 0.4);
changesize(2.5, 6.2);

changetitle see title

close Unloads currently selected image.
Use 'select_image' command to select an image.)
Don't confuse with fclose.

Command	Parameter#	Refers to
color	1	change in red for color portion
	2	change in green for color portion
	3	change in blue for color portion
	4	change in hue for color portion
	5	change in saturation for color portion
	6	change in value for color portion
		If the entire area is monochrome,
		parameters 1-5 are ignored.

Changes RGB or HSV color in current image or selected region.

Examples:To increase the red in a color image by 10:
color(10); or color(10,0,0);
To increase the blue in a color image by 10: color(0,0,10);
To increase the brightness in a color or monochrome image by 23:
color(0, 0, 0, 0, 0, 23); or lighten(23);
The color, brightness, and color_brightness commands are synonymous.
color(0,20,0,-5); increases the red by 20 and decreases the blue by 5
Don't confuse with setcolor().

colorbrightness see color

Command	Parameter#	Refers to
compositergb	1	Image number for red (must be an 8-bit image)
	2	Image number for green (must be an 8-bit image)
	3	Image number for blue (must be an 8-bit image)

Creates a composite 24-bit color image from 3 8-bit images representing red, green, and blue intensities. All three images must be of identical size. The color or contrast commands may be used to fine-tune the color balance of the composite image.

Example

compositergb(4, 5, 6); creates a new color image no. 7
compositergb("myred", "mygreen", "myblue");

Command	Parameter#	Refers to
contrast	1	change in red contrast for color portion
	2	change in green contrast for color portion
	3	change in blue contrast for color portion
	4	multiplies hue by a factor (100 = no change).
		Note that hue is expressed in degrees, so a hue
		of 360 is the same as 0.
	5	changes saturation
	6	changes value (intensity). This parameter
		also affects grayscale images.

Changes contrast

Note:
To change contrast of a grayscale image, use ``intensity''.
If no parameters are given, the ``contrast'' command activates the graphical Color/Contrast control.

Examples:
To increase blue contrast in a color image by a factor of 1.5:
contrast( 100, 100, 150);

The following two commands have an identical effect:
contrast( 100, 100, 100, 100, 100, 234);
intensity( 234 );

Command	Parameter#	Refers to
convert	1	bits/pixel to convert image
		to (must be 8, 16,24, or 32).

Changes image depth

Command	Parameter#	Refers to
cos	1	radians

Returns cosine of a value.

Command	Parameter#	Refers to
cosh	1	value

Returns hyperbolic cosine of a value, i.e. (exp(x) + exp(-x)) / 2

countgrains - same as findspots

createimage - see new

createresizeimage - see new

d Predefined variable for reading calibrated value of a pixel. This is the pixel value scaled according to user-supplied calibration values.

Ex.: print("Elevation in topographical map is ",d);

Command	Parameter#	Refers to
crop	1	upper left x
	2	upper left y
	3	lower right x
	4	lower right y

Crops the current image, using specified boundary.

Ex.: crop(100,100,200,200);

Command	Parameter#	Refers to
darken	1	pixel value to subtract

Makes image darker by subtracting specified value from each pixel. Suitable for grayscale but not indexed-color images. See `lighten'

Command	Parameter#	Refers to
densitometry	1	x1 1st x coordinate
	2	y1 1st y coordinate
	3	x2 2nd x coordinate
	4	y2 2nd y coordinate
	5	x3 3rd x coordinate
	6	y3 3rd y coordinate
	7	x4 4th x coordinate
	8	y2 4th y coordinate
	9	pixel compensation
	10	calibration factor

Performs strip densitometry on a rhomboidal region, starting from the line defined by (x1,y1) - (x2,y2). Subsequent samples are taken at 1-pixel intervals parallel to this line, in the direction toward (x3,y3) - (x4,y4). See Sec. 7.10. The first 8 parameters must be present or an error message is displayed. The x and y values must be provided in raw pixel coordinates, where (0,0) represents the upper left corner of the screen. Future versions of tnimage will allow x and y values to be specified in user-calibrated units.

If argument 9 is a 0 or omitted, no ``pixel compensation'' is performed. A 1 causes the pixel values to be translated through the image's OD table (gamma table), and a 2 converts the pixel values to their Z calibration value. This will change the measured signal.

If argument 10 is provided, the densitometry results are multiplied by this value.

Example: densitometry(20,40,160,160,340,700,350,800);

The parameters need not be numbers; as with all macros, any expression entered where a number is expected will be evaluated. Thus, for example, if the image has been calibrated, you can use the calibration coefficients that are displayed in the Image Calibration dialog to define a rhomboidal region in terms of calibrated units such as inches. These numbers are also available as the predefined variables Q00 to Q09 for the first dimension calibration coefficients, Q10 to Q19 for the 2nd dimension coefficients, and Q20 to Q29 for the 3rd dimension coefficients. For example, instead of a raw x screen coordinate of 20, you could enter the value in inches, multiplied and added to the appropriate Q00 to Q29 factors that would give a value of 20.

Since the formulas can be saved on disk, it is only necessary to figure out which coefficients to use once.

density Predefined variable for reading calibrated value of a pixel in an image. Can only appear on right side of an equation.

Ex.: d = density[1][0][x][y];

Command	Parameter#	Refers to
down	1	Image no.
	2	distance

Moves specified image down by the specified number of pixels. If no image is specified, the current image is moded. If no distance is specified, distance is the current shift value (change with the gray +/- keys)

drawbox - see drawrectangle

Command	Parameter#	Refers to
drawcircle	1	starting x
	2	starting y
	3	diameter in pixels
	4	color
	5	linewidth
	6	antialiasing (0 or 1)
	7	pixel drawing mode (SET, XOR, etc.)

Draws a circle at the specified screen coordinates. 0,0 is upper left of the display. Do not confuse with `circle' which opens the interactive circle dialog. The color is specified in the pixel depth of the image.

Ex.: drawcircle(100,100,8);

drawfilledbox see drawfilledrectangle

Command	Parameter#	Refers to
drawfilledrectangle	1	starting x
	2	starting y
	3	ending x
	4	ending y
	5	color
	6	pixel interaction mode

Draws a rectangle between the specified screen coordinates and fills it with the current foreground drawing color. 0,0 is upper left of the display.

Ex.: drawfilledrectangle(100,100,200,200);

Command	Parameter#	Refers to
drawlabel	1	string to draw
	2	starting x
	3	starting y
	4	0=horizontal, 1=vertical
	5	0=no background, 1=draw background
	6	foreground color
	7	background color

Draws specified string at designated screen coordinates. Do not confuse with `label' which opens the interactive label dialog. If param. 5 is 0, only the foreground pixels are set. If it is 1, the label is drawn in a filled rectangular box. 0,0 is upper left of the display.

Ex.: drawlabel("Elevation 2100 ft",100,100,200,200);

Command	Parameter#	Refers to
drawline	1	starting x
	2	starting y
	3	ending x
	4	ending y
	5	color
	6	pixel interaction mode

Draws a line at the specified screen coordinates. 0,0 is upper left of the display. Do not confuse with `line' which opens the interactive line dialog. Drawing is done in the current drawing color.

Ex.: drawline(100,100,200,200);

Command	Parameter#	Refers to
drawrectangle	1	starting x
	2	starting y
	3	ending x
	4	ending y
	5	color
	6	pixel interaction mode

Draws a rectangle between the specified screen coordinates. 0,0 is upper left of the display.

Ex.: drawrectangle(100,100,200,200);

duplicate

Makes a copy of current image.

Makes an exact copy of image
Ex.: duplicate("myimage");

duplicate(2);

else Use with 'if'

Ex.: if(i>234) i=255; else i=0;

erase - Begins spray erase mode. Click over areas to restore from image backup. Size of erased area is determined by spraysize in Config dialog. Click Cancel to stop.

exit	Quits the program without asking if you want
	to save your changes. Useful when running tnimage
	macros in batch mode (See ``Batch-mode processing'').

exp

Returns exponential of a value (e raised to power x)

evaluate

evaluates expression once, putting answer in message box.

Ex: evaluate(sqrt(k));

executeplugin see plugin

Command	Parameter#	Refers to
fclose	1	filename

Closes the previously-opened file. Unlike C, does not use a file pointer. Do not confuse with `close'.

Ex.: fclose("myfile.dat");

Command	Param.#	Refers to	Value
fft	1	Direction	1 Forward
			2 Reverse
			3 Convolute 2 images
			4 Deconvolute 2 images
			5 Change display only
	2	Display	1 Real
			2 Imaginary
			3 Power spectrum
	3	Image #2 (only required
		for deconvolution)

Performs Fourier transform on image
Examples:
fft(1); (forward fft of current image)
fft(4, 1, 8); (deconvolute current image with image 8 and show real values)

Command	Param.#	Refers to	Value
fftdisplay	1	Display mode	0 Original image
			1 Real
			2 Imaginary
			3 Power Spectrum

Controls whether to display original image, or real, imaginary, or power spectrum components of FFT'd image.

Examples: fftdisplay(1);

Command	Param#	Refers to	Value
file_format	1	Format
			-1 (automatically detect)
			0 NONE
			1 TIF
			2 PCX
			3 IMA
			4 IMG (Frame grabber)
			5 GIF (GIF87a)
			6 IMM
			7 GEM
			8 IMDS
			9 RAW
			11 JPG
			12 TARGA (Targa RLE)
			16 BMP (Windows bitmap)
			...etc.
			23 ASCII
			100 first custom format
			101 2nd custom format
			...etc.
			This will supercede the image's
			existing default file format for
			the duration of the macro.

Sets the default file format for loading and saving images.
Example: fileformat(5); = sets default format to GIF

These numbers correspond to the const definitions in the file xmtnimage.h. Check this file in case a new file format has been added.

Command	Param#	Refers to	Value	Meaning
filter	1	filter type	0	low pass
			1	high pass
			2	laplace
			3	background subtract
			4	background flatten
			5	noise (median)
			6	sharpen /
			7	sharpen |
			8	sharpen -
			9	sharpen $\backslash$
			10	edge detect -
			11	edge detect |
			12	sobel
			13	remove low freq.
			14	rank leveling
			15	engrave
			16	multiplicative sobel
			17	spatial difference
			18	maximize local contrast
			19	user-defined
	2	kernel size:	1	3x3
			2	5x5
			3	9x9
			4	15x15
	3	amount of
		filtering	1-100
	4	range (median filter)
	5	kernel multip.	any integer
	6	max background	0	black
			1	white

Filters current image or selected area.

Examples:

filter(5, 1, 3, 10, 1, 1); Filters the currently-selected image or area using a 3x3 median filter, with a filtering level of 3, a range of $\pm$10, kernel multiplier of 1, and white declared as the background.

filter(12, 2); Filters the currently-selected image or area using a 5x5 Sobel filter.

Command	Param#	Refers to	Value	Meaning
findspots	1	method		Which method to use
			1	1=quick segmentation
			2	2=neural networks
			3	3=differencing
	2	threshold	0-1	Threshold (0 to 1)
	3	size	0-20	Size (for differencing
				method only)
	4	match weight	0-1	Weight for match (0-1, used
				for neural networks only)
	5	mismatch weight	0-1	Weight for mismatch (0-1, used
				for neural networks only)
	6	labels	0	no labels
			1	print labels
	7	label color	0-$\infty$	color for labels
	8	graph	0	no graph
			1	graph of size distribution
	9	signal distrib.	0	no graph
		graph	1	graph of signal distribution
	10	rectangles	0	draw bounding rectangle
			1	don't draw rectangle
	11	minimum size	0-any integer	Minimum size (for quick
				segmentation only)
	12	maximum size	0-any integer	Maximum size (for quick
				segmentation only)
	13	save data	0	don't save
			1	save in file
	14	filename		file to save results

Finds grains or spots in image. For simplicity, all 3 types of grain counting use the same parameters. This means not all parameters are used by all methods, but saves retyping if you decide to change methods.

Example: findspots(1, 0.7, 0, 0, 0, 1, 255, 1, 0, 1, 2, 1000, 1, test.data)

Counts grains using quick segmentation method, using a threshold of 0.7, printing labels in color 255, draws a size distribution graph, puts a rectangle around each spot, ignoring spots smaller in size than 2 or larger than 1000, and saves the result in file "test.data". If test.data already exists, the program will ask whether you wish to overwrite it. If the filename is omitted, you will be prompted for a filename.

This macro also sets the constants SPOTS and GRAINS, which can be used in mathematical expressions.

Command	Parameter#	Refers to
fopen	1	filename

Opens the designated file for writing. Unlike C, does not use a file pointer. Do not confuse with open, which loads an image from disk.

Command	Parameter#	Refers to
for	1	initializer
	2	condition
	3	increment

Executes following statement list as long as condition 2 is true. Statement list must be enclosed in braces. Parameters must be separated by semicolons (;).

Ex:

        for(k=0; k<5; k++)
        {  print("k is ",k,"\n"); }

Command	Parameter#	Refers to
foregroundcolor	1	red
	2	green
	3	blue

Sets the foreground color to the color containing the specified red, green, and blue components.

Ex:

        foregroundcolor(255,255,255);

foregroundvalue see fcolor

Command	Parameter#	Refers to
fcolor	1	pixel value

Sets the foreground color to the specified pixel value, bypassing the conversion from red, green, and blue.

Ex:

        fcolor(255);

Command	Parameter#	Refers to
frame	1	frame to display

Changes current frame of multi-frame image.

Example: frame(172);
Jumps to frame #172 of the current multi-frame image.

freegraincountingarrays - After grain counting, the grain data arrays remain allocated permanently, in case user decides to reanalyze it. This command will free about 500K of memory. Don't use spotsize(), spotx(), spoty(), or spotarea() after executing this command.

g Predefined variable for reading and setting green component of a pixel in current image.

Ex.: g = r*0.8 + g*0.2 + b*0.1;

Command	Param#	Refers to
getstring	1	Prompt string

Displays a box displaying the specified prompt string, which requests a string. Returns the string to your macro. (See also input())

Ex.: f = getstring("Enter a filename");

Command	Param#	Refers to
goto	1	line number in macro to execute next.
		A jump to a lower line number causes an
		infinite loop. Press ESC to stop the
		macro.

Jumps to specified line in macro

Ex: if(k$<$5) goto(44);

green Predefined variable for reading green component of pixel of an image. Can only appear on right side of an equation.

Ex.: g = green[1][0][x+5][y-4];

i Predefined variable for reading and setting pixel intensity value of a pixel in current image.

Ex.: i+=50;

if

Ex.: if(i$>$234) i=255; else i=0;

im Predefined variable for reading and setting imaginary component of Fourier transform of current image.

Ex.: im = im/1000 + imag[1][x+5][y-4];

imag Predefined variable for reading imaginary component of Fourier transform of an image. Can only appear on right side of an equation.

Ex.: im = imag[1][x+5][y-4];

image Predefined variable for reading pixel value of an image. Can only appear on right side of an equation.

Ex.: i = image[1][0][x+5][y-4];

imageregistration See registration

Command	Param#	Refers to
input	1	Prompt string

Displays a box displaying the specified prompt string, which requests a number. Returns the number. (See also getstring())

Ex.: a=input("Please enter a number");

Command	Parameter#	Refers to
intensity	1	changes value (intensity) of color or
		grayscale images by some factor (100=no change).

Note:
To change the RGB components of a color image separately, use ``contrast''.

Example:
To increase intensity contrast by a factor of 1.5: intensity(150);

The following two commands have an identical effect:
contrast( 100, 100, 100, 100, 100, 234);
intensity(234);

Command	Parameter#	Refers to
invertcolors	1	upper left x
	2	upper left y
	3	lower right x
	4	lower right y

Inverts colors between specified screen coordinates. If no arguments are given, it inverts the entire current image.
Ex;: invertcolors(100,100,200,200);

invertregion see invertcolors

Command	Parameter#	Refers to
left	2	distance

Moves specified image left by the specified number of pixels. If no image is specified, the current image is moded. If no distance is specified, distance is the current shift value (change with the gray +/- keys)

Command	Parameter#	Refers to
lighten	1	pixel value to add

Makes image lighter by adding specified value to each pixel. Suitable for grayscale but not indexed-color images. See `darken'

ln

Returns natural logarithm of a value

load - see open

Command	Param#	Refers to
loadfft	1	filename

Opens the specified Fourier-transform file (which is in ASCII format) See sec. 7.19.2 for details on the format.

Command	Parameter#	Refers to
localcontrast	1	step

Performs local contrast maximization using the specified step value.

log

Returns natural logarithm of a value

log10

Returns base 10 logarithm of a value

Command	Param#	Refers to	Value
macro	1 Macro	Control is transferred
	file	to the first line of the new macro. After
	name	the new macro is finished, the old macro
		continues. There is no limit on the depth
		of nested macros except as imposed by
		available memory. Do not create recursive
		macros (macros which call themselves
		directly or indirectly).

If an argument is given, it executes the current macro; otherwise, it opens the macro editor. Not useful in macro editor.

Command	Param#	Refers to
mask	1	image no. to change
	2	image no. for mask
	3	mode
		1 Mask (1&=2)
		2 Inverse Mask (1&= 2)
		3 Add (1+=2)
		4 Subtract (1-=2)
		5 Multiply (1*=2)
	4	x offset in pixels
	5	y offset in pixels

Performs image masking.
Ex: mask(1,2,3,0,0); adds image 2 to image 1 with no offset
mask(1,2,4,2,2); subrract image 2 from image 1, with image 2 shifted down and right by 2 pixels.

Command	Parameter#	Refers to
max	1	expression
	2	expression

Returns value of the larger of two expressions

Ex.: i=max(i-100, 0);

Command	Parameter#	Refers to
maximize,	1	0=maximize red
maximizecontrast		1=maximize green
		2=maximize blue
		3=maximize intensity

Maximizes contrast in current image or selected region.

Example: maximize 2;
Maximizes blue contrast.

If no parameter is given, (i.e., maximize; ) it maximizes the intensity.

maximizecontrast see maximize

Command	Param#	Refers to
message	1	Text to put in message box

Displays an information box containing the specified text.

Command	Param#	Refers to	Value
messages	1	Message state	0 off
			1 on

Controls message box behavior. Setting messages to 0 disables messages, including all requests for confirmation and requests for filenames. Messages are automatically re-enabled after the macro ends. Useful in batch mode. Turning messages off is dangerous and should only be used in fully-debugged macros. If messages are turned off, a macro could overwrite files, unload images, create a file in a non-standard format, or exit without asking for confirmation.

Ex: messages(0);

Command	Parameter#	Refers to
min	1	expression
	2	expression

Returns value of the smaller of two expressions

Ex.: i=min(i*2, 255);

move Toggles state of `move/copy' button, which determines whether dragging on a selected area erases the original when it moves the object.

Command	Param#	Refers to
moveto		Reposition an image
	1	x coordinate
	2	y coordinate

Command	Parameter#	Refers to
movie	1	msec between frames

Starts a movie. Ex.: movie(1000);
Starts a 1 frame/sec animation of current image. The command version may be faster than using the dialog box because those Motif widgets can be a tad slow.

Command	Param#	Refers to	Value
new
	1	Method for obtaining image
		coordinates.	1 Use mouse
			2 Use specified coords.
			3 Copy another image
			4 Resize image using
			specified coordinates
	2	Border	0 No border
			1 Add border
	3	x size (in pixel units)
	4	y size (in pixel units)
	5	x position (0,0 = upper left)
	6	y position (0,0 = upper left)
	7	Number of frames for image
	8	0=put on main window, 1=separate window
	9	0=Don't search for edge when creating
		multiframe images 1=search
	10	Should subimages be aligned in panel (0 or 1)
	11	No. of columns to create in panel
	12	Left x coordinate
	13	Upper y coordinate
	14	Right x coordinate
	15	Lower y coordinate
	16	X Spacing between subimages in panel
	17	Y Spacing between subimages in panel

Creates a new image. Not all options are used for each method.

null - unclicks null buttons (see ``Custom buttons'').

Command	Parameter#	Refers to
open,	1	filename (can include wildcards)
load	2	x position for upper left corner
	3	y position for upper left corner
	4	x size (0 to 1) (1=full size)
	5	y size (0 to 1)

The remaining arguments (6 to 15) are used only for reading raw images.

Command	Parameter#	Refers to	Value	Meaning
open,	6	platform	0	PC
load			1	Mac
			2	IBM
	7	color type	0	RGB color
			1	grayscale/indexed color
			2	CMYK color
	8	bit packing	0	TIF-like
			1	GIF-like
			2	none
	9	x size in pixels
	10	y size in pixels
	11	No.of bytes
		to skip at start
		of file
	12	image bits/pixel
	13	red bits/pixel
	14	green bits/pixel
	15	blue bits/pixel
	16	black bits/pixel

Loads an image from disk

Examples:
load(myimage.tif.gz, 100, 100, 1, 1); Decompresses and reads myimage.tif.gz from disk, positions it at (100,100), at full size. Quotation marks are optional, since the argument must be a string.

The most recently loaded image becomes the currently-selected image for other operations.

Example: Load an image of raw bytes.
fileformat(9);
load(raw.img, 0, 0, 1, 1, 0, 1, 0, 382, 362, 10, 8);

The first command is necessary to override the automatic file detection, which would otherwise display a message ``Invalid file type''.

The second command loads the image at x=0, y=0, x size=100%, y size=100%, platform=PC,color type=indexed color, x size=382 pixels, y size = 362 pixels, skip 10 bytes, and interpret data as 8 bits/pixel.

If a large number of raw byte images having identical parameters are to be read, it is easier to create a custom file type and define these values as the defaults. This will eliminate repetitive retyping of the arguments.

Do not confuse with fopen, which opens a disk file for writing in a macro.

openimage see open

Command	Param#	Refers to	Value
palette	1	Palette	1 - gray scale
		number	2 - spectrum
			3 - multi colors 1
			4 - multi colors 2
			5 - multi colors 3
			6 - RGBI
			7 - black to green
			8 - zebra (useful for testing image authenticity)
			$>$9 = palette no. 9-10000
			-1 - Other (random)
			-2 = original image palette
			-3 = original image palette
			-4 = original background palette

Sets colormap of current image

Command	Param#	Refers to	Value
pasteimage	2	Mode	1 Background transparent part of region
			2 Background visible part of region
			3 Visible part of region background
			4 Transparent part of region background
			5 Stencil transparent part of region background
			6 Entire region background

Sets paste mode for subsequent ``paste'' commands and starts interactive pasting.

pi

Returns 3.1416..

Command	Param#	Refers to	Value
pixel_interact_mode		Pixel	1 Overwrite
		inter-	2 Maximum
		action	3 Minimum
		mode	4 Add
			5 Subtract new - old
			6 Subtract old - new
			7 XOR
			8 Average
			9 Superimpose

Sets global method for putting pixels on screen

Command	Parameter#	Refers to
pixels	1	image no.

Returns total no. of pixels in specified image. The predefined variable PIXELS gives the no. of pixels in the current image.

Command	Parameter#	Refers to
pow	1	expression 1
	2	expression 2

Returns expression 1 raised to the power of expression 2

Ex.: i=pow(i, 1.23);

Command	Parameter#	Refers to
print	1,2,...	a variable name, expression, or string const

Prints the specified items to stdout and flushes the output stream.
Ex.:

    print("And the answer is...:\t", 21*sqrt(4), "!!!\n");

Note: Char consts such as (newline) are placed in double quotes, same as string constants. String variables are not yet supported. There can be any number of parameters. No formatting strings or type specifiers are needed. Any numeric expressions are evaluated before being printed.

Executing `print' with no arguments calls the Print Image dialog.

plugin	1	Plugin pathname
	2...20	Arguments to pass to plugin

Ex: plugin(plugin, 100, 200, 300, "stuff", 500);

quit Quits the program and asks if you want to save your changes.

r Predefined variable for reading and setting red component of a pixel.

Ex.: r = r*0.8 + g*0.2 + b*0.1;

Command	Parameter#	Refers to
rand	1	random seed

Returns a random number between 0 and 1.

Ex.: i += rand(2)*4;

Command	Parameter#	Refers to
rdensity	1	x1 upper left x coordinate
	2	y1 upper left y coordinate
	3	x2 lower right x coordinate
	4	y2 lower right y coordinate

Measures the density of a rectangular region centered between (x1,y1) and (x2,y2). The result will depend on whether the image pixel values have been calibrated, and on the settings of the variables COMPENSATE and INVERT, which are automatically set in the densitometry dialogs. These variables reflect whether the pixel calibration is to be used and whether the maximum signal is black or white (sec.12). They can also be set in a macro. `rdensity' returns the sum of the calibrated density value for each pixel, corrected for image depth. See also `cdensity'

re Predefined variable for reading and setting real component of Fourier transform of current image.

Ex.: re = re/1000 + real[1][x+5][y-4];

read see open

readfft see loadfft

real Predefined variable for reading real component of Fourier transform of an image. Can only appear on right side of an equation.

Ex.: re = real[1][x+5][y-4];

red Predefined variable for reading red component of pixel of an image. Can only appear on right side of an equation.

Ex.: r = red[1][0][x+5][y-4];

registration

Warps an image to align an arbitrary number of user-defined fixed points in both images. Currently can only be done interactively.

Command	Parameter#	Refers to
resize	1	new x size in pixels
	2	new y size in pixels

Resizes window and image buffers for image. Image data remain unchanged in upper left corner of newly resized window. Useful for resizing to power of 2 for FFT, or in creating composite images. Use ``changesize'' to rescale the image data.

resizeimage see new

resizewindow see resize

restore restores image from backup

restoreimage see restore

Command	Parameter#	Refers to
right	2	distance

Moves specified image right by the specified number of pixels. If no image is specified, the current image is moded. If no distance is specified, distance is the current shift value (change with the gray +/- keys)

root Puts current image on root window.

rootoff Removes current image from root window.

rootpermanent see wallpaper

Command	Parameter#	Refers to
rotate	1	degrees
	2	0=no alias, 1=antialias

Rotates current image. Default is to use antialiasing.
Ex.: rotate(45.32);
rotate(264.1, 1);

Command	Parameter#	Refers to	Value
save	1	filename
	2	file format	see under ``file_format'' for
			permissible values
	3	bits/pixel	(Any value between 1-32).
	4	compress	0=no compression 1=compress file

Saves image to disk file

The bits/pixel be a legal value for the specified format otherwise it is a fatal error. If omitted, it uses the image's current bpp. Example: save(test.tif, 0); Creates a TIFF file named ``test.tif'' using the currently-selected area or image.

If no arguments are given, the image's original filename and format will be used. Use `file_format' to override the default image format. It may be necessary to change the filename extension in case the file is to be read by file viewers, which may require a specific file extension. If a macro tries to save a file without specifying a filename, a fatal error occurs, terminating the macro. If `compress' is set, the current external compression programd will be used. This will be in addition to any compression imposed by the file format itself, so it is not very useful for GIF or JPEG formats.

saveimage see save

Command	Parameter#	Refers to
select	1	upper left x coord.
	2	upper left y coord.
	3	lower right x coord.
	4	lower right y coord.

Sets boundary for other operations such as contrast. The coordinate values are relative to the upper left corner of the screen (= 0,0). Select_region is cancelled by select_image and vice versa. All 4 parameters must be given.

Example: select_region(100, 100, 200, 200);
This has the same effect as clicking-and-dragging the mouse from (100,100) to (200,200).

Command	Parameter#	Refers to
selectimage	1	image no.

Sets current image
NOTE: Image numbering changes unpredictably when an image is unloaded.

Example: selectimage(5);
Has the same effect as double-clicking on image #5.

select_region , selectaregion see select

separatergb Separates current image into 3 8-bit grayscale images representing red, green, and blue color planes. See ``compositergb''.

set Sets a variable.
Ex.: set(k=5);
Iteration is prevented for the command in parentheses (which need not be an assignment). If you typed k=5; by itself, the program would iterate through every pixel in the image, setting k to 5 repeatedly.

Command	Parameter#	Refers to
setbackgroundcolor	1	color
or	1	red
	2	green
	3	blue

Sets background color used by backspace and delete keys. Arguments should be appropriate for the screen depth, e.g., on a 24-bit display use setbackgroundcolor(127,127,127) or setbackgroundcolor(8355711).

setbcolor see setbackgroundcolor

Command	Parameter#	Refers to
setcolor	1	color
or	1	red
	2	green
	3	blue

Sets foreground drawing color. Arguments should be appropriate for the screen depth, e.g., on a 24-bit display use setcolor(127,127,127) or setcolor(8355711) .

setfcolor see setcolor

setforegroundcolor see setcolor

Command	Parameter#	Refers to
setpixel	1	x coord.
	2	y coord.
	3	color
	4	pixel mode

Sets a single pixel at specified screen coordinates. If specified, color is a number appropriate for the bits/pixel of the screen; otherwise it uses the current drawing color. Pixel mode - see ``pixel interact mode''. After setting a number of pixels, use the command "repair" to rebuild the display.

shiftframe see shift

Command	Parameter#	Refers to
shift	1	x pixel distance
	2	y pixel distance

Shifts a single frame of the current image in its image buffer for alignment with other frames.

Example: shift(-20, 34);
Moves current frame left 20 and down 34 pixels.

shift-enter Pressing Shift+Enter simultaneously executes a single line in the macro. Use with caution, because the command may iterate over all the pixels in the image, even if the overall macro restricts it to a small loop. Clicking on the Execute button executes the macro starting at the current cursor position.

shrink see changesize

Command	Parameter#	Refers to
sin	1	radians

Returns sine of a value.

Command	Parameter#	Refers to
sinh	1	value

Returns hyperbolic sine of a value, i.e. (exp(x) - exp(-x)) / 2.

size see changesize

Command	Parameter#	Refers to
spray	1	Spray mode
		1 Fine spray
		2 Diffuse spray
		3 Math spray
		4 Filter spray
		5 Erase spray

Begins spraying things when left mouse button is clicked. Lick the main ``Cancel'' button to stop.

Command	Parameter#	Refers to
spotsignal	1	spot number

Returns total signal in a spot or grain

After performing a grain counting, the constants SPOTS and GRAINS are automatically set to the number of grains found. The total signal in each spot can be accessed using spotsignal().

Ex:

      print("Total amount of stuff in spot 44 was ", spotsignal(44), "\n");

Command	Parameter#	Refers to
spotsize	1	spot number

Returns size of a spot or grain

After performing a grain counting, the constants SPOTS and GRAINS are automatically set to the number of grains found. The size of each spot can be accessed using spotsize().

Ex:

       print("spot size was ", spotsize(44), "\n");

Command	Parameter#	Refers to
spotx	1	spot number

x coordinate of a spot or grain

After performing a grain counting, the constants SPOTS and GRAINS are automatically set to the number of grains found. The x coordinate of each spot can be accessed using spotx().

Ex:

         print("spot was found at ", spotx(44), spoty(44), "\n");

Command	Parameter#	Refers to
spoty	1	spot number

y coordinate of a spot or grain

After performing a grain counting, the constants SPOTS and GRAINS are automatically set to the number of grains found. The y coordinate of each spot can be accessed using spoty().

Ex:

       print("spot was found at ", spotx(44), spoty(44), "\n");

sqrt

Returns square root of a value

Command	Parameter#	Refers to
step	1	step size

Sets the step size by which an image is moved when you click the large arrow buttons on the information window.

stop Breaks out of currently executing macro. Unlike `break', it terminates execution.
Ex: if(k$>$2000) stop

switchto see selectimage

Command	Parameter#	Refers to
tan	1	radians

Returns tangent of a value.

Command	Parameter#	Refers to
tanh	1	value

Returns hyperbolic tangent of a value, i.e. sinh(x)/cosh(x)

testplugin Same as executeplugin, except plugin prints debugging information to stdout.

textdirection sets direction for labels - 0=horizontal, 1=vertical

Command	Parameter#	Refers to
threshold	1	threshold value (0-1)

Thresholds an image, setting all pixels with density less than the threshold value to 0, all others to 1.

Command	Parameter#	Refers to
title	1	title

Changes title of current image.
Ex.: title("Newtitle");

Command	Parameter#	Refers to
transparency	1	transparency (0-100)

Sets the transparency value for an image.

undo restores image from backup

unload see close

unloadimage see close

unzoom restores zoomed image to normal size

unloadall Unloads all images. If `messages' is `on', you are prompted to save any image that has been modified.

Command	Parameter#	Refers to
unsetpixel	1	x coord.
	2	y coord.

Restores a single pixel at specified screen coordinates from the image backup, if it exists. After unsetting a number of pixels, use the command "repair" to rebuild the display.

Command	Parameter#	Refers to
up	1	Image no.
	2	distance

Moves specified image up by the specified number of pixels. If no image is specified, the current image is moded. If no distance is specified, distance is the current shift value (change with the gray +/- keys)

v Predefined variable for reading and setting density value of a pixel in current image. This is the pixel value corrected for image depth and scaled 0..1.

Ex.: v*=1.1;

w Predefined variable for reading and setting wavelet coefficient of current image

Ex.: w = w/100 + wave[1][x+5][y-4];

wallpaper Puts current image on root window, tiling it if necessary to create wallpaper. If image is animated, animation only continues for the first upper left copy. The root image remains after tnimage exits, but animation will stop.

Command	Parameter#	Refers to
wantimagetitle	1	0=no titles displayed
		1=titles displayed

Sets config option of whether to superimpose image title on upper left of image.

wave Predefined variable for reading wavelet coefficient of a pixel in an image. Can only appear on right side of an equation.

Ex.: w = w/100 + wave[1][x+5][y-4];

whatis see evaluate
Ex: whatis(k);

Command	Parameter#	Refers to
while	1	condition

Executes following statement list as long as condition is true. Statement list must be enclosed in braces.

Command	Parameter#	Refers to
windowborder	1	0=minimal border
		1=images are given a full border

If windowborder is 0, images are given a minimal border and positioned according to the coordinates specified as ``x position'' and ``y position'' in the ``open'' command. If windowborder is 1, images are positioned interactively and are given a title bar. This parameter only has an effect when windows=1. The actual behavior depends on the window manager.

Command	Parameter#	Refers to
windows	1	0=images are placed on main window
		1=images are placed in separate windows

Controls whether images are put in separate windows or on main window.

Command	Parameter#	Refers to
write	1	file name to write data to
	2,3,...	a variable name, expression, or string const

Writes the specified items to specified file using fprintf, then flushes the output. The file must already be opened with fopen. Close file with fclose after writing.
Ex.:

      write("myfile", "And the answer is...:\t", cbrt(74088), "\n");

Note: Char consts such as (newline) are placed in double quotes, same as string constants. String variables are not yet supported. There can be any number of parameters. No formatting strings or type specifiers are needed. Any numeric expressions are evaluated before being written.

x Predefined variable for reading x pixel coordinate.

Ex.: i = image[1][0][x+5][y-4];

y Predefined variable for reading y pixel coordinate.

Ex.: i = image[1][0][x+5][y-4];

zoom zooms image by selected factor

Command	Parameter#	Refers to
zoom	1	Image number
	2	Zoom factor

Ex.:
zoom(1, 2.3); Zooms image no. 1 to 2.3 times its original size.