Home Page > API Reference > Model > Operations and Agorithms > IBoolSectionEx

Search Documentation

IBoolSectionEx Interface

IBoolSectionEx interface is an enhanced version of IBoolSection, which returns information about the interentity curve of the two objects.

See also Cross View sample and BoolOp Sample

• Execute
• Execute2
• CreateExtendedContext
• Execute3
• Clip
• Clip2

HRESULT Execute( EBooleanOperation operation, ISection* object, VARIANT_BOOL createIntersLine, IArray** edges )

Parameters

operation - [in] member of EBooleanOperation enumeration indicating the operation to perform

object - [in] reference to the second object for the operation. (The first object is the entity which implements this IBoolSectionEx interface)

createIntersLine - [in] If true a set of Line Strip objects representing interentity line will be created and added as child of the first entity (the entity where this interface was queried form). See remarks for more details

edges - [out, retval] Array of isolated interentity loops. Each element has type IArray, elements in the later array have type IVertex. See remarks

Remarks

Performs operation indicated by operation on the entity where this IBoolSectionEx was queried from and object. This method also allows performing subtraction of a programmatically defined plane from the object. See details in Planar Subtract.

If createIntersLine parameter is true a new empty object will be created and added as new child of the first entity. The object will act as a group (container for its children). The objects will have one or more child objects of Line Strip type one per linked piece of interentity. For example, subtraction of a long and thin cylinder from a sphere will have two closed isolated interentity loops. In that case the newly added object will have two children one per each interentity loop. Coordinates of points in the lines and other information can be obtained via ISectionPointSet and ISectionLineStrip queried form the relevant child. See BoolOp Sample for an example.

The returned edges array contains information abut the isolated linked interentity loops. Each loop is an array (IArray) of IVertex elements, which can be used to obtain coordinates and normals to the surface at the interentity points.  See Cross View sample for an example. This calculation is not performed and NULL will be returned if createIntersLine is false.

IVertex obtained above contains all normals to the resulting surface. The most frequent case when two surfaces are smooth around the interentity curve the vertex contains two normals on the left (side of surface of the first object, where this interface was queried form) and right hand side of the interentity curve. Often there are several normals on each side, for example when interentity curve crosses an edge of either surface. In some cases (planar subtract or case when the second object is not a closed surface and edges do not intersect) the interentity curve becomes an edge of the resulting surface, so the vertex can have only single normal, the one which belongs to the first surface.

To find out which normals in the vertex belong to which side of the curve query IUserData from the IVertex and call IUserData.GetData. The returned cnt number is count of normals which belong to the first surface (normals on the left). Normals 0 to cnt-1 in the vertex belong to the first surface, the rest belong to the second surface.

HRESULT STDMETHODCALLTYPE Execute2( ISection* object, EBoolOpContext* context )

Parameters

object - [in] reference to the second object for the operation. (The first object is the entity which implements this IBoolSectionEx interface)

context - [in, out] - additional input and output parameters for the operation. See remarks

Remarks

Performs operation indicated by context.operation on the entity where this IBoolSectionEx was queried from and object. This method also allows performing subtraction of a programmatically defined plane from the object. See details in Planar Subtract.

If context.execute is false, only interentity loops are calculated and the Boolean operation is not executed, which significantly improves performance.

If context.interentityLine is true a new empty object will be created and added as new child of the first entity. The object will act as a group (container for its children). The objects will have one or more child objects of Line Strip type one per linked piece of interentity. For example, subtraction of a long and thin cylinder from a sphere will have two closed isolated interentity loops. In that case the newly added object will have two children one per each interentity loop. Coordinates of points in the lines and other information can be obtained via ISectionPointSet and ISectionLineStrip queried form the relevant child. See BoolOp Sample for an example.

If context.needEdges is true context.edges will contain information abut the calculated interentity curve. This calculation is not performed context.interentityLine is false. The curve consists of the isolated linked interentity loops. Each loop is an array (IArray) of IVertex elements, which can be used to obtain coordinates and normals to the surface at the interentity points. See remarks for the previous method for more details. See Cross View sample for an example.

context.edges array must be created by the caller. To create the array call Create or Create2 method of IDIObjectGenerator interface with parameter eType set to eObjTypeArray member of EObjectType enumeration. Query IArray  from the returned IUnknown interface. After call to this Execute2() method the array will contain elements which in turn are arrays too. More exactly arrays of vertices.

If separateComponents is true and the first object becomes divided into several isolated pieces, the pieces will become separate objects. The initial first object will be replaced with one if the pieces. The other pieces will be added as new children of the first object. Selection of pieces for the parent and children is random.

Note: All elements of the context structure must be initialized before the call. Details

HRESULT STDMETHODCALLTYPE CreateExtendedContext( IDictionary_KC** contextExt)

Parameters

contextExt - [out, retval] The created and returned context

Remarks

Creates a context with extra options for the Execute3 method below. All parameters have the default values

HRESULT Execute3( EBooleanOperation operation, ISection** object, IDictionary_KC* contextExt)

Parameters

operation - [in] member of EBooleanOperation enumeration indicating the operation to perform

object - [in] reference to the second object for the operation. (The first object is the entity which implements this IBoolSectionEx interface)

contextExt - [in] A null reference or a context created by the CreateExtendedContext() method above, which contains additional options for the operation. See remarks

Remarks

Performs operation specified by operation on the entity where this IBoolSectionEx was queried from and object. The significant difference with the Execute2 method is that the InclideChildren* properties below, allow boolean operations on groups of objects

contextExt has the following parameters:

HRESULT Clip(IObjectOriented* objectClipper, VARIANT_BOOL needTopLinkedComponentOnly)

Parameters

Remarks

Clips the object, which implements this interface with objectClipper

needTopLinkedComponentOnly has effect only when objectClipper has natural diection of its internal area. In the initial implementation this is used for the case of an infinite prizm build on a polygon in x and y axes, so z axis defines a positive direction

After the operation the resulting surface is often split into isolated pieces (A sphere clipped with a thin infinite triangular prizm around the center). When the pieces have non-overlapping distinct ranges they are arranged along z axis

In this situation if needTopLinkedComponentOnly is true only the one with max z will be the result of the operation. Otherwise all components will be merged into the final object

HRESULT Clip2(IObjectOriented* objectClipper, IListT** listIEntity)

Parameters

Remarks

Calculates the result of cliping this object (the object, which implements this interface) with objectClipper

Does not modify this object. listIEntity contains linked pieces of the result. See also the previous method