Postprocessor module

This module deals with the customization and creation of new postprocessors for VxCraft.

Postprocessor script

A postprocessor is essentially a Lua script file that contains special commands and functions to convert the toolpaths calculated by VxCraft into a suitable format for the CNC machine.

By default, the scripts are stored in the "PP" subfolder of the (see chapter "Installation") Program Data folder. New scripts can be added and managed in this folder.

Before you create or modify a postprocessor, please make sure that you save it under a unique name. Otherwise, when you update or install a new postprocessor package, your customized postprocessor could be overwritten. Please note that the prefix 'vxc_def_*' in the file name is used by VxCraft for predefined default postprocessors and therefore should not be used for your customized postprocessors.

Script sequence

The script flow in this module is different from other Lua modules because it is not linear.

The module is based on the concept of callback functions, which are provided by the user in the Lua script and called by VxCraft depending on the situation.

When a postprocessor run is executed, the script is first read and executed. Usually, only initialization tasks are performed in the script during this process. This run is necessary for VxCraft to capture the callback functions provided by the user.

Following this, VxCraft calls these callback functions as needed. For example, callJobBegin() is called at each job start and callMove(...) is used for each tool path point.

Functions

For the module, the following functions provided by VxCraft can be used and called anywhere in the script:

Function	vxPrint(...)
Description	vxPrint can be called with any number of arguments separated by commas. It converts all arguments to strings and prints them to the postprocessor environment console. The following data types are allowed: nil, number, string and boolean. Note: String literals such as %d, %s, %f, etc. are not considered by vxPrint().
Example	vxPrint("Start position: X ", pos_x, " Y ",4," Z ",50.0, "\n")

Function	vxClear()
Description	Deletes the contents of the postprocessor environment console.
Example	vxClear()

Function	vxWarn(string)
Description	Outputs the passed string as a popup warning message.
Example	vxWarn("The tool path is outside the maximum traverse path.")

Function	vxAsk(string)
Description	Outputs the passed string as a popup message that can be acknowledged with "Yes" or "No". Returns the value 1 if the message was acknowledged with "Yes".
Example	vxAsk("A collision was detected in the job. Continue?")

Function	getSetting(keystring)
Description	getSetting() returns the system setting with the passed key as a string.
Example	name = getSetting("pp_user")

Function	getSettingInt(keystring)
Description	getSettingInt() returns the system setting with the passed key as an integer.
Example	opendir = getSettingInt("pp_open_explorer")

Callback functions

The callback functions provided by the user must conform to a specific format. It is not necessary to provide all callback functions, and the order does not matter. If a function is missing, its absence is ignored and the process continues.

Return value

Each callback function must return "nil" if it runs without errors. If an error occurs, an error message can be returned in the form of a string. This aborts the postprocessor run and the message is displayed.

Callback function prototypes

The listing below provides an overview and description of all available callback functions:

function callBegin()

Called at the beginning of the postprocessor run. If only a single NC file is to be created, this function can be used to prepare this file and open it in write mode.

function callJobBegin()

Called every time a new job starts. Can be used, for example, for changing the tool and for pre-positioning.

function callMove(x,y,z,gflag,mflag)

Called for each toolpath point. This is the only callback function that receives arguments from VxCraft.

x,y,z

The coordinates of the tool path point as a floating point number.

gflag, mflag

These arguments give additional info about the tool waypoint. They are flags in integer format that can be checked with the bit operator "&" for certain states using an if query. Global variables provided by VxCraft can be used for checking. In the following a listing with possible queries:

Check	Description
if(gflag&FLAG_G0)	The tool waypoint is part of a positioning movement. The regular rapid traverse feed should be used.
if(gflag&FLAG_G1)	The tool path point is part of a regular milling movement. The regular milling feed should be used.
if(gflag&FLAG_G1_RAMP)	The tool waypoint is part of a ramped plunge movement. The plunge feed should be used.
if(gflag&FLAG_G1_PLUNGE)	The tool path point is part of a vertical plunge movement. The drill feed should be used.
if(mflag&FLAG_M_SPINDLE_START)	The spindle should be started before the tool path point is approached.

Global variables

Global variables are provided by VxCraft and can be accessed anywhere in the script. All global variables are updated before callJobBegin() is called and are valid until after callJobEnd() ends:

Project and system related variables

global variable	Description
ppDirProject	Path to the saved project file
ppFilePath	Path to the postprocessor script
ppFileBase	Postprocessor script name
ppFileExt	File extension of the postprocessor script
ppNameProject	The name of the project element
ppNameNcPack	The name of the NC-Pack object
ppNameTool	The name of the tool
ppNameJob	The name of the job object
ppVxPerUnit	Project resolution in voxels per user unit
ppUnitPerVx	Project resolution in user unit per voxel

global flags	Description
FLAG_G0	Check value for gflag (see function "callMove()")
FLAG_G1	Check value for gflag (see function "callMove()")
FLAG_G1_RAMP	Check value for gflag (see function "callMove()")
FLAG_G1_PLUNGE	Check value for gflag (see function "callMove()")
FLAG_M_SPINDLE_START	Check value for mflag (see function "callMove()")

Job related variables

Start position:

global variable	Description
ppStartposX	Position X of the first waypoint of the current job
ppStartposY	Position Y of the first waypoint of the current job
ppStartposZ	Position Z of the first waypoint of the current job

Spindle and tool:

global variable	Description
ppSpindleRotation	The spindle direction set in the job, 0 = Clockwise, 1 = Counterclockwise
ppSpindlespeed	The spindle speed set in the job
ppToolId	NC tool number of the current job
ppCooling	Cooling mode of the current job

feed rate:

global variable	Description
ppFeedMode	The feed rate mode set in the job, 0=rapid, 1=user defined feed rate.
ppFeedRapid	The user-defined feed rate intended for the rapid.
ppFeed	Feed rate for regular milling.
ppFeedRamp	Feed rate for ramped plunge movements.
ppFeedDrill	Feed rate for vertical plunge movements.

Job parameters:

global variable	Description
ppJobtype	Calculation algorithm used
ppPlaneSite	positioning plane
ppPlaneStart	Start plane (top machining plane)
ppPlaneEnd	End plane (lowest working plane)
ppPlungeDrill	Vertical plunge active/inactive
ppPlungeRamp	Ramped plunge active/inactive
ppPlungeSpiral	Spiral plunge active/inactive
ppPlungeAngle	Angle for ramp and spiral plunge
ppPlungeDia	Spiral diameter
ppSgap	Safety distance
ppAreaIn	Zone Inside active/inactive
ppAreaOut	Zone outside active/inactive
ppAreaStk	Workpiece active/inactive zone
ppRadcorr	Radius correction active/inactive
ppAe	Horizontal cutting depth
ppApMain	Vertical main infeed
ppApMicro	Vertical cutting depth of the intermediate steps
ppDrillTop	Drilling mode top
ppDrillFloor	Drilling mode floor
ppAllm_xy	Allowance model XY
ppAllm_z	Allowance model Z
ppAllf_xy	Allowance bounding XY
ppAllf_z	Aufmaß Grenzmodell Z
ppAlls_xy	Allowance stock XY
ppAlls_z	Aufmaß Werkstück Z
ppFeedDir	climb=0 / conventional=1
ppOpt	Optimization mode
ppCollision	A value other than 0 means that a collision was detected in the job.
ppPause	Status of the pause option set in the job