parameter.h

/*******************************************************************************
 * Copyright (c) 2024 Allied Vision Technologies GmbH
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *******************************************************************************/
 
#ifndef VISIONTRANSFER_PARAMETER_H
#define VISIONTRANSFER_PARAMETER_H
 
#include <string>
#include <vector>
#include <map>
 
#include <cstring>
#include <sstream>
#include <iomanip>
#include <limits>
#include <memory>
 
#include <visiontransfer/common.h>
#include <visiontransfer/parametervalue.h>
#include <visiontransfer/internal/conversionhelpers.h>
 
namespace visiontransfer {
namespace param {
 
class Parameter {
 
private:
    // We follow the pimpl idiom
    class Pimpl;
    Pimpl* pimpl;
 
public:
    enum GovernorType {
        GOVERNOR_NONE      = 0,
        GOVERNOR_SHELL     = 1,
        GOVERNOR_DBUS      = 2
    };
 
    enum ParameterAccessMode {
        ACCESS_NONE        = 0,
        ACCESS_READONLY    = 1,
        ACCESS_READWRITE   = 2
    };
 
    enum ParameterInteractionHint {
        INTERACTION_INVISIBLE = -1,
        INTERACTION_INACTIVE = 0,
        INTERACTION_ACTIVE = 1
    };
 
    enum GovernorFunction {
        GOVERNOR_FN_CHANGE_VALUE = 0,
        GOVERNOR_FN_POLL = 1
    };
 
    VT_EXPORT Parameter();
    VT_EXPORT Parameter(const std::string& uid);
    VT_EXPORT Parameter(const Parameter& other);
    VT_EXPORT ~Parameter();
    VT_EXPORT Parameter& operator= (const Parameter& other);
    VT_EXPORT std::string getUid() const;
    VT_EXPORT std::string getName() const;
    VT_EXPORT std::string getModuleName() const;
    VT_EXPORT std::string getCategoryName() const;
    VT_EXPORT std::string getDescription() const;
    VT_EXPORT std::string getUnit() const;
    VT_EXPORT ParameterValue::ParameterType getType() const;
    VT_EXPORT ParameterAccessMode getAccessForConfig() const;
    VT_EXPORT ParameterAccessMode getAccessForApi() const;
    VT_EXPORT Parameter& setAccessForConfig(ParameterAccessMode mode);
    VT_EXPORT Parameter& setAccessForApi(ParameterAccessMode mode);
    VT_EXPORT ParameterInteractionHint getInteractionHint() const;
    VT_EXPORT Parameter& setInteractionHint(ParameterInteractionHint hint);
    VT_EXPORT bool getIsModified() const;
    VT_EXPORT bool getIsPolled() const;
    VT_EXPORT Parameter& setIsPolled(bool mod);
    VT_EXPORT Parameter& setIsModified(bool mod);
    VT_EXPORT GovernorType getGovernorType() const;
    VT_EXPORT std::string getGovernorString() const;
    VT_EXPORT Parameter& setGovernor(GovernorType govType, const std::string& govStr);
    VT_EXPORT Parameter& setGovernorPollString(const std::string& govStr);
    VT_EXPORT bool getInvokeGovernorOnInit() const;
    VT_EXPORT Parameter& setInvokeGovernorOnInit(bool invoke);
    VT_EXPORT std::string interpolateCommandLine(const ParameterValue& newVal, GovernorFunction fn = GOVERNOR_FN_CHANGE_VALUE);
    VT_EXPORT bool isTensor() const;
    VT_EXPORT bool isScalar() const;
    VT_EXPORT bool isCommand() const;
    VT_EXPORT unsigned int getTensorDimension() const;
    VT_EXPORT std::vector<unsigned int> getTensorShape() const;
    VT_EXPORT unsigned int getTensorNumElements() const;
    VT_EXPORT std::vector<double> getTensorData() const;
    VT_EXPORT std::vector<double> getTensorDefaultData() const;
    VT_EXPORT std::vector<double>& getTensorDataReference();
    VT_EXPORT std::vector<double>& getTensorDefaultDataReference();
    VT_EXPORT Parameter& setTensorData(const std::vector<double>& data);
    VT_EXPORT Parameter& setTensorDefaultData(const std::vector<double>& data);
    VT_EXPORT Parameter& setName(const std::string& name);
    VT_EXPORT Parameter& setModuleName(const std::string& n);
    VT_EXPORT Parameter& setCategoryName(const std::string& n);
    VT_EXPORT Parameter& setDescription(const std::string& d);
    VT_EXPORT Parameter& setUnit(const std::string& d);
    VT_EXPORT Parameter& setType(ParameterValue::ParameterType t);
    VT_EXPORT Parameter& setAsTensor(const std::vector<unsigned int>& shape);
    template<typename T>
    VT_EXPORT bool isValidNewValue(T t) const;
    VT_EXPORT bool ensureValidDefault();
    VT_EXPORT bool ensureValidCurrent();
    template<typename T>
    VT_EXPORT T enforceIncrement(T t);
    template<typename T>
    VT_EXPORT Parameter& setDefault(T t);
    template<typename T>
    VT_EXPORT Parameter& setRange(T mn, T mx);
    VT_EXPORT Parameter& unsetRange();
    template<typename T>
    VT_EXPORT Parameter& setIncrement(T t);
    template<typename T>
    VT_EXPORT Parameter& setCurrent(T t);
    VT_EXPORT Parameter& setCurrentFrom(const Parameter& from);
    VT_EXPORT Parameter& setCurrentFromDefault();
    template<typename T>
    VT_EXPORT Parameter& setOptions(const std::vector<T>& opts, const std::vector<std::string>& descriptions);
    template<typename T>
    VT_EXPORT Parameter& setOptions(std::initializer_list<T> opts, std::initializer_list<std::string> descriptions);
    template<typename T>
    VT_EXPORT std::vector<T> getOptions() const;
    VT_EXPORT std::vector<std::string> getOptionDescriptions() const;
    VT_EXPORT ParameterValue getCurrentParameterValue();
    template<typename T>
    VT_EXPORT T getCurrent() const;
    VT_EXPORT ParameterValue getDefaultParameterValue();
    template<typename T>
    VT_EXPORT T getDefault() const;
    template<typename T>
    VT_EXPORT T getMin() const;
    template<typename T>
    VT_EXPORT T getMax() const;
    template<typename T>
    VT_EXPORT T getIncrement() const;
    VT_EXPORT bool hasOptions() const;
    VT_EXPORT bool hasCurrent() const;
    VT_EXPORT bool hasDefault() const;
    VT_EXPORT bool hasRange() const;
    VT_EXPORT bool hasIncrement() const;
    VT_EXPORT double at(unsigned int x);
    VT_EXPORT double at(unsigned int y, unsigned int x);
    VT_EXPORT double at(unsigned int z, unsigned int y, unsigned int x);
    // Header-only OpenCV glue:
#ifdef CV_MAJOR_VERSION
 
    VT_EXPORT Parameter& setTensorFromCvSize(const cv::Size& cvSize) {
        if ((getType()!=ParameterValue::TYPE_UNDEFINED) && !isTensor()) {
            throw std::runtime_error("Parameter::setTensorFromCvSize(): refused to overwrite existing non-tensor type");
        }
        if (isTensor() && (getTensorNumElements()!=0)) {
            // Already a tensor; only allow replacement with Size if prior size was 2
            if (getTensorNumElements() != 2) throw std::runtime_error("Parameter::setTensorFromSize(): refused to overwrite tensor with size != 2");
        } else {
            // Newly defined as a Tensor, set as two-element vector
            setAsTensor({2});
        }
        std::vector<double> data = { (double) cvSize.width, (double) cvSize.height };
        setTensorData(data);
        setTensorDefaultData(data);
        return *this;
    }
    VT_EXPORT void setCvSizeFromTensor(cv::Size& cvSize) {
        if (getTensorNumElements() != 2) throw std::runtime_error("Parameter::setCvSizeFromTensor(): refused to export Tensor of size!=2 to cv::Size");
        cvSize = cv::Size((int) at(0), (int) at(1));
    }
    template<typename T>
    VT_EXPORT Parameter& setTensorFromCvMat(const cv::Mat_<T>& cvMat) {
        if ((getType()!=ParameterValue::TYPE_UNDEFINED) && !isTensor()) {
            throw std::runtime_error("Parameter::setTensorFromCvMat(): refused to overwrite existing non-tensor type");
        }
        std::vector<unsigned int> dims = { (unsigned int) cvMat.rows, (unsigned int) cvMat.cols };
        if (isTensor() && (getTensorNumElements()!=0)) {
            // Already a tensor; only allow replacement with Mat data of matching size
            if (getTensorNumElements() != dims[0]*dims[1]) throw std::runtime_error("Parameter::setTensorFromCvMat(): refused to overwrite tensor with cv::Mat of mismatching total size");
        } else {
            // Newly defined as a Tensor, copy the Cv shape
            setAsTensor(dims);
        }
        // Not the fastest way, but less hassle than coping with array casts
        std::vector<double> data;
        for (unsigned int r=0; r<(unsigned int) cvMat.rows; ++r)
            for (unsigned int c=0; c<(unsigned int) cvMat.cols; ++c) {
                data.push_back((double) cvMat(r, c));
            }
        setTensorData(data);
        setTensorDefaultData(data);
        return *this;
    }
    template<typename T>
    VT_EXPORT void setCvMatFromTensor(cv::Mat_<T>& cvMat) {
        if (getTensorDimension() != 2) {
            std::ostringstream ss;
            ss << "{";
            for (unsigned int i=0; i<getTensorDimension(); ++i) {
                ss << getTensorShape()[i] << ", ";
            }
            ss << "}";
            ss << " " << getUid() << " " << ((int)getType());
            throw std::runtime_error(std::string("Parameter::Pimpl::setCvMatFromTensor(): refused to export non-2D Tensor to cv::Mat, offending shape is: ")+ss.str());
        }
        auto& refData = getTensorDataReference();
        cv::Mat_<T>(getTensorShape()[0], getTensorShape()[1], (T*)&refData[0]).copyTo(cvMat);
    }
#endif // CV_MAJOR_VERSION
};
 
} // namespace param
} // namespace visiontransfer
 
#endif