Visual3D Pipeline

From Software Product Documentation
Jump to navigation Jump to search
Language:  English  • français • italiano • português • español 

Overview

The Pipeline is a set of Visual3D commands that are processed in sequence.

Note: The pipeline is a COMMAND language, not a SCRIPTING language.

The Pipeline processor provides access to the core of Visual3D functionality through commands. Each function is represented by a command. The Pipeline is typically used to automate processing steps.

The Pipeline has the ability to manage files, define events, execute signal processing computations, create and edit modes, create and modify reports, and generated statistics. Edit boxes are usually provided for configuring each process step.

The pipeline processor (or any text processor) can be used to create the pipeline. Any pipeline command that can be run interactively through the pipeline processor may be saved to a text command file. This file may be reloaded later, or combined with other command files to build a more complex pipeline. The pipeline processor can be launched from the Visual3D tool bar or from the Pipeline menu.

In special cases, C-Motion creates custom pipeline commands for users. These commands are usually fully functional but hidden from the interface. Users requiring these special commands will need to remember the syntax for the commands.

A detailed tutorial to teach you how to use the command processing pipeline and introduce you to pipeline commands can be found here: Tutorial: The Command Pipeline

Pipeline Commands

Pipeline commands are divided into various categories: File, Signal, Event, etc. Commands under these folders are added to the pipeline by expanding the folder for a category, and selecting the function to be added by clicking the "Add" button. The selected function will be added to the pipeline immediately after the command that is currently highlighted in the pipeline. Commands can be repositioned in the pipeline using the arrow keys to the right of the list box.

A pipeline can be used to define the processing steps for a given experimental data analysis protocol. This allows, for example, the director of the laboratory to control the processing that is done by a member of the laboratory. This may be essential for some experimental studies that require that all of the data analysis be performed consistently.

Visual3D plug ins integrate seamlessly into Visual3D and are accessed through the pipeline processor. The Pipeline can be saved to disk as an ASCII file (The Pipeline (.v3s) File) that can be edited with any common word processing program.

For details of specific commands that can be used through the Visual3D pipeline, see: Pipeline Commands Reference

Pipeline Commands: Active Files

Pipeline commands usually process the "Active Files"; e.g. those files active in the Visual3D Workspace. If only one file is selected in the file selection box, the pipeline, when executed, will perform actions only on the data from that file. If ALL_FILES is selected, the script will perform actions on every file individually, as if the script had been run sequentially for each file. More information on these active files can be found here: Active Files.

Pipeline Commands: Syntax

Each Pipeline command consists of two parts - the command and its parameters. 

Command_Name 
/Parameter1= something 
/Parameter2= this_value+another_value 
/Parameter3= 3.14 
!/Parameter4= default_value_for_Parameter4
;

Note: that each parameter begins with a slash and that the command is terminated with a semicolon.

The "!" character is used to comment out a parameter. If the "!" character is at the beginning of a line, the line is ignored, and the default values for the parameter are used in the processing. The script text is provided so that these optional parameters may be un-commented and additional parameter values added.

To pass more than one set of parameters to the command, list the values of each parameter, separated by "+" signs. The generalized command above passes one set of three parameters to the command "Command_Name".

Optional parameter are commented out - thus they start with an exclamation mark. When a command is first added to the pipeline the default values are displayed on the line, so that the user is aware of the default values.

Pipeline Commands: Special Command Characters

The pipeline commands reserve 4 special characters

  • ! - if this is the first character of a line, the line is considered a comment. If the ! is at the beginning of a variable name, the default value of the variable is used
  • / - indicates a command variable
  • + - is a delimeter separating entries. For example, 1+2 indicates that the variable as two values (1 and 2).
  • & - indicates a concatenation. For example, this&that will be interpreted in the pipeline as thisthat

Pipeline Commands: Specifying Signals in a Command

Signals in Visual3D must be identified by 3 components

  1. Signal_Type - Target, Analog, etc
  2. Signal_Name - Signal Name
  3. Signal_Folder - The specific folder

Signals can be represented in two different ways depending on the command.

Many commands contain the following three parameters: 

/Signal_Types= The types of the signals
/Signal_Names= The names of the signals
/Signal_Folder= The name of the signal folder

These commands allow the user to import the checked signals in the data tree, so the syntax need not be remembered.

Implicit Behaviors

If only the signal type is specified. All signals of that type (and the default folder) are implicitly selected for use in the command.

For example: to apply a lowpass filter to all TARGETS. This is accomplished by specifying the SIGNAL_TYPE and SIGNAL_FOLDER but leaving SIGNAL_NAMES empty.

Lowpass_Filter
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_FOLDER=PROCESSED
/RESULT_SUFFIX=
/FILTER_CLASS=BUTTERWORTH
/FREQUENCY_CUTOFF=6.0
/NUM_REFLECTED=6
/NUM_EXTRAPOLATED=0
/TOTAL_BUFFER_SIZE=6
/NUM_BIDIRECTIONAL_PASSES=1
;

For legacy support (e.g. Visual3D version 1.0), if the SIGNAL_FOLDER is empty it defaults to ORIGINAL. In other words

/SIGNAL_FOLDER=
is equivalent to
/SIGNAL_FOLDER=ORIGINAL

Entering Signal Names into a Command

Some commands act on signals (Target, Analog, etc). You can select a signal name for the command to work on by checking the signals in the data tree (Signal and Event processing mode) and pressing the Import Signals from Data Tree button. This will add the signal information (Type,Name,Folder) to the command.

Many of the commands that act on signals will not show the signals in the dialog. This can be a bit of an annoyance when there are only a few signals selected, but often commands contain so many signals that the list box in the dialog will become meaningless because of all the signals.

To make it easier to enter the signal types, names, and folders into a command, there is a button to add all "checked" signals from the data tree.

Pipeline Commands: Expressions

For some commands, signals are represented using the a pipeline parameter syntax. This type of syntax is used in the evaluate_expression command. For example, to identify the RFT1 signal we use the syntax TYPE::FOLDER::NAME

TARGET::PROCESSED::RFT1

More details on Expressions and evaluate_expression can be found here: Expressions

Pipeline Parameters

An important feature of the pipeline is the ability to create and use Pipeline Parameters. A PIPELINE PARAMETER is a way to store a text string for use in Pipeline commands.

In one sense it is similar to specifying a global variable, such as body weight, that could be used in computations. It is actually much more flexible than that in the pipeline. The Visual3D pipeline commands permit multiple entries on a single line, and since the entire line can be represented as a string, a single PIPELINE PARAMETER can represent multiple entries.

More details on naming and using parameters in pipelines can be found here: Pipeline Parameters

Editing Pipeline Parameters

Parameters in pipeline commands may be edited in 3 ways:

  1. Using the built-in text editor (select the TEXT Button)
  2. Using a dialog (select the EDIT button). Most, but not all Visual3D commands have an edit dialog. If no dialog exists, then the text editor appears.
  3. Using an independent TEXT editor such as Notepad++.

Pipeline Control

RECALC Pipeline

The RECALC button updates the Visual3D Workspace by performing the following:

  1. If "use processed analog" is set, re-process force platforms.
  2. Rebuild all models in the Workspace
  3. Compute landmarks and model pose (e.g. position and orientation of all segments) for all #files in the Workspace
  4. Assign Force Platforms to Segments
  5. Compute Assigned Forces
  6. Compute Kinematics
  7. Compute Kinetics
  8. Compute Center of Mass.
  9. Execute the RECALC pipeline
  10. Update the display dialogs for any new data
  11. Recompute the Report graphs

More details on RECALC in the Visual3D workspace and pipelines can be found here: Pipeline Commands:RECALC Pipeline

Pipeline Favorites

Pipeline Favorites is a very powerful way for you to list your pipeline scripts as a Table of Contents. Your list of pipeline scripts can be viewed or run from the 'Pipeline Favorites' list box. More detail on pipeline favorites can be found here: Pipeline Commands:Pipeline Favorites

Launching Visual3D & Pipeline Externally

Launching Visual3D from a DOS Command Line (or an external program)

If you have a DOS PATH set to the Visual3D directory you can type

Visual3D.exe

If not, you must specify the full path to Visual3D.

c:\Program Files\Visual3D\Visual3D.exe

It is possible to have a pipeline executed immediately on launching Visual3D using the following syntax.

Visual3D.exe /s c:\exampleData\test.v3s

Note that the full path to the pipeline file is required unless the DOS PATH to this folder is specified.

Creating a Pipeline

Pipeline v3s File

The .v3s file is an ASCII file that can be saved to disk and can be edited with any common word processing program such as Notepad++. When Visual3D loads the .v3s file it parses this ASCII file into the individual commands that are displayed in the pipeline dialog.

Many of the topics in the wiki pages contain pipelines or snippets of pipelines, with a note saying that the text can be copied and pasted into a file.

For example, 

! Starting Fresh - Clear Workspace
File_New 
;

! Create a Hybrid model.
! Prompt for the Standing Trial to use... 
Create_Hybrid_Model 
! /CALIBRATION_FILE= 
; 

! Load the Model Template (Segment Definitions)
Apply_Model_Template 
! /MODEL_TEMPLATE= 
! /CALIBRATION_FILE= 
;

! Prompt for the Movement data files. 
! Multiple files can be selected in the dialog file listing using CTRL-Click 
Open_File
! /FILE_NAME= 
;

! Assigning the Movement files to the model 
! Pop up the dialog box...  
Assign_Model_File
! /CALIBRATION_FILE= 
! /MOTION_FILE_NAMES= 
;

The Process for creating a pipeline from the above text.

  1. Select the pipeline text above, with the right mouse button on the highlighted text select copy.
  2. Open Notepad
  3. Paste into Notepad
  4. Save the Notepad file as TestPipeline.v3s
  5. This command can now be opened in the Visual3D pipeline dialog


Pipeline Examples

See the pipeline examples page for a collection of pipeline processing examples, found here: Pipeline_Examples

Retrieved from ""