vreGimbalController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreGimbalController.h
//! \ingroup vreVrfmodel
//! \brief Controller for sensor gimbal movement and targeting
//!
//! This file defines the DtVreGimbalController class which extends the base sensor
//! gimbal controller with VRE-specific functionality. It provides mechanisms for
//! controlling sensor gimbal movement, targeting, and laser designation.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include <vrfmodel/sensorGimbalController.h>
#include "vreVrfModel/vreSimComponent.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
 
namespace makVrf
{
class DtLaserDesignatorStateComponent;
}
 
namespace makVre
{
class DtVreGimbalControllerDescriptor;
 
//! \brief Type identifier for the VRE sensor gimbal controller component
const char DtVreGimbalControllerType[] = "vre-sensor-gimbal-controller";
 
//! \brief Controller for sensor gimbal movement and targeting
//!
//! DtVreGimbalController extends the base sensor gimbal controller with VRE-specific
//! functionality. It manages the rotation of sensor gimbals to aim sensors at targets,
//! handles laser designation, and provides mechanisms for object tracking. The controller
//! supports both joystick-controlled and AI-controlled gimbal movement.
class VREVRFMODEL_DLL DtVreGimbalController : public DtVreSimComponent<DtSensorGimbalController>
{
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 gimbal controller component with the specified parameters.
   DtVreGimbalController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the gimbal controller component.
   virtual ~DtVreGimbalController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreGimbalControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Calculates and sets port values based on function input
   //! \param functionGroup The function group identifier
   //! \param function The specific function name
   //! \param value The input value to process
   //! \param repeat Flag indicating whether the function should repeat
   //!
   //! Processes input from function ports (typically joystick inputs) and
   //! applies the appropriate transforms to control the gimbal movement.
   virtual void calcAndSetPortValues(
      const DtString& functionGroup, const DtString& function, double value, bool repeat) override;
 
   //! \brief Finds the world location that a sensor is aiming at
   //! \param location The geocentric location of the sensor
   //! \param orientation The orientation of the sensor
   //! \param aimingPoint Output parameter that will contain the aiming point if found
   //! \return True if an aiming point was successfully found, false otherwise
   //!
   //! Determines the world location that a sensor is currently aiming at,
   //! based on the sensor's location, orientation, and internal configuration.
   virtual bool findLocationOfSensorAiming(
      const DtVector& location, const DtTaitBryan& orientation, DtVector& aimingPoint) const override;
 
   //! \brief Chooses an appropriate laser designator object as the target to engage
   //! \return Pointer to the selected designator component, or NULL if no valid target found
   //!
   //! Searches for and selects an appropriate laser designator object to engage as
   //! a target. Uses targetDesignatorValid() to check if each potential target is valid.
   //! This method enables sensors to track laser-designated targets.
   virtual const makVrf::DtLaserDesignatorStateComponent* lookupDesignator() const;
 
   //! \brief Processes a message to set the gimbal aim direction
   //! \param msg Pointer to the simulation message containing aim parameters
   //!
   //! Handles messages requesting to set the aiming direction of the gimbal.
   //! Extracts the target aiming information from the message and applies it
   //! to the gimbal controller.
   virtual void processSetAimGimbal(DtSimMessage* msg) override;
 
   //! \brief Updates the current laser designator target location
   //!
   //! Refreshes the stored location of the current laser designator target.
   //! This keeps the gimbal controller's understanding of the target position
   //! up to date for accurate tracking.
   virtual void updateDesignatorLocation();
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Overridden to allow object tracking while in joystick mode. This method
   //! is called each simulation frame to update the gimbal orientation based
   //! on current tracking targets and input controls.
   virtual void tick() override;
 
   //! \brief Determines the target point based on orientation and maximum laser range
   //! \param orientation The orientation to calculate the target point from
   //! \param location Output parameter that will contain the target point if found
   //! \return True if a target point was successfully found, false otherwise
   //!
   //! Overridden to respect the maximum range of the laser when determining target points.
   //! Calculates the point in world space that corresponds to the given orientation
   //! and the configured maximum laser range.
   virtual bool targetPoint(const DtTaitBryan& orientation, DtVector& location) const override;
 
protected:
   //! \brief Aims the sensor at a specified world location
   //! \param worldLocation The geocentric world location to aim at
   //!
   //! Attempts to adjust the gimbal orientation so that the sensor is aimed
   //! at the specified world location. Calculates the appropriate azimuth and
   //! elevation angles to achieve the desired aiming point.
   virtual void aimSensorAtPoint(const DtVector& worldLocation) override;
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreGimbalController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreGimbalController(const DtVreGimbalController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtVreGimbalController& operator=(const DtVreGimbalController& orig);
 
public:
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param object The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param compDescriptor 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* object, DtSimulationServices* simManager,
      DtComponentDescriptor* compDescriptor, DtReaderWriterRegistry* parentRegistry);
 
protected:
   //! \brief Pointer to the gimbal controller descriptor
   //!
   //! Contains the configuration parameters for this gimbal controller component.
   DtVreGimbalControllerDescriptor* myVreGimbalDescriptor;
 
   //! \brief Gets the current terrain check distance
   //! \return The current distance to check for terrain intersections
   //!
   //! Returns the current distance value used for terrain intersection checks.
   //! Used to handle terrain loading latency issues by progressively checking
   //! at different distances.
   double checkDistance() const;
 
   //! \brief Increases the terrain check distance
   //!
   //! Increments the terrain check distance when a previous check fails.
   //! Helps handle terrain loading latency by progressively increasing the
   //! check distance until terrain is found or the maximum is reached.
   void increaseCheckDistance() const;
 
   //! \brief Resets the terrain check distance to the minimum value
   //!
   //! Resets the terrain check distance back to the minimum configured value.
   //! Called when starting a new series of terrain checks.
   void resetCheckDistance() const;
 
   //! \brief Minimum distance for terrain intersection checks
   //!
   //! The starting (minimum) distance used for terrain intersection checks.
   //! This is the initial value used when resetting the check distance.
   double myMinCheckDistance;
 
   //! \brief Current distance for terrain intersection checks
   //!
   //! The current distance being used for terrain intersection checks.
   //! May be modified during runtime as checks are performed.
   mutable double myCurrentCheckDistance;
 
   //! \brief Maximum distance for terrain intersection checks
   //!
   //! The maximum distance to use for terrain intersection checks.
   //! Once this value is reached, no further increases will occur.
   double myMaxCheckDistance;
 
   //! \brief Laser code for designation
   //!
   //! The code used for laser designation. This helps identify specific
   //! laser designators when multiple are present in the simulation.
   int myLaserCode;
 
   //! \brief Flag indicating whether continuous tracking is enabled
   //!
   //! When true, indicates that the gimbal should continuously track
   //! the target, even in joystick control mode.
   bool myContinuousTrack;
};
 
} // namespace makVre