Vision inspection help

1. Overview

A vision job judges one camera frame with an inspection recipe (.vrp) and reports OK, NG or no verdict. Results appear as system tags vision.<job>.*, can be written back to user tags (PLC), and NG images and a result log are kept on the gateway.

2. Roles

3. Recipes

Upload a .vrp on the Recipes tab. The gateway test-loads it in the engine and keeps it only if that succeeds (32 MB each · 32 recipes and 128 MB on this device · 33 MB of versions carried in project bundles, which are limited to 48 MB). It is stored as the engine saves it after loading it once, so a downloaded file may differ in key order from the uploaded one. If the engine rejects it, the reason is shown in the screen language. Recipes travel with the project bundle. Only admins can download recipe contents.

4. Creating a job

1. id — lowercase letters, digits and _. Result tags are named vision.<id>.*.
2. Choose the camera and the recipe.
3. Choose the trigger (manual, tag edge or interval).
4. Outputs — pick outputs from the recipe; each becomes the result tag out.<name>. You never type the work UUID by hand. Work UUIDs are always stored in lower case: from vision engine r5 on, the engine reads the work IDs of a recipe in lower case. An older setup saved in upper case is rewritten once in lower case when the gateway starts, and it still runs with an older engine.
5. Write-back — write the verdict, outputs or counters to user tags (PLC). On no verdict a write happens only if “Value on no verdict” is set.

5. Triggers and frames

• Use frames taken after the trigger only (on by default) — only frames that arrive after the trigger are judged. With none within 3 s the result is no verdict (reason=camera).
• Wait after trigger (settleMs, 0–5000 ms) — a frame is stamped when the gateway receives it, which is later than when it was taken (RTSP delay). To judge only frames taken after the part has settled, set this a little above that delay. When it is above 0 the gateway waits even if the option above is off.
• The interval trigger takes 50 ms to 24 h (triggers are checked every 50 ms). When one inspection takes longer than the interval, the triggers in between are dropped and overrun grows — measure the inspection time of the recipe on the device before choosing a short interval.
• Triggers are checked every 50 ms, so intervals under 100 ms are rounded to 50 ms steps (the average interval holds, but single gaps are uneven).
• An ordinary job (a recipe without motion region or object tracking) with Use frames taken after the trigger only on waits for a new frame on each trigger. When the interval is shorter than the camera's frame interval, the triggers that fire while it waits are dropped and overrun grows — set the interval equal to or longer than the camera interval.
• When running a short interval (several times per second) for a long time, lower the number of result rows kept (results keep) and keep result images for NG only — result rows and images write a lot to the storage (the eMMC of a CM4).
• A trigger that arrives while the job is busy is dropped and counted in overrun (one waiting slot only).
• RTSP camera recommendations — the gateway receives and decodes the stream continuously at the camera's rate, so the device load follows the camera's resolution and fps. On the camera, choose a sub-stream of 720p and 15 fps or less, and keep the gateway's output rate at the default 2 fps (raise it only when inspections need it). A CM4 accepts up to 6 RTSP cameras (6 at 720p and 15 fps measured about 0.8 of a core); a 7th is refused with the reason. On Mac and Windows the limit is twice the logical cores (6 to 32) and can be changed with maxRtspCameras (1 to 64) in cameras.json in the config folder.

6. Outputs and range verdicts

Give an output a min and/or max and the result tag out.<name>.ok appears (1 = in range, 0 = out). A missing or non-numeric value counts as out of range. Verdict from decides what makes OK or NG.

When verdicts come from the engine, out-of-range marks in the result log are shown dimmed as “Reference — out of range” (they did not affect the verdict).

The recipe’s partial verdicts (JudgeLogics) appear as partial.0, partial.1 … (1 or 0, empty on no verdict).

7. Recipe input overrides

Enumeration inputs (for example OCR spacing or read mode, code-reader match mode) can be overridden with vision engine r4 (C API level 4) or later. The list shows the candidates the engine currently holds (for a job that was saved and loaded), and the value is set by name. With an older engine they are listed as “pending” and saving is refused. For inputs that change the layout (the type selection of TypeConverter, CreateObject, ObjectAttribute, ArrayElementAccess), the engine refuses with “cannot change: output is connected” while the job’s outputs feed another job — disconnect in the recipe first. Re-selecting the current value is fine.

Use these to change an input such as a threshold without editing the recipe. In the job editor under Recipe input overrides, pick an input and enter a value; it is applied after the recipe loads. Number, boolean and text inputs, and enumeration inputs (engine r4 or later), can be overridden (not images, regions or coordinates).

Overrides do not change result tags, so they can be saved while polling. Saving applies the new values to that job only — other jobs are untouched, and if this job is inspecting, the values are applied after that inspection finishes (it is not cancelled). Removing an override reloads the recipe so the recipe value returns.

8. Result tags

9. Counters and automatic reset

Counters survive restarts. With Automatic counter reset they go to 0 when the gateway’s local time passes a boundary.

• Daily close — one time (00:00 when empty).
• Shift boundaries — 2 to 6 times (for example 06:00, 14:00, 22:00).
• The inspection number (seq) is never reset — it links images and log lines.
• Boundaries passed while the gateway was off reset at start-up. If the clock steps back (time sync) the same boundary does not reset twice.
• Caution — if the clock steps back by one to two days (for example when a wrong clock is corrected), boundaries in between do not reset: they are earlier than the last reset, so they count as already passed. Resets resume normally from the boundary after the clock passes the last reset again. A clock that was more than two days ahead is pulled back at once. On a day with a big clock correction, press Reset counters by hand if needed.

To reset by hand use Reset counters on the job card (admin).

10. Result images and history

• Result images — by default only NG images are kept on disk (count and MB caps per job, 1 GB across all jobs). The oldest go first.
• History tab (operator) — the NG gallery and the result log. Filter by verdict and use “Load more” for older lines. “Removed” in the image column means the image was trimmed by the caps.
• Downloads — on the History tab, Result log CSV (current filter, up to 20,000 lines) and Images zip (up to 200 images, 64 MB, with an index.csv). The browser fetches the existing views one at a time and packs them, so the gateway carries no big load. Recipes (.vrp) are downloaded by admins only, on the Recipes tab.
• Report appendix — choose jobs under Vision NG appendix in a report template and the NG results inside the report period (newest 1–24 per job) are appended after the table. The CSV gets number, time and outputs; the screen and print get images (operator or higher). Report files that include the appendix can be downloaded by operators or higher only (fixed when the file is made; editing the template later does not change it).
• The result log keeps up to Result log rows per job (default 5000, max 20000, 0 = off). A line is at most 4 KB; longer lines have output values trimmed and show “(trimmed)”. Each job’s files stay under 8 MB.

11. Run, test and pause

• Run once — a manual trigger. Result tags, PLC write-back and the log all update.
• Test one shot — shows the verdict, outputs and result image only. Counters, result tags and PLC write-back are unchanged. You can also test with an image file.
• Pause — while paused every trigger (edge, interval, manual, script) is dropped. Test shots still work. Restarting the gateway clears the pause.

12. SCADA vision element

Set a SCADA camera element’s source to Vision inspection result (vision:<job>) to show the last result image with a verdict band (top, bottom or none) and counters. The image is fetched only when the inspection number changes. It works on viewer kiosks.

13. Alarm suggestions and OEE

• Suggest alarms (admin, job card) — after you confirm, two alarm rules are created: 3 NGs in a row (ngStreak, critical) and latency over the job’s time limit (latencyMs, warning). An object detection job gets two more rules, for the target class count and for unusable detection results (chapter 20). Edit them on the alarm screen.
• OEE — for quality quantities pick good vision.<job>.okCount and total vision.<job>.count.

14. Scripts and MCP

• Scripts: vision.run("job") (also vision.trigger) queues an inspection and returns at once. vision.last("job") returns the last result {result, judgment, seq, ts, outputs, …} or null. To wait for a result use on("vision.job.seq", …).
• Array outputs (histogram bins, line profile samples and so on) are not single values, so they cannot be picked as named outputs or range checks. Number arrays come with every result as arrays ({"<work ID>.out[<n>]": [numbers…]}); read them with vision.last("job").arrays, or draw them with a chart element's 'Draw a vision result array' in the screen editor, which redraws the whole array for each result. The histogram and line profile tools put their arrays in the result only when their array output input is on.
• MCP: the vision_* tools (status, jobs, recipes, run, test, summary, image list, result log, pause, resume, read attributes, overrides).

15. Troubleshooting

16. Sample project — Vision inspection line

The bundled sample Vision inspection line (Project › Samples) runs four inspection jobs on folder-playback cameras. It judges 26 synthetic images (3 OK and 3 NG for each of the first three jobs, 8 for the precision check) every 2 seconds and shows OK, NG, yield and the NG streak. It has two screens; switch with the Inspection · Precision check tabs in the header.

Setup (admin, before opening)

1. Download and unzip vision-sample-images.zip (3.2 MB). It has four image folders (6 · 6 · 6 · 8 images) and a calibration practice folder (calibration/).
2. In Configure › Shared Connections › Video › Register camera, create four Folder playback cameras — ids vision_count, vision_area, vision_code, vision_flange, image folders vision-count, vision-area, vision-code, vision-flange, interval 2500 ms.
3. Before saving each camera, upload the images of the matching folder in the Image folder panel at the bottom of the dialog (images added after saving take effect when the camera is saved again).
4. Open Vision inspection line from Project › Samples. The cameras must exist first, or the inspection jobs are not loaded — if you opened it first, open the sample again after creating the cameras. Opening it replaces this device's vision jobs, recipes and calibrations with the sample's.

• The inspection interval (2 s) is shorter than the camera interval (2.5 s), so frames taken after the trigger see each image once. Images play in name order, so each job gets three NG in a row; the alarm fires when the longest NG streak reaches 3. A slowly growing overrun count on the Vision page is normal (trigger ticks that land while waiting for the next image).
• Counters reset at midnight. Total OK, total NG, yield and the longest NG streak in the bottom row add up all four jobs. Images are not stored in the project bundle (.acproj); upload them again on another gateway (the calibration of the precision camera is stored in the bundle).
• In long-running demos and exhibitions the NG-streak alarm fires and clears on every loop (about 15 s), so alarm history keeps accumulating. Disable the alarm rule or shorten history retention if needed.
• Text such as PASS / FAIL on the result image is drawn into the image by the inspection engine, so it is always English regardless of the screen language. The verdict band and screen text follow the screen language.
• Without the vision engine (CM4 optional package · Windows setup component) or the vision license feature, the screen still opens and each column shows Vision inspection feature not installed.

16-1. Precision check — recipe teaching practice

The fourth job precision runs three tools on each plate part: Locate (alignment with a pattern model) → Bore (bore diameter) → Lot (lot code reading). The regions of Bore and Lot follow the position Locate found (their Align input takes the alignment result). The calibration of camera vision_flange (0.1 mm/pixel, made from a checkerboard image) is stored in the project, so the diameter is in mm.

The first recipe is taught only partly on purpose, for practice. The pattern model finds parts turned up to ±5° only, and the character model has no samples of 8.

Practice (admin · license vision-teach) — open the workbench from the job card › Adjust recipe and pick images from the folder-playback folder vision-flange as the image source. Section 17 describes each screen.

1. Pattern model (17-3) — pick image 01 and press Use current image next to Master image in the bar. In the model row of tool Locate press Teach → Rotation range (±deg) 15 → Teach. Keep the region (it is the reference position). Images 03 and 05 are now found (score about 97–99).
2. Calibration (17-2) — folder images open without calibration, so Bore measures pixels (about 100) and fails. Press Choose next to No calibration in the bar and pick vision_flange: 10.02 mm, OK.
3. Character training (17-4) — pick image 08 and press Character training on tool Lot → (1) Cut (7 boxes) → (2) type 2610B08 → (3) Add as samples → (4) Start training → (5) Read this image gives 2610B08. With about 90 samples training takes less than a second on a Mac.

When all three are done, Publish a new version and pick precision in the dialog so the running job uses it. To go back to the start, roll back to the original version in Versions.

• The first recipe (about 280 KB) was trained with its 84 character samples kept (keep samples on), so more samples can be added and trained.
• With the first recipe the two turned parts and the two bore NGs come in a row, so the precision NG streak reaches 4.
• The ZIP folder calibration/ holds the checkerboard image (5 mm squares) and the calibration file made from it, vision_flange.cal, for practising delete and upload on the Calibration tab. Deleting it reapplies the job without calibration: the diameter comes in pixels and every part fails.
• The master image (640×480 gray) is about 0.3 MB of raw pixels · about 0.4 MB inside the recipe.

16-2. License plate recognition — text reading and registered-vehicle matching

The bundled sample License plate recognition (Project › Samples) has one inspection job (plate) that reads 20 synthetic plate images; the project script plate-judge then matches the text read against a registered-vehicle list and sorts each plate into Registered · Unregistered · Read failed. The plates and numbers are entirely computer-drawn (the numbers are random) and may coincide with a real vehicle's number by chance. Do not use this for real vehicle reading or access control.

Setup (admin, before opening)

1. Download and unzip plate-sample-images.zip (0.3 MB). The plate-demo folder has 20 JPEG images; the zip also has the registered list and the typeface notice (SIL OFL 1.1).
2. In Configure › Shared connections › Video › Register camera, create a Folder playback camera — id plate_cam, image folder plate-demo, interval 2500 ms. Upload the 20 images before saving the camera, using the Image folder panel at the bottom of the dialog (images added after saving take effect only when the camera is saved again).
3. Open License plate recognition from Project › Samples. The camera must exist first, or the inspection job is not loaded.

Judging rules (the inspection engine only knows whether text was read — the reference text is left empty)

• The registered list is the tag PLATE.REGISTRY (comma-separated, 15 vehicles). Change the tag value to change the list without editing the script. If it is empty when the sample is first opened, the script writes the default list.
• One lap of the 20 images (50 s) gives 14 registered, 6 unregistered, 0 read failures (all 20 read correctly). The character reading model of the sample recipe was trained with the plate layout hint on (NNHNNNN|NNNHNNNN, Hangul cell width 1.0), so a Korean syllable without a final consonant (such as '가' in demo_08) that used to split into two pieces read as digits is kept as one character.
• The sample recipe needs vision inspection r12 or later. On a device with an older version the project opens without the inspection job and recipe, and the import report shows 'This recipe needs vision inspection r12 or later'; update the vision package (CM4 optional package · Windows setup component) and open the sample again.
• Limits: a registered vehicle with one character misread shows as unregistered, and a misread that happens to equal another registered number shows as registered. The engine's per-character scores are not used.
• For every unregistered or failed read, PLATE.ALERT pulses for 2 seconds, so the alarm history gets raise/clear pairs. Reset the totals with the Reset totals button.
• The images are not part of the bundle (.acproj); upload them again when you move to another gateway. Without the vision engine (CM4 optional package · Windows setup component) or the vision license feature, the screen still opens and shows Vision inspection feature not installed.

16-3. Parking entrance plate scene — plate finding and text reading

The bundled sample Parking entrance plate scene (Project › Samples) differs from 16-2: it looks at a whole entrance scene (1280×720), not a plate-only image. The recipe of the job gate has two tools — the plate finder (Finder) finds the plate in the scene and passes that area to the text reading tool (Plate) as its inspection area. Car position, plate size (0.8–1.15×), tilt (±5°) and brightness change from scene to scene. The script gate-judge sorts the result into registered · unregistered · read failed with the rules of 16-2, and a scene with no plate found becomes No car (not counted, no alert). Scenes, plates and numbers are all synthetic and cannot be used for real vehicle or site reading.

Setup (admin, before opening)

1. Download and unzip plate-scene-images.zip (3.9 MB). The gate-scene folder has 28 scenes (24 cars · 4 empty lanes); the zip also has the registered list (18 vehicles) and the typeface notice.
2. Create the folder playback camera gate_cam (image folder gate-scene, interval 2500 ms) and upload the 28 images before saving it.
3. Open Parking entrance plate scene from Project › Samples. Vision inspection r13 or later is needed (plate finder tool).

• The camera cell on the left shows the inspected scene (no overlay) and the green box on it is the plate found — the script turns the plate box outputs (center X · Y, width, angle) into screen coordinates and moves the box (the nearest of five widths).
• One lap (70 s) gives 16 registered · 8 unregistered · 0 read failed · 4 no car (measured on a Mac, about 6–10 ms per scene).
• The text reading in the recipe was taught again with the areas found in the scenes (binarization offset −40, deskew −8 to 8°, layout hint NNHNNNN|NNNHNNNN). On 200 synthetic scenes not used by the sample it read 194 correctly and 6 failed; no plate was misread as another valid number.
• When no plate is found the result is 'No car' even if a car is there (this inspection does not look for cars).

16-4. Conveyor object counting — one video at 2 · 5 · 10 frames per second

The bundled sample Conveyor object counting (Project › Samples) runs one synthetic conveyor video (8 boxes moving left to right at 160 px/s, a lap of about 38 s) side by side as three folders at 2, 5 and 10 frames per second. The recipes of the three jobs (c2 · c5 · c10) have the same shape — text reading (Label, first) · motion region (Motion) · object tracking (Track) — and the screen shows, per job, the counts (A→B · B→A · total) · last lap / this lap · recent crossings (ID · label read) · median time per frame · learning. The video is synthetic and cannot be used for real site counting.

Setup (admin, before opening)

1. Download and unzip conveyor-sample-images.zip (21 MB). Three folders: conveyor-2fps (76 images) · conveyor-5fps (190) · conveyor-10fps (380) — images × interval is 38.0 s in all three, so the three scenes stay in step however long they run.
2. Three folder playback cameras — conv2_cam · conv5_cam · conv10_cam, image folders of the same names, intervals 500 · 200 · 100 ms. Upload the images of each before saving it.
3. Open Conveyor object counting from Project › Samples. LinkVion Gateway 0.1.0.19 or later (100 ms interval trigger) and vision inspection r18 or later (majority warm-up · per-object reading · miss time allowance) are needed.

• The count line is the vertical line in the middle (drawn bottom to top) and side A is the left, so every box counts as A→B. The answer per lap is 8; the label order is P205 · P420 · H499 · P809 · B930 · A479 · E436 · T172.
• The maximum speed (px/s) is 240 in all three recipes (measured object speed 160 × 1.5). The maximum move (px/frame), confirm frames, miss frames and learning frames follow each frame rate (confirm and miss about 1 s, learning 4 s), and the miss time allowance is 1000 ms. The motion region's learning rate (LearningRate) and absorb frames (AbsorbFrames) are also per frame, so the same value means a different time at another frame rate — this sample sets absorb frames to 4 s (8 · 20 · 40) and keeps the default learning rate. With the default 300 absorb frames (150 s at 2 frames/s), boxes that were on the belt when the stream started stay as ghost regions for a long time and the counts go wrong. Absorbing alone is not enough — boxes of the same look pass the same place every 3.5 s and keep interrupting the absorb, so the places of boxes on the belt when the sample was opened or resumed stayed for close to a lap and gave false B→A counts. So all three recipes turn on majority warm-up (section 18) and learn for 4 s (8 · 20 · 40) — over twice the time a box takes to pass one spot (about 1.1 s), so passing boxes are not learned. So settling after learning (section 18) is off — right after opening the sample or resuming, everything is counted after the 4 s of learning ('Learning'). With it on, this scene always shows about two boxes, so an empty frame comes only at the empty belt at the end of a lap and boxes passing until then (up to about 31 s) are not counted. The minimum area (MinArea) of 2000 px (about 9 % of a box) keeps small pieces from being taken as areas. The judge logic (total and part 1) is the object tracking alone — with the default (all works pass) the Label that reads an empty wall always failed, showing FAIL on the overlay and part 1 false on the card. Confirming takes about 1 s because a track confirmed while only the front of the box is visible would read part of the label first and stop there.
• Per-object label reading is on in all three jobs (Job editor › Frame stream). The area of each newly confirmed object is read by the text reading job (the inspection result, stream and counts stay as they are, section 18). The verdict is rules: OK while the belt shows 0–4 object areas (the fixed area of the text reading tool is an empty wall, so the engine verdict is not used).
• Measured on a Mac (20 minutes, 32 laps): every job counted 256 (8 per lap) with 0 B→A, 0 no-verdict results, 2,432 · 6,080 · 12,160 inspections (every frame) and 0 overruns, and the labels read came in order with none missing or repeated. The median time per frame is about 4 ms (with per-object reading, Mac Debug library). Right after opening the sample and right after resuming with boxes on the belt, counting started right after the 4 s of learning (0 B→A); a resumed job is behind the others only by the boxes that passed while it rested and learned (1–2).
• The three jobs start at different moments and camera phases, so their totals are a little apart within a lap, and settling ends at a different moment for each job. Compare the Last lap cells for the equal count (a gap of more than 8 s of empty belt starts a new lap).
• The frame rates (2 · 5 · 10) are chosen by the sample and are not a processing limit. Processing time on each device (such as CM4) must be measured separately. Crossing events stay off in the event log (the default), so the screen shows the result tags (track.*) and the recent crossings collected by the script conveyor-events. The result tags hold only the last crossing, so when two objects cross in the same frame the list shows one of them (the counts include both).

17. Recipe adjustment (teaching)

A workbench for tuning a recipe's thresholds and choices by running it on images. It runs on a separate engine, so running inspections do not change until you save as job overrides or publish and apply to a job. Administrators only; the license must include the vision-teach feature (it does not open on a trial license).

Ways in

• Recipes tab › Adjust at the end of a row — opens with the recipe values.
• Job card › Adjust recipe — opens with that job's input overrides applied (and its time limit and pixel format).
• Inspection log › image window › Adjust with this image — opens with that image.

Image source — choose one of five under Image source: one camera frame now · a folder playback image · a file upload (JPEG or PNG, 8 MB) · an NG image from the inspection log · a test set image. Log images are usually overlays with results drawn on them, so verdicts re-run on them are for reference only. Turn on Also keep NG originals under Job edit › Result images to keep the camera original next to each NG overlay; that original is used instead (same size limit).

Screen

With Auto preview on, every change runs once shortly afterwards. With it off, press Run.

Test sets — under Test sets, collect OK and NG images (100 per set, 200 MB in total) and run them all at once. Load expectations with Import expectations from an expected.json (image name → judgment OK/NG and outputs with {"eq": value} or {"min": a, "max": b}, keyed tool name.output name). Results show the adjusted and opening values side by side with matches, false accepts, false rejects and changed verdicts. Use Mismatches only, Download CSV and To canvas (use that image). Test sets stay on the gateway but are not stored in project bundles (.acproj).

Saving — Save as job overrides stores the current adjustments as input overrides of a job that uses the same recipe. Inputs set back to the recipe value are removed from the overrides. Running inspections use them from the next inspection. Region changes are not kept as overrides — publish them.

Publish — Publish in the header stores the current adjustments and regions as a new version of the recipe (as the engine saves it, with a note). Versions never change; only the jobs you pick in the dialog use the new one. For the job the session was opened from, clear input overrides is on by default (those values are already in the new version). Other jobs' overrides are not in the new version, so you pick them one by one. Publishing content identical to an older version makes that version the published one again instead of creating a new one. The Publish button is off when the engine version cannot save recipes. Publishing and applying are refused while polling.

Versions — Versions on the Recipes tab lists a lineage (published and past versions), compares a past version with the published one (changed values, connections, tool names, judgment logic) and rolls back a job to an older version. The first uploaded original version is always kept; besides it, up to 3 unused past versions are kept per lineage (oldest removed first). Project bundles carry only versions used by jobs and published versions — original and past versions stay on this gateway and do not move with the project to another device (there the carried version looks like the first of a new lineage, and a missing previous version does not break anything). When this device exceeds 128 MB, unused past versions are removed first; if that is not enough, publishing and uploading are refused. The workbench header and the publish dialog show the remaining room.

Undo and drafts — Undo and Redo in the header (Ctrl+Z · Ctrl+Shift+Z) step back through value and region changes (100 steps per session). A changed session is autosaved as a draft every 30 seconds ("Autosaved" time in the header) and kept when the session closes or times out. When you open it again you are asked whether to resume the draft or discard it and open the published version. If the draft started from another version, that version number is shown and resuming opens the draft's version (without job overrides). Drafts are not stored in project bundles. Only one person can edit a recipe (lineage) at a time.

Auto set, work names, intermediate images, diagnosis (vision engine r6 or later)

• Auto set — a button in the properties panel. The engine sets the tool's thresholds and limits from the session image (area, count, brightness, contrast, diameter, length, angle and color tools only — for others the button is off and says why). The changed values show as "Teaching result" and form one undo step. After teaching there is no verdict, so the preview runs again. The running inspection engine is not touched; publish to use it in jobs.
• Rename — edit the tool (work) name at the top of the properties panel (up to 128 UTF-8 bytes). The name lives in the recipe, so publishing puts it in the new version.
• Intermediate images — image outputs have "View", which opens the image the engine made (after the last preview only). Images longer than 2048 px are scaled down.
• Diagnose — the header button reports connection, region and logic problems in the recipe. "No master image" is not a defect (the image is attached at run time), so it is hidden and only counted.
• Enum candidates with the same name — when broken characters make two candidate names equal, pick by number (#); the override stores the name and the number together. If the recipe changes so that number names something else, the job reports an error.

• A session loads one more engine on this device. A CM4 opens one at a time, other devices two, and each user has one (opening a new one closes the previous). It does not open with less than 256 MB of free memory.
• A session closes after 10 minutes without activity and lasts 2 hours at most (Extend in the bottom line). Saved overrides remain after it closes.
• Opening and closing a session (with the list of changed inputs), saving overrides, publishing, applying versions and test set results are written to the event log.

17-1. Master image

The bar under the workbench header shows Master image: W×H or none, with Use current image and Remove. It puts the current session image into the recipe as its reference image.

• The master image is not used for judging — inspections always run on the camera image of the moment. Regions and pattern models of tools that take an alignment result are taught in the reference pose (17-3); the master image keeps that reference pose image in the recipe. "No master image" in Diagnose is not a defect.
• It is stored as raw pixels and makes the recipe larger (640×480 gray about 0.3 MB of raw pixels · about 0.4 MB inside the recipe, 5 MP color about 15 MB) — a gray camera is recommended. Adding more than 8 MiB asks first; a recipe over 32 MiB is reverted.
• Adding and removing are one undo step each. They are not kept as job overrides, so publish to put them in the running recipe.

17-2. Calibration

With a calibration loaded, measuring tools such as diameter, length, angle and area give values in the calibration's unit (usually mm) instead of pixels. There is one calibration file per camera, kept apart from the recipe.

Upload — on the Calibration tab of the Vision page, press Upload (or Replace) in the camera row → Choose calibration file → width · height (empty uses the source image size stored in the file, 0 turns the size check off) · note → Upload. The gateway reads it with the inspection feature before storing it and reapplies the jobs using that camera ("jobs reapplied n · failed f"). Delete reapplies those jobs without calibration. Download returns the stored file as is.

• Calibration files are not created on this screen — upload a file made elsewhere (from a checkerboard or similar). Up to 4 MiB per file and 16 MiB in total; calibrations are saved with the project bundle (up to 48 MiB together with recipe bodies).
• A job stops when its calibration cannot be loaded — the job card shows Calibration file cannot be read or Image size differs from the calibration (when the camera image size differs from the calibration's image size). This keeps wrong mm values from appearing silently.

Choosing on the workbench — the bar under the header shows Calibration: <camera> or No calibration, with Choose. With the image source camera, current image, that camera's calibration is loaded by itself. Folder playback, file, history and test set images start with No calibration: press Choose and pick the camera in Choose session calibration. Switching to another such image goes back to no calibration, so choose again. A calibration chosen in the session does not change the calibration of running jobs. When the file changes on the Calibration tab, the bar shows "(calibration file changed — reloaded with the next camera image)".

17-3. Teaching a pattern model

Tools with a pattern model input, such as alignment, show Pattern model present (or No pattern model (not taught yet)) and a Teach button in the model row of the properties panel. It is enabled once there is a session image.

1. Teach → the Teach pattern model dialog. At the top, view the Image this tool sees (after the preprocessing of earlier tools) or the Original.
2. Model region (reference position) — starts with the model's current region. Keep it, or choose a shape and drag it on the image to teach a new region (large images are shown scaled, but the region is sent in original coordinates).
3. Settings — edge threshold, edge shape, edge contrast, rotation range (±deg), pyramid level and so on, depending on the model type. Empty fields keep the model's current values.
4. Teach (up to 30 s, Cancel teaching). The result is one undo step; run the preview again to check it.

• The region is stored as the reference position and moved by the alignment result (Align) at run time, so teach on an image in the reference pose. The dialog of a tool that takes an alignment result shows this note and the master image state (17-1). Teaching on a shifted or turned image moves the regions of later tools by the same amount.
• A taught pattern model is not kept as a job override — publish it. Recipes are limited to 32 MiB.
• When running inspections are busy, teaching stops and says so. Stop operation or try again when they are less busy, or use Teach without protection (admin confirmation, this one time, recorded — running inspections slow down for about 2 s while it teaches).

17-4. Character samples and training

The model row of a character reading tool shows n samples and a Character training button. The Character reading training dialog has five steps.

1. (1) Cut — cuts the image into character boxes in the tool's current text region (or a shape you choose). Adjust the boxes with Cutting settings (binarization, deskew, blob filter, blob merging). Depending on the device version, the Glyph height estimate (r11 or later) and Plate layout hint (r12 or later — layout letters N digit cell · H Hangul cell · A letter cell · / new line · | between layouts, e.g. NNHNNNN|NNNHNNNN) options appear. Both are off by default, and a recipe with one on cannot be used on older devices that lack it. All samples of a model use one cutting setting, so the settings are locked once samples exist (remove all samples to change them).
2. (2) Name — type one character per box on one line, starting from the top-left box. A space skips that box. The number of characters must match the number of boxes; type Hangul as precomposed syllables.
3. (3) Samples — Add as samples. Counts per character, List (remove selected), remove all of one character, Export · Import (only files exported from this screen, up to 32 MiB). Sample edits are undo steps.
4. (4) Train — set Accuracy check (cross validation) (off makes training about 4 to 5 times shorter with the same model), Number of folds and Keep samples, then Start training.
5. (5) Check — Read this image shows what the current image reads.

Training time and progress — before starting, "n samples · about t on this device · about m MiB of memory" is shown, and training does not start when free memory is short (Linux devices). While training, "p % · elapsed / about t" and the phase (making features, fitting, cross validation) are shown; progress is a share of the estimated time, so it moves with the elapsed time. Training continues when the dialog is closed, and "Character training p %" stays in the bar. Cancel training leaves samples and model unchanged. Each gateway trains one model at a time.

Protecting running inspections — training runs on the same gateway as the running inspections. It first measures their normal time ("Measuring the running inspections first"), and when they slow down during training it stops and later starts again from the beginning (3 automatic restarts). After those, press Resume now. If it still cannot finish, there are three ways:

1. Stop operation (communication) and train.
2. Train on another gateway (Mac or PC) and upload the recipe — it is the same recipe as training here.
3. An admin confirms and presses Resume without protection — running inspections slow down while it trains, and this is recorded in the audit log.

Keep samples (8 MiB) — with keep samples on, the samples stay in the recipe after training, so more samples can be added and trained later. Off makes the recipe smaller, but that recipe cannot be trained again. Keep samples is on by default when the expected recipe is 8 MiB or less, and off by default above that — export the samples first before turning it off. Training is refused when the recipe with kept samples would exceed 32 MiB.

• The training result is one undo step and reaches running inspections only when published.
• Training the same samples again on another device may give other model bytes, so the recipe number can differ (the reading is the same).

17-5. Common errors

18. Motion region and object tracking (frame stream)

When the recipe has a motion region or object tracking (vision inspection r15 or later) the job is the frame stream of one camera: each trigger puts one frame in, in order; the background is learned and objects are numbered and followed. Use a fixed camera and an interval trigger.

• Frame time — 'Pass the frame time to the inspection' (on by default) under 'Frame stream' uses the time each camera frame arrived for dropped frames, speeds (px/s) and event times. Below vision inspection r15 the frames run without a time and the job card shows 'No time'.
• Frame choice with an interval trigger — a frame-stream job driven by an interval trigger feeds the frame right after the last one, one at a time, regardless of 'Use frames taken after the trigger only' (no frame is skipped or fed twice). Keep the trigger interval equal to or shorter than the camera's frame interval — a longer one lets the frames in between pass. Manual and edge triggers still use frames after the trigger.
• Low frame rates — at 2 to 5 FPS set the object tracking maximum speed (px/s) in the recipe to the fastest object speed x 1.5, or counts are missed: at 0 (off) an object that moves more than the maximum move (px/frame) in one frame is lost (600 px/s at 2 FPS is 300 px a frame). Too large a value picks up a nearby other object.
• Count line — drawn from end A to end B. Side A is on the left when looking from A to B (screen coordinates, y grows downwards): for a line drawn left to right side A is above, for a line drawn top to bottom side A is on the right. Only objects passing within the segment are counted. Draw it where objects pass apart (two objects passing together may count as one).
• Learning — the first frames (the warm-up frames) learn the background (stream state 0). Results meanwhile are no verdict (reason learning) and the verdict and output tags go out uncertain. Alarms neither raise nor clear on uncertain values, and PLC result writes keep the last value unless a no-verdict value (noneValue) is set. The result tag learning and 'Learning' on the job card show it.
• Settling after learning (0.1.0.19, Job editor › Frame stream › Settling time after learning, default 0 = off) — a background learned while objects are in view remembers their places as background. When the objects leave, those places stay as 'ghost' areas, and while similar objects keep passing them the absorb (only continuous motion becomes background) keeps being interrupted, so they stay long — pieces that move to and fro across the count line give false B→A counts. When on, after learning ends counts and events stay out of the totals until a frame with no motion area at all comes or the maximum time passes, and results are no verdict as while learning (reason settling) with learning true. The base of the engine counts follows meanwhile, so after settling only the increase is counted. Block the cause first with majority warm-up in the recipe (r18), and use settling as a guard where majority warm-up cannot help — a belt crowded over half the view, or objects standing still while learning (objects passing meanwhile are not counted). On a line where objects keep coming, set it longer than the time for one empty gap to pass. Objects that passed while settling are not counted, so the totals can be short by that many.
• Majority warm-up (vision inspection r18 or later, the motion region input WarmupMajority in the recipe, off by default) — when on, during the warm-up frames each pixel learns the value it showed most often as background. Objects passing during learning are not learned, so a stream that starts or resumes while objects pass leaves no ghost areas (the cause the settling above guards against). An object that stays in one place for more than half the learning time (slow or stopped) can become background, so set the warm-up frames longer than twice the time an object takes to pass one spot (4 s in the conveyor sample). It is less accurate when objects cover over half the view or the picture shakes. Off learns by averaging as before and is not written to the recipe — a recipe with it on does not open on a device with r17 or earlier. Turn settling on as well only where majority warm-up is not enough (settling ends only when an empty frame comes, so in a scene that always shows objects that time stays uncounted).
• When learning starts over — changing this job, its recipe or calibration, a change of camera image size, a camera connection that drops and comes back (including a camera reopened after nobody looked at it for over 30 seconds — not merely a late frame), resuming from pause. A save that changes only other jobs keeps this job running.
• Counts — result tags track.countAtoB, track.countBtoA, track.countTotal (cumulative, following the counter reset of section 9) and track.active (objects now tracked). Counts carry on when learning starts over.
• Crossings — the last object over the line is in track.lastId, track.lastDir (1 A→B, 2 B→A), track.lastText, track.lastTs, the inspection history and the job card. Also record in the event log is off by default — when on, up to 30 a minute per job are recorded and the rest reported in one line (it writes a lot to the event log).
• Per-object text reading (vision inspection r17 or later) — when on, right after the inspection and on the same frame, the regions of newly found objects come first and are read in one go by the chosen OCR work. No work runs again and no recipe input changes, so the inspection result, stream and counts stay as they are. The result with the highest OCR score (below) is kept per object (the first one on a tie); an object whose text comes out the same twice is not read again. With the job's stop score on (default 0 = off), an object is not read again after its first read scoring at or above it, which cuts reads and inspection time (the same-text-twice rule and the reads-per-object limit stay; a stop score below the minimum score gets a warning on screen). When it crosses the line the text and score go out with the crossing, track.lastText and the inspection history. The OCR work's image input must be the inspection image (it cannot read when connected to a preprocessing output). Its search ROI may be connected (the object regions are passed separately). Reading stays within the inspection time limit and the per-frame number.
• OCR score and minimum score (r17 or later) — OCR gives each character a score (0–1000, the probability of the character read in thousandths), and the read's score is that of its lowest character (−1 is unknown — no character, or a model without probabilities). The job card and inspection history show the last inspection's OCR score, and the teaching preview outputs show CharScores and Score. With the job's OCR minimum score on (default 0 = off), an OK inspection scoring below it gives no verdict (reason 'read uncertain', verdict and output tags uncertain — alarms neither raise nor clear, PLC result writes follow the no-verdict value rule, the result picture is kept by the original OK verdict). An NG (engine NG or out of range) stays NG even with a low score. Also per-object reading gives a best read below it as 'read uncertain' (track.lastText uncertain; the PLC result write gets an empty text — or the no-verdict value if set — so the previous object's text does not stay). Unknown (−1) is not filtered. Set the value on site — look up the scores of a few correct and wrong reads from the real camera in the inspection history and put it between them. Synthetic text mostly scores in the 900s, but real text and Hangul can score much lower even when read correctly (in the synthetic number plate test, correctly read plates scored 28–954). Compare scores within one model only — training again changes the score of the same image.
• Find and read the plate · skip in runs (vision inspection r19 or later) — in per-object reading, choose the recipe's plate finder work under Find and read the plate in the job editor: each tracked box (a whole car, for example) is first searched for its number plate, and the plate found is read. A box where no plate is found (the car front not in view yet, for example) is "no plate", not a failed read: it does not count as a read and is looked at again on the next frame. The plate find score (0–1000) is kept apart from the OCR score and is used only to choose between two reads with the same OCR score (events and the job card show "plate find score"). When the finder accepts more than one plate in a box (two cars in one box) the card adds "several plates in the box". When boxes cut the plate, use Grow the search box (per mille: 200 = 20 % of the box width and height on each side); the search takes longer in proportion to its area. The plate finder work's image input must also be the inspection image. The recommended recipe is motion region → object tracking, with the plate finder and OCR works disconnected from each other and from the stream, and Skip in runs turned on for both in the work properties of the teaching screen: the two works then do not run on every frame (a whole-image search plus a read, about 34 ms at 720p on a CM4), and only the per-object reads cost time. A skipped work judges OK and keeps its outputs; it cannot be skipped while a work that runs reads its outputs (disconnect first). Skipping is kept in the recipe, so publish to use it in operation; such a recipe does not open on devices with r18 or earlier. The job card tells you when reading works are not skipped.
• Test shot — camera frames only (that frame also goes into the stream and the counts it adds are kept). An uploaded picture is refused (it would break the stream).
• It does not tell people from other things — anything that moves is counted. Not yet verified with real field cameras.

19. Focus check (sharpness)

When the recipe has a Sharpness work (vision inspection r24 or later), use Focus check in the job card's more menu (operator or above) to focus the lens. It reads only the sharpness work values from one camera frame and receives no picture; counters, result tags, PLC result writes and inspection records do not change. The job state conditions are the same as for a test shot.

• Pause first — for a job run by a trigger (tag change or interval), pause the job before checking focus. If it is not paused the gateway refuses, and the screen shows the reason and stops reading. Pause the job, then open the window again.
• Not for stream jobs — a job that uses the frame stream, like motion region and object tracking (section 18), refuses focus check (so no frames from outside the run enter the stream). Keep the sharpness works in a separate focus-only recipe.

1. Set the reference — teach the sharpness work in Recipe adjustment with an in-focus image. The score at that moment becomes the reference (100 %). Until the reference is set, only the score is shown instead of a bar, with the note "No reference: teach the reference first".
2. Watch the bars — each work has one bar showing % of the reference (Relative). The scale is 0–150 %, and the vertical line is the lower limit of the allowed range set on that work's Relative output; with no range set, the default 85 % is used. The actual value shows under the bar, like "allowed range lower limit 90 %" (or "default 85 %" with no range), and the bar turns red when the value is below it. Turn the lens until the bar is near 100 %. The screen rests 0.1 s after each reply before reading the next frame (longer when replies are slow, up to 1 s). Closing the window or hiding the tab stops reading.
3. Read failures — when a read fails the bars are cleared (old values are not left in green or red) and the reason is shown. The peak stays. Unless the refusal is "not paused" or "stream job", reading is retried every 1 s.
4. Peak — each row shows the peak so far and the current value as % of the peak. The peak rises only with values read in the "Measured" state and is cleared when the gateway restarts. After Reset peak, leave everything untouched and the % of peak shows how much the value fluctuates.
5. Allowed range — in the job editor, choosing the Relative output of a sharpness work fills in a lower limit of 85 % by default (an existing range is kept). The production verdict follows Verdict from (section 6). When the verdict comes from Engine verdict, this allowed range is for reference only and the row says so — for the gateway range to be used in the verdict, set Verdict from to Output ranges only (rules) or Engine + output ranges (both).

When the recipe has no sharpness work, or the camera or inspection fails, the bar area stays empty and the reason is shown.

20. Object detection results

Not a safety function — Object detection is not a certified safety function. Do not use it as the only means of protecting people or equipment. Detection results vary with lighting, camera angle and the model, and objects can be missed or wrongly detected.

When a recipe has an object detection work, its results appear as result tags vision.<job>.det.*. With several object detection works, the first one in the recipe is used. Boxes (positions) are not tags — they are drawn on the result image and feed object tracking.

• Detection work errors — when any detection work of the recipe fails (detection model missing, label mismatch, inference failure), the inspection has no verdict (reason detector_error). It is not OK even when the judgment is “NOT detection work” or the detection work is not in the judgment, and it is not counted as NG either. As with any no-verdict result, result is none, judgment and output tags are uncertain, verdict fields of PLC result writes such as ok and ng write only rows with a no-verdict value, and NG in a row (ngStreak) neither breaks nor grows — so an NG-in-a-row alarm cannot catch detection errors. Catch detection errors, a missing model and a lost camera with an alarm for det.valid below 1 (Suggest alarms on the job card creates it). The inspection history keeps the engine verdict separately.
• Unknown values — with no verdict, a detection work error, or a detection work skipped in Run (its previous values remain), every det.* tag is uncertain (no value) and det.valid is 0. On an error the inspection reports a count of 0, but that 0 is not published as “no objects”. Uncertain tags do not raise alarms, so keep an alarm for det.valid below 1 as well.
• PLC result writes — det.isResult, det.count, det.targetCount, det.maxScore and det.valid can be write sources (arrays are not written). When the value is unknown, only rows with a no-verdict value write that value; other rows write nothing (the PLC keeps the previous value). A no-verdict value such as −1, or writing det.valid (always 1 or 0) as well, lets the PLC tell “unknown” apart.
• Alarms — Suggest alarms on the job card adds two rules to a detection job: target class count (det.targetCount of 1 or more, warning) and detection results not usable (det.valid below 1 — model missing, camera lost or error, critical). Putting an alarm on a detection result tag, or adding a PLC result write to a detection job, opens a dialog to confirm the notice above.
• Connection record — whichever way a detection result is newly connected to a PLC result write or an alarm rule (screen, REST, assistant or bundle import), the security audit (vision.detector.link) and the event log record it, and the job card always shows “Detection results feed alarms or PLC”.
• Class filter — the filter is applied before the highest class of each box is chosen. Each box has one class. For example, choosing only “person” keeps every person detected. An empty filter means all classes.