12. Importing Motion Data

If you already have motion data from another tool — an animation package, a spreadsheet, a data logger or a simulation — you can import it into a show. Each column you import becomes the take of one axis, just as if you had recorded it (see chapter 10), so you can edit, run and test it in the same way.

What you can import

• Comma-separated files (.csv), which spreadsheets and most animation and logging software can write.

• Semicolon-separated files (.csv), which Excel writes on a PC set up for decimal commas.

• Tab-separated files (.tsv or .txt), such as Excel's Text (Tab delimited).

• Cells copied from a spreadsheet in Excel, Google Sheets or LibreOffice, added with the import window's Paste.

You can import several files at once — for example one file per axis, as many animation packages export them. To import from an Excel workbook, save the sheet as a CSV or tab-delimited text file, or copy its cells and paste them.

Contours imports positions at a fixed interval: one row per frame or per sample, evenly spaced in time, the way Contours records. The speed is worked out from the positions.

Note. Keyframes at uneven times can't be imported. Export a value for every frame instead.

The file format

Each row is one sample. The first column is the time, and each other column is the position of one axis, in the axis's own units as set in Axis Setup (degrees, mm and so on).

Time (s),Pan,Tilt
0.0,0.0,0.0
0.1,1.5,2.3
0.2,3.0,4.6
0.3,4.5,6.9

This file has a point every 0.1 s for two axes. In a project whose axes are called Pan and Tilt, each column goes to the axis of the same name; with other names, the two columns go to the first two axes in order.

The header

The header row is optional but recommended. Every row before the first row of numbers is a header, and the last of them names the columns. The names are used to match columns to axes, and the time column's name can give its units, as Time (s) does here. Lines that start with # are comments and are ignored.

Delimiters and numbers

• The delimiter is a comma, a semicolon or a tab, one per file. Contours detects it from the first rows.

• Decimals use a point (1.5). A decimal comma (1,5) also works in a semicolon- or tab-separated file, where it can't be mistaken for the delimiter.

• Scientific notation (1.5E-03) is fine. Thousands separators are not: write 1500, not 1,500.

• A name that contains the delimiter can be put in quotes: "Head, X".

• The file can be UTF-8, Windows-1252 or UTF-16 (Excel's Unicode Text).

Note. Contours never reads numbers with Windows' regional settings, so a file imports the same on every PC.

Blank cells

• An empty cell means that axis has no value at that time. Contours bridges the gap with a straight line between the values either side.

• A column whose first value comes after its file's first row holds that value from the start, and after its last value it holds the last one.

• Blank lines, and rows of nothing but delimiters (,,,), are ignored.

• Every row needs a cell for every column, even if the cell is empty. A row that stops short, or a cell that isn't a number, is reported with its row (see The checks).

Time

• The time must step by the same amount on every row. Small rounding in the written times, such as 0.033333333 for 30 fps, is fine; a missing or repeated row is not.

• Time can be in seconds, milliseconds or frames. Contours reads the units from the time column's header where it says (s, ms or frame, as in Time (ms)), and otherwise uses the units of your last import, or seconds. You can change them in the window.

• Time must increase down the file. It doesn't have to start at 0.

• A file with no time column can still be imported: you enter its interval in the window.

Opening the import window

• To import into a new show, or into the selected show, open the ⋮ menu at the right-hand end of the Shows toolbar and choose Import, or right-click a show and choose Import. Every axis in the project can take a column, and the import goes into a new show unless you choose otherwise.

• To import into one axis, right-click its profile and choose Import. Only that axis can take a column, and the import goes into that profile's show unless you choose New show.

Import is available once the project has at least one axis (see chapter 6). The Import motion data window opens over Contours.

Dropping files on Contours

You can also drag files from File Explorer and drop them on Contours, and the import window opens with them added:

• Drop .csv, .tsv or .txt files anywhere on the window to import them into a new show.

• Drop them on a show in the Shows list to import into that show, or on a profile, or its Position or Speed row, to import into that axis only. The row you drop on is selected.

Text boxes and other lists don't take a dropped file. Dropping files isn't available while the Record screen or the point editor is open, during a test run, or while an import window is already open. A project file (.cntp) dropped on its own opens the project instead (see chapter 4).

Wizard and Advanced

The import window has two modes. The Advanced switch at the bottom left moves between them:

• With Advanced off, the window is a wizard: it steps through the import one card at a time and explains more on each step.

• With Advanced on, every card is on one page.

The first time you import, the window opens as the wizard. After that it opens in whichever mode you last left it in. Switching keeps everything you have chosen; turning Advanced off takes you back to the wizard's first step. In either mode, Cancel at the bottom right closes the window without importing anything.

The wizard

A step bar across the top shows the four steps. The current step is orange, and a finished step is ticked: click it to go back to it. Back and Next are at the bottom right. Next is unavailable while the step has something that would stop the import, and Import appears only on the last step.

1. File: add your files or paste cells (see Adding files). The First rows card shows the picked file's first rows as they are written, tags each column as time or value, and says which row the data starts on. Pick another file from its File list. Next is available once a file has been added.

2. Time: the Time card, with a row for each file (see Timing). Click a file's name to see it in the Resampling card below: its samples drawn against the points that will be imported, what happens to them, and how many points each Import at gives, with the suggested one tagged.

3. Axes: which axis each column goes to (see Matching columns to axes), with how the matching works written above the card.

4. Review: the Summary card and the preview. The summary gives where the import goes (Import into), what it creates or replaces, the axes that aren't in the files, the timing, the length options when the axes would end at different times, and any warnings. Click Import here.

The Advanced page

Advanced shows the Files and Time cards across the top, Axes and Preview below, and a bar along the bottom with Into, a line saying what Import will do, and Import. The usual import is: add the files, check the preview, and click Import. The wizard's extra information is still there: First rows in the Files card shows the picked file's first rows, and the (i) beside a heading or option explains it.

Adding files

• Add files opens a file dialog, where you can choose one file or several. It opens in the folder you used last.

• Paste adds the cells on the clipboard as Pasted data. Copy the header row with the cells so the columns have names.

• Each file is listed with its number of rows. The × beside a file removes it. Click a file to pick it.

• While a large file is read, the bar at the bottom of the window shows its progress, with a Cancel that stops it.

Under the list, Delimiter (Comma, Semicolon or Tab), Decimal (Point (.) or Comma (,)) and Header rows show how the picked file is read, as Contours detected it. Change one and the file is read again with your setting. The decimal can only be a comma when the delimiter is a semicolon or a tab.

Tip. If a file's columns come out wrong — one column where you expected several, or a heading read as numbers — look at its first rows and check these three settings.

Timing

Each file keeps its own time: its own interval, its own start in the show and its own length, so the files don't have to match. The columns of one file share that file's time. The Time card has a row for each file:

Same for all files, above the rows, sets Time column, Units and Import at once for every file, from the first row, and greys them out on the other rows. It is ticked when the files are alike. Untick it to set each file on its own. Starts at is always set for each file.

When a file's time can't be used, the problem is shown in red under its row (see The checks).

Tip. If Every or Ends at is a thousand times too long or too short, the units are wrong: change Units.

Import at and resampling

The motors play a take one point every whole number of milliseconds, at least 10 ms apart. A file whose interval is already a whole number of milliseconds (10, 20, 25, 40, 50 or 100 ms, say) is kept exactly as it is. This is the usual case for a file made in a spreadsheet.

A file at a frame rate usually isn't: 30 fps is a point every 33.33 ms. Rounding that to 33 ms would make a 35-second animation finish 0.35 s early and drift away from its video. Instead, Contours resamples the file: every Import at it reads a new point off the straight line between the file's two nearest points, and the take still ends on the file's last value.

The suggested Import at is the largest of 10, 20, 25, 50 and 100 ms that isn't longer than the file's interval, so no detail is lost: 30 fps and 24 fps give 25 ms, 15 fps gives 50 ms and 60 fps gives 10 ms. You can type any whole number of milliseconds from 10 up; a longer interval gives fewer points. The (i) beside Import at lists how many points each interval gives for the picked file.

Starts at

Contours fills in Starts at so that files exported together stay in step: the file whose time starts earliest starts at 0 s, and a file whose time starts 2.5 s later starts at 2.5 s. A file with no time column starts at 0 s. Type another time to move a file, for example 0 to start a separate clip at the beginning of the show. Until a file starts, its axes hold their first position.

Matching columns to axes

The Axes card has a row for each value column: its Column name and where it comes from, the Axis it goes to, its Range and its Check.

Contours matches columns to axes by name first. A column's name is its header, or the file's name for a file with one value column. Case, spaces, _ and - don't count, and a name matches when it is the axis's name or ends with it: columns called Head X, head_x and 24FPS_len_Head_X all go to the axis Head X. Columns that no name matches take the remaining axes in order. A tag beside the axis says by name or by position.

• Pick another axis in the Axis list to change it. Each axis takes one column: if another column already had that axis, it is set to Skip.

• Choose Skip to leave a column out.

• When you opened Import from a profile, the list offers only that profile's axis and Skip.

• Axes that no column goes to are named under the rows. In a new show they stay empty; in an existing show they keep their data.

• Range shows the column's lowest and highest value, so wrong units stand out: -3.14 to 3.14 where you expected degrees, for example.

Values come in as they are: the import doesn't scale or offset them. To do that, see After importing.

Different lengths

When the imported axes would end at different times, a warning at the foot of the Axes card, and on the wizard's Review step, lists each axis's length and offers three options for the shorter axes:

A longer file is never trimmed, and no file is stretched or squeezed, because that would change its speed. For anything else, change the files themselves. The warning doesn't stop the import.

When you import into a show that has a video, the warning also gives the video's length, and it appears for that alone when the video is more than a second longer or shorter than the import. Axes of that show that aren't in the files keep their takes, and the warning says when the show will still end at different times.

The checks

Contours checks every column that goes to an axis, and shows the result in its Check: a green tick and OK, a warning in amber, or an error in red. While any column has an error, Import (and the wizard's Next) is unavailable until you fix it or set the column to Skip. A warning doesn't stop the import.

A file whose time can't be used shows one of these under its row on the Time card, and its columns can't be imported until it is fixed, the file is removed, or its columns are skipped:

A file that can't be read at all is reported in the bar at the bottom of the window.

Importing

Choose where the import goes with Into on the Advanced bar, or Import into on the wizard's Review step:

• New show: a new show named after what the files' names have in common (the four files 24FPS_len_Head_X, 24FPS_len_Head_Y, 24FPS_len_Head_Z and 24FPS_len_Body make a show called 24FPS_len), or after the file when there is one. A number is added if a show already has that name. Axes that aren't in the files are empty in the new show.

• Selected show: name: the show selected in the Shows tab, or the profile's show when you opened Import from a profile. The takes of the axes the columns go to are replaced; every other axis keeps its data, and the show keeps its name.

The line beside Into (the Show line on the Review step) says what Import will do, for example Creates the show “24FPS_len” with Head X, Head Y, Head Z and Body. or Replaces Head X in “Opening”. It turns red when the import will replace a take that has points; an axis with no take is only filled.

Caution. Contours doesn't ask before replacing a take. If you might want the old takes back, import into a new show, or use Save Backup first (see chapter 4).

Before you import, check the Preview. It draws each column as it will be imported, in its axis's colour, with the length option applied. A dashed line is a motor holding its position, and a marked time is too fast for that axis's motor.

Click Import. The window closes, the show is selected with its new takes on the chart, and a message at the bottom of the main window says what was imported. The project now has unsaved changes: save it to keep the import.

After importing

• Each imported axis has a take with a point every Import at, which the point editor shows as its Point Interval. Its speed is worked out from its positions.

• A show is as long as its longest take, so an import can make a show longer or shorter.

• To scale, shift or invert the values, open the point editor (chapter 11) and use Scale Points, Shift Points or Invert in its Adjust card. With no rows selected, they change the whole take.

• Motion that was too fast for its motor can be eased in the point editor as well, by editing points or with Smoothing or Stretch Time.

• Play the show against its video (chapter 9) and run it on the Test tab (chapter 13) before you rely on it.