SuggestSettingsParameters.h

Go to the documentation of this file.

/*******************************************************************************
 * This file is part of the Zivid API
 *
 * Copyright 2015-2024 (C) Zivid AS
 * All rights reserved.
 *
 * Zivid Software License, v1.0
 *
 * 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 Zivid AS nor the names of its contributors may be used
 * to endorse or promote products derived from this software without specific
 * prior written permission.
 *
 * 4. This software, with or without modification, must not be used with any
 * other 3D camera than from Zivid AS.
 *
 * 5. Any software provided in binary form under this license must not be
 * reverse engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY ZIVID AS "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL ZIVID AS 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.
 *
 * Contact: Zivid Customer Success Team <customersuccess@zivid.com>
 * Info:    http://www.zivid.com
 ******************************************************************************/
 
#pragma once
 
#include <array>
#include <chrono>
#include <cmath>
#include <ctime>
#include <iomanip>
#include <memory>
#include <set>
#include <sstream>
#include <string>
#include <tuple>
#include <utility>
#include <vector>
 
#include "Zivid/DataModel/Detail/Detail.h"
#include "Zivid/DataModel/NodeType.h"
#include "Zivid/DataModel/Traits.h"
#include "Zivid/Detail/CoreExport.h"
#include "Zivid/Detail/TypeTraits.h"
#include "Zivid/Range.h"
 
#ifdef _MSC_VER
#    pragma warning(push)
#    pragma warning(disable : 4251) // "X needs to have dll-interface to be used by clients of class Y."
#endif
 
namespace Zivid
{
    namespace CaptureAssistant
    {
 
 
        // NOLINTNEXTLINE(clang-analyzer-optin.performance.Padding)
        class ZIVID_CORE_EXPORT SuggestSettingsParameters
        {
        public:
            static constexpr DataModel::NodeType nodeType = DataModel::NodeType::group;
 
            static constexpr const char *path{ "" };
 
            static constexpr const char *name{ "SuggestSettingsParameters" };
 
            static constexpr const char *description{
                R"description(Used to specify a constraint on the total capture time for the settings suggested by the Capture Assistant, and
optionally specify the ambient light frequency.
)description"
            };
 
            static constexpr size_t version{ 1 };
 
#ifndef NO_DOC
            template<size_t>
            struct Version;
 
            using LatestVersion = Zivid::CaptureAssistant::SuggestSettingsParameters;
 
            // Short identifier. This value is not guaranteed to be universally unique
            // Todo(ZIVID-2808): Move this to internal DataModelExt header
            static constexpr std::array<uint8_t, 3> binaryId{ 's', 's', 'p' };
 
#endif
 
 
            // NOLINTNEXTLINE(clang-analyzer-optin.performance.Padding)
            class ZIVID_CORE_EXPORT AmbientLightFrequency
            {
            public:
                static constexpr DataModel::NodeType nodeType = DataModel::NodeType::leafValue;
 
                static constexpr const char *path{ "AmbientLightFrequency" };
 
                static constexpr const char *name{ "AmbientLightFrequency" };
 
                static constexpr const char *description{
                    R"description(Adapt suggested settings to the ambient light frequency. This can be used to avoid artifacts in the point
cloud due to AC powered ambient light being mixed in with the camera's projector light.
 
Select your power grid frequency. 60 Hz is typically used in Japan, Americas, Taiwan, South Korea, and the
Philippines. 50 Hz is the normal in rest of the world. If ambient light is unproblematic, turn off for
optimal performance.
)description"
                };
 
                enum class ValueType
                {
                    none,
                    hz50,
                    hz60
                };
                static const AmbientLightFrequency none; 
                static const AmbientLightFrequency hz50; 
                static const AmbientLightFrequency hz60; 
 
                static std::set<ValueType> validValues()
                {
                    return { ValueType::none, ValueType::hz50, ValueType::hz60 };
                }
 
                AmbientLightFrequency() = default;
 
                explicit constexpr AmbientLightFrequency(ValueType value)
                    : m_value{ verifyValue(value) }
                {}
 
                ValueType value() const;
 
                std::string toString() const;
 
                friend std::ostream &operator<<(std::ostream &stream, const AmbientLightFrequency::ValueType &value)
                {
                    return stream << AmbientLightFrequency{ value }.toString();
                }
 
                bool operator==(const AmbientLightFrequency &other) const
                {
                    return m_value == other.m_value;
                }
 
                bool operator!=(const AmbientLightFrequency &other) const
                {
                    return m_value != other.m_value;
                }
 
                friend std::ostream &operator<<(std::ostream &stream, const AmbientLightFrequency &value)
                {
                    return stream << value.toString();
                }
 
            private:
                void setFromString(const std::string &value);
 
                constexpr ValueType static verifyValue(const ValueType &value)
                {
                    return value == ValueType::none || value == ValueType::hz50 || value == ValueType::hz60
                               ? value
                               : throw std::invalid_argument{
                                     "Invalid value: AmbientLightFrequency{ "
                                     + std::to_string(static_cast<std::underlying_type<ValueType>::type>(value)) + " }"
                                 };
                }
 
                ValueType m_value{ ValueType::none };
 
                friend struct DataModel::Detail::Befriend<AmbientLightFrequency>;
            };
 
 
            // NOLINTNEXTLINE(clang-analyzer-optin.performance.Padding)
            class ZIVID_CORE_EXPORT MaxCaptureTime
            {
            public:
                static constexpr DataModel::NodeType nodeType = DataModel::NodeType::leafValue;
 
                static constexpr const char *path{ "MaxCaptureTime" };
 
                static constexpr const char *name{ "MaxCaptureTime" };
 
                static constexpr const char *description{
                    R"description(Capture time budget. This budget assumes a high-end computer meeting Zivid's recommendations. The actual
capture time may differ, based on your computer's performance and (for Zivid 2 and 2+) your network connection
speed.
)description"
                };
 
                using ValueType = std::chrono::milliseconds;
 
                static constexpr Range<std::chrono::milliseconds> validRange()
                {
                    return { std::chrono::milliseconds{ 200 }, std::chrono::milliseconds{ 10000 } };
                }
 
                MaxCaptureTime() = default;
 
                explicit constexpr MaxCaptureTime(std::chrono::milliseconds value)
                    : m_value{ verifyValue(value) }
                {}
 
                std::chrono::milliseconds value() const;
 
                std::string toString() const;
 
                bool operator==(const MaxCaptureTime &other) const
                {
                    return m_value == other.m_value;
                }
 
                bool operator!=(const MaxCaptureTime &other) const
                {
                    return m_value != other.m_value;
                }
 
                bool operator<(const MaxCaptureTime &other) const
                {
                    return m_value < other.m_value;
                }
 
                bool operator>(const MaxCaptureTime &other) const
                {
                    return m_value > other.m_value;
                }
 
                bool operator<=(const MaxCaptureTime &other) const
                {
                    return m_value <= other.m_value;
                }
 
                bool operator>=(const MaxCaptureTime &other) const
                {
                    return m_value >= other.m_value;
                }
 
                friend std::ostream &operator<<(std::ostream &stream, const MaxCaptureTime &value)
                {
                    return stream << value.toString();
                }
 
            private:
                void setFromString(const std::string &value);
 
                constexpr ValueType static verifyValue(const ValueType &value)
                {
                    return validRange().isInRange(value)
                               ? value
                               : throw std::out_of_range{ "MaxCaptureTime{ " + std::to_string(value.count())
                                                          + " } is not in range ["
                                                          + std::to_string(validRange().min().count()) + ", "
                                                          + std::to_string(validRange().max().count()) + "]" };
                }
 
                std::chrono::milliseconds m_value{ 1200 };
 
                friend struct DataModel::Detail::Befriend<MaxCaptureTime>;
            };
 
            using Descendants =
                std::tuple<SuggestSettingsParameters::AmbientLightFrequency, SuggestSettingsParameters::MaxCaptureTime>;
 
            SuggestSettingsParameters();
 
            explicit SuggestSettingsParameters(const std::string &fileName);
 
#ifndef NO_DOC
            template<
                typename... Args,
                typename std::enable_if<sizeof...(Args) >= 1, int>::type = 0,
                typename std::enable_if<
                    Zivid::Detail::TypeTraits::AllArgsAreInTuple<Descendants, typename std::decay<Args>::type...>::
                        value,
                    int>::type = 0>
#else
            template<typename... Args>
#endif
            explicit SuggestSettingsParameters(Args &&...args)
            {
                using namespace Zivid::Detail::TypeTraits;
 
                static_assert(
                    AllArgsDecayedAreUnique<Args...>::value,
                    "Found duplicate types among the arguments passed to SuggestSettingsParameters(...). "
                    "Types should be listed at most once.");
 
                set(std::forward<Args>(args)...);
            }
 
#ifndef NO_DOC
            template<typename... Args, typename std::enable_if<sizeof...(Args) >= 2, int>::type = 0>
#else
            template<typename... Args>
#endif
            void set(Args &&...args)
            {
                using namespace Zivid::Detail::TypeTraits;
 
                using AllArgsAreDescendantNodes = AllArgsAreInTuple<Descendants, typename std::decay<Args>::type...>;
                static_assert(
                    AllArgsAreDescendantNodes::value, "All arguments passed to set(...) must be descendant nodes.");
 
                static_assert(
                    AllArgsDecayedAreUnique<Args...>::value,
                    "Found duplicate types among the arguments passed to set(...). "
                    "Types should be listed at most once.");
 
                Zivid::DataModel::Detail::invokeSetWithEachArgument(*this, std::forward<Args>(args)...);
            }
 
#ifndef NO_DOC
            template<typename... Args, typename std::enable_if<sizeof...(Args) >= 1, int>::type = 0>
#else
            template<typename... Args>
#endif
            SuggestSettingsParameters copyWith(Args &&...args) const
            {
                using namespace Zivid::Detail::TypeTraits;
 
                using AllArgsAreDescendantNodes = AllArgsAreInTuple<Descendants, typename std::decay<Args>::type...>;
                static_assert(
                    AllArgsAreDescendantNodes::value,
                    "All arguments passed to copyWith(...) must be descendant nodes.");
 
                static_assert(
                    AllArgsDecayedAreUnique<Args...>::value,
                    "Found duplicate types among the arguments passed to copyWith(...). "
                    "Types should be listed at most once.");
 
                auto copy{ *this };
                copy.set(std::forward<Args>(args)...);
                return copy;
            }
 
            const AmbientLightFrequency &ambientLightFrequency() const
            {
                return m_ambientLightFrequency;
            }
 
            AmbientLightFrequency &ambientLightFrequency()
            {
                return m_ambientLightFrequency;
            }
 
            SuggestSettingsParameters &set(const AmbientLightFrequency &value)
            {
                m_ambientLightFrequency = value;
                return *this;
            }
 
            const MaxCaptureTime &maxCaptureTime() const
            {
                return m_maxCaptureTime;
            }
 
            MaxCaptureTime &maxCaptureTime()
            {
                return m_maxCaptureTime;
            }
 
            SuggestSettingsParameters &set(const MaxCaptureTime &value)
            {
                m_maxCaptureTime = value;
                return *this;
            }
 
            template<
                typename T,
                typename std::enable_if<std::is_same<T, SuggestSettingsParameters::AmbientLightFrequency>::value, int>::
                    type = 0>
            const SuggestSettingsParameters::AmbientLightFrequency &get() const
            {
                return m_ambientLightFrequency;
            }
 
            template<
                typename T,
                typename std::enable_if<std::is_same<T, SuggestSettingsParameters::MaxCaptureTime>::value, int>::type =
                    0>
            const SuggestSettingsParameters::MaxCaptureTime &get() const
            {
                return m_maxCaptureTime;
            }
 
            template<size_t i, typename std::enable_if<i == 0, int>::type = 0>
            const SuggestSettingsParameters::AmbientLightFrequency &get() const
            {
                return m_ambientLightFrequency;
            }
 
            template<size_t i, typename std::enable_if<i == 1, int>::type = 0>
            const SuggestSettingsParameters::MaxCaptureTime &get() const
            {
                return m_maxCaptureTime;
            }
 
            template<typename F>
            void forEach(const F &f) const
            {
                f(m_ambientLightFrequency);
                f(m_maxCaptureTime);
            }
 
            template<typename F>
            void forEach(const F &f)
            {
                f(m_ambientLightFrequency);
                f(m_maxCaptureTime);
            }
 
            bool operator==(const SuggestSettingsParameters &other) const;
 
            bool operator!=(const SuggestSettingsParameters &other) const;
 
            std::string toString() const;
 
            friend std::ostream &operator<<(std::ostream &stream, const SuggestSettingsParameters &value)
            {
                return stream << value.toString();
            }
 
            void save(const std::string &fileName) const;
 
            void load(const std::string &fileName);
 
        private:
            void setFromString(const std::string &value);
 
            void setFromString(const std::string &fullPath, const std::string &value);
 
            std::string getString(const std::string &fullPath) const;
 
            AmbientLightFrequency m_ambientLightFrequency;
            MaxCaptureTime m_maxCaptureTime;
 
            friend struct DataModel::Detail::Befriend<SuggestSettingsParameters>;
        };
 
#ifndef NO_DOC
        namespace Detail
        {
            ZIVID_CORE_EXPORT void save(const SuggestSettingsParameters &dataModel, std::ostream &ostream);
            ZIVID_CORE_EXPORT void load(SuggestSettingsParameters &dataModel, std::istream &istream);
        } // namespace Detail
#endif
 
#ifndef NO_DOC
        template<>
        struct SuggestSettingsParameters::Version<1>
        {
            using Type = SuggestSettingsParameters;
        };
#endif
 
    } // namespace CaptureAssistant
} // namespace Zivid
 
#ifdef _MSC_VER
#    pragma warning(pop)
#endif
 
#ifndef NO_DOC
#    if !(defined(_MSC_VER) && (_MSC_VER <= 1900))
namespace std // NOLINT
{
 
    template<>
    struct tuple_size<Zivid::CaptureAssistant::SuggestSettingsParameters> : integral_constant<size_t, 2>
    {};
 
    template<size_t i>
    struct tuple_element<i, Zivid::CaptureAssistant::SuggestSettingsParameters>
    {
        static_assert(
            i < tuple_size<Zivid::CaptureAssistant::SuggestSettingsParameters>::value,
            "Index must be less than 2");
 
        using type // NOLINT
            = decltype(declval<Zivid::CaptureAssistant::SuggestSettingsParameters>().get<i>());
    };
 
} // namespace std
#    endif
#endif
 
// If we have access to the DataModel library, automatically include internal DataModel
// header. This header is necessary for serialization and deserialization.
#if defined(__has_include) && !defined(NO_DOC)
#    if __has_include(                                                                                                 \
        "Zivid/CaptureAssistant/SuggestSettingsParametersInternal.h")                                                  \
        && __has_include("Zivid/DataModelNodeMetaData.h")
#        include "Zivid/CaptureAssistant/SuggestSettingsParametersInternal.h"
#    endif
#endif