Objects.h

Go to the documentation of this file.

/* © 1998 JRM Technologies, Inc.*/



/***********************************
Copyright JRM Enterprises, Inc. 1998
All rights reserved.

This code is the intellectual property of JRM Enterprises, Inc.
It may not be used or released as source or compiled binary form
without the prior written consent of JRM Enterprises, Inc.
***********************************/


#ifndef OBJECTS_H_
#define OBJECTS_H_

#include "JRMlibrary.h"
#include "Ellipsoid.h"

#include "SigSimDefines.h"
#include "SigSimStructs.h"

#include "particles.h"
#include "Radar.h"


#if SIGSIM_PRODUCT == SIGSIM3A
//#include "polygons.h"
//#include "GFE-NRT.h"
#include "Sonar.h"
#include "RFsig.h"
#endif


#include "sigsim.h"
#include "sigsimDLLstub.h"


#ifdef __cplusplus
extern "C"
{
#endif
   
    /* ------------ DEFINITIONS, ENUMERANTS, and DATA STRUCTURES ------------------ */

    typedef enum
    {
        TERRAIN,
        AIRCRAFT,
        GROUND_VEHICLE,
        WATERSURFACE,
        UNDERWATER,
        NONENTITY
    } OBJECT_TYPE;

    typedef struct
    {
        jrmbool active; 
      double time_activated;
        double thrust;        // [kg/hr] engine thrust
    } OBJECT_STATE;        // stub

    typedef struct
    {
        VECTOR Rview;   // unit vector tangent to refracted path (at sensor location)  to ID [unitless cosines, in sensor-local (North, East, Down) system]
        VECTOR Rtarget; // Orientation of path away from target in target local NED system. [unitless cosines]
        double Range;   // Path length [m]
        double Rdot; // rate of change of Refracted LOS path length [m/s].
    } Rpath;

    typedef struct 
    {
        char imagefile[SIGSIM_STRING_SIZE];
        double Rmin, Rave, Rmax; // [W/cm2] image emittance
      double ax, bx;          // [um]  image waveband
    } OBJECT_SIDE_VIEW;

   typedef struct
   {
      OBJECT_SIDE_VIEW front, back, left, right, up, down;
   }  OBJECT_VIEWS;

    typedef struct
    {
        char object_id[SIGSIM_STRING_SIZE];
        char object_subdirectory[SIGSIM_STRING_SIZE];
        OBJECT_TYPE object_type;       
        OBJECT_STATE state;

        int ntracks;                   // Number of TRACKS in track array
        TRACK *track;                     // Expected trajectory        
        GEODETIC_LOCATION geod_loc;          // Position of origin of local FRD system
        GEOCENTRIC_LOCATION geoc_loc;        // Position of origin of local FRD system
        EULERzyx FRD_orientation;            // Relates object body FRD to instantaneous local NED.
        VECTOR ned_linear_velocity;          // [m/s] Current linear velocity
        VECTOR ned_linear_acceleration;         // [m/s2] Curent linear acceleration
        VECTOR ned_angular_velocity;         // [rad/s] Current angular velocity. Magnitude gives speed clockwise about direction
        VECTOR ned_angular_acceleration;     // [rad/s2] Current angular acceleration. Magnitude gives accel clockwise about direction

        double length, width, height;        // [m] calculated
        long nmatls;                   // number of materials in the mp_table array
        MATL_PROP_TABLE *mp_table;           // array of material property data (BRDF and areal RCS)
      OBJECT_VIEWS *view;                 // legacy SigSimC-only option for representing object matclass

#ifdef _POLYGONS_H_
        char *geometryfile;                  // Geometry file (e.g. OpenFlight)
      POLY_ARRAY *geometry;               // Loaded geometry from geometry file (if any)
#endif
#ifdef _CTDR_CPDR_H_
        SPIRITS_TABLE *spirits_table;        // SPIRITS surface temp
        PLUME_FLOWFIELD *spf_table;          // SPF plume flowfield
        PLUME_RADIANCE_MAP *spurc_table;     // SPURC plume radiance projection LUT
      USCSET *uscset;                     // JRM Universal Scatter Center set 
        SMOKE_PROJECTION_MAP *combic_table;     // holds smoke cloud projection for given FOV
        POLY_ARRAY *muses_table;          // Muses surface temp
#endif
#ifdef _GFE_NRT_
      SPIRITS_PLUMEFIT *pfit;             // Spirits plume fit data
      MSIC_PS_DATASPEC *msic;             // MSIC-format Point Source Spectral Radiance Datacube
#endif
#ifdef _SIGSIM_RADAR_H_
        SCATTER_TABLE *scat_table;           // scatter center table for all the sensor center frequencies to be played
        SCATTER_VECTOR_TABLE *scat_vector_table;// scatter center table for all the sensor center frequencies to be played
        RCS_TABLE *rcs_table;             // holder for polarized RCS 2D LUT
      double rcs_sigma;                // Default RCS [1]
        OLD_RCS_TABLE *old_rcs_table;         
        char rcs_file[SIGSIM_STRING_SIZE];      // Radar Cross section file
      RF_JAMMER *rfjammer;             // RF Jammer
      RF_DECOY *rfdecoy;                  // RF Chaff/decoy 
#endif
#ifdef _SIGSIM_SONAR_H_
      TARGET *target;                     // Sonar Target Properties
#endif
#ifdef _RFSIG_H_
      DATALINK_PARTICIPANT *datalink;        // Datalink
#endif
#ifdef _PARTICLES_H_
      PARTICLEINPUT *pinput;              // Particle System Input
      PARTICLESYSTEM *psystem;            // Particle System Parameters (derived from pinput)
#endif

    } OBJECT;


   // InitializeObject sets all object parameters to 0 or null. It does not free any existing memory.
    // Inputs :   object = pointer to OBJECT
    // Returns:   SIGSIM_FUNCTION_FAILURE if object is NULL,
    //         SIGSIM_SUCCESS upon successful completion.
   SIGSIM_API int InitializeObject(OBJECT *object);


    // AllocateObjects allocates (but does not fill) an array of OBJECTs of length nobjects.
    // Inputs : nobjects = number of OBJECTs to be allocated.
    // Outputs: Object = Pointer to array of OBJECTs to be allocated.
    //         ms_poly_array and rcs_table will be NULL by default.
    // Returns: SIGSIM_MEMORY_ALLOCATION_ERROR if Object array already allocated or otherwise cannot be allocated.
    //         SIGSIM_SUCCESS on successful completion.  
    SIGSIM_API int AllocateObjects(int nobjects, OBJECT **Object);   // Allocates general array of objects


    // Free_Objects frees the memory allocated to an array of OBJECTs.
    // Inputs :   object = pointer to array of OBJECTs
    //         nobjects = size of object array
    // Returns:   SIGSIM_FUNCTION_FAILURE if object array is already NULL,
    //         SIGSIM_SUCCESS upon successful completion.
    SIGSIM_API int Free_Objects(OBJECT **object, int nobjects);

    // Free_Object_Arrays frees the memory allocated to the arrays within an array of OBJECTs,
    // but not that associated with the object array itself.
    // Inputs :   object = array of OBJECTs
    //         nobjects = size of object array
    // Returns:   SIGSIM_FUNCTION_FAILURE if object array is already NULL,
    //         SIGSIM_SUCCESS upon successful completion.
    SIGSIM_API int Free_Object_Arrays(OBJECT *object, int nobjects);

    // ---------- State Updates -------------

    // UpdateObjectKinematics() is intended to update the position and FOV for this object by indexing into the proper track record based on the simtime.
    // INPUTS : sens points to object with one or more track records filled in.
    //         E defines the Earth ellipsoid for geodetic to geocentric conversion
    //         simtime is the simulation time in seconds.
    // OUTPUTS: object->{geoc_loc, geod_loc} corresponding to simtime (from track records)
    //         object->{ned_linear_velocity, ned_angular_velocity, ned_linear_acceleration, ned_angular_acceleration} corresponding to simtime (from track records).
    SIGSIM_API int   UpdateObjectKinematics(OBJECT *object, ellipsoid E, double simtime); 

    // ObjectThermalSpinUp() forms nodal mesh for object matl systems and plays a time-step update to initialize them.
    SIGSIM_API int   ObjectThermalSpinUp(OBJECT *object, double spinupPeriod, METIN *metin);

    /* ----------------------- PROJECTIONS AND INTERSECTIONS ----------------------- */

    SIGSIM_API int GetBackgroundHits(ellipsoid E, OBJECT obj, VECTOR Rtarget, double delta, int ngeoC, VECTOR *TNED, GEOCENTRIC_LOCATION *geoC);
    SIGSIM_API int KLUDGE_SensorTransverseVecsInObjectNED(ellipsoid E, SENSOR sens, OBJECT obj, VECTOR RtargetNED, VECTOR *right, VECTOR *down);
    SIGSIM_API int KLUDGE_SensorTransverseVecsInObjectNED_P2P(ellipsoid E, FOV sens, GEOCENTRIC_LOCATION obj, VECTOR RtargetNED, VECTOR *right, VECTOR *down);
    SIGSIM_API int TargetTransverseDimensions(VECTOR right, VECTOR down, int nvecs, VECTOR *corner, double *horizontal, double *vertical);

    /* -------------------- RADIANCE CALCULATION -------------------------- */
    SIGSIM_API double computerad(OBJECT *objectin, SENSOR *sens, VECTOR direction);

    // SetMinMaxObjectRadiances() can be used to set the OBJECT structure minimum and maximum radiances and passbands for use with the UseRadImage switch,
    // but note that all passbands will be the SAME, all maximum radiances will be the SAME, and all minimum radiances will be the SAME, for all faces of the object cube.
    // For specification of different parameters for each face, the user is expected to either use GetScenario, or use a call to rademit_approx as follows:
    // Given a passband ax and bx [in microns], and a face temperature T [in degK], the associated radiance is given by:
    //      double itd;
    //      rad = rademit_approx(ax, bx, T, 10, &itd);
    // This should be done for Tmin and Tmax, for each face.
    //
    // Inputs: object = pointer to OBJECT whose passband and radiances are to be calculated.
    //         bmpax = wavelength [um] of start of passband associated with the image.
    //         bmpbx = wavelength [um] of end   of passband associated with the image.
    //         bmptlo = temperature [degC] of start of image dynamic range.
    //         bmpthi = temperature [degC] of end   of image dynamic range.
    // Outputs:   Passband starting wavelengths object->{axf,axb,axl,axr,axu,axd}.
    //         Passband ending     wavelengths object->{bxf,bxb,bxl,bxr,bxu,bxd}.
    //         Minimum radiances object->{rminf, rminb, rminl, rminr, rminu, rmind}.
    //         Maximum radiances object->{rmaxf, rmaxb, rmaxl, rmaxr, rmaxu, rmaxd}.
    // Returns:   SIGSIM_SUCCESS upon successful completion.
    SIGSIM_API int SetMinMaxObjectRadiances(OBJECT *object, double bmpax, double bmpbx, double bmptlo, double bmpthi);

    // FillObjectRadianceFromImages() fills OBJECT radiance images.
   // If object->view->xxx.imageFile(s) exist, they will be read and converted
    // to radiances stored in object->view->xxx.Rave. Here 'xxx' and 'x' denote a particular face {u,d,r,l,f,b}.
    // Inputs :   sigsim_data_dir = string containing the name of the main data directory.
    //         object = pointer to OBJECT whose radiance tables are to be filled.
    // Uses:   object->{front,back,left,right,up,down}_rad_file.
    //         object->{rmaxf,rmaxb,rmaxl,rmaxr,rmaxu,rmaxd}
    //         object->{rminf,rminb,rminl,rminr,rminu,rmind}
    // Outputs: object->{radf,radb,radl,radr,radu,radd}
    // Returns: SIGSIM_FILE_NOT_FOUND*(-1) if sigsim_data_dir/object/bmp/object->{front,back,left,right,up,down}_rad_file is not found or can't be read.
    //         SIGSIM_SUCCESS upon successful completion.
   SIGSIM_API int FillObjectRadianceFromImages(char *sigsim_data_dir, OBJECT *object);

    SIGSIM_API double ObjectRadianceFromImage(OBJECT *object, SENSOR *sens, VECTOR NED);


#ifdef _SIGSIM_RADAR_H_
   /* ------------- RADAR --------------------- */

    // ReturnScatterAspect() gets the most relevant XPatch scatter center table for that target az/el aspect and frequency.
    // Returns FALSE if no appropriate data exists. 
    // Not required if CalcRFReflectedPower is to be called, but useful if one is to pass this info to 3rd party codes.
    // "el" [deg] measured from FR plane toward D, 
    // "az" [deg] measured on FR plane counter-clockwise about D from F
    // "freq" [Hz]
    //SIGSIM_API jrmbool ReturnScatterAspect(OBJECT *object, double az, double el, double freq, SCATTER_ASPECT *sa);
   SIGSIM_API jrmbool ReturnScatterVectorAspect(OBJECT *object, double az, double el, double freq, SCATTER_VECTOR_ASPECT *aspect);
    SIGSIM_API jrmbool ReturnScatterAspect(OBJECT *object, double az, double el, double freq, RCS_ASPECT *aspect);

    // ReturnRCSAspect() makes sure that the relavent RCS data is available for this az/el aspect and frequency
    // Returns FALSE if no appropriate data exists.
    // Not required if CalcRFReflectedPower is to be called, but useful if one is to pass this info to 3rd party codes.
    // "el" [deg] measured from FR plane toward D, 
    // "az" [deg] measured on FR plane counter-clockwise about D from F
    // "freq" [Hz]
    SIGSIM_API jrmbool ReturnRCSAspect(OBJECT *object, double az, double el, double freq, RCS_ASPECT *ra);

   // FillObjectRCS() fills OBJECT RCS table from the specified file.
    // If object->rcs_file exists, then it will be read into object->old_rcs_table
    // Inputs :   sigsim_data_dir = string containing the name of the main data directory (this routine will look for the object/rcs subdirectory).
    //         object = pointer to OBJECT whose RCS table is to be filled.
    // Uses:   object->rcs_file
    // Outputs: object->old_rcs_table
    // Returns: SIGSIM_FILE_NOT_FOUND if sigsim_data_dir/object/rcs/object->rcs_file is not found or can't be read.
    //         SIGSIM_SUCCESS upon successful completion.
   SIGSIM_API int FillObjectRCS(char *sigsim_data_dir, OBJECT *object);

    /*
    // CalcObjectRCS() performs coherent ray-sums over all scatter centers to calculate rcs and stores in object->rcs.
    // Internal function.
    SIGSIM_API int CalcObjectRCS(OBJECT *object); 
    */
   SIGSIM_API jrmComplex getSigSimTargetRCS(double az_deg, double el_deg, double freq_Hz, RCS_TABLE *rcs_table, enum Polarization pol);
   SIGSIM_API void getSigSimTargetRCSAllPol (double az_deg, double el_deg, double freq_Hz, RCS_TABLE *rcs_table, jrmComplex *HH, jrmComplex *HV, jrmComplex *VH, jrmComplex *VV);

#endif // _SIGSIM_RADAR_H_


#ifdef _PARTICLES_H_
   /* ------------------------ PARTICLE SYSTEM ROUTINES ------------------------------- */
   SIGSIM_API int UpdateObjectParticleEffects(char *sigsim_atm_dir, OBJECT *object, METIN *metin);

   SIGSIM_API int PrintParticleSystem(OBJECT *object, SPECTRAL_DOMAIN *spectrum);
#endif // _PARTICLES_H_


#ifdef _POLYGONS_H_
   /* ------------------------ OBJECT GEOMETRY ROUTINES ------------------------------- */

    typedef struct
    {
        long polyID; // ID of polygon hit
        VECTOR norm_g;  // Normal in global space
        jrmbool inout;  // TRUE = ray enters face, FALSE = ray exits face
        VECTOR v1,v2,v3;// Vertices in global space
        VECTOR hit_g;   // Position of hitpoint in global space
        VECTOR hit_b;   // Position of hitpoint in body space
        VECTOR hit_v;   // Distances from vertices {v1, v2, v3}
        double dist; // Distance along global +x from global origin.
    } OBJHIT;        // Object hitpoint

    /* -------------------------- OBJECT CREATION --------------------------- */

   // AllocateObjectArray allocates (but does not fill) an array of OBJECTs of length num_objects, and also allocates the ms_poly_array for each.
    // Inputs : num_objects = number of OBJECTs to be allocated.
    //         polys_per_object = array of integers, each specifying the number of polygons in the corresponding OBJECT's ms_poly_array.
    // Outputs: object = Pointer to array of OBJECTs to be allocated.
    //         rcs_table will be NULL by default.
    // Returns: SIGSIM_MEMORY_ALLOCATION_ERROR if Object array or ms_poly_array already allocated or otherwise cannot be allocated.
    //         SIGSIM_SUCCESS on successful completion.  
    SIGSIM_API int AllocateObjectArray(int num_objects, int *polys_per_object, OBJECT **object);

    // AddToObject() modifies composite OBJECT to add new OBJECTs according to placement/orientation in corresponding TRACK array.
    // Inputs :   composite = pointer to pre-allocated OBJECT to be added to.
    //         nobjects = number of OBJECTs in object array to be added. Should also equal number of TRACKs in track array.
    //         object = array of OBJECTs to be added to composite OBJECT.
    //         track = array of TRACKs on a one-to-one correspondence with the object array. Each TRACK gives the position and orientation of the corresponding OBJECT to be added, as measured in the composite OBJECT's body FRD system.
    // Returns:   The number of polygons in the final composite OBJECT's ms_poly_array, after all OBJECTs have been added. int i;
    SIGSIM_API long AddToObject(OBJECT *composite, int nobjects, OBJECT *object, TRACK *track);

    SIGSIM_API int CreateCone(int nmb_faces, double length, double angle, VERTEX base_center, VECTOR dir, OBJECT* cone);
    // "nmb_faces" specifies the number of MS_POLYGONs to use in construction of the cone.
    // "length" is in meters
    // "angle" is in radians and is half of the angle at the cone apex
    // "base_center" is in meters, and refers to the location of the center of the cone base relative to the object local origin in object-local FRD.
    // "dir" is a vector specifying the direction from base center to the apex vertex in object-local FRD.
    SIGSIM_API int CreateCyl(int nmb_faces, double length, double radius, VERTEX center, VECTOR dir, OBJECT* cyl);
    // "nmb_faces" specifies the number of MS_POLYGONs to use in construction of the cylinder.
    // "length" is in meters
    // "radius" is in meters
    // "center" is in meters, and refers to the location of the center of the cylinder relative to the object local origin in object-local FRD.
    // "dir" is a vector specifying the direction of the cylinder axis in object-local FRD, and has bi-directional ambiguity.
    SIGSIM_API int BoxTestObject(OBJECT *object, double length, double width, double height, double patch);

    /* ----------------- COORDINATE TRANSFORMATIONS ----------------------------- */
    SIGSIM_API int GetTargetSensorNEDProjPolygons(OBJECT *obj, SENSOR *sens, ellipsoid E, POLY_ARRAY *p);
    // Translates object's polygons to sensor NED system.
    // "obj" contains the polygons to be translated.
    // "proj" is the output array of translated NED polygons
    // "nmb_tr" is the number of polygons in the output "proj" array.

    /* ----------------------- PROJECTIONS AND INTERSECTIONS ----------------------- */
    SIGSIM_API int GetObjectBoundingBox(OBJECT *obj, VECTOR FRDright, VECTOR FRDdown, double *up, double *down, double *left, double *right);
    SIGSIM_API int PolyNirt(OBJECT *object, TRACK track, OBJHIT **hit);
    // PolyNirt inputs an object placed at a certain track.position within a global space at arbitrary track.orientation.
    // A ray is then fired along the x-axis of the global space, and intersects the object at certain points.
    // PolyNirt allocates and returns an array of nhit "OBJHIT" structures containing the intersection data.
    // NOTE : Assumes track.position is in same units as poly vertices !!!
    SIGSIM_API int Free_OBJHITs(OBJHIT *hits);
    SIGSIM_API int GetTargetNEDBoundingBox(OBJECT *obj, VECTOR Rtarget, int *nvecs, VECTOR *corner);
    SIGSIM_API void ObjectDimensions(OBJECT *objectin);
    // CalcObjectLOSFrameExtents() finds the downrange and maximum crossrange extents of the object relative to a local NED vector.
    SIGSIM_API int CalcObjectLOSFrameExtents(OBJECT object, VECTOR to_eye_NED, double *crossrange, double *downrange);

   /* ---------------------- STATE UPDATES -------------------- */

    // UpdateObjectMSPOLYARRAYTemperatures() merely updates the ms_poly_array temperatures (degK) with the mp_table.Tsurf temperatures corresponding to the instantiated material system.
    SIGSIM_API int   UpdateObjectMSPOLYARRAYTemperatures(OBJECT *object);

#endif // _POLYGONS_H_

#ifdef __cplusplus
}
#endif

#endif //OBJECTS_H_