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