Differences

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

--- visual3d:documentation:pipeline:file_commands:file_open [2024/06/19 13:59] – created sgranger
+++ visual3d:documentation:pipeline:file_commands:file_open [2025/05/16 16:28] (current) – wikisysop
@@ Line 1: / Line 1: @@
-The command **File_Open** command will add a file to the Visual3D Workspace. The command is as follows:
+====== File Open ======
-**File_Open**
+===== Overview =====
-/File_Name= File_Name is the file name or file mask including the path.
+The **File_Open** pipeline command is used to load a file into the Visual3D workspace.
-/File_Path= The path string that will be pre-pended to the File_Name
+  * Usually, this command is the first step in a pipeline as all subsequent operations rely on having an active file loaded.
-/Search_Subfolder= Search all subfolders for files matching the filename or file mask
+  * For supported file and filter types, see the notes section.
-!/Suffix= Text here will be added to the end of the C3D file which is loaded.
-!/Set_Prompt= This parameters sets the text in the upper left hand corner of the browse window
-!/On_File_Not_Found=PROMPT
-!/File_Types_On_Prompt= This parameter sets the type of files the dialog will show (CMO, C3D, ASCII, etc)
-**;**
-**Note:** If **/File_Name=** is blank, a dialog pops up to allow the user to browse to the file. Wildcards (*) can be used in place of the file name.
-===== File_Types =====
+===== Pipeline Command =====
+The command below is as seen in the Visual3D application.
-The following file types are supported and can be added within Visual3D:
+<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>
-  * .c3d - C3D File or [[[http://www.c3d.org|www.c3d.org]]]
+===== Command Parameters =====
-  * .cmo - Visual3D Workspace File
-  * .txt - Visual3D TAB delimited text File
-  * .gcd - Vicon GCD File
-  * .ndi - NDI Aurora File
-  * .p2d - P2D File
-===== Filter =====
+The following table shows the command parameters:
-You can filter using the following filter types:
+|**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.|
-  * C3D
+===== Dialog Box =====
-  * CMO
+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.
-  * VND
-  * P2D
-  * ASCII
-  * XML
-  * NDI
-  * GCD
-  * MVNX
-Multiple file types can be specified by using a plus sign (ex. C3D+CMO+P2D)
+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 =====
-This page lists several examples for this command.
+The following examples will go through the use of the **File_Open** command within the Visual3D application.
-==== Prompt the user for the filename ====
+=== Example 1: Prompt the user for the filename ===
 This example will prompt the user for the files by opening a dialog box for selection.
@@ Line 49: / Line 59: @@
 <code>
 File_Open
-/File_Name=
+/FILE_NAME=
+! /FILE_PATH=
+! /SEARCH_SUBFOLDERS=FALSE
+! /SUFFIX=
+! /SET_PROMPT=File_Open
+! /ON_FILE_NOT_FOUND=PROMPT
+! /FILE_TYPES_ON_PROMPT=
 ;
 </code>
-==== Specify the filename ====
+=== 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_Open
-/File_Name= c:\demo_files\walking.c3d
+/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>
-==== Specify the filename using wildcards ====
+=== 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_Open
-/File_Name= c:\demo_files\*.c3d
+/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>
-==== Specify the filename using a pipeline parameter and wildcards ====
+=== 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
@@ Line 84: / Line 111: @@
 ! Now open the file.
-File_Open=
+File_Open
-/File_Name= ::DATA_FOLDER&*.c3d
+/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>
-==== Specify the filename using the default data folder and wildcards ====
+=== 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.
@@ Line 101: / Line 133: @@
 ! Now open the file.
 File_Open=
-/File_Name= ::DATA_FOLDER&*.c3d
+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 =====
-\\
-[[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Commands_Reference|Back to Pipeline Commands Reference]]
+=== 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]]