Skip to content

micropsi-industries/ximea_ros_cam

 
 

Repository files navigation

ximea_ros_cam

Prerequisites

Tested on:

  • Ximea USB 3.0 MQ013CG-E2

Make sure that the camera firmware (both CPU and FPGA) are updated to the latest stable firmware! See: https://www.ximea.com/support/wiki/allprod/XIMEA_Camera_Firmware_Command-Line_Update for more info

Installing Ximea Camera Driver

Install the Ximea Software Package

Download and install the Ximea Software Package here: https://www.ximea.com/support/documents/4

Ubuntu 16.04 LTS Installation

Retrieve the Ximea Software Package:

cd ~; mkdir tmp; cd tmp
wget https://www.ximea.com/support/attachments/download/271/XIMEA_Linux_SP.tgz

Extract and install the Ximea Software Package (Note: -cam_usb30 is for USB 3.0 cameras):

tar -xf XIMEA_Linux_SP.tgz
cd package
./install -cam_usb30

(Optional: Cleanup)

cd ~
rm -rf tmp

Add user to the plugdev group

sudo gpasswd -a $USER plugdev

Setup the USB FS Memory Max Allocation to Infinite

This is done to make sure that the USB FS buffering size is sufficient for high bandwidth streams through USB 3.0

Set this with every new shell:

Put echo 0 > /sys/module/usbcore/parameters/usbfs_memory_mb into /etc/rc.local

Or

Apply to current shell:

echo "0" | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb

Set realtime priority to the /etc/security/limits.conf

Place the following in /etc/security/limits.conf to make the Ximea camera driver have real time priority

*               -       rtprio          0
@realtime       -       rtprio          81
*               -       nice            0
@realtime       -       nice            -16

Then add the current user to the group realtime:

sudo groupadd realtime
sudo gpasswd -a $USER realtime

Using ximea_ros_cam

Examine launch/example_cam.launch and config/example_cam_config.yaml to get an understanding on how to use the driver.

Launching a Camera:

roslaunch ximea_ros_cam example_cam.launch

To view the stream: rosrun rqt_image_view rqt_image_view

Launching Multiple Cameras:

Each camera can be ran with their own individual launch files (the parameters will be defined in their own individual name spaces, which makes each camera "unique").

Copy the example_cam.launch and input another serial number to serial_no of the other camera.

When launching multiple cameras, be sure to launch them at separate times (~1-2 seconds apart), this is potentially due to USB resource hog issues.

Parameter Descriptions:

Note that these parameters are found in either the config file or launch file

General

serial_no - Serial number of the Ximea camera (used to locate the proper camera)

cam_name - Name of the camera used when saving camera images and snapshots under the directory pointed by image_directory

calib_file - Calibration file used by the camera

frame_id - Frame ID of the camera

num_cams_in_bus - Number of USB cameras processed by a single USB controller (That is, if a hub has one controller and 4 ports, with 3 ports plugged with USB 3.0 cameras, then num_cams_in_bus = 3) (This will divide the total USB bandwidth by num_cams_in_bus to ensure equal bandwidth for each camera)

bw_safetyratio - Bandwidth safety ratio, a multiplier to the bandwidth allocated for each camera

poll_time - Used to set the duration (in seconds) which the camera is attempted to be opened again. When using multiple cameras, a duration of 2 seconds between each camera is recommended. (i.e. poll_time=0.0 and poll_time=2.0 for cameras 1 and 2).

poll_time_frame - This is the ROS timer loop period for the ximea camera node. It should generally be set to a rate that is a factor higher than the camera capture rate. For example, if the camera runs at 20Hz (or 0.05s period) and poll_time_frame set to 0.001s, then the timer will constantly loop every 0.001 seconds which is faster than the 0.05s period of the camera capture time, with an error that is roughly 0.000 to 0.002 between frames. Warning: if this value is larger than the period of the camera capture rate, then the frame rate of the camera is capped to the rate of the poll_time_frame, for example, if poll_time_frame is 0.5s, then the maximum rate that the camera can achieve is 2Hz

publish_xi_image_info - Flag for publishing the extra ximea camera information provided with each image acquisition.

Image Saving

image_directory - Directory used by the flag save_disk and calib_mode (**Note: Must be a valid directory path with an ABSOLUTE path, otherwise the camera fails to launch or will not create the directory properly. **)

save_disk - Save images to disk, under the directory <image_directory>/stream

calib_mode - Saves images everytime a trigger is pressed, under the director <image_directory>/calib

Compressed Image Transport Parameters

See compressed_image_transport for more information.

image_transport_compressed_format - Format for the compressed image - jpg or png

image_transport_compressed_jpeg_quality - 1 to 100 (1 = min quality)

image_transport_compressed_png_level - 1 to 9 (9 = max compression)

Colouring

format - Image format:

XI_MONO8 - Grayscale 8 bit
XI_MONO16 - Grayscale 16 bit
XI_RGB24 - BGR 24 bit
XI_RGB32 - BGRA 32 bit
XI_RGB_PLANAR - NOT USED
XI_RAW8 - RAW 8 bit
XI_RAW16 - RAW 16 bit

white_balance_mode - 0 = none, 1 = use coefficients, 2 = auto

white_balance_coef_red - manual white balance red coefficient (0 to 8)

white_balance_coef_green - manual white balance green coefficient (0 to 8)

white_balance_coef_blue - manual white balance blue coefficient (0 to 8)

Frame Rate Control

cam_trigger_mode - 0 = none, 2 = hardware trigger

hw_trigger_edge - For hardware trigger mode, 0 = rising-edge trigger, 1 = falling-edge trigger

frame_rate_control - Camera frame rate control (Works if no triggering is enabled)

frame_rate_set - FPS limiter (0 for none). This is depending on available bandwidth

img_capture_timeout - Timeout for getting an image, in milliseconds

Exposure Settings

auto_exposure - Auto exposure

auto_exposure_priority - Auto exposure gain ratio (1 = favour only exposure)

auto_time_limit - Auto exposure time limit (microseconds)

auto_gain_limit - Auto exposure gain limit

exposure_time - Manual exposure time (microseconds)

manual_gain - Manual exposure gain

Region of Interest

roi_top, roi_left - Top left corner in pixels

roi_width, roi_height - Width, height in pixels

License

MIT License

Copyright (c) 2017 WAVE Laboratory

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Releases

No releases published

Packages

No packages published

Languages

  • C++ 92.0%
  • CMake 6.7%
  • Python 1.3%