SkillEventRenderer.h

Go to the documentation of this file.

/*
 * This file is part of ArmarX.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @package    RobotAPI::ArmarXObjects::OpossumLogger
 * @author     Joana Plewnia ( joana dot plewnia at kit dot edu )
 * @date       2026
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
#include <functional>
#include <optional>
#include <set>
#include <string>
#include <vector>
 
#include <SimoxUtility/json/json.hpp>
 
#include <ArmarXCore/core/time/DateTime.h>
 
namespace armarx::opossum
{
 
    /**
     * @brief One skill lifecycle event, as stored in the Skill memory's
     * `SkillEvent` core segment.
     *
     * `parameters` and `result` are expected in the self-describing Aron JSON
     * format (the one with `_ARON_VALUE` / `_ARON_ELEMENTS` wrappers), which is
     * both what `aron::data::converter::AronNlohmannJSONConverter` produces and
     * what an LTM export writes to `data.aron.json`. This lets the same renderer
     * run on live memory data and on exported files.
     */
    struct SkillEvent
    {
        std::string skillName;
 
        /// One of the `armarx::skills::SkillStatus` names, e.g. "Running", "Succeeded".
        std::string status;
 
        /// The call stack of the execution, e.g. "ServeDrinks->ServeDrinks::BringObjectFromCart".
        std::string executorName;
 
        nlohmann::json parameters;
        nlohmann::json result;
 
        armarx::core::time::DateTime timestamp;
    };
 
    /**
     * @brief Resolves an object class to its natural-language ("spoken") name.
     *
     * Returns `std::nullopt` if the class is unknown, in which case the renderer
     * falls back to a humanized class name. Injected rather than hardcoded so
     * that the renderer stays free of PriorKnowledge/filesystem dependencies and
     * can be unit-tested; see `ObjectSpokenNames.h` for the production lookup.
     */
    using SpokenNameLookup = std::function<std::optional<std::string>(
        const std::string& dataset, const std::string& className)>;
 
    /**
     * @brief Converts skill events into OPOSSUM log lines.
     *
     * The output format is one `key:value` line per event, e.g.
     * @code
     * skill:LookAtObject, object:dining table, called_by:ServeDrinks::ApproachAndAskForDrink, state:started, time_stamp:2026-07-08T16:45:40.341
     * @endcode
     *
     * This is a port of `tools/gen_armar7_logs.py` in the `opossum_euROBIN`
     * repository, which produces the same lines offline from an LTM export.
     * Function names are kept in sync with that script on purpose, so the two
     * can be compared when the format changes.
     */
    class SkillEventRenderer
    {
    public:
        SkillEventRenderer();
        SkillEventRenderer(std::set<std::string> noiseSkills, SpokenNameLookup spokenNameLookup);
 
        /**
         * @brief Render one event.
         * @return The log line, or `std::nullopt` if the event is not reportable
         *         (unknown/intermediate status, or a skill on the noise list).
         */
        std::optional<std::string> render(const SkillEvent& event) const;
 
        /// Whether `render()` would drop this skill as noise. Lets a caller skip
        /// the event before paying to fetch it.
        bool isNoiseSkill(const std::string& skillName) const;
 
        /// Pure body/gaze control and primitives that only implement a skill
        /// already logged above them. These say nothing at scene level.
        static const std::set<std::string>& DefaultNoiseSkills();
 
        /// `DefaultNoiseSkills()` as a comma-separated string (for property defaults).
        static std::string DefaultNoiseSkillsString();
 
        /// Split a comma-separated list into a set, trimming whitespace.
        static std::set<std::string> ParseSkillList(const std::string& commaSeparated);
 
    private:
        /// Natural-language name of an ObjectID `{dataset, className, instanceName}`.
        std::string objectName(const nlohmann::json& objectID) const;
 
        /// `Kitchen/serving-cart-at-lab/on-upper-shelf:with-drinks`
        /// -> `on upper shelf of serving cart`.
        std::string locationName(const std::string& value) const;
 
        /// The parameters that carry scene-level meaning, keyed by what they mean.
        std::vector<std::string> subjectFields(const nlohmann::json& parameters) const;
 
        std::set<std::string> noiseSkills;
        SpokenNameLookup spokenNameLookup;
    };
 
    /**
     * @brief Helpers of `SkillEventRenderer`, exposed for testing.
     *
     * Each is a port of the equally-named function in `gen_armar7_logs.py`.
     */
    namespace detail
    {
        /// Decode a self-describing Aron JSON tree into plain JSON.
        nlohmann::json flat(const nlohmann::json& node);
 
        /// `serving-cart-at-lab` -> `serving cart at lab`; `laundryBasket` -> `laundry basket`.
        std::string humanize(const std::string& text);
 
        /// Whether `value` is an ObjectID (has className, dataset and instanceName).
        bool isObjectID(const nlohmann::json& value);
 
        /// Fetch a parameter by name, supporting `outer.inner` nesting.
        const nlohmann::json* lookup(const nlohmann::json& parameters, const std::string& key);
 
        /// Pull the human-readable reason out of an ArmarX error message.
        std::string errorText(const std::string& message);
 
        /// Free text needs quoting: it may contain commas, which separate fields.
        std::string quoted(const std::string& text);
 
        /// Map a `SkillStatus` name to the reported state, if it is reportable.
        std::optional<std::string> stateOf(const std::string& status);
 
        /// The last segment of the executor call stack, i.e. the calling skill.
        std::string calledBy(const std::string& executorName);
 
        /// Local time as `2026-07-08T16:45:40.341` (milliseconds, truncated).
        std::string timestamp(const armarx::core::time::DateTime& time);
    } // namespace detail
 
} // namespace armarx::opossum