{"id":24396816,"url":"https://github.com/ai4ce/insta360_ros_driver","last_synced_at":"2025-07-08T21:35:13.253Z","repository":{"id":252443780,"uuid":"815092662","full_name":"ai4ce/insta360_ros_driver","owner":"ai4ce","description":"A ROS driver for Insta360 cameras, enabling real-time image capture, processing, and publishing in ROS environments.","archived":false,"fork":false,"pushed_at":"2025-03-16T21:02:01.000Z","size":6839,"stargazers_count":58,"open_issues_count":1,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-25T12:51:19.139Z","etag":null,"topics":["360-camera","driver","insta360","insta360-one-x2","insta360-one-x3","insta360-sdk","ros","webcam"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ai4ce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-14T10:36:27.000Z","updated_at":"2025-03-22T07:01:56.000Z","dependencies_parsed_at":"2024-08-29T19:17:42.016Z","dependency_job_id":"84b37310-e537-4bbc-a546-fc792c0e0478","html_url":"https://github.com/ai4ce/insta360_ros_driver","commit_stats":null,"previous_names":["ai4ce/insta360_ros_driver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai4ce%2Finsta360_ros_driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai4ce%2Finsta360_ros_driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai4ce%2Finsta360_ros_driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai4ce%2Finsta360_ros_driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ai4ce","download_url":"https://codeload.github.com/ai4ce/insta360_ros_driver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248442237,"owners_count":21104138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["360-camera","driver","insta360","insta360-one-x2","insta360-one-x3","insta360-sdk","ros","webcam"],"created_at":"2025-01-19T21:58:34.162Z","updated_at":"2025-04-11T16:41:49.312Z","avatar_url":"https://github.com/ai4ce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# insta360_ros_driver\n\nA ROS driver for the Insta360 cameras. This driver is tested on Ubuntu 20.04 with ROS Noetic. The driver has also been verified on the Insta360 X2 and X3 cameras.\n\n## Installation\nTo use this driver, you need to first have Insta360 SDK. Please apply for the SDK from the [Insta360 website](https://www.insta360.com/sdk/home). \n\n```\ncd ~/catkin_ws/src\ngit clone https://github.com/ai4ce/insta360_ros_driver\ncd ..\n```\nThen, the Insta360 libraries need to be installed as follows:\n- add the \u003ccode\u003ecamera\u003c/code\u003e and \u003ccode\u003estream\u003c/code\u003e header files inside the \u003ccode\u003einclude\u003c/code\u003e directory\n- add the \u003ccode\u003elibCameraSDK.so\u003c/code\u003e library under the \u003ccode\u003elib\u003c/code\u003e directory.\n\nAfterwards, install the other required dependencies and build\n```\nrosdep install --from-paths src --ignore-src -r -y\ncatkin build\n```\n\nBefore continuing, **make sure the camera is set to dual-lens mode**\n\nThe Insta360 requires sudo privilege to be accessed via USB. To compensate for this, a udev configuration can be automatically created that will only request for sudo once. The camera can thus be setup initially via:\n```\nrosrun insta360_ros_driver setup.sh\n```\nThis creates a symlink  based on the vendor ID of Insta360 cameras. The symlink, in this case \u003ccode\u003e/dev/insta\u003c/code\u003e is used to grant permissions to the usb port used by the camera.\n![setup](docs/setup.png)\n\n## Usage\nThis driver directly publishes the video feed in YUV format, since that is the camera's native setting. Alongside this, the driver also publishes the camera feed as standard BGR images to the \u003ccode\u003e/front_camera_image/compressed\u003c/code\u003e and \u003ccode\u003e/back_camera_image/compressed\u003c/code\u003e topics. Note that the compressed images have some amount of latency (~50 ms) compared to the raw output. \n\n### Camera Bringup\nThe camera can be brought up with the following launch file\n```\nroslaunch insta360_ros_driver bringup.launch\n```\n![bringup](docs/bringup_rqt.png)\nThis publishes the raw yuv and compressed images as the following topics\n- /insta_image_yuv\n- /front_camera_image/compressed\n- /back_camera_image/compressed\n\nThe launch file has the following optional arguments:\n- compress (default=\"true\")\n\nEnables the \u003ccode\u003e/live_processing\u003c/code\u003e which publishes the compressed front and back images. When set to false, only the raw YUV image is published\n\n- undistort (default=\"false\")\n\nWhen set to true, the \u003ccode\u003e/live_processing\u003c/code\u003e node will also use the specified intrinsic matrix, found in \u003ccode\u003econfig/config.yaml\u003c/code\u003e to undistort the images in real-time. **Note that this process can reduce the frame rate and/or increase latency.** It is therefore recommended to keep it as 'false' and perform undistortion in post-processing, as will be shown in the next section.\n\n- debug (default=\"false\")\n\nWhen set to true, additional diagnostic windows are created. These show the publishing frequency and image size. Note that **xterm** is required for this functionality, and can be installed using the following command.\n```\nsudo apt-get install xterm\n```\n\n### Recording to a Bag File\nWhile the camera driver is active (via the bringup launch file above), data can be recorded to a bag file using\n```\nroslaunch insta360_ros_driver bag_record.launch\n```\n**The bag file save locations are specified within \u003ccode\u003econfig/config.yaml\u003c/code\u003e**\n![config.yaml](docs/config.png)\n\nThe launch file contains one optional argument:\n- bag_type (default=\"compressed\", options=\"\\[\"raw\", \"compressed\", \"undistorted\"\\])\n\nThis specifies which directory to save the bag_files to, as specified in \u003ccode\u003econfig/config.yaml\u003c/code\u003e When set to \"raw\", it will only record the \u003ccode\u003e/insta_image_yuv\u003c/code\u003e topic. Note that when specifying the \u003ccode\u003ebag_type\u003c/code\u003e to be \"undistorted\", \u003ccode\u003eundistort:=true\u003c/code\u003e must be set for \u003ccode\u003ebringup.launch\u003c/code\u003e\n\nThe Raw YUV image appears as follows:\n\n![YUV](docs/yuv.png)\n\n### Post-Processing: Image Compression and Splitting\nGiven a bag file containing raw YUV image data, the images can be split to front and back and also compressed using the following launch file.\n```\nroslaunch insta360_ros_driver bag_compress.launch\n```\nThis launch file reads all the bag files specified in the \u003ccode\u003eraw_bag_folder\u003c/code\u003e within the \u003ccode\u003econfig/config.yaml\u003c/code\u003e file and outputs bag files containing split and compressed images into the \u003ccode\u003ecompressed_bag_folder\u003c/code\u003e directory. The compressed images are within the \u003ccode\u003e/front_camera_image/compressed\u003c/code\u003e and \u003ccode\u003e/back_camera_image/compressed\u003c/code\u003e topics.\n\nAfter compression and splitting, the images appear as follows:\n![BGR](docs/bgr.png)\n\n### Post-Processing: Image Undistortion\nGiven a bag file containing compressed front and back images, these images can be undistorted using the following launch file.\n```\nroslaunch insta360_ros_driver bag_undistort.launch\n```\nThis launch file reads all the bag files specified in the \u003ccode\u003ecompressed_bag_folder\u003c/code\u003e within the \u003ccode\u003econfig/config.yaml\u003c/code\u003e file and outputs bag files undistorted images into the \u003ccode\u003eundistorted_bag_folder\u003c/code\u003e directory. The images are undistorted using the intrinsics specified inside the \u003ccode\u003econfig/config.yaml\u003c/code\u003e file and are within the \u003ccode\u003e/front_camera_image/compressed\u003c/code\u003e and \u003ccode\u003e/back_camera_image/compressed\u003c/code\u003e topics.\n\nAfter undistortion, the images appear as follows:\n![undistorted](docs/undistort.png)\n\n### Bag Preview\nThe compressed and undistorted bag files can be previewed using RViz via the following launch file.\n```\nroslaunch insta360_ros_driver bag_preview.launch\n```\n\nThe launch file has the following argument:\n- bag_file (default=\"~/bag/undistorted/record.bag\")\n\nThis is the filepath of the bag file that will be previewed. Please make sure to change this accordingly. \n\nWhen launched, an RViz window will be created showing both front and back images, as was previously demonstrated in earlier sections of the documentation\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=ai4ce/insta360_ros_driver\u0026type=Date)](https://star-history.com/#ai4ce/insta360_ros_driver\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fai4ce%2Finsta360_ros_driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fai4ce%2Finsta360_ros_driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fai4ce%2Finsta360_ros_driver/lists"}