ARON Specifications

We distinguish between:

• type specification vs. data information
• data transfer object (in the following called "ARON DTO") vs. its corresponding C++ wrapper (in the following called "ARON object"). The DTO specification is done in ice so that every ARON object can be transferred via ice.

ARON Type specification

An ARON type specification defines the static type for an ARON data DTO or an ARON data object. It does not contain any data (e.g. an ARON type list only knows the accepted type, not the list members). Since ARON supports maybe types (raw ptr, smart ptr, optional), every ARON type DTO contains a special member. It can only consist of the following types and information (ARONVariant means any Type):

Object { // dto called armarx::aron::type::dto::AronObject
    string name;
    AronVariant extends;
    map<string, AronVariant> memberTypes;
}
Dict { // dto called armarx::aron::type::dto::Dict
    AronVariant acceptedType;
}
List { // dto called armarx::aron::type::dto::List
     AronVariant acceptedType;
}
Pair { // ...
     AronVariant acceptedType1;
     AronVariant acceptedType2;
}
Tuple {
     vector<AronVariant> acceptedTypes;
}
IntEnum {
     string name;
     map<string, int> acceptedValues;
}
NDArray {
     int ndim;
     type type; // in [uint8, int8, uint16, int16, uint32, int32, float32, float64]
}
Matrix {
     int rows, cols;
     type type; // in [int16, int32, int64, float32, float64]
}
Quaternion {
     type type; // in [float32, float64]
} 
Position {
}
Orientation {
} 
Pose {
} 
Image {
    pixelType type; // in [rgb24, depth32]
}     
PointCloud {
    voxelType type; // in [PointXYZ, PointXYZI, PointXYZL, PointXYZRGB, PointXYZRGBA, PointXYZRGBL, PointXYZHSV]
}
Int { // dto called armarx::aron::type::dto::AronInt
}
Long { // dto called armarx::aron::type::dto::AronLong
}
Float { // dto called armarx::aron::type::dto::AronFloat
}
Double { // dto called armarx::aron::type::dto::AronDouble
}
String { // dto called armarx::aron::type::dto::AronString
}
Bool { // dto called armarx::aron::type::dto::AronBool
}
Time { // dto called armarx::aron::type::dto::AronTime
}

ARON Data specification

ARON data objects and ARON data DTOs are similar structured to type objects and type DTOs. However, there are fewer classes for data objects and data DTOs. ARON data is completely decoupled from the static types and contains the data members (e.g. an aron data list only contains the list members (as ARONVariants) and not the accepted type):

Dict { // dto called armarx::aron::data::dto::Dict
    map<string, AronVariant> members;
}
List { // dto called armarx::aron::data::dto::List
     vector<AronVariant> elements;
}
NDArray { // ...
     vector<int> shape;
     string type;
     vector<byte> data;
}
Int { // dto called armarx::aron::data::dto::AronInt
     int value;
}
Long { // dto called armarx::aron::data::dto::AronLong
     long value;
}
Float { // dto called armarx::aron::data::dto::AronFloat
     float value;
}
Double { // dto called armarx::aron::data::dto::AronDouble
     double value;
}
String { // dto called armarx::aron::data::dto::AronString
     string value;
}
Bool { // dto called armarx::aron::data::dto::AronBool
     bool value;
}

Note

Note that every ARON data object or DTO can be nullptr! The reason is that if the type supports maybe types and a member is, for example, optional, the data must support maybetype as well. If a generated ARON class has an optional member, this member will be translated into a NULL ARON object and DTO.

Connection of ARON data and ARON type

ARON data contains fewer classes than ARON type. Because ARON data objects and DTOs do not check the type of the members (they can be any aron data (ARONVariant)), we can only validate an aron data object or DTO if we have the type information. The following mapping describes, how data and types correspond.

ARON Type	ARON Data
Object	Dict
Dict	Dict
List	List
Pair	List
Tuple	List
NDArray	NDArray
Matrix	NDArray
Quaternion	NDArray
Position	NDArray
Orientation	NDArray
Pose	NDArray
Image	NDArray
PointCloud	NDArray
IntEnum	Int
Int	Int
Long	Long
Float	Float
Double	Double
String	String
Bool	Bool
Time	Long

If no type object or DTO is available, we can at least derive some information from the data object (e.g. "it is a data dict, so the type cant be list").

To differ between data and type makes it easier to work with these Variants. In most cases, the type information is not relevant. Then you only have to check for the data type.

ARON Data and Type Objects

As already mentioned, we implemented wrapper classes around the DTO. These classes offer convenience methods and conversions and make lots things easier when working directly with ARON. These classes can be found at aron/core/{data,type}/variant/Variant.h.

The ARON objects have more or less the same structure as the DTOs (see above). Everything is stored as a std::shared_ptr (e.g. members, elements, acceptedTypes, ...). If you want to implement a method which takes any ARON data object as input, you can use the base class of every ARON data object:

void myFancyMethod(const armarx::aron::data::VariantPtr& variant);

If you want to check, what a variant really is, you can use the descriptor of the object:

armarx::aron::data::VariantPtr variant;  // <-- the variant
auto desc = variant->getDescriptor();
switch(desc)
{
    case armarx::aron::data::Descriptor::eDict: ...
    case armarx::aron::data::Descriptor::eList: ...
    ...
}

If you have a DTO, you do not know the exact type, but you want to have a ARON object you can make use of the static construction methods:

armarx::aron::data::dto::GenericData dto; // <-- the DTO variant
auto aron = armarx::aron::data::Variant::FromAronDTO(dto);

If you know the type, you can use the constructor the specific ARON object.

Example to Create an ARON Data Dict from Scratch

Goal: Have an ARON dict with a list as member "the_list" and some values in it. Then echo the members and their descriptor as a string.

using namespace armarx;
 
// setup aron object
auto dict = std::make_shared<aron::data::Dict>();
{
    auto list = std::make_shared<aron::data::List>();
    for (unsigned int i = 0; i < 10; ++i)
    {
        list->addElement(std::make_shared<aron::data::Int>(i));
    }
    dict->addElement("the_list", list);
}
 
// echo
auto listVariant = dict->getElement("the_list"); // will return a aron::data::VariantPtr
auto list = aron::data::List::DynamicCastAndCheck(listVariant); // cast and check whether the cast was successful
for (const auto& intVar : list->getElements())
{
    auto i = aron::data::Int::DynamicCastAndCheck(intVar);
    std::cout << "The value is: " << i->getValue() << std::endl;
    std::cout << "The descriptor is: " << aron::data::defaultconversion::string::Descriptor2String.at(i->getDescriptor()) << std::endl;
}

Please note that we might add more methods or make the current ones more flexible (e.g. such as nlohmann::json).

ARON Optionals

ARON does support optional types which allows you to use your object as an std::optional in C++. We currently support the following optional types: floats, strings, dictionaries, optional elements inside a dictionary, lists, optional elements inside a list, matrices, poses, quaternions, pointclouds, rgb images, rgbd images

Not supported are: IntEnums

You can define your type as an optional inside your .xml:

<?xml version="1.0" encoding="UTF-8" ?>
<AronTypeDefinition>  
     <AronIncludes>
          <Include include="path_to_other_xml_file_you_want_to_include" /> 
          ... 
     </AronIncludes>
     <GenerateTypes>
          <ObjectChild key='some_float'>
               <float32 optional="true"/>
          </ObjectChild>
        ...
     </GenerateTypes>
</AronTypeDefinition>

ARON Default Values

ARON supports default values which will be used if no value is assigned.

We currently support default values for the following types with the following values:

ARON Type	Supported Default Value
NDArray	Identity, Ones, Zeroes
Matrix	Identity, Ones, Zeroes
Quaternion	Identity, Ones, Zeroes
Image	empty
PointCloud	Ones, Zeroes
IntEnum	IntEnum of your choice
Int	Int of your choice
Long	Long of your choice
Float	Float of your choice
Double	Double of your choice
String	String of your choice
Bool	Bool of your choice

Definition of default value:

Default Value	String representation
Identity	"identity"
Ones	"1"
Zeroes	"0"
empty	"empty"

To define a default value in your xml file you can add the default tag to your definition. You can either choose to set the default value directly (e.g. by setting default="0" in a matrix to get a matrix initialized with all zeroes), or simply set default as a tag in your definition, which will take the deafult default value (e.g. identity for matrices). It is highly discouraged to only set the defaulttag without an explicit value.

If you define a default value for a primitive type like float or string, you have to define it as a string, e.g. default="42" for defining a float default value of 42.0.

See the following example for how to define a default value:

<?xml version="1.0" encoding="UTF-8" ?>
<AronTypeDefinition>
    <Include>
        <SystemInclude package="" path="Eigen/Core" />
    </Include>
 
    <GenerateTypes>
        <Object name="armarx::DefaultTestElement">
            <ObjectChild key="val">
                <float32 />
            </ObjectChild>
        </Object>
        
        <Object name='armarx::DefaultTest'>
 
            <objectchild key='the_int'>
                <int32 default="45"/>
            </ObjectChild>
            <objectchild key='the_long'>
                <int64 default="44"/>
            </ObjectChild>
            <objectchild key='the_float'>
                <float32 default="43"/>
            </ObjectChild>
            <objectchild key='the_double'>
                <float64 default="42"/>
            </ObjectChild>
            <objectchild key='the_string'>
                <string default="lalala" />
            </ObjectChild>
            <objectchild key='the_bool'>
                <bool default="false"/>
            </ObjectChild>
 
            <ObjectChild key='some_eigen_matrix'>
                <Matrix rows="25" cols="10" type="int64" default="identity"/>
            </ObjectChild>
 
            <ObjectChild key='the_float_quaternion'>
                <Quaternion type="float32" default=""/>
            </ObjectChild>
 
            <ObjectChild key='the_xyzrgb_pcl_pointcloud'>
                <PointCloud type="PointXYZRGB" default="0"/>
            </ObjectChild>
 
            <ObjectChild key='the_default_rgb24_image'>
                <Image type="rgb24" default="empty"/>
            </ObjectChild>
 
            <ObjectChild key='the_default_depth32_image'>
                <Image type="depth32" default=""/>
            </ObjectChild>
 
        </Object>
    </GenerateTypes>
</AronTypeDefinition>