Utility Programs Reference Manual 1 op_vuanim Utility

Transcription

1 1 op_vuanim Utility Animations of simulations provide useful support for analyzing, verifying, and troubleshooting dynamic models. Simulations developed within OPNET s modeling editors offer animations for investigating the behavior and performance of dynamic models. This chapter describes the overall architecture of OPNET s model animation system, as well as the usage of the op_vuanim program, which provides a means of viewing animations both during simulation, and afterwards. Animation System Architecture The model animation system architecture is the basis for animation services within OPNET products. It addresses the basic range of animation-related issues, from animation generation via simulation to animation viewing within the op_vuanim program. Topics covered in the discussion of the animation system architecture include: definitions of fundamental animation concepts such as animation flow, animation request, and viewer animation data routing options, which include direct viewing and animation history files animation activation mechanisms, which include simulation environment attributes and animation probes conversion of animations between the history file and script file forms detailed presentation of the syntax and function of animation script files In defining the animation architecture, it is necessary to reference standard, contingent components and systems within OPNET products, such as: simulation: one output product of OPNET modeling environments is a simulation, a stand-alone program that performs event-driven modeling of a system. Simulations can generate animations as a form of documenting the dynamic characteristics of the modeled system. Simulation Kernel: simulations are built from OPNET-supplied and user-defined components; the core OPNET simulation algorithms and services are contained in a object code library known as the Simulation Kernel, which is linked into simulations as they are built. Animation generation is one of many services supported by the Simulation Kernel. Modeler/Release 10.0 UP-1-1

2 Kernel Procedure: the programming interface of the Simulation Kernel is defined by a set of Kernel Procedures (often abbreviated as KPs) which each perform a particular operation for processes and procedures within a simulation. KPs are organized into packages that address particular simulation services. Animation services are provided by the Anim package of KPs within the Simulation Kernel. simulation debugger: the Simulation Kernel incorporates a command-driven debugging interface for analyzing and controlling simulation behavior, known as the simulation debugger. The simulation debugger supports single-event control of simulation execution, and provides many diagnostic information features. probe: by default, simulations do not typically generate files of output data; instead, specific results of interest to the user are specified by probes set on particular simulation objects. Probes are contained within a file known as a probe list, which is applied to simulations to activate data collection. Animation probes support the activation of animation data generation within a simulation. Animation Fundamentals OPNET animations can be produced and recorded during simulations. Animations and simulation runs have a one-to-one correspondence. Multiple simulation runs cannot contribute to a single animation. A simulation cannot produce more than one animation. UP-1-2 Modeler/Release 10.0

3 When a simulation run is initiated, the user specifies whether animation data will be recorded and how it will be routed. If record animation is specified, all animation data generated by a simulation run will be routed as indicated, contributing to a single animation. A simulation cannot change the routing of animation data while executing. Figure 1-1 Simulation/Animation Relationships Supported: simulation animation Not Supported: simulation animation simulation animation Not Supported: simulation animation Animations depict dynamic simulation conditions. As simulation events occur at various points in simulation time, they generate animation data that is tagged with the associated simulation time. Thus, all animation data are associated with simulation time values. An animation time range always falls within the time range of the associated simulation run. Simulation runs have a beginning and an end in simulation time; likewise, their associated animations have beginnings and ends in simulation time. The first animation data generated by a simulation may begin later than T=0, and the last animation data generated by a simulation may occur well before the end of the run. However, animation data can never occur at negative times, or at times later than the end of the associated simulation run. As a simulation producing an animation progresses, it typically generates animation data at a large number of irregularly spaced points in simulation, which are spread in small bursts throughout the simulation. Animation data depicting a simulation event is usually produced as soon after the event as possible, so that (synchronized viewing of animation data is possible (i.e., viewing the animation output of a simulation event shortly after it occurs, and Modeler/Release 10.0 UP-1-3

4 before the simulation progresses to another event. The previous statements are usually true, but since users can generate custom animations through flexible Kernel Procedure invocations, it is possible to cluster the output of animation data into only a few large bursts that occur at the beginning, end, or some intermediate point in a simulation.) Because animations are described by bursts of data that occur over a range of time, these bursts form a flow of data. The term animation flow refers to the sequence of animation data generated by a simulation run. As will be explained later in this chapter, animation flows can be stored in a file, conveyed to another process using network protocols, or processed and displayed by a viewing program. Figure 1-2 Comparison of Typical Simulation and Animation Flow Time Ranges time range of simulation run T=0 T=t sim. end time range of animation flow T=0 T=t anim. end Bursts usually consist of animation data generated at the same simulation time. The fine-grain structure of bursts is a series of animation requests. Animation requests are the smallest units of animation data. Each animation request is associated with a single simulation time, a single simulation event, and a single source within the simulation (e.g., a specific process). Typically, animation flows will contain thousands of animation requests. There are over forty types of animation requests supported by the OPNET system. New types of requests cannot be defined by users. Simple animation requests describe a single graphical operation, such as drawing a line, and contain all the data required for the operation. A more complex animation request may describe a compound graphical operation, such as moving a symbol along a path. Such a request will depend on data contained in other requests--however, no matter how complex an animation request is, it never describes graphical operations associated with different simulation times or events. UP-1-4 Modeler/Release 10.0

5 Thus it is possible to segment an animation flow according to simulation times or events; such divisions always occur on request boundaries since these properties never change within a single animation request. Figure 1-3 Animation Flows are Composed of Animation Requests animation request: R animation flow: R R R R R R R R R R R R time T=0 T=t anim. end association of requests with simulation events and times: R R R R R R R R R R R R R R R R (T=10,Ev=210) (T=10,Ev=212) (T=14,Ev=216) (T=14,Ev=220) Animation flows can describe graphical operations performed within one or more abstract display regions called viewers. A viewer is a rectangular region with an internal coordinate system. Most animation requests are targeted to a particular viewer, as identified by a viewer ID contained within the request. Some administrative requests deal with animation-wide issues, and do not generate visible output in a particular viewer; these requests do not contain viewer IDs. Viewers can be opened or closed by specific request types at any stage of an animation flow. However, viewers must be opened before requests can be targeted to them. Once a viewer has been closed, it cannot accept any further requests. Animation requests specify graphical operations in terms of viewer coordinates. Each viewer has its own coordinate system, but the viewer coordinate systems share the following common properties: two-dimensional (X is the horizontal axis, Y is the vertical axis) origin is the upper-left corner positive X direction points right, positive Y direction points down only integral, non-negative coordinates are supported; the upper limit on coordinate values is 32,766 coordinates are measured in units of pixels coordinate system extends beyond visible region of viewer Modeler/Release 10.0 UP-1-5

6 The request that opens a viewer specifies its location within the workspace coordinate system, and its initial size. Viewers may have intersections within the workspace, in which case the viewers that are opened later will initially overlap the viewers opened earlier. The size of a viewer determines the rectangular region of the viewer s coordinate system that is visible, but it does not limit graphical operations from being performed outside of this visible region. The visible region of a viewer can be changed by scrolling the viewer via a specific request type. Due to the limitations of the viewer coordinate system, the visible region cannot be scrolled into the (X,Y) plane quadrants with negative coordinate values. Figure 1-4 Animation Viewers within Workspace Coordinate System origin +Y +X workspace coordinate system coordinates of viewer locations in workspace animation viewer visible region animation viewer visible region UP-1-6 Modeler/Release 10.0

7 Figure 1-5 Animation Viewer Coordinate System origin +Y +X viewer coordinate system scroll coordinate visible region The abstract concept of a viewer is realized within the animation viewing program op_vuanim, which creates editor windows for each viewer. Viewer windows can be manipulated using the standard GUI operations for moving, resizing, scrolling, and circulating windows. These operations do not affect the animation being viewed, but change the presentation of the animation. Details of op_vuanim features appear later in this chapter. 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 environment attributes and animation probes within a probe list applied to the simulation. Besides activating a flow, the animation-related environment attributes 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 environment attributes and animation probes, are discussed 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 environment attributes, no animation flow will be generated. Each of these routing options are discussed in separate subsections below. Modeler/Release 10.0 UP-1-7

8 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 1-6 Flow Routing Option: Direct Viewing local viewing scenario: common host computer simulation process animation flow op_vuanim process remote viewing scenario: sim. host computer viewing host computer simulation process animation flow local area network op_vuanim process UP-1-8 Modeler/Release 10.0

9 The direct viewing option is specified by the anim_view environment attribute 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 environment attribute assignments may need to be provided to specify communication parameters. Figure 1-7 Specifying Direct Viewing via 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 1-8 Animation Flow Communication Over UDP/IP encapsulated request packets flow to the op_vuanim process simulation process R UDP IP IP UDP A R UDP IP IP UDP A op_vuanim process encapsulated acknowledgment packets flow to the simulation process Note: the packets in this diagram are only intended to depict data types and flow directions; except in special conditions, there is no more than a single packet in transit between the simulation and op_vuanim processes at a time. Modeler/Release 10.0 UP-1-9

10 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 environment attribute. 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 environment attribute is localhost, which usually translates to the loopback address of the simulation host computer. Thus the anim_host environment attribute typically does not need to be specified in the local viewing scenario. Figure 1-9 Specifying the op_vuanim Host via 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 This relative port offset is known as the animation port, and is specified to both op_vuanim and simulations via the anim_port environment UP-1-10 Modeler/Release 10.0

11 attribute. The default value of anim_port is 0, so that the default UDP port number is = 3211; setting anim_port to 5 will result in a UDP port number of = 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 1-10 Matching Simulation and op_vuanim Animation Ports % op_runsim -net_name angen \ -anim_view -anim_port 11 % op_vuanim -anim_port simulation process UDP port (OS-assigned #) anim. requests UDP port (# 3222) op_vuanim process 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 environment attribute. 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 Modeler/Release 10.0 UP-1-11

12 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 environment attributes. The anim_timeout attribute accepts a floating-point value in units of seconds; its default value is 3.0 seconds. The anim_attempts environment attribute 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 1-11 Specifying Retransmission Parameters via 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 environment attributes can be assigned stable values in the Environment Database, as shown on the next page. Notice that the anim_view environment attribute is not typically assigned in the Environment Database, since the decision to select the direct viewing option is best left open until a simulation is executed. Figure 1-12 Setting Animation Communication Parameters in the Environment Database <...> # 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. Acceptance of the animation flow is indicated by a message in the message area and header strip text that indicates the name of simulation. The initial mode of the animation flow is paused; the flow will not UP-1-12 Modeler/Release 10.0

13 begin playback until a playback operation is activated from op_vuanim s button panel. The buttons associated with operations that can initiate the playback are displayed on the next page; more information on these operations is presented later in this chapter. Figure 1-13 Animation Flow Acceptance Messages op_vuanim header strip op_vuanim 8.0.A (c) 2001 OPNET Technologies, Inc. Paused Simulation: rtesamp.sim op_vuanim message area flow type indication and simulation name simulation name and host computer Figure 1-14 op_vuanim Animation Playback Operation Button play anim. flow step to next anim. request step to next sim. event step to next sim. time Modeler/Release 10.0 UP-1-13

14 Figure 1-15 Animation Flow Rejection Messages op_vuanim message area 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. Should another simulation attempt to establish communications, op_vuanim will issue an error message, and the rejected simulation will issue 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. simulation name and host computer simulation error message 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 Environment Database 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. UP-1-14 Modeler/Release 10.0

15 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 1-16 Flow Routing Option: History File during simulation: after simulation: simulation process animation flow animation history file growth during simulation execution animation history file animation flow op_vuanim process Modeler/Release 10.0 UP-1-15

16 The history file option is specified by the anim_hist environment attribute 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 1-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. Once 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. Figure 1-18 Read Animation History Operation Button Animation History Header Strip Example op_vuanim header strip op_vuanim 8.0.A (c) 2001 OPNET Technologies, Inc. Paused Simulation: tdout flow type indication and history name 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. UP-1-16 Modeler/Release 10.0

17 Figure 1-19 op_vuanim Animation Playback Operation Buttons Play Pause Restart Terminate Slower Animation Faster To Next Event dddd To Next Time dddd To Next Animation Request 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 environment attributes, as shown in Figure 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 1-20 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 OPNET 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. Modeler/Release 10.0 UP-1-17

18 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 environment attribute 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 1-21 Animation History / Script Conversion forward conversion op_cvanim animation script file animation history file op_cvanim -reverse reverse conversion The diagram below puts the conversion cycle into the larger context of animation history routing. Figure 1-22 Animation History Editing Data Flow Diagram simulation process op_cvanim Text editor animation script file animation history file op_cvanim -reverse op_vuanim process UP-1-18 Modeler/Release 10.0

19 op_cvanim obtains the base name of the animation from the string environment attribute 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 environment attributes 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 environment attribute. 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 environment attribute, 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. Modeler/Release 10.0 UP-1-19

20 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, refer to Custom Probes on page UP 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 discussed 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 1-23 Simulation Object Targeting by Animation Probes Probe Object Reference level 1 object A level 1 object A level 2 object M level 2 object M level 3 object Probe Object Reference level 1 object A level 2 object O level 3 object Z level 2 object level 3 object O Z 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 UP-1-20 Modeler/Release 10.0

21 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 1-1 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 End of Table 1-1 Figure 1-24 Union of Animation Probe Time Ranges time range of simulation run T=0 T=t sim. end time range of anim. probe 1 time range of anim. probe 2 time range of animation flow 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 1-2 on page UP-1-22; 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 Modeler/Release 10.0 UP-1-21

22 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 1-2 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 End of Table 1-2 Figure 1-25 Animation Probe Viewer Name Configuration viewer name UP-1-22 Modeler/Release 10.0

23 Figure 1-26 Animation Probe Viewer Size and Location Configuration +Y +X workspace coordinate system (window x, window y) window height probe viewer visible region window width 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 1-3 Special Automatic Animation Probe Attributes Name Type Description representation string specifies the name of the automatic animation representation that the probe enables End of Table 1-3 Modeler/Release 10.0 UP-1-23

24 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 1-4 Special Custom Animation Probe Attributes Name Type Description label string specifies the probe is labeled, and provides the label text End of Table 1-4 UP-1-24 Modeler/Release 10.0

25 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. Refer to the User Interface chapter in the Editor Reference manual for details. Automatic Animation Features Automatic animation probes can be set on subnets, nodes, and modules to generate an animation representation. There are three types of representations: node movement, packet flows, and state tracking. These are summarized in the following table. Table 1-5 Automatic Animation Representations Representation Object(s) Being Probed Description node movement subnetworks Displays the movement of mobile and satellite nodes within a subnetwork. packet flows subnetworks, nodes (fixed, mobile, and satellite) Displays packets being sent over point-to-point links, bus links, and taps within a subnetwork; displays packets being sent over packet streams within a node. state tracking processors, queues Displays the active state of the root process of a processor or queue module. End of Table 1-5 Node Movement Representation If an automatic animation probe is set on a subnetwork, the node movement representation can be selected. This representation displays the movements of nodes within the selected subnet. The application of this representation is viewing the movement of mobile and satellite nodes along trajectories and orbits. Fixed nodes are displayed, but do not move in this representation. The diagram below provides an example of how node movement animation will Modeler/Release 10.0 UP-1-25

26 appear within op_vuanim. In this example, an automatic animation probe has been placed on the mrt_sub subnet. The animation shows the movement of the jam mobile node along its trajectory. The diagrams show the animation of node movement at two different simulation times. Figure 1-27 Example of Node Movement Representation 11 seconds into the simulation 3 minutes, 56 seconds into the simulation You can also set the packet flows or the packets flows and node movement (shown as pk flows & nd mvmt) representations on a subnet. Packet Flows Representation If an automatic animation probe is set on a subnetwork or a node, the packet flows representation can be selected. This representation displays packets being sent over certain types of paths: point-to-point links or bus taps in a subnetwork, or streams in a node (note that bus packet flows are displayed on the bus taps, not the bus links themselves). Packets are represented by traversal marks, which appear as yellow dots moving along the paths (note that all colors mentioned in this section will appear as black on monochrome monitors). Once a packet has traversed a path, a small red arrow indicating the flow direction is permanently displayed near the middle of the path. Such arrows are useful for visually determining which paths have been traversed. There are several variations in the identification of packets in the packet flows representation. On point-to-point links or streams, a packet traversal mark is identified by its associated packet ID, displayed near the mark as a yellow number (a packet ID is a serial number that uniquely identifies a packet within a simulation). Depending on the angle of the path, a packet's traversal mark and ID number may be visually tied by a short yellow line segment. On bus taps, a packet traversal mark is identified by both its associated packet ID and its UP-1-26 Modeler/Release 10.0

27 packet tree ID displayed near the mark as two adjacent yellow numbers (the packet tree ID is the right-most number of the two, and it is surrounded by parentheses). A packet tree ID is a serial number that uniquely identifies a "tree" of packets that are all copies of a single original packet; packet trees are only created when new packets are created, but not when packets are copied). If paths are very short, there is not enough space to display packet traversal marks. If packets are sent on such paths, a red number surrounded by parentheses is displayed on the path, representing the quantity of packets currently traversing the path. This quantity is distinguishable from other IDs by its red color, surrounding parentheses, and the lack of an adjacent packet traversal mark. Packet traversal marks (and their identifying numbers) represent packets being sent over paths. The animation intervals in which packet traversal marks are displayed correspond to the intervals in which the represented packets were undergoing transmission. The animation of the marks consists of two major steps: (1) to represent a packet beginning transmission, the corresponding mark appears at the source end of the path and moves to a resting point near the middle of the path; (2) to represent a packet ending transmission, the corresponding mark moves from the middle of the path to the destination end of the path, and disappears. When packet transmission happens over a short timespan, the two animation steps of a packet traversal mark may be immediately consecutive in an animation, and thus visually merge so that it seems the traversal mark did not stay at the resting point near the middle of the path at all. In addition, under some conditions packet traversal marks undergo a compressed, one-step animation in which the mark moves along the whole path without resting; this occurs on streams with the forced delivery method. If more than one packet is being sent on a path at the same time, multiple packet traversal marks "stack up" near the middle of the path, on the half of the path closer to source object. The stack of marks on the path builds in order of arrival, towards the source object. The possibility of multiple traversal marks appearing on a single path depends on the type of path, as described in the points below: Point-to-point links and bus taps can have multiple channels, and the packet flows representation merges the packets of all channels of a path without specifically identifying them with their channel. Thus multiple packet traversal marks may appear concurrently on a multi-channel link or tap, representing packets on different channels. Even on single-channel point-to-point links, multiple packet traversal marks may appear concurrently. If a packet begins transmission at the exact time that another packet ends transmission, the traversal marks for both packets will appear together just at the time of transition. Duplex point-to-point links and bus taps are bi-directional, so packets being received and transmitted are both represented, on opposite sides of the path's middle. Modeler/Release 10.0 UP-1-27

28 The reception of multiple concurrent packets on a single channel of a bus tap is not represented by multiple packet traversal marks; instead, the collision is represented by a red box with an inscribed "X" that appears over the first packet's traversal mark just before that mark is erased. Multiple traversal marks can appear on packet streams in nodes if the packets are sent with the scheduled delivery method, and there is either a delivery delay or multiple packets are forwarded over the same stream at the same time. The following diagram illustrates the packet flows representation in a bus-based network. Figure 1-28 Example of Packet Flows Representation packet ID packet traversal marker packet tree ID number of packets traversing the link (short links) State Tracking Representation If an automatic animation probe is set on a processor or queue, the state tracking representation can be selected. This representation displays the diagram of the root process inside the processor or queue being probed. A square outline appears around the initial state, and moves from one state to the UP-1-28 Modeler/Release 10.0

29 next as the root process is interrupted and responds by executing actions and choosing transitions. This animation allows users to gain a better understanding of the process model and external condition dynamics. The following example shows the state tracking of a process model at two different simulation times. Figure 1-29 Example of State Tracking Representation square outline indicates current state Custom Animation Features The Anim package of Kernel Procedures within the Simulation Kernel supports full generality in user-defined animations. Within the documentation of the Anim package, detailed information is provided about KP syntax, functionality, and usage. However, some custom animation features are based on sophisticated interactions of components within the animation architecture, and these features require the presentation of additional conceptual information in this section. Animation Macros The animation macro feature provides a way to build a simple but convenient tool : a group of parameterized animation requests that can be executed by a single KP invocation to accomplish a common animation task. Animation macros do not provide complex control structures and do not qualify as a fully general programming language. Instead, they are small groups of animation requests that have been combined and given a unique identifier for invocation. However, macros do offer several properties that increase their scope and descriptive power, as presented below: Parameterization: macros support the definition of parameters that can be used as the values for almost all arguments of requests in the macro. This facilitates the definition of general-purpose macros that can be applied to different tasks through parameter specification. Modeler/Release 10.0 UP-1-29

30 Re-invocation: macros support multiple re-invocations with parameter changes, while retaining parameters and other state memory that can be reused. This reduces the number of animation requests and argument values that need to be specified to accomplish a recurring animation task, such as moving a graphical object according to a dynamic stream of data. Specialization: macros are divided into several sections that can be independently executed under different conditions. This facilitates the comprehensive bundling of related animation requests, especially when some of the requests must only be issued once to initialize state memory, but other requests that use the state memory must be repeatedly issued. Macros consist of a series of animation requests issued by op_anim_mgp and op_anim_mme KPs (Mgp stands for Macro-Oriented Graphics Primitive and Mme stands for Macro-Oriented Model Element). These KPs reference a macro ID that was assigned when a macro was created, and rather than actually performing a graphical operation, they just append a specification for a graphical operation to the end of the referenced macro. The construction methodology for macros is detailed on the next page. 1) A macro is created by invoking the KP op_anim_macro_create(); this causes memory for the macro definition structure to be allocated, and returns a macro ID to the invoking process or procedure. When created, macros are empty of animation requests, but are open (i.e., they can accept animation requests). 2) Macros are defined one animation request at a time by invoking op_anim_mgp() or op_anim_mme() KPs and referencing the macro ID obtained in step (1) above. Each such KP invocation appends an animation request to the end of the macro (when invoked, macros execute their requests in First-Come, First-Served (FCFS) order, starting at the beginning and moving towards the end of the macro). Once an animation request has been added to a macro, it cannot be removed or edited. Thus macros grow monotonically. 3) When a macro has been fully defined, no further animation requests need to be appended to its end, and the macro can be closed to prevent this. The KP op_anim_macro_close() closes a macro. UP-1-30 Modeler/Release 10.0

31 The definition of a typical macro is shown below. Note the rejection of the request issued by the Mgp invocation, due to the macro s closed state. This feature of closed macros is useful in simulations involving multiple instances of the same process, and will be revisited later in this section. Figure 1-30 Definition of Example Macro op_anim_macro_create() op_anim_mgp_circle_draw() op_anim_mgp_icon_draw() op_anim_mgp_text_draw() op_anim_macro_close() op_anim_mgp_circle_draw() macro: draw symbol mgp_circle_draw mgp_icon_draw mgp_text_draw Macros support state memory through a mechanism based on registers. Each macro can access up to 26 registers, named A-Z, and all the registers are identical in capability and access methods. Every time a macro is invoked, or drawn, a new bank of 26 registers is allocated for use by the macro instance (known as a macro drawing). Macro drawing registers are retained in memory for as long as their associated macro drawing is retained. Thus a macro drawing s bank of registers is dedicated to the use of that drawing, and can serve as its state memory. Registers can hold all three basic macro data types: integers, doubles, and strings. When a register is assigned a value, the register is identified by name and data type, and it stores its value using the indicated data type until it is assigned another value. Registers may be assigned values by the requests issued by two op_anim_mgp() KPs: op_anim_mgp_reg_set() issues a request that assigns a specified value to a register, and op_anim_mgp_arop() issues a request that assigns the result of an binary arithmetic operation to a register (the two operands of the operation are also registers). Modeler/Release 10.0 UP-1-31

32 The values of registers may be used to provide the argument values for any macro request issued by an op_anim_mgp() or op_anim_mme() KP. Registers are referenced by passing special symbolic constants to the arguments of these KPs, instead of constants or expressions that are resolved to literal values. The ranges of register name symbolic constants are displayed below. Figure 1-31 Macro Drawing Register Symbolic Constant Ranges integer values OPC_ANIM_REG_A_INT OPC_ANIM_REG_Z_INT double values OPC_ANIM_REG_A_DBL OPC_ANIM_REG_Z_DBL string values OPC_ANIM_REG_A_STR OPC_ANIM_REG_Z_STR In addition to being assigned values by macro requests, registers may be assigned values by the KPs that invoke macros. The KPs op_anim_igp_macro_draw() and op_anim_igp_macro_redraw() both invoke a macro after assigning values to the macro drawing s registers. The combination of macro invocation and register value assignment provides the required technology for parameterizing macros: the parameters of a macro are assigned values by the argument list of the macro invocation KPs, and these parameters are used as arguments for selected macro requests. The two macro invocation KPs accept variable-length argument lists that are terminated by the symbolic constant OPC_EOL, and can perform 0 to 26 register assignments in one invocation. The differences between these KPs are discussed below: op_anim_igp_macro_draw() invokes a macro specified by its macro ID, after it has allocated a drawing context with a bank of registers, and performed the required initial register assignments; this KP is intended for initially drawing a graphical object within a viewer. op_anim_igp_macro_redraw() re-invokes the macro of an existing macro drawing, after it has performed the required update assignments to registers; this KP is intended for modifying selected properties of a macro-produced graphical object retained within a viewer, and redrawing the object to reflect these new properties. Macros have two sections: the setup section and the graphics section. Each macro request falls into one and only one of these sections. The setup section is intended for requests that need to be performed once during the first invocation of a macro, such as a request that initializes some drawing registers based on arithmetic operations applied to the initial values of the macro s "parameter" registers. The graphics section is intended for requests that need to be repeatedly performed during re-invocations of a macro. Every macro has both sections defined, but it is common for macros to have a null setup section (i.e., to have all requests in the graphics section). By default, Mgp or Mme requests appended to the end of a macro are considered to be in the graphics section. In order for animation requests to be placed within a macro s setup UP-1-32 Modeler/Release 10.0

33 section, these requests must be appended to the macro all together before any graphics section requests, and followed by the request issued by the KP op_anim_mgp_setup_end() (the request issued by this KP demarcates the "border" in the macro request list that divides the setup section and the graphics section). As mentioned previously, macro setup and graphics sections are executed under different conditions, based on their specific roles. The conditions leading to execution of each section are listed below: Under normal conditions the KP op_anim_igp_macro_draw() executes the setup section to initialize the macro drawing, followed immediately by the graphics section, to display the macro s graphical output for the first time. Under normal conditions the KP op_anim_igp_macro_redraw() re-executes only the graphics section of a macro, to redisplay the macro s output based on new register assignments. If the KP op_anim_igp_macro_draw() is passed the graphical property symbolic constant OPC_ANIM_SETUP, only the setup section of a macro will be executed. The graphics section of such a macro is not executed until op_anim_igp_macro_redraw() is explicitly applied to the macro s drawing. If the KP op_anim_igp_macro_redraw() is passed the erase mode symbolic constant OPC_ANIM_ERASE_MODE_XOR_RESET, both the setup section and the graphics section of the macro will be re-executed. A window system redraw or pop-up event may be received by the op_vuanim program, causing a redraw of animation viewers, including the viewers retained macro drawings. In order to redisplay these drawings, the graphics sections of their respective macros are executed. Modeler/Release 10.0 UP-1-33

34 Statistic Animation Features Statistic animation is presented in op_vuanim as graphs of simulation statistics. These plots resemble the analysis panels used in the Analysis Tool, except that they plot the output vector results as the simulation generates them. You can graphically display an output vector result being graphed by specifying a value for the statistic attribute of statistic animation probes. Figure 1-32 Statistic Panel and Viewer Animation Script Reference The animation script language provides a simple syntax for describing an animation flow. An animation script comprises a single list of a flow s requests encoded in the form of statements. Statements are terminated by semi-colons, and may be padded with space or tab characters, split across file lines, combined with other statements on a single line, or surrounded by blank lines. However, it is conventional in scripts to place each statement on its own line, aligned to the left-most character of the line. The format of each statement is the same, and includes the following information: simulation time when the request was issued execution ID of simulation event that was executing when the request was issued request name keyword list of request arguments, separated by spaces or tabs UP-1-34 Modeler/Release 10.0

35 A typical request statement is displayed below. Note that the time, event, and request argument fields are not explicitly labeled within the statement itself; thus the formats of the statement and its associated request are usually needed to decipher the data contents of a statement. Figure 1-33 Example Animation Script Statement viewer_open 2 rtstats ; simulation time event ID request name argument list terminator Each request supported by the animation script language is documented by its own entry later in this section. A request entry presents the syntax format of the request, including the request s name and argument list, but not the simulation time, event ID, or terminator fields of a request statement. An entry also provides a description of each request argument. An example entry appears on the next page. Modeler/Release 10.0 UP-1-35

36 Detailed information on the functionality and purpose of animation script requests is not provided in their entries. For these details, refer to the Animation Package chapter of the Simulation Kernel manual. Functionality information is provided for animation script requests that do not have an exact Kernel Procedure equivalent. Figure 1-34 Example Animation Request Entry request syntax format viewer_open <anvid> <name> <x> <y> <w> <h> <anvid> Anvid viewer ID <name> string viewer name <x> integer X coordinate of viewer upper-left corner <y> integer Y coordinate of viewer upper-left corner <w> integer width of viewer <h> integer height of viewer KP Analog: op_anim_viewer_open() equivalent Anim package Kernel Procedure request argument data In general, for every animation script request type, there is an equivalent Anim package Kernel Procedure (labeled in request entries as the KP Analog). However, there are some special cases in which there is not an exact equivalency, such as: Anim KPs that just provide a local service to simulation processes or procedures without issuing any requests (this case includes op_anim_ime_gen_pos(), op_anim_lprobe_anvid(), and op_anim_macro_close()). Anim KPs that implement a graphical operation by issuing multiple separate requests (this case includes op_anim_ime_nmod_draw(), which issues the ime_nmod_load and ime_mod_draw requests to load and draw a model). Anim KPs with a variable number of arguments that issue an initial request followed by a series of argument-setting requests and a termination request (this case includes op_anim_igp_macro_draw(), op_anim_igp_macro_redraw(), and op_anim_ime_nobj_update(), which UP-1-36 Modeler/Release 10.0

37 respectively issue the initial requests igp_macro_draw, igp_macro_redraw, and ime_nobj_update; the initial requests are followed by a series of arg_int, arg_dbl, or arg_str requests that set integer, double, or string arguments, and then by the arg_eol list termination request). Anim KPs that issue a different request depending on the type of data passed to their arguments (this case include op_anim_mgp_reg_set(), which issues the mgp_reg_set_int, mgp_reg_set_dbl, and mgp_reg_set_str requests). The arguments of animation script requests are all literal constants encoded in ASCII (i.e., there are no variable or macro capabilities in the script language). Argument data types are defined for distinct categories of information, as documented in the table below. Note that these data types are similar in many instances to the corresponding C data types used to declare the arguments of Anim package KPs; however, the script language supports specialized data types and associated assignment syntax to make specification of arguments convenient. Table 1-6 Animation Request Argument Data Types Data Type Example Value Description integer 5 general integer value double 6.73 general floating-point value Internal C Storage Class int or short double string word "several words" general text value; spaces can be included if string is surrounded by double-quotes char [] Anvid 44 viewer ID (integer) int Anmid 32 macro ID (integer) int Andid 12 drawing ID (integer) keyword xor_reset single-word value, from an enumerated set of words int char or short keyword list { retain_on, setup_on } brace-enclosed, comma-separated list of keywords char or short End of Table 1-6 Modeler/Release 10.0 UP-1-37

38 Keywords are defined for many predefined enumerated values, such as request options. These keywords are concise because they rely on the animation-specific nature of scripts, in contrast to the much more verbose Anim package symbolic constants used in simulation processes and procedures. Most of the enumerated keyword values are listed in the argument description section of request entries. UP-1-38 Modeler/Release 10.0

39 The common request argument <props> (graphical properties) has many enumerated values, and these keywords are listed only on the next page. <props> arguments are declared as keyword lists, and they accept a brace-enclosed list of graphical property keywords. Graphical property keywords are categorized into property classes. In general, graphical properties from different classes are independent and can be combined, but graphical properties from the same class will produce unexpected results if combined. Table 1-7 Accepted Keywords for <props> Argument (Part 1 of 2) Property Class horizontal alignment vertical alignment color names / RGB (the keyword prefix <p> may be one of the following: color for foreground color, or bgcolor for background color) color names / standard (the keyword prefix <p> may be one of the following: color for foreground color, or bgcolor for background color) text fonts Keywords alignh_centeralignh_leftalignh_right alignv_bottomalignv_centeralignv_top <p>_rgb000<p>_rgb001<p>_rgb002<p>_rgb003 <p>_rgb010<p>_rgb011<p>_rgb012<p>_rgb013 <p>_rgb020<p>_rgb021<p>_rgb022<p>_rgb023 <p>_rgb030<p>_rgb031<p>_rgb032<p>_rgb033 <p>_rgb100<p>_rgb101<p>_rgb102<p>_rgb103 <p>_rgb110<p>_rgb111<p>_rgb112<p>_rgb113 <p>_rgb120<p>_rgb121<p>_rgb122<p>_rgb123 <p>_rgb130<p>_rgb131<p>_rgb132<p>_rgb133 <p>_rgb200<p>_rgb201<p>_rgb202<p>_rgb203 <p>_rgb210<p>_rgb211<p>_rgb212<p>_rgb213 <p>_rgb220<p>_rgb221<p>_rgb222<p>_rgb223 <p>_rgb230<p>_rgb231<p>_rgb232<p>_rgb233 <p>_rgb300<p>_rgb301<p>_rgb302<p>_rgb303 <p>_rgb310<p>_rgb311<p>_rgb312<p>_rgb313 <p>_rgb320<p>_rgb321<p>_rgb322<p>_rgb323 <p>_rgb330<p>_rgb331<p>_rgb332<p>_rgb333 <p>_beige<p>_black<p>_blue<p>_brick <p>_brown<p>_corn<p>_cyan<p>_fuchsia <p>_green<p>_magenta<p>_maroon<p>_olive <p>_orange<p>_orchid<p>_peach<p>_pink <p>_plum<p>_purple<p>_red<p>_tan <p>_sienna<p>_steel<p>_tan<p>_violet <p>_white<p>_yellow font_open_10font_open_12font_open_14 font_open_18font_open_24 Modeler/Release 10.0 UP-1-39

40 Table 1-7 Accepted Keywords for <props> Argument (Part 2 of 2) Property Class pixel operators macro setup flag drawing styles drawing retention flag Keywords pixop_andpixop_dstpixop_eqvpixop_nand pixop_ndstpixop_nodstpixop_norpixop_nosrc pixop_nsrcpixop_odstpixop_onepixop_or pixop_osrcpixop_osrcpixop_xorpixop_zero setup_offsetup_on style_dashesstyle_dotsstyle_patternstyle_solid retain_offretain_on End of Table 1-7 An example <props> value is shown below; it sets the graphical properties of text drawn by an igp_text_draw request to be 18 point, green, and with alignment based on the top edge: Figure 1-35 Example Text Graphical Property Value { font_open_18, color_green, alignv_top } One other common request argument is declared as a keyword list: the <arg_vals> argument of mgp and mme macro-based requests. This type of argument expects a fixed-size list of keywords that represent the source of values for the other requests arguments. A value source may be: (a) a specified macro drawing register (identified by a keyword of the form reg_<c>, where <C> is a single character); (b) a literal value specified later in the request statement (identified by the keyword constant ). Thus the <arg_vals> argument configures a particular format for the mgp and mme requests, by specifying the number of additional arguments to be expected after <arg_vals>. The size of the <arg_vals> list is determined by the number of arguments supported by a request; this number appears in the request entry declarations of <arg_vals>. An example value for <arg_vals> appears below. Figure 1-36 Example of Value Source Specification in Macro Request mgp_circle_draw 23 { reg_p, reg_x, reg_y, constant } 21; <props> <radius> register P register X <ctr_x> <ctr_y> register Y UP-1-40 Modeler/Release 10.0

41 The mechanism for specifying attribute sources via <arg_vals> presents a complication for optional arguments that are only present when another argument includes a particular value. This situation is limited to the optional <pat_name> argument of the mgp_bg_fill, mgp_circle_fill, and mgp_rect_fill requests, which normally should only be included if the <props> argument includes the style_pattern property keyword. The following special considerations affect these requests: the number of items in the <arg_vals> list is always the same (i.e., a keyword in this list applies to the <pat_name> argument, whether or not <pat_name> is assigned a value from the request statement) if the <props> argument is specified by a literal value in the request statement, and it includes the style_pattern property keyword, and the <arg_vals> argument specifies that the <pat_name> argument expects a literal value, then <pat_name> should appear in the request statement if the <props> argument is specified by a reference to a macro drawing register, and the <arg_vals> argument specifies that the <pat_name> argument expects a literal value, then <pat_name> should appear in the request statement excluding the above cases, <pat_name> should not appear in the request statement Modeler/Release 10.0 UP-1-41

42 Animation Script Requests arg_int <anvid> <arg_id> <value> <anvid> Anvid viewer ID <arg_id> integer argument ID <value> integer argument value KP Analog: None [This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attribute assignable as an integer is color, as specified by an ID of 0).] [When assigning an object s color, the range of accepted values is [0-63].] arg_dbl <anvid> <arg_id> <value> <anvid> Anvid viewer ID <arg_id> integer argument ID <value> double argument value KP Analog: None [This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attributes assignable as doubles are x position and y position, as specified by the IDs 2 and 3, respectively).] UP-1-42 Modeler/Release 10.0

43 arg_str <anvid> <arg_id> <value> <anvid> Anvid viewer ID <arg_id> integer argument ID <value> string argument value KP Analog: None [This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attribute assignable as a string is icon name, as specified by an ID of 1).] arg_eol <anvid> <anvid> Anvid viewer ID KP Analog: None [This request terminates a series of arg_<type> requests, where <type> is either int, dbl, or str. Argument assignment requests follow requests that have a variable number of arguments: igp_macro_draw, igp_macro_redraw, and ime_nobj_update.] force no arguments KP Analog: op_anim_force() Modeler/Release 10.0 UP-1-43

44 flow_end no arguments KP Analog: op_anim_flow_end() igp_bg_fill <anvid> <props> [<pat_name>] [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list [<pat_name>] string pattern name [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_bg_fill() [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] UP-1-44 Modeler/Release 10.0

45 igp_circle_draw <anvid> <props> <ctr_x> <ctr_y> <radius> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list <ctr_x> integer X coordinate of the circle s center point <ctr_y> integer Y coordinate of the circle s center point <radius> integer radius of the circle [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_circle_draw() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] igp_circle_fill <anvid> <props> [<pat_name>] <ctr_x> <ctr_y> <radius> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list [<pat_name>] string pattern name [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] <ctr_x> integer X coordinate of the circle s center point <ctr_y> integer Y coordinate of the circle s center point <radius> integer radius of the circle [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_circle_fill() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] Modeler/Release 10.0 UP-1-45

46 igp_drawing_erase <anvid> <andid> <mode> <anvid> Anvid viewer ID <andid> integer drawing ID [<mode> keyword erase mode KP Analog: op_anim_igp_drawing_erase() [Accepted erase mode keywords are: none, redraw, xor, and xor_reset.] igp_icon_draw <anvid> <props> <ic_name> <x> <y> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list <ic_name> string icon name <x> integer X coordinate of icon upper-left corner <y> integer Y coordinate of icon upper-left corner [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_icon_draw() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] UP-1-46 Modeler/Release 10.0

47 igp_line_draw <anvid> <props> <x1> <y1> <x2> <y2> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list <x1> integer X coordinate of line s first endpoint <y1> integer Y coordinate of line s first endpoint <x2> integer X coordinate of line s second endpoint <y2> integer Y coordinate of line s second endpoint [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_line_draw() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] igp_macro_draw <anvid> <props> <anmid> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list <anmid> Anmid macro ID [<andid>] Andid drawing ID of request [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] This request is followed by a series of one or more argument-setting requests of the types arg_int, arg_dbl, or arg_str; each of these requests specifies a macro register and its new value. The list of argument requests is terminated by a request of the type arg_eol. KP Analog: op_anim_igp_macro_draw() Modeler/Release 10.0 UP-1-47

48 igp_macro_redraw <anvid> <andid> <mode> <anvid> Anvid viewer ID <andid> Andid drawing ID of previously drawn macro <mode> keyword erase mode [Accepted erase mode keywords are: none, redraw, xor, and xor_reset.] This request is followed by a series of one or more argument-setting requests of the types arg_int, arg_dbl, or arg_str; each of these requests specifies a macro register and its new value. The list of argument requests is terminated by a request of the type arg_eol. KP Analog: op_anim_igp_macro_redraw() igp_rect_draw <anvid> <props> <x> <y> <width> <height> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list <x> integer X coordinate of rectangle upper-left corner <y> integer Y coordinate of rectangle upper-left corner <width> integer width of rectangle <height> integer height of rectangle [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_rect_draw() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] UP-1-48 Modeler/Release 10.0

49 igp_rect_fill <anvid> <props> [<pat_name>] <x> <y> <width> <height> [<andid>] <anvid> Anvid viewer ID <props> keyword list graphical property list [<pat_name>] string pattern name [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] <x> integer X coordinate of rectangle upper-left corner <y> integer Y coordinate of rectangle upper-left corner <width> integer width of rectangle <height> integer height of rectangle [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_rect_fill() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] igp_text_draw <anvid> <props> <x> <y> <text> [<andid>] <anvid> Anvid viewer ID Modeler/Release 10.0 UP-1-49

50 igp_text_draw <anvid> <props> <x> <y> <text> [<andid>] <props> keyword list graphical property list <x> integer X coordinate of text position <y> integer Y coordinate of text position <text> string text string to be drawn [<andid>] Andid drawing ID of request KP Analog: op_anim_igp_text_draw() [This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.] UP-1-50 Modeler/Release 10.0

51 ime_mod_draw <anvid> <anmid> <view_name> <mod_options> <props> <anvid> Anvid viewer ID <anmid> Anmid model ID <view_name> string model view name [This numeric identifier must match the ID of a model previously loaded via an ime_nmod_load request.] <mod_options> integer model drawing option flags [This value is a bitwise OR combination of option flags. The value 0 indicates that there are no options selected. The option flags are: display dynamic paths, such as orbits or trajectories (1); display the model at half its normal size (2); configure the displayed model with speed optimizations for same-size substitution of object icons (8).] <props> keyword list graphical property list KP Analog: op_anim_ime_nmod_draw() (this KP issues both ime_nmod_load and ime_mod_draw requests) ime_nmod_load <anmid> <mod_type> <mod_name> <anmid> Anmid model ID [This numeric identifier is assigned to the model loaded by this request.] <mod_type> integer model type code [This numeric code specifies one of the model types available for use in an animation viewer. The values accepted by this argument are not listed in this manual, but instead appear within the description of the op_cvanim program.] <mod_name> string model name KP Analog: op_anim_ime_nmod_draw() (this KP issues both ime_nmod_load and ime_mod_draw requests) Modeler/Release 10.0 UP-1-51

52 ime_nobj_update <anvid> <obj_type> <obj_name> <anvid> Anvid viewer ID <obj_type> integer object type code [This numeric code specifies one of the object types in the model diagram displayed by the specified viewer. The values accepted by this argument are not listed in this manual, but instead appear within the description of the op_cvanim program.] <obj_name> string object name This request is followed by a series of one or more argument--setting requests of the types arg_int, arg_dbl, or arg_str; each of these requests specifies an object attribute and its new value. The list of argument requests is terminated by a request of the type arg_eol. KP Analog: op_anim_ime_nobj_update() UP-1-52 Modeler/Release 10.0

53 Modeler/Release 10.0 UP-1-53

54 ime_npath_traverse <anvid> <path_type> <path_name> <trav_id> <trav_options> <props> <text> <anvid> Anvid viewer ID <path_type> integer path object type code <path_name> string path object name <trav_id> integer traversal ID [This numeric code specifies one of the path object types in the model diagram displayed by the specified viewer. The values accepted by this argument are not listed in this manual, but instead appear within the description of the op_cvanim program.] [This numeric identifier is assigned to the traversal state memory created by this request; it is used to associate the halves of a two-part traversal.] UP-1-54 Modeler/Release 10.0

55 ime_npath_traverse <anvid> <path_type> <path_name> <trav_id> <trav_options> <props> <text> <trav_options> integer traversal option flags [This numeric code is a bitwise OR combination of two categories of code flags: (a) a single traversal type flag that sets the section of path traversed; (b) one or more independent option flags that modify the appearance of the traverse marker or the direction of traversal. The code values for both categories of option flag are listed in tables below: Traversal Option Flags Type Value circle marker 0 square marker 1 marker text 8 reverse traversal 16 Traversal Type Flags Type Value source begin 2 destination end 4 full 6 source end 32 destination begin 34 source abort 36 destination abort 38 KP Analog: op_anim_ime_npath_traverse() Modeler/Release 10.0 UP-1-55

56 macro_create <anmid> <anmid> Anmid macro ID KP Analog: op_anim_macro_create() [This numeric identifier is assigned to the macro produced by this request.] macro_destroy <anmid> <anmid> Anmid macro ID KP Analog: op_anim_macro_destroy() mgp_arop <anmid> <opa_regid> <operator> <opb_regid> <res_regid> <anmid> Anmid macro ID <opa_regid> keyword macro drawing register ID* for operand A <operator> keyword arithmetic operator code [Accepted operator keywords are: add, subtract, multiply, and divide.] <opb_regid> keyword macro drawing register ID* for operand B <res_regid> keyword macro drawing register ID* for operation result KP Analog: op_anim_mgp_arop() *[Accepted register ID keywords have the format reg_<l>, and are within the range reg_a through reg_z, inclusive.] UP-1-56 Modeler/Release 10.0

57 mgp_bg_fill <anmid> <arg_vals> [<props>] [<pat_name>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (2 items) graphical property list* [<pat_name>] string pattern name* [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_bg_fill() mgp_circle_draw <anmid> <arg_vals> [<props>] [<ctr_x>] [<ctr_y>] [<radius>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (4 items) graphical property list* [<ctr_x>] integer X coordinate of the circle s center point* [<ctr_y>] integer Y coordinate of the circle s center point* [<radius>] integer radius of the circle* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_circle_draw() Modeler/Release 10.0 UP-1-57

58 gp_circle_fill <anmid> <arg_vals> [<props>] [<pat_name>] [<ctr_x>] [<ctr_y>] [<radius>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (5 items) graphical property list* [<pat_name>] string pattern name* [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] [<ctr_x>] integer X coordinate of the circle s center point* [<ctr_y>] integer Y coordinate of the circle s center point* [<radius>] integer radius of the circle* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_circle_fill() mgp_icon_draw <anmid> <arg_vals> [<props>] [<ic_name>] [<x>] [<y>] anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (4 items) graphical property list* [<ic_name>] string icon name* [<x>] integer X coordinate of icon upper-left corner* [<y>] integer Y coordinate of icon upper-left corner* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_icon_draw() UP-1-58 Modeler/Release 10.0

59 mgp_line_draw <anmid> <arg_vals> [<props>] [<x1>] [<y1>] [<x2>] [<y2>] <anmid> Anmid macro ID <arg_vals> <props> keyword list keyword list argument value source list (5 items) graphical property list* <x1> integer X coordinate of line s first endpoint* <y1> integer Y coordinate of line s first endpoint* <x2> integer X coordinate of line s second endpoint* <y2> integer Y coordinate of line s second endpoint* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_line_draw() mgp_rect_draw <anmid> <arg_vals> [<props>] [<x>] [<y>] [<width>] [<height>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (5 items) graphical property list* [<x>] integer X coordinate of rectangle upper-left corner* [<y>] integer Y coordinate of rectangle upper-left corner* [<width>] integer width of rectangle* [<height>] integer height of rectangle* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_rect_draw() Modeler/Release 10.0 UP-1-59

60 mgp_rect_fill <anmid> <arg_vals> [<props>] [<pat_name>] [<x>] [<y>] [<width>] [<height>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (6 items) graphical property list* [<pat_name>] string pattern name* [This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.] [<x>] integer X coordinate of rectangle upper-left corner* [<y>] integer Y coordinate of rectangle upper-left corner* [<width>] integer width of rectangle* [<height>] integer height of rectangle* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_rect_fill() mgp_reg_set_int <anmid> <regid> <value> <anmid> Anmid macro ID <regid> keyword macro drawing register ID [Accepted register ID keywords have the format reg_<c>, where <C> is a single character, and are within the range reg_a through reg_z, inclusive.] <value> integer value to be assigned to specified register KP Analog: op_anim_mgp_reg_set() UP-1-60 Modeler/Release 10.0

61 mgp_reg_set_dbl <anmid> <regid> <value> <anmid> Anmid macro ID <regid> keyword macro drawing register ID [Accepted register ID keywords have the format reg_<c>, where <C> is a single character, and are within the range reg_a through reg_z, inclusive.] <value> double value to be assigned to specified register KP Analog: op_anim_mgp_reg_set() mgp_reg_set_str <anmid> <regid> <value> <anmid> Anmid macro ID <regid> keyword macro drawing register ID [Accepted register ID keywords have the format reg_<c>, where <C> is a single character, and are within the range reg_a through reg_z, inclusive.] <value> string value to be assigned to specified register KP Analog: op_anim_mgp_reg_set() mgp_setup_end <anmid> <anmid> Anmid macro ID KP Analog: op_anim_mgp_setup_end() Modeler/Release 10.0 UP-1-61

62 mgp_text_draw <anmid> <arg_vals> [<props>] [<x>] [<y>] [<text>] <anmid> Anmid macro ID <arg_vals> [<props>] keyword list keyword list argument value source list (4 items) graphical property list* [<x>] integer X coordinate of text position* [<y>] integer Y coordinate of text position* [<text>] string text string to be drawn* *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mgp_text_draw() mme_nobj_pos <anmid> <arg_vals> [<obj_type>] [<obj_name>] <x_regid> <y_regid> [<vertex>] <anmid> Anmid macro ID <arg_vals> [<obj_type>] keyword list keyword list argument value source list (3 items) object type code* [This numeric code specifies one of the object types in the model diagram displayed by the specified viewer. The values accepted by this argument are not listed in this manual, but instead appear within the description of the op_cvanim program.] UP-1-62 Modeler/Release 10.0

63 mme_nobj_pos <anmid> <arg_vals> [<obj_type>] [<obj_name>] <x_regid> <y_regid> [<vertex>] [<obj_name>] string object name* <x_regid> keyword drawing register ID for X coordinate of position <y_regid> keyword drawing register ID for Y coordinate of position [<vertex>] keyword object vertex code* [Accepted register ID keywords have the format reg_<c>, where <C> is a single character, and are within the range reg_a through reg_z, inclusive.] [Accepted vertex keywords are: icon_ctr, icon_n, icon_s, icon_e, icon_w, icon_ne, icon_nw, icon_se, icon_sw, path_src, path_dst, and path_mid.] *[The above arguments marked with asterisks are optional, and should only be included if they are specified as having constant value in the <arg_vals> source list.] KP Analog: op_anim_mme_nobj_pos() Modeler/Release 10.0 UP-1-63

64 viewer_close <anvid> <anvid> Anvid viewer ID KP Analog: op_anim_viewer_close() viewer_open <anvid> <name> <x> <y> <w> <h> <anvid> Anvid viewer ID <name> string viewer name <x> integer X coordinate of viewer upper-left corner <y> integer Y coordinate of viewer upper-left corner <w> integer width of viewer <h> integer height of viewer KP Analog: op_anim_viewer_open() viewer_open_std <anvid> <name> <loc_type> <anvid> Anvid viewer ID <name> string viewer name <loc_type> keyword viewer location code KP Analog: op_anim_viewer_open_std() [Accepted location keywords are: custom, full, n_half, s_half, e_half, w_half, nw_qtr, ne_qtr, sw_qtr, and se_qtr.] viewer_redraw <anvid> <anvid> Anvid viewer ID KP Analog: op_anim_viewer_redraw() UP-1-64 Modeler/Release 10.0

65 viewer_scroll <anvid> <x> <y> <anvid> Anvid viewer ID <x> integer X coordinate of the upper-left corner of specified viewer s visible region <y> integer Y coordinate of the upper-left corner of specified viewer s visible region KP Analog: op_anim_viewer_scroll() op_vuanim Environment You can run op_vuanim by choosing Play Animation from the Results menu or by typing the following on the command-line prompt: op_vuanim Modeler/Release 10.0 UP-1-65

66 The op_vuanim display is similar in appearance to OPNET, except that an op_vuanim animation viewer contains a button bar. This bar s buttons resemble a VCR s, and include play, pause, restart, stop, speed up, slow down, and skip to next... options. You can also load animation history files, view real time animation (simultaneously with an executing simulation), and use a variety of operations to control how animation data is displayed. Figure 1-37 op_vuanim Environment with Animation Viewer Time Bar The largest area of the display the animation viewing area is where you can load and view animations. Animations are displayed in windows called viewers. A viewer is a rectangular region with an internal coordinate system. Viewer windows can be manipulated using the standard GUI operations for moving, resizing, scrolling, and circulating editor windows. Viewers may occupy some or all of the animation viewing area and there may be several viewers open simultaneously. The size of a viewer determines the rectangular region of the viewer s coordinate system that is visible, but it does not limit graphical operations from being performed outside of this visible region. UP-1-66 Modeler/Release 10.0

67 Across the bottom of each viewer window is a time bar that displays the current simulation time (in days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds, and picoseconds). The foreground viewer will always display the current simulation time. Viewers that are frozen in the background will have their simulation time paused. The time is automatically updated whenever they become active again. System Menu If you launch op_vuanim from the command line and no animation viewer is open, the System menu, which comprises the following menus, displays: File Edit Windows Help The following tables provide a quick overview of the System menu, its items, each item s function, and, where necessary, a reference to further documentation on this function. File Menu The File menu includes items that relate to high-level operations, such as opening and closing animation files. The following table summarizes the operations that can appear in this menu. See the System Menus chapter in the Editor Reference manual for more details about high-level file operations. Table 1-8 File Menu Summary Menu item Description Reference Open... Opens an existing animation file. Playing Animation on page UP-1-73 Refresh Model Directories Reads all directories listed in the mod_dirs preference and updates the list of available models. Exit Exits the current program. End of Table 1-8 Modeler/Release 10.0 UP-1-67

68 Edit Menu The Edit menu includes operations for opening a text editor and changing your global preferences. Table 1-9 Edit Menu Summary Menu item Description Reference Open Edit Pad Opens an edit pad. Text and Source Code Editors chapter of Editor Reference Preferences End of Table 1-9 Allows you to edit environment attributes for the program. System Menus chapter of Editor Reference Windows Menu The Windows menu includes operations for hiding, displaying, and arranging open windows on your desktop. Table 1-10 Windows Menu Summary Menu item Description Reference Hide This Editor Hide Other Editors Hides, but does not close or save, the current editor. Hides, but does not close or save, other editors. Show All Editors Shows all previously hidden editors. Animation Viewers End of Table 1-10 Lists all open Animation Viewer windows. Select the desired window to make it active. Help Menu The Help menu provides access to context-sensitive help, the product documentation and tutorials, and information about the program. UP-1-68 Modeler/Release 10.0

69 See the System Menus chapter of the Editor Reference manual for more details about these operations. Table 1-11 Help Menu Summary Menu item Description Refere nce Documentation Opens the documentation. Tutorial Opens the tutorial. Web OPNET Home Opens your browser to the OPNET home page. Web Technical Support About This Application End of Table 1-11 Allows access to the Technical Support area of the OPNET web site. Displays information about the program (including release number), the workstation environment, and OPNET technical support. Animation Viewer Menus When you select Play Animation from the Results menu, the System window will appear, followed soon after by an Animation Viewer window. This window contains the following menus: File Edit Controls Windows Help The following tables provide a quick overview of the menus and operations found in the Animation Viewer window. References show where each operation is discussed further in OPNET documentation. File Menu The File menu includes items that relate to high-level operations, such as opening and closing animation files. The following table summarizes the operations that can appear in this menu. Modeler/Release 10.0 UP-1-69

70 See the System Menus chapter in the Editor Reference manual for more details about high-level file operations. Table 1-12 File Menu Summary Menu item Description Reference Open... Opens an existing animation file. Playing Animation on page UP-1-73 Close Closes all animation viewers. Print Diagnostics Model Files Exit End of Table 1-12 Prints viewer, model, and drawing information associated with all viewers in the current animation flow. 1. Delete Model Files--Deletes selected models from disk. 2. Add Model Directory--Select a directory and add it to your list of model directories. 3. Refresh Model Directories--Causes OPNET to search the model directories and update its list of available models. Exits the current program. Controlling Viewer Display on page UP-1-76 Edit Menu The Edit menu includes operations for refreshing the display, opening a text editor and changing your global preferences. Table 1-13 Edit Menu Summary Menu item Description Reference Redraw Redraws the display to accurately display the contents of the editor window. Open Edit Pad Opens an edit pad. Text and Source Code Editors chapter of Editor Reference Preferences End of Table 1-13 Allows you to edit environment attributes for the program. System Menus chapter of Editor Reference UP-1-70 Modeler/Release 10.0

71 Controls Menu The Controls menu includes operations for controlling the animation playback. Table 1-14 Controls Menu Summary Menu item Description Reference Play Pause Restart Terminate Slow Down Animation Speed Up Animation Step to Next Event Step To Next Time Step To Next Animation Request End of Table 1-14 Activates any animation flow that has been established. Pauses an animation indefinitely, until another operation reactivates it. Restarts a paused or stopped animation flow from its beginning. Stops an animation flow. Once stopped, an animation can be restarted only via the Restart Animation flow operation. Slows down the animation sequence in increments. Speeds up the animation sequence in increments. Steps to the next simulation event (which may not necessarily correspond to a graphical change). Steps to the next simulation time. Because multiple events may occur at each simulation time, this operation may carry out more animation requests than the Step to Next Event operation. Steps to the next animation request. When the animation sequence begins, it stops after the first animation request received by op_vuanim. Using Playback Operations on page UP-1-73 Using Playback Operations on page UP-1-73 Using Playback Operations on page UP-1-73 Using Playback Operations on page UP-1-73 Adjusting Animation Speed on page UP-1-74 Adjusting Animation Speed on page UP-1-74 Adjusting Animation Speed on page UP-1-74 Adjusting Animation Speed on page UP-1-74 Adjusting Animation Speed on page UP-1-74 Modeler/Release 10.0 UP-1-71

72 Windows Menu The Windows menu includes operations for displaying and hiding open editor windows. Table 1-15 Windows Menu Summary Menu item Description Reference Hide This Editor Hide Other Editors Hides, but does not close or save, the current editor. Hides, but does not close or save, other editors. Show All Editors Shows all previously hidden editors. Animation Viewers End of Table 1-15 Lists all open Animation Viewer windows. Select the desired window to make it active. Help Menu The Help menu provides access to context-sensitive help, the product documentation and tutorial, and information about the program. See the System Menus chapter of the Editor Reference for more details about these operations. Table 1-16 Help Menu Summary Menu item Description Reference What s This? Displays a? rollover pointer for quick identification of the project window s components. Documentation Opens the documentation. Tutorial Opens the tutorial. Web OPNET Home Web Technical Support About This Application End of Table 1-16 Opens your browser to the OPNET home page. Allows access to the Technical Support area of the OPNET web site. Displays information about the program (including release number), the workstation environment, and OPNET technical support. UP-1-72 Modeler/Release 10.0

73 Playing Animation Before you can view an animation, you must read in an animation history file (unless you are using the direct viewing option). After a history file has been loaded, the animation flow is active, but paused. op_vuanim does not begin playing back the flow until you start it with an appropriate Playback operation or a Step operation. Procedure 1-1 Loading an animation 1 Choose Open... from the File menu. A dialog box opens with a list of available animation history files (which store a scenario s animation results). 2 Select an animation to display and click OK. op_vuanim reads in the animation. End of Procedure 1-1 Using Playback Operations Four playback operations control the basic display of an animation sequence. These operations allow you to start, stop, pause, and restart an animation, as described in the following table. Table 1-17 Playback Operations Button Name Description Play Activates any animation flow that has been established. Pause Restart Pauses an animation indefinitely, until another operation reactivates it. You can also pause an animation sequence by moving the cursor. However, this method only pauses the sequence for a few seconds before animation automatically resumes. Restarts a paused or stopped animation flow from its beginning. Terminate Stops an animation flow. Once stopped, an animation can be restarted only via the Restart Animation Flow operation. End of Table 1-17 Modeler/Release 10.0 UP-1-73

74 Procedure 1-2 Starting a paused animation... 1 Left-click one of the following buttons or choose the item from the Controls menu: Play The animation resumes from the current point in the animation history file. Restart The animation restarts from simulation time 0. Any viewer that was moved or resized returns to its original size and position. Any Step operation t The animation advances to the next event, time, or animation request, depending on the button activated. Refer to Stepping Through an Animation on page UP-1-75 for more information. End of Procedure 1-2 Procedure 1-3 Pausing or stopping an animation... 1 Left-click the Pause or Terminate button or choose the item from the Controls menu. End of Procedure 1-3 Adjusting Animation Speed Sometimes it is necessary to speed up or slow down the animation flow to view particular aspects of the animation. Two operations adjust animation speed. These are presented in the table below. Table 1-18 Rate Operations Button Name Description Slow Down Animation Slows down the animation sequence in increments. Speed Up Animation Speeds up the animation sequence in increments. End of Table 1-18 UP-1-74 Modeler/Release 10.0

75 You can invoke these operations before an animation flow is read in or during playback. When invoked during playback, these operations cause op_vuanim to slow down or speed up animation in all open viewers. After the flow rate is changed, op_vuanim maintains it for the entire session or until the rate is changed again. The rate does not revert to the default between animation viewing sequences. Animations run at a default speed of 0.1 second, meaning there is a pause lasting 0.1 second (real time) between successive animation events. This interval, called the animation event gap, is shown in op_vuanim s mode display. The largest event gap (corresponding to the slowest animation) is 10 seconds. The smallest event gap (corresponding to the fastest animation) is 0.01 second. Procedure 1-4 Adjusting animation speed... 1 Left-click a Rate operation button or choose the item from the Controls menu. The animation speeds up or slows down to the next incremental value. The mode display shows the new event gap. 2 To further slow down or speed up animation, repeat step 1. End of Procedure 1-4 Stepping Through an Animation At times, simply slowing down an animation is not enough to allow close examination. Thus, op_vuanim allows you to step through an animation, pausing at each simulation event, time, or animation request. The three operations that step through an animation are presented in the following table. Table 1-19 Step Operations Button Name Description Step to Next Event Steps to the next simulation event (which may not necessarily correspond to a graphical change). Step to Next Time Step to Next Animation Request Steps to the next simulation time. Because multiple events may occur at each simulation time, this operation may carry out more animation requests than the Step to Next Sim. Event operation. Steps to the next animation request. When the animation sequence begins, it stops after the first animation request received by op_vuanim. Typically the first request will pop up a blank animation viewer. End of Table 1-19 Modeler/Release 10.0 UP-1-75

76 Each of these operations causes a paused animation to advance one step, then pause again after the first simulation event, time, or animation request. You can continue activating toolbar buttons to step through an animation. Controlling Viewer Display The following operations can be invoked to control viewer windows. Table 1-20 Viewer Operations Name Toggle Background Freezing Print Diagnostics Description Enables and disables animation display in background (inactive) viewers. Prints viewer, model, and drawing information associated with all viewers in the current animation flow. End of Table 1-20 Background Freezing When multiple viewers are open, op_vuanim displays animation such that viewers become momentarily active to display the current state of animation (as generated by the simulation). Viewers that are inactive during this time will not display animation until the simulation generates animation data related to the objects in them. Multiple viewers will change from inactive to active throughout the course of a simulation so that you can view animation throughout different parts of a system model. Background freezing refers to op_vuanim s ability to suspend animation when multiple viewers are on the screen, so that only one viewer is active. When background freezing is on, only one viewer will display animation; other windows will remain frozen in the background. When background freezing is off, all viewers display animation sequences, which allows you to monitor multiple animations. The background freezing status is indicated in op_vuanim s mode display. It is turned on by default. The Toggle Background Freezing operation can be invoked at any time before, during, or after an animation sequence has started. If this operation is invoked when background freezing is on, op_vuanim toggles it off. Viewers that were frozen in the background become active and their time bars are updated with the current simulation time. If background freezing was off, op_vuanim toggles it on. This causes the viewer in the foreground to display animation and remain active; viewers in the background become inactive and their animation sequences are suspended. UP-1-76 Modeler/Release 10.0

77 Diagnostic Information Information related to the animation viewer and the model it contains can be generated using the Print Diagnostic Information operation. This can be used to examine areas of interest within an animation for troubleshooting and analysis. This operation can be invoked any time during animation playback. The data is printed to the command shell window that spawned op_vuanim and will reflect the current time in the animation viewers. Procedure 1-5 Viewing diagnostic information... 1 Choose Print Diagnostics from the File menu. 2 Information on all viewers in displayed in the window that spawned op_vuanim. The information reflects the current status of all viewers and is grouped into the following categories: Viewer Count lists the number of viewers associated with the animation history file. This number includes any viewers that have been closed during animation playback. Viewer State lists information about the viewer such as viewer ID, name, position, and size. The viewer status will either be visible, meaning that it is currently open in the window, or closed. The name of the model inside the viewer is also provided. Model State lists information about the model inside the viewer, such as object names and packet IDs. Drawing Count lists the number of drawings and the information associated with each drawing. Drawings are the result of animation requests. For example, one drawing could be an actual model, comprised of a series of animation requests. Drawing information listed includes a time stamp for when the drawing was created, an event ID indicating the order in which the drawing occurred, and the type of drawing. End of Procedure 1-5 Modeler/Release 10.0 UP-1-77

78 UP-1-78 Modeler/Release 10.0