Skip to main content

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

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 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

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 object { if (obj.left>img.width/2) obj.delete(); }

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.Widththe width of the image, in pixels (this value cannot be set by the script)
img.Heightthe height of the image, in pixels (this value cannot be set by the script)
img.Unitthe number of pixels in one unit
img.UnitStrthe selected unit (centimeter, millimeter, micrometer, etc.) (text value)
img.UnitShortthe 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.Typethe object type (see table below)
obj.Areathe object area
obj.Perimeterthe object perimeter
obj.Avgintensaverage intensity of the object
obj.Avgintensredaverage intensity of the red channel of the object
obj.Avgintensgreenaverage intensity of the green channel of the object
obj.Avgintensblueaverage intensity of the blue channel of the object
obj.Lengththe object length
obj.Distancethe distance defined by a path
obj.Widththe object width
obj.Heightthe object height
obj.Huethe object hue value
obj.Anglethe object angle
obj.Roundnessthe object roundness
obj.Leftthe object left side (x-coordinate)
obj.Rightthe object right side (x-coordinate)
obj.Radiusthe object radius
obj.Topthe object top (y-coordinate)
obj.Bottomthe object bottom (y-coordinate)
obj.Xx-coordinate of the center of the object
obj.Yy-coordinate of the center of the object
obj.Custom1a custom number assigned to the object by the script
obj.Custom2a second custom number assigned to the object by the script
obj.Labelthe object label (text value)
obj.Infoadditional text field for the object (text value)
obj.Unitstrthe abbreviation of the unit of measurement (cm, mm, µm, etc.) (text value)
obj.Selectedthe '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:

1t.Unitobject created by the Unit tool
2t.Lengthobject created by the Length tool
3t.Middleobject created by the Middle tool
4t.Angleobject created by the Angle tool
5t.Perpendicularobject created by the Perpendicular line tool
6t.Pathobject created by the Path tool
7t.Areaobject created by the Area tool
8t.Centerobject created by the Center tool
9t.Circleobject created by the Circle tool
10t.Rectangleobject created by the Rectangle tool
11t.Marker1object created by the Marker tool (style 1)
12t.Marker2object created by the Marker tool (style 2)
13t.Barcodeobject created by the Barcode tool
14t.Ellipseobject created by the Ellipse tool
15t.Arcobject 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.
Hypotenuse functionHypotenuse function
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

TRUEreturns the value 1
FALSEreturns the value 0
PIreturns the value 3.14159265359

Operators

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