Mech-Eye ROS Interface

This repository contains the official ROS interface for Mech-Eye camera.

Installation

Dependencies

ROS

This API supports Ubuntu 18.04 with ROS Melodic, and Ubuntu 20.04 with ROS Noetic.

Install Mech-Eye SDK

Download and install MechEyeApi_1.6.0 compatible with Ubuntu from this link.

Install the Interace

• Download this ROS interface

  mkdir -p ~/catkin_ws/src && cd ~/catkin_ws/src
  git clone https://github.com/MechMindRobotics/mecheye_ros_interface
  cd ~/catkin_ws
  catkin_make

Brief intro to the interface

• Interface functions can be found in the documentation inside Mech-Eye SDK.

• Change config in ~/catkin_ws/src/mecheye_ros_interface/launch/start_camera.launch

  • save_file: true to enable save file to '/tmp/xxx', otherwise keep it as false
  • camera_ip: change to your camera ip address here (also remember to comment and uncomment the lines in MechMindCamera.cpp to connect to a specific camera)
  • tf related arguments: using quaternion for rotation parameters, to be changed to your calibrated parameters.
  • at the moment, image save path can only be changed in source code /mecheye_ros_interface/src/MechMindCamera.cpp.
  • remember to catkin_make again after changing *.cpp.

• Source the build workspace and use roslaunch

  source ~/catkin_ws/devel/setup.bash
  roslaunch mecheye_ros_interface start_camera.launch 

  Select a camera in LAN. Then, the camera will start working.

• Open a new terminal, source the workspace and call services

  source ~/catkin_ws/devel/setup.bash
  rosservice call [/service] [arguments]

  # Example
  rosservice call /set_cloud_outlier_filter_mode '!!str Off'   # for 'Off', it is necessary to input '!!str' before it.
  rosservice call /set_laser_settings 'Fast' 0 50 1 20
  rosservice call /set_3d_exposure [3.2,4.0]   # Do not input ' ' before the second arg, or it will be passed by string.
  rosservice call /add_user_set '!!str 123'
  rosservice call /delete_user_set 'test'

Topics

/mechmind/camera_info

Camera calibration and metadata.

/mechmind/color_image

Color image encoded as "bgr8".

/mechmind/depth_image

Depth image encoded as 32-bit float.

/mechmind/point_cloud

Point cloud data.

/mechmind/color_point_cloud

Color point cloud data.

Services

add_user_set

Invoke this service to add a user set.

This service has one parameter:

value (string): User set name to add.

capture_color_map

Invoke this service to capture color map once.

capture_color_point_cloud

Invoke this service to capture color point cloud once.

capture_depth_map

Invoke this service to capture color depth map once.

capture_point_cloud

Invoke this service to capture point cloud once.

delete_user_set

Invoke this service to delete a specified user set.

This service has one parameter:

value (string): User set name to delete.

device_info

Invoke this service to get the current connected device information.

get_2d_expected_gray_value

Invoke this service to get the expected image gray value.
Only take effect when 2D exposure mode is Auto.
A smaller value can decrease the brightness of the image, while a larger value can generate a brighter image.

get_2d_exposure_mode

Invoke this service to get current 2D exposure mode.

get_2d_exposure_sequence

Invoke this service to get current 2D HDR exposure sequence.
Only take effect when 2D exposure mode is HDR.

get_2d_exposure_time

Invoke this service to get current 2D exposure time.
Only take effect when 2D exposure mode is Timed.

get_2d_roi

Invoke this service to get current ROI when scanning 2D images.
Only take effect when 2D exposure mode is Auto or HDR.

get_2d_sharpen_factor

Invoke this service to get current image sharpen factor.

get_2d_tone_mapping

Invoke this service to get whether or not is tone mapping enabled.
Tone mapping uses gray level transformation algorithm to make the image look more natural.

get_3d_exposure

Invoke this service to get current 3D exposure sequence.

get_3d_gain

Invoke this service to get current camera's gain value during scanning 3D images.
Gain is an electronic amplification of the image signal. Large gain value is needed only when scanning extremely dark objects.

get_3d_roi

Invoke this service to get current depth map's ROI.

get_all_user_sets

Invoke this service to get all available user sets.

get_cloud_outlier_filter_mode

Invoke this service to get current cloud outler filter mode.

get_cloud_smooth_mode

Invoke this service to get current cloud smooth filter mode.

get_current_user_set

Invoke this service to get the current user set name.

get_depth_range

Invoke this service to get the current depth image's valid range along Z-axis in the camera coordinate system.

get_fringe_contrast_threshold

Invoke this service to get the current signal contrast threshold for effective pixels. Pixels with contrast less than this threshold will be ignored.

get_fringe_min_threshold

Invoke this service to get the current signal minimum threshold for effective pixels. Pixels with intensity less than this threshold will be ignored.

get_laser_settings

Invoke this service to get the current laser settings.

get_uhp_settings

Invoke this service to get the current uhp settings.

get_uhp_capture_mode

Invoke this service to get the current uhp capture mode.

get_uhp_fringe_coding_mode

Invoke this service to get the current uhp fringe coding mode.

set_2d_expected_gray_value

Invoke this service to set the expected image gray value.
Only take effect when 2D exposure mode is Auto.
A smaller value can decrease the brightness of the image, while a larger value can generate a brighter image.

This service has one parameter:

value (int32): Expected image gray value to set. Min:0, Max: 255.

set_2d_exposure_mode

Invoke this service to set current 2D exposure mode.

This service has one parameter:

value (string): 2D exposure mode to set. Options include 'Timed', 'Auto', 'HDR', and 'Flash'.

set_2d_exposure_sequence

Invoke this service to set current 2D HDR exposure sequence.
Only take effect when 2D exposure mode is HDR.

This service has one parameter:

sequence (float64[]): 2D exposure sequence to set. Min: 0.1, Max: 999. Min Size: 1, Max Size: 5.

set_2d_exposure_time

Invoke this service to set current 2D exposure time.
Only take effect when 2D exposure mode is Timed.

This service has one parameter:

value (float64): 2D exposure time to set. Min: 0.1, Max: 999.

set_2d_roi

Invoke this service to set current ROI when scanning 2D images.
Only take effect when 2D exposure mode is Auto or HDR.

This service has four parameters:

x (uint32): The column coordinates of the upper left point of the region of interest.
y (uint32): The row coordinates of the upper left point of the region of interest.
width (uint32): The width of the region of interest.
height (uint32): The height of the region of interest.

set_2d_sharpen_factor

Invoke this service to set current image sharpen factor.

This service has one parameter:

value (float64): The sharpen factor to set. Min: 0, Max: 5.

set_2d_tone_mapping

Invoke this service to set whether or not is tone mapping enabled.
Tone mapping uses gray level transformation algorithm to make the image look more natural.

This service has one parameter:

value (bool): Whether or not to enable tone mapping.

set_3d_exposure

Invoke this service to set current 3D exposure sequence.

This service has one parameter:

sequence (float64[]): Exposure sequence to set. Min: 0.1, Max: 99. Min Size: 1, Max Size: 3.

set_3d_gain

Invoke this service to set current camera's gain value during scanning 3D images.
Gain is an electronic amplification of the image signal. Large gain value is needed only when scanning extremely dark objects.

This service has one parameter:

value (float64): Gain value to set. Min: 0, Max: 16.

set_3d_roi

Invoke this service to set current depth map's ROI.

This service has four parameters:

x (uint32): The column coordinates of the upper left point of the region of interest.
y (uint32): The row coordinates of the upper left point of the region of interest.
width (uint32): The width of the region of interest.
height (uint32): The height of the region of interest.

set_cloud_outlier_filter_mode

Invoke this service to set current cloud outler filter mode.

This service has one parameter:

value (string): Cloud outlier filter mode to set. Options include '!!str Off', 'Normal', and 'Weak'.

set_cloud_smooth_mode

Invoke this service to set current cloud smooth filter mode.

This service has one parameter:

value (string): Cloud smooth mode to set. Options include '!!str Off', 'Normal', 'Weak', and 'Strong'.

set_current_user_set

Invoke this service to set the current user set name.

This service has one parameter:

value (string): User set name to set.

set_depth_range

Invoke this service to set the current depth image's valid range along Z-axis in the camera coordinate system.

This service has two parameters:

lower (int32): The lower limit of the roi on the z value of the depth map in the camera coordinate system.
upper (int32): The upper limit of the roi on the z value of the depth map in the camera coordinate system.

set_fringe_contrast_threshold

Invoke this service to set the current signal contrast threshold for effective pixels. Pixels with contrast less than this threshold will be ignored.

This service has one parameter:

value (int32): Signal contrast threshold to set. Min: 1, Max: 100.

set_fringe_min_threshold

Invoke this service to set the current signal minimum threshold for effective pixels. Pixels with intensity less than this threshold will be ignored.

This service has one parameter:

value (int32): Signal minimum threshold to set. Min: 1, Max: 100.

set_laser_settings

Invoke this service to set the current laser settings.

This service has five parameters:

fringeCodingMode (string): Laser fringe coding mode to set. Options include 'Fast', and 'Accurate'.
frameRangeStart (int32): The laser scan field of view start position to set. Min: 0, Max: 100.
frameRangeEnd - frameRangeStart >= 25
frameRangeEnd (int32): The laser scan field of view end position to set. Min: 0, Max: 100.
frameRangeEnd - frameRangeStart >= 25
framePartitionCount (int32): Laser's scan partition number to set. Min: 1, Max: 4.
powerLevel (int32): Laser's power level to set. Min: 20, Max: 100.

set_uhp_settings

Invoke this service to set the current uhp settings.

This service has two parameters:

capture_mode (string): Uhp capture mode to set. Options include 'Camera1', 'Camera2' and 'Merge'.
fringe_coding_mode (string): Uhp fringe coding mode to set. Options include 'Fast', and 'Accurate'.

set_uhp_capture_mode

Invoke this service to set the current uhp capture mode.

This service has one parameter:

capture_mode (string): Uhp capture mode to set. Options include 'Camera1', 'Camera2' and 'Merge'.

set_uhp_fringe_coding_mode

Invoke this service to set the current uhp fringe coding mode.

This service has one parameter:

fringe_coding_mode (string): Uhp fringe coding mode to set. Options include 'Fast', and 'Accurate'.