====== File Open ======

===== Overview =====
The **File_Open** pipeline command is used to load a file into the Visual3D workspace.
  * Usually, this command is the first step in a pipeline as all subsequent operations rely on having an active file loaded.
  * For supported file and filter types, see the notes section.

===== Pipeline Command =====
The command below is as seen in the Visual3D application.

<code>
File_Open
! /FILE_NAME=
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
;
</code>

===== Command Parameters =====

The following table shows the command parameters:

|**Parameter**               |**Description** |
|**/FILE_NAME=**             |Name of the file being opened. This can be left blank if prompting the user|
|**/FILE_PATH=**             |Path to the folder where the file is stored.|
|**/SEARCH_SUBFOLDERS=FALSE**| If set to 'TRUE', Visual3D will also search in subfolders under 'FILE_PATH'|
|**/SUFFIX=**                |Optional suffix to append to the base file name.|
|**/SET_PROMPT=File_Open**   |If provided, prompts the user with a dialog box titled with this label to choose a file manually.|
|**/ON_FILE_NOT_FOUND=PROMPT**|If the file is not found, 'PROMPT' or 'SKIP'|
|**/FILE_TYPES_ON_PROMPT**    |Filter for the file types when using prompt.|

===== Dialog Box =====
The command can be edited in a text editor or in a 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_open_emptydlgbox.png?550|}}

  * **Select Filename**: Manually browse for and select the specific file you want to open.
  * **Select Filepath (Optional)**: Choose the folder where the file is stored.
  * **Suffix**: If a file with this suffix exists in the folder, it will be automatically added to the file name.
  * **Search Subfolders**: If checked, Visual3D will search within subfolders of the specified file path to find the file.
  * **Prompt**: Sets the title shown in the file selection dialog when prompting the user to choose a file.
  * **Action on File Not Found**: What Visual3D should do if the file is not found. Options include PROMPT or SKIP
  * **File Mask on Prompt**: A filter for which file types appear in the dialog.

===== Examples =====

The following examples will go through the use of the **File_Open** command within the Visual3D application. 

=== Example 1: Prompt the user for the filename ===

This example will prompt the user for the files by opening a dialog box for selection.

<code>
File_Open
/FILE_NAME=
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
;
</code>

=== Example 2: Specify the filename ===

This example specifies the filename explicitly. Note that the filename should contain the complete path to the file.

<code>
File_Open
/FILE_NAME= c:\demo_files\walking.c3d 
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
;
</code>

=== Example 3: Specify the filename using wildcards ===

This example specifies the filename by using a wildcard. All C3D files in the c:\demo_files folder will be opened.

<code>
File_Open
/FILE_NAME= c:\demo_files\*.c3d 
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
</code>

=== Example 4: Specify the filename using a pipeline parameter and wildcards ===

This example uses [[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Parameters|Pipeline Parameters]] to specify the folder containing the data files and uses a wildcard in the filename

<code>
Set_Pipeline_Parameter_To_Folder_Path
/PARAMETER_NAME= DATA_FOLDER
/PARAMETER_VALUE=c:\demo_files
;

! Now open the file.
File_Open
/FILE_NAME= ::DATA_FOLDER&*.c3d 
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
</code>

=== Example 5: Specify the filename using the default data folder and wildcards ===

This example uses [[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Parameters|Pipeline Parameters]] to specify the [[Visual3D:Documentation:Dialogs:Program_Options#Default_Folders|default data folder]] containing the data files and uses a wildcard in the filename.

<code>
Set_Pipeline_Parameter_To_Folder_Path
/PARAMETER_NAME= DATA_FOLDER
/PARAMETER_VALUE=VISUAL3D_DEFAULT_DATA_FOLDER
;

! Now open the file.
File_Open=
File_Open
/FILE_NAME= ::DATA_FOLDER&*.c3d 
! /FILE_PATH=
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
</code>

===== Notes =====

=== File_Types ===

The following file types are supported and can be added within Visual3D:

  * .c3d - C3D File or [[[http://www.c3d.org|www.c3d.org]]]
  * .cmo - Visual3D Workspace File
  * .txt - Visual3D TAB delimited text File
  * .gcd - Vicon GCD File
  * .ndi - NDI Aurora File
  * .p2d - P2D File

=== Filter ===

You can filter using the following filter types:

  * C3D
  * CMO
  * VND
  * P2D
  * ASCII
  * XML
  * NDI
  * GCD
  * MVNX

Multiple file types can be specified by using a plus sign (ex. C3D+CMO+P2D)

[[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Commands_Reference|Back to Pipeline Commands Reference]]