360toPerspective/cpp/include/Slicer360ToPerspective.hpp

#ifndef H_Slicer360ToPerspective
#define H_Slicer360ToPerspective

#include <Camera.hpp>
#include <Image.hpp>

/// @brief This class encapsulates the algorithms to convert a 360-degree image to perspective images.
/// @details The 360-degree image is converted to perspective images by projecting the pixels of the 360-degree image using perspective projection and virtual cameras.
/// The virtual cameras are added to the slicer using the AddCamera() method.
/// The output images are saved in the folder specified by the SetOutputFolder() method.
/// By default, the ProjectToCameras and ProjectToAllCameras are parallelized using OpenMP.
class Slicer360ToPerspective {
    public:
        /// @brief Builds a Slicer360ToPerspective object using a 360-degree image.
        /// @param panorama_image The 360-degree image to be used as an input.
        Slicer360ToPerspective(Image const& panorama_image_ = Image(1,1,3));

        /// @brief Sets the 360-degree image to be used as an input.
        /// @param panorama_image_ 360-degree image to be used as an input.
        /// @return A reference to the current object.
        Slicer360ToPerspective & SetPanoramaImage(Image const& panorama_image_);

        /// @brief Sets the width of the output images.
        /// @param width Width of the output images in pixels.
        /// @param height Height of the output images in pixels. By default = -1. If < 0, the height is set to the width to yield a square image.
        /// @return A reference to the current object.
        Slicer360ToPerspective & SetOutputImageSize(int width, int height = -1);

        /// @brief Sets the interpolation method used to project the 360-degree image to perspective images. See Image::InterpMethod.
        /// @param interpolation_method_ Interpolation method used to project the 360-degree image to perspective images.
        /// @return A reference to the current object.
        Slicer360ToPerspective & SetInterpolationMethod(Image::InterpMethod const& interpolation_method_);
        
        /// @brief Sets the folder where the output images are saved. By default, the output images are saved in the current folder.
        /// @param folder Folder where the output images are saved.
        /// @return A reference to the current object.
        Slicer360ToPerspective & SetOutputFolder(std::string const& folder);

        /// @brief Sets the cameras used to convert the 360-degree image to perspective images.
        /// @details The camera vector is directly accessible through the public "cameras" attribute. This method is provided for convenience and consistency.
        /// @param cameras_     A vector of cameras used to project the 360-degree image.
        /// @return A reference to the current object.
        Slicer360ToPerspective & SetCameras(std::vector<Camera> const& cameras_);

        /// @brief Computes the coverage of the 360-degree image by the cameras added to the slicer.
        /// @param width Width of the generated 360-degree image containing the results of the analysis.
        /// @param raw   If true, the output is the number of cameras that see the pixel of the 360 image (8-bit monochrome image). If false, the output is a colored RGB image.
        /// @return The coverage of the 360-degree image.
        Image ComputeCoverage(int width, bool raw = false) const;

        /// @brief Projects the 360-degree image to a perspective image using the specified camera.
        /// @param camera The camera used to project the 360-degree image.
        /// @return The generated perspective image.
        Image ProjectToCamera(Camera const& camera) const;

        /// @brief Projects the 360-degree image to perspective images using the specified cameras.
        /// @param cameras  A vector of cameras used to project the 360-degree image.
        /// @return A vector of generated perspective images.
        std::vector<Image> ProjectToCameras(std::vector<Camera> const& cameras_) const;

        /// @brief Projects the 360-degree image to perspective images using all the cameras added to the slicer.
        /// @return A vector of generated perspective images.
        std::vector<Image> ProjectToAllCameras() const;

        /// @brief Loads the cameras from a CSV file.
        /// @details The CSV file should contain one camera per row and the columns should be in the following order:
        ///          - Yaw   (degrees)
        ///          - Pitch (degrees)
        ///          - Roll  (degrees)
        ///          - FOV   (degrees)
        /// @param filename File path of the CSV file.
        /// @return A reference to the current object.
        Slicer360ToPerspective & LoadCamerasFromFile(std::string const& filename);

        std::vector<Camera> cameras;//!< A vector of cameras that are used to convert the 360-degree image to perspective images.
    
    private:
        /// @brief Computes the projection of the 360-degree image to a perspective image using the specified camera on a single pixel of the output image.
        /// @param camera The camera used to project the 360-degree image.
        /// @param i      The y-coordinate of the pixel of the output image (row).
        /// @param j      The x-coordinate of the pixel of the output image (column).
        /// @return The color of the pixel of the output image.
        Eigen::Vector3i ProjectToCameraPixel(Camera const& camera, int i, int j) const;

        Image panorama_image;                       //!< The 360-degree input image.
        int output_image_width;                     //!< Width of the output images in pixels.
        int output_image_height;                    //!< Height of the output images in pixels.
        Image::InterpMethod interpolation_method;   //!< Interpolation method used to project the 360-degree image to perspective images.
        std::string output_folder;                  //!< Folder where the output images are saved.
};

#endif