Merge branch 'master' of https://agile.bu.edu/gitlab/ec504/ec504_projects/group8

INSTALL.txt

===========

Pre-conditions:

---------------

This code requires a Unix/Linux-based system due to the shell script dependencies and environment configurations. It has been specifically tested on standard lab machines but should be compatible with most Linux distributions. The software relies on Java 17 and Apache Maven, which are included in the installation steps.

Hardware Requirements:

- A machine capable of running Java 17 efficiently, preferably with at least 4GB of RAM for optimal performance of the object detection and VSLAM processing.

Software Requirements:

- Java JDK 17

- Apache Maven 3.9.6

- A Unix/Linux-based operating system

Supporting Files:

-----------------

All required libraries are managed through Maven, which will handle the dependencies automatically as specified in the project's pom.xml file. No additional manual installation of libraries is required beyond the initial setup performed by `install.sh`.

Examples of Project Usage:

- `data_installation.sh`: Download and install one of two datasets based on the user's input. The available options are:

    1. TUM_RGB: The Freiburg3 Long Office Household dataset, suitable for testing robustness in indoor environments.

    2. EuRoC_Mav: The Machine Hall 01 Easy dataset from the EuRoC MAV dataset series, ideal for aerial vehicle-based environments.

    Usage Example:

    `./data_installation.sh TUM_RGB`

    `./data_installation.sh EuRoC_Mav`

    *NOTE TO PEER REVIEWERS: RUNNING THIS SCIPT IS NOT NECESSARY FOR ASSESSMENT OF OUR PROJECT. We provided KeyFrames to execute the main components already*

- `run_vslam.sh`: After downloading a dataset, generate key frames and key frame points using the downloaded dataset. 

    Ensure that the dataset being specified is the same one that was downloaded above

    Usage Example:

        ./run_vslam.sh TUM_RGB

        ./run_vslam.sh EuRoC_Mav

    *NOTE TO PEER REVIEWERS: RUNNING THIS SCIPT IS NOT NECESSARY FOR ASSESSMENT OF OUR PROJECT. The VSLAM algorithm as already been run for your convinience*

- `run_obj_detection.sh`: Perform object detection on generated key frames, modifying the project configuration temporarily to use YOLO.

    To measure effectiveness of this script, remove the following two provided directories `/src/main/java/vslam/BoundedInfo` and `/src/main/java/vslam/BoundedKeyFrames`

    Execution of this script should regenerate those two directories

    *NOTE TO PEER REVIEWERS: RUNNING THIS SCIPT IS NOT NEEDED TO EXECUTE OUR PROJECT. THE BoundedInfo is pregenerated for your convinience*

- `data_installation.sh` installs a large amount of data and `run_vslam.sh` executes Matlab code under the hood, so they are not required to be run by peer reviewers

Descriptions of Testing Patterns:

---------------------------------

Testing in this project is divided into two main categories:

1. Object Detection Tests:

   - These tests are run using the `mvn test` command. They focus on edge cases and the precision of data structures like 'Point', 'objectSet', and 'boundingBox'.

2. YOLO Tests:

   - Navigate to the YOLO testing directory and compile the `YOLOTest` class. This will execute tests for the YOLO object detection framework, outputting bounding boxes on images and generating corresponding CSV files for verification.

   Testing Commands:

    `cd path/to/yolo_test_directory`

    `javac YOLOTest.java`

    `java YOLOTest`

    This will compare the output with provided baseline image (`KeyFrame_0060.csv`) to verify accuracy and reproducibility.

Execution:

----------

To compile and run the project:

1. Execute `./install.sh`

2. Run `source ~/.bashrc`

3. Execute `mvn clean install -DskipTests` to build the project, skipping tests during development to speed up the build process.

4. Run `mvn exec:java` to execute the main application, which will start the configured object detection or VSLAM process as specified in the pom.xml file's main class configuration.

This documentation ensures that any student or developer can set up, understand, and use the project from scratch on a compatible machine.

#!/bin/bash

# Define the target directory for dataset installation

TARGET_DIR="/src/main/java/vslam"

# Check for correct usage

if [ "$#" -ne 1 ]; then

    echo "Usage: $0 {TUM_RGB|EuRoC_Mav}"

    exit 1

fi

# Setup dataset URLs and filenames based on the argument

if [ "$1" = "TUM_RGB" ]; then

    URL="https://cvg.cit.tum.de/rgbd/dataset/freiburg3/rgbd_dataset_freiburg3_long_office_household.tgz"

    FILENAME="rgbd_dataset_freiburg3_long_office_household.tgz"

elif [ "$1" = "EuRoC_Mav" ]; then

    URL="http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip"

    FILENAME="MH_01_easy.zip"

else

    echo "Invalid dataset name. Choose either TUM_RGB or EuRoC_Mav."

    exit 2

fi

# Create target directory if it does not exist

mkdir -p $TARGET_DIR

# Change to the target directory

cd $TARGET_DIR

# Download the dataset

echo "Downloading $FILENAME ..."

wget $URL -O $FILENAME

# Extract the dataset

echo "Extracting $FILENAME ..."

if [[ $FILENAME == *.tgz ]]; then

    tar -xzvf $FILENAME

elif [[ $FILENAME == *.zip ]]; then

    unzip $FILENAME

fi

# Remove the compressed file after extraction

rm $FILENAME

echo "Installation and extraction complete!"

#!/bin/bash

# Define the POM file location

POM_FILE="pom.xml"

# Function to modify the POM file to use YOLODetector

use_yolo_detector() {

    # Backup the original POM file

    cp $POM_FILE "${POM_FILE}.bak"

    # Replace the main class to use YOLODetector

    sed -i 's|<exec.mainClass>object_detection.ObjectDetector</exec.mainClass>|<exec.mainClass>yolo.YOLODetector</exec.mainClass>|g' $POM_FILE

}

# Function to restore the original POM file

restore_original_pom() {

    # Restore the original POM file from backup

    mv "${POM_FILE}.bak" $POM_FILE

}

# Use YOLODetector for object detection

use_yolo_detector

# Run Maven commands to clean, build, and execute the project

mvn clean install -DskipTests

mvn exec:java

# Restore the original POM configuration

restore_original_pom

echo "Object detection has completed. The POM file has been restored to its original configuration."

#!/bin/bash

# Define the script that runs the VSLAM implementation

MATLAB_SCRIPT="/src/main/java/vslam/vslam_implementation.m"

# Check if the correct number of arguments was provided

if [ "$#" -ne 1 ]; then

    echo "Usage: $0 {TUM_RGB|EuRoC_Mav}"

    exit 1

fi

# Determine which dataset to use based on the argument provided

if [ "$1" = "TUM_RGB" ]; then

    DATASET_PATH="/src/main/java/vslam/rgbd_dataset_freiburg3_long_office_household/rgb"

elif [ "$1" = "EuRoC_Mav" ]; then

    DATASET_PATH="/src/main/java/vslam/mav0/cam0/data"

else

    echo "Invalid dataset name. Choose either TUM_RGB or EuRoC_Mav."

    exit 2

fi

# Navigate to the MATLAB script directory (assuming MATLAB can be called from command line)

cd /src/main/java/vslam

# Run the MATLAB script with the dataset path

matlab -batch "worldPointSet = vslam_implementation('${DATASET_PATH}'); save('worldPointSet.mat', 'worldPointSet');"

echo "VSLAM processing complete. Output saved in worldPointSet.mat"