Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:pipeline:meta_commands:meta_commands_overview [2024/06/19 12:51] – sgranger
+++ visual3d:documentation:pipeline:meta_commands:meta_commands_overview [2025/04/28 17:38] (current) – Cleaned up formatting and removed references to 3DSSPP. wikisysop
@@ Line 1: / Line 1: @@
-\\
+====== Meta Commands Overview ======
+A meta-command is a Visual3D [[visual3d:documentation:pipeline:general_information:pipeline_commands_reference|pipeline script]] with additional header lines so that you can pass in parameter values. It has a **.v3m** extension instead of **.v3s**. The meta-command should be stored in a folder labelled **Meta-Commands**, which is located in the Visual3D **Plugins** Folder. You will have to create this folder yourself - it is not part of a default installation. The header in the meta-command defines the data that should be passed. A meta-command can be used just like any other command in a pipeline script, and can be used to simply supply values, or it can be used as a macro that includes pipeline commands as well.
-a meta-command is a visual3d pipeline script with additional header lines so that you can pass in parameter values. it has a **.v3m** extension instead of **.v3s**. the meta-command should be stored in a folder labeled **meta-commands**, which is located in the visual3d **plugins** folder. you will have to create this folder yourself - it is not part of a default installation.
+When Visual3D starts, it scans the meta-command directory (identified in the Edit->Preferences dialog) and adds any meta-commands it finds to the pipeline editing dialog. **NOTE**: This means that any meta-command scripts added to the Plugins/Meta-Commands folder after launch will not be available until Visual3D is closed and restarted.
-when visual3d starts, it scans the meta-command directory (identified in the edit->preferences dialog) and adds any meta-commands it finds to the pipeline editing dialog.
+===== Meta-Command Header Syntax =====
-the header in the meta-command defines the data that should be passed. a meta-command can be used just like any other command in a pipeline script, and can be used to simply supply values, or it can be used as a macro that includes pipeline commands as well.
+<code>
+! BEGIN_META //- This line is a mandatory identifier to signal Visual3D
+! META_CMD_NAME = x //- Where x is the name you want your new command to have
+</code>
-\\
+A meta-command can have multiple parameter specifications. Each one formatted:
+<code>
+! META_PARAM = param_name: type : default_parameter : optionality
+</code>
+  - **Param_Name**: what you call your parameter
+  - **Type**: either integer, string, float, or signal
+    - For signal type parameters the signal type, name, and folder are needed in the [:sig_type:sig_name:sig_folder] format
+  - **Default_Parameter**: You can set a default value for the parameter or this can be left blank
+  - **Optionality**: Yes or No, determines if parameter is required or not
-===== meta-command header syntax =====
+<code>
+! END_META //- The mandatory end identifier
-! begin_meta\\
+</code>
-//- this line is a mandatory identifier to signal visual3d//
-\\
-! meta_cmd_name = x\\
-//- where x is the name you want your new command to have//
-\\
-a meta-command can have multiple parameter specifications. each one formatted:\\
-! meta_param = parm_name: type : default_parameter : optionality [:sig_type:sig_name:sig_folder]\\
-//- parm_name = what you call your parameter - followed by :\\
-//
-- type = integer, string, float, signal\\
-- default_parameter = you can set a default value for the parameter, or this can be left blank\\
-- optionality = yes, no determines if parameter is required or not\\
-- for type=signal, the signal type, name, and folder are also needed//\\
-//
-\\
-! end_meta\\
-//- the mandatory end identifier//
-\\
-for example:
+For example:
 <code>
-! begin_meta
+! BEGIN_META
-! meta_cmd_name=terry_rt_plantar_flexors_group
+! META_CMD_NAME=Terry_Rt_Plantar_Flexors_Group
-! meta_param= model_name : string ::yes
+! META_PARAM= MODEL_NAME : string ::yes
-! meta_param= right_thigh_markers : string ::yes
+! META_PARAM= RIGHT_THIGH_MARKERS : string ::yes
-! meta_param= right_shank_markers: string ::yes
+! META_PARAM= RIGHT_SHANK_MARKERS: string ::yes
-! meta_param= right_foot_markers: string ::yes
+! META_PARAM= RIGHT_FOOT_MARKERS: string ::yes
-! end_meta
+! END_META
 </code>
-this command will appear in the visual3d pipeline dialog list box in a folder labeled **meta_commands**. the command will be similar to the following:
+This command will appear in the [[visual3d:documentation:pipeline:pipeline_overview|Visual3D Pipeline Dialog]] list box in a folder labeled **Meta_Commands**. The command will be similar to the following:
 <code>
-terry_rt_plantar_flexors_group
+Terry_Rt_Plantar_Flexors_Group
-/model_name= *model.mdh
+/MODEL_NAME= *model.mdh
-/right_thigh_markers= rgt+rlk+rmk
+/RIGHT_THIGH_MARKERS= RGT+RLK+RMK
-/right_shank_markers= ltt +rla+rma
+/RIGHT_SHANK_MARKERS= LTT +RLA+RMA
-/right_foot_markers= rhl+rft2+rft1
+/RIGHT_FOOT_MARKERS= RHL+RFT2+RFT1
 ;
 </code>
-example of a default parameter: ! meta_param = segment_name:string:rpv:yes
+==== Editing a Meta-Command ====
-==== editing a meta-command ====
-meta-commands are stored on the disk, not in the workspace. in order to edit a meta-command it is necessary to open the file in a text editor such as notepad. the pipeline stores a reference to the meta-command file, rather than loading the meta-command.
-==== meta-command examples ====
-following is a list of meta-command examples:
-=== emg ===
-**1. basic_emg_filters** - basic filtering of emg signals. a series of band-stop (notch) filter for filtering 60 hz noise, followed by a high pass filter at 10 hz and a low pass filter at 350 hz. click [[visual3d:documentation:pipeline:meta_commands:example_-_emg_meta_command|meta commands example 2]] for details.
+Meta-commands are stored on the disk, not in the workspace. In order to edit a meta-command it is necessary to open the file in a text editor such as [[visual3d:documentation:pipeline:general_information:notepad|Notepad++]]. The pipeline stores a reference to the meta-command file, rather than loading the meta-command.
-**2. emg_resting_background and madonna_emg_remove background** - to offset trial data to accommodate for any dc shift by quantifying the emg background noise based on a "resting trial". click [[visual3d:documentation:emg:processing_tools|emg: removing background noise]] for details.
+===== Meta-Command Examples =====
-**3. emg_compute_normalization_factors** - compute the normalization factor for greatest ½ second activity during 5 second trial. a window of twenty-five .02 second intervals of integrated emg is moved one interval at a time across the 5 seconds of data to find the greatest emg. the average integrated emg during the ½ second is used to compute the normalization factor. click [[visual3d:documentation:emg:filtering:removing_dc_bias|emg compute normalization scale factors]] for details.
+Following is a list of Meta-Command Examples:
-**4. emg_normalize** - typically the scaling factors for emg signals are the result of other data trials. individual files in visual3d cannot access the data from other files, so they only way signals can be shared is through the global workspace. for the sake of this example, we will assume that the scale factors already exist in the global workspace. click [[visual3d:documentation:emg:processing:normalize_emg_to_generic_global_variable|emg scale by global value]] for details.
+==== EMG ====
-=== events ===
+**1. Basic_EMG_Filters** - Basic filtering of EMG signals. A series of band-stop (notch) filter for filtering 60 Hz noise, followed by a high pass filter at 10 Hz and a low pass filter at 350 Hz. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Example_-_EMG_Meta_Command|Meta Commands Example 2]] for details.
-**1. copy_events_between_files** - copy event labels from the mocap c3d file into the analog c3d file. one set of analog signals are collected with the mocap system at 1000 hz. one set of analog signals are collected with different software at 1500 hz (frame 1 is synchronized). click [[visual3d:documentation:pipeline:event_commands:example_-_copy_events_between_files|events:example 11]] for details.
+**2. EMG_Resting_Background and Madonna_EMG_Remove Background** - To Offset trial data to accommodate for any DC shift by quantifying the EMG Background noise based on a "Resting Trial". Click [[Visual3D:Documentation:EMG:Processing_Tools|EMG: Removing Background Noise]] for details.
-**2. compute_events_without_grf** - computing gait events from only kinematic data. the following example is based on the following article published in 2008. zeni ja, richards jg, higginson js (2008) two simple methods for determining gait events during treadmill and overground walking using kinematic data. gait & posture 27, 710-714. click [[visual3d:documentation:pipeline:event_commands:example_-_gait_events_using_kinematic_data|events:example 6]] for details.
+**3. EMG_Compute_Normalization_Factors** - Compute the normalization factor for greatest ½ second activity during 5 second trial. A window of twenty-five .02 second intervals of integrated EMG is moved one interval at a time across the 5 seconds of data to find the greatest EMG. The average integrated EMG during the ½ second is used to compute the normalization factor. Click [[Visual3D:Documentation:EMG:Filtering:Removing_DC_Bias|EMG Compute Normalization Scale Factors]] for details.
-**3. sit_to_stand_events** - computing events for sit to stand from vertical height of the center of mass. the subject stands then sits and stands again. click [[visual3d:documentation:pipeline:event_commands:example_-_sit_to_stand_events|events:example 7]] for details.
+**4. EMG_Normalize** - Typically the Scaling factors for EMG signals are the result of other data trials. Individual files in Visual3D cannot access the data from other files, so they only way signals can be shared is through the Global Workspace. For the sake of this example, we will assume that the scale factors already exist in the Global Workspace. Click [[Visual3D:Documentation:EMG:Processing:Normalize_EMG_to_Generic_Global_Variable|EMG Scale by Global Value]] for details.
-**4. number_events_sequentially** - this meta-command will rename an event sequentially across files. there are two examples. one that renames an event_label sequentially and the other example uses this meta-command to find complete cycles across a series of trials. click [[visual3d:documentation:pipeline:meta_commands:number_events_sequentially_using_a_meta-command|number events sequentially using a meta-command]] for details.
+==== Events ====
-=== metrics ===
+**1. Copy_Events_Between_Files** - Copy Event Labels from the motion capture c3d file into the analog c3d file. One set of analog signals are collected with the motion capture system at 1000 Hz. One set of analog signals are collected with different software at 1500 Hz (frame 1 is synchronized). Click [[Visual3D:Documentation:Pipeline:Event_Commands:Example_-_Copy_Events_Between_Files|Events:Example 11]] for details.
-**1. concatenate_gait_metrics** - this meta-command will create the gait metrics for each tag, labeling the global metrics folder by this tag, then concatenated the metrics from all tags into one signal and store it in a global metrics folder labelled all_tags. click [[visual3d:documentation:pipeline:meta_commands:concatenate_gait_metric_signals_using_a_meta-command|concatenate gait metric signals using a meta-command]] for details.
+**2. Compute_Events_Without_GRF** - Computing gait events from only kinematic data. The following example is based on the following article published in 2008. Zeni JA, Richards JG, Higginson JS (2008) Two simple methods for determining gait events during treadmill and overground walking using kinematic data. Gait & Posture 27, 710-714. Click [[Visual3D:Documentation:Pipeline:Event_Commands:Example_-_Gait_Events_using_Kinematic_Data|Events:Example 6]] for details.
-**2. add_index_column_to_metric** - visual3d cannot plot an array of metric values since the metric signals have no time base. this meta-command will create a new column of data containing index numbers, so that we can plot column1 against column2. essentially it creates an array for the metric signal which will have the additional index column. click [[|metrics example 3]] for details.
+**3. Sit_To_Stand_Events** - Computing events for sit to stand from vertical height of the Center of Mass. The subject stands then sits and stands again. Click [[Visual3D:Documentation:Pipeline:Event_Commands:Example_-_Sit_to_Stand_Events|Events:Example 7]] for details.
-=== sdsspp ===
+**4. Number_Events_Sequentially** - This meta-command will rename an event sequentially across files. There are two examples. One that renames an Event_label sequentially and the other example uses this meta-command to find complete cycles across a series of trials. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Number_Events_Sequentially_Using_a_Meta-Command|Number Events Sequentially Using a Meta-Command]] for details.
-**1. create_3dsspp_target_offsets** - this meta-command creates a collection of derived signals that are used for computing the 3dsspp planar angles. this command is used where there is no linkmodel, and therefore no landmarks defined. click [[|create 3dsspp target offsets]] for details.
+==== Metrics ====
-**2. create_3dsspp_projected_angles** - this meta-command computes projected planar angles consistent with the definition of the model pose in the 3dsspp software. click [[|create_3dsspp_projected_angles]] for details.
+**1. Concatenate_Gait_Metrics** - This meta-command will create the gait metrics for each TAG, labeling the GLOBAL Metrics folder by this TAG, then concatenated the metrics from all TAGS into one signal and store it in a GLOBAL METRICS folder labelled ALL_TAGS. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Concatenate_Gait_Metric_Signals_Using_a_Meta-Command|Concatenate Gait Metric Signals Using a Meta-Command]] for details.
-'**3. create_3dsspp_origin_destination_events** - this meta-command creates event labels for the origin and destination of the lift. each of the three tasks, floor-to-waist, knee-to-waist, waist-to-overhead are processed differently for the event detection. these algorithms are not fool-proof, so it is imperative that the user check the events visually. click [[|create_3dsspp_origin_destination_events]] for details.
+**2. Add_Index_Column_To_Metric** - Visual3D cannot plot an array of metric values since the METRIC signals have no time base. This meta-command will create a new column of data containing index numbers, so that we can plot column1 against column2. Essentially it creates an array for the metric signal which will have the additional index column. Click [[|Metrics Example 3]] for details.
-=== other ===
+==== Other ====
-**1. create_global_means_for_left_right** - creates a global_normalized_signal_mean event for left and right sides with common labels (e.g. rhs and lhs). click [[visual3d:documentation:pipeline:signal_commands:signal_management_commands#meta-command_-_create_global_means_for_left_right|create_global_means_for_left_right]] or [[visual3d:documentation:statistics:create_mean_signal|statistics example 1]] for details.
+**1. Create_Global_Means_For_Left_Right** - Creates a Global_Normalized_Signal_Mean event for left and right sides with common labels (e.g. RHS and LHS). Click [[Visual3D:Documentation:Pipeline:Signal_Commands:Signal_Management_Commands#Meta-Command_-_Create_Global_Means_For_Left_Right|Create_Global_Means_For_Left_Right]] or [[Visual3D:Documentation:Statistics:Create_Mean_Signal|Statistics Example 1]] for details.
-**2. set_corners** - creates landmarks from targets in a movement trial but not in the standing trial. the movement trial contains 4 markers that have been placed on the corners of an object. the standing trial does not contain these markers, but needs the corner locations for defining an object (segment). click [[visual3d:documentation:modeling:landmarks:example_-_create_landmarks_from_targets_in_movement_trial|landmarks example 4]] for details.
+**2. Set_Corners** - Creates landmarks from Targets in a movement trial but not in the standing trial. The movement trial contains 4 markers that have been placed on the corners of an object. The standing trial does not contain these markers, but needs the corner locations for defining an object (segment). Click [[Visual3D:Documentation:Modeling:Landmarks:Example_-_Create_landmarks_from_Targets_in_movement_trial|Landmarks Example 4]] for details.
-**3. fp_shift** - meta-command example to shift force platform corners. click [[visual3d:documentation:pipeline:meta_commands:shift_force_platform_corners_using_a_meta-command|shift force platform corners using a meta-command]] for details.
+**3. FP_Shift** - Meta-command example to shift force platform corners. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Shift_Force_Platform_Corners_Using_a_Meta-command|Shift Force Platform Corners Using a Meta-command]] for details.
-**4. add_sequential_tags** - given a set of c3d files opened in the workspace, tag files in numerical order regardless of their filenames. the purpose is to have a series of tags trial1, trial2, trial 3,,..., etc for reporting. the order of the files is based on their internal order in visual3d and may appear random to the user. click [[visual3d:documentation:pipeline:meta_commands:tag_files_sequentially_using_a_meta-command|tag files sequentially using a meta-command]] for details.
+**4. Add_Sequential_Tags** - Given a set of C3D files opened in the Workspace, TAG files in numerical order regardless of their filenames. The purpose is to have a series of TAGS Trial1, Trial2, Trial 3,,..., etc for reporting. The order of the files is based on their internal order in Visual3D and may appear random to the user. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Tag_Files_Sequentially_using_a_Meta-Command|Tag Files Sequentially using a Meta-Command]] for details.
-**5. example_meta** - this is an example of using a meta-command to process differing experimental protocols, models, metrics, and reports. the specifics for each experimental protocol can be passed as meta-command parameters. this could be used to standardize scripts and protocols within a lab. click [[visual3d:documentation:pipeline:meta_commands:example_-_meta_command_parameters|meta commands example 3]] for details.
+**5. Example_Meta** - This is an example of using a meta-command to process differing experimental protocols, models, metrics, and reports. The specifics for each experimental protocol can be passed as meta-command parameters. This could be used to standardize scripts and protocols within a lab. Click [[Visual3D:Documentation:Pipeline:Meta_Commands:Example_-_Meta_Command_Parameters|Meta Commands Example 3]] for details.
-**6. linear_regression_explicit** - this is an example of using a meta-command to perform a linear regression of data that is passed as meta-command parameters. click [[visual3d:documentation:statistics:compute_linear_regression|statistics example 4]] for details.
+**6. Linear_Regression_Explicit** - This is an example of using a meta-command to perform a linear regression of data that is passed as meta-command parameters. Click [[Visual3D:Documentation:Statistics:Compute_Linear_Regression|Statistics Example 4]] for details.
-**7. linear_regression_events** - this is an example of using a meta-command to perform a linear regression between an event range for data that is passed as meta-command parameters. click [[visual3d:documentation:statistics:meta_command_for_linear_regression|statistics example 5]] for details.
+**7. Linear_Regression_Events** - This is an example of using a meta-command to perform a linear regression between an event range for data that is passed as meta-command parameters. Click [[Visual3D:Documentation:Statistics:Meta_Command_for_Linear_Regression|Statistics Example 5]] for details.