Data Layer¶
A PLC, Node-RED or any ctrlX app uses InSiSo Visual Detector through the ctrlX Data Layer. The app's whole Data Layer is one folder, the same for every cell, whether it has one camera or five and one detector or ten:
insiso/visual-detector/
├── ready BOOL a trigger will work; if not, message says why
├── message STRING "Ready", or what to fix
├── busy BOOL a trigger is being processed
├── trigger (W) STRING write any value, e.g. your part number
├── picture/ the picture every block below describes (written last)
│ ├── id a counter, one higher per picture evaluated
│ ├── time when it was taken, for documentation
│ ├── trigger what produced it: your value, pulse-<camera>-<n>, or free-run
│ ├── ok, error did every camera and detector run
│ └── count objects found, all functions and cameras together
├── color/ Color Detection: every blob, as arrays
├── object/ Object Detection: every object, as arrays
├── coordinates/ Coordinate Mapping: the same objects in machine mm
├── json STRING the whole picture as one text, for Node-RED
├── command (W) STRING every web button, by name
└── command-result STRING the answer to the last command
Is the app on the Data Layer?¶
Open Diagnostics. The first line of chips answers this before anything else: ctrlX Data Layer, the licence, each camera and each detector. Its Trigger button writes trigger exactly as a PLC would. If the button works, the three steps below work from your PLC.
The three steps¶
| Step | Node | What to do |
|---|---|---|
| 1 | ready |
Wait until it is TRUE. When FALSE, message says what to fix, for example Camera 2 is not connected. |
| 2 | trigger |
Write any value that changes each time, for example your part counter 1042. Every connected camera takes one picture and every detector runs once. |
| 3 | picture/trigger |
Wait until it shows 1042. It is written last, so every block already holds this part's answer. Then read what you need. |
1. wait until ready = TRUE
2. write trigger := '1042'
3. wait until picture/trigger = '1042'
then read picture/ok, picture/count,
object/class[0], object/x-px[0], coordinates/x-mm[0], ...
Every object is one element of the arrays, and element 0 is the most confident. A colour-sorting cell reads color/name[0]. A code-reading cell reads object/code[0]. A pick-and-place cell reads object/x-px, y-px and orientation-deg, or coordinates/x-mm, y-mm and position-valid once Coordinate Mapping is set up. A dimensioning cell reads coordinates/length-mm, width-mm and height-mm.
Example, an orange and a red part in view:
picture/count = 2
picture/trigger = "1042"
color/picture-id = 4711 (= picture/id)
color/count = 2
color/name = ["orange", "red"]
color/x-px = [412.0, 1180.0]
color/y-px = [300.0, 310.0]
color/width-px = [96.0, 102.0]
What the answer means¶
ok is not "found something". ok says the app did its job: every camera sent a picture and every detector ran. count says what was in the picture. An empty belt is ok = TRUE, count = 0.
One picture, provably. Values are read one node at a time, so the picture number is on picture/id, on every block as <block>/picture-id, and on every object as picture[]. It is a counter, one higher for every picture the app evaluates. Two values with the same picture number came from the same exposure, whenever they were read. After a restart the counter carries on past its last value, so a number is never given out twice.
Several cameras or detectors. A trigger fires every connected camera at the same moment and runs every detector once, on its own camera's picture. count adds up everything found. camera[] and detector[] say where each element came from. json has the same objects in one text:
{"trigger": "1042", "ok": true, "count": 1, "objects": [
{"kind": "object", "detector": "model-1", "camera": 1, "class": "carton",
"confidence": 0.93, "x_px": 1250.0, "y_px": 980.0, "width_px": 610.0,
"height_px": 455.0, "orientation_deg": 0.0, "orientation_valid": false,
"x_mm": 412.5, "y_mm": 120.0, "position_valid": true}]}
Orientation. Color Detection measures it from the blob's shape (orientation-valid is TRUE when the blob is elongated). A model gives upright boxes, so orientation-deg is 0 with orientation-valid FALSE unless the model predicts corners.
Which detectors run. Every detector listed under Is it running? on Camera Connector. Leave one out by pausing it, or with the command configure-detector {"id": "model-2", "active": false}.
Hardware trigger¶
With the camera in hardware trigger mode, every pulse on its trigger line takes one picture, published exactly as for a software trigger. Since the PLC wrote no value, picture/trigger reads pulse-<camera>-<n>, n being the camera's picture number:
1. remember sLast := picture/trigger
2. pulse the camera's trigger line
3. wait until picture/trigger <> sLast
then read object/class[0], ...
Free run¶
With free-running cameras, the detectors run all the time and every picture reaches the same nodes, with picture/trigger = free-run. They are published when a value changes, at most four times a second. That is for watching, dashboards and simple sorting. A PLC that must read one answer per part uses a trigger.
Commands¶
Every button in the app's pages is also a command on the command node. Write the name, a space and the argument; the answer appears in command-result:
command := 'set-trigger-mode 1,software'
command := 'camera-status 2'
See Data Layer commands for every command.
Structured Text¶
Function blocks for the three steps (FB_VisionTrigger) and for one command and its answer (FB_VisionCommand), using the CXA_Datalayer library, are available from InSiSo with the PLC acceptance test program. Ask support.
Every node¶
Generated from the app's node table, version 4.7.21. The app's Help page lists those of the installed version. Arrays (string[], float[], bool[]) have one element per object.
| Node | Type | Access | Content |
|---|---|---|---|
ready |
bool | R | TRUE when a trigger will work: licence, cameras and at least one detector are in place. When FALSE, message says why |
message |
string | R | Ready, or what to fix, in plain words |
busy |
bool | R | TRUE while a trigger is being processed |
trigger |
string | R/W | Write any value, e.g. your part number: every camera takes one picture and every detector runs once. picture/trigger shows the value back, last, when the answer is complete |
picture/id |
float | R | A counter: the picture every block below describes, one higher for every picture evaluated, whatever camera (with several cameras in one picture, the first camera's). Each block repeats it in its own picture-id. Resumes past the last value after a restart, never repeats. Written last: when it shows a new number, every block already carries that picture |
picture/time |
string | R | When that picture was taken (UTC ISO 8601), for documentation; several cameras joined with +. Compare picture/id, not this |
picture/trigger |
string | R | What produced this picture: the value written to trigger, pulse-<camera>-<n> for a pulse on the camera's trigger line, or free-run for a picture the free-running cameras took on their own, or settings-change for a triggered camera's last picture looked at again after its color settings changed. Written last of all: when it equals your value, the answer to your trigger is complete |
picture/ok |
bool | R | TRUE when every camera delivered a picture and every detector ran. It does not mean something was found; count says that |
picture/error |
string | R | Why ok is FALSE, in plain words; empty when ok |
picture/count |
float | R | How many objects every function found in this picture, all cameras together |
color/picture-id |
float | R | The picture this block describes (equals picture/id once the picture is complete) |
color/count |
float | R | How many blobs were found: the length of the arrays below |
color/name |
string[] | R | The color of each blob found, by its name on the Color Detection page; element i of every color/ array is the same blob |
color/x-px |
float[] | R | Each blob's centre X in the picture, pixels |
color/y-px |
float[] | R | Each blob's centre Y in the picture, pixels |
color/width-px |
float[] | R | Each blob's width in the picture, pixels |
color/height-px |
float[] | R | Each blob's height in the picture, pixels |
color/orientation-deg |
float[] | R | Each blob's orientation from its shape, degrees; meaningful only where orientation-valid is TRUE |
color/orientation-valid |
bool[] | R | TRUE where the blob's shape gives an orientation (elongated), FALSE for a round or square blob |
color/confidence |
float[] | R | How well each blob fits its color range, 0..1 |
color/camera |
float[] | R | The camera that saw each blob |
color/picture |
float[] | R | The picture counter each blob was found in; differs from picture-id only when several cameras contribute to one picture |
object/picture-id |
float | R | The picture this block describes (equals picture/id once the picture is complete) |
object/count |
float | R | How many objects the models found: the length of the arrays below |
object/class |
string[] | R | The class of each object the models found; element i of every object/ array is the same object |
object/x-px |
float[] | R | Each object's centre X in the picture, pixels |
object/y-px |
float[] | R | Each object's centre Y in the picture, pixels |
object/width-px |
float[] | R | Each object's box width in the picture, pixels |
object/height-px |
float[] | R | Each object's box height in the picture, pixels |
object/orientation-deg |
float[] | R | Each object's orientation, degrees, when the model provides one; 0 with orientation-valid FALSE for a model that gives upright boxes |
object/orientation-valid |
bool[] | R | TRUE where the model measured the object's orientation |
object/confidence |
float[] | R | Each object's confidence, 0..1 |
object/camera |
float[] | R | The camera that saw each object |
object/detector |
string[] | R | The detector that found each object, e.g. model-1 |
object/picture |
float[] | R | The picture counter each object was found in; differs from picture-id only when several cameras contribute to one picture |
object/code |
string[] | R | The Data Matrix code read inside each object; empty where none was read |
coordinates/picture-id |
float | R | The picture this block describes (equals picture/id once the picture is complete) |
coordinates/count |
float | R | How many objects are listed: the length of the arrays below, the same objects as object/ in the same order |
coordinates/class |
string[] | R | The class of each object, as object/class; element i is object i |
coordinates/x-mm |
float[] | R | Each object's machine X (Coordinate Mapping) |
coordinates/y-mm |
float[] | R | Each object's machine Y (Coordinate Mapping) |
coordinates/position-valid |
bool[] | R | TRUE where x-mm and y-mm are measured; FALSE when that camera is not calibrated (Coordinate Mapping page) |
coordinates/length-mm |
float[] | R | Each object's length (longer side); 0 where not measured |
coordinates/width-mm |
float[] | R | Each object's width (shorter side); 0 where not measured |
coordinates/height-mm |
float[] | R | Each object's height; 0 where not measured |
coordinates/camera |
float[] | R | The camera that saw each object |
coordinates/picture |
float[] | R | The picture counter each object was found in |
json |
string | R | Everything this picture holds, every object from every camera and function, as one JSON text (for Node-RED or a PLC that parses JSON) |
command |
string | R/W | Write a command by name, then a space and its argument, e.g. "set-trigger-mode 1,software". Every button in the web pages has one; the Help page lists them. The outcome is in command-result |
command-result |
string | R | JSON outcome of the last command. Starts {"ok": ..., "command": ..., "argument": ...} so a PLC sees both within 255 characters |