External Model

An external model is a track consisting of one or more point masses with world positions determined by a data source (model data generated in a separate modeling program such as a spreadsheet, EJS or other modeling tool). The track enables the external model to be animated and drawn directly on a real-world video for visual comparison. Note: when comparing data with a video it is important that the model time steps match the video frame rate. For example, to compare data with a 100 fps video the time steps should be 0.01 s.

There are three types of data source:

1. A text data file written by a separate modeling program (e.g., spreadsheet).
2. Text data copied to the clipboard in a separate modeling program (e.g., spreadsheet). Clipboard data has the advantage that it can be auto-pasted, thus enabling changes in the modeling program to be displayed instantly in Tracker. For more information, see Auto-pasting.
3. An EJS simulation or other modeling program able to send data directly to Tracker.

1. Creating an external model track

To create an external model from a text data file, do one of the following:

• Click the Track button , then New|External Model|Text File..., and open the file using the file chooser.
• Choose File|Import|Text Data File..., then open the file using the file chooser.

To create an external model from text data on the clipboard, do one of the following:

• Choose Edit|Paste Data or hit Control-V (Command-V on Mac).
• Click the Track button , then New|External Model|Clipboard.

To create an external model from an EJS simulation jar file (version 5.2 or later), run the EJS simulation and send the data directly to Tracker. For more information see Data sources: EJS simulations below.

2. Auto-pasting

An external model created from pasted clipboard data can be refreshed automatically by checking the Auto-Paste checkbox on the toolbar. Tracker will then constantly monitor the clipboard contents and automatically paste any valid data that it finds. If the clipboard data changes, the new data is immediately applied to the existing external model track. This makes it easy to change a model in a separate application, copy its data to the clipboard, and automatically see the changes in Tracker.

For an example of how powerful auto-pasting is, take a look at Tracker Video Modeling with Spreadsheets, an Excel spreadsheet model of a projectile that uses macros to automatically copy data cells to the clipboard whenever a model parameter changes. When combined with the auto-paste feature in Tracker this results in a completely "live" connection so when a model parameter is edited in the spreadsheet the modified trajectory is instantly drawn on the video. This entire example, including tutorial, spreadshhet model and video, is packaged in a Tracker project (TRZ) file that can be downloaded at https://www.compadre.org/osp/items/detail.cfm?ID=14056.

3. Data sources: text data format

The figure below shows four examples of text data suitable for an external model. Note that:

• Data and variable names are organized into rows and columns.
• There must be at least 2 columns of data, each row of which defines (x, y) position coordinates for a point mass (see left-most example below). Additional columns may define time t ("launched_marble" example) and/or (x, y) positions for multiple point masses ("jumper" example).
• Optional rows above the position data define names for the track and individual point masses. Names should not contain spaces or punctuation marks. Underscores ("_") are converted to spaces in Tracker.
• The row defining the track name, if present, must be the first. If no track name is specified, the default name "external_model" is used.
• The row defining individual point mass names, if present, must be immediately above the first data row. Names are defined in pairs that start or end with "x" and "y", are otherwise identical, and are in adjacent columns; the "x" and "y" are stripped when the names are imported into Tracker. For example, in the "jumper" data below, point masses are defined with names "head", "elbow" and "knee". Strings in parentheses or square brackets (e.g., units) are ignored--for example, "xball (m)" is read as "xball".
• Time "t" is optional. When no time data is included, Tracker uses the video frame times.
• Every data row defines a separate data point. Data points must contain values in the same order in which the variables are defined. Values may be null as shown in the jumper data below.
• Names or values in a given row are separated ("delimited") by tabs, spaces, commas or semicolons. You must use the same delimiter throughout.
• Data values can be written in decimal or scientific format. The numbers "-6", "3.14" and "9.5E-2" are all valid values.

Most programs that collect, generate or analyze data, including spreadsheets, are able to copy and save (or export) text data that conform to these specifications.

4. Data sources: EJS simulations

EJS (Easy Java/Javascript Simulations) is a free authoring tool written in Java that helps non-programmers create interactive simulations for teaching and learning. EJS was created by Francisco Esquembre and, along with Tracker, is part of the Open Source Physics project. EJS can be downloaded from http://www.um.es/fem/EjsWiki/Main/Download.

Starting with EJS version 5.2, simulations can send data directly to Tracker where it is displayed as an external model. In addition, video and Tracker files can be loaded into Tracker directly from EJS. This greatly increases the potential for comparing dynamic models with videos.

For more information about creating simulations and sending data from EJS, see the EJS Wiki help pages.

5. External model properties

Since the data source usually provides data generated by a theoretical model, an external model is treated as a type of particle model. For this reason its user-controlled properties are displayed and edited using the Model Builder tool. To use the builder, choose Model Builder... from the external model's track menu.

Data points loaded from a data source are stored in a data point array. Each data point can be referred to by its index (starting from 0) in the array. For example, in the "launched_marble" text data example above the array would have a length of 11 with indices from 0 to 10. The data point at index 10 would have the value (t=1.0, x=5.0, y=-10.0).

The following properties are user-settable in the model builder:

1. Start frame: the video frame displaying the first data point.
2. Frame count: the number of video frames displaying data points.
3. Data start: the index of the first displayed data point.
4. Data stride: the index increment between displayed data points.
5. Time Basis: the source of the time base used to determine video frame times (and thus velocities and accelerations). Data time is enabled only if a data source provides time data.

For example, using the settings shown in the figure above, data point index 2 is displayed in video frame 15, index 4 in frame 16, index 6 in frame 17, index 8 in frame 18 and index 10 in frame 19 as shown in the green and white bar graphics. In this example, the data time is ignored since video time is selected as the time basis.

6. External model point and line properties

The points defined by a external model are point masses so each has settable mass, color, footprint and motion vector properties. This also means you can attach measuring tools to the points and add them to center of mass tracks just like any other point mass track.

When a external model defines two or more points you can connect them with lines using the Lines item in the external model's menu. With three or more points choose Close to connect the last point back to the first.

7. Stamping

Each model point can independently create a stamped point mass which clones the model point's current positions. The stamped point mass positions don't move when you change scale. For more information see Stamping a point mass.