Differences

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

--- visual3d:documentation:pipeline:file_commands:file_rename [2024/06/17 17:06] – removed sgranger
+++ visual3d:documentation:pipeline:file_commands:file_rename [2025/07/30 14:59] (current) – wikisysop
@@ Line 1: / Line 1: @@
+====== File Rename ======
+===== 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.
+===== Pipeline Command =====
+The command below is as seen on the Visual3D application, the parameters allow for manipulation of the command's options.
+<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>
+===== Command Parameters =====
+The following table shows the command parameters and descriptions:
+|**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.|
+===== Dialog =====
+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|}}
+  * **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.
+===== Examples =====
+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
+! /NEW_FILE_NAME=
+/USE_SEARCH_REPLACE=TRUE
+/SEARCH_FOR=Walk
+/REPLACE_WITH=Run
+/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]]