Access Constraint Plugin Lifecycle

Access Constraints are used in two ways in STK:

  • as a visibility constraint when computing visibility (i.e., access) intervals. Visibility intervals may be computed from several tools:
    • Access Tool
    • Chains
    • DeckAccess
    • Coverage
    • Targeted Sensors
    • Targeted Attitude for vehicles
    • Display Times
    • ...others
  • as a metric indicating an important characteristic of the analysis. Tools that report metrics include:
    • the Report & Graph Manager, outputting Constraint Data
    • a Figure of Merit, configured to use an Access Constraint metric

    Many constraints require additional configuration data to be set by the user. For example, all Min/Max constraints require a min and/or max value be set; the lighting constraint requires the setting of a lighting type; the object exclusion constraint requires an STK object and exclusion angle. The configuration data is held by STK objects as part of their constraint settings. Thus, each constraint should be viewed as a pairing of (i) a computational algorithm; and (ii) configuration data required by the computational algorithm.

    The pairing of the algorithm with its configured data, for use as a computational entity, occurs in a PreCompute step, culminating with an activated constraint component. The activated component is initialized with its data and any other data needed from the two objects involved in the access computation. Once activated, the constraint component can compute its metric. The metric value may be used in an event detection algorithm to determine time intervals satisfying some condition (e.g., elevation angle >5 degs) or simply be used as an important characteristic of an analysis, depending on the tool using the access constraint. Once the tool no longer needs to compute with the access constraint, it is deactivated in a PostCompute step.

    The PreCompute, Compute, and PostCompute steps describe the computational lifecycle of every constraint. This lifecycle has ramifications on the lifecycle of the plugin component.

    Computational Lifecycle

    The following describes the computational lifecycle of a plugin component:

    1. Instantiate the plugin component as a COM object
    2. If the plugin supports IAgUtPluginConfig:
      • GetPluginConfig() is called
      • Properties of any declared configuration data is obtained
      • If the access constraint has specified configuration data, the associated Properties are set
    3. Init() is called
    4. PreCompute() is called
    5. Evaluate() is called as often as needed
    6. PostCompute() is called
    7. Free() is called
    8. The plugin component is destroyed

    Configuration Data Lifecycle

    The following describes the lifecycle of a plugin component created for the purposes of setting its configuration data (e.g., on the Constraints->Plugins panel):

    1. Instantiate the plugin component as a COM object
    2. If the plugin supports IAgUtPluginConfig:
      • GetPluginConfig() is called
      • Properties of any declared configuration data is obtained
      • If parameters are modified, VerifyPluginConfig() is called
      • If the parameter settings are valid, the associated Properties are set
      • GetPluginConfig() is called lastly to obtain the specified configuration data so that it can be stored without an instantiated plugin component
    3. The plugin component is destroyed

    Most importantly, the author of an Access Constraint Plugin must be aware that a plugin component may be created and destroyed many times, depending on how it is used by STK--there is not just one instantiated plugin component that lives for the lifetime of STK.

    Important Facets of the Plugin Lifecycle

    Visibility Constraint

    Access constraints apply to a pairing of STK objects. Some constraints (e.g., elevation angle) may be applied by both STK objects. [This depends on whether the constraint has been registered to do so.] Even if the same constraint is active for each object, different activated constraint components will be created because they may (and probably will) have different configuration data. The access constraint plugin is no different: if the constraint is registered on both objects then it may be applied by a user to both objects and two activated plugin components will be created, one for each object. In one case, one object will be the Base object with the other being the Target; in the second case, the objects will switch the Base-Target designations.

    • Once a plugin has been instantiated for a pairing, including the determination of the Base and Target designations, that plugin component will only be called for that pairing. A different plugin component will be instantiated for other pairings, or when the Base-Target designations are switched.
    • In Coverage, if the grid instance of the Coverage Definition object uses an access constraint plugin, then a separate plugin component will be created with each applicable Asset (i.e., for each Asset for which the plugin constraint registers it as a Target for the grid instance Base).
    • The Base and Target objects being used with an instantiated plugin may be determined from within the plugin using the IAgAccessConstraintPluginObjectDescriptor interface.

    Currently, when visibility intervals are being computed, the entire collection of applicable access constraints are first activated, initialized by calling Init(), and then PreCompute() is called on each one. This is done before any constraint is evaluated. Once all visibility processing is completed, PostCompute() is called on all the activated constraints, and then each is freed using Free() and destroyed.

    • It may happen during constraint processing that no visibility intervals exist, in which case no subsequent constraint need be evaluated. Thus, it is possible that Evaluate() is never called although PreCompute() and PostCompute() will be called.
    • If both objects activate a access plugin constraint, two plugins will be instantiated and PreCompute() called on both before Evaluate() is called on either.

    Metric

    In general, the lifecycle for plugin components follows the same lifecycle as that outlined above. However, additional considerations must be addressed when using an access constraint plugin component as a metric in a Figure of Merit.

    Figure of Merit

    Currently, each time step in the animation graphics of Figure of Merit objects causes a complete computational lifecycle for plugins. That is, for every animation time:

    • a plugin component is instantiated using the grid instance as Base and each (applicable) Asset as Target
    • Init() and PreCompute() are called on each one
    • For each grid point, for each plugin component, Evaluate() is called
    • PostCompute() and Free() are called on each one.
    • Each plugin is then destroyed.

    Because the plugin is instantiated and freed at every time step, no plugin component can 'remember' information from one time step to the next.

    For faster animation, avoid doing IO (like, for example, logging to a log file) during any of the plugin's calls.