|
1 | 1 | # Image Grabber |
2 | 2 |
|
3 | | -Image Grabber allows you to capture images (JPG) or video (AVI) with multiple Basler USB Cameras at once. It logs all |
4 | | -captured data to a CSV file for later use. |
| 3 | +Image Grabber allows you to capture images or video with multiple Basler USB Cameras at once. It logs all captured data |
| 4 | +to a CSV file for later use. |
5 | 5 |
|
6 | | -## How to launch |
| 6 | +## Prerequisites |
| 7 | + |
| 8 | +Tested on Ubuntu 20.04, may not work properly on other Linux distributions. This software is necessary for the code to |
| 9 | +compile and run properly. |
| 10 | + |
| 11 | +* Compiler supporting C++17. |
| 12 | +* CMake 3.16 and higher. |
| 13 | +* [OpenCV library](https://opencv.org/). |
| 14 | +* [Pylon SDK](https://www.baslerweb.com/en/sales-support/downloads/software-downloads/installationnotes-pylon-6-2-0-linux-x86-arm/) |
| 15 | + (tested on version 6.2.0). |
| 16 | + |
| 17 | +Devices supported are: |
| 18 | + |
| 19 | +* [Basler ace USB 3.0](https://docs.baslerweb.com/basler-ace-usb-30) cameras |
| 20 | + (tested on acA2000-165uc and acA1920-150uc). |
| 21 | + |
| 22 | +## How to use the app |
7 | 23 |
|
8 | 24 | In the project root folder: |
9 | 25 |
|
10 | 26 | 1. Build and compile: `make`. |
11 | 27 | 2. Run with arguments (see below), for example: `./ImageGrabber -v -f 60 -o "/myoutput"`. |
12 | | -3. Exit the app with `Ctrl+C`. |
| 28 | +3. Exit the app with `SIGINT` or `SIGTERM` signal (`Ctrl+C`). |
13 | 29 |
|
14 | 30 | ## Arguments |
15 | 31 |
|
16 | | -* `-R` (`--bwr`) - Set balance white (red channel), larger than 0 (default: auto continuous). (=1 red intensity |
17 | | - unchanged, >1 intensity increased, <1 intensity decreased). |
18 | | -* `-G` (`--bwg`) - Set balance white (green channel), larger than 0 (default: auto continuous). (=1 green intensity |
19 | | - unchanged, >1 intensity increased, <1 intensity decreased). |
20 | | -* `-B` (`--bwb`) - Set balance white (blue channel), larger than 0 (default: auto continuous). (=1 blue intensity |
21 | | - unchanged, >1 intensity increased, <1 intensity decreased). |
22 | | -* `-e` (`--exposure`) - Set exposure time in microseconds, range may vary (for example 28 - 1e7). |
23 | | -* `-f` (`--framerate`) - Set framerate (fps) of recording (default: 25). |
24 | | -* `-g` (`--gain`) - Set gain, range may vary (for example 0 - 23.59). |
| 32 | +* `-R` (`--bwr`) - Balance white (red channel), larger than 0, double precision, (default: auto continuous), |
| 33 | + (=1 red intensity unchanged, >1 intensity increased, <1 intensity decreased). |
| 34 | +* `-G` (`--bwg`) - Balance white (green channel), larger than 0, double precision, (default: auto continuous), |
| 35 | + (=1 green intensity unchanged, >1 intensity increased, <1 intensity decreased). |
| 36 | +* `-B` (`--bwb`) - Balance white (blue channel), larger than 0, double precision, (default: auto continuous), |
| 37 | + (=1 blue intensity unchanged, >1 intensity increased, <1 intensity decreased). |
| 38 | +* `-e` (`--exposure`) - Set exposure time in microseconds, range may vary (for example 28 - 1e7), double precision, |
| 39 | + (default: auto continuous). |
| 40 | +* `-f` (`--framerate`) - Set framerate (fps) of recording, double precision, (default: 25). |
| 41 | +* `-g` (`--gain`) - Set gain, range may vary (for example 0 - 23.59), double precision, (default: auto continuous). |
25 | 42 | * `-h` (`--help`) - Show help. |
26 | 43 | * `-i` (`--image`) - Save images instead of video. |
27 | 44 | * `-o` (`--output`) - Set directory for video/image and log output (default: out), directories will be created. |
28 | | -* `-q` (`--quality`) - Set image quality (only for `-i`) between 0 and 100, the higher is the better (default: 95). |
| 45 | +* `-q` (`--quality`) - Set image quality (use only together with `-i`) between 0 and 100, the higher is the better, |
| 46 | + integer precision, (default: 95). |
29 | 47 | * `-v` (`--verbose`) - Print information about the camera state. |
| 48 | + |
| 49 | +## Output format |
| 50 | + |
| 51 | +Saved images are in JPG format. |
| 52 | + |
| 53 | +Saved video is in AVI container. |
| 54 | + |
| 55 | +Saved log information is in CSV file with format shown below. Each captured image on a separate line. |
| 56 | + |
| 57 | +* `index` - Index of the captured image. |
| 58 | +* `mode` - Format of recording: `img` or `vid`, stays same for one log file. |
| 59 | +* `camera` - Camera identification number, stays same for one log file. |
| 60 | +* `file_path` - Path to the captured image or video. |
| 61 | +* `timestamp_in_ms` - System timestamp of the captured image in milliseconds. |
| 62 | +* `iso_datetime` - Datetime of the captured image in ISO format `YYYY-MM-DDThh:mm:ss.sss`. |
| 63 | +* `exposure_time` - Exposure time of the captured image. |
| 64 | +* `gain` - Gain of the captured image. |
| 65 | +* `white_balance_r` - Balance white (red channel) of the captured image. |
| 66 | +* `white_balance_g` - Balance white (green channel) of the captured image. |
| 67 | +* `white_balance_b` - Balance white (blue channel) of the captured image. |
| 68 | + |
| 69 | +## Cameras configuration |
| 70 | + |
| 71 | +Cameras can be configured using the arguments when launching the app. Settings are applied to all cameras. Default |
| 72 | +values for all available settings are `auto continuous` which means that before each image is captured, values are |
| 73 | +automatically set. Available settings are stated below. |
| 74 | + |
| 75 | +* Exposure time |
| 76 | + * Available range depends on the camera used, |
| 77 | + see [documentation](https://docs.baslerweb.com/exposure-time#specifics) to find these values. |
| 78 | + * Maximal exposure time is limited to values that do not interfere with the requested frame rate. |
| 79 | +* Gain |
| 80 | + * Available range depends on the camera used, see [documentation](https://docs.baslerweb.com/gain#specifics) to find |
| 81 | + these values. |
| 82 | +* White Balance |
| 83 | + * Configure each channel independently - red, green, blue. |
| 84 | + |
| 85 | +## Cameras handling |
| 86 | + |
| 87 | +App detects all Basler cameras connected to the device and starts recording on all of them with the same settings. Once |
| 88 | +any camera is disconnected, recording is stopped on all of the cameras. As soon as the disconnected camera is connected |
| 89 | +again, the recording is resumed and the newly obtained data is appended. |
| 90 | + |
| 91 | +## Image handling |
| 92 | + |
| 93 | +Each captured image is handled by the OpenCV library and it is saved using it. Videos are also saved with OpenCV. |
| 94 | + |
| 95 | +## Synchronization of capturing |
| 96 | + |
| 97 | +Capturing images with multiple cameras is parallelized using Pylon library - each camera has its own thread. |
| 98 | +Synchronization of capturing images from all cameras at the same time is done by software trigger that is serially sent |
| 99 | +to all cameras. Software sleep until the necessary time is used when waiting for the next image. With this mechanism, |
| 100 | +precision of +-1 ms is achieved. |
0 commit comments