vreLadderClimbingActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreLadderClimbingActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator for human ladder climbing
//!
//! This file defines the DtVreLadderClimbingActuator class which handles movement
//! of human entities up and down ladders. It manages position, velocity, and orientation
//! updates when a human entity is in the ladder-climbing state.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vrfobjcore/actuatorComponent.h>
 
class DtAnalogInputPort;
class DtInputPortGroup;
class DtUpdateRepositoryOutputPortGroup;
 
namespace makVre
{
class DtVreLadderClimbingPSR;
class DtLadder;
 
//! \brief Type identifier for the VRE ladder climbing actuator component
const char DtVreLadderClimbingActuatorType[] = "vre-ladder-climbing-actuator";
 
//! \brief Actuator responsible for moving human entities up and down ladders
//!
//! DtVreLadderClimbingActuator handles the movement of human entities when they
//! are climbing ladders. It manages the entity's position, velocity, and orientation
//! during ladder climbing, ensuring smooth transitions between regular movement and
//! ladder climbing states. The actuator receives movement direction input from
//! control components and updates the entity's state accordingly.
class VREVRFMODEL_DLL DtVreLadderClimbingActuator : public DtVreSimComponent<DtActuatorComponent>
{
public:
   //! \brief Constructor
   //! \param name The name of this component
   //! \param owner The local object that owns this component
   //! \param simManager The simulation services manager
   //! \param desc Component descriptor with configuration parameters
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new ladder climbing actuator component with the specified parameters.
   DtVreLadderClimbingActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the ladder climbing actuator component,
   //! including process state and port groups.
   virtual ~DtVreLadderClimbingActuator() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreLadderClimbingActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the ladder climbing actuator
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs initial setup of the ladder climbing actuator, including creating
   //! the process state repository (PSR) for maintaining climb state. This method
   //! is called during component initialization.
   virtual bool init() override;
 
   //! \brief Updates the actuator state each simulation frame
   //!
   //! If the entity is in a ladder-climbing state (according to the PSR),
   //! computes the movement of the entity on the ladder for this tick and
   //! updates the state in myUpdateRepositoryOutputPortGroup. This includes
   //! calculating new position, velocity, and orientation values based on
   //! the input control direction and ladder geometry.
   virtual void tick() override;
 
   //! \brief Creates input and output ports for the actuator
   //! \return True if ports are successfully created, false otherwise
   //!
   //! Creates the movement control input ports needed for ladder climbing,
   //! as well as the update repository output port group for updating the
   //! entity's state. These ports allow the actuator to receive movement
   //! direction and output position updates.
   virtual bool createPorts() override;
 
   //! \brief Creates input and output port groups for the actuator
   //! \return True if port groups are successfully created, false otherwise
   //!
   //! Creates the movement control input port group and the update repository
   //! output port group. These port groups organize the input and output ports
   //! for proper routing between components.
   virtual bool createPortGroups() override;
 
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param owner The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory method used by the component creation system to instantiate
   //! new instances of this component type.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
protected:
   //! \brief Creates the process state repository for the actuator
   //! \return Pointer to the created process state repository
   //!
   //! Creates the myProcessState data member and adds it to the process state
   //! repository manager. Uses the name and type specified in the component
   //! descriptor (if they exist) or appropriate defaults if not specified.
   //! This PSR stores the ladder climbing state including which ladder the
   //! entity is on and position information.
   virtual DtVreLadderClimbingPSR* createPSR();
 
   //! \brief Gets the default process state repository type
   //! \return String identifying the default PSR type
   //!
   //! Returns the default process state repository type for ladder climbing,
   //! which is used when no type is specified in the component descriptor.
   const char* defaultPSRType() const;
 
   //! \brief Gets the ladder climbing speed for this entity
   //! \return Climbing speed in meters per second
   //!
   //! Returns the ladder climbing speed for this entity in meters per second.
   //! The speed is based on the value from the descriptor if one exists
   //! (i.e., if a descriptor of type DtClimbingLadderActuatorDescriptor has been
   //! configured). If no descriptor is available or the speed is not specified,
   //! a default value of 0.4 m/s is returned.
   virtual double ladderClimbingSpeed();
 
   //! \brief Calculates and updates entity state during ladder climbing
   //!
   //! If the entity is on a ladder, calculates the new position, velocity,
   //! orientation, and other state values for the current simulation frame,
   //! then sets these values on the output ports. This method handles the
   //! actual movement calculations based on input direction and ladder geometry.
   virtual void calculateAndUpdateNewState();
 
   //! \brief Constrains entity position to the ladder extent
   //! \param ladder Reference to the ladder object
   //! \param bodyLadderBaseToEntity Vector from ladder base to entity in body coordinates
   //!
   //! Given a vector in body coordinates, clamps it to fall somewhere along the length
   //! of the ladder. This ensures that the entity's x component (in body coordinates)
   //! remains between the base and top of the ladder, preventing the entity from
   //! climbing beyond the ladder's endpoints.
   virtual void clampToLadderExtent(const DtLadder& ladder, DtVector& bodyLadderBaseToEntity);
 
protected:
   //! \brief Process state repository for ladder climbing state
   //!
   //! Holds state information associated with ladder climbing, including which
   //! ladder the entity is currently on, position relative to the ladder, and
   //! climbing state. This state persists across simulation ticks and can be
   //! saved and restored with scenarios.
   DtVreLadderClimbingPSR* myProcessState;
 
   //! \name Ports and Port Groups
   //! \{
 
   //! \brief Input port for ladder climbing movement direction
   //!
   //! Receives the desired climbing direction in radians (range: 0 - 2*pi).
   //! This direction controls whether the entity climbs up, down, or
   //! remains stationary on the ladder. Parent group: movement-control
   DtAnalogInputPort* myLadderClimbingMovementDirectionInputPort;
 
   //! \brief Output port group for updating entity state
   //!
   //! Port group used to set values into the VRF state repository during ladder climbing.
   //! This includes position, velocity, orientation, and other state values in local
   //! coordinates, which are applied to the entity during simulation.
   DtUpdateRepositoryOutputPortGroup* myUpdateRepositoryOutputPortGroup;
};
 
} // namespace makVre