Support matrix parameter value in parameter value JSON schema defintion

[yrh012]

In order to support matrices, we should also update the parameter value definition to also accept an array of items where items can also be array or primitives (string, bool, int, double)

so I propose changing the JSON schema of the parameter value definition to:

"parameter_value": {
  "type": [
    "null",
    "boolean",
    "integer",
    "number",
    "string",
    "array"
  ],
  "items": {
    "oneOf": [
      { "type": ["boolean", "integer", "number", "string"] },
      {
        "type": "array",
        "items": { "type": ["boolean", "integer", "number", "string"] }
      }
    ]
  }
}

fyi @domire8 @eeberhard

[eeberhard]

Hmm, thanks for raising the suggestion but "Support matrices by allowing an array of arrays" is not quite as straightforward as it appears. Let me illustrate some problems:

Does not validate common length

If we use the term matrix, we really should be referring to a rank 2 tensor, which is to say all rows should be equal length (or equivalently all columns must be complete and contiguous). With json schema, there is no good way of saying that all array items must be the same arbitrary length. We can only define a fixed min/max or length that each item should validate with. So, something like the following would be valid YAML but not a valid matrix:

[[ 1, 2, 3 ]
 [ 4, 5 ]
 [ 6, 7, 8 ]]

Does not validate common type

As you have proposed it, each "row" could be a different type, which seems undesired

[[ 1, 2, 3 ]
 [ true, false ]
 [ "foo", "bar", "baz" ]]

It would need to be explicitly restricted with:

  "items": {
    "oneOf": [
      { "type": ["boolean", "integer", "number", "string"] },
      {
        "type": "array",
        "items": { "type": "boolean" }
      },
      {
        "type": "array",
        "items": { "type": "integer" }
      },
      {
        "type": "array",
        "items": { "type": "number" }
      },
      {
        "type": "array",
        "items": { "type": "string" }
      }
    ]
  }

Does not provide ordering information

Assuming we have a correctly shaped matrix of numeric type expressed as an array of arrays, is it row-major or column-major?

Seems intuitive enough when written like this:

my_matrix_param:
  - [ 8, 3, 4 ]
  - [ 1, 5, 9 ]
  - [ 6, 7, 2 ]

But maybe less clear like this:

my_matrix_param:
  -
   - 8
   - 3
   - 4
  -
   - 1
   - 5
   - 9
  -
   - 6
   - 7
   - 2

We can document a row-major convention but explicit validation would always be preferred

Does not provide enough real usage scenarios

items can also be array or primitives (string, bool, int, double)

What is your use-case for components that want tabular "matrix" of bools or strings?

Does not map easily to a ROS 2 parameter type

Parameters in YAML are ultimately mapped to ROS 2 parameters, because that is their entire purpose. ROS 2 parameters do not support matrices, so the best we have (for now ¹) is a double array. This requires the matrix to be expressed in flattened form, and so we have two of the same problem points about non-explicit row-major vs column-major ordering nor that the length of the array can be factored by MxN rows and columns. But, together with parameter description and parameter validation, it is already supported for a specialized component to say that it takes a matrix parameter of a certain size and for that matrix to be expressed in a single array in the YAML.

Still, you may still be looking for a way that overcomes the main two issues of defining size and order. This would need some way to encode and decode matrix data explicitly and unambiguously with known number of rows and columns...

Enter state_representation::Parameter

It's admittedly very wonky and unintuitive but if you use the state type parameter, and then use parameter as the state representation type, you could use the ParameterType::MATRIX which contains an Eigen::MatrixXd (or numpy 2d matrix in Python).

parameter_type: state
parameter_state_type: parameter

As a reminder, when using state-type parameters, the YAML is expected to contain the JSON-serialized string representation, transported as a string ROS 2 parameter, which the component is then expected to parse into an object with clproto.

The main drawback is that entering this serialized data in the YAML is not very nice, but the eventual intention was for Studio to provide widgets for easily defining or editing state-type parameters (including cartesian and joint states) beyond the simple primitives.

---

So, in conclusion - matrices are already supported "loosely" as either 1d arrays (with the downside of non-explicit ordering and length) or as serialized strings of state-type parameters in the clproto format. Rather than just making the YAML more permissive and creating a third way, we should look for ways to improve or combine these current ways.

Footnotes

1. In future more capabilities for parameters may be introduced to ROS 2 (https://github.com/ros2/ros2/issues/1734) but this may take a while and won't be supported by current distros which remain relevant even in future years) ↩

[yrh012]

Thank you for the detailed explanation; it is now clear how the current parameter structure already supports matrices in a loose form. I can think of a refinement where we introduce an explicit matrix shape field whenever the parameter type is a matrix, together with providing the user with the ability to choose a convention for row-major versus column-major ordering and number of elements for explicit length check within the JSON schema.

This allows values to remain stored as flat lists of doubles, integers, booleans while validating that the number of elements matches the declared dimensions, and providing enough information to reconstruct the matrix reliably.

In robotics, Indeed I cannot think of an immediate use case for string matrices, while boolean matrices could serve as selection or masking matrices, though this functionality can be encoded through integer matrices with 1 and 0.

{
  "parameter_value": [1, 2, 3, 4, 5, 6],
  "parameter_type": "matrix",
  "shape": [2, 3],
  "number_of_elements": 6,
  "layout": "row-major"
}