Selective Booleans
[Advanced Operations, Booleans]

Collaboration diagram for Selective Booleans:


Classes
class	tube_options
	Creates a data structure to facilitate generalizing selective Booleans. More...
Functions
outcome	api_boolean_tube_body (BODY blank, BODY tube, ENTITY_LIST &start_faces, ENTITY_LIST &end_faces, SPAposition start_pos, int number_of_starts, SPAposition end_pos, int number_of_ends, SPAvector start_dir, tube_options *opts, int number_of_options, ENTITY_LIST &bodies, AcisOptions ao=NULL)
	Does a selective Boolean operation on two bodies.
outcome	api_create_graph_from_cells (ENTITY_LIST &cells, generic_graph &graph, AcisOptions ao=NULL)
	Creates a graph (from cells) used in graph theory.
outcome	api_create_graph_from_edges (ENTITY_LIST &edges, generic_graph &graph, AcisOptions ao=NULL)
	Creates a graph (from edges) used in graph theory.
outcome	api_create_graph_from_faces (ENTITY_LIST &faces, generic_graph &graph, AcisOptions ao=NULL)
	Creates a graph (from faces) used in graph theory.
outcome	api_initialize_sbooleans ()
	Initializes the Selective Booleans Component library.
outcome	api_selective_boolean_stage1 (BODY blank, BODY tool, generic_graph &graph, AcisOptions ao=NULL)
	Creates a graph for the first stage of selective Booleans from a tool body and a blank body.
outcome	api_selective_boolean_stage2 (BODY non_reg_unite_body, generic_graph graph_of_cells_to_keep, AcisOptions *ao=NULL)
	Completes the selective Boolean process for the cells selected.
outcome	api_selective_boolean_stage2 (BODY non_reg_unite_body, ENTITY_LIST &cells_to_keep, AcisOptions ao=NULL)
	Completes the selective Boolean process for the cells selected.
outcome	api_selective_unite (BODY tool, BODY blank, int tnum, SPAposition tpos, int bnum=0, SPAposition bpos=NULL, AcisOptions *ao=NULL)
	Unites two bodies with the given positions.
outcome	api_subgraph_2dcell (const generic_graph whole_graph, generic_graph &partial_graph, AcisOptions *ao=NULL)
	Returns a subgraph containing only the vertices that are 2D cells.
outcome	api_subgraph_3dcell (const generic_graph whole_graph, generic_graph &partial_graph, AcisOptions *ao=NULL)
	Returns a subgraph containing only the vertices that are 3D cells.
outcome	api_subset_graph_with_plane (const generic_graph whole_graph, const SPAposition &plane_origin, const SPAunit_vector &plane_normal, generic_graph &partial_graph, AcisOptions *ao=NULL)
	Finds the subset of a graph on one side of a plane.
outcome	api_terminate_sbooleans ()
	Terminates the Selective Booleans Component library.

Function Documentation

outcome api_boolean_tube_body	(	BODY *	blank,
		BODY *	tube,
		ENTITY_LIST &	start_faces,
		ENTITY_LIST &	end_faces,
		SPAposition *	start_pos,
		int	number_of_starts,
		SPAposition *	end_pos,
		int	number_of_ends,
		SPAvector	start_dir,
		tube_options **	opts,
		int	number_of_options,
		ENTITY_LIST &	bodies,
		AcisOptions *	ao = `NULL`
	)

Does a selective Boolean operation on two bodies.

Role: The API boolean_tube_body takes two bodies (blank and tube) as input and calls the selective Booleans stage1 once and stage2 the number_of_options times. Each time these selective Booleans are called, this function automatically sets up the subgraph from a set of options and start and end conditions.

If you pass multiple options into api_boolean_tube_body, the results will be found many times faster than calling it separately for each option.

Defining the operation (bool_type) using tube_options:

There are 3 types of cells, "only from the blank", "only from the tool", and "from both".

There are 4 possible bool_types, UNITE, LIMIT, INTERSECT, and SUBTRACT:

UNITE operation deals with the cells "only from the tool", adding the specified ones to the blank. Given a variable, opts, of type tube_options, call for example: opts->set_bool_type(UNITE).
LIMIT operation is the same as UNITE except that all cells from the blank are discarded instead of kept.
INTERSECT operation deals with "cells from both". Only the specified cells are kept.
SUBTRACT operation deals with "cells from both". Start with the blank, and subtract the specified cells.

Defining Laws using tube_options:

Laws are used to specify which subset of the possible cells your operation should use. Laws are string expressions consisting of the main variable that loops over all possible cell numbers (x1), some constants (X2, X3, X4, X5, X6, and possibly more), and some operators and conditionals (=, !=, >, or, etc). For shorthand, you can use x for x1, y for x2, and z for x3.

x1 (x) = order of this cell, or the independent variable.
x2 (y) = largest order in the component cell x belongs to.
x3 (z) = TRUE if from tool.
x4 = TRUE if from blank.
x5 = TRUE if start cell.
x6 = TRUE if end cell.

Example Laws:

Imagine a vertical tube cutting through the three legs of an extruded letter 'E', where the tube also extends above the top leg and below the bottom leg. Let 'E' be the blank, and the tube be the tool. Specify the top cell to be a start cell, and the bottom cell to be the end cell, using the ordering techniques explained below. There are now 4 possible cells that could be included in the unite operation, numbered from top to bottom 0, 1, 2, and 3.

x1 iterates over the 4 cells, testing each one to see whether it should be kept. In this case, it takes on numbers 0, 1, 2, and 3.
x2 is always 3, since 3 is the biggest possible number.
x3 is always TRUE, since we are doing a unite, and only cells from the tool are considered.
x4 is always FALSE, since we are doing a unite, and no cells from the blank are considered.
x5 is TRUE if x1 is 0.
x6 is TRUE if x1 is 3.
Thus, to specify all but the last cell, use:
law* keep_law = NULL;
api_str_to_law("x!=x2",&keep_law)
opts->set_keep_law( keep_law );
keep_law->remove();
To specify all start cells, substitute the second line with:
api_str_to_law("x5",&keep_law)
To keep the second and last cells, substitute the second line with:
api_str_to_law("x=1 or x6",&keep_law)

Defining Cell Numbers, or Ordering:

To determine cell numbers, first pick start cells and end cells. This is done by picking start vertices and end vertices, or start faces and end faces, which are on the cells you want to pick. Start cells are all numbered zero. The shortest paths from start cells to end cells are automatically found. Depending on the operation type, non-relevant cells are discarded, and the rest are given an integral number based on the steps they are away from the start cell. Note that multiple cells could share the same number.

Keep Branches:

Cells that are not on any "shortest path" are considered "branch cells." You can either keep them all or discard them all with the keep_branches flag, which defaults to FALSE. To keep branch cells use: opts->set_keep_branches(TRUE).

Effect: Changes model

Journal: Available

Parameters:

	blank	blank body.
	tube	tube body.
	start_faces	start face.
	end_faces	end face.
	start_pos	array of start positions.
	number_of_starts	number of start positions.
	end_pos	array of end positions.
	number_of_ends	number of end positions.
	start_dir	start direction should be (0,0,0) if not cyclic.
	opts	options for tube.
	number_of_options	number of options.
	bodies	output bodies.
	ao	acis options.

include <sboolapi.hxx>

outcome api_create_graph_from_cells	(	ENTITY_LIST &	cells,
		generic_graph *&	graph,
		AcisOptions *	ao = `NULL`
	)

Creates a graph (from cells) used in graph theory.

Role: This API creates a graph that can be used for graph theory operations and selective Booleans.

When creating a graph from cells, the list must contain cells from Cellular Topology. The ACIS topology is analyzed to determine which cells are connected. The connections between cells become edges (or dashes) of the graph.

Effect: Changes model

Journal: Available

Parameters:

	cells	cells to use.
	graph	graph.
	ao	acis options.

include <sboolapi.hxx>

outcome api_create_graph_from_edges	(	ENTITY_LIST &	edges,
		generic_graph *&	graph,
		AcisOptions *	ao = `NULL`
	)

Creates a graph (from edges) used in graph theory.

Role: This API creates a graph used for graph theory operations and selective Booleans.

Effect: Changes model

Journal: Available

Parameters:

	edges	edges to use.
	graph	graph.
	ao	acis options.

include <sboolapi.hxx>

outcome api_create_graph_from_faces	(	ENTITY_LIST &	faces,
		generic_graph *&	graph,
		AcisOptions *	ao = `NULL`
	)

Creates a graph (from faces) used in graph theory.

Role: This API creates a graph that can be used for graph theory operations and selective Booleans.

Effect: Changes model

Journal: Available

Parameters:

	faces	faces to use.
	graph	graph.
	ao	acis options.

include <sboolapi.hxx>

outcome api_initialize_sbooleans ( )

Initializes the Selective Booleans Component library.

Effect: System routine

Journal: Not Available

include <sboolapi.hxx>

outcome api_selective_boolean_stage1	(	BODY *	blank,
		BODY *	tool,
		generic_graph *&	graph,
		AcisOptions *	ao = `NULL`
	)

Creates a graph for the first stage of selective Booleans from a tool body and a blank body.

Role: This API creates a graph structure (e.g., graph theory) from the blank_body entity and the tool_body entity. Using Cellular Topology, distinctive cells of the blank_body and the tool_body become vertices of the graph. Overlapping portions of the cells become edges in the graph. Once the graph has been created, further graph theory operations can be performed to obtain a more desirable graph. This is then used as input to the second stage of selective Booleans, api_selective_boolean_stage2.

Errors: Pointer to tool or blank body is NULL or not to a BODY.

Effect: Changes model

Journal: Available

Parameters:

	blank	blank body.
	tool	tool body.
	graph	cell adjacency graph.
	ao	acis options.

include <sboolapi.hxx>

outcome api_selective_boolean_stage2	(	BODY *	non_reg_unite_body,
		generic_graph *	graph_of_cells_to_keep,
		AcisOptions *	ao = `NULL`
	)

Completes the selective Boolean process for the cells selected.

Role: This function modifies the entity based on either the results of graph theory or a Cellular Topology cell list. When a cell list is used, only the cell entities in the list should be kept. When a graph is used, the resulting graph still maps to cells in the body and represents the cells to keep.

The mapping of cells in a graph to entities will not be the same from execution to execution.

Effect: Changes model

Journal: Available

Parameters:

	non_reg_unite_body	body to use.
	graph_of_cells_to_keep	graph cells to keep.
	ao	acis options.

include <sboolapi.hxx>

outcome api_selective_boolean_stage2	(	BODY *	non_reg_unite_body,
		ENTITY_LIST &	cells_to_keep,
		AcisOptions *	ao = `NULL`
	)

Completes the selective Boolean process for the cells selected.

Role: This function modifies the entity based on either the results of graph theory or a Cellular Topology cell list. When a cell list is used, only the cell entities in the list should be kept. When a graph is used, the resulting graph still maps to cells in the body and represents the cells to keep.

The mapping of cells in a graph to entities will not be the same from execution to execution.

Effect: Changes model

Journal: Available

Parameters:

	non_reg_unite_body	body to use.
	cells_to_keep	cells to keep.
	ao	acis options.

include <sboolapi.hxx>

outcome api_selective_unite	(	BODY *	tool,
		BODY *	blank,
		int	tnum,
		SPAposition *	tpos,
		int	bnum = `0`,
		SPAposition *	bpos = `NULL`,
		AcisOptions *	ao = `NULL`
	)

Unites two bodies with the given positions.

Role: This selective union operation takes two bodies and two lists of positions. The lists of positions are used to specify the portions to keep after the Boolean operation. If the number of positions is zero, the operation will retain the entire body.

Effect: Changes model

Journal: Available

Parameters:

	tool	first body.
	blank	second body.
	tnum	number of position on tool to keep, 0 means keep all.
	tpos	positions.
	bnum	number of position on blank to keep, 0 means keep all.
	bpos	positions.
	ao	acis options.

include <sboolapi.hxx>

outcome api_subgraph_2dcell	(	const generic_graph *	whole_graph,
		generic_graph *&	partial_graph,
		AcisOptions *	ao = `NULL`
	)

Returns a subgraph containing only the vertices that are 2D cells.

Effect: Read-only

Journal: Available

Parameters:

	whole_graph	input graph.
	partial_graph	output graph with 2d cells.
	ao	acis options.

include <sboolapi.hxx>

outcome api_subgraph_3dcell	(	const generic_graph *	whole_graph,
		generic_graph *&	partial_graph,
		AcisOptions *	ao = `NULL`
	)

Returns a subgraph containing only the vertices that are 3D cells.

Effect: Read-only

Journal: Available

Parameters:

	whole_graph	input graph.
	partial_graph	output graph with 3d cells.
	ao	acis options.

include <sboolapi.hxx>

outcome api_subset_graph_with_plane	(	const generic_graph *	whole_graph,
		const SPAposition &	plane_origin,
		const SPAunit_vector &	plane_normal,
		generic_graph *&	partial_graph,
		AcisOptions *	ao = `NULL`
	)

Finds the subset of a graph on one side of a plane.

Role: The graph must first be split at that plane. It is assumed that the graph is made of entities which are either faces or cells.

Effect: Read-only

Journal: Available

Parameters:

	whole_graph	input graph.
	plane_origin	origin.
	plane_normal	plane normal.
	partial_graph	output graph.
	ao	acis options.

include <sboolapi.hxx>

outcome api_terminate_sbooleans ( )

Terminates the Selective Booleans Component library.

Effect: System routine

Journal: Not Available

include <sboolapi.hxx>

Selective Booleans [Advanced Operations, Booleans]

Classes

Functions

Function Documentation

Selective Booleans
[Advanced Operations, Booleans]