Skip to content

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