base on A ROS Driver for V4L2 USB Cameras # usb_cam [](https://github.com/ros-drivers/usb_cam/actions/workflows/build_test.yml) ## A ROS 2 Driver for V4L USB Cameras This package is based off of V4L devices specifically instead of just UVC. For ros1 documentation, see [the ROS wiki](http://ros.org/wiki/usb_cam). ## Supported ROS 2 Distros and Platforms All Officially supported Linux Distros and corresponding ROS 2 releases are supported. Please create an issue if you experience any problems on these platforms. Windows: TBD/Untested/Unproven MacOS: TBD/Untested/Unproven For either MacOS or Windows - if you would like to try and get it working please create an issue to document your effort. If it works we can add it to the instructions here! ## Quickstart Assuming you have a supported ROS 2 distro installed, run the following command to install the binary release: ```shell sudo apt-get install ros-<ros2-distro>-usb-cam ``` As of today this package should be available for binary installation on all active ROS 2 distros. If for some reason you cannot install the binaries, follow the directions below to compile from source. ## Building from Source Clone/Download the source code into your workspace: ```shell cd /path/to/colcon_ws/src git clone https://github.com/ros-drivers/usb_cam.git ``` Or click on the green "Download zip" button on the repo's github webpage. Once downloaded and ensuring you have sourced your ROS 2 underlay, go ahead and install the dependencies: ```shell cd /path/to/colcon_ws rosdep install --from-paths src --ignore-src -y ``` From there you should have all the necessary dependencies installed to compile the `usb_cam` package: ```shell cd /path/to/colcon_ws colcon build source /path/to/colcon_ws/install/setup.bash ``` Be sure to source the newly built packages after a successful build. Once sourced, you should be able to run the package in one of three ways, shown in the next section. ## Running The `usb_cam_node` can be ran with default settings, by setting specific parameters either via the command line or by loading in a parameters file. We provide a "default" params file in the `usb_cam/config/params.yaml` directory to get you started. Feel free to modify this file as you wish. Also provided is a launch file that should launch the `usb_cam_node_exe` executable along with an additional node that displays an image topic. The commands to run each of these different ways of starting the node are shown below: **NOTE: you only need to run ONE of the commands below to run the node** ```shell # run the executable with default settings (without params file) ros2 run usb_cam usb_cam_node_exe # run the executable while passing in parameters via a yaml file ros2 run usb_cam usb_cam_node_exe --ros-args --params-file /path/to/colcon_ws/src/usb_cam/config/params.yaml # launch the usb_cam executable that loads parameters from the same `usb_cam/config/params.yaml` file as above # along with an additional image viewer node ros2 launch usb_cam camera.launch.py ``` ## Launching Multiple usb_cam's To launch multiple nodes at once, simply remap the namespace of each one: ```shell ros2 run usb_cam usb_cam_node_exe --remap __ns:=/usb_cam_0 --params-file /path/to/usb_cam/config/params_0.yaml ros2 run usb_cam usb_cam_node_exe --remap __ns:=/usb_cam_1 --params-file /path/to/usb_cam/config/params_1.yaml ``` ## Supported formats ### Device supported formats To see a connected devices supported formats, run the `usb_cam_node` and observe the console output. An example output is: ```log This devices supproted formats: Motion-JPEG: 1280 x 720 (30 Hz) Motion-JPEG: 960 x 540 (30 Hz) Motion-JPEG: 848 x 480 (30 Hz) Motion-JPEG: 640 x 480 (30 Hz) Motion-JPEG: 640 x 360 (30 Hz) YUYV 4:2:2: 640 x 480 (30 Hz) YUYV 4:2:2: 1280 x 720 (10 Hz) YUYV 4:2:2: 640 x 360 (30 Hz) YUYV 4:2:2: 424 x 240 (30 Hz) YUYV 4:2:2: 320 x 240 (30 Hz) YUYV 4:2:2: 320 x 180 (30 Hz) YUYV 4:2:2: 160 x 120 (30 Hz) ``` ### Driver supported formats The driver has its own supported formats. See [the source code](include/usb_cam/formats/) for details. After observing [the devices supported formats](#device-supported-formats), specify which format to use via [the parameters file](config/params.yaml) with the `pixel_format` parameter. To see a list of all currently supported driver formats, run the following command: ```shell ros2 run usb_cam usb_cam_node_exe --ros-args -p pixel_format:="test" ``` Note: "test" here could be replaced with any non-supported pixel format string. The driver will detect if the given pixel format is supported or not. More formats and conversions can be added, contributions welcome! ### Supported IO methods This driver supports three different IO methods as of today: 1. `read`: copies the video frame between user and kernal space 1. `mmap`: memory mapped buffers allocated in kernel space 1. `userptr`: memory buffers allocated in the user space To read more on the different methods, check out [this article that provides a good overview of each](https://lwn.net/Articles/240667/) ## Compression Big thanks to [the `ros2_v4l2_camera` package](https://gitlab.com/boldhearts/ros2_v4l2_camera#usage-1) and their documentation on this topic. The `usb_cam` should support compression by default since it uses `image_transport` to publish its images as long as the `image_transport_plugins` package is installed on your system. With the plugins installed the `usb_cam` package should publish a `compressed` topic automatically. Unfortunately `rviz2` and `show_image.py` do not support visualizing the compressed images just yet so you will need to republish the compressed image downstream to uncompress it: ```shell ros2 run image_transport republish compressed raw --ros-args --remap in/compressed:=image_raw/compressed --remap out:=image_raw/uncompressed ``` ## Address and leak sanitizing Incorporated into the `CMakelists.txt` file to assist with memory leak and address sanitizing is a flag to add these compile commands to the targets. To enable them, pass in the `SANITIZE=1` flag: ```shell colcon build --packages-select usb_cam --cmake-args -DSANITIZE=1 ``` Once built, run the nodes executable directly and pass any `ASAN_OPTIONS` that are needed: ```shell ASAN_OPTIONS=new_delete_type_mismatch=0 ./install/usb_cam/lib/usb_cam/usb_cam_node_exe ``` After shutting down the executable with `Ctrl+C`, the sanitizer will report any memory leaks. By default this is turned off since compiling with the sanatizer turned on causes bloat and slows down performance. ## Documentation [Doxygen](http://docs.ros.org/indigo/api/usb_cam/html/) files can be found on the ROS wiki. ### License usb_cam is released with a BSD license. For full terms and conditions, see the [LICENSE](LICENSE) file. ### Authors See the [AUTHORS](AUTHORS.md) file for a full list of contributors. ", Assign "at most 3 tags" to the expected json: {"id":"8682","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"