rfxElevationMessage.h

Go to the documentation of this file.

// ******************************************************************************
// ** Copyright (c) 2025 MAK Technologies
// ** All rights reserved.
// ******************************************************************************
 
 
//! \file rfxElevationMessage.h
//! \brief Defines the request and response messages for terrain elevation queries
//! \ingroup vreRadarFxShared
//!
//! This file contains message classes for requesting terrain elevation data
//! at specific locations and receiving the elevation results
 
 
#pragma once
 
#include "export.h"
#include "rfxMessage.h"
 
#include <matrix/vlVector.h>
 
#include <string>
 
namespace makRadarFx
{
 
//! \brief Request message for terrain elevation data
//!
//! This message requests the elevation at a specific target location using sensors
//! on a specified platform or from the ownship location. The request supports multiple
//! methods of specifying both the sensor position (ownship) and the target position,
//! including using the observer's current view, specifying an entity by ID, or using
//! absolute coordinates. If line of sight is not available from the sensing platform
//! to the target location, the corresponding response will contain an error.
class RFX_DLL_SHARED DtElevationRequest : public DtBaseMessage
{
public:
   //! \brief Default constructor
   //!
   //! Initializes a new elevation request message with default settings
   DtElevationRequest();
 
   //! \brief Virtual destructor
   virtual ~DtElevationRequest();
 
   //! \brief Uses the current observer's position for the sensor location
   //!
   //! When called, this function configures the request to use the current observer's
   //! position and orientation for the sensor placement. The client does not need to
   //! set an ownship location if using this method to position the sensor.
   virtual void useObserverAsHost();
 
   //! \brief Sets an absolute position for the sensor location
   //! \param location Vector containing the sensor position (latitude, longitude, altitude)
   //!
   //! If the ownship is not hosted in the simulation system, this method allows
   //! explicit specification of the sensor position for the elevation test.
   virtual void setOwnshipLocation(DtVector location);
 
   //! \brief Gets the absolute sensor position
   //! \return Vector containing the sensor position (latitude, longitude, altitude)
   //!
   //! Returns the currently set absolute sensor position
   virtual DtVector ownshipLocation();
 
   //! \brief Sets an entity ID to use for the sensor position
   //! \param name String identifier of the entity to use as the sensor platform
   //!
   //! If the sensor platform is hosted by the simulation system, this method allows
   //! specification of the entity by its global simulation name or ID.
   virtual void setOwnshipEntityId(const std::string& name);
 
   //! \brief Gets the entity ID used for the sensor position
   //! \return String identifier of the entity used as the sensor platform
   virtual std::string ownshipEntityId();
 
   //! \name Sensor Placement Mode Queries
   //! @{
   //! \brief Methods to determine how the sensor is being positioned
 
   //! \brief Checks if using the observer position for the sensor
   //! \return True if the observer is being used as the sensor host
   virtual bool isUsingObserverAsHost();
 
   //! \brief Checks if using an entity as the sensor platform
   //! \return True if an entity ID is being used for the sensor host
   virtual bool isUsingEntityAsHost();
 
   //! \brief Checks if using an absolute position for the sensor
   //! \return True if absolute coordinates are being used for the sensor position
   virtual bool isUsingAbsoluteLocation();
   //! @}
 
   //! \brief Uses the current observer's view direction for the target position
   //!
   //! When called, this function configures the request to use the current observer's
   //! view direction to determine the target position for the elevation query.
   virtual void useObserverForTarget();
 
   //! \brief Sets an entity ID to use for the target position
   //! \param name String identifier of the entity to use as the target
   //!
   //! Specifies an entity by its global simulation name or ID to use as the
   //! target location for the elevation query.
   virtual void setTargetEntityId(const std::string& name);
 
   //! \brief Gets the entity ID used for the target position
   //! \return String identifier of the entity used as the target
   virtual std::string targetEntityId();
 
   //! \brief Sets an absolute position for the target location
   //! \param location Vector containing the target position (latitude, longitude, altitude)
   //!
   //! Specifies the absolute coordinates of the target location for the elevation query.
   //! Location format is latitude/longitude/altitude (in degrees/meters).
   //! The altitude component is not required and will be determined by the query.
   virtual void setTargetLocation(DtVector location);
 
   //! \brief Gets the absolute target position
   //! \return Vector containing the target position (latitude, longitude, altitude)
   virtual DtVector targetLocation();
 
   //! \name Target Placement Mode Queries
   //! @{
   //! \brief Methods to determine how the target is being positioned
 
   //! \brief Checks if using the observer view for the target position
   //! \return True if the observer view is being used to determine the target
   virtual bool isUsingObserverForTarget();
 
   //! \brief Checks if using an entity as the target
   //! \return True if an entity ID is being used for the target
   virtual bool isUsingEntityForTarget();
 
   //! \brief Checks if using an absolute position for the target
   //! \return True if absolute coordinates are being used for the target position
   virtual bool isUsingLocationForTarget();
   //! @}
 
 
   //! \brief size of the message
   virtual int messageSize();
   //! \brief decode a message.  Used by the factory
   static DtBaseMessage* decode(unsigned char* buffer, int length);
   //! \brief clone a message.  Caller of function is responsible managing this memory
   virtual DtBaseMessage* clone();
 
protected:
   //! \brief Serializes the message data to a stream writer
   //! \param writer Reference to the stream writer to write the data to
   virtual void serialize(DtStreamWriter& writer);
 
   //! \brief Deserializes message data from a stream reader
   //! \param reader Reference to the stream reader to read the data from
   virtual void deserialize(DtStreamReader& reader);
 
   //! \brief Flag indicating if using observer as the sensor host
   bool myUseObserverAsHost;
 
   //! \brief Flag indicating if using an entity as the sensor host
   bool myUseEntityAsHost;
 
   //! \brief Flag indicating if using absolute coordinates for the sensor position
   bool myUseAbsoluteOwnship;
 
   //! \brief Flag indicating if using observer view for the target
   bool myUseObserverForTarget;
 
   //! \brief Flag indicating if using an entity as the target
   bool myUseEntityAsTarget;
 
   //! \brief Flag indicating if using absolute coordinates for the target position
   bool myUseAbsoluteTarget;
 
   //! \brief Name/ID of the entity to use as the sensor host
   std::string myOwnshipName;
 
   //! \brief Name/ID of the entity to use as the target
   std::string myTargetName;
 
   //! \brief Absolute coordinates for the sensor position
   DtVector myOwnshipLocation;
 
   //! \brief Absolute coordinates for the target position
   DtVector myTargetLocation;
};
 
//! \brief Response message containing terrain elevation data
//!
//! This message contains the response to an elevation request, providing
//! the terrain elevation at the requested location and any error information
//! if the elevation could not be determined. The response may include an error
//! if there is no line of sight from the sensor position to the target location.
class RFX_DLL_SHARED DtElevationResponse : public DtBaseMessage
{
public:
   //! \brief Error codes for elevation responses
   enum DtElevationError
   {
      ELEVATION_NO_ERROR,       //!< No error, elevation is valid
      ELEVATION_ERROR_OCCLUDED, //!< Error due to occlusion (no line of sight)
      ELEVATION_ERROR_OTHER     //!< Other unspecified error
   };
 
   //! \brief Default constructor
   //!
   //! Initializes a new elevation response message with default settings
   DtElevationResponse();
 
   //! \brief Virtual destructor
   virtual ~DtElevationResponse();
 
   //! \brief Sets the elevation result
   //! \param elevation The elevation value in meters
   //!
   //! Sets the elevation at the requested location. A value of NaN indicates
   //! that the request could not be completed due to line of sight being
   //! blocked from the sensing platform to the requested target or another error.
   virtual void setElevation(float elevation);
 
   //! \brief Gets the elevation result
   //! \return The elevation value in meters, or NaN if unavailable
   //!
   //! Returns the terrain elevation at the requested location.
   virtual float elevation();
 
   //! \brief Sets the error code
   //! \param error The error code to set
   //!
   //! Sets the error status for this elevation response. Use ELEVATION_NO_ERROR
   //! if the elevation value is valid.
   virtual void setError(DtElevationError error);
 
   //! \brief Gets the error code
   //! \return The current error code
   //!
   //! Returns the error status for this elevation response.
   virtual DtElevationError error();
 
   //! \brief size of the message
   virtual int messageSize();
   //! \brief decode a message.  Used by the factory
   static DtBaseMessage* decode(unsigned char* buffer, int length);
   //! \brief clone a message.  Caller of function is responsible managing this memory
   virtual DtBaseMessage* clone();
 
protected:
   //! \brief Serializes the message data to a stream writer
   //! \param writer Reference to the stream writer to write the data to
   virtual void serialize(DtStreamWriter& writer);
 
   //! \brief Deserializes message data from a stream reader
   //! \param reader Reference to the stream reader to read the data from
   virtual void deserialize(DtStreamReader& reader);
 
   //! \brief The elevation value in meters
   float myElevation;
 
   //! \brief The error code for this response
   DtElevationError myError;
};
} // namespace makRadarFx