Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Compute_Boolean_Shell

Functions

HC_KEY Compute_Boolean_Shell (int target_pcount, const HC_POINT *target_points, const HC_VECTOR *target_normals, int target_flist_length, const int *target_face_list, int tool_pcount, const HC_POINT *tool_points, const HC_VECTOR *tool_normals, int tool_flist_length, const int *tool_face_list, const char *options)
 Performs one of several boolean operations on two shells. IMPORTANT NOTE: This routine is primarily meant to provide a reasonable visual representation of the boolean result, and has limititions covered in the NOTES section which prevent this routine from being relied on to produce manifold shell results. The routine is provided AS-IS. More...
 
HC_KEY DCompute_Boolean_Shell (int targetpcount, const HC_DPOINT *targetpoints, const HC_VECTOR *targetnormals, int targetflist_length, const int *targetface_list, int toolpcount, const HC_DPOINT *toolpoints, const HC_VECTOR *toolnormals, int toolflist_length, const int *toolface_list, const char *options, Point const *in_color_tool, Point const *in_color_target, unsigned short const *in_vis_tool, unsigned short const *in_vis_target)
 Similar to Compute_Boolean_Shell(), but accepts and returns double-precision values. More...
 

Detailed Description

Function Documentation

HC_KEY Compute_Boolean_Shell ( int  target_pcount,
const HC_POINT target_points,
const HC_VECTOR *  target_normals,
int  target_flist_length,
const int *  target_face_list,
int  tool_pcount,
const HC_POINT tool_points,
const HC_VECTOR *  tool_normals,
int  tool_flist_length,
const int *  tool_face_list,
const char *  options 
)

Performs one of several boolean operations on two shells. IMPORTANT NOTE: This routine is primarily meant to provide a reasonable visual representation of the boolean result, and has limititions covered in the NOTES section which prevent this routine from being relied on to produce manifold shell results. The routine is provided AS-IS.

Parameters
target_pcount- Number of valid points in targetpoints.
target_points- Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the target shell. (A simple N = 3 array can also be used) Passed by reference always.
target_normals- Sequential list of vertex normals of the target shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
target_flist_length- Total number of integers in targetface_list
target_face_list- Encoded description of how to connect the points to build the faces of the target shell. Passed by reference always.
tool_pcount- Number of valid points in toolpoints.
tool_points- Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the tool shell. (A simple N = 3 array can also be used) Passed by reference always.
tool_normals- Sequential list of vertex normals of the tool shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
tool_flist_length- Total number of integers in toolface_list.
tool_face_list- Encoded description of how to connect the points to build the faces of the tool shell. Passed by reference always.
options- A quoted string or a string variable containing a list of desired options. Passed by reference always.
Returns
key

DETAILS

This function takes the definitions for two manifold shells and performs one of three boolean operations on those shells. The result is a new shell that gets inserted into the currently open segment. Valid choices for options include the following:

boolean type = [subtract | union | intersect]

Tells 3dGS which specific type of boolean operation to perform on the supplied shells. In the event of a union or an intersection, the order of target and tool does not matter. However, in the case of a subtraction the tool will be subtracted from the target shell.

plane coefficient = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. For both the single and double precision version, the default setting is "plane coefficient = 0.000001".

plane tolerance = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. The default setting is "plane tolerance = 0.0003" for the single precision version. For the double precision version, the default setting is "plane tolerance = 0.000001".

plane merge tolerance = [float]

This value is used in the internal logic for determining the boolean result. Changing the value based on the scale of the object can give better results. The default setting is "plane merge tolerance = 0.0003" for the single precision version. For the double precision version, the default setting is "plane merge tolerance = 0.000001".

target handedness = [left|right]

The polygon handedness of the target shell. If not specified, "left" handedness is assumed.

tool handedness = [left|right]

The polygon handedness of the tool shell. If not specified, "left" handedness is assumed.

RESTRICTIONS

This function will perform a Compute_Optimized_Shell() on the resulting boolean shell data before placing it in the currently open segment. The shell will have left polygon handedness. The user may need to delete the tools and target in their scene depending on the intended behavior.

The two shells that participate in the boolean operation must be closed and manifold bodies. There cannot be overlapping facets or other inconsistencies in the data. You must have consistent handedness in each input shell (though each shell can have it's own handedness, e.g., the target can have right handedness and the tool can have left handedness) and you must specify the handedness in the options if it differs from the defaults, otherwise one can get unexpected results. The input shells must only contain convex faces.

The faces of the target and tool shells should not be co-planar.

NOTES

The resulting shell of the Compute_Boolean_Shell() function may contain an excessive number of triangles in the region where the target and tool meet. If the boolean functionality is used for continuous surface removal (for example, recursive use of the boolean operation result as the input value for a subsequent boolean operation), this effect may become exacerbated.

Due to the nature of the algorithm, very small triangles may be produced which can lead to precision problems, such as missing faces or faces with wrong handedness. In extreme cases, these precision problems can lead to the creation of extraneous triangles.

See also
Insert_Shell
HC_KEY DCompute_Boolean_Shell ( int  targetpcount,
const HC_DPOINT *  targetpoints,
const HC_VECTOR *  targetnormals,
int  targetflist_length,
const int *  targetface_list,
int  toolpcount,
const HC_DPOINT *  toolpoints,
const HC_VECTOR *  toolnormals,
int  toolflist_length,
const int *  toolface_list,
const char *  options,
Point const *  in_color_tool,
Point const *  in_color_target,
unsigned short const *  in_vis_tool,
unsigned short const *  in_vis_target 
)

Similar to Compute_Boolean_Shell(), but accepts and returns double-precision values.

Parameters
targetpcount- Number of valid points in targetpoints.
targetpoints- Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the target shell. (A simple N = 3 array can also be used) Passed by reference always.
targetnormals- Sequential list of vertex normals of the target shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
targetflist_length- Total number of integers in targetface_list
targetface_list- Encoded description of how to connect the points to build the faces of the target shell. Passed by reference always.
toolpcount- Number of valid points in toolpoints.
toolpoints- Vector of x-y-z triplets for the coordinates of the vertices that could be used to build the tool shell. (A simple N = 3 array can also be used) Passed by reference always.
toolnormals- Sequential list of vertex normals of the tool shell, x-y-z triplets. It is legal to pass NULL for this parameter, in which case normal information will be ignored. Passed by reference always.
toolflist_length- Total number of integers in toolface_list.
toolface_list- Encoded description of how to connect the points to build the faces of the tool shell. Passed by reference always.
options- A quoted string or a string variable containing a list of desired options. Passed by reference always.
in_color_tool- The color of the tool as described in Set_Color().
in_color_target- The color of the target as described in Set_Color().
in_vis_tool- The visibility of the tool. Pass 0 for no visibility or any number greater than 0 to enable visibility.
in_vis_target- The visibility of the target. Pass 0 for no visibility or any number greater than 0 to enable visibility.
Returns
key

DETAILS

No additional details. See Compute_Boolean_Shell().