Digimizer scripts

A Digimizer script is a block of statements.

A block of statements is a group of one or more statements placed between balanced curly braces { }.

Statements are separated by means of semicolons.

Example:

{
    statement1;
    statement2;
}

A statement can be

• a single statement such as an assignment statement, a flow control statement or a standard procedure.
• a compound statement (or statements block), which is a group of statements enclosed in curly braces { }. They can be used wherever a single statement may be used.

Comments

Any text between // and the end of the line is ignored by the script (will not be executed).

For example, in the following script statement1 will not be executed:

{
    // statement1;
    statement2;
}

Assignment statement

In an assignment statement, a value is assigned to a workspace variable, an image attribute, or a measurement object attribute. The value is a result of an expression.

An expression consists of numbers or text values, variables, operators and functions.

For example, the following statement assigns the value 25.6 to a workspace variable var1. If the variable var1 does not exist, it is created first.

var1=25.6

Increment & Decrement statements

The statement var++ increments the value of workspace variable var by 1; the statement var++ has the same effect as var=var+1

The statement var-- decrements the value of workspace variable var by 1; the statement var-- has the same effect as var=var-1

Regional settings for decimal symbol and list separator

Important: in Digimizer scripts, the program ignores the regional settings for decimal symbol and list separator.

• The decimal symbol is a symbol used to separate the integer part from the fractional part of a number.

  In some countries, a dot is used as a decimal symbol (e.g. PI is written as 3.14), but in other countries it is a comma (PI = 3,14).

• The list separator is used to separate the arguments in a function.

  In some countries, the list separator is a comma. E.g. in Excel, the arguments for the POWER function are written as POWER(x,y). In other countries a semicolon is used: POWER(x;y)

The decimal symbol and list separator can be selected in the Windows control panel, section Region and Language.

Digimizer will use these regional settings in its output, but in Digimizer scripts these regional settings are ignored and

• you must use a dot for decimal symbol, e.g. i=1.5
• you must use a semicolon for list separator, e.g. Sharpen(3,50)

Flow control statements

if (condition) { statementsIfTRUE } [ else { statementsIfFalse } ]

The expression condition is evaluated. If the result is 1 (TRUE), then the block of statements statementsIfTRUE is executed.

The else clause is optional. If it is present, then the statements statementsIfFALSE are executed when the condition is 0 or FALSE.

while (condition) { statements }

The expression condition is evaluated. If the result is 1 (TRUE), then the block of statements statements is executed.

Next, the expression condition is re-evaluated. If the result is 1 (TRUE), then the block of statements statements is executed.

This is repeated as long as condition evaluates to 1 (TRUE).

foreach object { statements }

Use the foreach object statement to loop through all measuring objects. The object can be referenced to by means of the obj identifier.

Objects have attributes and methods, listed in the tables below.

In the following example, all objects in the right half of the image are deleted:

Foreach loops cannot be nested - you cannot have a foreach loop within another foreach loop.

break

Use the break statement to interrupt and exit a while or foreach loop.

halt

Use the halt statement to end the script. The halt statement can be used anywhere in the script.

You can also interrupt the script by pressing the Esc key.

Image attributes

The image can be referenced to by the identifier img. The image attributes are listed in the following table. All attributes are numbers, except where indicated.

img.Width	the width of the image, in pixels (this value cannot be set by the script)
img.Height	the height of the image, in pixels (this value cannot be set by the script)
img.Unit	the number of pixels in one unit
img.UnitStr	the selected unit (centimeter, millimeter, micrometer, etc.) (text value)
img.UnitShort	the abbreviation of the selected unit (cm, mm, µm, etc.) (text value)

Object attributes and methods

The object can be referenced to by the identifier obj. The object attributes are listed in the following table. All attributes are numbers, except where indicated.

obj.Type	the object type (see table below)
obj.Area	the object area
obj.Perimeter	the object perimeter
obj.Avgintens	average intensity of the object
obj.Avgintensred	average intensity of the red channel of the object
obj.Avgintensgreen	average intensity of the green channel of the object
obj.Avgintensblue	average intensity of the blue channel of the object
obj.Length	the object length
obj.Distance	the distance defined by a path
obj.Width	the object width
obj.Height	the object height
obj.Hue	the object hue value
obj.Angle	the object angle
obj.Roundness	the object roundness
obj.Left	the object left side (x-coordinate)
obj.Right	the object right side (x-coordinate)
obj.Radius	the object radius
obj.Top	the object top (y-coordinate)
obj.Bottom	the object bottom (y-coordinate)
obj.X	x-coordinate of the center of the object
obj.Y	y-coordinate of the center of the object
obj.Custom1	a custom number assigned to the object by the script
obj.Custom2	a second custom number assigned to the object by the script
obj.Label	the object label (text value)
obj.Info	additional text field for the object (text value)
obj.Unitstr	the abbreviation of the unit of measurement (cm, mm, µm, etc.) (text value)
obj.Selected	the 'selected' state of the object: true (1) or false (0)

The object methods are:

obj.Delete()	deletes the object
obj.Select()	selects the object
obj.Unselect()	unselects the object

The object types are:

1	t.Unit	object created by the Unit tool
2	t.Length	object created by the Length tool
3	t.Middle	object created by the Middle tool
4	t.Angle	object created by the Angle tool
5	t.Perpendicular	object created by the Perpendicular line tool
6	t.Path	object created by the Path tool
7	t.Area	object created by the Area tool
8	t.Center	object created by the Center tool
9	t.Circle	object created by the Circle tool
10	t.Rectangle	object created by the Rectangle tool
11	t.Marker1	object created by the Marker tool (style 1)
12	t.Marker2	object created by the Marker tool (style 2)
13	t.Barcode	object created by the Barcode tool
14	t.Ellipse	object created by the Ellipse tool
15	t.Arc	object created by the Arc tool

Mathematical functions

ABS(x)	returns the absolute value of x
ACOS(x)	returns the arccosine of x
ASIN(x)	returns the arcsine of x
ATAN(x)	returns the arctangent of x
COS(x)	returns the cosine of x
EXP(x)	returns ex (where e = 2.71828182846)
HYPOT(x,y)	returns the square root of the sum of squares of its arguments x and y. This corresponds to calculating the length of the hypotenuse of a right-angled triangle.
LN(x)	returns the natural logarithm of x
LOG(x)	returns the base-10 logarithm of x
POWER(x,y)	returns x raised to the power y: xy
SIN(x)	returns the sine of x
SQRT(x)	returns the square root of x
SQUARE(x)	returns the square of x: x*x
TAN(x)	returns the tangent of x

Rounding functions

CEIL(x)	rounds x upward
FLOOR(x)	rounds x downward
ROUND(x)	returns the value of x rounded to the nearest integer.

Other functions

NOW()	the Now() function takes no argument and returns a string with the current date and time. The format of the string is YYYYMMDDhhmmss where YYYY is the year, MM is the month, DD is the day, hh is the hour, mm is the minutes, and ss is the seconds.
TIME()	the Time() function takes no argument and returns the UNIX Epoch time. This is the number of seconds that have elapsed since the Unix epoch, that is the time 00:00:00 UTC on 1 January 1970, ignoring leap seconds.

Mathematical constants

TRUE	returns the value 1
FALSE	returns the value 0
PI	returns the value 3.14159265359

Operators

Mathematical operators
*	5*3	multiplication
/	5/3	division
^	2^3	2 raised to the power 3
+	2+3	sum of two numbers; the + operator can also be used to concatenate two text strings
-	2-3	difference
Comparison operators
<=	var<=5	returns TRUE (1) if var is less than or equal to 5
>=	var>=5	returns TRUE (1) if var is more than or equal to 5
<	var<5	returns TRUE (1) if var is less than 5
>	var>5	returns TRUE (1) if var is more than 5
==	var==5	returns TRUE (1) if var is equal to 5
!=	var!=5	returns TRUE (1) if var is not equal to 5
Logical operators
&&	expression1 && expression2	returns TRUE (1) if both expression1 AND expression2 return TRUE (1)
||	expression1 || expression2	returns TRUE (1) if expression1 OR expression2 returns TRUE (1)

Standard procedures

Image manipulation and enhancement

BackgroundCorrection()

Corrects image defects caused by uneven illumination. See Background correction.

Brightness(red[,green,blue])

Sets the brightness of the different color components (see Selective color brightness). Values for the red, green, and blue components must be in the range [-100..100]. If only one parameter is specified, that value is are used for the red, green, and blue components.

ContrastAutoFix()

Maximizes contrast automatically. See Contrast Auto Fix.

Despeckle()

Removes noise from images without blurring edges. See Despeckle.

Flip(vertical | horizontal)

Flips the image vertically or horizontally. See Flip.

Grayscale()

Converts the image to a grayscale image. See Convert to Grayscale.

Invert()

Creates a negative of the image. See Invert.

Rotate(left | right)

Rotate the image left or right. See Rotate.

SelectAll()

Selects all measurement objects in the image window.

Sharpen([filtersize,intensity])

Applies a sharpen filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3
intensity: % filter intensity; the default value is 50.

StretchHistogram([trimLO][,trimHI])

Optimizes contrast by histogram stretching.

Optional parameters:
trimLO: the percentage of pixels with the lowest intensity to trim.
trimHI: the percentage of pixels with the highest intensity to trim.
If only one parameter is given, the same value is used for trimLO and trimHI.
When you do not specify values for trimLO and trimHI, the observed range of pixel intensities is stretched over the full range of possible pixel intensities.

UnselectAll()

Unselects all measurement objects in the image window.

Filters

GeometricMeanFilter([filtersize])

Applies a Geometric Mean Filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

HarmonicMeanFilter([filtersize])

Applies a Harmonic Mean Filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

ContraHarmonicMeanFilter([filtersize][,order])

Applies a Contraharmonic Mean Filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.
order: the order Q of the filter; the default value is 1.

MaximumFilter([filtersize])

Applies a Minimum filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

MeanFilter([filtersize])

Applies an Arithmetic Mean Filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

MedianFilter([filtersize])

Applies a Median Filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

MidpointFilter([filtersize])

Applies a Midpoint filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

MinimumFilter([filtersize])

Applies a Minimum filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

RangeFilter([filtersize])

Applies a Range filter to the image.

Optional parameters:
filtersize: larger filter size yields stronger effect; the default value is 3.

Binarization

Binarize([lower threshold][,higher threshold])

Converts the image to a binary image by converting all pixels between two threshold values to red and those below the lower or above the higher threshold to white. See Binarization.

Optional parameters:
lower threshold: a value in the range [0..255]
higher threshold: a value in the range [0..255]
If only one threshold value is given this value is used as the higher threshold and the lower threshold is set to 0.
If no thresholds are specified, the software uses histogram-derived threshold values.

MorphDilate()

Adds pixels at region boundaries and fill in holes (Morphological Dilate operation after binarization).

MorphErode()

Removes pixels at boundaries or regions and increase the size of holes (Morphological Erode operation after binarization).

MorphOpen()

Smooths boundaries, break narrow isthmuses and eliminate small noise regions (Morphological Open operation after binarization).

MorphClose()

Smooths boundaries, join narrow breaks and fill small holes caused by noise (Morphological Close operation after binarization).

NoiseReduction()

Reduces noise in the binary image. See Noise reduction.

Analysis of objects after binarization

SetExcludeBorderObjects(TRUE | FALSE)

Sets the option to exclude objects that are on the image border. The default is to exclude objects that are on the image border (parameter=TRUE).

SetMinimumArea(value)

Sets the minimum area of objects. If value is 0 or FALSE, then there is no minimum area. The default is not to take into account a minimum area.

SetMaximumArea(value)

Sets the maximum area of objects. If value is 0 or FALSE, then there is no maximum area. The default is not to take into account a maximum area.

SetMinimumLength(value)

Sets the minimum length of objects. If value is 0 or FALSE, then there is no minimum length. The default is not to take into account a minimum length.

SetMaximumLength(value)

Sets the maximum length of objects. If value is 0 or FALSE, then there is no maximum length. The default is not to take into account a maximum length.

AnalyzeObjects()

Extracts object contours from the binary image using the setting listed above. See Analyze Objects.

Text output window

Echo(value[,value...])

This will echo the text(s) or number(s) value to a text output window. If the text output window is not open, it is created first.
If value is a number, it can be followed by :decimals.
For example: Echo(PI:3) will cause the following text to be displayed in the output window: 3.142.
In text values, the following special characters can be used: "\n" and "\t".
"\n" will insert a line break (the subsequent text will be written on a new line)
"\t" will insert a tab.

EchoOff()

The EchoOff() command can be used to switch OFF echoing of text to the output window.

EchoOn()

The EchoOn() command can be used to switch ON echoing of text to the output window.

Examples

General image quality improvement

Some successively executed commands that generally improve image quality.

{
	BackgroundCorrection();
	ContrastAutoFix();
	Despeckle();
}

Find largest area

Iterate through all measurement objects and find the largest area. Next find that object that has the area equal to the maximum and label it "Largest area". Finally show the largest area in the output window.

{
	max=0; 
	foreach object {
		if (obj.area>max) {
			max=obj.area;
		}
	}	
	foreach object {
		if (obj.area==max) {
			obj.label="Largest area";
		}
	}	
	echo("The largest object is ",max," ",img.UnitShort,"²\n");
}

See also

• Manage scripts (Tools menu)
• Digimizer script language