parameter.h

/*******************************************************************************
 * Copyright (c) 2023 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/conversionhelpers.h>
 
namespace visiontransfer {
namespace param {
 
class VT_EXPORT Parameter {
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
    };
 
    Parameter(): uid("undefined"), name("undefined"), governorType(GOVERNOR_NONE), invokeGovernorOnInit(false), accessForConfig(ACCESS_NONE), accessForApi(ACCESS_NONE), interactionHint(INTERACTION_ACTIVE), isModified(false) {}
    Parameter(const std::string& uid);
    std::string getUid() const { return uid; }
    std::string getName() const { return name; }
    std::string getModuleName() const { return modulename; }
    std::string getCategoryName() const { return categoryname; }
    std::string getDescription() const { return description; }
    std::string getUnit() const { return unit; }
    inline ParameterValue::ParameterType getType() const { return type; }
    ParameterAccessMode getAccessForConfig() const { return accessForConfig; }
    ParameterAccessMode getAccessForApi() const { return accessForApi; }
    inline Parameter& setAccessForConfig(ParameterAccessMode mode) { accessForConfig = mode; return *this; }
    inline Parameter& setAccessForApi(ParameterAccessMode mode) { accessForApi = mode; return *this; }
    ParameterInteractionHint getInteractionHint() const { return interactionHint; }
    inline Parameter& setInteractionHint(ParameterInteractionHint hint) { interactionHint = hint; return *this; }
    bool getIsModified() const { return isModified; }
    inline Parameter& setIsModified(bool mod) { isModified = isCommand() ? false : mod; return *this; }
    GovernorType getGovernorType() const { return governorType; }
    std::string getGovernorString() const { return governorString; }
    inline Parameter& setGovernor(GovernorType govType, const std::string& govStr) { governorType = govType; governorString = govStr; return *this; }
    bool getInvokeGovernorOnInit() const { return invokeGovernorOnInit; }
    Parameter& setInvokeGovernorOnInit(bool invoke) { invokeGovernorOnInit = invoke; return *this; }
    std::string interpolateCommandLine(const ParameterValue& newVal);
    bool isTensor() const { return type == ParameterValue::ParameterType::TYPE_TENSOR; }
    bool isScalar() const { return type != ParameterValue::ParameterType::TYPE_TENSOR; }
    bool isCommand() const { return currentValue.isCommand(); }
    unsigned int getTensorDimension() const {
        return currentValue.isDefined() ? currentValue.getTensorDimension() : defaultValue.getTensorDimension(); }
    std::vector<unsigned int> getTensorShape() const {
        return currentValue.isDefined() ? currentValue.getTensorShape() : defaultValue.getTensorShape();}
    unsigned int getTensorNumElements() const {
        return currentValue.isDefined() ? currentValue.getTensorNumElements() : defaultValue.getTensorNumElements();}
    std::vector<double> getTensorData() const;
    std::vector<double> getTensorDefaultData() const;
    std::vector<double>& getTensorDataReference();
    std::vector<double>& getTensorDefaultDataReference();
    inline Parameter& setTensorData(const std::vector<double>& data) {
        currentValue.setTensorData(data);
        return *this;
    }
    inline Parameter& setTensorDefaultData(const std::vector<double>& data) {
        defaultValue.setTensorData(data);
        return *this;
    }
#ifdef CV_MAJOR_VERSION
 
    inline Parameter& setTensorFromCvSize(const cv::Size& cvSize) {
        if (currentValue.isDefined() && !(currentValue.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 };
        currentValue.setTensorData(data);
        defaultValue.setTensorData(data);
        return *this;
    }
    inline void setCvSizeFromTensor(cv::Size& cvSize) {
        if (getTensorNumElements() != 2) throw std::runtime_error("Parameter::setCvSizeFromTensor(): refused to export Tensor of size!=2 to cv::Size");
        auto val = getCurrentParameterValue();
        cvSize = cv::Size((int) val.tensorElementAt(0), (int) val.tensorElementAt(1));
    }
    template<typename T>
    inline Parameter& setTensorFromCvMat(const cv::Mat_<T>& cvMat) {
        if (currentValue.isDefined() && !(currentValue.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));
            }
        currentValue.setTensorData(data);
        defaultValue.setTensorData(data);
        return *this;
    }
    template<typename T>
    inline 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::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
 
    inline Parameter& setName(const std::string& name) { this->name = name;         return *this; }
    inline Parameter& setModuleName(const std::string& n) { this->modulename = n; return *this; }
    inline Parameter& setCategoryName(const std::string& n) { this->categoryname = n; return *this; }
    inline Parameter& setDescription(const std::string& d) { this->description = d; return *this; }
    inline Parameter& setUnit(const std::string& d) { this->unit = d; return *this; }
    inline Parameter& setType(ParameterValue::ParameterType t) {
        this->type = t;
        // min, max, increment, options left undefined here
        if (t==ParameterValue::ParameterType::TYPE_COMMAND) {
            // Commands no not have to have an initialized prior value
            defaultValue.setType(this->type);
            currentValue.setType(this->type);
            defaultValue.setValue("");
            currentValue.setValue("");
        }
        return *this;
    }
    inline Parameter& setAsTensor(const std::vector<unsigned int>& shape) {
        setType(ParameterValue::TYPE_TENSOR);
        defaultValue.setTensorShape(shape);
        currentValue.setTensorShape(shape);
        return *this;
    }
    template<typename T>
    bool isValidNewValue(T t) const {
        if (validOptions.size()) {
            // enum-style list of options
            for (auto& o: validOptions) {
                if (o.getValue<T>() == t) return true;
            }
            return false;
        } else {
            if ((type==ParameterValue::ParameterType::TYPE_INT) || (type==ParameterValue::ParameterType::TYPE_DOUBLE)) {
                if (minValue.isUndefined() || maxValue.isUndefined()) {
                    // unlimited range numerical
                    return true;
                } else {
                    // limited range numerical
                    double val = internal::ConversionHelpers::anyToDouble(t);
                    return val>=minValue.getValue<double>() && val<=maxValue.getValue<double>();
                }
            } else {
                // non-numerical, cannot range-restrict
                return true;
            }
        }
    }
    bool ensureValidDefault();
    bool ensureValidCurrent();
    template<typename T> T enforceIncrement(T t);
    template<typename T>
    Parameter& setDefault(T t) {
        defaultValue.setType(getType());
        defaultValue.setValue(enforceIncrement(t));
        ensureValidDefault();
        return *this;
    }
    template<typename T>
    Parameter& setRange(T mn, T mx) {
        minValue.setType(type);
        maxValue.setType(type);
        minValue.setValue(mn);
        maxValue.setValue(mx);
        ensureValidDefault();
        ensureValidCurrent();
        return *this;
    }
    Parameter& unsetRange() {
        minValue.setType(ParameterValue::ParameterType::TYPE_UNDEFINED);
        maxValue.setType(ParameterValue::ParameterType::TYPE_UNDEFINED);
        ensureValidDefault();
        ensureValidCurrent();
        return *this;
    }
    template<typename T>
    Parameter& setIncrement(T t) {
        incrementValue.setType(type);
        incrementValue.setValue(t);
        ensureValidDefault();
        ensureValidCurrent();
        return *this;
    }
    template<typename T>
    Parameter& setCurrent(T t) {
        currentValue.setType(getType());
        currentValue.setValue(enforceIncrement(t));
        ensureValidCurrent();
        return *this;
    }
    Parameter& setCurrentFrom(const Parameter& from);
    Parameter& setCurrentFromDefault();
    template<typename T>
    Parameter& setOptions(const std::vector<T>& opts, const std::vector<std::string>& descriptions) {
        if (opts.size() != descriptions.size()) throw std::runtime_error("Option list and description list of mismatched size");
        validOptions.clear();
        validOptionDescriptions.clear();
        for (unsigned int i=0; i<opts.size(); ++i) {
            validOptions.push_back(ParameterValue().setType(type).setValue(opts[i]));
            validOptionDescriptions.push_back(descriptions[i]);
        }
        ensureValidDefault();
        ensureValidCurrent();
        return *this;
    }
    template<typename T>
    Parameter& setOptions(std::initializer_list<T> opts, std::initializer_list<std::string> descriptions) {
        std::vector<T> tmpOpts(opts);
        std::vector<std::string> tmpComm(descriptions);
        return setOptions(tmpOpts, tmpComm);
    }
    template<typename T>
    std::vector<T> getOptions() const {
        std::vector<T> vec;
        for (auto& o: validOptions) {
            vec.push_back(o.getValue<T>());
        }
        return vec;
    }
    std::vector<std::string> getOptionDescriptions() const {
        return validOptionDescriptions;
    }
    inline ParameterValue getCurrentParameterValue() {
        if (hasCurrent()) {
            return currentValue;
        } else {
            if (hasDefault()) {
                return defaultValue;
            } else {
                throw std::runtime_error(std::string("Tried getCurrent(), but no value set and no default defined for ") + getUid());
            }
        }
    }
    template<typename T>
    T getCurrent() const {
        if (hasCurrent()) {
            return currentValue.getValue<T>();
        } else {
            if (hasDefault()) {
                return defaultValue.getValue<T>();
            } else {
                throw std::runtime_error(std::string("Tried getCurrent(), but no value set and no default defined for ") + getUid());
            }
        }
    }
    inline ParameterValue getDefaultParameterValue() {
        return defaultValue;
    }
    template<typename T>
    T getDefault() const {
        return defaultValue.getValue<T>();
    }
    template<typename T>
    T getMin() const {
        return minValue.isDefined() ? (minValue.getValue<T>()) : (std::numeric_limits<T>::lowest());
    }
    template<typename T>
    T getMax() const {
        return maxValue.isDefined() ? (maxValue.getValue<T>()) : ((std::numeric_limits<T>::max)());
    }
    template<typename T>
    T getIncrement() const {
        return incrementValue.isDefined() ? (incrementValue.getValue<T>()) : internal::ConversionHelpers::toStringIfStringExpected<T>(1);
    }
    bool hasOptions() const {
        return validOptions.size() > 0;
    }
    bool hasCurrent() const {
        if (type == ParameterValue::ParameterType::TYPE_TENSOR) {
            // For tensors: the data array must also have been set first
            return currentValue.isDefined() && (currentValue.getTensorCurrentDataSize() == currentValue.getTensorNumElements());
        } else {
            return currentValue.isDefined();
        }
    }
    bool hasDefault() const {
        if (defaultValue.isTensor()) {
            // For tensors: the data array must also have been set first
            return defaultValue.isDefined() && (defaultValue.getTensorCurrentDataSize() == defaultValue.getTensorNumElements());
        } else {
            return defaultValue.isDefined();
        }
    }
    bool hasRange() const {
        return maxValue.isDefined();
    }
    bool hasIncrement() const {
        return incrementValue.isDefined();
    }
    double at(unsigned int x) { return getCurrentParameterValue().tensorElementAt(x); }
    double at(unsigned int y, unsigned int x) { return getCurrentParameterValue().tensorElementAt(y, x); }
    double at(unsigned int z, unsigned int y, unsigned int x) { return getCurrentParameterValue().tensorElementAt(z, y, x); }
 
 
private:
    std::string uid;
    std::string name;
    std::string modulename;    // Broad association to a module (e.g. "settings", "cam0", "cam1", etc.)
    std::string categoryname;  // Free-form, module specific, category grouping (e.g. Aravis feature categories)
    std::string description;
    std::string unit;
    ParameterValue::ParameterType type;
 
    ParameterValue defaultValue;
    ParameterValue currentValue;
    ParameterValue minValue;       // minValue.isUndefined() until range has been set
    ParameterValue maxValue;
    ParameterValue incrementValue; // incrementValue.isUndefined() until increment set
    std::vector<ParameterValue> validOptions;
    std::vector<std::string> validOptionDescriptions;
 
    // The following fields are used in nvparamd (the master) and not set elsewhere
    GovernorType governorType;
    std::string governorString; // D-Bus address or shell command line, respectively
    // 'oninit' action - ignore, or the same as on a change.
    // This is only used in the parameter daemon, this variable need not be relayed.
    bool invokeGovernorOnInit;
 
    ParameterAccessMode accessForConfig;
    ParameterAccessMode accessForApi;
 
    ParameterInteractionHint interactionHint;
    bool isModified;
};
 
} // namespace param
} // namespace visiontransfer
 
#endif