ImFusion SDK version 2.41 introduces a large refactoring and overhaul of our object serialization framework revolving around the Configurable interface and Properties class. The entire component was moved to the ImFusionCore library and the corresponding includes are now found in ImFusion/Core/... instead of ImFusion/Base/.... The majority of changes was implemented while providing a deprecation layer to facilitate migration and enabling existing code to continue working. However, at a few places an API break was the only reasonable option. This page provides you with an overview of the changes and guidelines for the migration. See also the new Object Serialization component page.

Overview of Affected Classes and Interfaces

The following classes and interfaces of ImFusionLib are affected:

Configurable interface: moved to ImFusionCore and extended
Properties class: moved to ImFusionCore and extended
ParameterMixin class: deprecated, functionality has been merged into Configurable interface
Parameter class: moved to ImFusionCore, API chagnes
free functions in Base/Utils/PropertyUtils.h header: deprecated, replaced by member functions of Properties
PropertiesXML namespace: deprecated, replaced by PropertiesIO namespace
PropertyFile class: deprecated, replaced by PropertiesIO namespace

API-breaking Changes

Properties::Attribute Type

Previously, Properties::Attribute used to be a typedef for a std::pair<std::string, std::string>. It has been converted into a simple struct with named fields for key and value. As a result, you must no longer use attribute.first and attribute.second to access key/value but attribute.key and attribute.value.

Properties::paramMap() Member Function

The return type of the Properties::paramMap() member function has changed. It now returns a std::map<std::string, Properties::Param> containing all information about each stored parameter instead of a std::map<std::string, std::string> only providing the parameter value. Code using this function to access parameter values needs to be adjusted:

Properties p = ...;
for (const auto& pair : p.paramMap())
    LOG_INFO("value: " << pair.second);

becomes

Properties p = ...;
for (const auto& pair : p.paramMap())
    LOG_INFO("value: " << pair.second.value);

Note: A linker error such as unresolved external symbol ImFusion::Properties::setParam<struct ImFusion::PropertiesDetail::Param,0>(...) is most probably related to this API change.

Parameter::signalValueChanged Signature

Parameter::signalValueChanged no longer passes the sender as signal argument. If you require access to the sender in a callback function you should capture it in the corresponding lambda instead.

Configurable interface

The two virtual member functions Configurable::configure() and Configurable::configuration() are no longer pure virtual. Therefore, when implementing these functions in derived classes you should make sure to call be base class' version. However, this change should not break any existing code since the new base class implementation only takes care of serializing Parameters and existing classes implementing the Configurable interface do not rely on this unless they use the ParameterMixin interface, which itself has been deprecated, see ParameterMixin<T>.

Parameter<T> base class

The base class of Parameter<T> is no longer Configurable but ParameterBase.

Changes with Temporary Deprecation Layer

Moved Header Files

The following header files have changed their location:

ImFusion/Base/Configurable.h moved to ImFusion/Core/Configurable.h
ImFusion/Base/Properties.h moved to ImFusion/Core/Properties.h

Properties Class

There have been several deprecations inside the Properties class:

The addSubProperties() and insertSubProperties() member functions taking owning raw pointers have been replaced by versions taking a std::unique_ptr to model proper ownership semantics.
Internally, Properties now store a map of structs instead of a struct of maps. Therefore, functions such as Properties::defaultMap() or Properties::paramTypeMap() have been deprecated and replaced by Properties::paramMap() returning a map of structs encompassing all that information in one place. See als Properties::paramMap() Member Function
Several other member functions have been renamed and/or changed signature in order to homogenize the API. See the corresponding deprecation messages for detailed information how to follow-up on this.
The various typedefs such as Properties::ParamMap, Properties::ParamList have been deprecated without replacement. Write out the full type yourself or create your own alias if you need to.

ParameterMixin<T>

The ParameterMixin<T> interface providing functionality to automatically serialize Parameters has been moved into the base Configurable interface. Therefore, you should no longer inherit from this class but only from Configurable. This simplifies inheritance hierarchies and also avoids linker issues on certain platforms. The Configurable::registerParameter() function signature has been changed to take a pointer instead of a reference.

class MyAlgorithm : public ParameterMixin<Algorithm> {
public:
    Parameter<double> p_threshold = {"threshold", 42.0, *this};
}