API review

Proposer: Ken Tossell

Present at review:

• Jack O'Quin
• Eric Perko

Scope

This package does not provide any C or Python API; it only exports the ROS interface for camera_node.

ROS API:

• Camera topics
  • /image_raw - sensor_msgs/Image
    • ./compressed, etc. - with image_transport
  • /camera_info - sensor_msgs/CameraInfo
• Dynamic controls (dynamic_reconfigure)
  • Automatically changing control values are reported to the user.

  • See libuvc_camera#Parameters

Plans

libuvc_camera will support streaming and configuration for UVC-compliant webcams and other UVC media source devices.

To do:

• Implement standard UVC control getters/setters.
• Add compressed video streaming (MJPEG).
• Allow ROS streaming in non-RGB modes.

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

• USB Video Class specification (zipped pdf): See USB_Video_Class_1.1.pdf pp. 77-102 for descriptions of the standard controls.

• (Ken) There are several controls where the unit and range are implementation-dependent; different cameras have different ranges, and the resolution is 1.0/(max-min). The camera will provide min and max when asked. Should the ROS driver accept values in the range [min, max] or in [0.0, 1.0] or in [0.0, 100.0], or ... ? If it takes [min, max], (how) should it let the user know what the range is?

  • (Eric) While it's annoying in the GUI, I'd prefer [min,max] and let improvements to dynamic_reconfigure allow the driver to change those limits at runtime.

    • (Ken) If we use [min,max], perhaps the config could include param_max and param_min parameters. The driver also might export a config wrapper class to allow UVCConfigWrapper(config).set_brightness_fractional(0.12) -- though this stuff would all be temporary and only in Python... Adding these pieces sounds bad when they're just going to be thrown out sounds bad, but is [min,max] usable without them?

      • (Eric) Would it be sufficient if the driver just set the parameter's value to its min or max whenever the user went beyond them? Does the dynamic_reconfigure GUI show parameters that the driver has changed the value of?

• (Ken) Are the control names and option names OK? Should any of them be changed to better match other drivers or the UVC spec?

  • (Eric) I think the current names are OK.

• (Ken) Should the driver always publish auto-updated control values? Would anyone want to be able to turn that off?

  • (Eric) I think I'd like to be able to see the auto-updated values changing.

  • (Eric) Should there be parameters for what "mode" a control is in (e.g. camera1394's feature control states: query, auto, manual, off, etc)? That would allow someone to turn the auto-updating on and off or query the current camera parameters.

    • (Ken) How would you expose these options and the query function, in terms of parameters and services?

      • (Eric) Essentially, I would see these as parameters controlling how the driver interprets other parameters. For example, if we had an iris_absolute_mode parameter in the config file, if the user set it to manual, the driver would set the camera iris based on iris_absolute. If the user had it set to query, the driver would put the current iris setting in the iris_absolute parameter instead of writing the value to the camera. The user could then view this value in either the dynamic_reconfigure GUI or by otherwise querying the parameter server/dumping the dynamic configuration to yaml.

• (Ken) ROS-side streaming formats: Add a parameter to let the user change the pixel format in sensor_msgs/Image?

  • (Eric) Are there cases where this wouldn't be set solely based on the video_mode? Would we convert in the driver if, say, someone configured the driver for RGB and then set the pixel format to BGR?

    • (Ken) I think we'd see YUYV -> RGB. Uncompressed streams are YUYV (or UYVY?) and NV12. The cameras I've tried all use YUYV and MJPEG.

      • (Eric) I suppose I can see that being useful for controlling the conversion to BGR or RGB, depending on what the user wants. Keep in mind any encoding has to be supported (list of supported encodings for sensor_msgs/Image: doc/api/sensor_msgs/html/image__encodings_8h.html ). MJPEG would probably be a better fit for something like sensor_msgs/CompressedImage, since that already accepts images as jpegs.

• (Kei) Can we add user defined extra control command? see doc/api/opt_camera/html/opt__nm33__uvc_8cpp_source.html for example.

  • (Ken) It'd need a ROS service interface or some other way to set access the XU controls, and users need to be able to load extended control descriptions. I'd like to support this if we can settle on the interface.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Conclusion

Package status change mark change manifest)

• Action items that need to be taken.

• Major issues that need to be resolved

---