VERICUT Development Tools

VERICUT Development Tools

OptiPath API
Introduction
OptiPath API is designed to enable an interface between VERICUT and customized plugin toolpath optimization programs. OptiPath API is only available on Windows platform.
When a system environment variable "CGTECH_OPAPI" is defined with a user's
optimization library name, VERICUT will automatically run OptiPath in API mode and
connect to user's program. VERICUT's own OptiPath function will no longer be
available.

How to build a plug-in library

The plug-in format used by VERICUT is a "WIN32 Dynamic Linked Library" which can
be built using MSVC. The following files/libraries are needed:
opapi.h, optimport.h, opapi.lib, opapi.dll
and a sample C file called "opapi_template.c"
The easiest way to build such a plug-in dll , for example, "opapi_usr.dll", is to start with
creating a C/C++ file, like "opapi_usr.c", with the skeleton code in "opapi_template.c".
There is one setup function must be present with exactly the declaration style and name
provided below:
void opapi_setup(void); where optimization callback functions must be registered
inside this setup function.
The following functions can be used to register these callbacks in setup:
void opapi_set_initialize_function(OPAPI_InitializeFunction);
void opapi_set_optimize_function(OPAPI_OptimizeFunction);
void opapi_set_terminate_function(OPAPI_TerminateFunction);
void opapi_set_tool_change_setup_function(OPAI_ToolSetupFunction);
void opapi_set_user_data(void *);
In addition, there are 22 optional utility functions that provide user program with detailed
process data. All the functions are described in Function Definition section at the end of
this document. Examples can be found in "opapi_template.c".
void opapi_free(char *);
double opapi_get_axial_depth(void);

VERICUT Development Tools

double opapi_get_chip_thickness(void);
void opapi_get_contact_area(int *, double *);
int opapi_get_conventional_cut_flag(void);
void opapi_get_current_tool(char **, int *, sOPAPI_APT_CUTTER *);
void opapi_get_cut_tool_position(double[6], double[6]);
void opapi_get_cut_machine_position(double[12], double[12]);
void opapi_get_decompressed_map_data(sOPAPI_MAP, int *, char **);
void opapi_get_grid_map(sOPAPI_MAP *);
void opapi_get_motion_type(eOPAPI_MOTION_TYPE *, double[6]);
void opapi_get_radial_width(void);
double opapi_get_program_feedrate(void);
double opapi_get_program_spindle_speed(void);
int opapi_get_side_cut_flag(void);
double opapi_get_spindle_speed(void);
int opapi_get_thin_cut_flag(void);
void opapi_get_toolpath_record(int *, char **);
double opapi_get_total_distance(void);
double opapi_get_total_time(void);
double opapi_get_total_volume_removed(void);
char *opapi_get_variable_value(char *);
double opapi_get_volume_removed(void);
void opapi_send_message(char *, int);
void opapi_set_resolution(double);
void opapi_set_override_rpm(double);
void opapi_write_out_comment_line(char *);
Include "opapi.h" and "optimport.h" in "opapi_usr.c". Compile and link all the usr files
with "opapi.lib". This will generate a ".dll" library.
Set system environment variable "CGTECH_OPAPI" set to where this dll is , for
example, "c:\opapi\opapi_usr.dll" and place "opapi.dll" in the same directory where
"CGTech.dll" is. OptiPath API mode is now ready to go.

VERICUT Development Tools

Function Definition
void opapi_setup(void)
Setup function. Must be present with exactly the same declaration style and name. Called
when OptiPath API library is first loaded. It is to register user's optimization function.
The following functions can be and should only be called in this setup function:
opapi_set_initialize_function(OPAPI_InitializeFunction);
opapi_set_tool_change_setup_function(OPAI_ToolSetupFunction);
opapi_set_optimize_function(OPAPI_OptimizeFunction);
opapi_set_terminate_function(OPAPI_TerminateFunction);
opapi_set_user_data(void *);
void opapi_set_initialize_function(OPAPI_InitializeFunction func_p)
Register user's initialization function with VERICUT. The initialization function
registered, func_p, should have the following declaration style:
typedef int (*OPAPI_InitializeFunction)(void *userData);
which returns 1 if initialization is successful or 0 if initialization failed. If failed, OptiPath
will be turned off. This function should only be called in opapi_setup() function. Once
registered, the initialization function, func_p, will be called each time the user turn
OptiPath on.
void opapi_set_tool_change_setup_function(OPAPI_ToolSetupFunction func_p)
Register user's tool change setup function with VERICUT. The tool change function
registered, func_p, should have the following declaration style:
typedef int (*OPAPI_ToolSetupFunction)(void *userData);
which returns 1 if tool setup is successful or 0 if tool setup failed. If failed, no
optimization will occur for the current tool. Therefore, if a tool does not need to be
optimized, just return 0 when func_p is called for this tool. This function should only be
called in opapi_setup() function. Once registered, the tool setup function, func_p, will be
called each time a tool change occurs.
void opapi_set_optimize_function(OPAPI_OptimizeFunction func_p)
Register user's optimization function with VERICUT. The optimization function
registered, func_p, should have the following declaration style:
typedef void (*OPAPI_OptimizeFunction)(void *userData);

VERICUT Development Tools

This function should only be called in opapi_setup() function. Once registered, the
optimization function, func_p, will be called in a frequency defined by user (see
opapi_set_resolution(double)) during cutting process.
void opapi_set_terminate_function(OPAPI_TerminateFunction func_p)
Register user's terminate function with VERICUT. The termination function registered,
func_p, should have the following declaration style:
typedef void (*OPAPI_TerminateFunction)(void *userData);
This function should only be called in opapi_setup() function. Once registered, the
termination function, func_p, will be called each time OptiPath is turned off.
void opapi_set_user_data(void *usr_data)
Set user data that needs to be passed among optimization functions
OPAPI_InitializeFunction, OPAPI_ToolSetupFunction, OPAPI_OptimizeFunction,
OPAPI_TerminateFunction. This function should only be called in opapi_setup()
function.
void opapi_set_resolution(double distance)
Set optimization resolution distance. Optimization resolution distance controls the
frequency or "sampling distance" used to analyze each tool path motion. Each feed rate
controlled motion is partitioned into samples and OPAPI_OptimizeFunction is called
based on this distance. Distance is measured along the tool motion. This function should
only be called in the OPAPI_InitializeFunction.
If the user program does not set up a resolution by calling this function in initialization, a
default resolution distance based on the size of the cutting tool relative to the displayed
model is calculated by VERICUT. This choice is recommended when little or no
knowledge of cutting methods or feed rates is available.
Parameters:
distance: Input, optimization distance.
void opapi_set_override_rpm(double rpm)
Set override spindle speed in rpm. This function should only be called in
OPAPI_ToolSetupFunction, which sets up a new spindle speed for the tool just loaded.
Parameters:
rpm: Input, spindle speed in rpm.

VERICUT Development Tools

void opapi_get_current_tool(char **tool_id, int *is_apt, OPAPI_APT_CUTTER
*apt_cutter)
Get the current tool information. This function can be called in
OPAPI_ToolSetupFunction, to retrieve information about the current loaded tool.
Parameters:
tool_id: Output, tool id of current tool as defined in tool library. Will be null if an apt tool
is defined by cutter statement.
is_apt : Output, 1 if an apt cutter, 0 if not. apt_cutter: Output, cutter definition stored in
sOPAPI_CUTTER if current tool is an apt cutter.
void opapi_get_toolpath_record(int *rec_num, char **record)
Get the current toolpath record.
Parameters:
rec_num: Output, current record number(line number) in toolpath file.
record: Output, current toolpath record being processed.
void opapi_get_cut_tool_position(double start[6], double end[6])
Get tool positions at the starting and ending points of current motion in stock component
coordinate system.
Parameters:
start: Output, tool starting position, defined by tool tip position [0-2] in (X, Y, Z) and tool
axis vector [3-5] in (I, J, K).
end: Output, tool ending position, defined by tool tip position [0-2] in (X, Y, Z) and tool
axis vector [3-5] in (I, J, K).
void opapi_get_cut_machine_position(double start[12], double end[12])
Get machine positions at the starting and ending points of current motion.
Parameters:
start: Output, machine starting position in (X, Y, Z, U, V, W, A, B, C, A2, B2, C2)
end: Output, machine ending position in (X, Y, Z, U, V, W, A, B, C, A2, B2, C2)
void opapi_get_motion_type(eOPAPI_MOTION_TYPE *type, double circle[6])

VERICUT Development Tools

Get current motion type.
Parameters:
type : Output, motion type defined in eOPAPI_MOTION_TYPE
circle: Output, circle defined by circle center [0-2] in (X, Y, Z) and circle normal [3-5] in
(I, J, K) for circular motion.
void opapi_get_contact_area(int *contact, double *area)
Get the area that tool is in contact with material
Parameters:
contact: Output, 1 if tool is in contact with material, 0 if not.
area : Output, area of material that is in contact with the tool.
void opapi_get_grid_map(sOPAPI_MAP * map)
Get detailed tool-material immersion data.
Parameters:
map: Output, returned map->gridMask field must be freed by using opapi_free(char *).
VERICUT provides kinematics of cutter immersion data in the form of a grid map, a
mapping of what parts of the workpiece are in contact with the cuter and stores it in the
sOPAPI_MAP structure. The grid map is a projection plane (gridAxisX & gridAxisY)
that is normal to cutter transition vector (gridAxisZ). Each grid has a bit value of 1 or 0,
with 1 meaning the projected part on the workpiece is in contact with the cutter and 0
meaning no contact. All the grid bits are stored row by row, starting from bottom to top,
left to right, into (a) 32-bits integer(s).
void opapi_get_decompressed_map_data(sOPAPI_MAP *map, int *size, char **values)
Transform immersion data to the form of an array of integers, decompressed by
gridMask. Each array element has a value of 0 or 1. For example, values[numX] = 0
means on the [numX]th grid (row = 1, column = 0), the cutter has no contact with
material.
Parameters:
map: Input, a map structure that contains grid mask data.
size: Output, size of the unsigned array.
values: Output, pointer to the bit array. Must be freed by using opapi_free(char *).

VERICUT Development Tools

void opapi_free(char *data)
Free memory.
Parameters:
data: Input, memory pointer.
void opapi_send_message(char *message, int display)
Send a message to VERICUT.
Parameters:
message: Input, message to be sent
display: Input, 0 written to log file; 1 displayed in logger; 2 display in logger and written
to log file.
void opapi_write_out_comment_line(char *comments)
Write out a comment line in the optimized toolpath file. Only valid in G-code toolpath
file.
Parameters:
comments: Input, comment line to write out. Must be a complete line, including starting
comment character and end of line return character.

double opapi_get_radial_width(void)
Return maximum radial width.
double opapi_get_axial_depth(void)
Return maximum axial depth.
double opapi_get_chip_thickness(void)
Return chip thickness.

double opapi_get_volume_removed(void)
Return volume of material being removed by current motion.

VERICUT Development Tools

double opapi_get_program_feedrate(void)
Return programmed feedrate.
double opapi_get_program_spindle_speed(void)
Return program spindle speed in rpm.
double opapi_get_spindle_speed(void)
Return spindle speed in rpm.
double opapi_get_total_time(void)
Return total time.
double opapi_get_total_distance(void)
Return total distance.
double opapi_get_total_volume_removed(void)
Return total volume of material being removed.
int opapi_get_conventional_cut_flag(void)
Return conventional cut flag.
int opapi_get_side_cut_flag(void)
Return side cut flag.
int opapi_get_thin_cut_flag(void)
Return thin cut flag.
char * opapi_get_variable_value(char * variable_name)
Return a variable value. Only valid for G-code toolpath file.
Parameters:
variable_name: Input, name of the variable.
8

VERICUT Development Tools

Return the address of variable value depending the variable type.
If variable is a number, return the address of the double value (double *).
If variable is a text, return the address of the string (char *)
typedef struct s_OPAPI_CUTTER
{
double cutterDiameter; /* Cutter diameter, D */
double cutterHeight; /* Cutter height, H */
double cornerRadius; /* Corner radius, R */
double eDistance; /* Distance from tool centerline to corner radius center, E */
double fDistance; /* Distance from tool tip to corner radius center, F */
double baseAngle; /* Base angle, A */
double sideAngle; /* Side angle, B */
} sOPAPI_CUTTER;

typedef struct s_OPAPI_MAP

{
double toolEnd[2]; /* Tool tip at starting position projected to the projection grids, in
gridAxisX, gridAxisY */
double gridOrigin[3]; /* Origin of projection grids in X, Y, Z */
double gridAxisX[3]; /* Projection grids' X axis in I, J, K. X axis in normal to the Z axis
and tool axis in starting position */
double gridAxisY[3]; /* Projection grids' Y axis in I, J, K */
double gridAxisZ[3]; /* Projection grids' Z axis in I, J, K. Z axis is the unit vector of
cutter translation position vector */
double gridSize; /* Length of each grid */
int numGridsX; /* Number of grids along gridAxisX */
9

VERICUT Development Tools

int numGridsY; /* Number of grids along gridAxisY */
int maskSize; /* Number of int/32 bits that are used to store the mask */
int *gridMask; /* Pointer to grid mask */
} sOPAPI_MAP;
typedef enum e_OPAPI_MOTION_TYPE
{
OPAPI_LINEAR = 0,
OPAPI_CIRCLE = 1,
OPAPI_NURBS = 2,
OPAPI_RAPID = 3,
}eOPAPI_MOTION_TYPE;

10

VERICUT Development Tools

API Interface for Heidenhain iTNC Controller

This document describes the VERICUT 6.1 requirements for the Heidenhain iTNC API.
The API functions in this document are the minimum frame work needed for VERICUT
and the Heidenhain iTNC Controller to perform a successful simulation. The API
functions may and will be modified to take advantage of new and existing capabilities of
the Heidenhain iTNC Controller and new API functions will be implemented as needed.
The API functions must be implemented and exportable via the TNC DLL.
The API functions will isolate VERICUT from Heidenhain iTNC specific nuances as
much as possible. For example, TNC circle data is given as a set of intermediate points
on the circle. The TNC DLL must buffer up the intermediate points and then create the
circle data based on the buffered intermediate points. VERICUT does not want the
intermediate points. VERICUT wants just the resultant circle motion.
A new NC program type has been added to VERICUT 6.1. The new type is located in the
NC Program window:
Project menu > NC Programs
NC Program Type = Heidenhain iTNC
Set the following environment variable so that VERICUT will find the new TNC DLL:
set CGTECH_TNCAPI_NEW="path to TNC dll"
The API function, ctlapi_get_next_record_TNC(), uses the structure sCTL_MOTION
found in "ctlapi.h"
The log file debug feature can be turned On/Off using the Debug Control API option on
the Process Options window: Debug tab (Project > Processing Options > G-Code >
Process Options).
The rest of this document defines the TNC API function prototypes which must be
implemented and exportable via the TNC DLL.

11

VERICUT Development Tools

/*********************************************************
This function shall initialize the COM interface, establish connection to the TNC and
initialize session variables.
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_hard_initialize_TNC(void);

/*********************************************************
This function shall perform a TNC disconnect, un-initialize the COM interface and reset
session variables.
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_hard_terminate_TNC(void);

/*********************************************************
This function shall set the main program file, set tool position, set feed rate and set
execution mode. This function will be called for initial setting of main program file, for
main program file change and at simulation reset.
(I) program, main program file

12

VERICUT Development Tools

Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_program_prepare_TNC(char *program);

/*********************************************************
This function shall start the execution of the selected main program file.
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_start_program_TNC(void);

/*********************************************************
This function shall stop execution of the main program file.
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_stop_program_TNC(void);
13

VERICUT Development Tools

/*********************************************************
This function shall get the list of motions created from one record.
(O) list, list of motions created from one record.
Returns:
number of motions (int)
**********************************************************/
int ctlapi_get_next_record_TNC(sCTL_MOTION **list);

/*********************************************************
This function shall open the tool file for write. The tool file should be located in the same
directory as the Main Program File (MPF). Extract the path from the specified MPF and
construct the tool file (path and name.)
(I) mpf, main program file
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_frame_initialize_TNC(char *mpf);

14

VERICUT Development Tools

/*********************************************************
This function shall close the tool file and send a request to the controller to load the tool
file.
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_frame_terminate_TNC(void);

/*********************************************************
This function shall write tool info to the tool file for a single tool.
(I) tool_num, tool number
(I) radius, tool radius
(I) length, tool length
Returns:
0, Error
1, OK
**********************************************************/
int ctlapi_frame_tool_TNC(int tool_num, double radius, double length);

/*********************************************************

15

VERICUT Development Tools

This function shall return the current controller simulation time.
Returns:
time (double)
**********************************************************/
double ctlapi_get_time_TNC(void);

/*********************************************************
This function shall return the program-at-end flag.
Returns:
0, not at end of program
1, at end of program
**********************************************************/
int ctlapi_get_prog_at_end_TNC(void);

/*********************************************************
This function shall set the event notify function.
The event notify function shall notify VERICUT of one of the following events:
0 = program block
1 = tool change
2 = enter subroutine
3 = leave subroutine
16

VERICUT Development Tools

4 = current program line
5 = S word
6 = F word
7 = M word
8 = current message
The event notify function prototype is:
void event_notify(int event_type, long line_number, char *event_text);
Returns:
none
**********************************************************/
void ctlapi_set_event_notify_function_TNC(void (*func)(int, long, char *));

/*********************************************************
This function shall set the client message function.
The client message function allows the controller to pass text messages to VERICUT.
The client message function prototype is:
void client_message(char *message);
(I) func, client message function.
Returns:
none

17

VERICUT Development Tools

**********************************************************/
void ctlapi_set_client_message_function_TNC(void (*func)(char *));

18