Automation Guide¶

Preface¶

This documentation is intended to provide insight into the workings of the Automation tool (the “Tool”). The Tool is currently under active development. Parts of this manual may become outdated or incomplete as development progresses.

Overview of Automation¶

The Automation tool is intended to automate the intake and processing of scan data in PKS. Where PKS supports a direct interaction with a scanner, Automation is able to automate the collection of scan data by communicating directly with hardware. In other cases, the Tool is able to monitor a user-selected Base Directory for new scan data.

This feature is ideal for cases where:

1. Scan data has already been collected and a user is seeking to experiment with different workflows, or
2. A User is seeking to automate the processing of scan data in bulk, and has written a script (outside of PKS/the Tool) that is able to ‘load’ scan data into the base directory for processing.

Where the Tool is being used to generate deviation analyses between scan data and a reference file, users also have the option of generating a log file for recordkeeping purposes.

Some features of the Tool are still under active development. In the future, scripting hooks will be incorporated into the Tool’s pipeline in order to increase its extensibility and customizability to meet the specific requirements of our users.

UI/UX¶

The GUI is split into two sections:

1. A section to configure the source of the scan data to be processed by the tool.
2. A section (titled “Settings”) to tailor the alignment, processing, and analysis required for a user’s specific needs.

Also part of the UI, but not represented in the Automation tool’s GUI, is SAPPServer. SAPPServer is accessed outside of the Automation window in PKS. It is accessible via the Main Menu bar under Settings:

The remainder of the UI is the normal PKS backsplash. When in the Automation window, PKS will render scan data, reference data, and results based on the User’s selected settings and the stage of the pipeline that the tool is in at a given moment.

States¶

The Tool is a finite-state machine. Each State has its own requirements and conditions for transitioning to the next state. The exact behavior that occurs within a State will depend on the User’s settings.

Off¶

The Tool’s starting State. The Tool is not performing any tasks. It may not be fully configured, or it may be configured and waiting for user input to transition into the next State.

Idle¶

The Tool has been configured with all necessary parameters to run. It may be:

1. Starting an iteration of the Tool’s pipeline,
2. Monitoring the Base Directory for scan data, or
3. Finishing an iteration of the Tool’s pipeline.

When the Tool is in this state it is waiting (idling) for further input. The nature and origin of this input will depend on the Tool’s mode. When Directory Monitoring is selected, the input comes in the form of a flag indicating all scan data is present in the Base Directory and ready for processing. Where scanners are being used to directly collect scan data, the input will either be clicking the “Scan” button in the UI, the “Next” button in the UI, or SAPPServer will send a similar command once it has received a scan instruction from an external source.

Scan¶

The Tool will proceed with collecting data from the source selected by the user. When Directory Monitoring is selected, the Tool will read and load all scan data included in the <Base Directory>/scans subfolder.

When Scanner is selected, the Tool will collect the number of scans selected by the user in the UI using the hardware connected to PKS.

Scan In Progress¶

Two preconditions are required for the Tool to be in this state. First, Scanner mode is selected in the UI. Second, the user must have chosen to collect data in multiple (more than 1) stages.

In order to exit this state, the user must provide a command to continue scanning(either via the UI or SAPPServer) and move to the Scan state again, or to Reset the Tool and return it to the Idle state.

Prepare Data¶

The Tool has received all expected input and data has been loaded into PKS. At this stage, any global transformation data for a given Group will be applied to the individual scans within each Group. If the Filter option is selected, all scan data will also be filtered for isolated vertices.

Process Data¶

The Tool will now attempt to Align and Process the scan data based on user selections in the configuration stage. Where an Alignment is performed, the scan data is modified based on the group it is in.

With respect to alignment, the Tool will attempt to align scans depending on which option is selected:

1. None: No alignment operations will be performed.
2. Stage: Scans will be aligned on a Group by Group basis, and the result of this alignment will be combined into a single mesh.
3. Stage+: Scans will be aligned on a Group by Group basis, the results of this alignment will be combined into a single mesh, all outputs from all Groups will be aligned against a reference file provided by the user, and then aligned to each other.
4. All: Every scan present in PKS will be aligned against each other without restriction or consideration for the Groups they have been assigned to.
5. Reference: Where a reference file has been provided by a user, every scan present in PKS will be aligned against that reference without restriction or consideration for the Groups they have been assigned to.

Note that with Stage and Stage+, the original scans in each Group (whether scanned from a scanner or loaded from a directory) will be destroyed. Only an aligned and combined version of these scans will remain. For more information on preserving scan data, please refer to the Settings section.

With respect to processing, the Tool will attempt to process all scans regardless of Group and store the result in a single mesh:

1. None: No processing operations will be performed.
2. Group: All remaining meshes in the project will be grouped together.
3. Combine: All remaining meshes in the project will be combined.
4. Finalize: All remaining meshes in the project will have a Finalize operation performed on them. Please see the external PKS documentation on Finalization for more information. Note that a user’s PKS settings will impact the Finalize operation’s parameters in automation.

Where a processing operation is performed, only the output of this operation will be preserved in the PKS project. All other scan data will be destroyed.

Analyze Data¶

Where a user provides a reference file in <Base Directory>/reference and selects an option from the “Mesh Deviation” dropdown, an Analysis operation will be performed on the remaining data.

Note that the Tool will first check to determine whether the Process Data operation(s) produced a single mesh. If it does not, a mesh will be chosen from the existing data automatically.

The user may choose from the following Analysis options:

1. None: No analysis options will be performed.
2. Deviation: A deviation analysis will be performed on the reference data and outcome data generated from the Process Data operation(s).
3. Deviation+: Removes selected vertices prior to calculating the deviation analysis.

Once the Analyze operation is complete, and if the user has opted to do so in the Settings, the Tool will proceed with saving the results of the latest iteration. What data is saved here will depend on how the Tool is configured:

If Save Output is not enabled, no data will be saved regardless of any other user settings.

If Save Output is enabled:

1. A directory with the same name as the runID will be created in <Base Directory>/output directory.
2. All remaining data in the PKS Project will be saved to a PBN file using the runID as the name.
3. If a reference file has been created, the Tool will attempt to save the results of any deviation analysis that has been performed. It will save this data to a text file using the runID as the name.
4. The name of the reference mesh will be preserved by creating a text file with the same name.
5. A screenshot of the deviation analysis will be captured and saved as a PNG file using the runID as the name.
6. Where the user wishes to preserve debug data, the <Base Directory> will be replicated in <Base Directory>/output/runID/debug

   Note that the data generated here will be a copy of the <Base Directory> at the start of the Tool’s last iteration.

7. The Tool will add the log data to a master CSV file in <Base Directory>/output

Done¶

The Tool may be in this state for reasons:

1. In Directory Mode, the Tool failed to properly load scan data.
2. In Scanner Mode, the Tool failed to properly collect scan data.
3. All steps in the automation pipeline are complete.

In all of these cases, the RunResult variable will indicate the success or failure of the automation pass. The Tool will then generate a flag in the <Base Directory> to indicate it is done running its tasks, reset itself in preparation for a subsequent pass, and return to the Idle state.

Data Collection¶

The settings in this section cover how the Tool manages and stores data loaded into PKS during a single iteration of the automation pipeline.

Base Directory¶

Required: Yes
Left-click: Select the directory path via the prompt window
Right-click: Clear value

The base directory must contain a specific folder structure:

If any of these folders are absent in the base directory when the Tool moves from OFF to IDLE, it will automatically generate them. While the Tool is designed to integrate with external scripting, it is vital that any external scripts do not modify or remove these directories during an automation pass. Each directory serves a specific purpose:

1. Output: results of an automation iteration are stored here, including debug data, log files, and the output of any processing operations performed
2. Reference: If a user is seeking to analyze or process data using a reference file, it must be stored in this directory
3. Scans: Where Directory Mode is selected, the Tool will load data from this directory
4. Scripts: This feature is under active development.
5. Transforms: Any transformation matrices to be applied to scan data or group data must be stored here. See “Naming Requirements” for more information.

Input Type¶

Required: Yes
Left-click: Select the option from the dropdown menu
Right-click: N/A

The input type dictates the origin of the scan data to be processed and analyzed. If “Directory” is selected, the Tool will monitor the Base Directory for a “Ready.txt”. When the file is added to the Base Directory, the Tool will check the “Scans” directory for scan data, loading the found files into PKS and moving into the next stage.

Scans¶

Required: In Scanner Mode only
This setting is only required in Scanner Mode. It tells the Tool how many scans to take in each Group.

Stages (Groups)¶

Required: In Scanner Mode only
This setting is only required in Scanner Mode. It tells the Tool how many Groups to generate, each holding the number of scans set in Scan.

Naming Requirements¶

This is only required when using Directory Mode. Unlike Scan Mode, Directory Mode allows users to dynamically change the groups and scans included in different iterations of the Tool. For instance, the first iteration may have 10 scans and a single Group, while the tenth may have 5 Groups with 5 scans in each.

In order to facilitate this flexibility, users must follow a strict naming convention:
G<Group #>_S<Scanner #>_M<Mesh #>
The first parameter tells the Tool which Group the mesh belongs to, the Second parameter tells the Tool which Scanner the mesh originates from, and the third parameter specifies which mesh it is. So, the 7th mesh intended for Group 1, that was taken by Scanner 1, must be named “G1_S1_M7”.

Note that this naming convention is only a requirement when a user needs the flexibility of operating on scans in Groups. The Tool will still run with scan data using other names, but it will place all scans in a single Group.

TFN files store transformation matrices that are applied on a per-scan or per-Group basis. In order for these matrices to be correctly applied during an iteration of the Tool, they must follow the exact same naming convention as the meshes that they are to be applied to. For example, if our mesh from Scanner 1, G1_S1_M7, has a transformation matrix that must be applied, the TFN file must be named “G1_S1_M7.tfn” and exist in the <Base Directory>/transforms folder.

Where a transformation matrix is to be applied to an entire Group, the name of the TFN is truncated to exclude Scanner and Mesh data. The TFN for Group 1 would be “G1.tfn”. For Group 8, it would be “G8.tfn”, and so on.

Settings¶

Align Type¶

Determine which Alignment algorithm to utilize when the Tool is in the Processing State. Please see Polyga documentation on Alignment algorithms for more information.

Align¶

Determine which Alignment methodology to apply when the Tool is in the Processing State.

Processing¶

Choose which processing methodology is applied to scan data in the Processing State, after any alignment operations are performed.

Mesh Deviation¶

Choose which mesh deviation analysis methodology is applied to scan data in the Analysis State, after any alignment and processing operations are performed.

Filter¶

When this option is selected, the Tool removes isolated vertices after transformations are applied and prior to moving into the Processing State.

Save Output¶

When this option is selected, the Tool preserves the log and, if selected, debug data in the <Base Directory>/output folder.

Export Source¶

When this option and Save Output are selected, debug data is preserved for each iteration of the Tool in the <Base Directory>/output folder.

Other Behaviour¶

Bound Settings¶

With the exception of the Export Source selection, all settings will bind once set and persist between instances of PKS. The Export Source setting is for debugging purposes only. In a regular iteration of the Automation pipeline, the Tool deletes all group data held in its Singleton as well as the input scan data from the PKS Project after processing them. By selecting Export Source, this data is preserved alongside the regular Save Data log files.