finish readme

Author: IrvingF7

README.md

@@ -1,2 +1,63 @@
 # realsense_ROS2_interface
-This package interfaces the robot/joystick with the realsense ROS2 wrapper
+
+This ROS2 package interfaces robots and/or joysticks with the official Intel RealSense ROS wrapper.
+
+While it's targeting Intel RealSense and Sony Playstation Joystick, the package can be easily modified to work with any USB camera and controller.
+
+For any questions, please contact the author, [Irving Fang](https://irvingf7.github.io/).
+
+This package is heavily influenced and inspired by a [similar ROS1 package](https://github.com/ripl/capture-images) written by [Dr. Takuma Yoneda](https://takuma.yoneda.xyz/) from TTIC.
+
+## Setup
+This package is only tested on `Ubuntu 22.04` and `ROS humble` distribution.
+
+It requires the official [RealSense ROS2 wrapper](https://github.com/IntelRealSense/realsense-ros) and the Intel RealSense SDK.
+
+I expect this package to be easily portable to other Ubuntu versions and ROS 2 distros, since it does not utilize anything specific to `Ubuntu 22.04` and `ROS humble`.
+
+
+
+## Installation
+
+After acquiring all the prerequisites, simply put this folder (which contains two ROS2 packages, technically speaking) inside your ROS workspace's `src` folder and run the following command in your ROS workspace.
+
+```
+colcon build
+```
+
+
+## Package Breakdown
+I will walk through the package structure briefly here. Feel free to skip over if you are familiar with how a typical ROS2 package works.
+
+This project is actually made of two ROS2 packages:
+
+- `realsense_capture`: contains all the code that actually does the job.
+
+- `realsense_interface_msg`: contains the definition for the service message type that's being used.
+
+It's a conventional ROS practice to dedicate an independent package for message type definitions.
+
+Inside `realsense_capture`:
+- `realsense_image_server.py`: responsible for constantly getting images from the camera, and is ready to serve the image whenever requested, that is, the capture button on the joystick is hit.
+
+- `realsense_image_client.py`: responsible for acquiring the image whenever the capture button on the joystick is hit. 
+
+
+## Usage
+To use the package, run
+
+```bash
+ros2 launch realsense_capture realsense_sys_launch.py
+```
+
+***Note***: The launch file also launches Foxglove, a visualization/monitoring app for ROS2. Get rid of related lines if desired. 
+
+There is no need to launch the RealSense ROS wrapper separately, as they are integrated in the launch file.
+
+
+## Contributing
+
+Contributions to this project are welcome. If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.
+
+## Citation
+If you find this little package helpful, please consider citing it in your paper/work.

realsense_capture/launch/realsense_sys_launch.py

@@ -88,7 +88,7 @@
                            {'name': 'hdr_merge.enable',             'default': 'false', 'description': 'hdr_merge filter enablement flag'},
                            {'name': 'wait_for_device_timeout',      'default': '-1.', 'description': 'Timeout for waiting for device to connect (Seconds)'},
                            {'name': 'reconnect_timeout',            'default': '6.', 'description': 'Timeout(seconds) between consequtive reconnection attempts'},
-                           {'name': 'img_folder',                   'default': '/home/irving/Desktop', 'description': 'folder to save images'},
+                           {'name': 'save_folder',                   'default': '/home/irving/Desktop', 'description': 'folder to save images'},
                           ]
 
 def declare_configurable_parameters(parameters):
@@ -160,7 +160,7 @@ def generate_launch_description():
         package='realsense_capture',
         executable='image_client',
         name='image_client',
-        parameters=[{'img_folder': launch_params['img_folder'],
+        parameters=[{'save_folder': launch_params['save_folder'],
                      }]
     )
 

realsense_capture/realsense_capture/image_client.py realsense_capture/realsense_capture/realsense_image_client.py

@@ -28,8 +28,8 @@ def __init__(self):
 
         ############################ Launch Parameters ########################################
         # parameter handling
-        self.declare_parameter(name = 'img_folder', value = '/home/irving/Desktop')
-        self.img_folder = self.get_parameter('img_folder').get_parameter_value().string_value
+        self.declare_parameter(name = 'save_folder', value = '/home/irving/Desktop')
+        self.save_folder = self.get_parameter('save_folder').get_parameter_value().string_value
 
         ############################ Client Setup #############################################
         # rgb client
@@ -75,7 +75,7 @@ def postprocess(self, img, modality):
         '''
         encoded_img = self.cvbridge.imgmsg_to_cv2(img_msg=img, 
                                                   desired_encoding='passthrough')
-        cv2.imwrite(os.path.join(self.img_folder, f'{modality}_{img.header.stamp.sec}.png'), encoded_img)
+        cv2.imwrite(os.path.join(self.save_folder, f'{modality}_{img.header.stamp.sec}.png'), encoded_img)
 
         # color the log message
         color_start = '\033[94m'

realsense_capture/realsense_capture/image_server.py realsense_capture/realsense_capture/realsense_image_server.py

@@ -24,8 +24,8 @@
     tests_require=['pytest'],
     entry_points={
         'console_scripts': [
-            'image_server = realsense_capture.image_server:main',
-            'image_client = realsense_capture.image_client:main',
+            'realsense_image_server = realsense_capture.realsense_image_server:main',
+            'realsense_image_client = realsense_capture.realsense_image_client:main',
         ],
     },
 )