Differences

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

--- visual3d:documentation:pipeline:file_commands:file_save_as [2024/06/19 13:59] – created sgranger
+++ visual3d:documentation:pipeline:file_commands:file_save_as [2025/06/09 21:15] (current) – wikisysop
@@ Line 1: / Line 1: @@
-Save the current Workspace to a new CMO file. A dialog will appear to allow the user to select the new file.
+====== File Save As ======
+===== Overview =====
+The **File_Save_As** command is used to save the currently active workspace to a **new file**, rather than overwriting the original.
+  * Works similar to a "Save As" button: the user can specify a new file name and destination folder.
+  * This command is commonly used when you want to preserve the original CMZ file, and instead save a modified version with updates (e.g., added events, new model data, etc.)
+**Important Note:**
+There is an important distinction between this command and **[[visual3d:documentation:pipeline:file_commands:file_save|File_Save]]**.
+  * File_Save saves directly to the currently open CMZ file.
+  * File_Save_As creates a new file: nothing is overwritten unless you specify the same name.
+===== Pipeline Command =====
+The command below is as seen on the Visual3D application, it has parameters as options to manipulate this command.
 <code>
 File_Save_As
+!/FILE_NAME=
+!/FOLDER=
+!/SET_PROMPT=Save CMZ file as
+!/SAVE_EMBEDDED_GRAPHICS=FALSE
+!/CREATE_FOLDER_PATH=FALSE
 ;
 </code>
-\\
+===== Command Parameters =====
+The following table shows the command parameters and descriptions.
+|**Parameter**  |**Description**|
+|**! /FILE_NAME=**| Name of the new file to save the workspace into- this file will be created.|
+|**! /FOLDER=**  | Folder to save the file in, can be a full or relative path.|
+|**! /SET_PROMPT=**|Text to display in the save dialog window if the user is prompted.|
+|**! /SAVE_EMBEDDED_GRAPHIC=FALSE**|If 'TRUE', embedded 3D graphics/visuals ae saved inside the CMZ file.|
+|**! /CREATE_FOLDER_PATH=FALSE**|If 'TRUE', Visual3D will create the folder path if it does not already exist.|
+===== Dialog =====
+The command can be edited in a text editor or in dialog form. To edit in the dialog pop up form 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:filesaveas_dlgbox.png?400|}}
+  * **Select Filename**: Choose or type the name of the new CMZ file you want to save.
+  * **Select Folder**: Choose the folder where the new file should be saved. If the filename entered above includes a full path, this folder selection is ignored.
+  * **Checkbox - if file path doesn't exist, create a new one**: If checked, Visual3D will automatically create the folder path if it does not exist yet.
+  * **Prompt**: This text appears as the title of the Save dialog if you're prompting the user.
+===== Examples =====
+The following examples will go through the use of the File_Save_As command in the Visual3D application.
+==== Example 1: Save with added model data ====
+This pipeline loads a file, computes model-based data - in this case the Left Knee Angle, and saves the updated version as a new CMZ.
+<code>
+File_Open
+!/FILE_NAME=Subject01
+!/FILE_PATH=Trials/
+!/SEARCH_SUBFOLDERS=FALSE
+!/SUFFIX=_Gait.cmz
+!/SET_PROMPT=
+!/ON_FILE_NOT_FOUND=SKIP
+!/FILE_TYPES_ON_PROMPT=
+;
+Compute_Model_Based_Data
+/RESULT_NAME=Left_Knee_Angle
+/SUBJECT_TAG=
+/FUNCTION=JOINT_ANGLE
+/SEGMENT=Left_Knee
+!/REFERENCE_SEGMENT=Pelvis
+!/RESOLUTION_COORDINATE_SYSTEM=LAB
+!/USE_CARDAN_SEQUENCE=TRUE
+!/NORMALIZATION=FALSE
+;
+File_Save_As
+!/FILE_NAME=Subject01_Updated.cmz
+!/FOLDER=Processed/
+!/SET_PROMPT=Save updated CMZ
+!/SAVE_EMBEDDED_GRAPHICS=FALSE
+!/CREATE_FOLDER_PATH=TRUE
+;
+</code>
+==== Example 2: Save a custom trial version with embedded graphics and folder creation ====
+This pipeline loads a trial, detects peak vertical force, extracts the Force Value at this event, and saves a new version including 3D graphics output.
+<code>
+File_Open
+!/FILE_NAME=Participant_Trial03
+!/FILE_PATH=GaitData/
+!/SEARCH_SUBFOLDERS=FALSE
+!/SUFFIX=.cmz
+!/SET_PROMPT=
+!/ON_FILE_NOT_FOUND=PROMPT
+!/FILE_TYPES_ON_PROMPT=
+;
+Event_Global_Maximum
+/RESULT_EVENT_NAME=Peak_Vertical_Force
+/SIGNAL_TYPES=ANALOG
+/SIGNAL_FOLDER=ORIGINAL
+/SIGNAL_NAMES=Force
+/SIGNAL_COMPONENTS=Z
+/FRAME_OFFSET=0
+/TIME_OFFSET=
+/EVENT_SEQUENCE=RHS,RTO
+/EXCLUDE_EVENTS=
+/EVENT_SEQUENCE_INSTANCE=0
+/EVENT_SUBSEQUENCE=
+/SUBSEQUENCE_EXCLUDE_EVENTS=
+/EVENT_SUBSEQUENCE_INSTANCE=0
+/THRESHOLD=500
+;
+Metric_Signal_Value_At_Event
+/SIGNAL_FOLDER=EVENT_LABEL
+/SIGNAL_LABEL=Z
+/EVENT_NAME=Peak_Vertical_Force
+/RESULT_METRIC_NAME=Vertical_Force_Peak
+;
+File_Save_As
+!/FILE_NAME=Participant_Trial03_ForcePeak.cmz
+!/FOLDER=Saved_Metrics/
+!/SET_PROMPT=Save trial with force peak
+!/SAVE_EMBEDDED_GRAPHICS=TRUE
+!/CREATE_FOLDER_PATH=TRUE
+;
+</code>
+----
 [[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Commands_Reference|Back to Pipeline Commands Reference]]