Filter Scope Functions

CAgAttr ChangeCBs(const string& satListString, const string& CBListString, const string& propagatorComponentListString)

This function supports the ChangeCentralBodyTool utility. Use it to transition central bodies (CBs) within the filter. The function does the following for each satellite configured in the filter:

  • It sets the selected propagator component as the satellite's propagator, if not set to the selected one already.

  • It validates that the propagator component you specify for the satellite has the same central body as the new one you want to use.

  • It will update the central body in the satellite object and transform the selected restart state/covariance to the new CB reference inertial frame.

  • It will create a new restart file.

The function also checks to ensure that the filter is in restart mode before processing.

Parameters

satListString string

Enter a single string listing the satellite names; names are separated by white space, e.g., "Satellite1 Satellite2".
CBListString string

Enter a single string listing the satellite CB names, in the same order as satListString. Names are separated by commas, e.g., "Earth, Moon".
propagatorComponentListString string

Enter a single string listing the satellite propagator component names, in the same order as satListString. Names are separated by commas, e.g., "Earth HPOP, Moon HPOP".

Return Value

The function returns a CAgAttr object containing the following members:

Succeed CAgAttrBool

This is true if successful and false if unsuccessful.
Messages CAgAttrString This contains informational or error messages to be displayed in the status line.

Example JavaScript:

Copy 
let satListString = "Satellite1, Satelllite2";
let CBListString = "Earth, Moon";
let propagatorComponentListString = "Earth HPOP, Moon HPOP";
let result = sc.Filter(0).ChangeCBs(satListString, CBListString, propagatorComponentListString);
if(result.Succeed.value())
{
    window.alert("Success: " + result.Messages.value());
}
else
{
    window.alert("Failed: " + result.Messages.value());
}

CAgAttr ChangeMotionModels(const string& satListString, const string& MotionModelListString)

This function supports the ChangeMotionModelTool utility. Use it to transition between satellite motion models within the filter. The function will update the Motion Model(s) in the satellite object(s) and transform the selected restart state/covariance to the new reference frame: Inertial for Orbiter and Fixed for Lander. It will also create a new restart file.

Parameters

satListString string

Enter a single string listing the satellite names, which are separated by white space, e.g., "Satellite1 Satellite2"
MotionModelListString string

Enter a single string listing the satellite Motion Model names, using the same order as satListString. Names are separated by white space, e.g., "Orbiter Lander".

Return Value

The function returns a CAgAttr object containing the following members:

Succeed CAgAttrBool

This is true if successful and false if unsuccessful.
Messages CAgAttrString This contains informational or error messages to be displayed in the status line.

Example VBS:

Copy 
satListString = "Satellite1 Satelllite2"
CBListString = "Orbiter Lander"
set retv = ODTK.Scenario(0).Filter(0).ChangeMotionModels(satListString, MotionModelListString)
ODTK.writemessage retv.Succeed,"force"
ODTK.writemessage retv.Messages,"force"

bool GenerateGNSSDDObs(string prMeasType, string phaseMeasType, bool orthogonalObs, bool retainExcess, string filename)

This is a helper function to the GenerateGNSSDDObs utility. It generates GNSS Double Difference Measurements from the currently assigned tracking data files. These must contain the raw measurements of either type CA pseudo-range or P1 & P2 pseudo-range to generate double-differenced pseudo-range or LA, L1, or L2 phase to generate double-differenced phase. The SatelliteList and TrackerList for the current filter restrict the combinations of double-differenced measurements to be generated. The calling sequence allows for the specification of one double-differenced pseudo-range and one double-differenced phase type to be generated. The generation of dual frequency double-differenced observations cannot be combined with the generation of single frequency double-differenced observations in a single call. You must ensure that the format of the specified output file is able to support doubly differenced measurements. The function will not return an error if the requested format is invalid; it will just create a file of zero size. It will also display the number of measurements written in the message viewer.

Parameters

prMeasType string

Choose one of these options:"CADD", "PDFDD" or "".
phaseMeasType string

Choose one of these options:"LADD", "L1DD", "L2DD", "LDFDD" or "".
orthogonalObs bool

Enter either true or false, which controls whether or not the generated observations are restricted to be a set that is not correlated.
retainExcess bool

Enter either true or false, which controls whether or not the function saves raw observations not used in the generation of double-differenced observations to the output file.
filename string

Provide the path to the desired output file name.

Return Value

bool

This is a flag indicating if the function generated an output file or not.

Example VBS:

Copy 
filename = "c:\tmp\cadd.gobs"
bResult = sc.Filter(0).GenerateGNSSDDObs("CADD", "LADD", true, true, filename)

CAgAttr GetRestartTimeStrings(double precision)

Use this to get a list of restart times.

Parameters

precision double

The desired decimal precision for the returned dates

Return Value

CAgAttr

A list of restart time strings, including the date units

Example VBS:

Copy 
set list = ODTK.Scenario(0).Filter(0).GetRestartTimeStrings(0.001)

Example Result:

Copy 
"11 Jul 2025 16:00:00.000 UTCG"

CAgAttr GetSatCBs()

This function supports the ChangeCentralBodyTool utility. It reads the selected Filter restart record and returns the names of satellites and their associated central bodies.

Return Value

The function returns a CAgAttr object containing the following members:

Succeed CAgAttrBool

True if successful, false if unsuccessful
Messages CAgAttrString Informational or error messages to be displayed in the status line
SatList CAgAttrList of CAgAttrStrings A list of satellite names
CBList CAgAttrList of CAgAttrStrings A list of satellite central body names

Example VBS:

Copy 
set retv = ODTK.Scenario(0).Filter(0).GetSatCBs()
ODTK.writemessage retv.Succeed,"force"
ODTK.writemessage retv.Messages,"force"
ODTK.writemessage retv.SatList,"force"
ODTK.writemessage retv.CBList,"force"

CAgAttr GetSatMotionModels()

This function supports the ChangeMotionModelTool utility. It reads the selected Filter restart record and returns the names of satellites and their associated motion models.

Return Value

A CAgAttr object containing the following members:

Succeed CAgAttrBool

True if successful, false if unsuccessful
Messages CAgAttrString Informational or error messages to be displayed in the status line
SatList CAgAttrList of CAgAttrStrings A list of satellite names
MotionModelList CAgAttrList of CAgAttrStrings A list of satellite motion model names

Example VBS:

Copy 
set retv = ODTK.Scenario(0).Filter(0).GetSatMotionModels()
ODTK.writemessage retv.Succeed,"force"
ODTK.writemessage retv.Messages,"force"
ODTK.writemessage retv.SatList,"force"
ODTK.writemessage retv.MotionModelList,"force"

CAgAttr GetStateContents()

Returns a list of states (as a list of strings) that will be the filter state when it runs. It is called by the StateContent tool.

Return Value

CAgAttr

A list of strings

Example VBS:

Copy 
Set stateList = sc.Filter(0).GetStateContents
for each thing in stateList
    odtk.writemessage thing, "debug"
next

Example Result:

Copy 
"sat1    Orbit Z Velocity"

bool Go()

Use this to run the filter process in either start or restart mode.

Return Value

bool

A flag indicating if the filter ran and if the subsequent ephemeris prediction propagated to the requested stop time

Example VBS:

Copy 
bSuccess = sc.Filter(0).Go

To distinguish between the filter run itself and the ephemeris prediction, you can inspect the following Boolean attributes with detailed status/error information:

Copy 
Filter.RunResults.NumMeasAccepted = <int>
Filter.RunResults.NumMeasRejected = <int>
Filter.RunResults.NumMeasProcessed = <int>
Filter.RunResults.SumRatioSquareAccepted = <double>
Filter.RunResults.SumRatioSquareRejected = <double>
Filter.RunResults.InitializeSuccess = <bool>
Filter.RunResults.RestartSuccess = <bool>
Filter.RunResults.SetupSuccess = <bool>
Filter.RunResults.RunSuccess = <bool>
Filter.RunResults.RunCanceled = <bool>
Filter.RunResults.PropagatorError = <bool>
Filter.RunResults.EphemerisPredictPropagatorError = <bool>
Filter.RunResults.PropagatorAltitudeError = <bool>
Filter.RunResults.PropagatorVelocityError = <bool>
Filter.RunResults.PropagatorStateVectorError = <bool>
Filter.RunResults.PropagatorErrorSatelliteName = <string>
Filter.RunResults.PropagatorErrorTime = <time>

bool OutputPropagatorDefn(string satName, string filename)

Use this to write a satellite's propagator definition to a file that the STK application can read for initializing a satellite's integrator settings. The state written to the file is based on the filter results, where the epoch in the file will be at the last filter stop time.

Parameters

satName string

The name of one of the satellites in a filter run
filename string The path of the output file

Return Value

bool

Indicates success or failure

Example VBS:

Copy 
bSuccess = sc.Filter(0).OutputPropagatorDefn("sat1", "C:\tmp\sat1.pg")

bool Pause()

Use this to pause the filter process. You can step the filter forward with StepForward and restart it with Go or end it with Stop.

Return Value

bool

Always true

Example VBS:

Copy 
bSuccess = sc.Filter(0).Pause

bool SetEditedResiduals(string inputs, string date, integer nType, double measVal)

This is a helper function for the graphical residual editing capability. It enables graphical residual editing to work properly in cases where multiple observations of the same type from the same sensor exist for the same satellite at identical times. This function updates the ResidualEditing Schedule.

Parameters

inputs string

Contains the following items separated by spaces:

  • emmiter ID (-1 if not set)

  • strand

  • tracker

  • satellite

  • measurement type
date dString The date string with units
ntype int The type of measurement
dvalue double The measurement value

Return Value

bool

True if an entry is valid, false if not

Example VBS:

Copy 
inputs = "-1 TrackingSystem1.Facility1 - * TrackingSystem1.Facility1 Satellite1 Range "
dString = "01 Jul 2008 13:44:00 UTCG"
nType = 1
double_value = 1420193.763369
bSuccess = sc.Filter(0).SetEditedResiduals(inputs, dString, nType, double_value)

bool StepForward()

Use this to move the filter process forward one step.

Return Value

bool

A flag indicating if the filter ran or not

Example VBS:

Copy 
bSuccess = sc.Filter(0).StepForward

bool Stop()

Use this to stop the filter process.

Return Value

bool

Always true

Example VBS:

Copy 
bSuccess = sc.Filter(0).Stop

bool Transfer()

This transfers the filter solution to the estimated objects. It also writes a summary of actions to the message viewer.

Return Value

bool

Always true

Example VBS:

Copy 
bSuccess = sc.Filter(0).Transfer

CAgAttr ViewRestartData(const string& restartTimeString)

This function supports the ViewRestartData utility. Call this function to display the state content of the filter restart record associated with the input restart time.

Parameters

restartTimeString string

Provide the restart time string, e.g., "02 Jul 2011 11:17:00.000 UTCG".

Return Value

The function returns a CAgAttr object containing the following members:

Succeed CAgAttrBool

This is true if successful and false if unsuccessful.
Messages CAgAttrString This contains informational or error messages to be displayed in the status line.
StateNames CAgAttrList of CAgAttrStrings These identify the filter states.
StateUnits CAgAttrList of CAgAttrStrings These identify the state display units.
StateEstimates CAgAttrList of CAgAttrDoubles This gives state estimates.
StateSigmas CAgAttrList of CAgAttrDoubles This gives error root variances for state estimates.
StateErrorCovariance CAgAttrList of CAgAttrDoubles This gives a lower-triangular representation of the state error covariance matrix.

Example VBS:

Copy 
dim restartTimeString
dim restartRecord
restartTimeString = "02 Jul 2011 11:17:00.000 UTCG"
set restartRecord = fil.ViewRestartData(restartTimeString)
if restartRecord.Succeed then
    set listStateNames     = restartRecord.StateNames
    set listStateUnits     = restartRecord.StateUnits
    set listStateEstimates = restartRecord.StateEstimates
    set listStateSigmas    = restartRecord.StateSigmas
else
    MsgBox restartRecord.Messages
end if