entityHelper.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file entityHelper.h
//! \brief Defines helper utilities for working with entities in VR-Engage
//!
//! This file contains the DtEntityHelper class which provides utility functions
//! for interacting with simulation entities. It offers methods for entity lookup,
//! position calculation, orientation, sensor management, and spatial operations.
 
#pragma once
 
 
#include "vrePlayerStation/export.h"
 
#include <vrvCore/DtUniqueID.h>
#include <vrvCore/DtElementData.h>
 
#include <matrix/vlVector.h>
#include <matrix/vlQuaternion.h>
#include <vlpi/entityType.h>
 
#include <string>
#include <map>
 
namespace makVrv
{
class DtDe;
class DtObserver;
class DtSceneObject;
class DtIntersector;
} // namespace makVrv
 
namespace makVre
{
class DtEntityResolver;
}
 
 
//! \brief Helper class for entity information and operations
//!
//! DtEntityHelper provides a comprehensive set of utility functions for working
//! with simulation entities. It facilitates entity lookup, position and orientation
//! calculations, sensor management, and various spatial operations. This class serves
//! as a bridge between the VR-Engage application and the underlying simulation entities,
//! abstracting complex operations behind simple interface methods.
//!
//! The class follows a singleton pattern for global access while maintaining proper
//! initialization controls.
class PLAYERSTATION_DLL DtEntityHelper
{
public:
   //! \brief Constructor
   //! \param de Reference to the display engine
   //! \param resolver Pointer to the entity resolver
   //!
   //! Creates a new entity helper object with the specified display engine and
   //! entity resolver. The display engine provides access to the visual representation
   //! of entities, while the entity resolver maps between different entity identifiers.
   DtEntityHelper(makVrv::DtDe& de, makVre::DtEntityResolver* resolver);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the entity helper.
   virtual ~DtEntityHelper();
 
   //! \brief Initializes the singleton instance
   //! \param de Reference to the display engine
   //! \param resolver Pointer to the entity resolver
   //!
   //! Initializes the singleton instance of the entity helper with the specified
   //! display engine and entity resolver. This must be called before any other
   //! static methods are used.
   static void initialize(makVrv::DtDe& de, makVre::DtEntityResolver* resolver);
 
   //! \brief Gets the singleton instance
   //! \return Reference to the singleton instance
   //!
   //! Retrieves the singleton instance of the entity helper.
   //! The helper must be initialized before calling this method.
   static DtEntityHelper& instance();
 
   //! \brief Checks if the singleton is initialized
   //! \return True if initialized, false otherwise
   //!
   //! Determines whether the singleton instance has been properly initialized.
   static bool isInitialized();
 
   //! \brief Entity location methods
   //! @{
 
   //! \brief Finds an entity's location given its global simulation ID
   //! \param globalId Global simulation identifier string
   //! \return 3D vector containing the entity's position in geocentric coordinates
   //!
   //! Looks up the current position of an entity using its global simulation ID.
   //! Returns the entity's position in geocentric coordinates.
   DtVector lookupEntityLocation(const std::string& globalId);
 
   //! \brief Finds an entity's location given its unique ID
   //! \param uniqueId Unique identifier for the entity
   //! \return 3D vector containing the entity's position in geocentric coordinates
   //!
   //! Looks up the current position of an entity using its unique ID.
   //! Returns the entity's position in geocentric coordinates.
   DtVector lookupEntityLocation(makVrv::DtUniqueID uniqueId);
   //! @}
 
   //! \brief Orientation calculation methods
   //! @{
 
   //! \brief Determines the quaternion to rotate from one vector to another
   //! \param cigStart Starting position vector in geocentric coordinates
   //! \param cigEnd Target position vector in geocentric coordinates
   //! \return Quaternion representing the rotation from start to end vector
   //!
   //! Calculates a quaternion that rotates from the start vector to the end vector.
   //! This function assumes the database up vector as the up direction for both vectors.
   //! Useful for orienting entities to face specific targets or directions.
   DtQuaternion orientToVector(DtVector cigStart, DtVector cigEnd);
 
   //! \brief Determines the heading in degrees from an entity to a target point
   //! \param globalId Global simulation identifier string of the source entity
   //! \param cigEnd Target position in geocentric coordinates
   //! \return Heading in degrees from entity to target (0-360, clockwise from north)
   //!
   //! Calculates the heading in degrees from an entity to a target point.
   //! The heading is measured clockwise from north (0-360 degrees).
   double degreesToTarget(std::string& globalId, DtVector cigEnd);
 
   //! \brief Determines the heading in degrees from an entity to a target point
   //! \param uniqueId Unique identifier of the source entity
   //! \param cigEnd Target position in geocentric coordinates
   //! \return Heading in degrees from entity to target (0-360, clockwise from north)
   //!
   //! Calculates the heading in degrees from an entity to a target point.
   //! The heading is measured clockwise from north (0-360 degrees).
   double degreesToTarget(makVrv::DtUniqueID uniqueId, DtVector cigEnd);
 
   //! \brief Determines the heading in degrees between two points
   //! \param cigStart Starting position in geocentric coordinates
   //! \param cigEnd Target position in geocentric coordinates
   //! \return Heading in degrees from start to end point (0-360, clockwise from north)
   //!
   //! Calculates the heading in degrees from a start point to an end point.
   //! The heading is measured clockwise from north (0-360 degrees).
   //! This version works with arbitrary positions rather than entities.
   double degreesToTarget(DtVector cigStart, DtVector cigEnd);
   //! @}
 
   //! \brief Entity lookup methods
   //! @{
 
   //! \brief Gets the scene object for an entity
   //! \param uniqueId Unique identifier of the entity
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Retrieves the scene object associated with the specified entity.
   //! The scene object provides access to the visual representation and properties
   //! of the entity in the 3D scene.
   makVrv::DtSceneObject* getSceneObject(makVrv::DtUniqueID uniqueId);
 
   //! \brief Gets an entity's current heading
   //! \param uniqueId Unique identifier of the entity
   //! \return Heading in degrees (0-360, clockwise from north)
   //!
   //! Retrieves the current heading of an entity specified by its unique ID.
   //! The heading is measured in degrees clockwise from north.
   double getHeading(makVrv::DtUniqueID uniqueId);
 
   //! \brief Gets a scene object's current heading
   //! \param scnObj Pointer to the scene object
   //! \return Heading in degrees (0-360, clockwise from north)
   //!
   //! Retrieves the current heading of a scene object.
   //! The heading is measured in degrees clockwise from north.
   double getHeading(makVrv::DtSceneObject* scnObj);
 
   //! \brief Gets an observer's current heading
   //! \param obs Pointer to the observer
   //! \return Heading in degrees (0-360, clockwise from north)
   //!
   //! Retrieves the current heading of an observer (camera view).
   //! The heading is measured in degrees clockwise from north.
   double getHeading(makVrv::DtObserver* obs);
 
   //! \brief Gets an entity's current altitude
   //! \param uniqueId Unique identifier of the entity
   //! \return Altitude in meters above mean sea level
   //!
   //! Retrieves the current altitude of an entity specified by its unique ID.
   //! The altitude is measured in meters above mean sea level.
   double getAltitude(makVrv::DtUniqueID uniqueId);
 
   //! \brief Gets a scene object's current altitude
   //! \param scnObj Pointer to the scene object
   //! \return Altitude in meters above mean sea level
   //!
   //! Retrieves the current altitude of a scene object.
   //! The altitude is measured in meters above mean sea level.
   double getAltitude(makVrv::DtSceneObject* scnObj);
   //! @}
 
   //! \brief Entity identifier conversion methods
   //! @{
 
   //! \brief Converts marking text to a unique ID
   //! \param markingText Entity marking text (display name)
   //! \return Unique ID corresponding to the marking text
   //!
   //! Looks up the unique ID of an entity based on its marking text (display name).
   //! Returns a null ID if no matching entity is found.
   makVrv::DtUniqueID uniqueIdFromMarkingText(const std::string& markingText);
 
   //! \brief Converts connection ID to a unique ID
   //! \param connectionId Entity connection identifier
   //! \return Unique ID corresponding to the connection ID
   //!
   //! Looks up the unique ID of an entity based on its connection identifier.
   //! Returns a null ID if no matching entity is found.
   makVrv::DtUniqueID uniqueIdFromConnectionId(const std::string& connectionId);
 
   //! \brief Converts marking text to a connection ID
   //! \param markingText Entity marking text (display name)
   //! \return Connection ID corresponding to the marking text
   //!
   //! Looks up the connection identifier of an entity based on its marking text.
   //! Returns an empty string if no matching entity is found.
   std::string connectionIdFromMarkingText(const std::string& markingText);
 
   //! \brief Converts unique ID to a connection ID
   //! \param id Unique identifier of the entity
   //! \return Connection ID corresponding to the unique ID
   //!
   //! Looks up the connection identifier of an entity based on its unique ID.
   //! Returns an empty string if no matching entity is found.
   std::string connectionIdFromUniqueId(makVrv::DtUniqueID id);
 
   //! \brief Converts unique ID to marking text
   //! \param uniqueId Unique identifier of the entity
   //! \return Marking text (display name) corresponding to the unique ID
   //!
   //! Looks up the marking text (display name) of an entity based on its unique ID.
   //! Returns an empty string if no matching entity is found.
   std::string markingTextFromUniqueId(makVrv::DtUniqueID uniqueId);
 
   //! \brief Converts connection ID to marking text
   //! \param id Connection identifier of the entity
   //! \return Marking text (display name) corresponding to the connection ID
   //!
   //! Looks up the marking text (display name) of an entity based on its connection ID.
   //! Returns an empty string if no matching entity is found.
   std::string markingTextFromConnectionId(const std::string& id);
   //! @}
 
   //! \brief Entity existence and property methods
   //! @{
 
   //! \brief Checks if an entity exists in the simulation
   //! \param entityName Name of the entity to check
   //! \return True if the entity exists, false otherwise
   //!
   //! Determines whether an entity with the specified name exists
   //! in the current simulation. This can be used to verify an entity
   //! before attempting to interact with it.
   bool entityExists(const std::string& entityName);
 
   //! \brief Gets all sensors for an entity
   //! \param entityName Name of the entity
   //! \return Vector of sensor names belonging to the entity
   //!
   //! Retrieves a list of all named published sensor objects for the
   //! specified entity. These sensors can be used for tracking, targeting,
   //! or other sensor-related operations.
   std::vector<std::string> sensorsForEntity(const std::string& entityName);
 
   //! \brief Gets the unique ID of a sensor
   //! \param hostId Unique ID of the host entity
   //! \param sensorName Name of the sensor
   //! \return Unique ID of the specified sensor
   //!
   //! Retrieves the unique identifier for a specific sensor on a host entity.
   //! This ID can be used for further sensor-related operations.
   makVrv::DtUniqueID sensorUniqueId(makVrv::DtUniqueID hostId, const std::string& sensorName);
   //! @}
 
   //! \brief Entity sensor utilities
   //! @{
 
   //! \brief Response types for targeting pod queries
   //!
   //! Enumeration of possible states a targeting pod can be in.
   enum TargetingPodResponse
   {
      NO_SENSOR,      //!< No suitable sensor found on the entity
      TRACK_LOCATION, //!< Sensor is tracking a location in space
      TRACK_TARGET    //!< Sensor is tracking another entity
   };
 
   //! \brief Gets targeting pod information for a specific sensor
   //! \param entityName Name of the entity that owns the targeting pod
   //! \param sensorId Unique ID of the specific sensor to query
   //! \param trackedLocation [out] Location being tracked (valid if response is TRACK_LOCATION)
   //! \param trackedTarget [out] Entity being tracked (valid if response is TRACK_TARGET)
   //! \return Status of the targeting pod (NO_SENSOR, TRACK_LOCATION, or TRACK_TARGET)
   //!
   //! Retrieves information about what a specific targeting pod sensor is currently tracking.
   //! Depending on the sensor's state, either trackedLocation or trackedTarget will be populated.
   TargetingPodResponse targetingPodInfo(const std::string& entityName, makVrv::DtUniqueID sensorId,
      DtVector& trackedLocation, makVrv::DtUniqueID& trackedTarget);
 
   //! \brief Gets targeting pod information using the first available gimbaled sensor
   //! \param entityName Name of the entity that owns the targeting pod
   //! \param trackedLocation [out] Location being tracked (valid if response is TRACK_LOCATION)
   //! \param trackedTarget [out] Entity being tracked (valid if response is TRACK_TARGET)
   //! \return Status of the targeting pod (NO_SENSOR, TRACK_LOCATION, or TRACK_TARGET)
   //!
   //! Retrieves information about what the entity's first gimbaled sensor is tracking.
   //! This is a convenience method when the specific sensor ID is not known.
   //! Depending on the sensor's state, either trackedLocation or trackedTarget will be populated.
   TargetingPodResponse targetingPodInfo(
      const std::string& entityName, DtVector& trackedLocation, makVrv::DtUniqueID& trackedTarget);
 
   //! \brief Gets the tracking mode of a sensor
   //! \param hostId Unique ID of the host entity
   //! \param sensorId Unique ID of the sensor
   //! \return String describing the tracking mode (e.g., "TRACK ENTITY", "TRACK LOCATION")
   //!
   //! Retrieves the current tracking mode of a sensor as a string.
   //! Common values include "TRACK ENTITY", "TRACK LOCATION", and others
   //! specific to the sensor type and configuration.
   std::string sensorTrackingMode(makVrv::DtUniqueID hostId, makVrv::DtUniqueID sensorId);
 
   //! \brief Gets the unique ID of a sensor's target entity
   //! \param hostId Unique ID of the host entity
   //! \param sensorId Unique ID of the sensor
   //! \return Unique ID of the entity being tracked by the sensor
   //!
   //! Retrieves the unique identifier of the entity that the sensor
   //! is currently tracking. Returns a null ID if the sensor is not
   //! tracking an entity or if it's tracking a location instead.
   makVrv::DtUniqueID sensorTargetUniqueId(makVrv::DtUniqueID hostId, makVrv::DtUniqueID sensorId);
 
   //! \brief Gets the location a sensor is targeting
   //! \param hostId Unique ID of the host entity
   //! \param sensorId Unique ID of the sensor
   //! \return Geocentric coordinates of the location being tracked
   //!
   //! Retrieves the geocentric coordinates of the location that
   //! the sensor is currently tracking. If the sensor is tracking
   //! an entity, this returns the current location of that entity.
   DtVector sensorTargetLocation(makVrv::DtUniqueID hostId, makVrv::DtUniqueID sensorId);
 
   //! \brief Gets the center of a sensor's view frustum
   //! \param hostId Unique ID of the host entity
   //! \param sensorId Unique ID of the sensor
   //! \return Geocentric coordinates of the frustum center
   //!
   //! Retrieves the geocentric coordinates of the center point of the
   //! sensor's view frustum. This represents the center of the sensor's
   //! field of view, which may differ from its target location.
   DtVector sensorFrustumCenter(makVrv::DtUniqueID hostId, makVrv::DtUniqueID sensorId);
 
   //! @}
 
   //! \brief Spatial calculation functions
   //! @{
 
   //! \brief Gets an entity's position and orientation
   //! \param id Unique ID of the entity
   //! \param position [out] Vector to receive entity's position
   //! \param orientation [out] Orientation values to receive entity's orientation
   //! \return True if the position and orientation were successfully retrieved
   //!
   //! Retrieves the current position and orientation of an entity.
   //! The position is returned in the local coordinate system, and the
   //! orientation is returned as Tait-Bryan angles (heading, pitch, roll).
   bool entityPositionAndOrientation(makVrv::DtUniqueID id, DtVector& position, DtTaitBryan& orientation);
 
   //! \brief Gets a sensor's orientation relative to its host
   //! \param hostId Unique ID of the host entity
   //! \param sensorId Unique ID of the sensor
   //! \param orientation [out] Orientation values to receive sensor's orientation
   //! \return True if the orientation was successfully retrieved
   //!
   //! Retrieves the current orientation of a sensor relative to its host entity.
   //! The orientation is returned as Tait-Bryan angles (heading, pitch, roll)
   //! in the reference frame of the host object.
   bool sensorRefOrientation(makVrv::DtUniqueID hostId, makVrv::DtUniqueID sensorId, DtTaitBryan& orientation);
 
   //! \brief Converts local coordinates to geodetic coordinates
   //! \param local Vector in local coordinate system
   //! \return Geodetic coordinates in degrees (latitude, longitude, altitude)
   //!
   //! Converts a position from the local coordinate system to geodetic coordinates.
   //! The result is expressed as degrees of latitude and longitude, and altitude in meters.
   DtVector localToGeodeticInDegrees(const DtVector& local);
 
   //! \brief Calculates a terrain intersection point
   //! \param localPosition Starting position in local coordinates
   //! \param x X component of the direction quaternion
   //! \param y Y component of the direction quaternion
   //! \param z Z component of the direction quaternion
   //! \param w W component of the direction quaternion
   //! \param intersectionPoint [out] Vector to receive intersection coordinates
   //! \return True if an intersection was found, false otherwise
   //!
   //! Calculates the intersection point between a ray and the terrain. The ray
   //! starts at localPosition and extends in the direction specified by the
   //! quaternion components (x, y, z, w). If an intersection is found, the
   //! coordinates are stored in intersectionPoint.
   bool getIntersectionPoint(
      const DtVector& localPosition, double x, double y, double z, double w, DtVector& intersectionPoint);
 
   //! \brief Sensor tracking modes
   //!
   //! Enumeration of the possible tracking modes for sensors.
   enum SensorTrackingMode
   {
      TrackEntity,  //!< Sensor is tracking an entity
      TrackLocation //!< Sensor is tracking a location
   };
 
   //! \brief Gets an entity's type information
   //! \param uniqueId Unique ID of the entity
   //! \return Entity type information
   //!
   //! Retrieves type information for the specified entity, including
   //! domain, kind, country, category, subcategory, and specific data.
   DtEntityType entityType(makVrv::DtUniqueID uniqueId);
 
   //! \brief Gets the entity resolver being used
   //! \return Pointer to the entity resolver
   //!
   //! Provides access to the entity resolver object used by this helper.
   //! The entity resolver maps between different entity representation systems.
   makVre::DtEntityResolver* entityResolver();
 
   //! \brief Signal emitted when an entity is removed
   //!
   //! This signal is emitted whenever an entity is removed from the simulation.
   //! Handlers can connect to this signal to perform cleanup or other operations
   //! when entities are removed.
   boost::signalslib::signal<void(makVrv::DtElementID entity)> signal_entityRemoved;
   //! @}
 
protected:
   //! \brief Slot called when elements are removed
   //! \param elements List of element IDs that were removed
   //!
   //! Internal handler that processes element removal notifications and
   //! emits the signal_entityRemoved signal for each removed entity.
   void slot_elementsRemoved(const makVrv::DtElementData::ElementIdList& elements);
 
protected:
   //! \brief Reference to the display engine
   //!
   //! Provides access to the 3D visualization and scene management system.
   makVrv::DtDe& myDe;
 
   //! \brief Type definition for string-to-ID mapping
   using StringToIdMap = std::map<std::string, makVrv::DtUniqueID>;
 
   //! \brief Mapping from marking text to unique IDs
   StringToIdMap myMarkingTextToUniqueIdMap;
 
   //! \brief Mapping from connection IDs to unique IDs
   StringToIdMap myConnectionIdToUniqueIdMap;
 
   //! \brief Type definition for string-to-string mapping
   using StringToStringMap = std::map<std::string, std::string>;
 
   //! \brief Mapping from marking text to connection IDs
   StringToStringMap myMarkingTextToConnectionIdMap;
 
   //! \brief Pointer to the entity resolver
   //!
   //! Used to translate between different entity identifier systems.
   makVre::DtEntityResolver* myEntityResolver;
 
   //! \brief Pointer to the terrain intersection calculator
   //!
   //! Used for ray-terrain intersection calculations.
   makVrv::DtIntersector* myIntersector;
};