Execution

Once the calling program has initialized the library, set any of the desired parameters, and populated the input arrays with data it will call the main fucntion QisBool_Booleanize. This is where the actual "work" gets done.

Syntax:

int QisBool_Booleanize
 (int*** XY_arr,int** pair_num_arr, int * N,
  int** XY1_arr, int * pair_num1_arr, int N1, 
  int** XY2_arr, int * pair_num2_arr, int N2,
  int code,

Function:

this is the core boolean function call. It takes as input two sets of input geometric data (polygons stored in arrays) and produces an array of output polygons based on the operation code selected. Prior to calling QisBool_Booleanize, the caller should first set up the various parameters that "flavor" the operations. After calling QisBool_Booleanize and using the results, the caller should release the memory.

Inputs:

int** XY1_arr - an array of pointers - each element in the array points to the memory location where the coordinates for the polygon are stored. See illustration.

int * pair_num1_arr - an array where each element contains the number of vertices in that polygon.

int N1 - integer - number of polygons in this set.

int** XY2_arr - an second array of pointers - each element in this second array points to the memory location where the coordinates for the polygon are stored.

int * pair_num2_arr - an array where each element contains the number of vertices in that polygon.

int N2 - integer - number of polygons in this set.

int code - boolean operation, one of the following: UNION_OPCODE, DIFFERENCE_OPCODE,XOR_OPCODE,INTERSECTION_OPCODE

bdll_handle - the thread handle.

Output

int*** XY_arr - an array of pointers each pointing to the array element of polygon coordinates.

pair_num_arr - an array where each element is the number of vertices in the returned polygon.

Return Codes: PROVISIONAL: BE SURE TO REFER TO HEADER FILE!

Notes

Implicit Union - operations Difference, XOR and intersection all require that each of the two input sets are first unionized. This is done automatically and need not be explicitly called by the user.

In the case that there is no second operand (for example, union of a single array of polygons) then set XY2_arr, pair_num2_arr, and N2 to NULL,NULL,0 respectively.

Syntax:

int QisBool_BinaryMT
    (int**  XY_in_arr1, int* pair_num_in_arr1,  int Polys1,
     int**  XY_in_arr2, int* pair_num_in_arr2,  int Polys2,
     int*** XY_out_arr, int** pair_num_out_arr, int* Nout, 
     short index, short thrnum, short operation
    );

Function:

both this function (and QisBool_Booleanize) are thread safe - however this function is internally multi-threaded and does automatic partitioning of the data. For large datasets where the standard function would bog down (due to n² compute time) this one scales closer to linear. This function always has two operands.

Inputs:

int** XY_in_arr1 - an array of pointers for the first operand - each element in the array points to the memory location where the first coordinate of each polygon is stored.

int* pair_num_in_arr1 - an array where each element contains the number of vertex pairs for that polygon.

int Polys1 - integer - number of polygons in the first operand.

int** XY_in_arr2 - an array of pointers for the second operand - each element in the array points to the memory location of the first coordinate of each polygon in the collection.

int* pair_num_in_arr2 - an array where each element contains the number of vertices in that polygon.

int Polys2 - integer - number of polygons in the second operand.

short index - the index number (handle) returned by a prior call to QisBool_Create()

short threadnum - tells the library how many threads should be used for performing the desired operation.

short operation - geometric boolean operation, one of the following: DIFFERENCE_OPCODE, XOR_OPCODE or INTERSECTION_OPCODE

Output

int*** XY_arr - the address of an array of pointers for the output polygons.

int** pair_num_arr - address of the array containing the number of vertices for each of the returned polygons.

int* N - the address of the number of output polygons.

Return Codes: PROVISIONAL: BE SURE TO REFER TO HEADER FILE!

 0 if no errors.

-2 if the number of requested threads exceeds the maximum ( 64 ).

Notes

Implicit Union - operations Difference, XOR and intersection all require that each of the two input sets are first unionized. This is done automatically and need not be explicitly called by the user.

Syntax:

int QisBool_UnionMT
 (
  int** iXY, int* iNV, int iN, 
  int*** oXY, int** oNV, int* oN, 
  short iNThreads,
  void* iBooleanHandle
 );

Function:

Use this function to unionize a single set of polygons. By setting options, you can perform sizing, clipping and convexing on the set simultaneously.

Both this function (and QisBool_Booleanize) are thread safe - this function is internally multi-threaded and does automatic partitioning of the data. For large datasets where the standard function would bog down (due to n² compute time) this one scales closer to linear. This function has only a single operand.

Input Arguments

int**  iXY

int* iNV

int Polys

iBooleanHandle

short inThreads

Output Arguments

int*** oXY

int** oNV

int* oN

Return Codes: PROVISIONAL: BE SURE TO REFER TO HEADER FILE!

 0 if no errors.

-2 if the number of requested threads exceeds the maximum ( 64 ).

Syntax:

int QisBool_DeEmbedding
          ( int** XY1_arr, int* pair_num1_arr, int N1, 
            int*** XY_arr, int** pair_num_arr, int* N, 
            int index
          );

Function:

A special union operation which differs from standard union. The intent is to group polygons based on whether they are fully contained by a "parent" polgyon. Examples and illustrations can be found here.

Inputs:

int** XY1_arr - an array of pointers for the polygons - each element in the array points to the memory location where the first coordinate of each polygon is stored.

int* pair_num1_arr - an array where each element contains the number of vertex pairs for that polygon.

int N1 - number of polygons in the input array.

short index - a thread index obtained by calling QisBool_Create()

Output

int*** XY_arr - the address of an array of pointers for the output polygons.

int** pair_num_arr - address of the array containing the number of vertices for each of the returned polygons. A negative value for vertex count indicates that this is a child polygon.

int* N - the address of the number of output polygons.

Return Codes: PROVISIONAL: BE SURE TO REFER TO HEADER FILE!

 0 if no errors.