Analysing a Scene

system/analyse-scene measures a picture and tells you what a fixed threshold would have to be commissioned at to measure the parts in it. It reports; it changes nothing.

It sits on system/ rather than inside a module because the answer is about the picture. Ten modules looking at the same camera would have asked the same question ten times and got the same answer back.

What it needs

Node Type Default Meaning

input/input-image-address

string

""

The image node to analyse. Its own, not a module’s.

input/crop/startX .. height

uint16

0

The region to analyse; all zero means the whole image.

input/bin-size

int32

0

Measure a shrunk copy: every bin-size × bin-size block becomes one pixel. 0 shrinks only what needs shrinking. Everything reported stays in your image’s units.

input/histogram-bins

int32

256

How finely output/histogram counts grey levels, 2 to 256.
bin-size and histogram-bins are different knobs. bin-size shrinks the image the analysis measures, and wants a small number. histogram-bins only decides how the grey levels are bucketed, and 256 — one bucket per level — is usually right.

What it reports

output/recommended-settings is the practical one: a list of node=value lines, relative to a module’s detect-area/input/, holding the level to commission, which end is the part, and whether a region has to be measured as the shape its outline encloses. Nothing is written for you — read them and set them deliberately.

output/histogram is how you check that advice. A fixed level wants to sit in the valley between the part’s hump and the background’s, and a single suggested number cannot show you whether there is one valley, two, or none at all. It is counted on the cropped image at full size, before any shrinking bin-size asked for, so it describes the picture rather than a resampling of it.

The rest describe the picture: parts-are-dark, parts-touching, region-count, expected-region-count, illumination-spread, separability, feature-thickness and area-sensitivity. output/findings says in words anything worth knowing, including the cases where no level will work.

The one to read first

area-sensitivity answers "will a fixed level hold here?". It is how much the measured area moves when the threshold moves one grey level — smaller is better, and there is nothing to aim for below 0.

Value What it means

0.006

A hard edge. The threshold sits in an empty valley; a fixed level is safe.

0.01

Still comfortable.

> 0.05

Brittle. One grey level costs 5 % of the reading. A fixed level is not a safe thing to commission here, and the application will say so in output/findings.

0.15

A picture that will not hold still at all.

The arithmetic that matters is area-sensitivity × drift in grey levels = fractional error. At 0.05, a lamp that ages ten grey levels over a shift moves your reading by half.

It only costs you if something moves

A high value under a steady lamp is a constant offset: it calibrates out of an absolute reading and cancels entirely when you compare one part against another. It bites when the lighting or the threshold moves. So read this number together with how stable your cell actually is.

Fixing a brittle picture

Nothing in detect-area/input/ fixes it. This application offers one thresholding method, FIXED, so there is no swept or adaptive level to hide behind — a brittle picture is fixed at the camera.

Sensitivity is roughly perimeter × edge-ramp-width / (contrast × area), which gives three levers. Work down the table:

Lever What raises the number What to do

Edge softness

Defocus, motion blur, sensor noise at high gain. Usually the biggest cause, and the one least suspected — the same scene defocused, with the lighting untouched, more than doubles this number.

Refocus. Shorten the exposure or steady the part to kill motion blur. Drop the gain and add light instead. Better optics.

Contrast

A narrow grey gap between part and background, so the edge transition is spread thin.

Lighting: backlight, change the angle, add a diffuser or a polariser, change the background.

Feature size

Thin or intricate parts — a lot of perimeter for very little area. Inherent to the part, not to your setup.

More pixels on the part: magnification, a closer working distance, or a higher resolution sensor.

Which lever is yours

Do not guess — the other outputs name it, and they outrank each other in this order:

  1. illumination-spread, against the part-to-background gap. If the light varies more than about a third of that gap, uneven lighting is the real problem and no single level fits the frame at all. Fix this first.

  2. feature-thickness. Below about 8 px the features are simply fine, and no amount of lamp tuning changes that — you need more pixels on the part.

  3. Only then is it edge softness or contrast.

output/findings says which of the three it hit, in words, most important first.