Automation

From KScan3D

Jump to: navigation, search

Contents

Overview

You can automate certain features in KScan3D by using scripts. You write scripts in the Lua scripting language. Lua allows for feature-rich scripting, including more advanced features such as loops and custom functions. You can control scanning, alignment, and mesh processing using scripts.

Running an Individual Command

Running an individual command is an easy way to quickly test a command without saving a new script.

  1. Type the script commands into the textbox at the bottom of the screen.
  2. Click Run Command or press ENTER to execute the command.

Creating a New Script

  1. Click New to open the Please enter a script name dialog box.
    Scriptdb.jpg
  2. Type a name for your script. This will be the script file name.
  3. Click OK to open the Browse For Folder dialog box.
    SaveExportFolder.JPG
  4. Navigate to a location to store the script or click Make New Folder to create a new one.
    Note: If this is your first time creating a script, we recommend that you create a new folder called "Scripts" somewhere on your hard drive.
  5. Click OK. A text editor opens where you can write and save your new script.

Editing an Existing Script

  1. Click the drop-down arrow next to the Edit button.
    EditScript.jpg
  2. Click a script from the recently-used scripts list or click Browse to select another file.
  3. Click Edit to open a text editor for the selected script. If you click Edit again, the same selected script opens.

Running a Script

  1. Click the drop-down arrow next to the Run button.
    Runscript.jpg
  2. Click a script from the recently-used scripts list or click Browse to select another file.
  3. Click Run to run the selected script. If you click Run again, the same selected script runs. This is helpful for frequently used tasks.
  4. Check the Script Output window for logged output results.

Note: You can also run scripts from a command line. Refer to the script command-line argument for more information.

Lua Basics

This section will cover the basics of scripting with Lua and KScan3D. It is not meant to be a comprehensive guide. For more in-depth information, refer to the Lua reference manual here: Lua Language Reference

Debugging

To check the value of a variable, use the PrintValue() function.

a = 4
PrintValue( a )

That would display PrintValue(variable="4") in the log window. Note that some variables cannot be displayed, such as lists. To display the contents of a list, loop through and print the values by their index in the list (PrintValue(myList[2])).

Comments

To add a comment line into the script, place "--" as the first non-whitespace characters on a line.

-- this is a comment

Variables

Variables in Lua can be defined without needing to specify the type - Lua will automatically set the variable to the correct type as needed.

Global

The default scope in Lua is global. These variables are persistent, so setting a variable in one script will allow that variable to be accessed in another script.

a = true
a = 9.37

Local

For variables which will only be used within the context of the current script, the local keyword can be specified.

local a = true
local a = 9.37

Conditionals/Booleans

To check if a statement is true or false, we can use conditional statements. Keywords include if, then, else, elseif, and not.

a = 4 * 6
if a < 20 then
   PrintValue("a is smaller than 20")
else
   PrintValue("a is larger than 20")
end
a = false
if not a then
   PrintValue("a is false")
end

Loops

for

Runs for a specific number of iterations in the format "for i=startIndex,endIndex,increment". If the increment is absent, it is presumed to be 1.

for i=1,10,1 do
   PrintValue( i )
end

while

Runs until a condition is no longer true.

count = 10
while count > 0 do
   PrintValue( i )
   count = count - 1
end

nil

Some functions will return nil - this is a null value, and usually indicates that the function failed.

Strings

Text and other variables can be concatenated using ".." characters.

timeString = "The time taken was: "
totalTime = 937
PrintValue( timeString .. totalTime .. " milliseconds" )

Lists

Several functions return lists. These lists are based on the .NET System.Collections.Generic.List<string>, and can be accessed as such.

groupList = GetAllGroups()
PrintValue( "There are " .. groupList.Count .. " scans in the current project." )

New lists can be created from scratch using the NewListString() function. Here is an example using Add() (to add a single string) and AddRange() (to add a list of strings).

myList = NewListString()
myList:Add( "Item 1" )
myList:Add( "Item 2" )
newList = NewListString()
newList.AddRange( myList )
PrintValue( newList.Count )
-- displays: PrintValue(variable="2")

Examples

You can copy the following examples into a blank .script file.


This very basic script is all you need to scan.

Scan()

Often, you will want to create a new project before each scan session. To ensure a unique name, you can use the built-in Lua date and time functions from the "os" module. The result is also checked to make sure the project was created.

-- creates a project in the format "2012-03-23[1332532193]"
result = NewProject(os.date("%Y-%m-%d") .. "[" .. os.time() .. "]" )
if not result then
   PrintValue( "The project was not created successfully." )
   return
end


Here's a more advanced example of running several capture-only scans with a pause in between to allow a user time to change the position of the object before the next scan - useful if a rotary is not available. Afterwards, the script loops through all of the scan groups to process the data and create a mesh. The built-in "os.clock()" function is also used to track the amount of time it took to complete the script.

-- start the timer
startTime = os.clock()
-- enable capture-only mode
Set("Scanning_Generation_Type", 2)
-- capture 10 scans and add them to a list
groupList = NewListString()
for i=1,10 do
   result, newGroups = Scan()
   -- check to make sure the scan went OK - if not, we stop the script execution
   if not result then
      -- show a custom error message
      PrintValue( "Scan #" .. i .. " failed." )
      return
   end
   -- add the new groups to the list (usually there will only be one, but there could be more for multi-scanner setups)
   groupList:AddRange( newGroups )
   -- pause for 7 seconds to allow the object to be moved/rotated
   Wait(7)
end
-- get the final count of groups
groupCount = groupList.Count
-- loop through and process the new scan groups into meshes - note that list indexing starts at 0
for i=0,groupCount-1 do
   result = Process( groupList[i], 0 )
   -- check the result
   if not result then
      PrintValue( "Failed to process group: " .. groupList[i] );
      return
   end
end
totalTime = os.clock() - startTime
PrintValue( "Script completed successfully. Time taken: " .. totalTime .. " seconds" )

Functions

Calibrating


CloseCalibration()

Closes the current calibration.


DeleteCalibration(name)

Deletes a calibration by name.

Parameters
nameThe name of the calibration.
Example
DeleteCalibration("My Calibration")
Returns
true if successful, false if unsuccessful.

DeleteCalibrationPath(dir)

Deletes a calibration by complete path.

Parameters
dirThe full path to the calibration.
Example
DeleteCalibrationPath("C:\Users\User\Documents\KScan3D\Calibrations\My Calibration")
Returns
true if successful, false if unsuccessful.

GetScannerIndexFromName(scannerName)

Gets the internal scanner index based on its name.

Parameters
scannerNameThe name of a scanner in the calibration.
Example
GetScannerIndexFromName("Scanner-001")
Returns
The index of the scanner in the current calibration, or -1 if it does not exist.

GetScannerNameFromIndex(scannerIndex)

Gets the name of the scanner based on its internal index in the current calibration.

Parameters
scannerIndexA zero-based index into the list of scanners.
Example
GetScannerNameFromIndex(0)
Returns
The scanner name if successful, nil if unsuccessful.

LoadCalibration(name)

Loads a calibration by name.

Parameters
nameThe name of the calibration.
Example
LoadCalibration("My Calibration")
Returns
true if successful, false if unsuccessful.

LoadCalibrationPath(dir)

Loads a calibration by complete path.

Parameters
dirThe full path to the calibration.
Example
LoadCalibrationPath("C:\Users\User\Documents\KScan3D\Calibrations\My Calibration")
Returns
true if successful, false if unsuccessful.

Reconnect()

Reconnects to the scanner(s).


Cameras


GetCameraNameFromIndex(cameraID, scannerName)

Gets the name of the camera based on its position in the scanner.

Parameters
cameraIDCamera index to get the name from. 0 for left, 1 for right, 2 for texture camera.
scannerNameThe name of the scanner to retrieve the camera name from.
Example
GetCameraNameFromIndex(0, Scanner_01)
Returns
The camera name if successful, nil if unsuccessful.

General


Get(settingName)

Gets an application setting value by name.

Parameters
settingNameAn application setting name.
Example
Get("Calibrating_MinCalibrationImages")
Returns
The value of the setting as text if successful, nil if unsuccessful.

NewListString()

Utility function to allow for the creation of lists compatible with other KScan3D script functions. Items (such as scan group IDs) can be added to the list using myListName:Add("Scan01").

Returns
An empty list.

PrintValue(variable)

Displays the current variable value in the log. Useful for debugging purposes.

Parameters
variableAny variable returned from a script function.
Example
PrintValue(groupID)

Run(fileName, arguments)

Launches an external application and waits until it closes.

Parameters
fileNameThe complete path to an application.
argumentsAny arguments to the application.
Example
Run("C:\Windows\notepad.exe", "C:\My Scripts\My Scan.script")
Returns
true if successful, false if unsuccessful.

Set(name, value)

Sets an application setting value by name.

Parameters
nameAn application setting name.
valueAn application setting value, as text.
Example
Set("Calibrating_MinCalibrationImages", "10")
Returns
true if successful, false if unsuccessful.

Wait(seconds)

Pauses the script for a specified delay.

Parameters
secondsThe delay time (in seconds).
Example
Wait(1.33)

Groups


Copy(groupID, suffix)

Makes a copy of a scan group.

Parameters
groupIDA scan group ID.
suffixA suffix to append to the new group ID.
Example
Copy("1", "copy")
Returns
true if successful, false if unsuccessful, as well as the new group ID.

DeleteAllGroups()

Deletes all scan groups in the current project.


DeleteGroup(groupName)

Deletes a scan group.

Parameters
groupNameThe name of a scan group.
Example
DeleteGroup("Scan01")

DeleteSelectedGroups()

Deletes all selected scan groups in the current project.


DeselectAll()

Deselects all scan group.


DeselectGroup(groupID)

Deselects a scan group.

Parameters
groupIDA scan group ID.
Example
DeselectGroup("1")

GetAllGroups()

Gets a list of all scan groups in the current project.

Returns
A list of all scan groups.

GetGroupAliasFromID(gid)

Gets the group alias its corresponding ID.

Parameters
gidA group ID.
Example
GetGroupAliasFromID("1")
Returns
The group alias if found, nil if not found.

GetGroupIDFromAlias(alias)

Gets the group ID its corresponding alias.

Parameters
aliasA group alias.
Example
GetGroupIDFromAlias("Side Scan 1")
Returns
The group ID if found, nil if not found.

GetSelectedGroups()

Gets a list of selected scan groups.

Returns
A list of selected scan groups.

LoadGroup(groupID)

Loads a scan group.

Parameters
groupIDA scan group ID.
Example
LoadGroup("1")
Returns
true if successful, false if unsuccessful.

LoadSelected()

Loads all selected scan groups.

Returns
true if successful, false if unsuccessful.

LockGroup(groupID)

Locks a scan group.

Parameters
groupIDA scan group ID.
Example
LockGroup("1")

SaveGroup(groupID)

Saves a scan group.

Parameters
groupIDA scan group ID.
Example
SaveGroup("1")
Returns
true if successful, false if unsuccessful.

SaveGroups(groupIDs)

Saves a list of scan groups.

Parameters
groupIDsA list of scan group IDs.
Example
SaveGroups({ "1", "2", "3", "4" })
Returns
true if successful, false if unsuccessful.

SelectGroup(groupID)

Selects a scan group.

Parameters
groupIDA scan group ID.
Example
SelectGroup("1")

SetGroupAlias(groupID, alias)

Sets the alias of a group.

Parameters
groupIDA scan group ID.
aliasThe new group alias.
Example
SetGroupAlias("1", "Side Scan 1")
Returns
true if successful, false if unsuccessful.

UnloadAll()

Unloads all scan groups.


UnloadGroup(groupID)

Unloads a scan group.

Parameters
groupIDA scan group ID.
Example
UnloadGroup("1")

UnloadSelected()

Unloads all selected scan groups.


UnlockGroup(groupID)

Unlocks a scan group.

Parameters
groupIDA scan group ID.
Example
UnlockGroup("1")

Processing


Align()

Aligns one or more unlocked meshes to any locked meshes. Meshes must be loaded. Note that the alignment method used is based on the Processing_Alignment_Type setting.

Returns
true if successful, false if unsuccessful.

Combine(groups)

Combines multiple groups of one or more meshes into a single group.

Parameters
groupsa list of one or more scan group IDs
Example
Combine({ "1", "2", "3", "4" })
Returns
true if successful, false if unsuccessful, as well as the combined group ID.

Decimate(groupList)

Applies mesh decimation to all selected scan groups. The decimated resolution is defined by the Processing_MeshDecimationResolution application setting, where 25.0 results in approximately 25% of the original number of vertices, and 100.0 = 100% of the original (no decimation).

Returns
true if successful, false if unsuccessful.

ErodeSelected()

Applies mesh erosion to all selected scan groups. The number of erosion passes is defined by the Processing_Erosion application setting.

Returns
true if successful, false if unsuccessful.

Export(outputDir, ext)

Exports all loaded groups except for combined groups.

Parameters
outputDirThe complete path to an existing output directory.
extThe exported file type/extension. Can be ".3d3", ".asc", ".obj", ".ply", ".stl", ".png", or ".dep". Note that when using a texture camera, OBJ, PLY, and 3D3 types will also export the texture images, and in the case of OBJ, accompanying ".mtl" files.
Example
Export("C:\Exported Meshes\", ".obj")
Returns
A list of complete paths to the exported meshes. Any mesh which failed to export will result in a blank entry ("").

Finalize(groups)

For each group, creates a unified mesh based on one or more combined meshes. This is affected by the Processing_Merging_Type setting: if it is 0, then the existing data is used as-is; if it is 1, then the data is resampled based on Poisson surface reconstruction. Also note that if the Processing_Finalize_RemoveSourceData setting is false, a new scan group will be created for each group ID.

Parameters
groupsa list of one or more scan group IDs
Example
Finalize({ "1", "2", "3", "4" })
Returns
true if successful, false if unsuccessful, as well as a list of one or more output group IDs.

FineAlign(groups, type)

Runs a thorough global alignment. Note that the meshes must already be loaded.

Parameters
groupsa list of one or more scan group IDs
typeAlignment type. Must be 3.
Example
FineAlign({ "1", "2", "3", "4" }, 3)
Returns
true if successful, false if unsuccessful.

Import(fileName)

Imports a mesh.

Parameters
fileNameThe complete path to a mesh file. Acceptable formats are 3D3, OBJ, and STL.
Example
Import("C:\Models\Car.obj")
Returns
The new group ID if successful, nil if unsuccessful.

Process(gid, generateType)

Generates 3D data from 2D scan images.

Parameters
gidthe scan group ID
generateType0 for Mesh, 1 for Points
Example
Process("16", 0)
Returns
true if successful, false if unsuccessful.

ProcessGroups(groups, generateType)

Generates 3D data from 2D scan images.

Parameters
groupsa list of one or more scan group IDs
generateType0 for Mesh, 1 for Points
Example
ProcessGroups({ "1", "2", "3", "4" }, 0)
Returns
true if successful, false if unsuccessful.

ReprojectColoursToTexture(groupID, txtWidth, txtHeight)

Create a UV-mapped texture based on existing colour data.

Parameters
groupIDScan to operate on.
txtWidthWidth of the generated texture.
txtHeightHeight of the generated texture.
Example
ReprojectColoursToTexture("1", 1024, 1024)
Returns
true if successful, false if unsuccessful.

SmoothSelected()

Applies mesh smoothing to all selected scan groups. The number of smoothing passes is defined by the Processing_Smoothing application setting.

Returns
true if successful, false if unsuccessful.

UnCombine(groupID)

Splits a combined group into its component groups. The output groups only contain a single mesh each.

Parameters
groupIDa combined group ID
Example
UnCombine({ "1", "2", "3", "4" })
Returns
true if successful, false if unsuccessful, as well as a list of one or more output group IDs.

Projects


CloseProject()

Closes the current project.

Returns
true if successful, false if unsuccessful.

DeleteProject(name)

Deletes a project by name.

Parameters
nameA project name.
Example
DeleteProject("My Project")
Returns
true if successful, false if unsuccessful.

DeleteProjectPath(dir)

Deletes a project by complete path.

Parameters
dirA project directory.
Example
DeleteProjectPath("C:\Users\User\Documents\KScan3D\Projects\My Project\")
Returns
true if successful, false if unsuccessful.

LoadProject(name)

Loads a project by name.

Parameters
nameA project name.
Example
LoadProject("My Project")
Returns
true if successful, false if unsuccessful.

LoadProjectPath(dir)

Loads a project by complete path.

Parameters
dirA project directory.
Example
LoadProjectPath("C:\Users\User\Documents\KScan3D\Projects\My Project\")
Returns
true if successful, false if unsuccessful.

NewProject(name)

Creates a new project by name.

Parameters
nameA project name.
Example
NewProject("My Project")
Returns
true if successful, false if unsuccessful.

NewProjectPath(dir)

Creates a new project by complete path.

Parameters
dirA project directory.
Example
NewProjectPath("C:\Users\User\Documents\KScan3D\Projects\My Project\")
Returns
true if successful, false if unsuccessful.

SaveProject()

Saves the current project.

Returns
true if successful, false if unsuccessful.

Scanners


GetScannerType(scannerName)

Gets the current scanner type.

Parameters
scannerNameThe name of the scanner.
Example
GetScannerType(Scanner 1)
Returns
The type of the scanner as text if successful, nil if unsuccessful.

ScannerGet(scannerName, settingName)

Gets a scanner setting value by name.

Parameters
scannerNameThe name of the scanner.
settingNameA scanner setting name.
Example
ScannerGet(Scanner 1, "ForceInfraredEmitterOff")
Returns
The value of the setting as text if successful, nil if unsuccessful.

ScannerSet(scannerName, name, value)

Sets a scanner setting value by name.

Parameters
scannerNameThe name of the scanner.
nameA scanner setting name.
valueA scanner setting value, as text.
Example
ScannerSet(Scanner 1, "ForceInfraredEmitterOff", "True")
Returns
true if successful, false if unsuccessful.

UpdateScanner(scannerName)

Updates a single scanner.

Parameters
scannerNameA scanner name.
Example
UpdateScanner(Scanner 1)
Returns
True if successful, False if unsuccessful.

UpdateScanners(scannerNames)

Updates a list of scanners.

Parameters
scannerNamesA list of scanner names.
Example
UpdateScanners({"Scanner 1", "Scanner 2"})
Returns
True if successful, False if unsuccessful.

Scanning


Scan()

Scans into the project using the scanner(s) defined in the current calibration. Note that the Scanning_Generation_Type setting will affect whether the resulting scan is automatically processed or not, and if so, whether to generate a complete mesh or just a point cloud.

Returns
true if successful, false if unsuccessful, as well as a list of one or more output group IDs.

ScannerConnect()

Ensures that all scanners in the current calibration are connected and working properly.

Returns
true if successful, false if unsuccessful.


NEXT: KScan3D Driver Switcher



Site Map

APIAbout KScan3DAligning Data
AutomationCombining MeshesCopyright Notice
Creating A Multi-Sensor Setup For Full Body ScanningEditing DataEnd User License Agreement
Exporting DataFAQFinalizing a Mesh
First StepsHardware RequirementsInstallation
KScan3D Driver SwitcherMain PageRelease Notes
Scanning BasicsScanning an ObjectThe Devices Interface
The Project InterfaceThe Settings InterfaceTroubleshooting
Tutorial VideosUsing Multiple Sensors
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox