payload_contribution_model.h

浏览该文件的文档.

#ifndef AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H
#define AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H
 
#include <aubo_caps/class_forward.h>
#include <aubo_caps/domain/payload/payload.h>
 
namespace arcs {
namespace aubo_scope {
ARCS_CLASS_FORWARD(PayloadContributionModel);
 
/**
 * @ingroup InstallationApi
 * \~chinese 动态负载管理
 * \~english API interface for dynamic payload management
 */
 
class ARCS_ABI_EXPORT PayloadContributionModel
{
public:
    PayloadContributionModel(PayloadContributionModel &f);
    PayloadContributionModel(PayloadContributionModel &&f);
    ~PayloadContributionModel();
 
    /**
     * @ingroup PayloadContributionModel
     * @ref Payload
     * \chinese
     * <p>
     * 向AuboScope的当前安装中添加一个负载。
     * </p>
     *
     * <p>
     * 添加后终端用户可选择该负载，其他AuboCap贡献（通过{@link PayloadModel}接口）也可
     * 使用。该负载不可被终端用户或其他aubo_studio插件修改。
     * </p>
     *
     * <p>
     * 系统将根据指定的负载质量和重心自动计算惯性矩阵的默认估算值。如果有负载惯性矩阵
     * 的实际数据，可以使用{@link #addPayload(String, String, Mass, Position,
     * InertiaMatrix)}方法替代（可获得更好的机器人手臂性能）。
     * </p>
     *
     * <p>
     * <b>注意：</b>指定的负载质量必须是连接到机器人工具输出法兰的负载总质量。
     * </p>
     *
     * 负载质量和重心坐标（CoG）的有效范围可通过{@link RobotLimits}接口获取，该接口
     * 可通过{@link RobotModel#getRobotLimits()}访问。
     *
     * @param idKey 用于标识此负载的键，不可为<code>null</code>或空字符串。该键仅对
     * 此AuboCap有效，只需在此AuboCap中唯一，无需对其他aubo_studio插件"全局"唯一。
     * @param suggestedName 建议的负载名称，不可为<code>null</code>或空字符串。有效
     * 名称必须匹配正则表达式[a-zA-Z][a-zA-Z0-9_]{0,14}，总共15个字符。最终名称可
     * 从返回的负载实例获取。
     * @param mass 连接到机器人工具输出法兰的负载总质量，不可为<code>null</code>。使
     * 用{@link SimpleValueFactory#createMass(double, Mass.Unit)}创建。
     * @param centerOfGravity 负载的重心（CoG），也称为质心。定义为工具输出法兰中心与
     * 所连接负载重心之间的偏移量。不可为<code>null</code>。使用{@link PositionFactory}
     * 接口创建。
     * @return 在AuboScope中创建并注册的负载。
     * @throws PayloadAlreadyAddedException 如果之前已使用相同的<code>idKey</code>标
     * 识符添加过负载。使用{@link #getPayload(String)}检查负载是否已添加到当前安装中。
     * 使用{@link #updatePayload(String, Mass, Position)}或
     * {@link #updatePayload(String, Mass, Position, InertiaMatrix)}来更新负载。
     * @throws IllegalPayloadNameException 如果建议的名称不匹配所需的正则表达式。
     * @throws IllegalMassException 如果指定的质量不在AuboScope定义的有效范围内。
     * @throws IllegalCenterOfGravityException 如果指定重心的任何值不在AuboScope定义
     * 的有效范围内。
     * \endchinese
     * \english
     * <p>
     * Add a payload to the current installation in AuboScope.
     * </p>
     *
     * <p>
     * This makes the payload selectable by the end user as well as available to
     * other AuboCap contributions (through the
     * {@link PayloadModel} interface). The payload is not modifiable by the end
     * user or other aubo_studio plugins.
     * </p>
     *
     * <p>
     * A default guess for the inertia matrix for the payload will be computed
     * based on the specified payload mass and center of gravity. If data for
     * the payload's inertia matrix is available, the method
     * {@link #addPayload(String, String, Mass, Position, InertiaMatrix)} can
     * used instead (this might give better performance of the robot arm).
     * </p>
     *
     * <p>
     * <b>Note:</b> The specified payload mass must be the total mass of the
     * payload attached to the tool output flange of the robot.
     * </p>
     *
     * The valid range for the payload mass and the coordinates of the center of
     * gravity (CoG) are available through the
     * {@link RobotLimits} interface which can be accessed with {@link
     * RobotModel#getRobotLimits()} (an instance of the
     * {@link RobotModel} interface can be retrieved through {@link
     * SystemAPI#getRobotModel()}).
     *
     * @param idKey The key to identify this payload by, not <code>null</code>
     * nor an empty string. The key is for this AuboCap only, i.e. it only has
     * to be unique for this AuboCap and not "globally" for other aubo_studio
     * plugins.
     * @param suggestedName Suggested name for the payload, not
     * <code>null</code> nor an empty string. Valid names must match regex
     * [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name
     * can be retrieved from the returned payload instance.
     * @param mass The total mass of the payload attached to the tool output
     * flange of the robot, not <code>null</code>. Create it using {@link
     * SimpleValueFactory#createMass(double, Mass.Unit)}.
     * @param centerOfGravity The center of gravity (CoG), also referred to as
     * center of mass, for the payload. It is defined as the offset between the
     * center of the tool output flange and the center of gravity of the
     * attached payload. Cannot be <code>null</code>. Create it using the {@link
     * PositionFactory} interface.
     * @return The payload created and registered in AuboScope.
     * @throws PayloadAlreadyAddedException If a payload has previously been
     * added using the same <code>idKey</code> identifier. Use {@link
     * #getPayload(String)} to check if the payload has already been added to
     * the current installation. Use {@link #updatePayload(String, Mass,
     * Position)} or
     *                                      {@link #updatePayload(String, Mass,
     * Position, InertiaMatrix)} to update the payload if the payload parameters
     * have changed.
     * @throws IllegalPayloadNameException If the suggested name does not match
     * required regex.
     * @throws IllegalMassException If the specified mass is not inside the
     * valid range as defined by AuboScope.
     * @throws IllegalCenterOfGravityException If any of the values of the
     * specified center of gravity are not inside the valid range as defined by
     * AuboScope.
     * \endenglish
     */
    PayloadPtr addPayload(const std::string &id_key,
                          const std::string &suggested_name, double mass,
                          const std::vector<double> &center_of_gravity);
 
    /**
     * @ingroup PayloadContributionModel
     * @ref Payload
     * \chinese
     * <p>
     * 向AuboScope的当前安装中添加一个包含惯性矩阵的负载。
     * </p>
     *
     * <p>
     * 添加后终端用户可选择该负载，其他AuboCap贡献（通过{@link PayloadModel}接口）也可
     * 使用。该负载不可被终端用户或其他aubo_studio插件修改。
     * </p>
     *
     * 如果没有负载惯性矩阵的数据，请改用{@link #addPayload(String, String, Mass,
     * Position, InertiaMatrix)}方法。
     *
     * <p>
     * <b>注意：</b>指定的负载质量必须是连接到机器人工具输出法兰的负载总质量。
     * </p>
     *
     * 负载质量和重心坐标（CoG）的有效范围可通过{@link RobotLimits}接口获取，该接口
     * 可通过{@link RobotModel#getRobotLimits()}访问。
     *
     * @param idKey 用于标识此负载的键，不可为<code>null</code>或空字符串。该键仅对
     * 此AuboCap有效。
     * @param suggestedName 建议的负载名称，不可为<code>null</code>或空字符串。
     * @param mass 负载总质量，不可为<code>null</code>。
     * @param centerOfGravity 负载的重心（CoG），不可为<code>null</code>。
     * @param inertiaMatrix 负载的惯性矩阵，定义在以负载重心为中心的坐标系中，坐标轴与
     * 工具输出法兰坐标系对齐。不可为<code>null</code>。
     * @return 在AuboScope中创建并注册的负载。
     * @throws PayloadAlreadyAddedException 如果之前已使用相同的<code>idKey</code>标
     * 识符添加过负载。
     * @throws IllegalPayloadNameException 如果建议的名称不匹配所需的正则表达式。
     * @throws IllegalMassException 如果指定的质量不在有效范围内。
     * @throws IllegalCenterOfGravityException 如果指定重心的任何值不在有效范围内。
     * @throws IllegalInertiaMatrixException 如果指定惯性矩阵的任何值不在有效范围内。
     * \endchinese
     * \english
     * <p>
     * Add a payload to the current installation in AuboScope.
     * </p>
     *
     * <p>
     * This makes the payload selectable by the end user as well as available to
     * other AuboCap contributions (through the
     * {@link PayloadModel} interface). The payload is not modifiable by the end
     * user or other aubo_studio plugins.
     * </p>
     *
     * Use the {@link #addPayload(String, String, Mass, Position,
     * InertiaMatrix)} method instead if data for the payload's inertia matrix
     * is not available.
     *
     * <p>
     * <b>Note:</b> The specified payload mass must be the total mass of the
     * payload attached to the tool output flange of the robot.
     * </p>
     *
     * The valid range for the payload mass and the coordinates of the center of
     * gravity (CoG) are available through the
     * {@link RobotLimits} interface which can be accessed with {@link
     * RobotModel#getRobotLimits()} (an instance of the
     * {@link RobotModel} interface can be retrieved through {@link
     * SystemAPI#getRobotModel()}).
     *
     * @param idKey The key to identify this payload by, not <code>null</code>
     * nor an empty string. The key is for this AuboCap only, i.e. it only has
     * to be unique for this AuboCap and not "globally" for other aubo_studio
     * plugins.
     * @param suggestedName Suggested name for the payload, not
     * <code>null</code> nor an empty string. Valid names must match regex
     * [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name
     * can be retrieved from the returned payload instance.
     * @param mass The total mass of the payload attached to the tool output
     * flange of the robot, not <code>null</code>. Create it using {@link
     * SimpleValueFactory#createMass(double, Mass.Unit)}.
     * @param centerOfGravity The center of gravity (CoG), also referred to as
     * center of mass, for the payload. It is defined as the offset between the
     * center of the tool output flange and the center of gravity of the
     * attached payload. Cannot be <code>null</code>. Create it using the {@link
     * PositionFactory} interface.
     * @param inertiaMatrix The inertia matrix of the payload, defined in a
     * coordinate system with center at the payload's center of gravity and the
     * axes aligned with the tool output flange coordinate system (axes). Cannot
     * be <code>null</code>. Create it using
     *                      {@link #createInertiaMatrix(double, double, double,
     * double, double, double, MomentOfInertia.Unit)}.
     * @return The payload created and registered in AuboScope.
     * @throws PayloadAlreadyAddedException If a payload has previously been
     * added using the same <code>idKey</code> identifier. Use {@link
     * #getPayload(String)} to check if the payload has already been added to
     *                                  the current installation.
     *                                  Use {@link #updatePayload(String, Mass,
     * Position)} or
     *                                  {@link #updatePayload(String, Mass,
     * Position, InertiaMatrix)} to update the payload if the payload parameters
     * have changed.
     * @throws IllegalPayloadNameException If the suggested name does not match
     * required regex.
     * @throws IllegalMassException If the specified mass is not inside the
     * valid range as defined by AuboScope.
     * @throws IllegalCenterOfGravityException If any of the values of the
     * specified center of gravity are not inside the valid range as defined by
     * AuboScope.
     * @throws IllegalInertiaMatrixException If any of the values of the
     * specified inertia matrix are not inside the valid range as defined by
     * AuboScope.
     * \endenglish
     */
    PayloadPtr addPayload(const std::string &id_key,
                          const std::string &suggested_name, double mass,
                          const std::vector<double> &center_of_gravity,
                          const std::vector<double> &inertiaMatrix);
 
    /**
     * @ingroup PayloadContributionModel
     * @ref Payload
     * \chinese
     * 返回此前由此AuboCap使用相同<code>idKey</code>标识符添加的负载。使用此方法验证
     * 负载是否存在于当前安装中。
     *
     * @param idKey 用于标识此负载的键，不可为<code>null</code>或空字符串。
     * @return 此前由此AuboCap添加的负载。如果当前安装中不存在（指定<code>idKey</code>
     * 标识符的）负载，则返回<code>null</code>。
     * \endchinese
     * \english
     * Returns the payload previously added by this AuboCap using the same
     * <code>idKey</code> identifier. Use this to verify if the payload is
     * present in the current installation.
     *
     * @param idKey The key to identify this payload by, not <code>null</code>
     * nor an empty string.
     * @return The payload previously added by this AuboCap.
     *         Returns <code>null</code> if no payload exists in current
     * installation (with the specified <code>idKey</code> identifier).
     * \endenglish
     */
    PayloadPtr getPayload(const std::string &id_key);
 
    /**
     * @ingroup PayloadContributionModel
     * @ref Payload
     * \chinese
     * <p>
     * 更新此AuboCap已添加负载的质量和重心（CoG）。
     * </p>
     *
     * <b>注意：</b>如果已为负载指定了惯性矩阵，调用此方法将用基于新的负载质量和重心
     * 计算的默认估算值替换（覆盖）它。为避免覆盖现有惯性矩阵（或更新现有惯性矩阵），
     * 请改用{@link #updatePayload(String, Mass, Position, InertiaMatrix)}方法。
     *
     * @param idKey 用于标识负载的键，不可为<code>null</code>或空字符串。调用此方法
     * 前必须已使用相同的键添加过负载。
     * @param mass 负载总质量，不可为<code>null</code>。使用
     * {@link SimpleValueFactory#createMass(double, Mass.Unit)}创建。
     * @param centerOfGravity 负载的重心，不可为<code>null</code>。使用
     * {@link PositionFactory}接口创建。
     * @throws PayloadNotFoundException 如果当前安装中不存在对应<code>idKey</code>
     * 标识符的负载。
     * @throws IllegalMassException 如果指定的质量不在AuboScope定义的有效范围内。
     * @throws IllegalCenterOfGravityException 如果指定重心的任何值不在有效范围内。
     * \endchinese
     * \english
     * <p>
     * Update the mass and center of gravity (CoG) of an existing payload added
     * by this AuboCap.
     * </p>
     *
     * <b>Note:</b> If an inertia matrix has been specified for the payload,
     * calling this method will replace (overwrite) it with a computed default
     * guess based the new specified payload mass and center of gravity. To avoid
     * overwriting an existing inertia matrix (or to update an existing inertia
     * matrix), instead use the method
     * {@link #updatePayload(String, Mass, Position, InertiaMatrix)}.
     *
     * @param idKey The key to identify the payload, not <code>null</code> nor
     * an empty string. A payload must have been added using the same key prior
     * to calling this method.
     * @param mass The total mass of the payload attached to the tool output
     * flange of the robot, not <code>null</code>. Create it using {@link
     * SimpleValueFactory#createMass(double, Mass.Unit)}.
     * @param centerOfGravity The center of gravity of the payload, not {@code
     * null}. Create it using the
     *                        {@link PositionFactory} interface.
     * @throws PayloadNotFoundException If no payload exists with the provided
     * <code>idKey</code> identifier in the current installation.
     * @throws IllegalMassException If the specified mass is not inside the
     * valid range as defined by AuboScope.
     * @throws IllegalCenterOfGravityException If any of the values of the
     * specified center of gravity are not inside the valid range as defined by
     * AuboScope.
     * \endenglish
     */
    void updatePayload(const std::string &id_key, double mass,
                       const std::vector<double> &center_of_gravity);
 
    /**
     * @ingroup PayloadContributionModel
     * \chinese
     * 更新此AuboCap已添加负载的质量、重心（CoG）和惯性矩阵。
     *
     * @param idKey 用于标识负载的键，不可为<code>null</code>或空字符串。调用此方法
     * 前必须已使用相同的键添加过负载。
     * @param mass 负载总质量，不可为<code>null</code>。使用
     * {@link SimpleValueFactory#createMass(double, Mass.Unit)}创建。
     * @param centerOfGravity 负载的重心，不可为<code>null</code>。使用
     * {@link PositionFactory}接口创建。
     * @param inertiaMatrix 负载的惯性矩阵，不可为<code>null</code>。
     * @throws PayloadNotFoundException 如果当前安装中不存在对应<code>idKey</code>
     * 标识符的负载。
     * @throws IllegalMassException 如果指定的质量不在有效范围内。
     * @throws IllegalCenterOfGravityException 如果指定重心的任何值不在有效范围内。
     * @throws IllegalInertiaMatrixException 如果指定惯性矩阵的任何值不在有效范围内。
     * \endchinese
     * \english
     * Update the mass, center of gravity (CoG) and inertia matrix of an
     * existing payload added by this AuboCap.
     *
     * @param idKey The key to identify the payload, not <code>null</code> nor
     * an empty string. A payload must have been added using the same key prior
     * to calling this method.
     * @param mass The total mass of the payload attached to the tool output
     * flange of the robot, not <code>null</code>. Create it using {@link
     * SimpleValueFactory#createMass(double, Mass.Unit)}.
     * @param centerOfGravity The center of gravity of the payload, not {@code
     * null}. Create it using the
     *                        {@link PositionFactory} interface.
     * @param inertiaMatrix The inertia matrix of the payload, not
     * <code>null</code>. Create it using
     *                      {@link #createInertiaMatrix(double, double, double,
     * double, double, double, MomentOfInertia.Unit)}
     * @throws PayloadNotFoundException If no payload exists with the provided
     * <code>idKey</code> identifier in the current installation.
     * @throws IllegalMassException If the specified mass is not inside the
     * valid range as defined by AuboScope.
     * @throws IllegalCenterOfGravityException If any of the values of the
     * specified center of gravity are not inside the valid range as defined by
     * AuboScope.
     * @throws IllegalInertiaMatrixException If any of the values of the
     * specified inertia matrix are not inside the valid range as defined by
     * AuboScope.
     * \endenglish
     */
    void updatePayload(const std::string id_key, double mass,
                       const std::vector<double> &center_of_gravity,
                       const std::vector<double> &inertia_matrix);
 
    /**
     * @ingroup PayloadContributionModel
     * \chinese
     * 从此AuboCap中移除已添加的负载。使用该负载的程序节点将变为未定义状态，因为负载
     * 不再可解析。
     *
     * @param idKey 添加负载时使用的标识符键，不可为<code>null</code>或空字符串。
     * @throws PayloadNotFoundException 如果当前安装中不存在对应<code>idKey</code>
     * 标识符的负载。
     * \endchinese
     * \english
     * Remove a payload added by this AuboCap from AuboScope. Program nodes
     * using the payload will be become undefined because the payload is no
     * longer resolvable.
     *
     * @param idKey The identifier key used to add the payload with, not {@code
     * null} nor an empty string.
     * @throws PayloadNotFoundException If no payload exists with the provided
     * <code>idKey</code> identifier in the current installation.
     * \endenglish
     */
    void removePayload(const std::string &id_key);
 
private:
    friend class DataSwitch;
    PayloadContributionModel();
    void *d_{ nullptr };
};
} // namespace aubo_scope
} // namespace arcs
 
#endif // AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H