RoomEditor.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    navigation::ArmarXObjects::room_editor
 * @author     Fabian Reister ( fabian dot reister at kit dot edu )
 * @date       2026
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
#include <cstddef>
#include <functional>
#include <map>
#include <optional>
#include <string>
#include <vector>
 
#include <Eigen/Core>
 
#include <RobotAPI/components/ArViz/Client/Client.h>
#include <RobotAPI/components/ArViz/Client/Interaction.h>
#include <RobotAPI/components/ArViz/Client/Layer.h>
 
#include <armarx/navigation/algorithms/Room.h>
 
namespace armarx::navigation::components::room_editor
{
 
    /// A room together with the provider segment (i.e. the navigation graph) it belongs to.
    struct EditableRoom
    {
        std::string providerSegmentName;
        algorithms::Room room;
    };
 
    /**
     * @brief Interactive ArViz front-end for the room polygons stored in the navigation memory.
     *
     * Each polygon vertex is visualized as a draggable handle which is restricted to the
     * XY plane. Additionally, a handle is placed on the midpoint of every edge. Dragging
     * such an edge handle (or using its context menu) cuts the edge, i.e. inserts a new
     * vertex in between the two adjacent ones.
     *
     * The editor is purely concerned with visualization and interaction. Whenever a room
     * has been modified, the callback registered via `setRoomChangedCallback()` is invoked,
     * which is where the change is persisted (e.g. written back to the memory).
     */
    class RoomEditor
    {
    public:
        struct Parameters
        {
            /// Prefix of the ArViz layers created by the editor.
            std::string layerPrefix = "RoomEditor";
 
            /// Radius of the (spherical) vertex handles [mm].
            float vertexHandleRadius = 75.F;
 
            /// Edge length of the (cubic) edge handles [mm].
            float edgeHandleSize = 90.F;
 
            /// Width of the polygon outline [mm].
            float lineWidth = 10.F;
 
            /// Handles are drawn slightly above the polygon to avoid z-fighting [mm].
            float handleZOffset = 20.F;
 
            /// Radius of the (cylindrical) whole-room move handle [mm].
            float moveHandleRadius = 120.F;
 
            /// Height of the (cylindrical) whole-room move handle [mm].
            float moveHandleHeight = 40.F;
 
            /// Scale of the room name labels.
            float labelScale = 4.F;
        };
 
        /// Called whenever a room was modified by the user.
        using RoomChangedCallback = std::function<void(const EditableRoom&)>;
 
        RoomEditor(viz::Client arviz, const Parameters& parameters);
 
        /**
         * @brief Replaces the edited rooms, e.g. after (re-)reading them from the memory.
         *
         * Any interaction that is currently in progress is discarded.
         */
        void setRooms(const std::vector<EditableRoom>& rooms);
 
        const std::vector<EditableRoom>& rooms() const;
 
        void setRoomChangedCallback(RoomChangedCallback callback);
 
        /// True while the user is dragging a handle. Reloading should be paused meanwhile.
        bool isInteracting() const;
 
        /**
         * @brief Processes the interaction feedback of the previous commit and stages
         *        everything that has to be (re-)drawn.
         *
         * Must be called once per cycle, right after `stage` has been reset.
         */
        void update(const viz::CommitResult& result, viz::StagedCommit& stage);
 
        /// Stages a full redraw of all layers (rooms and handles).
        void redrawAll(viz::StagedCommit& stage);
 
    private:
        struct Handle
        {
            enum class Type
            {
                /// The handle represents the polygon vertex at `pointIndex`.
                Vertex,
                /// The handle sits on the edge from `pointIndex` to `pointIndex + 1`.
                Edge,
                /// The handle moves/rotates the whole room. `pointIndex` is unused.
                Move
            };
 
            Type type = Type::Vertex;
            std::size_t roomIndex = 0;
            std::size_t pointIndex = 0;
        };
 
        /// The transformation the user is currently applying to a handle.
        struct PendingTransform
        {
            std::string element;
            Handle handle;
 
            /// For Vertex/Edge handles: the absolute new position of the (inserted) vertex.
            Eigen::Vector2f position = Eigen::Vector2f::Zero();
 
            /// For Move handles: the delta rotation about Z [rad] applied to the whole room.
            float rotation = 0.F;
 
            /// For Move handles: the delta translation in world XY [mm] applied to the whole room.
            Eigen::Vector2f translation = Eigen::Vector2f::Zero();
        };
 
        enum class ContextMenuEntry
        {
            InsertPointAfter = 0,
            InsertPointBefore = 1,
            DeletePoint = 2
        };
 
        void handleInteraction(const viz::InteractionFeedback& interaction,
                               viz::StagedCommit& stage);
 
        void handleContextMenu(const Handle& handle, int entry, viz::StagedCommit& stage);
 
        /// Applies the pending transformation to the room polygon and notifies the callback.
        void applyPendingTransform(viz::StagedCommit& stage);
 
        /// Stages a redraw of the room polygons only (used for the live drag preview).
        void redrawRooms(viz::StagedCommit& stage);
 
        /// The polygon of the given room, with a pending drag preview applied.
        std::vector<Eigen::Vector2f> previewPolygon(std::size_t roomIndex) const;
 
        /// The (untransformed) position a handle is drawn at.
        Eigen::Vector2f handlePosition(const Handle& handle) const;
 
        std::string elementName(const Handle& handle) const;
 
        void notifyRoomChanged(std::size_t roomIndex) const;
 
        viz::Client arviz;
        Parameters parameters;
 
        RoomChangedCallback roomChangedCallback;
 
        std::vector<EditableRoom> rooms_;
 
        viz::Layer roomLayer;
        viz::Layer handleLayer;
 
        /// Maps ArViz element names to the handle they represent.
        std::map<std::string, Handle> handleByElement;
 
        std::optional<PendingTransform> pendingTransform;
    };
 
} // namespace armarx::navigation::components::room_editor