Created a readme file for the perception team and wrote initial sensor fusion documentation and set up instructions

Author: LucasEby

GEMstack/onboard/perception/README.md

@@ -0,0 +1,70 @@
+# Perception Team
+This folder contains code that is used to detect objects in 3D space and subsequently notify other GEMstack components of the detected objects. It is split up into 3 main areas: Pedestrian detection code created at the beginning-middle of the course, Cone Detection code that is used to detect cones (optionally with orientation), and Sensor Fusion code which fuses YOLO + painted lidar data and PointPillars 3D bounding boxes to detect pedestrians.
+
+## Cone Detection
+Description goes here.
+
+### Relevant Files
+- cone_detection.py
+- perception_utils.py
+
+
+## Sensor Fusion
+To improve the quality of the detected pedestrians, we decided to fuse detections from multiple modalities to take advantage of the strengths each sensor (camera and lidar in our case) provides. We accomplished this by fusing the 3D bounding box detections of pedestrians generated by YOLO (model which detects pedestrians with camera data) + painted lidar data and PointPillars (model which detects pedestrians with only lidar data). 
+
+### Relevant Files
+#### Setup files to create PointPillars Cuda 11.1.1 Docker container:
+- build_point_pillars.sh
+- setup/docker-compose.yaml
+- setup/Dockerfile.cuda111
+
+#### Code used to detect pedestrians:
+- combined_detection.py
+- point_pillars_node.py
+- yolo_node.py
+
+#### Code used to analyze the results of detections and extract data from rosbags for further analysis:
+- eval_3d_bbox_performance.py
+- rosbag_processor.py
+- test_eval_3d_bbox_performance.py
+
+### Local Installation Steps for PointPillars Docker Container
+#### READ BEFOREHAND: 
+- Before perfoming installation steps, please make sure you source ALL terminal windows (except for docker terminal window). 
+$ source /opt/ros/noetic/setup.bash
+$ source ~/catkin_ws/devel/setup.bash
+- These instructions were written with the assumption that you are running them inside of the outermost GEMstack folder.
+- If you have set up issues please read the "Set Up Issues Known Fixes" section at the bottom.
+
+#### Steps:
+1. Install Docker
+2. Install Docker Compose
+3. A bash script was created to handle docker permissions issues and make the set up process simpler:
+$ bash GEMstack/onboard/perception/build_point_pillars.sh
+4. Start the container (use sudo if you run into permissions issues)
+$ docker compose -f GEMstack/onboard/perception/setup/docker-compose.yaml up
+5. Run roscore on local machine (make sure you source first)
+$ roscore
+6. Start up YOLO node (make sure you source first):
+$ python3 GEMstack/onboard/perception/yolo_node.py
+7. Run yaml file to start up the CombinedDetector3D GEMstack Component (make sure you source first):
+$ python3 main.py --variant=detector_only launch/combined_detection.yaml
+8. Run a rosbag on a loop (make sure you source first):
+$ rosbag play -l yourRosbagNameGoesHere.bag 
+
+### Vehicle Installation Steps for PointPillars Docker Container
+Perform the same setup steps as the above section with the below exceptions:
+1. Ensure you source instead with the following command:
+$ source ~/demo_ws/devel/setup.bash 
+2. Initialize the sensors:
+$ roslaunch basic_launch sensor_init.launch
+3. Initialize GNSS (if you need it)
+$ roslaunch basic_launch visualization.launch
+4. Do not run a rosbag in Step 8 above (it's not needed since you'll be getting live data from the vehicle)
+
+#### Known Fixes for Set Up Issues
+1. If you get a shape error when creating the "results_normal" variable in yolo_node.py, please downgrade your Ultralytics version to 8.1.5 (this is the version used on the car at the time of writing this):
+$ pip install 'ultralytics==8.1.5'
+2. If you run into communication issues with ROS, please make sure you have sourced EVERY terminal window (except for docker window there's no need to): 
+$ source /opt/ros/noetic/setup.bash
+$ source ~/catkin_ws/devel/setup.bash