vreSimpleRadarObjectSensor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreSimpleRadarObjectSensor.h
//! \ingroup vreVrfmodel
//! \brief Sensor for radar detection with target tracking capabilities
//!
//! This file defines the DtVreSimpleRadarObjectSensor class which extends
//! DtVreRadarObjectSensor to provide target tracking and designation capabilities
//! for air targets. It supports both TWS (Track While Scan) and STT (Single Target Track)
//! modes and manages prioritized target lists.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreRadarObjectSensor.h"
#include "vreVrfobjcore/vreSimpleRadarObjectSensorPSR.h"
#include <unordered_map>
 
class DtRwRadarContactInfo;
 
namespace makVre
{
 
//! \brief Type identifier for the VRE simple radar object sensor component
const char DtVreSimpleRadarObjectSensorType[] = "vre-simple-radar-object-sensor";
 
//! \brief Sensor for radar detection with target tracking and designation capabilities
//!
//! DtVreSimpleRadarObjectSensor extends the base radar object sensor to provide
//! target tracking and designation capabilities specifically for air targets. It
//! manages the radar antenna state for tracking, supports different radar modes
//! (TWS - Track While Scan and STT - Single Target Track), and maintains prioritized
//! lists of designated targets.
//!
//! The sensor provides information about detected targets including their position,
//! velocity, and classification, and supports selecting specific targets for tracking
//! and weapons guidance.
class VREVRFMODEL_DLL DtVreSimpleRadarObjectSensor : public DtVreRadarObjectSensor
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreSimpleRadarObjectSensor();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreSimpleRadarObjectSensor(const DtVreSimpleRadarObjectSensor& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtVreSimpleRadarObjectSensor& operator=(const DtVreSimpleRadarObjectSensor& orig);
 
public:
   // using DtSignatureObjectSensor::tick;
 
   //! \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 simple radar object sensor component with the specified parameters.
   DtVreSimpleRadarObjectSensor(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the simple radar object sensor component.
   virtual ~DtVreSimpleRadarObjectSensor() override;
 
   //! \brief Initializes the radar sensor component
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs component initialization, including setting up the radar sensor
   //! parameters and process state repository. Called during component creation.
   virtual bool init() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreSimpleRadarObjectSensorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Updates the radar sensor state each simulation frame
   //!
   //! Updates the antenna state for target tracking and calls the base class
   //! tick method to process standard radar operations. Manages target tracking,
   //! designation, and updates radar contact information based on current
   //! sensor mode and detected objects.
   virtual void tick() override;
 
   //! \brief Determines if an object should be detected by the radar
   //! \param object Reference to the object being evaluated for detection
   //! \param contactInfo Output parameter to receive contact information if detected
   //! \return True if the object is detected, false otherwise
   //!
   //! Evaluates whether the specified object should be detected by the radar sensor
   //! based on range, radar cross-section, and other factors. If detected, populates
   //! the contactInfo parameter with information about the contact.
   virtual bool detectObject(DtSimObjectReference object, DtRwSensorContactInfo* contactInfo) override;
 
   //! \brief Determines if an already detected object should remain detected
   //! \param object Reference to the previously detected object
   //! \param contactInfo Output parameter with contact information to update
   //! \param contactInfoModified Output parameter indicating if contactInfo was modified
   //! \return Result indicating if detection should continue, be removed, or remain unchanged
   //!
   //! Evaluates whether a previously detected object should continue to be detected
   //! by the radar sensor. Updates contact information if the object remains detected
   //! and sets contactInfoModified to true if changes were made.
   virtual ContinueDetectingResult continueDetectingObject(
      DtSimObjectReference object, DtRwSensorContactInfo* contactInfo, bool& contactInfoModified) 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:
   //      static DtReaderWriter* provideDesignatedTarget(void* c);
 
   //! \brief Updates the radar antenna position and state
   //!
   //! Updates the radar antenna position and state based on the current tracking
   //! mode and target information. Manages antenna rotation in scanning modes and
   //! fixed pointing in single-target tracking mode.
   void updateAntennaState();
   //! \brief Increments the radar scan bar counter
   //!
   //! Increments the counter that tracks the current scan bar position
   //! in the radar scanning pattern. Used to simulate radar scan patterns
   //! across elevation bars.
   void incrementBar();
 
   //! \brief Determines if a tracked target should be detected based on radar modes
   //! \param trackId The track identifier of the target to check
   //! \return True if the target should be detected in the current radar mode
   //!
   //! Evaluates whether a target with the specified track ID should be detected
   //! based on the current radar mode (e.g., in STT mode, only the designated
   //! target should be detected).
   bool targetShouldBeDetected(int trackId);
 
   //! \brief Calculates the azimuth angle to a target
   //! \param target Reference to the target object
   //! \return Azimuth angle to the target in degrees
   //!
   //! Calculates the azimuth angle (horizontal angle) from the radar to the
   //! specified target object, in degrees. Used for determining if the target
   //! is within the current radar scan sector.
   double azimuthToTargetInDegrees(DtSimObjectReference target);
   //! \brief Calculates the elevation angle to a target
   //! \param target Reference to the target object
   //! \return Elevation angle to the target in degrees
   //!
   //! Calculates the elevation angle (vertical angle) from the radar to the
   //! specified target object, in degrees. Used for determining if the target
   //! is within the current radar scan bar.
   double elevationToTargetInDegrees(DtSimObjectReference target);
 
   //! \brief Updates the contact information for a detected target
   //! \param target Reference to the target object
   //! \param targetInfo Pointer to the contact information to update
   //! \return True if the contact information was modified, false otherwise
   //!
   //! Updates the radar contact information for a detected target with current
   //! data such as position, velocity, and track quality. Returns true if any
   //! information was changed.
   bool updateContactData(DtSimObjectReference target, DtRwRadarContactInfo* targetInfo);
 
   //! \brief Provides information about the currently designated target
   //! \return Reader/writer containing information about the designated target
   //!
   //! Implements the base class method to provide information about the currently
   //! designated target (highest priority target in the designated target list).
   //! Used by other components to identify which target the radar is currently
   //! prioritizing for tracking or weapons guidance.
   virtual DtReaderWriter* processProvideDesignatedTarget() override;
 
   //! \brief Gets the default process state repository type
   //! \return String identifying the default PSR type (DtVreSimpleRadarObjectSensorPSRType)
   //!
   //! Returns the default process state repository type for this component.
   //! Overrides the base class method to provide the specialized PSR type for
   //! the simple radar object sensor.
   virtual const char* defaultPSRType() const override;
 
   //! \brief Gets the track ID for a target entity
   //! \param id UUID of the target entity
   //! \return Track ID assigned to the entity
   //!
   //! Retrieves or assigns a track ID for the entity with the specified UUID.
   //! Track IDs are unique identifiers used to reference detected targets in
   //! the radar system.
   virtual int trackID(const DtUUID& id);
   //! \brief Gets the entity UUID corresponding to a track ID
   //! \param trackId The track ID to look up
   //! \return Reference to the UUID for the specified track ID
   //!
   //! Retrieves the entity UUID associated with the specified track ID.
   //! This performs the reverse lookup of trackID(), converting a radar track
   //! identifier back to the corresponding entity UUID.
   virtual const DtUUID& uuidFromTrackId(int trackId);
 
   //! \brief Determines a display label for an entity based on its type
   //! \param DtEntityType Entity type to get a label for
   //! \return String label to display for the entity type
   //!
   //! Creates a human-readable label for an entity based on its type code.
   //! Used to generate display names for radar contacts in the user interface.
   std::string entityLabelFromType(const DtEntityType&);
 
   //! \brief Sets the list of designated targets for the radar
   //! \param trackId Vector of track IDs to designate, in priority order
   //!
   //! Sets the designated targets list and updates the emitter system's track targets.
   //! The order of track IDs in the vector represents their priority, with the first
   //! element being the highest priority target. Overrides the base class method.
   virtual void setDesignatedTargets(const std::vector<int>& trackId) override;
 
   //! \brief Clears all designated targets from the radar
   //!
   //! Clears the designated targets list and the emitter system's track targets.
   //! This removes all current target designations, restoring the radar to a
   //! standard search/track state. Overrides the base class method.
   virtual void clearDesignatedTargets() override;
 
   //! \brief Gets the priority of a designated target
   //! \param trackId The track ID to check for priority
   //! \return The target's priority (1-based, with 1 being highest priority) or -1 if not designated
   //!
   //! Returns the target's position in the designated targets list, where 1 represents
   //! the highest priority target. If the specified track ID is not in the designated
   //! targets list, returns -1 to indicate it is not designated.
   int targetPriority(int trackId) const;
 
   //! \brief Checks if a target is in the designated targets list
   //! \param trackId The track ID to check
   //! \return True if the target is designated, false otherwise
   //!
   //! Determines whether the specified track ID is present in the designated
   //! targets list. Returns true if the target is designated, false otherwise.
   bool isTargetDesignated(int trackId) const;
 
   //! \brief Gets the highest priority designated target's track ID
   //! \return The Next To Shoot (NTS) target's track ID, or -1 if no targets are designated
   //!
   //! Returns the track ID of the first target in the designated targets list,
   //! which represents the Next To Shoot (NTS) target with highest priority.
   //! This is effectively the only designated target in STT (Single Target Track) mode.
   //! Returns -1 if the designated targets list is empty.
   int nextToShootTarget() const;
 
   //! \brief Checks if the radar is in Single Track Target mode
   //! \return True if in STT mode, false otherwise
   //!
   //! Determines whether the radar is currently in STT (Single Track Target) mode.
   //! In this mode, only the designated target (as returned by nextToShootTarget())
   //! should be tracked. This contrasts with TWS (Track While Scan) mode where
   //! multiple targets can be tracked simultaneously.
   bool singleTrackTargetMode() const;
 
   //! \brief Cache of entity labels by entity type string
   //!
   //! Stores previously looked up entity labels indexed by entity type string.
   //! Used to avoid repeating the entity label lookup for commonly encountered
   //! entity types.
   std::unordered_map<std::string, DtRwString> myKnownEntityLabels;
 
   //! \brief Map of detection states indexed by track ID
   //!
   //! Tracks the detection state of each target by its track ID. The boolean value
   //! indicates whether the target is currently detected (true) or not (false).
   //! Used to manage continuity of detection between simulation frames.
   std::unordered_map<int, bool> myTargetDetectionState;
 
   //! \brief Pointer to the radar sensor's process state repository
   //!
   //! Contains the persistent state information for the radar sensor,
   //! including tracking settings, antenna position, and designated targets.
   DtVreSimpleRadarObjectSensorPSR* myVreSimpleRadarObjectSensorPsr;
};
 
} // namespace makVre