ladder.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file ladder.h
//! \ingroup vreVrfobjcore
//! \brief Ladder representation class for VREngage
//!
//! This file defines the DtLadder class, which provides a representation of a ladder
//! in VREngage simulations, including its base, top, and orientation. It processes navigation
//! ladder data to create a usable representation that enables human entities to climb ladders.
 
#pragma once
 
#include "vreVrfobjcore/export.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlDcm.h>
 
#include <vector>
 
class DtNavLadder;
class DtPhysicalWorld;
 
namespace makVre
{
//! \brief Helper class that represents a climbable ladder in simulations
//!
//! This class provides a representation of a ladder, including its base, top,
//! orientation, and entry/exit points. It processes navigation ladder data to
//! determine the locations where a human entity can mount or dismount the ladder,
//! as well as the ladder's physical characteristics like pitch, heading and length.
class VREVRFOBJCORE_DLL DtLadder
{
public:
   //! \brief Default constructor
   //!
   //! Creates a new ladder representation with default values.
   //! Must be initialized with init() before use.
   DtLadder();
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the ladder representation.
   virtual ~DtLadder();
 
   //! \brief Copy constructor
   //! \param orig The source ladder to copy from
   //!
   //! Creates a new ladder representation as a copy of the provided original.
   DtLadder(const DtLadder& orig);
 
   //! \brief Assignment operator
   //! \param orig The source ladder to copy from
   //! \return Reference to this ladder after assignment
   //!
   //! Assigns the contents of the provided ladder to this one.
   DtLadder& operator=(const DtLadder& orig);
 
   //! \brief Equivalence operator
   //! \param other The ladder to compare with
   //! \return True if the ladders are equivalent, false otherwise
   //!
   //! Compares this ladder with another to determine if they are equivalent.
   virtual bool operator==(const DtLadder& other);
 
   //! \brief Initializes the ladder from navigation data
   //! \param navLadder The navigation ladder data to initialize from
   //! \param physicalWorld Pointer to the physical world for terrain queries
   //!
   //! Initializes this ladder representation based on the provided navigation ladder
   //! data and physical world. This calculates the ladder's base, top, orientation,
   //! and entry/exit points.
   virtual void init(const DtNavLadder& navLadder, DtPhysicalWorld* physicalWorld);
 
   //! \brief Gets the ladder base position
   //! \return The position of the ladder's base in local coordinates
   //!
   //! Returns the position where the bottom of the ladder contacts the ground.
   virtual DtVector base() const;
 
   //! \brief Gets the ladder base entry/exit point
   //! \return The position where an entity would enter/exit at the ladder's base
   //!
   //! Returns the position where an entity would stand to mount or dismount
   //! the ladder at its base.
   virtual DtVector baseEntryExit() const;
 
   //! \brief Gets the ladder top position
   //! \return The position of the ladder's top in local coordinates
   //!
   //! Returns the position of the top end of the ladder.
   virtual DtVector top() const;
 
   //! \brief Gets the ladder top entry/exit point
   //! \return The position where an entity would enter/exit at the ladder's top
   //!
   //! Returns the position where an entity would stand to mount or dismount
   //! the ladder at its top.
   virtual DtVector topEntryExit() const;
 
   //! \brief Gets the ladder heading
   //! \return The heading angle in radians
   //!
   //! Returns the heading angle of the ladder in radians. This represents
   //! the direction the ladder is facing when viewed from above.
   virtual double heading() const;
 
   //! \brief Gets the ladder pitch
   //! \return The pitch angle in radians
   //!
   //! Returns the pitch angle of the ladder in radians. This represents
   //! the steepness of the ladder relative to the ground.
   virtual double pitch() const;
 
   //! \brief Gets the ladder length
   //! \return The length of the ladder in meters
   //!
   //! Returns the total length of the ladder from base to top.
   virtual double length() const;
 
   //! \brief Gets the ladder orientation matrix
   //! \return The direction cosine matrix representing the ladder's orientation
   //!
   //! Returns a direction cosine matrix representing the ladder's orientation
   //! in local coordinates.
   virtual DtDcm localOrientation() const;
 
protected:
   //! \brief Calculates ladder properties from point data
   //!
   //! Internal method that calculates the ladder's base, top, heading, pitch,
   //! length, and orientation based on the ladder points.
   virtual void calculateBaseTopAndOrientation();
 
 
protected:
   //! \brief Ordered list of points on the ladder
   //!
   //! Stores points along the ladder in local (database) coordinates.
   std::vector<DtVector> myLocalPointsOnLadder;
 
   //! \brief Ordered list of entry/exit points
   //!
   //! Stores points near the ladder on the terrain in local coordinates,
   //! where an entity would stand to mount or dismount the ladder.
   //! Has one-to-one correspondence with myLocalPointsOnLadder.
   std::vector<DtVector> myLocalLadderEntryExitPoints;
 
   //! \brief Index of the base point in the points array
   //!
   //! Stores the index of the base point within myLocalPointsOnLadder.
   int myBaseIndex;
 
   //! \brief Index of the top point in the points array
   //!
   //! Stores the index of the top point within myLocalPointsOnLadder.
   int myTopIndex;
 
   //! \brief The ladder heading in radians
   //!
   //! Stores the heading angle of the ladder in radians.
   double myHeading;
 
   //! \brief The ladder pitch in radians
   //!
   //! Stores the pitch angle of the ladder in radians.
   double myPitch;
 
   //! \brief The ladder length in meters
   //!
   //! Stores the total length of the ladder from base to top.
   double myLength;
 
   //! \brief The ladder orientation matrix
   //!
   //! Stores a direction cosine matrix representing the ladder's orientation
   //! in local coordinates.
   DtDcm myLocalOrientation;
 
   //! \brief Pointer to the physical world
   //!
   //! Stores a pointer to the physical world used for terrain queries.
   DtPhysicalWorld* myPhysicalWorld;
};
} // namespace makVre