Flow Activation and Routing

Animation flows are not generated as a default by-product of simulations. Instead, animation flows must be specifically activated by the user. Flow activation is accomplished through a combination of simulation preferences and animation probes within a probe list applied to the simulation. Besides activating a flow, the animation-related preferences of a simulation specify how the flow will be routed (several options are available for routing the generated animation data). In addition to specifying which types of animation will be produced by which model objects, animation probes specify viewer options and animation time-range limits. Both types of activation requirements, animation-related preferences and animation probes, are described in this section.

There are two routing options for animation flows generated by a simulation: (1) routing to direct viewing in op_vuanim; (2) routing to an animation history file. If neither of these routing options is selected by the appropriate simulation preferences, no animation flow will be generated. Each of these routing options are described in separate subsections below.

Direct Viewing

In the direct viewing option, animation flow data is routed directly from an executing simulation to a concurrently executing instance of the op_vuanim program. The method of communication between the simulation and op_vuanim is a low-level network datagram protocol. The use of the network protocol supports both local and remote viewing scenarios: in a remote viewing scenario, op_vuanim executes on a different host computer than the simulation; in a local scenario, op_vuanim executes on the same host computer as the simulation.

The simulation and op_vuanim processes are synchronized by the animation flow, so that the simulation halts progress after it sends an animation request to op_vuanim, until it receives an acknowledgment that op_vuanim actually displayed the request. With this synchronization, a user can view simulation progress at an adjustable pace, without having the simulation continue far ahead of the user’s position in the animation flow, thus generating a large backlog of animation flow data. The synchronization of the direct viewing option is also critical when the option is used in conjunction with the simulation debugger, because it guarantees that a command specified in the debugger can be immediately reflected in the animation flow displayed in op_vuanim. This immediate feedback stems from the fact that the simulation is restricted from getting ahead of either the simulation debugger command loop or the animation flow playback of op_vuanim.

Figure 7: Flow Routing Option: Direct Viewing

Flow Routing Option: Direct Viewing

The direct viewing option is specified by the anim_view preference of simulations. Setting this Boolean attribute to TRUE as shown below causes a simulation to attempt to communicate with an op_vuanim process. Additional information in the form of preference assignments may need to be provided to specify communication parameters.

Figure 8: Specifying Direct Viewing Using the anim_view Flag

% op_runsim -net_name angen -anim_view <...>

The network datagram protocol used as the communication channel between an executing simulation and a op_vuanim process is UDP (User Datagram Protocol), which relies on the datagram delivery services of the industry-standard IP networking protocol (both of these protocols are part of the DoD-developed TCP/IP protocol suite). Each animation request is encapsulated in a UDP packet, and forwarded to the op_vuanim process. Two types of acknowledgment packets are returned from the op_vuanim process to its associated simulation for each request: an acknowledgment that the request was received, and an acknowledgment that the request was displayed. Time-out features are built into the Simulation Kernel so that it will retransmit animation requests that have not been acknowledged within an adequate time interval.

Figure 9: Animation Flow Communication Over UDP/IP

Animation Flow Communication Over UDP/IP

In order for UDP datagrams to travel between the simulation and op_vuanim processes, these processes must be aware of each other’s IP network address and UDP port number. Since the interprocess communication is still based on UDP/IP, these data items are required when the simulation and op_vuanim processes are executing on the same host computer. A port number identifies a port opened by a process for a protocol using the delivery services of IP, and distinguishes the process as a unique destination for the contents of IP packets. Address and port number data is obtained using a client/server strategy that is typical for IP-based services.

The op_vuanim process is considered a server process: it offers the animation viewing service to client simulations on the network. For this strategy to work, the op_vuanim process must begin execution before simulations attempt to connect with it. During initialization, op_vuanim establishes a UDP port on its host computer. The default port number is a fixed value that is also the default expectation of client simulations.

A client simulation derives the IP address of the op_vuanim host computer from the anim_host preference. This attribute provides the simulation with the network name of the op_vuanim host computer; the host’s name is translated into the host’s IP address using a name server available on the network, or the simulation host computer’s /etc/hosts file. The default value of the anim_host preference is “localhost”, which usually translates to the loopback address of the simulation host computer. Thus the anim_host preference typically does not need to be specified in the local viewing scenario.

Figure 10: Specifying the op_vuanim Host Using the anim_host Flag

% op_runsim -net_name angen -anim_view -anim_host guardian

Once an op_vuanim process receives an initial communication establishment packet from a simulation, it can extract the simulation’s host computer IP address from the packet, for use in future acknowledgment packets. The op_vuanim program thus does not require user specification of the IP address of the simulation’s host computer.

As mentioned previously, the default UDP port number of op_vuanim is known to simulations. This port number is hardwired to 3211, which should not interfere with any widely-used, IP-based service. However, particular installations may need to reserve this port number for internally developed or commercial software systems. In such cases, both op_vuanim and simulations can be informed that another UDP port number must be used. An alternative port number is not specified directly, but is specified as an offset from the default port number of 3211. This relative port offset is known as the animation port, and is specified to both op_vuanim and simulations via the anim_port preference. The default value of anim_port is 0, so that the default UDP port number is 3211 + 0 = 3211; setting anim_port to 5 will result in a UDP port number of 3211 + 5 = 3216. Provided that an op_vuanim process and a simulation process agree on the value of anim_port, they can establish communications.

A simulation is assigned a free UDP port number by the operating system when it opens up a port to communicate with op_vuanim. The simulation’s port number varies from execution to execution, and is not of interest to the user since it is directly conveyed to op_vuanim in the communication establishment packet.

Figure 11: Matching Simulation and op_vuanim Animation Ports

Matching Simulation and op_vuanim Animation Ports

Another problem related to animation ports arises when more than one op_vuanim process is executing on a single host computer. It is impossible for two ports on the same host to share a port number, so multiple op_vuanim processes must have different animation port value. op_vuanim tries to open a UDP port based on the specified animation port, but if it detects that the request port number is in use by another process, it increments the animation port by one and tries to open a UDP port based on the new value. This "bump up" procedure continues indefinitely until a free port is found. Thus multiple op_vuanim processes can be spawned on a single host computer without specifying different animation port values, since each process will find an available port.

In order for a simulation to communicate with one of multiple op_vuanim processes on a single host computer, the animation port number should be determined by reading it from the middle-right status strip within the environment of the desired op_vuanim instance. Once determined, the particular animation port can be targeted by executing a simulation with the same value assigned to the anim_port preference.

The UDP and IP protocols do not guarantee delivery of datagrams, and do not provide retransmission of datagrams lost in transit due to LAN collisions, routing problems, or other network lapses. Thus the communicating simulation and op_vuanim processes must detect packet losses and perform retransmissions themselves. The animation communication logic in op_vuanim and the Simulation Kernel does provide a robust retransmission service that can be parameterized to meet the network delay conditions experienced at different installations. The two retransmission parameters affect: (a) the amount of time that a simulation will wait for a request reception acknowledgment from an op_vuanim process before retransmitting; (b) the number of times a simulation will retransmit a request before giving up. These parameters are respectively set by the anim_timeout and anim_attempts preferences. The anim_timeout attribute accepts a floating-point value in units of seconds; its default value is 3.0 seconds. The anim_attempts preference accepts an integer value; its default value is 5 retries. The default values of these attributes have been determined to provide a viable connection in a fairly loaded LAN environment.

Figure 12: Specifying Retransmission Parameters Using the anim_timeout and anim_attempts Flags

% op_runsim -net_name angen -anim_view -anim_host guardian \
	-anim_timeout 2.5 -anim_attempts 8

In many user installations, the parameters that affect direct viewing of animation flows will stay constant over relatively long periods of time. Thus the corresponding preferences can be assigned stable values in the preferences file. Notice that the anim_view preference is not typically assigned in the preferences file, since the decision to select the direct viewing option is best left open until a simulation is executed.

Figure 13: Setting Animation Communication Parameters in the Preferences File

<...>

# animation communication parameters
anim_host:      guardian
anim_port:      6
anim_attempts:  8
anim_timeout:   2.5
<...>

This first packet received by op_vuanim from a simulation indicates that an animation flow will follow. As a result, op_vuanim enters an active mode for the playback of the animation flow. The initial mode of the animation flow is paused; the flow will not begin playback until a playback operation is activated from op_vuanim’s button panel. The buttons associated with operations that control the playback are shown in Figure 14; more information on these operations is presented later in this chapter.

Figure 14: op_vuanim Animation Playback Operation Button

op_vuanim Animation Playback Operation Button

Until an accepted animation flow is terminated by the simulation or by an op_vuanim user action, op_vuanim will not accept an animation flow from another simulation. If another simulation attempts to establish communications, op_vuanim issues an error message and the rejected simulation issues an error message while continuing to execute without sending further animation packets to op_vuanim. Likewise, when playing back an animation history file, op_vuanim will reject an incoming animation flow.

Figure 15: Animation Messages in op_vuanim Status Bar: Examples

Animation Messages in op_vuanim Status Bar: Examples

Most animation flows are not self-contained; i.e., they depend on the existence of other referenced resources to be properly displayed without error. Examples of other referenced resources are models used as the diagram context for animations, maps used as model backdrops, trajectory or orbit files used as movement paths, and user-defined icons. These resources are referenced in the animation flow data, rather then being fully integrated, in order to avoid redundant storage of the resources and any associated version-consistency problems. However, the referencing of resources introduces the problem of access to these resources. Provided that op_vuanim is executing in a user context (as defined by the preferences file and the model directories referenced therein) that includes the needed resources, an animation flow with resource references can be properly played back by op_vuanim. In situations where an animation flow is being displayed by a op_vuanim process in a different user context or host computer than the source simulation, the referenced resource files must be copied to the op_vuanim process environment so that it can properly access and utilize them in the animation playback.

History Files

In the animation history file option, animation flow data is routed from an executing simulation into a binary data file that grows in size as the simulation progresses. When a simulation producing an animation history file is completed, the history file can be loaded and viewed in op_vuanim. History files provide the following benefits:

  • long-term storage of an animation in a format that can be immediately viewed with no additional preparation
  • elimination of animation latency caused by simulation computation and inter-process communication and synchronization
  • repeated viewing of an animation without recomputation
  • convenient format for transmission of animations to colleagues

Animation history files are the favored option for animation routing, due to the time savings they afford. In most cases, the direct-viewing alternative is used primarily with the simulation debugger because animation history files cannot be viewed during a simulation run and therefore cannot serve as a feedback mechanism for a debugging session.

Figure 16: Flow Routing Option: History File

Flow Routing Option: History File

The history file option is specified by the anim_hist preference of simulations. This string attribute accepts the base name of the animation history file, without the file’s path or type suffix. The file type suffix .ah (an acronym of “animation history”) is appended to the base name. Note that new animation history files are stored in the primary model directory, and are not coupled to the location of the simulation that generated them.

Figure 17: Specifying a History File via the anim_hist Flag

% op_runsim -net_name angen -anim_hist ang2

After an animation history file is created, and the simulation that generated it has finished executing, the history file can be read into op_vuanim via the Read Animation History operation.

After a selection from the menu has been made, the header strip text indicates the name of the loaded history file. Unlike typical read operations that deal with models, the Read Animation History operation does not transfer the full contents of the animation history file to virtual memory before displaying it. Instead, a portion of the animation history file is read into a virtual memory buffer that stores the requests until needed in the animation playback. When the buffer has been depleted of requests by the playback procedure, it is again filled from the history file, until the whole history file has been processed through the buffer. The size of the history buffer is fixed at 8 KB, and cannot be modified.

After the initial buffer of an animation history file has been loaded by the Read Animation History operation, the animation flow is active but paused. The flow will not begin playback until a playback operation is activated from op_vuanim’s button panel. Operations that active playback, pause, return to start, etc., are displayed on the next page. Note that these are the same operations that can initiate the playback of a direct view animation, with the addition of the Restart Animation Flow operation, which restarts the currently loaded animation from its beginning.

Figure 18: op_vuanim Animation Playback Operation Buttons

op_vuanim Animation Playback Operation Buttons

The caveat appearing in the last section regarding referenced resources also applies to animation flows derived from history files. Since animation history files may contain references to supporting files such as models, maps, trajectory or orbit files, or icons, the referenced resources must be accessible to op_vuanim to guarantee an error-free animation playback.

Dual Routing

The direct viewing and history file routing options of animations can be combined within a single simulation, so that a simulation’s animation is viewable as the simulation executes, but is also available for repeated viewing later. Dual routing of a simulation’s animation flow is selected by specifying both the anim_view and anim_hist preferences, as shown in Figure 19. Under dual routing, the direct viewing option is still independent of the history file option, so if a user exits op_vuanim and thus shuts down direct viewing of an animation flow, the simulation will continue to produce an animation history file.

Figure 19: Specifying Dual Routing of an Animation Flow

% op_runsim -net_name angen -anim_view -anim_host guardian -anim_hist ang2

Script Files

Although there are only two direct routing options for animation flows generated by a simulation (direct viewing in op_vuanim, or writing to a history file), a detour can be inserted into the animation history file routing option for the purpose of editing or enhancing an animation flow. Animation history files contain binary data that is encoded in a proprietary format, and so cannot be directly manipulated by users. However, animation history files can be converted into animation script files, which are equivalent descriptions of the captured animation flow, encoded in an ASCII scripting language that can be viewed and modified within a standard text editor. Script files can also be converted back into history files, thus providing the ability to edit or add to an animation history file indirectly through the script form.

Conversion of an animation flow between the history file and script file forms is performed by the op_cvanim utility program. op_cvanim determines the direction of conversion by the Boolean value of the preference “reverse”: forward conversion (“reverse” set to FALSE) produces a history file from a script file, and reverse conversion (“reverse” set to TRUE) produces a script file from a history file, as illustrated in the following diagram.

Figure 20: Animation History / Script Conversion

Animation History / Script Conversion

The diagram below puts the conversion cycle into the larger context of animation history routing.

Figure 21: Animation History Editing Data Flow Diagram

Animation History Editing Data Flow Diagram

op_cvanim obtains the base name of the animation from the string preference “m” (the animation base name should not include a file path or file type suffix). The file type suffix .as is appended to the base name to form the animation script file name, and the suffix .ah is appended for the animation history file name. Animation history or script files created by op_cvanim are stored in the working model directory, and are not coupled to the file from which they were converted.

Once in script form, an animation flow is available for symbolic viewing and editing. Each request of an animation flow is described by a single statement in a script (the scripting language is presented in a later section of this chapter). Script editing may include adding new requests, deleting undesirable requests, or modifying the arguments of requests. Animation scripts may also be completely entered manually, for the purpose of prototyping an animation concept. If statements in an animation script have syntax errors, op_cvanim will detect these in the process of converting the script file to a history file, and will issue an error and cancel the conversion.

Animation Probes

An animation routing option can be selected via the simulation preferences anim_view or anim_hist, causing the simulation to activate an animation flow. In the direct viewing option, an activated animation flow will establish communications with the indicated op_vuanim process, and a file will be created in the animation history option. However, an activated animation flow will not contain any animation requests if no animation probes have been applied to the simulation through the probe preference. Animation probes are required to identify the objects enabled for animation request generation. If no probes are specified in a probe list, or if no value is assigned to the probe preference, then no objects are enabled to generate animation requests.

There are three types of animation probes.

  • An automatic animation probe enables an animation algorithm built into the Simulation Kernel called a representation; this algorithm generates a complete animated depiction of a simulation model in a single viewer, including a model diagram and dynamic elements that move or change in the diagram.
  • A custom animation probe enables a simulation object and all of its sub-objects to issue custom animation requests. Custom animation requests are specified by Anim package KPs invoked by user-defined processes or procedures within a simulation, but requests will not be issued into the simulation’s animation flow unless the object containing the process or procedure making Anim invocations is enabled by a custom animation probe.
  • A statistic animation probe animates output vector results that are generated by a corresponding statistic probe.

A probe list can include any number of automatic and custom animation probes, in addition to non-animation probes. The animation requests enabled by animation probes are combined into the single simulation animation flow, interleaved in the order of generation. Animation probes are generally independent and do not affect each other; the only exception to this occurs when a custom animation probe references the same object as another custom animation probe, or an object hierarchically affected by another custom animation probe. For a description of this type of interaction, see Custom Probes.

Automatic, custom, and statistic animation probes share a large number of common attributes that specify data required by all probes, and data required to describe the probes’ time range and viewer options. The general probe attributes include the name attribute that identifies the probe object within the probe list, and several attributes used to hierarchically identify the object targeted by the probe. These attributes are not described in detail in this chapter, but the diagram below illustrates the targeting of a simulation object by an animation probe (note that objects are described in an abstract sense).

Figure 22: Simulation Object Targeting by Animation Probes

Simulation Object Targeting by Animation Probes

Two probe attributes define the time range over which an animation probe will enable animation requests issued from its targeted objects. These attributes are described in the table below. By default, the anim start attribute has a value of 0, and the anim stop has an infinite value; unless these attributes are explicitly assigned different values, an animation probe will be in effect during the full duration of a simulation. Setting the anim start attribute to a positive, non-zero value, or setting the anim stop attribute to a value less than the duration of the associated simulation will result in a reduced time range for the probe. Restricted probe time ranges are useful in limiting an animation to only interesting events that fall within a specific segment of time. Since each animation probe has its own time range attributes, the aggregate time range of an animation flow actually spans the earliest probe start time and the latest probe stop time.

Table 14: Time-Range Attributes of Animation Probes

Name Type Units Description
anim start double seconds specifies the start time of the probe’s effect
anim stop double seconds specifies the stop time of the probe’s effect

Figure 23: Union of Animation Probe Time Ranges

Union of Animation Probe Time Ranges

Animation probe time ranges are not entirely strict; a few types of animation request can "cut through" the limits of a time range, adding themselves to a simulation’s animation flow even though the request times fall outside of the nominal time range of the associated animation probe. The request types that cut through probe time ranges have the following common properties: (a) they don’t directly perform a graphical operation in a viewer; (b) they create an animation resource that is needed by later animation requests. If these types of requests were blocked when issued outside of their associated time range, the associated resources would not exist and later animation requests would cause errors upon referring to the missing resources. Activities that can cut through time ranges include the creation of viewers, and the creation and definition of macros (introduced later in this chapter).

Viewers are an important part of the animation playback environment. Viewers define a display region for a series of related animation requests. All animation probes specify the parameters of an associated viewer using a group of five attributes that are listed in Table 15; however, automatic and custom animation probes create viewers under different conditions. Every automatic animation probe creates a viewer with the specified name and initial size, and directs all the animation requests it enables to its viewer. A custom animation probe only creates a viewer based on the probe’s specified parameters if objects it enables issue animation requests that reference the probe’s viewer; other animation requests enabled via custom animation probes may create their own viewers in accordance with the design of the custom animation. Therefore the viewer specified by a custom animation probe may be ignored by some or all of the custom animation requests that it enables.

Four of the five animation probe viewer attributes specify the initial size and location of the viewer’s visible region in workspace coordinates. All of these values can be changed during animation playback within op_vuanim, via a user operation. The initial scroll position of a probe’s viewer cannot be specified in the probe object; it is fixed at the origin of the viewer’s coordinate system. A viewer’s scroll coordinate can be changed through an Anim Kernel Procedure, or by user operations in op_vuanim.

Table 15: Viewer Attributes of Animation Probes

Name Type Units Description
window name string N/A specifies the name of the viewer, a string that appears in the banner at the bottom of the viewer
window x integer pixels specifies the initial X coordinate of the viewer’s upper-left corner in the context of the workspace coordinate system
window y integer pixels specifies the initial Y coordinate of the viewer’s upper-left corner in the context of the workspace coordinate system
window width integer pixels specifies the initial width of the viewer’s visible region
window height integer pixels specifies the initial height of the viewer’s visible region

Figure 24: Animation Probe Viewer Name Configuration

Animation Probe Viewer Name Configuration

Figure 25: Animation Probe Viewer Size and Location Configuration

Animation Probe Viewer Size and Location Configuration

Automatic Probes

An automatic animation probe is set for a single simulation object, and enables requests that create a single animation viewer and perform graphical operations within it. In order to "animate" the probed object, the Simulation Kernel generates animation requests that display the model diagram that defines the internal structure of the object, in addition to superimposed dynamic elements. For a given model type, the Simulation Kernel may support several different animation algorithms, known as representations. An animation flow can include multiple automatic animation representations, but each must be separately enabled by its own automatic animation probe. A single object can even be probed for different simultaneous representations.

In addition to the general animation probe attributes, automatic animation probes must specify the respective representations they generate. The representation enabled by an automatic animation probe is specified by the representation attribute, displayed in the following table. The possible values of this attribute depend on the type of object being probed.

Table 16: Special Automatic Animation Probe Attributes

Name Type Description
representation string specifies the name of the automatic animation representation that the probe enables

Custom Probes

A custom animation probe is set for a single simulation object, but it affects all the objects contained within the directly probed object. Custom animation probes enable the set of probed objects to issue custom animation requests. The direct sources of custom animation requests are invocations of the Anim package KPs by processes or procedures associated with simulation objects. If an object contains an animation request-generating process, the requests will only be added to the simulation’s animation flow if a custom animation probe enables requests from the object.

Multiple custom animation probes may be defined in a probe list, and they may be defined in hybrid probe lists that also include automatic animation probes. A custom animation probe is independent of all other custom animation probes if it references an object that is not hierarchically related to any other probed object. On the other hand, a custom animation probe may overlap another custom animation probe by probing an object that is hierarchically related to the other probe’s object. Custom animation probes with overlapping regions of influence produce the following effects: (a) the general request-enabling effect of custom animation probes is simply applied to a region of influence that is the union of the probes’ independent regions of influence; (b) if a process or procedure associated with an object within the intersection of the probe regions of influence issues an Anim package KP with the viewer ID argument set to the symbolic constant OPC_ANIM_ANVID_PBSPEC, then only one of the probe-specified viewers will display the KP’s result (the affected viewer depends on the order of the probes in the probe list).

In addition to the general animation probe attributes, custom animation probes include an optional probe attribute (label) that can be used to restrict the influence of the probes to Anim package KP invocations that rely on the existence of a particular probe label. If a value is assigned to the “label” attribute, the custom animation probe is considered a labeled probe (a custom animation probe with no value assigned to “label” is considered an unlabeled probe). Labeled probes sacrifice the ability of unlabeled probes to enable animation requests generally throughout their region of influence. Instead, a labeled probe only enables requests from Anim package KP invocations that reference the probe’s associated viewer ID. A labeled probe’s viewer ID can be obtained by invoking the KP op_anim_lprobe_anvid() and passing the probe’s label. Labeled probes provide a useful mechanism for defining custom animation features within a simulation that can be independently enabled or disabled.

Table 17: Special Custom Animation Probe Attributes

Name Type Description
label string specifies the probe is labeled, and provides the label text

Statistic Probes

Statistic animation probes produce dynamic graphs of simulation results. To get this result, you:

  • Define a node or link statistic probe to cause the statistic’s data to be collected
  • Define a statistic animation probe which displays the collected data

The output of a statistic animation probe is displayed in an editor window. See Chapter 1 “User Interface” on page 1 for details.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com