Detecting Areas

<module>/detect-area searches one image, once, and reports the regions it finds.

Running it

Set the image address and execute:

module-1/detect-area/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
write module-1/detect-area/execute

Then read output/status-code and output/result.

Everything else has a working default, so this first run tells you whether anything is being found at all. Tuning follows: see Tuning the Detection, and Analysing a Scene for commissioning the threshold level.

The result

output/result is an area_detect_result flatbuffer.

Field Meaning

blobs[].x, .y

Centre of the region.

blobs[].area

[pixel^2] Pixels the region covers, counted - never derived from a fitted shape.

blobs[].label

Which region this is in output/blob-labels - how a reported area maps to its pixels.

blobs[].bbox_x/y/width/height

Tight box around the region.

blob_count

How many regions, for a control program that only needs a count.

total_area

[pixel^2] Sum over all regions - the headline number for a coverage check.

largest_index, largest_area

The biggest region.

image_width, image_height

The searched region - the whole image unless a crop was set.

preprocess_method

NONE, LOG, DOG or DOH, as applied.

timestamp

Microseconds since epoch, when the run finished.

Regions are sorted by area, so blobs[0] is the largest.

total_area is usually the number to act on: coverage, contamination and fill checks are all "how much", not "how many".

Colour images

Either a grey or a colour image goes in. Thresholding and connected components are single-channel operations, so a colour image is converted and measured like any other. On ctrlX OS, a ctrlX image node delivers three colour channels whatever the camera is, so a grayscale camera produces three identical copies. There is no flag, and a region is reported once however many channels arrived.

Restricting the search

input/crop/{startX, startY, width, height} limits the search to part of the image. A zero width or height reaches the corresponding edge, so the default all-zero region searches everything and startX=100 with zero sizes searches from there to the bottom-right corner.

Two reasons to use it: speed, and excluding areas where a region cannot be, which avoids counting background clutter.

A region reaching past an edge is refused rather than trimmed, naming the input and the limit it broke.

Preprocessing

input/preprocess/method applies one filter before detection:

Method What it does

NONE

The default.

LOG

Laplacian of Gaussian - blur then a second derivative; emphasises regions of a size set by the sigma.

DOG

Difference of Gaussians - two blurs subtracted, a band pass. sigma-first must differ from sigma-second.

DOH

Determinant of Hessian - second derivatives combined. kernel-size must be 1, 3, 5 or 7.

Only the chosen method’s parameters are read, and only they are validated.

The regions themselves

The result carries numbers, not pixels. The pixels are in output/blob-labels, published by every run: one region number per pixel, and blobs[].label says which number is which region. See The Label Image.

An empty result

An empty blobs list with status-code 1 means no regions matched - nothing else. Every other reason a run could produce nothing is caught before detection and reported as a negative status code. See Execution Status.