THE SIMULATION ANIMATION BLOCK


Table of Contents


INTRODUCTION

The Ansim directory is a collection of functions for MATLAB 5.0 and a corresponding block for Simulink 2.0 that are used to animate simple objects based on inputs from a Simulink model. Animation and setup are implemented in a Graphical User Interface (GUI) environment that allows the user to be "hands off" the Simulink simulation.

Users have a choice of five object types that are available for animation: dot, line, patch, text and rectangle. Each of the objects has properties which can either be constant values or be dependent upon an input from the Simulink model. Any number of objects may be added, modified or deleted.

Other functionality that has been built in to the animation GUI includes the ability to control a number of axis parameters and the ability to save and load animation setups.

For a demonstration of the block, change to the

ansim
directory, and type
ansimtest
from the MATLAB command line. When the SIMULINK model appears, double click on the Animation Block. The Animation Figure Window will appear. You will then be prompted to see if you want to load a specific animation configuration file. Select the option to load the file and the setup will be completed. Edit objects by double-clicking on them, or just start the simulation and watch the animation.

TUTORIAL

The following section gives a description of each of the functions available in the Animation Figure Window (AFW). It first looks at initializing the window and working with the buttons located on it. Following this, each of the menus is looked at and a description of each submenu item is given. At the end of this tutorial, the user should have an understanding of how everything in the animation figure window works.

Description of Main MATLAB Functions

There are a large number of functions associated with this block. A few of the more important functions are:

  • andot.m, anline.m, anpatch.m, anrect.m, antext.m
  • Object functions.
  • ansim.m - Simulation animation.
  • ansimini.m - Initialize figure for SIMULINK animations.
  • anobj.m - Initialize object icons for animations.
  • These functions are important for setting up the AFW, animating the objects and adding new objects.


    Initializing the Animation Figure Window

    If the AFW is not open, double-clicking on the SIMULINK animation block will open it. If the window is already open, double-clicking on the block will bring the AFW to the top level of the screen. If a file has previously been saved within an AFW, an attempt will be made to reload the saved file. If this file is not found, the figure window will initialize with an empty workspace.


    The Animation Window

    Upon initialization of an AFW, the user will see:

    1. a tool bar of object buttons in the upper left corner of the figure
    2. reset and close buttons in the lower part of the figure
    3. a status message in the bottom middle of the figure
    4. the animation workspace in the middle of the figure

    Status Bar

    Located at the bottom of the AFW is the status bar. This bar shows the status of the AFW, allows the user to start and stop the simulation and allow the user to close the AFW . If an animation is run, reset must be selected in order to be able to modify any of the objects on the AFW. The status bar will state "Simulation Stopped. To modify/add objects, press Reset". When the simulation is running, two additional options appear on the Status Bar. The first button allows the user to select whether or not the objects leave "tracks" behind during animation. The second button will clear the tracks from the animation axis.

    Tool Bar

    In the upper-left corner of the AFW is the Object Tool Bar. The top button is the select button and the five buttons underneath it are the five different object types. Currently, these object types include dot, rectangle, text, line and patch. These object-type buttons may only be depressed while the AFW is in a Reset state. Once a button is depressed, clicking on the AFW workspace will place the object that has been selected. Once the object is placed, the Select button will be placed in a depressed position and a dialog will appear for the new object's properties.


    Screen Functions

    Once an object has been placed, it is possible to drag it around, remove it or modify it. Dragging the object around will update the X and Y coordinates of the object. In order to remove an object, first select the object by clicking on it and then press Ctrl-X. Modification of an object may be performed by double clicking on it.

    The File Menu

    The File menu on the AFW contains three options: Load, Save and Close. The Load menu option will load the specified MAT file and the Save menu option will save the current AFW configuration in a MAT file. If a file is loaded or saved, information is placed in the SIMULINK Animation block so that the next time the block is loaded, the saved configuration will be loaded. If the file is not found, the AFW will be initialized empty. The Close menu option will close the AFW.

    The Edit Menu

    The edit menu allows the user to create new objects, delete objects and modify objects. The menu is only enabled when the AFW has been reset.

    New Object

    The menu New Object has a sub-menu with five options. Each of these options relates to an object type. This sub-menu is created using the anobj command. Additional object types can be added inside this command and instructions to do so may be found there. Selecting one of the five existing objects will place the new object in the center of the AFW and bring up a dialog box. It should be noted that a feature has been added that allows objects to remain static during animation. If an object is not dependent upon inputs, then it is considered to be a static object and will not be redrawn during animation. The fourbar demo gives an example of this.

    Delete Object

    Delete the currently selected object. This option is only enabled when an object has been selected.

    Delete All Objects

    This option is only enabled when objects are on the screen. Selecting this option will delete all objects from the AFW.

    Modify Object...

    Once an object has been selected, this option will be enabled. Choosing this option will bring up the selected object's dialog box. The object dialog boxes allow users to make entries for the X and Y position of the objects, objects sizes, color, etc. These entries may be constant values or they may be based upon the input signal. A sample entry for X Position is:

    Any object attribute displayed in a dialog box can be dependent upon an input signal to the animation block. The only exceptions to this rule are for text. The entries String, Horizontal alignment and Vertical Alignment are fixed at object creation. If you are using a PC platform, please see the note about color in the bugs section.

    The View Menu

    The View menu allows the user to control axis and AFW characteristics. Currently, twelve different options are available.

    Axis On

    This option determines whether or not the axis is displayed. If this option is checked, then all other options related to the axis are visible. If this option is not checked, the axis, tick marks, grid, and axis box are not displayed but are still active.

    Grid On

    This option determines whether or not the X and Y Grids are displayed. A check mark next to this option turns the grid on. Note: The Tick Marks must also be on for the grid to be visible.

    Border On

    This option determines whether or not the axis box is turned on. If the option is checked, then the box is turned on.

    Square Axis

    This option determines whether or not the animation axis is square. Selecting this option will make the axis square.

    AutoScale On

    This option determines whether or not the axis will automatically scale outwards when an object reaches the current axis limits. If this option is checked, then the axis will autoscale. If this option is not checked, then the objects will be limited to displaying inside the boundaries of the axis.

    Tick Marks/Labels On

    This option determines whether or not the Tick Marks and Labels are displayed. If the option is checked, then these are displayed.

    Change Axis Limits...

    This option will bring up a dialog that allows the user to set the axis limits. These limits will be set whether or not autoscale is set. AutoScale may still be active though.

    Change LabelsŠ

    This option allows the user to set the xlabel, ylabel and title on the animation axis.

    Show Status Bar

    This option allows the user to hide the status bar at the bottom of the screen. If it is not checked, then the Status Bar is hidden and the axis resizes to fill the AFW.

    Show Tool Bar

    This option controls whether or not the buttons on the AFW are displayed. If this option is checked, then the buttons are displayed. If it is not checked, then the buttons are hidden and the axis resizes to fill the AFW.

    Find All Objects

    This option will autoscale the axes so that all objects are present. Selecting this option will override any axis limits that may be present.

    Find Simulink Diagram

    This option will bring to the front the SIMULINK window that the Animation block is located on.

    The Simulation Menu

    This menu contains the options for controlling the SIMULINK simulation. It is also possible to reset object positions and set an initial input vector using options in this menu.

    Start/Restart

    These two options are tied to the SIMULINK figure windows. The simulation may be started, restarted and stopped directly from the AFW.

    Reset

    This option acts the same as the Reset button on the AFW.

    Set Initial Input Vector...

    This option allows the user to specify what the initial values of the inputs are to the AFW. These values are used to place objects on the AFW in an expected position. Up to 100 inputs are possible at this time. Users may specify none to 100 values. Default values of zero will be used for those input values that are not specified.


    DEMOS

    A single demo has been supplied with this block:

    ansimtest.mdl.
    Type
    ansimtest
    from the MATLAB command line. When the SIMULINK model appears, double click on the Animation Block. The Animation Figure Window will appear. You will then be prompted to see if you want to load a specific animation configuration file. Select the option to load the file and the setup will be completed. Edit objects by double-clicking on them, or just start the simulation and watch the animation.


    KNOWN LIMITATIONS AND BUGS

    This program is considered finished for MATALB 5.0 and Simulink 2.0. Because it is freely distributed, fixing bugs in ANSIM have a lower priority than bug in MATLAB itself. Besides, we're busy working on something much cooler. Still, if you encounter any bugs or otherwise unpleasant behavior, please contact the authors listed below. Odds are good that you will get a quick reply, and possibly even a quick fix. If you include (1) the name of the Operating System you are using, (2) the processor/clock speed of your machine, and (3) the version of MATALB and Simulink you are using, we'll have a much better chance of duplicating your problem and finding a solution. Also, if any error messages are generated, please copy them as well.

    Original Author:

    Loren Dean
    The MathWorks, Inc.
    ldean@mathworks.com

    Revisions By:

    Kevin Kohrt
    The MathWorks, Inc.
    kkohrt@mathworks.com