ADPluginBar Documentation¶
Author: Jakub Wlodek¶
Corresponding Author: Kazimierz Gofron¶
Installing the plugin¶
The ADPluginBar plugin depends on several external libraries. These include:
- Opencv: Can be built from source from github. Otherwise install from package manager.
- Zbar: Can be built from source from github. Otherwise install from package manager.
- EPICS, Area Detector, and their submodules, all of whuch can be found on github.
Further installation instructions are located in the README.md file in the top level of this repository.
Using ADPluginBar¶
The sample image used in all screens in this document captured with a prosilica camera
ADPluginBar (current version 2-0) has several requirements for proper
functionality. As pf R2-0, 8 bit and 16 bit images are supported, in
both Mono and RGB mode.
Not that the image will be converted to grayscale if input is in RGB.
Output arrays from the plugin will be in RGB because barcode bounding
boxes are displayed in blue.
Some conversion information between NDArrays and OpenCV Mat objects
used as a conversion element is included in a file in the barSrc
directory. Additionally, though inverted
bar codes are supported, they require a PV flag to be set, and thus
cannot be read in conjunction with standard bar or QR codes. They are
also only supported in 8-bit mode. This is another feature
that is being considered for a future release.
Once ADPluginBar is installed, Some edits must be made to the common
plugins screen linked to your detector. It should look as follows:
The Address that should be passed to each of the elements is Bar1.
Thus, the entire PV would be, for example, “$(P)Bar1:PortName_RBV”
for the portname field.
The “more” button should be linked to the provided “NDPluginBar.opi”
screen, or an equivalent adl or edl screen. (Currently only CSS
screens are provided, though
other types may be looked into in the future.) The NDPluginBar.opi
screen looks as follows:
ADPluginBar supports reading up to 5 bar codes simultaneously, though
currently only the first discovered barcode has its coordinates stored
as a PV.
In order to access the remaining 4 barcodes, simply press the button
titled: “View 1-5”. Once pressed, the following screen will display:
As you can see, in the sample image used above, two barcodes are
present, the QR code which was generated with a test message, and a
two dimensional barcode taken form
a box from around the test area. Both codes were detected ane placed
into PVs BarcodeMessage1_RBV, BarcodeType1_RBV and the ‘2’
equivalents.
As of release R2-0, ADPluginBar supports a live view of the detected
barcodes in an image. To use this feature, set use any EPICS viewer,
and set the Array Port to BAR1,
or whatever port your plugin has been set to. In the image above, I
used the NDPluginStdArrays plugin for viewing in CSS. When a barcode
is detected, a blue bounding box is drawn
around the code.
For more information on the newest release of ADPluginBar please check
the RELEASE.md file in the top level directory. Additionally, please
contact the
author with any questions regarding the usage of the plugin or feature
requests.
Release Notes¶
R2-1 (8-May-2019)
- Features Added:
- Threading has been added (similar to NDPluginDmtx) for much faster performance, and no lost frames
- Bug Fixes
- Threading for improved performance removes issues with dropped frames when image size was too large
- Y-coordinate for corner PVs now indicates from the bottom up rather than from the top down
- Future Plans
- Possible integration with ADPluginDmtx
- Image autosaving when barcode detected
- Database integration
R2-0 (4-January-2018)¶
- Features Added:
- Corners can now be displayed for any of the 5 barcodes via a PV toggle
- Number Codes now lists the number of codes in the image not the total number of codes
- Passing the ADPluginBar Array Port to an EPICS Viewer allows for live display of detected barcodes and QR codes
- Support for both 8 bit and 16 bit images
- Added support for input of RGB images as opposed to only Mono images
- Barcode Message PVs changed to waveforms to increase max character count to 256
- Bug Fixes/Code Refactoring:
- Fixed issue where plugin would freeze in certain situations where codes were repeated.
- Removed redundant functions, split up large functions into more compact pieces
- Improved documentation for all functions
- Future Plans:
- Add support for automatic image saving when barcodes detected
- Support for databases like MySQL and MongoDB
R1-1 (27-June-2018)¶
- Several key features added and bugs fixed:
- Support added for reading up to 5 codes in one image (Corner data stored in PV for first code)
- Support added for reading inverted bar codes i.e. white code on black background
- Fixed issue where number of barcodes would continue to increment when seeing the same bar code
- Fixed issuse where seeing the same barcode would cause an infinite loop of asyn messages in the IOC shell
- Future plans:
- Add ability to save image file with detected barcodes marked.
- Add ability to pipe information into an NDArray and display it in CSS
R1-0 (22-June-2018)¶
- Original release. Some issues that can be resolved with future
releases:
- Only mono images supported
- stringin record used for barcode message, so limit of 40 characters currently
Code Documentation¶
Below is an explanation of functions included in ADPluginBar and the general plugin structure.
ADPluginBar File structure¶
All of the plugin Source code is housed in the barApp/barSrc directory. The barApp/Db/NDBar.template file contains PV definitions. barApp/screens contains CSS .opi files.
Function definitions
| Function Name | InputArgs | OutputArgs | Description |
|---|---|---|---|
| initPVArrays | None | None | Function that places PV indexes into arrays for easier iteration |
| printCVError | None | None | Function for printing out OpenCV exception information |
| clearPreviousCodes | None | None | Function that clears out the currently detected barcodes. |
| ndArray2Mat | pArray, arrayInfo | img | Function that converts input NDArray pArray into output Mat img |
| mat2NDArray | img | pScratch | Function that converts input Mat img into output NDArray pScratch |
| fix_inverted | img | None | Function that inverts black and white in image to allow for detecting inverted codes |
| push_corners | symbol, update_corners | discovered | Function that updates poition of discovered code from symbol and updates PVs if update_corners flag set |
| update_corners | discovered | None | Function that updateds corner PVs to those of discovered |
| scan_image | img | None | Function that changes Mat to zbar image and scans it with zbar |
| clear_unused_barcode_pvs | counter | None | Function that resets PVs that had detected barcode earlier, but no longer do |
| decode_bar_codes | img | None | Function that scans image, then loops over any detected codes and updates PVs |
| show_bar_codes | img | None | Function that takes list of discovered codes and draws them on the image based on pushed corners |
| writeInt32 | pasynUser, value | None | Function that is called when a PV is written to |
| processCallbacks | pArray | None | Function that is called for each NDArray created by the attached driver |
More detailed documentation can be found in the plugin Src.