Skip to content

installation.md

Latest commit

 

History

History
executable file
·
137 lines (89 loc) · 4.61 KB

installation.md

File metadata and controls

executable file
·
137 lines (89 loc) · 4.61 KB
Raw

RayCloudTools Installation Guide

This guide provides detailed instructions on how to install RayCloudTools using Docker and also compiling from source. It also includes optional build dependencies and instructions for running unit tests.

Installation via Docker

RayCloudTools is designed for Linux environments. However, thanks to Docker, it can be easily installed and run on Mac and Windows systems as well.

Getting Started with Docker

  1. Install Docker Desktop: Follow the installation instructions available at Docker's official documentation.

  2. Build the Docker Image from the Dockerfile:

    To build the image from the Dockerfile within the repository, follow these steps:

    • Clone the repository with:

      git clone https://github.com/csiro-robotics/raycloudtools.git

    • Navigate to the directory containing the Dockerfile within the cloned git folder. The Dockerfile is located in raycloudtools/docker, change to this directory in your terminal or PowerShell.

    • Build the Docker image by running the following command:

      docker build -t raycloudtools:latest .

      This command does the following:

      • docker build: Builds a Docker image from a Dockerfile.
      • -t raycloudtools:latest: Tags the built image with the name raycloudtools and tag latest.
      • .: Specifies the location of the Dockerfile and context for the build. . denotes the current directory.

  3. Run the RayCloudTools Image:

    After building the image, proceed with running the container:

    • For Windows users, open PowerShell.

    • For Mac users, open Terminal.

    • Run the following command:

      docker run -it -v C:/:/mnt/ raycloudtools:latest

      This command has the following effects:

      • docker run: Executes a Docker container.
      • -it: Allows interactive processes by keeping STDIN open and allocating a pseudo-TTY.
      • -v C:/:/mnt/: Mounts the host system's root directory to /mnt/ inside the container. Adjust the host path as necessary, for example, to an external drive.
      • raycloudtools:latest: Specifies the Docker image and tag to use.

    On the first execution, Docker will run the container based on the specified image. You can find the container in Docker Desktop under ‘Containers’.

Compiling from Source (Ubuntu Linux)

For those preferring to compile RayCloudTools from source, follow these steps:

  1. Install Dependencies:

    sudo apt-get install libeigen3-dev

  2. Compile and Install Libraries:

    • Compile libnabo:

      git clone https://github.com/ethz-asl/libnabo.git
cd libnabo
git checkout tags/1.0.7
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
make && sudo make install
cd ../..

    • Compile RayCloudTools:

      git clone https://github.com/csiro-robotics/raycloudtools.git
cd raycloudtools
mkdir build && cd build
cmake ..
make

  3. Setting the PATH:

    • To run the rayXXXX tools from anywhere, update your ~/.bashrc or execute sudo make install. For updating ~/.bashrc, add: 
      export PATH=$PATH:/path/to/raycloudtools/build/bin

Optional Build Dependencies

Follow these additional steps for specific functionalities:

  • For .laz file support with rayimport:

    • Install LASzip and libLAS as described, ensuring you disable GEOTIFF in libLAS and enable WITH_LAS during the raycloudtools build process.

  • For .rxp file support:

    • Download and install RiVLib from the RIEGL website, add RiVLib to your system path, and enable WITH_RIEGL during the raycloudtools build.

  • For raywrap functionality:

    • Clone and compile qhull, ensuring you enable WITH_QHULL during the raycloudtools build.

  • To render clouds to .tif images:

    • Follow the instructions for compiling libgeotiff, including adjusting your LD_LIBRARY_PATH as needed, and enable WITH_TIFF during the raycloudtools build.

Running Unit Tests

Unit tests ensure the reliability of RayCloudTools outputs. If used they should be enabled at build time.

Enabling Unit Tests

  • During the initial configuration in the build directory, enable unit tests with:

    cmake -DRAYCLOUD_BUILD_TESTS=ON ..

Executing Tests

  • Using CTest:

    • Navigate to the build directory.
    • Execute ctest . Optionally, specify the build configuration (e.g., ctest . -C Release).

  • Direct Invocation:

    • Ensure you are in the build/bin directory.
    • Execute the tests with ./raytest.