Differences

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

--- sift:directory_watchers [2025/02/06 15:34] – created sgranger
+++ sift:directory_watchers [2025/02/06 16:49] (current) – sgranger
@@ Line 1: / Line 1: @@
-==Directory Watcher==
+===== Directory Watchers =====
-Watchers are a powerful tool to automate your workflow,
+Watchers are a powerful tool to automate your workflow, Sift can be set to run in the background and "Watch" directories, when a file as added or removed from one of these directories and list of predefined scripts can be executed. If you have a consistent processing pipeline, this can be set to run as soon as your source file are loaded onto you drive, with no direct user input needed!
-== Watcher Files ==
+===== Watcher Files =====
-Watcher files are stored as a XML within your PCs AppData folder, it is possible to create remove and edit these files directly. This can even be done through external scripting tools to automate the process of creating watchers themselves
+Watchers are stored as a XML file within you PCs AppData folder, it is possible to create, remove, and edit these files directly as long as the formatting is maintained. This can even be done through external scripting tools allowing you to even automate the process of creating and editing watchers.
-the AppData folder is hidden by default on most windows systems and can be found [path to appdata]
+"C:\Users\UserName\AppData\Roaming\HAS-Motion, Inc\Sift\watchers" \\
+{{sift_watcher_xml.png}} \\
-[file structure]
-==Creating a Watcher==
+the AppData folder is hidden by default on most windows systems file explorer can be set to show hidden files by accessing **View** on the top toolbar and selecting **Show -> Hidden items** \\
-Watchers can be created through the sift command line through the -CreateWatcher command
+{{windows_hidden_items.png}} \\
--CreateWatcher
+===== Creating, Editing, and Deleting Watchers =====
-name - This is the name used to reference the directory watcher, it will be the name of the xml file
+In addition to interacting with the files directly, Watchers can be controlled through the following commands on the Sift command line:
-directory - this is the directory that will be watched, this can be passed more than once to watch multiple directories
-script - this is a script to be executed upon triggering the watcher, the script can be a .v3s pipeline or a .bat script in the case of a .bat script the first line of the script must be ##SIFT (This ensures only scripts fully intended for sift are executed), the script command can be passed multiple times to execute multiple scripts, the scripts will be executed in the order they are passed.
-Recursive - if this is passed all sub-directories within a watched directory will also be watched.
-delay - a delay is important, as if you were to move several file into a watcher directory at once, a trigger would be made for each file. The delay is the number of ms to wait from trigger to execution, the delay will be reset with each new file, ensuring that everything is only triggered once. ALternativly you could set a large delay if you want things to run a certain time after you're done working.
-overwrite - if this watcher will overwrite any existing watchers with the same name, otherwise the command will fail
--listwatchers
+----
+==== -CreateWatcher / -cw ====
+----
+Create a new Directory Watcher, the file will automatically be saved to the AppData watcher folder, by default all new watchers a set to active.
+=== Parameters ===
+== Name (Required) ==
+This is the name used to reference the directory watcher, it will be the name of the xml file \\
+== Directory (Required) ==
+This is the directory that will be watched, this can be passed more than once to watch multiple directories \\
+== Script (Required) ==
+This is a script to be executed upon triggering the watcher, the script can be a .v3s pipeline or a .bat script in the case of a .bat script the first line of the script must be ::SIFT (This ensures only scripts fully intended for sift are executed), the script command can be passed multiple times to execute multiple scripts, the scripts will be executed in the order they are passed. \\
+== Recursive ==
+If this is passed all sub-directories within a watched directory will also be watched. \\
+== Delay ==
+The time in milliseconds between a trigger and the execution of the script(s). A delay is important, as if you were to move several file into or out of a watched directory at once, a trigger would be made for each file. The delay will be reset with each new file, ensuring that everything is only triggered once. Alternatively you could set a large delay if you want things to run a certain time after you're done working, or if you do want the watcher to trigger for each individual event, set delay to 0\\
+<sub>//Default:// 3000</sub>
+== Overwrite ==
+If passed this watcher will overwrite any existing watchers with the same name, otherwise the command will fail \\
+=== Example ===
+<code>-CreateWatcher name "EXAMPLE_WATCHER" directory "C:\Input_Data" script "C:\Scripts\V3D_Script.v3s" script "C:\Scripts\Sift_Script.bat" delay "4000" recursive overwrite</code>
+----
+==== -listwatchers / -lw ====
+----
 This command will list all watchers and their parameters
--deleteWatcher "name"
+----
-use this command and pass the name of a watcher to delete it.
+==== -deleteWatcher / -dw ====
-==Using Watcher==
+----
-For watchers to work Sift must be running in the background, from the system tray, to launch Sift in background mode you can either pass the command -LaunchMinimized, which will set Sift to always launch in the background, or -LaunchBackgroundInstance which will immediatly launch Sift to the background with out setting it to do so by default.
+Use this command and pass the name of a watcher to delete it.
+=== Parameters ===
+== name (Required) ==
+The name of the watcher to delete
+=== Example ===
+<code>-DeleteWatcher name "Example_Watcher_Two"</code>
+----
+==== -ActivateWatcher / -aw ====
+----
+Used to activate the passed watcher(s)
+=== Parameters ===
+== name ==
+The name of the watcher to be activated can be passed multiple times to activate multiple watchers, if no name is passed all watchers will be activated \\
+=== Example ===
+<code>-ActivateWatcher name "Example_Watcher" name "Example_Watcher_Two" </code>
+----
+==== -DeactivateWatcher / -daw ====
+----
+Used to deactivate the passed watcher(s)
+=== Parameters ===
+== name ==
+The name of the watcher to be deactivated, can be passed multiple times to deactivate multiple watchers, if no name is passed all watchers will be deactivated \\
+=== Example ===
+<code>-DeactivateWatcher name "Example_Watcher" name _Example_Watcher_Two" </code>
+===== Using Watchers =====
+For watchers to work Sift must be running in the background, from the system tray, to launch Sift in background mode you can either pass the command -LaunchMinimized, which will set Sift to always launch in the background, or -LaunchBackgroundInstance which will immediately launch Sift to the background with out setting it to do so by default.
 once sift is running in the background you can interact with it via the system tray icon
-from here you can
+{{sift_tray.png}} \\
+from here you can \\
+  * **Open GUI** - this will open a standard instance of sift with a GUI
+  * **Open Console** - this will open a console instance of sift, only one console instance of sift can run at a time
+  * **Quit** - this will close the background instance of sift, all other instances will remain open
+  * **Disable Start in Tray** - If you have sift set to launch in the background by default, this will disable it
+  * **Watchers** - if you have any active watchers they will be found here, within this list you can enable or disable individual watchers or enable or disable all watchers
+{{sift_tray_watchers.png}} \\
+when a watcher is triggered all v3d pipelines will be run in the background, however all .bat scripts will open a command line interface, if you are running sift commands a command line instance of sift will open, this will not work if you already have sift open on the console, or if a script is triggered while another is still be processed.
+==== BATCH Files ====
+Any .bat file can be executed via Directory Watchers, as long as the first line of the file is a BATCH comment containing SIFT (::SIFT) in order to run Sift commands via directory watchers you must first call Sift and pass it the desired commands
-open gui - this will open a standard instance of sift with a GUI
+=== Example ===
-open console - this will open a console instance of sift, only one console instance of sift can run at a time
+<code>
-quit - this will close the background instance of sift, all other instances will remain open
+::SIFT
-Disable start in tray - If you have sift set to launch in the background by default, this will disable it
-Watchers - if you have any active watchers they will be found here, within this list you can enable or disable individual watchers or enable or disable all watchers
-when a watcher is triggered all v3d pipelines will be run in the background, however all .bat scripts will open a commandline interface, if you are running sift commands a command line instance of sift will open, this will not work if you already have sift open on the console, or if a script is triggered while another is still be processed.
+"C:\Program Files\Sift\Sift.exe" -LoadLib "C:\Input_Data" -LoadQuery "C:\Input_Data\Query.q3d" -SaveProject "C:\Input_Data\Sift_Queried_Data.i3d" -Exit
+</code>
-[batch example]
+Windows BATCH scripting is a powerful tool and much more logic can be put into them, see the [[sift:tutorials:command_line|Batch Processing Tutorial]] For a slightly more complex example, for a step by step guide on creating and using Directory Watchers see the [[sift:tutorials:using_directory_watchers|Using Directory Watchers Tutorial]]