ProfilerCalibrationInterfaces.h

/*******************************************************************************
 * BSD 3-Clause License
 *
 * Copyright (c) 2016-2025, Mech-Mind Robotics Technologies Co., Ltd.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 *   contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Info:  https://www.mech-mind.com/
 *
 ******************************************************************************/
 
#pragma once
#include <memory>
#include <optional>
#include <opencv2/core/mat.hpp>
#include "api_global.h"
#include "profiler/ProfileData.h"
#include "profiler/calibration/MultiProfilerErrorStatus.h"
#include "profiler/calibration/ProfilerHandEyeErrorStatus.h"
#include "profiler/calibration/ProfilerCalibrationTypes.h"
 
namespace mmind {
namespace eye {
class MultiProfilerCalibration;
class MMIND_API_EXPORT ProfilerCalibrationInterfaces
{
public:
    enum class CloudStitchOption {
        RefineStitchParameters = 1, 
        OverlapRegionUniformSampling =
            2, 
    };

    enum class StitchParamRefineOption {
        RefineT = 1, 
    };
 
    using CorrectedResult = TransformedImageInfo;
 
public:
    ProfilerCalibrationInterfaces();
    ~ProfilerCalibrationInterfaces();

    bool setCalibCameraModel(const std::string& cameraModel);

    void setMajorDeviceInfo(const DeviceInfo& deviceInfo);

    void setMinorDeviceInfos(const std::vector<DeviceInfo>& deviceInfos);

    void setCalibTargetSize(const TargetSize& targetSize);

    void setCalibTargetPoses(const std::vector<TargetPose>& targetPoses);

    MultiProfilerErrorStatus calculateCalibration(
        const cv::Mat& majorDepth, const std::vector<cv::Mat>& minorDepths,
        std::vector<CalibResult>& calibResults, bool unifiedMoveDirection = true,
        const std::optional<cv::Point3f>& majorCameraMoveDirVec = std::nullopt);

    MultiProfilerErrorStatus calibrateSingleProfilerMoveDirection(
        const cv::Mat& firstDepth, const cv::Mat& secondDepth, ProfilerMovementAxis moveAxis,
        MoveDirCalibResult& calibResult,
        const std::optional<cv::Point3f>& knownYAxisMoveDir = std::nullopt);

    MultiProfilerErrorStatus calibrateSingleProfilerWidthExpansion(
        const cv::Mat& firstDepth, const cv::Mat& secondDepth,
        const std::vector<RefPositionBias>& refPositionBiases, std::vector<StitchParams>& results,
        const std::optional<cv::Point3f>& knownYAxisMoveDir = std::nullopt);

    ProfilerHandEyeErrorStatus calibrateTrussRobot(
        const std::vector<TrussRobotCalibMatchedPoint>& matchedPoints,
        const TrussRobotCalibConfig& config, TrussRobotCalibResult& calibResult);

    ProfilerHandEyeErrorStatus transformPointFromProfilerCoord2TrussRobotCoord(
        const cv::Point3f& profilerPoint, const cv::Point3f& profilerCapturePosition,
        const TrussRobotCalibResult& calibResult, cv::Point3f& dstPoint,
        const std::optional<cv::Point3f>& tcpOffSet = std::nullopt);

    MultiProfilerErrorStatus correctProfilerMoveDir(const cv::Point3f& moveDirVec,
                                                    const ProfilerImage& srcImage,
                                                    CorrectedResult& result,
                                                    const MoveDirCorrectionOptions& options = {});

    MultiProfilerErrorStatus stitchProfilerWidthExpansion(
        const ImageInfo& majorImageInfo, const std::vector<ImageInfo>& minorImageInfos,
        const WidthExpansionType& type, FusionResult& results,
        const std::vector<StitchParams>& multiParams, bool fusionFlag);

    MultiProfilerErrorStatus stitchProfilerWidthExpansion(
        const ImageInfo& majorImageInfo, const std::vector<ImageInfo>& minorImageInfos,
        const WidthExpansionType& type, FusionResult& results,
        const std::vector<StitchParams>& multiParams, bool fusionFlag,
        const std::vector<bool>& moveConsistentFlags);

    bool saveCalibFiles(bool needSaveAll = true, const std::string& saveFolderName = "") const;

    MultiProfilerErrorStatus stitchImages(
        const ProfilerImage& majorImage, const std::vector<ProfilerImage>& minorImages,
        const std::vector<CalibResult>& calibResults, MultiStitchResult& stitchResults,
        const std::optional<MultiStitchParams>& stitchParams = std::nullopt);

    MultiProfilerErrorStatus stitchImagesForZParallel(
        const ProfilerImage& majorImage, const std::vector<ProfilerImage>& minorImages,
        const std::vector<CalibResult>& calibResults, MultiStitchResultZParallel& stitchResults,
        const std::optional<MultiStitchParams>& stitchParams = std::nullopt);

    MultiProfilerErrorStatus stitchPointCloud(
        const ProfilerImage& majorImage, const std::vector<ProfilerImage>& minorImages,
        int cloudStitchOption, int paramRefineOption, const std::vector<CalibResult>& calibResults,
        bool correctRingError = true, int normalEstimationKnn = -1,
        const std::optional<MultiStitchParams>& stitchParams = std::nullopt);

    MultiProfilerErrorStatus getStitchedPointCloud(
        ProfileBatch::UntexturedPointCloud& pointCloud) const;

    MultiProfilerErrorStatus getStitchedPointCloud(
        ProfileBatch::TexturedPointCloud& texturedPointCloud) const;

    MultiProfilerErrorStatus imageFusionForZParallel(FusionResult& fusionResult,
                                                     const std::vector<bool>& fusionFlag = {});

    MultiProfilerErrorStatus imageFusionForZParallel(const MultiStitchResultZParallel& stitchResult,
                                                     const cv::Point2i& majorBias,
                                                     FusionResult& fusionResult,
                                                     const std::vector<bool>& fusionFlag = {});

    bool saveStitchFiles(const std::string& saveFolderName = "") const;

    bool saveStitchFilesForZParallel(const std::string& saveFolderName = "") const;

    MultiProfilerErrorStatus loadCalibProperties(const std::string& loadFolderName = "",
                                                 bool needLoadAll = false);
    std::vector<CalibResult> getCurrentCalibResults() const;

    DeviceInfo getMajorDeviceInfo() const;

    TargetSize getTargetSize() const;

    std::string getCameraModel() const;

    std::vector<DeviceInfo> getMinorDeviceInfos() const;

    std::vector<TargetPose> getTargetPoses() const;

    ProfilerCalibrationInterfaces(const std::string& cameraModel, const DeviceInfo& majorDeviceInfo,
                                  const std::vector<DeviceInfo>& minorDeviceInfos,
                                  const TargetSize& targetSize,
                                  const std::vector<TargetPose>& targetPoses);

    ProfilerCalibrationInterfaces(const std::string& cameraModel,
                                  const DeviceInfo& profilerDeviceInfo,
 
                                  const TargetSize& targetSize,
                                  const std::vector<TargetPose>& targetPoses);
 
private:
    friend class InternalInterfaces;
    std::unique_ptr<MultiProfilerCalibration> calibrationInstance;
};
 
} // namespace eye
 
} // namespace mmind