Spatial Services Models

Version 1.7
Contact:   admin@csim.com

Contents:

  • Overview

  • API Specification of Routines - Initialization/Clean-up, Registering/Removing Objects, Controlling Motion, Reporting Positions, Finding near-by objects, Relative Distances or Bearing, Subscribing/Unsubscribing to Regions & Registrations, Arbitrary Attributes, Unit conversions, Line-of-Sight, Reading Way-point files.

  • Usage Information - Object ID's vs. Names, Coordinate Vectors, Time Values, Arbitrary Attributes, Distributed Operations

  • Legacy Routines - RegisterEnity, SetHermite, getTargetData, getActiveObjects, UnregisterEntity, ...

  • Appendix - Return Codes / Error Codes, Interpolation Methods, Coordinate Systems,

  • Examples

Overview:

The Spatial Services are part of the Vehicles, Platforms, & Terrains (VPT) model-library. It registers objects, such as vehicles, platforms, or fixed objects, along with their initial positions and rotational orientations. It accepts movement trajectories and manages objects locations at all times. The VPT package uses the information to support distributed spatial services, including:

  • Report the exact location, velocity, acceleration, and orientation of any object at any time.
  • Locate any/all objects within a given distance of another object or point.
  • Provide distance and bearing information between one object and any another.
  • Subscribe to a notification of any object(s) coming within a given distance of another object at any time.
  • Coordinate transformation functions, such as conversions between geodetic (degrees Lat/Lon) to regional projections (miles or km North/South relative a projected local map-reference point), or other reference frames, such as Earth-centered Cartesian or UTM.
  • Accept terrain elevation map data from standard sources (GDAL, GIS, DTED, etc.), and provide distance (altitude) from surface, determine line-of-sight between pairs of points, as well as to supply elevation data to guide surface objects.
VPT is based on data-structures and support methods that scale to efficiently support these services over arbitrary distances (region-sizes), time-spans, velocities, and number of objects. Expected nominal/intended ranges to be handled are:
  • Region Sizes = Urban to whole-Hemisphere coverage = 1-km to 10,000-km. Typically 50 to 1,000-km on a side.
  • Time spans = 1-minute to several-weeks. Typically on the order of minutes, hours, or days.
  • Velocities = 0.0 to ~28,000-km/h (orbital velocity). Typically 50-km/h (ground vehicles) to 900-km/h (aircraft/jets).
  • Populations = 1 to 100,000 objects. Typically 20 to 4,000 objects.
VPT spatial services are classed into the following categories:
  1. Initialization and Clean-up.
  2. Instantiating (registering) and removing objects.
  3. Controlling or Updating Object Positions or Motions (moving objects).
  4. Reporting Object Exact Positions.
  5. Finding near-by objects.
  6. Computing relative distances and directions or bearings.
  7. Subscribing / Unsubscribing to Regions & New Object Registrations.
  8. Setting & Getting Arbitrary Attributes.
  9. Unit conversions.
  10. Determining line-of-sight.
  11. Reading Way-point files.
All function values are doubles, and the functions return value is an integer unless otherwise specified. The base coordinate system is a regional Cartesian projection where unit positive values are in meters North, East, and Altitude, or x, y, z respectively as viewed on a typical map. Several coordinate systems are supported. See Coordinate Systems.   Values are based on the System International (SI) units of Meters, Kilograms, Seconds (MKS), and all angles are in degrees unless otherwise stated.

All objects can be referenced by unique names or ID's. When an object is first registered, the user supplies the name, and a unique ID is returned. The ID is used to reference the object in all subsequent calls. For convenience, unique names can be generated by the vpt_gen_name() function. ID's can be looked-up by name with the vpt_get_object_id() function. Names can be retrieved by the vpt_get_object_name() function.

The routines for each category are listed in the following sections. Information about each routine is supplied in the following format:

Routine_Name
Description of purpose, and relevant notes.
Inputs:
ParamName Type Units Description
ParamName Type Units Description
  ...   ...   ...   ...
Outputs:
ParamName Type Units Description
  ...   ...   ...   ...
Return Value:     Type and/or value description.
Prototype:
int Routine_Name( Type Param_name, Type Param_name, ... );

API Specification of Routines:

Function Index

  1. Initialization & Clean-up
  2. Instantiating & Removing Objects
  3. Controlling or Updating Object Positions or Motions
  4. Reporting Object Positions
  5. Finding near-by objects
  6. Computing relative distances and directions or bearings
  7. Subscribing to Regions & New Object Registrations
  8. Setting & Getting Attributes
  9. Unit conversions
  10. Determining line-of-sight
  11. Reading Way-point files

A. Initialization & Clean-up

vpt_initialize
Initializes spatial services internal structures. Prepares spatial server to accept objects and trajectories. This MUST BE CALLED FIRST, before any other spatial services functions.
Inputs:
None
Outputs:
None
Return Value:     0 on success; 1 on error.
Prototype:
RCODE   vpt_initialize()

vpt_cleanup
Free all data structures and zero-out all lists and pointers. Release all allocated resources.
Inputs:
None
Outputs:
None
Return Value:     RCODE
Prototype:
RCODE   vpt_cleanup()

B. Instantiating & Removing Objects

vpt_register_object
Registers new object for tracking within VPT. Returns ID handle to object. Specifies object's initial motion trajectory.
Inputs:
simTime double Seconds Simulated time-instant that object is to be instantiated. Relative to current time. (Zero means now, or ASAP.)
position double[3] COORD Initial position in N/E/Ht, Lat/Lon/Alt, or x,y,z.
CoordSys COORD Enum Coordinate system used to specify position. See appendix COORD.
velocity double[3] Meters/S Initial velocity vector.
acceleration double[3] Meters/S^2 Initial acceleration vector.
jerk double[3] Meters/S^3 Initial rate of acceleration change. (3rd order differential or impulse.)
orientation double[3] Degrees Initial orientation. Pitch, roll, yaw.
rotationRate double[3] Degrees/S Initial rotation rates. (1st order time differential of angles.)
rotationAccel double[3] Degrees/S^2 Initial rotational accelerations. (2nd order time differential of angles.)
interp INTERP Enum Interpolation method or quality, to use. See appendix INTERP.
Outputs:
None
Return Value:     ID of object, if successfully created; Otherwise returns negative error-code on error.
Prototype:
int   vpt_add_object( const double simTime, const double position[3], const COORD CoordSys, const double velocity[3], const double acceleration[3], const double jerk[3], const double orientation[3], const double RotationRate[3], const double RotationAccel[3], const INTERP interp )

vpt_register_object_relative
Similar to vpt_register_object above, but coordinates are specified relative another object, instead of absolute. Registers new object for tracking within VPT. Returns ID handle to object. Specifies object's initial motion trajectory.
Inputs:
simTime Simulated time-instant that object is to be instantiated. (Zero means now, or ASAP.)
position double[3] COORD Initial position in N/E/Ht, Lat/Lon/Alt, or x,y,z.
CoordSys COORD Enum Coordinate system used to specify position. See appendix COORD.
baseObjID int VPT_ID ID of the object to which coordinate position is relative.
velocity double[3] Meters/S Initial velocity vector.
acceleration double[3] Meters/S^2 Initial acceleration vector.
jerk double[3] Meters/S^3 Initial rate of acceleration change. (3rd order differential or impulse.)
orientation double[3] Degrees Initial orientation. Pitch, roll, yaw.
rotationRate double[3] Degrees/S Initial rotation rates. (1st order time differential of angles.) Pitch, roll, yaw.
rotationAccel double[3] Degrees/S^2 Initial rotational accelerations. (2nd order time differential of angles.) Pitch, roll, yaw.
interp INTERP Enum Interpolation method or quality, to use. See appendix INTERP.
Outputs:
None
Return Value:     ID of object, if successfully created; Otherwise returns negative error-code on error.
Prototype:
int   vpt_add_object( const double simTime, const double position[3], const COORD CoordSys, const int baseObjID, const double velocity[3], const double acceleration[3], const double jerk[3], const double orientation[3], const double RotationRate[3], const double RotationAccel[3], const INTERP interp )

vpt_delete_object
Removes object at the specified time.
Inputs:
ID int VPT_ID ID of object to delete.
simTime double Seconds Simulated time-instant that object is to be removed. Zero value means now or ASAP.
Outputs:
None
Return Value:     0 on success. Otherwise returns 1 on failure, for example if object cannot be found.
Prototype:
RCODE   vpt_delete_object( const int ID, const double simTime )

C. Controlling or Updating Object Positions or Motions (moving objects):

vpt_set_object_position
Use to update or change an object's position.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes position. (Zero means now, immediately, or ASAP.)
position double[3] COORD New object position.
CoordSys COORD Enum Coordinate system used to specify position. See appendix COORD.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_position( const int ID, const double simtime, const double position[3], const COORD CoordSys )

vpt_set_object_position_relative
Use to update or change an object's position, relative to another object.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes position. (Zero means now, immediately, or ASAP.)
position double[3] COORD New object position.
CoordSys COORD Enum Coordinate system used to specify position. See appendix COORD.
baseObjID int VPT_ID ID of the object to which new coordinate position is relative.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_position_relative( const int ID, const double simtime, const double position[3], const COORD CoordSys, const int baseObjID )

vpt_set_object_motion
Use to update or change an object's motion vectors, such as velocity or acceleration.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes motion values. (Zero means now, immediately, or ASAP.)
velocity double[3] Meters/S Velocity vector.
acceleration double[3] Meters/S^2 Acceleration vector.
jerk double[3] Meters/S^3 Rate of acceleration change. (3rd order differential or impulse.)
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_motion( const int ID, const double simtime, const double velocity[3], const double acceleration[3], const double jerk[3] )

vpt_set_object_orientation
Use to update or change an object's orientation.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes orientation. (Zero means now, immediately, or ASAP.)
orientation double[3] Degrees Orientation. Pitch, roll, yaw.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_orientation( const int ID, const double simtime, const double orientation[3] )

vpt_set_object_rotation
Use to update or change an object's rotational motion rates.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes motion values. (Zero means now, immediately, or ASAP.)
rotationRate double[3] Degrees/S Rotation rates. (1st order time differential of angles.)
rotationAccel double[3] Degrees/S^2 Rotational accelerations. (2nd order time differential of angles.)
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_rotation( const int ID, const double simtime, const double rotationRate[3], const double rotationAcce[3] )

vpt_set_object_position_motion
Alternate convenience function to set all of an object's position, orientation, and motion parameters in a single call, instead of the separate calls above.
Inputs:
ID int VPT_ID ID of object to be adjusted.
simTime double Seconds Simulated time-instant that object takes new position and motion values. (Zero means now, immediately, or ASAP.)
position double[3] COORD New object position.
CoordSys COORD Enum Coordinate system used to specify position. See appendix COORD.
velocity double[3] Meters/S Velocity vector.
acceleration double[3] Meters/S^2 Acceleration vector.
jerk double[3] Meters/S^3 Rate of acceleration change. (3rd order differential or impulse.)
orientation double[3] Degrees Orientation. Pitch, roll, yaw.
rotationRate double[3] Degrees/S Rotation rates. (1st order time differential of angles.)
rotationAccel double[3] Degrees/S^2 Rotational accelerations. (2nd order time differential of angles.)
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_position_motion( const int ID, const double simtime, const double position[3], const COORD CoordSys const double velocity[3], const double acceleration[3], const double jerk[3],const double orientation[3], const double rotationRate[3], const double rotationAcce[3] )

vpt_set_object_motion_interpolation_method
Use to change or set an objects position interpolation method or quality.
Inputs:
ID int VPT_ID ID of object to be adjusted.
interp INTERP Enum Interpolation method or quality, to use. See appendix INTERP.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_object_motion_interpolation_method( const int ID, const INTERP interp )

vpt_attach_object
Causes an object's position and motion to be governed by another object, as if attaching one object to another. Often useful when object is part-of, or <i>on-board</i>, another vessel object. Objects can be later detached for independent motion, for example, munitions, cargo, etc..
Inputs:
ID1 int VPT_ID ID of governing object. Object to attach to.
ID2 int VPT_ID ID of object to be governed or attached.
simTime double Seconds Simulated time-instant that object is to be attached. Zero value means now or ASAP.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_attach_object( const int ID1, const int ID2, const double simTime )

vpt_detach_object
Causes object to no longer be governed by another object, but to move independently.
Inputs:
ID int VPT_ID ID of object to be detached.
simTime double Seconds Simulated time-instant that object is to be detached. Zero value means now or ASAP.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_detach_object( const int ID, const double simTime )

D. Reporting Object Positions:

vpt_get_position
Uses interpolation method to pass back object's position coordinates.
Inputs:
ID int VPT_ID ID of object.
simTime double Seconds Simulated time-instant that coordinates are requested for. Zero value means now or ASAP.
CoordSys COORD Enum Coordinate system that position is requested in. See appendix COORD.
Outputs:
position double[3] COORD New object position.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_postion( const int ID, const double simtime, const COORD CoordSys, const double position[3] )

vpt_get_orientation
Pass back an object's rotational orientation values.
Inputs:
ID int VPT_ID ID of object.
simTime double Seconds Simulated time-instant that coordinates are requested for. Zero value means now or ASAP.
Outputs:
orientation double[3] Degrees Orientation. Pitch, roll, yaw.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_orientation( const int ID, const double simtime, const double orientation[3] )

vpt_get_position_motion
Uses interpolation method to pass back all of an object's position, orientation, and motion coordinates.
Inputs:
ID int VPT_ID ID of object.
simTime double Seconds Simulated time-instant that coordinates are requested for. Zero value means now or ASAP.
CoordSys COORD Enum Coordinate system that position is requested in. See appendix COORD.
Outputs:
position double[3] COORD New object position.
velocity double[3] Meters/S Velocity vector.
acceleration double[3] Meters/S^2 Acceleration vector.
jerk double[3] Meters/S^3 Rate of acceleration change. (3rd order differential or impulse.)
orientation double[3] Degrees Orientation. Pitch, roll, yaw.
rotationRate double[3] Degrees/S Rotation rates. (1st order time differential of angles.)
rotationAccel double[3] Degrees/S^2 Rotational accelerations. (2nd order time differential of angles.)
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_postion_motion( const int ID, const double simtime, const COORD CoordSys, const double position[3], const double velocity[3], const double acceleration[3], const double jerk[3],const double orientation[3], const double rotationRate[3], const double rotationAcce[3] )

E. Finding near-by objects:

vpt_find_objects_near_object
Passes back a list of the objects within the specified radius of the specified object. Allocates array in STD-Int-Vector. ** Must be freed by caller **.
Inputs:
ID int VPT_ID ID of object.
radius double meters Region.
Outputs:
numObjs int none Number of objects in list.
IDlist STD-Int-Vector VPT_ID_List Array of ID numbers.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
vpt_find_objects_near_object(   const int ID, const double radius, int *numObjs, STD-Int-Vector *IDlist )

vpt_find_objects_near_position
Passes back a list of the objects within the specified radius of the specified position. Allocates array. ** Must be freed by caller **.
Inputs:
position double[3] COORD Position of center of region.
CoordSys COORD Enum Coordinate system that position is specified in. See appendix COORD.
radius double meters Radius of region.
Outputs:
numObjs int none Number of objects in list.
IDlist STD-Int-Vector VPT_ID_List Array of ID numbers.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
vpt_find_objects_near_position(   const double position[3], const COORD CoordSys, double radius, int *numObjs, STD-Int-Vector *IDlist )

F. Computing relative distances and directions or bearings:

vpt_get_range
Passes-back the range from object 1 to object 2 in meters, at the current time.
Inputs:
ID1 int VPT_ID ID of observing object. Bearing will be relative to this object.
ID2 int VPT_ID ID of remote object that bearing is requested to.
Outputs:
range double Meters Distance between object 1 and object 2.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_range( const int ID1, const int ID2, double *range )

vpt_get_bearing
Passes-back the bearing from object 1 to object 2 in radians, at the current time. The bearing is the direction of one point relative to another point.
Inputs:
ID1 int VPT_ID ID of observing object. Bearing will be relative to this object.
ID2 int VPT_ID ID of remote object that bearing is requested to.
Outputs:
bearing double[2] Radians Az+El Bearing of second object.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_bearing( const int ID1, const int ID2, double *bearing )

vpt_get_range_and_bearing
Passes-back the range and bearing from object 1 to object 2 in meters and radians, respectively, at the current time.
Inputs:
ID1 int VPT_ID ID of observing object. Bearing will be relative to this object.
ID2 int VPT_ID ID of remote object that bearing is requested to.
Outputs:
range double Meters Distance between object 1 and object 2.
bearing double[2] Radians Az+El Bearing of second object.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_get_range_and_bearing( const int ID1, const int ID2, double *range, double *bearing )

G. Subscribing to Regions & New Object Registrations

vpt_subscribe_to_near_object
This routine subscribes to objects that enter or exit within a given radius of the specified object. It registers your call-back function to be called when objects pass into or out-of the region. An optional parameter is passed to your call-back function, which also receives the ID of the approaching object, and the subscription-ID responsible for the call-back.
Inputs:
ID int VPT_ID ID of object.
radius double meters Radius of region.
callbackfn void(int,int,void*) none Handle to your callback function.
param void* none Optional parameter passed to callback.
Outputs:
subscrID int none Subscription ID handle.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_subscribe_to_near_object( const int ID, const double radius, const void callbackfn(int,intvoid*), const void *param, int *subscrID )

vpt_subscribe_to_near_position
This routine subscribes to objects that enter or exit within a given radius of the specified position. It registers your call-back function to be called when objects pass into or out-of the region. An optional parameter is passed to your call-back function, which also receives the ID of the approaching object, and the subscription-ID responsible for the call-back.
Inputs:
position double[3] COORD Position of center of region.
CoordSys COORD Enum Coordinate system that position is specified in. See appendix COORD.
radius double meters Radius of region.
callbackfn void(int,int,void*) none Handle to your callback function.
param void* none Optional parameter passed to callback.
Outputs:
subscrID int none Subscription ID handle.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_subscribe_to_near_position( const double position[3], const double radius, const void callbackfn(int,int,void*), const void *param, int *subscrID )

vpt_unsubscribe
Removes subscriptions by subscription-ID.
Inputs:
subscrID int none Subscription ID handle.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such subscription.
Prototype:
RCODE   vpt_unsubscribe( const int subscrID )

vpt_unsubscribe_to_all_events
Removes subscriptions to all events. This includes both near-object and new object registration events.
Inputs:
None
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error.
Prototype:
RCODE   vpt_unsubscribe_to_all_events()

vpt_subscribe_to_all_registrations
This routine subscribes to all new object registrations. It registers your call-back function to be called when new objects are instantiated. An optional parameter is passed to your call-back function, which also receives the ID of the new object, and the subscription-ID responsible for the call-back.
Inputs:
callbackfn void(int,int,void*) none Handle to your callback function.
Outputs:
subscrID int none Subscription ID handle.
Return Value:     0 on success. Otherwise 1 on error.
Prototype:
RCODE vpt_subscribe_to_all_registrations(   int *subscrID )

vpt_unsubscribe_to_all_registrations
This routine unsubscribes to all events registered to the named call-back function.
Inputs:
callbackfn void(int,int,void*) none Handle to your callback function.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error.
Prototype:
RCODE vpt_unsubscribe_to_all_registrations(   const void callbackfn(int,int,void*) )

vpt_get_name( ID, max_char, name)
Passes back the character name associated with the ID. Note that there can be different names associated with an ID. This returns the name within the current federate.
Inputs:
ID int VPT_ID ID of object.
max_char int none Maximum size of the passed character array.
Outputs:
name char* none Name of the object.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   pt_get_name( const int ID, const int max_char, char *name)

vpt_get_ID( ID, max_char, name)
Inverse of vpt_get_name. Passes back the ID of the named object.
Inputs:
name char* none Name of the object.
Outputs:
ID int VPT_ID ID of object.
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   pt_get_ID( const char *name, int *ID )

H. Setting & Getting Attributes:

vpt_set_attribute
Adds new attribute with value to specified object, if it did not already have an attribute of the given name. Otherwise, it just sets attribute's value to the new value.
Inputs:
ID int VPT_ID ID of object to set attribute on.
attrib_name char_* none Attribute name.
attrib_value char_* none Attribute value.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as no such object.
Prototype:
RCODE   vpt_set_attribute( const int ID, const char *attrib_name, const char *attrib_value )

vpt_get_attribute_value
Retrieves names attribute value from the given object ID.
Inputs:
ID int VPT_ID ID of object to get attribute from.
attrib_name char_* none Attribute name.
maxlen int none Maximum length of string to be returned. (Size of pre-allocated attrib_value array.)
Outputs:
attrib_value char_* none Attribute value. Must be pre-allocated with sufficient size to hold answer.
Return Value:     0 on successful retrieval. Otherwise 1 on error such as no object, or no attribute of given name.
Prototype:
RCODE   vpt_get_attribute_value( const int ID, const char *attrib_name, const int maxlen, char *attrib_value )

I. Unit conversions:

vpt_set_absolute_time_reference
Sets the absolute time reference corresponding to simulation time=0.0, relative day of the year and time of the day. The time reference defaults to day=1, hour=0, min=0, sec=0.0. The time reference is used in vpt_get_sysTime and vpt_getDHMS calls. All internal time values are in Seconds from the start of the current simulation. The VPT_Time_Reference can be set to convert relative simulation time to-and-from the day, hour, minute, and second of a year.
Inputs:
day int days Normally day within scenario (ex. day 2), but can be day of the year, or days from a reference year.
hour int hours Hour of the day. Range 0 - 23.
min int minutes Minute of the hour. Range 0 - 59.
sec double seconds Second of the minute. Range 0.0 - 59.9999.
Outputs:
None.
Return Value:     0 on success. Otherwise 1 on error such as out-of-range value.
Prototype:
RCODE   vpt_set_time_reference( const int day, const int hour, const int min, const double sec )

vpt_get_relative_current_time
Returns the current simulation time in seconds relative to the start of the simulation.
Inputs:
None.
Outputs:
None
Return Value:     Returns the current simulation time in seconds as double-float.
Prototype:
double   vpt_get_current_time()

vpt_get_absolute_time
Uses Time-Reference to convert relative simulation time to a day, hour, minute, and second of a year.
Inputs:
None
Outputs:
day int days Normally day within scenario (ex. day 2), but can be day of the year, or days from reference year.
hour int hours Hour of the day. Range 0 - 23.
min int minutes Minute of the hour. Range 0 - 59.
sec double seconds Second of the minute. Range 0.0 - 59.9999.
Return Value:     0 on success. Otherwise 1 on error.
Prototype:
RCODE   vpt_get_absolute_time( int *day, int *hour, int *min, double *sec )

vpt_convert_DHMS_to_seconds
Converts a linear-seconds time quantity to Days, Hours, Minutes, Seconds.
In/Outs:
day int days Day number. Range 0 - ...
hour int hours Hour of the day. Range 0 - 23.
min int minutes Minute of the hour. Range 0 - 59.
sec double seconds Second of the minute. Range 0.0 - 59.9999.
Return Value:     0 on success. Otherwise 1 on error such as out-of-range value.
Prototype:
RCODE   vpt_convert_DHMS_to_seconds( int *day, int *hour, int *min, double *sec )

vpt_convert_seconds_to_DHMS
Converts a Days, Hours, Minutes, Seconds time amount to a linear-seconds time quantity.
In/Outs:
day int days Day number. Range 0 - ...
hour int hours Hour of the day. Range 0 - 23.
min int minutes Minute of the hour. Range 0 - 59.
sec double seconds Second of the minute. Range 0.0 - 59.9999.
Return Value:     0 on success. Otherwise 1 on error such as out-of-range value.
Prototype:
RCODE   vpt_convert_seconds_to_DHMS( int *day, int *hour, int *min, double *sec )

vpt_convert_nautical_miles_to_meters
Converts nautical miles to meters.
Inputs:
nautmiles double Nautical_Miles Distance in nautical miles.
Outputs:
none
Return Value:     Distance in meters.
Prototype:
double   vpt_convert_nautical_miles_to_meters( const double nautmiles )

vpt_convert_meters_to_nautical_miles
Converts meters to nautical miles.
Inputs:
meters double Meters Distance in meters.
Outputs:
none
Return Value:     Distance in nautical miles.
Prototype:
double   vpt_convert_meters_to_nautical_miles( const double km_distance )

vpt_convert_feet_to_meters
Converts feet to meters.
Inputs:
feet double Feet Distance in Feet.
Outputs:
none
Return Value:     Distance in meters
Prototype:
double   vpt_convert_feet_to_meters( const double feet )

J. Determining line-of-sight:

vpt_line_of_sight
Determine if there is line-of-sight between two objects.
Inputs:
ID1 int VPT_ID ID of object 1.
ID2 int VPT_ID ID of object 2.
Outputs:
none
Return Value:     0 if no line-of-sight, 1 objects are within line-of-sight, otherwise -1 on error, such as no such object.
Prototype:
int   vpt_line_of_sight( const int ID1, const int ID2 )

K. Reading Way-point files:

vpt_read_waypoint_file
Read named way-point file, and begins managing objects. The way-point file enables instantiating new objects at scheduled times, and moving them on scheduled trajectories. The file content is specified in XML format, and may be generated by a variety of tools, including the graphical Scenario Entry Tool (S.E.T.), as well as various custom automatic scenario generators. The way-point format is also compatible with the WinFrame-3d 2D Map-based & 3D battle-scene visualization tool. With this, you can view the vehicle locations and movements in relation to each other, ground objects, and time.
The format of the way-point file is as follows:
To instantiate an object at time T:
      <inst_obj name="" type="" T="" x="" y="" z="" xang="" yang="" z="" />
... Where the appropriate values are to be placed within the quotes.
To specify motion between times T1 and T2:
      <mo obj="" T1="" T2="" x="", y="", z="" />
To specify motion for a duration relative to the current time:
      <mo_rel obj="" duration="" x="", y="", z="" />
To specify rotation around the x, y, or z axes in radions from T1 to T2, or for a relative duration:
      <ro obj="" T1="" T2="" xang="", yang="", zang="" />
Or,
      <ro_rel obj="" duration="" xang="", yang="", zang="" />
See: WinFrame-3d for more information.
Inputs:
waypt_file char* none Name of XML way-point data.
Outputs:
None
Return Value:     0 on success. Otherwise 1 on error such as cannot open input file for reading.
Prototype:
RCODE   vpt_read_waypoint_file( const char *waypt_file )

Usage Information:

Object ID's vs. Names
For efficiency, the VPT spatial services routines reference objects by unique integer ID's. Some user-models naturally refer to objects by unique character string names and types. The type designator is useful, for example, to graphically render object scenes relative to other objects on maps or over terrain images. VPT provides methods for associating names with objects, and for rapidly retrieving ID's by names.

The unique ID handle is obtained when an object is first registered. The ID must be used in all subsequent transactions involving the given object.

Coordinate Vectors
For efficiency, all coordinates in three-dimensional space (3-space) are specified as arrays of three double-float values. For example, a relative position in meters North, East, Altitude is specified in the array:   double position[3].     Similarly, an absolute position, velocity or acceleration in degrees Lat-Lon and height in KFt, can all be specified with the same three-element array. Rotational orientation, velocity, and accelerations around the three principle axes (North,East,Up) also use the three-element array of doubles.

Several coordinate systems are supported. In UTM (Earth-polar) or regional (Cartesian) surface-map coordinates, positive axes values correspond to North, East, and Up for the three axes, respectively. Negative values on these axes correspond to South, West, and Down, in direction respectively. The Altitude axis corresponds to the radial from the center of Earth. Zero altitude corresponds to surface height, or Mean Sea-Level. For rotational values, positive refers to clockwise rotation around the: Altitude axis (when looking down), North-South axis when looking South, and East-West axis when looking West.

For Earth Centered or Earth Fixed Cartesian coordinates, the double-float vector is also used.

  • The positive Z-axis points toward the North Pole.
  • The positive X-axis is defined by the intersection of the plane define by the prime meridian and the equatorial plane.
  • The positive Y-axis completes a right handed orthogonal system by a plane 90-degrees east of the X-axis and its intersection with the equator.

Time Values
All time values are given as the simulated time in seconds from the start of the simulation. A VPT_Reference_Time can be set, to convert simulation time to a specific day, hour, minute, and second of a year.

Return Values
Most functions normally return zero when successful, but return a non-zero error-code if an error occurs.

Arbitrary Attributes
Arbitrary attributes can be attached to objects, and retrieved when needed. The attributes consist of name-value pairs, and are character-strings. See Setting and Getting Arbitrary Object-Attributes.

Distributed Operation
When running Spatial Services in a federation with multiple simulation federates, a single federate should be designated to manage spatial services. The vpt_initialize routine should be called on that federate, and all other federates should communicate object events to the designated federate.

It is permissable to run multiple spatial services on the various federates, but awareness of objects managed by remote federates will not be global.

Legacy Routines:

RegisterEntity
Inputs:
order DRM_Order none
data SpatialData none Coordinates, motion values,
Outputs:
none
Return Value:     void
Prototype:
void   RegisterEntity( const DRM_Order order, SpatialData *data )

SetHermite
Sets default interpolation to be Hermite.
Inputs:
Outputs:
Return Value:    
Prototype:
void   SetHermite( )

getTargetData
Accesses and passes-back position information about objects, relative to a given object.
Inputs:
time double seconds
latitude double degrees
longitutde double degrees
altitude double meters
Outputs:
tgt TargetData none Entity pointer (Reference to ID)
Return Value:     void
Prototype:
getTargetData(   double time, double latitude, double longitude, double altitude, TargetData *tgt )

getActiveObjects
Returns list of moving objects near a given point.
Inputs:
time double seconds
latitude double degrees
longitutde double degrees
altitude double meters
Outputs:
numActiveObjects int none Number of objects in returning list.
tgt TargetData none Entity pointer (Reference to ID)
Return Value:     void
Prototype:
void   getActiveObjects( double time, double latitude, double longitude, double altitude, int *numActiveObjects, TargetData *tgt )

UnregisterEntity
Inputs:
entity SpatialID none ID of enity to be unregistered.
Outputs:
none
Return Value:     void
Prototype:
void   UnregisterEntity( const SpatialID entity )


Inputs:
Outputs:
Return Value:    
Prototype:
 

Appendix:

Return Codes / Error Codes:     RCODE
A special integer type, called RCODE is defined to designed return-values.
  1. Ok, no error.
  2. Error occurred. Operation failed dues to unknown object ID.

Interpolation Methods:
The object motion interpolation methods is an Enum of:

  1. FIRST
  2. SECOND
  3. THIRD

Coordinate Systems:
The supported coordinate systems include any in the Enum of:

  1. ECEF - Earth Centered - Earth Fixed Cartesian. All units are in meters relative the center of Earth origin.
  2. GEOD - (also LLA or GLLH) - Geodetic Latitude, Longitude, and Height. Units are degrees and meters, respectively.
  3. UTM - Unified Transverse Mercator. Units are grid-cell designator, and regional North, East, Altitude in meters.
  4. MGRS - Military Grid Reference System. Like UTM, but slightly different units.
  5. E.N.U - East North Up, the native internal coordinate system. Referenced to an arbitrary local or regional map coordinate.
Our Earth is not a perfect sphere, but rather a slightly oblate ellipsoid. Various datums have been devised, based on measurements, surveys, and models of various qualities. A datum is the set of parameters and control points used to accurately define the three-dimensional shape of the Earth, and to reference points near the surface in relation to it. The VPT coordinate system translations above support the following Well Known Text (WKT) Earth ellipsoid datums:      
  1. Airy
  2. Australian National
  3. Bessel 1841
  4. Bessel 1841 (Nambia)
  5. Clarke 1866
  6. Clarke 1880
  7. Everest
  8. Fischer 1960 (Mercury)
  9. Fischer 1968
  10. GRS 1967
  11. GRS 1980
  12. Helmert 1906
  13. Hough
  14. International
  15. Krassovsky
  16. Modified Airy
  17. Modified Everest
  18. Modified Fischer 1960
  19. South American 1969
  20. WGS 60
  21. WGS 66
  22. WGS-72
  23. WGS-84

Base Object Types:
OTYPE objType,

Base Object Classes:
const OCLASS objClass

Examples:

  • Example 1 - A simple two object case.
  • Example 2 -