====== 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]]