Segmentation of measurement using an external Python script that returns an include/exclude value for each pixel.
Description
The script receives the spectra of all pixels and returns one value per pixel: 1.0 includes the pixel and 0.0 excludes it. Breeze then groups the included pixels into objects according to Separate / Merge and applies Min area, Max area, Object filter and Shrink. Descriptors can then be added to the objects.
By default the script is called one and receives all pixels of the measurement. If a Frames (segmentation) segmentation is placed before the Python script, the script is called once for every frame and receives only the pixels of that frame. In both cases the script must return exactly one value for every pixel it receives, in row-by-row order: from the top row to the bottom row, and from left to right within each row.
The script works on the spectrum of each individual pixel. Pixels are not averaged unless you write that in the script. The values are the spectra as they are in the project, so they depend on whether the data in the project has been converted to absorbance or not (for example reflectance or absorbance). The script receives band numbers, not wavelengths. To use a wavelength, look up its band number in the wavelength list of the image (for example in the .hdr file) and use that number in the script. Band numbers in the script start at 0, so the first band is 0. This differs from Breeze expressions such as b1, where the first band is 1.
On a Windows machine, you need to install Python version 3 or higher and the py Python launcher, or specify a custom python interpreter.
First, select Segmentation as node type and then select Python script as the method. Select the python script file using the Browse button or type the path to the script file directly.
Parameters
Python file
The Python script file to run. Select it with the Browse button or type the path to the file.
Python interpreter Optional
Use the file selector to specify a custom Python executable. If left empty, the system will attempt to use:
-
The global system command (
pyon Windows,python3on Linux). -
The bundled Breeze Python environment (used as a fallback if the global command is not found).
Min area
The minimum number of pixels for an object to be included. Default: 50. Small isolated groups of included pixels, such as single bright specks, are removed by this setting.
Max area
The maximum number of pixels for an object to be included.
If 0 no maximum area is defined.
Object filter
Use an expression to further exclude unwanted objects based on shape. Example: roundness > 0.5
Properties that can be used for the Expression:
-
Area -
Length -
Width -
Circumference -
Regularity -
Roundness -
Angle -
D1 -
D2 -
X -
Y -
MaxBorderDistance -
BoundingBoxArea
For details on each available property see: Object properties Details
Shrink
Removes the given number of pixels from the border of each included object. Default: 0.
Separate / Merge
Defines how the pixels that the script marks 1.0 are grouped into objects. Default: Normal.
The Separate parameter defines how pixels that pass your segmentation threshold are grouped into distinct object samples.
Pixel connectivity
Breeze uses 8-connectivity. Pixels are considered connected if they touch horizontally, vertically, or diagonally on a single corner.
1. Normal
-
Behavior: Standard connected-component grouping.
-
Result: Pixels touching by an edge or corner form a single object. Physically isolated clusters form separate objects.
2. Separate adjacent objects
-
Behavior: Applies a distance transform to find the inner centers (geometric peaks) of pixel clusters, then splits them using a watershed-style growth algorithm.
-
Best Used For: Round or spherical objects that are touching or overlapping.
-
Limitation: Elongated, branched, or irregular shapes may be incorrectly split into multiple objects because the algorithm detects multiple internal peaks within a single physical item.
3. Merge all objects into one
-
Behavior: Disregards spacing; combines all valid pixels across the entire image.
-
Result: Evaluates the entire frame as one single object for collective regional analysis.
4. Merge all objects per row
-
Behavior: Groups detected objects based on the spatial grid of their vertical center points (Y-coordinates).
-
Result: All objects residing within the same horizontal row lane are merged into a single object.
5. Merge all objects per column
-
Behavior: Groups detected objects based on the spatial grid of their horizontal center points (X-coordinates).
-
Result: All objects residing within the same vertical column lane are merged into a single object.
Link
Only visible when applicable
Link output objects from two or more segmentations to top segmentation. Descriptors can then be added to the common object output and will be calculated for objects from all segmentations.
The segmentations must be at same level to be available for linking.
Example
The script must define a function named perform. Breeze calls it once for the measurement, or once for each frame if a Frames segmentation is placed before the Python script. The function receives frame_data and num_bands and must return one value for every pixel it receives: 1.0 includes the pixel and 0.0 excludes it.
A band is one wavelength that the camera measures. The spectrum of a pixel consists of one value for each band, and num_bands is the number of bands. Band numbers in the script start at 0, so the first band is 0 and the second band is 1.
In the script below, frame_data[i + 1] is the second band of the pixel. A pixel is included if its value in the second band is below 0.5.
def perform(frame_data, num_bands):
result = []
count = len(frame_data)
if count == 0:
return result
for i in range(0, count, num_bands):
if (i + 1) < count and frame_data[i + 1] < 0.5:
result.append(1.0)
else:
result.append(0.0)
return result
Example input to the script
Data is streamed directly into the Python script's memory. The frame_data input is a contiguous, flat 1D array of floats. It holds all the bands of the first pixel, then all the bands of the second pixel, and so on, with the pixels in row-by-row order (from the top row to the bottom row and from left to right within each row).
Because the data does not contain line breaks, the script receives a num_bands parameter. You use this parameter as the step size in your loop to mathematically jump from one pixel to the next.
For a 3-band camera capturing three pixels, the raw input array looks like this:
[17.0, 16.0, 19.0, 15.0, 14.0, 13.0, 15.0, 14.0, 16.0]
Example output from the script
Your script simply returns a standard Python list from the perform function. The list must contain the binary segmentation mask (1.0 for included, 0.0 for excluded) representing each spatial pixel. For the input above, the second band of the three pixels is 16.0, 14.0 and 14.0, and none of these is below 0.5, so the script returns:
[0.0, 0.0, 0.0]
Migrating from Breeze older than 2026.1
If you are updating an older Python script that used file parsing, you must align it with the new memory stream format.
-
Remove file reading: Do not import
sys, readsys.argv, or open temporary text files. -
Wrap your logic: Place your code inside a
def perform(frame_data, num_bands):ordef perform(frame_data):function. -
Return, do not print: Return your final list directly from the function instead of using
print(result). -
Update array access: Pixels are no longer separated by rows. To access a specific band (e.g., the second band), use
frame_data[i + 1]inside your stepped loop instead of splitting a string. Exceptions and error formatting are now handled automatically by the system wrapper.
Everything inside the yellow line has now been selected as a sample.
Python script for coffee bean segmentation
This script separates green coffee beans from the tray they lie on. A pixel is included as a bean if its absorbance at 2064 nm is higher than its absorbance at 1672 nm by more than 0.08. Beans absorb more at 2064 nm, relative to 1672 nm, than the mesh and the holes of the tray do.
The script uses band numbers, not wavelengths. In this image the bands closest to 1672 nm and 2064 nm are band 132 and band 204, counting from 0. Look up the band numbers for your own image in its wavelength list. The threshold 0.08 and the band numbers belong to this image, and the data must be converted to absorbance. Adjust them for your own data.
BAND_A = 132 # 1672 nm
BAND_B = 204 # 2064 nm
THRESHOLD = 0.08
def perform(frame_data, num_bands):
result = []
count = len(frame_data)
if count == 0:
return result
for i in range(0, count, num_bands):
difference = frame_data[i + BAND_B] - frame_data[i + BAND_A]
if difference > THRESHOLD:
result.append(1.0) # include this pixel
else:
result.append(0.0) # exclude this pixel
return result
Parameters for this example
Python file = the script above, Min area = 50, all other parameters at their default values.
The same rule can be applied without a script with the Intensity segmentation: Convert to = Absorbance and Expression = w2064 - w1672 > 0.08.
Results for this example
77 beans, one object for each bean.
Troubleshooting
The Python script segmentation only works when the Runtime setting Apply changes sample average source is set to In-Memory Calculation. If it is set to Read Sample Average from Disk, Apply changes shows the error “Reading sample averages from disk is not supported by the selected segmentation” (Code 3004).
To change it, open Settings, select Runtime, and set Apply changes sample average source to In-Memory Calculation