Differences

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

--- visual3d:documentation:pipeline:file_commands:file_rename [2024/06/19 13:59] – created sgranger
+++ visual3d:documentation:pipeline:file_commands:file_rename [2025/07/30 14:59] (current) – wikisysop
@@ Line 1: / Line 1: @@
-\\
+====== File Rename ======
-Renames the specified file(s). This can also be done manually by going to File->Rename.
-|<code>\\ File_Rename\\ ! /EXISTING_FILE_NAME=ALL_FILES\\ ! /NEW_FILE_NAME=\\ ! /USE_SEARCH_REPLACE=FALSE\\ ! /SEARCH_FOR=\\ ! /REPLACE_WITH=\\ ! /REMOVE_FILE_PATH=FALSE\\ ! /RENAME_STATIC_CALIBRATION_FILES=TRUE\\ ; \\ </code>  |  {{FileRenameDialog.png}}|
+===== Overview =====
-\\
+The **File_Rename** command in Visual3D is used to rename one or more existing C3D files in the workspace. This command is especially helpful when automating naming conventions for large datasets or batch-processing files across multiple subjects or trials.
+This is equivalent to selecting **File > Rename** from the Visual3D application menu. The command provides flexible renaming options, including the ability to use Search/Replace, remove file paths, and rename associated static calibration files.
-==== Parameters ====
+===== Pipeline Command =====
-  * **EXISTING_FILE_NAME:** ALL_FILES can be specified here, or an individual C3D file can be selected\\
+The command below is as seen on the Visual3D application, the parameters allow for manipulation of the command's options.
-  * **NEW_FILE_NAME:** If renaming an individual C3D file, the new name can be specified here\\
+<code>
-  * **USE_SEARCH_REPLACE:** Specify TRUE or FALSE to use the search/replace function. This must be used in conjunction with the SEARCH_FOR and REPLACE_WITH parameters.\\
+File_Rename
+! /EXISTING_FILE_NAME=ALL_FILES
+! /NEW_FILE_NAME=
+! /USE_SEARCH_REPLACE=FALSE
+! /SEARCH_FOR=
+! /REPLACE_WITH=
+! /REMOVE_FILE_PATH=FALSE
+! /RENAME_STATIC_CALIBRATION_FILES=TRUE
+;
+</code>
-  * **SEARCH_FOR:** Specifies what text will be removed. This must be used in conjunction with the REPLACE_WITH and REPLACE_WITH parameters.\\
+===== Command Parameters =====
-  * **REPLACE_WITH:** Specifies what text will be put in place of "SEARCH_FOR" text. This must be used in conjunction with the SEARCH_FOR and USE_SEARCH_REPLACE parameters.\\
+The following table shows the command parameters and descriptions:
-  * **REMOVE_FILE_PATH:** Specify TRUE or FALSE to remove file path.
+|**Parameter**|**Description**|
+|**! /EXISTING_FILE_NAME=ALL_FILES**|The file(s) to be renamed. You can specify a single file, ALL_FILES, or a wildcard.|
+|**! /NEW_FILE_NAME=**|The new name to assign. Only used when renaming a single file without search/replace.|
+|**! /USE_SEARCH_REPLACE=FALSE**|If TRUE, activates search/replace renaming logic.|
+|**! /SEARCH_FOR=**|The string in the filename to find when using search/replace.|
+|**! /REPLACE_WITH=**|The string to replace the found text with.|
+|**! /REMOVE_FILE_PATH=FALSE**|If TRUE, removes the file path prefix from the file name|
+|**! /RENAME_STATIC_CALIBRATION_FILES=**|If TRUE, will also rename any static calibration files linked to the C3D.|
-**NOTE:** Since users use similar naming conventions for C3D files, Visual3D stores the file path from where the C3D file was original loaded to differentiate between different files. Only remove the file path if you have a very good reason, and if you do, be careful when comparing between subjects, sessions, conditions, etc.\\
+===== Dialog =====
-  * **RENAME_STATIC_CALIBRATION_FILES:**Specify TRUE or FALSE to also perform search/replace on the static trial.\\
+The command can be edited in the text editor, or in dialog form. To edit in the dialog, either click on the Edit button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below:
+{{:visual3d:documentation:pipeline:file_commands:file_rename_dlg.png?400|}}
-==== Example1: Search/Replace ====
+  * **Existing File(s)**: Dropdown to select a specific file or ALL_FILES.
+  * **New File Name**: Used to rename one file to a new fixed name.
+  * **Remove File Paths**: Options to strip the full file path from the file reference in workspace.
+  * **Rename using Search/Replace**: Enables the lower section for text substitution.
+  * **Search For/Replace With**: Provide the substring to search and the new text to replace it with.
+  * **Also Rename Static Calibration Files**: Ensures associated calibration files are renamed accordingly.
-The search/replace function in this command can be used to rename the C3D files in the workspace.
+===== Examples =====
-In the following example, the C3D files have the name "Sub01_Walk001.c3d" but they are renamed to "Sub01_NEW_NAME001.c3d".
+The following example will go through the use of the **File_Rename** command in the Visual3D application.
+==== Example 1: Search/Replace ====
+This example demonstrates how to rename multiple files using search/replace logic.
+Assume you have accidentally named your RUNNING trial files with the prefix "Walk": **Sub01_Walk001.c3d, Sub01_Walk002.c3d, etc.**
+You want to rename these **Sub01_Run001.c3d, Sub01_Run002.c3d, etc.**
 <code>
 File_Rename
-! /EXISTING_FILE_NAME=ALL_FILES
+/EXISTING_FILE_NAME=ALL_FILES
 ! /NEW_FILE_NAME=
 /USE_SEARCH_REPLACE=TRUE
-/SEARCH_FOR=WALK
+/SEARCH_FOR=Walk
-/REPLACE_WITH=NEW_NAME
+/REPLACE_WITH=Run
-! /REMOVE_FILE_PATH=FALSE
+/REMOVE_FILE_PATH=FALSE
+/RENAME_STATIC_CALIBRATION_FILES=TRUE
+;
+</code>
+This command scans all loaded files and replaces the word "Walk" with "Run" in each filename. The numeric suffix (e.g., 001, 002) remains unchanged. The static calibration files are renamed along with the motion files.
+=== Example 2: Rename File After Gait Event Detection ===
+This example walks through a typical workflow where a CMZ workspace is loaded, gait events are applied, and the resulting workspace in Visual3D is renamed and saved.
+Step 1: Clear workspace and load file which does not have Gait Events already loaded
+<code>
+File_New
+;
+File_Open
+/FILE_NAME=Data_Files\Sub04_Workspace.cmz ! USER INPUT - Change to desired file path/name
+! /FILE_PATH=
+! /SEARCH_SUBFOLDERS=FALSE
+! /SUFFIX=
+! /SET_PROMPT=File_Open
+! /ON_FILE_NOT_FOUND=PROMPT
+! /FILE_TYPES_ON_PROMPT=
+;
+</code>
+Step 2: Apply automatic gait events and then rename the workspace file to reflect the change.
+<code>
+Automatic_Gait_Events
+! /FRAME_WINDOW=8
+! /USE_TPR=TRUE
+! /TPR_EVENT_INSTANCE=1
+;
+File_Rename
+/EXISTING_FILE_NAME=Data_Files\Sub04_Workspace.cmz
+/NEW_FILE_NAME=Sub04_Workspace_with_GaitEvents.cmz
+! /USE_SEARCH_REPLACE=FALSE
+! /SEARCH_FOR=
+! /REPLACE_WITH=
+! /REMOVE_FILE_PATH=
 ! /RENAME_STATIC_CALIBRATION_FILES=TRUE
 ;
 </code>
-\\
+Renames the updated file with a new name to reflect that gait events were added.
+===== Notes =====
+  * This command only renames files inside the Visual3D workspace. If you want to rename physical files on disk, that must be handled externally.
+----
 [[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Commands_Reference|Back to Pipeline Commands Reference]]