Element Controller

interface ICwAPI3DElementController

Public Functions

virtual ICwAPI3DString *getLastError(int32_t *aErrorCode) = 0

Gets the last error.

Parameters:

aErrorCode – [out] [int32_t*] The error code.

Returns:

[ICwAPI3DString*] The error string.

virtual ICwAPI3DElementIDList *getAllIdentifiableElementIDs() = 0

Retrieves a list of all identifiable elements.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all identifiable elements.

virtual ICwAPI3DElementIDList *getVisibleIdentifiableElementIDs() = 0

Retrieves a list of all visible identifiable elements.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all visible identifiable elements.

virtual ICwAPI3DElementIDList *getInvisibleIdentifiableElementIDs() = 0

Retrieves a list of all invisible identifiable elements.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all invisible identifiable elements.

virtual ICwAPI3DElementIDList *getActiveIdentifiableElementIDs() = 0

Retrieves a list of all active identifiable elements.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all active identifiable elements.

virtual ICwAPI3DElementIDList *getInactiveAllIdentifiableElementIDs() = 0

Retrieves a list of all identifiable elements that are inactive.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all inactive identifiable elements.

virtual ICwAPI3DElementIDList *getInactiveVisibleIdentifiableElementIDs() = 0

Retrieves a list of visible identifiable elements that are inactive.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all inactive visible identifiable elements.

virtual void deleteElements(ICwAPI3DElementIDList *aElementIdList) = 0

Deletes the specified elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be deleted.

virtual void joinElements(ICwAPI3DElementIDList *aElementIdList) = 0

Joins the specified elements together.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be joined.

virtual void joinTopLevelElements(ICwAPI3DElementIDList *aElementIdList) = 0

Joins the specified top-level elements together.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of top-level elements to be joined.

virtual elementID createRectangularBeamPoints(double aWidth, double aHeight, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a rectangular beam using points.

Example:

// Create a rectangular beam defined by points
double beamWidth = 200.0;
double beamHeight = 400.0;
vector3D beamAxisStartPt{300.0, 0.0, 0.0};
vector3D beamAxisEndPt{300.0, 0.0, 4000.0};
vector3D lengthVector = (beamAxisEndPt - beamAxisStartPt).normalized();
vector3D beamAxisY{1.0, 0.0, 0.0};
vector3D beamAxisZ = lengthVector.cross(beamAxisY).normalized();
vector3D beamHeightAxisPt = beamAxisStartPt + beamAxisZ;

elementID beamID = aFactory.getElementController()->createRectangularBeamPoints(
    beamWidth,
    beamHeight,
    beamAxisStartPt,
    beamAxisEndPt,
    beamHeightAxisPt
);

Parameters:

• aWidth – [in] [double] The width of the beam.

• aHeight – [in] [double] The height of the beam.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created rectangular beam.

virtual elementID createCircularBeamPoints(double aDiameter, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a circular beam using points.

Example :

double beamDiameter = 120.0;
vector3D beamAxisStartPt{0.0, 0.0, 0.0};
vector3D beamAxisEndPt{0.0, 0.0, 3000.0};
vector3D lengthVector = (beamAxisEndPt - beamAxisStartPt).normalized();
vector3D beamAxisY{1.0, 0.0, 0.0};
vector3D beamAxisZ = (lengthVector.cross(beamAxisY)).normalized();
vector3D beamOrientationPt = beamAxisStartPt + beamAxisZ;
elementID beamID = aFactory.getElementController()->createCircularBeamPoints(beamDiameter, beamAxisStartPt, beamAxisEndPt, beamOrientationPt);

Parameters:

• aDiameter – [in] [double] The diameter of the beam.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created circular beam.

virtual elementID createSquareBeamPoints(double aWidth, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a square beam using points.

Example:

// Create a square beam using two axis points and an orientation point
double beamWidth = 100.0;
vector3D beamAxisStartPt{500.0, 500.0, 0.0};
vector3D beamAxisEndPt{500.0, 500.0, 2500.0};

vector3D lengthVector = (beamAxisEndPt - beamAxisStartPt).normalized();
vector3D referenceVector{0.0, 1.0, 0.0};
vector3D beamAxisZ = lengthVector.cross(referenceVector).normalized();
vector3D orientationPt = beamAxisStartPt + beamAxisZ;

elementID beamID = aFactory.getElementController()->createSquareBeamPoints(
    beamWidth,
    beamAxisStartPt,
    beamAxisEndPt,
    orientationPt
);

Parameters:

• aWidth – [in] [double] The width of the beam.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created square beam.

virtual elementID createRectangularBeamVectors(double aWidth, double aHeight, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a rectangular beam using vectors.

Example:

double beamWidth = 150.0;
double beamHeight = 300.0;
double beamLength = 4000.0;
vector3D originPoint{0.0, 0.0, 0.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Direction along length
vector3D zDirection{0.0, 0.0, 1.0};  // Direction along height

elementID beamID = aFactory.getElementController()->createRectangularBeamVectors(
    beamWidth,
    beamHeight,
    beamLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aWidth – [in] [double] The width of the beam.

• aHeight – [in] [double] The height of the beam.

• aLength – [in] [double] The length of the beam.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created rectangular beam.

virtual elementID createCircularBeamVectors(double aDiameter, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a circular beam using vectors.

Example :

double beamDiameter = 100.0;
double beamLength = 3500.0;
vector3D originPoint{200.0, 200.0, 200.0};
vector3D xDirection{0.0, 1.0, 0.0};  // Beam aligned with Y axis
vector3D zDirection{0.0, 0.0, 1.0};  // Z orientation (arbitrary for circular beam)
elementID beamID = aFactory.getElementController()->createCircularBeamVectors(beamDiameter, beamLength, originPoint, xDirection, zDirection);

Parameters:

• aDiameter – [in] [double] The diameter of the beam.

• aLength – [in] [double] The length of the beam.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created circular beam.

virtual elementID createSquareBeamVectors(double aWidth, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a square beam using vectors.

Example:

// Create a square beam using length and orientation vectors
double beamWidth = 120.0;
double beamLength = 2800.0;

vector3D originPoint{0.0, 0.0, 500.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Direction along length
vector3D zDirection{0.0, 0.0, 1.0};  // Direction for orientation

elementID beamID = aFactory.getElementController()->createSquareBeamVectors(
    beamWidth,
    beamLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aWidth – [in] [double] The width of the beam.

• aLength – [in] [double] The length of the beam.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created square beam.

virtual elementID createRectangularPanelPoints(double aWidth, double aThickness, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a rectangular panel using points.

Example:

double panelWidth = 1200.0;
double panelThickness = 27.0;
vector3D panelCornerPt{0.0, 0.0, 0.0};
vector3D panelLengthPt{0.0, 2400.0, 0.0};
// Calculate a point to define panel orientation
vector3D normalVector{0.0, 0.0, 1.0};  // Panel normal in Z direction
vector3D orientationPt = panelCornerPt + normalVector;

elementID panelID = aFactory.getElementController()->createRectangularPanelPoints(
    panelWidth,
    panelThickness,
    panelCornerPt,
    panelLengthPt,
    orientationPt
);

Parameters:

• aWidth – [in] [double] The width of the panel.

• aThickness – [in] [double] The thickness of the panel.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created rectangular panel.

virtual elementID createRectangularPanelVectors(double aWidth, double aThickness, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a rectangular panel using vectors.

Example:

double panelWidth = 1000.0;
double panelThickness = 20.0;
double panelLength = 2000.0;
vector3D originPoint{0.0, 0.0, 100.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Direction along length
vector3D zDirection{0.0, 0.0, 1.0};  // Panel normal direction

elementID panelID = aFactory.getElementController()->createRectangularPanelVectors(
    panelWidth,
    panelThickness,
    panelLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aWidth – [in] [double] The width of the panel.

• aThickness – [in] [double] The thickness of the panel.

• aLength – [in] [double] The length of the panel.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created rectangular panel.

virtual elementID createDrillingPoints(double aDiameter, vector3D aFirstPoint, vector3D aSecondPoint) = 0

Creates a drilling using points.

Example :

double drillDiameter = 30.0;
vector3D drillStartPt{100.0, 100.0, 0.0};
vector3D drillEndPt{100.0, 100.0, 200.0};
elementID drillingID = aFactory.getElementController()->createDrillingPoints(drillDiameter, drillStartPt, drillEndPt);

Parameters:

• aDiameter – [in] [double] The diameter of the drilling.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

Returns:

[elementID] The ID of the created drilling.

virtual elementID createDrillingVectors(double aDiameter, double aLength, vector3D aStartingPoint, vector3D aDrillingDirection) = 0

Creates a drilling using vectors.

Example :

double drillDiameter = 12.0;
double drillLength = 180.0;
vector3D drillStartPt{200.0, 200.0, 50.0};
vector3D drillDirection{0.0, 0.0, 1.0};  // Drilling in Z direction
elementID drillingID = aFactory.getElementController()->createDrillingVectors(drillDiameter, drillLength, drillStartPt, drillDirection);

Parameters:

• aDiameter – [in] [double] The diameter of the drilling.

• aLength – [in] [double] The length of the drilling.

• aStartingPoint – [in] [vector3D] The starting point.

• aDrillingDirection – [in] [vector3D] The direction of the drilling. (The vector needs to be normalized beforehand)

Returns:

[elementID] The ID of the created drilling.

virtual elementID createLinePoints(vector3D aFirstPoint, vector3D aSecondPoint) = 0

Creates a line using points.

Example :

vector3D lineStartPt{0.0, 0.0, 0.0};
vector3D lineEndPt{500.0, 500.0, 0.0};
elementID lineID = aFactory.getElementController()->createLinePoints(lineStartPt, lineEndPt);

Parameters:

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

Returns:

[elementID] The ID of the created line.

virtual elementID createLineVectors(double aLength, vector3D aStartingPoint, vector3D aLineDirection) = 0

Creates a line using vectors.

Example :

double lineLength = 1000.0;
vector3D lineStartPt{200.0, 0.0, 200.0};
vector3D lineDirection{1.0, 1.0, 0.0};  // 45 degree line in XY plane
lineDirection = lineDirection.normalized();
elementID lineID = aFactory.getElementController()->createLineVectors(lineLength, lineStartPt, lineDirection);

Parameters:

• aLength – [in] [double] The length of the line.

• aStartingPoint – [in] [vector3D] The starting point of the line.

• aLineDirection – [in] [vector3D] The direction of the line.

Returns:

[elementID] The ID of the created line.

virtual elementID createNode(vector3D aNodePosition) = 0

Creates a node at the specified point.

Example :

vector3D nodePosition{250.0, 250.0, 100.0};
elementID nodeID = aFactory.getElementController()->createNode(nodePosition);

Parameters:

aNodePosition – [in] [vector3D] The position of the node.

Returns:

[elementID] The ID of the created node.

virtual ICwAPI3DElementIDList *solderElements(ICwAPI3DElementIDList *aElementIdList) = 0

Solder the specified elements together.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be soldered.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the soldered elements.

virtual void convertBeamToPanel(ICwAPI3DElementIDList *aElementIdList) = 0

Converts the specified beams to panels.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of beams to be converted.

virtual void convertPanelToBeam(ICwAPI3DElementIDList *aElementIdList) = 0

Converts the specified panels to beams.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of panels to be converted.

virtual void deleteAllElementEndTypes(ICwAPI3DElementIDList *aElementIdList) = 0

Deletes all end types of the provided elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to delete all end types.

virtual void deleteAllElementProcesses(ICwAPI3DElementIDList *aElementIdList) = 0

Deletes all processes of the provided elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to delete all processes.

virtual void moveElement(ICwAPI3DElementIDList *aElementIdList, vector3D aMoveVector) = 0

Moves the provided elements by a specified vector.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to move.

• aMoveVector – [in] [vector3D] The vector by which to move the elements.

virtual elementID createPolygonBeam(ICwAPI3DVertexList *aPolygonVertices, double aThickness, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a polygon beam.

Example :

// Create a triangular beam
ICwAPI3DVertexList* vertices = aFactory.createVertexList();
vertices->append(vector3D{0.0, 0.0, 0.0});
vertices->append(vector3D{200.0, 0.0, 0.0});
vertices->append(vector3D{100.0, 173.2, 0.0});  // Equilateral triangle
double beamThickness = 1000.0;  // Length of the beam
vector3D extrusionVector{0.0, 0.0, 1.0};  // Direction of extrusion
vector3D zVector{1.0, 0.0, 0.0};  // Orientation vector
elementID polygonBeamID = aFactory.getElementController()->createPolygonBeam(vertices, beamThickness, extrusionVector, zVector);

Parameters:

• aPolygonVertices – [in] [ICwAPI3DVertexList*] The vertices of the polygon.

• aThickness – [in] [double] The thickness of the beam.

• aXDirectionLocal – [in] [vector3D] The X-axis direction of the beam.

• aZDirectionLocal – [in] [vector3D] The Z-axis direction of the beam.

Returns:

[elementID] The ID of the created polygon beam.

virtual elementID createTextObject(const character *aText, vector3D aPosition, vector3D aXDirectionLocal, vector3D aZDirectionLocal, double aSize) = 0

Creates a text object.

Example:

const character* textContent = L"Cadwork API";
vector3D textPosition{0.0, 0.0, 0.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Text direction
vector3D zDirection{0.0, 0.0, 1.0};  // Text orientation
double textHeight = 200.0;

elementID textID = aFactory.getElementController()->createTextObject(
    textContent,
    textPosition,
    xDirection,
    zDirection,
    textHeight
);

Parameters:

• aText – [in] [const character*] The text to be displayed in the text object.

• aPosition – [in] [vector3D] The position of the text object.

• aXDirectionLocal – [in] [vector3D] The X-axis direction of the text object.

• aZDirectionLocal – [in] [vector3D] The Z-axis direction of the text object.

• aSize – [in] [double] The size of the text object.

Returns:

[elementID] The ID of the created text object.

virtual ICwAPI3DElementIDList *copyElements(ICwAPI3DElementIDList *aElementIdList, vector3D aCopyVector) = 0

Copies a list of elements.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be copied.

• aCopyVector – [in] [vector3D] The vector along which the elements should be copied.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the copied elements.

virtual void rotateElements(ICwAPI3DElementIDList *aElementIdList, vector3D aOrigin, vector3D aRotationAxis, double aRotationAngle) = 0

Rotates a list of elements.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be rotated.

• aOrigin – [in] [vector3D] The origin of the rotation.

• aRotationAxis – [in] [vector3D] The axis of the rotation.

• aRotationAngle – [in] [double] The angle of the rotation in radians.

virtual ICwAPI3DElementIDList *subtractElements(ICwAPI3DElementIDList *aHardElements, ICwAPI3DElementIDList *aSoftElements) = 0

Subtracts a list of “soft” elements from a list of “hard” elements.

Parameters:

• aHardElements – [in] [ICwAPI3DElementIDList*] The list of “hard” elements.

• aSoftElements – [in] [ICwAPI3DElementIDList*] The list of “soft” elements.

Returns:

[ICwAPI3DElementIDList*] The list of elements resulting from the subtraction.

virtual bool checkElementId(elementID aElementId) = 0

Checks if the provided element ID exists.

Parameters:

aElementId – [in] [elementID] The ID of the element to check.

Returns:

[bool] True if the element ID exists, false otherwise.

virtual ICwAPI3DElementIDList *filterElements(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementFilter *aFilter) = 0

Filters a list of elements based on a provided filter.

Example:

ICwAPI3DElementIDList* allElements = aFactory.getElementController()->getActiveIdentifiableElementIDs();

ICwAPI3DElementFilter elementFilter;
elementFilter.setName(L"beam");

ICwAPI3DElementIDList* filteredElements = aFactory.getElementController()->filterElements(
    allElements,
    &elementFilter
);

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to filter.

• aFilter – [in] [ICwAPI3DElementFilter*] The filter to apply to the list of elements.

Returns:

[ICwAPI3DElementIDList*] The list of elements that pass the filter.

virtual ICwAPI3DElementIDListMap *mapElements(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementMapQuery *aMapQuery) = 0

Maps a list of elements based on a provided map query.

Example:

// Create a map query by subgroup
ICwAPI3DElementMapQuery mapQuery;
mapQuery.setBySubgroup();

// Map the active identifiable elements using the query
ICwAPI3DElementIDMap* mappedItems = aFactory.getElementController()->mapElements(
    aFactory.getElementController()->getActiveIdentifiableElementIDs(),
    &mapQuery
);

printf("Mapped item count: %d\n", mappedItems->count());

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to map.

• aMapQuery – [in] [ICwAPI3DElementMapQuery*] The map query to apply to the list of elements.

Returns:

[ICwAPI3DElementIDListMap*] The map of elements that pass the map query.

virtual void startElementModuleCalculation(ICwAPI3DElementIDList *aCoverIdList) = 0

Starts the calculation of the element module for a list of covers.

Parameters:

aCoverIdList – [in] [ICwAPI3DElementIDList*] The list of covers for which to start the element module calculation.

virtual void setElementDetailPath(const character *aPath) = 0

Sets the detail path for the element module.

Parameters:

aPath – [in] [const character*] The path to be set as the detail path.

virtual ICwAPI3DString *getElementDetailPath() = 0

Retrieves the detail path of the element module.

Returns:

[ICwAPI3DString*] The detail path of the element module.

virtual ICwAPI3DString *getElementCadworkGuid(elementID aElementId) = 0

Retrieves the Cadwork GUID of a specific element.

Parameters:

aElementId – [in] [elementID] The ID of the element.

Returns:

[ICwAPI3DString*] The Cadwork GUID of the element.

virtual elementID getElementFromCadworkGuid(const character *aCadworkGuid) = 0

Retrieves the element ID from a Cadwork GUID.

Parameters:

aCadworkGuid – [in] [const character*] The Cadwork GUID to retrieve the element ID from.

Returns:

[elementID] The ID of the element.

virtual void addElementsToUndo(ICwAPI3DElementIDList *aElementIdList, int32_t aCmd) = 0

Adds elements to the undo stack.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be added to the undo stack.

• aCmd – [in] [int32_t] The command associated with the undo operation.

virtual void makeUndo() = 0

Performs an undo operation, reverting the last change made.

virtual void makeRedo() = 0

Performs a redo operation, reapplying the last change that was undone.

virtual void splitElements(ICwAPI3DElementIDList *aElementIdList) = 0

Splits the specified elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be split.

virtual void setLineToMarkingLine(ICwAPI3DElementIDList *aElementIdList) = 0

Sets the specified lines to be marking lines.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of lines to be set as marking lines.

virtual void setLineToNormalLine(ICwAPI3DElementIDList *aElementIdList) = 0

Sets the specified lines to be normal lines.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of lines to be set as normal lines.

virtual elementID createAutoExportSolidFromStandard(ICwAPI3DElementIDList *aElementIdList, const character *aOutputName, const character *aStandardElementName) = 0

Creates an auto export solid from a standard element.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be used in the auto export solid.

• aOutputName – [in] [const character*] The name of the output.

• aStandardElementName – [in] [const character*] The name of the standard element.

Returns:

[elementID] The ID of the created auto export solid.

virtual void setElementModulePropertiesForElements(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementModuleProperties *aProperties) = 0

Sets the module properties for the provided elements.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to set the module properties for.

• aProperties – [in] The module properties to be set.

virtual ICwAPI3DElementModuleProperties *getElementModulePropertiesForElement(elementID aElementId) = 0

Retrieves the module properties for a specific element.

Parameters:

aElementId – [in] [elementID] The ID of the element.

Returns:

[ICwAPI3DElementModuleProperties*] The module properties of the element.

virtual ICwAPI3DString *getElementTypeDescription(elementID aElementId) = 0

Retrieves the type description of a specific element.

Parameters:

aElementId – [in] [elementID] The ID of the element.

Returns:

[ICwAPI3DString*] The type description of the element.

virtual elementID createTextObjectWithFont(const character *aText, vector3D aPosition, vector3D aXDirectionLocal, vector3D aZDirectionLocal, double aSize, const character *aFontName) = 0

Creates a text object with a specific font.

Example:

const character* textContent = L"Custom Text";
vector3D textPosition{0.0, 0.0, 0.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Text direction
vector3D zDirection{0.0, 0.0, 1.0};  // Text orientation
double textHeight = 150.0;
const character* fontName = L"Arial";

elementID textID = aFactory.getElementController()->createTextObjectWithFont(
    textContent,
    textPosition,
    xDirection,
    zDirection,
    textHeight,
    fontName
);

Parameters:

• aText – [in] [const character*] The text to be displayed in the text object.

• aPosition – [in] [vector3D] The position of the text object.

• aXDirectionLocal – [in] [vector3D] The X-axis direction of the text object.

• aZDirectionLocal – [in] [vector3D] The Z-axis direction of the text object.

• aSize – [in] [double] The size of the text object.

• aFontName – [in] [const character*] The name of the font to be used in the text object.

Returns:

[elementID] The ID of the created text object.

virtual ICwAPI3DElementIDList *getOpeningVariantIDs(ICwAPI3DElementIDList *aElementIdList, int32_t aOpeningType) = 0

Retrieves the opening variant IDs of the provided elements.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to check for opening variants.

• aOpeningType – [in] [int32_t] The type of opening to check for.

Returns:

[ICwAPI3DElementIDList*] The list of opening variant IDs.

virtual elementID getParentContainerId(elementID aElementId) = 0

Retrieves the parent container ID of a nested element.

Parameters:

aElementId – [in] [elementID] The ID of the nested element.

Returns:

[elementID] The ID of the parent container.

virtual ICwAPI3DElementIDList *getExportSolidContentElements(elementID aElementId) = 0

Retrieves the content elements of an export solid.

Parameters:

aElementId – [in] [elementID] The ID of the export solid.

Returns:

[ICwAPI3DElementIDList*] The list of content elements.

virtual ICwAPI3DElementIDList *getContainerContentElements(elementID aElementId) = 0

Retrieves the content elements of a container.

Parameters:

aElementId – [in] [elementID] The ID of the container.

Returns:

[ICwAPI3DElementIDList*] The list of content elements.

virtual void applyTransformationCoordinate(ICwAPI3DElementIDList *aElementIdList, vector3D aOldPoint, vector3D aOldXDirectionLocal, vector3D aOldYDirectionLocal, vector3D aNewPoint, vector3D aNewXDirectionLocal, vector3D aNewYDirectionLocal) = 0

Applies a transformation to the provided elements.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to transform.

• aOldPoint – [in] [vector3D] The original point of the transformation.

• aOldXDirectionLocal – [in] [vector3D] The original X-axis direction.

• aOldYDirectionLocal – [in] [vector3D] The original Y-axis direction.

• aNewPoint – [in] [vector3D] The new point of the transformation.

• aNewXDirectionLocal – [in] [vector3D] The new X-axis direction.

• aNewYDirectionLocal – [in] [vector3D] The new Y-axis direction.

virtual void deleteElementsWithUndo(ICwAPI3DElementIDList *aElementIdList) = 0

Deletes the provided elements with undo functionality.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to delete.

virtual void addCreatedElementsToUndo(ICwAPI3DElementIDList *aElementIdList) = 0

Adds created elements to the undo stack.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements that were created.

virtual void addModifiedElementsToUndo(ICwAPI3DElementIDList *aElementIdList) = 0

Adds modified elements to the undo stack.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements that were modified.

virtual void recreateElements(ICwAPI3DElementIDList *aElementIdList) = 0

Recreates elements based on the provided list.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be recreated.

virtual bool checkIfElementsAreInCollision(elementID aFirstElementID, elementID aSecondElementID) = 0

Checks if two elements are in collision.

Parameters:

• aFirstElementID – [in] [elementID] The ID of the first element.

• aSecondElementID – [in] [elementID] The ID of the second element.

Returns:

[bool] True if the elements are in collision, false otherwise.

virtual bool checkIfElementsAreInContact(elementID aFirstElementID, elementID aSecondElementID) = 0

Checks if two elements are in contact.

Parameters:

• aFirstElementID – [in] [elementID] The ID of the first element.

• aSecondElementID – [in] [elementID] The ID of the second element.

Returns:

[bool] True if the elements are in contact, false otherwise.

virtual void createMultiWall(ICwAPI3DElementIDList *aElementIdList) = 0

Creates a multi-wall structure.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be used in the multi-wall structure.

virtual ICwAPI3DElementIDList *getUserElementIDs() = 0

Retrieves a list of user element IDs.

Returns:

[ICwAPI3DElementIDList*] The list of user element IDs.

virtual ICwAPI3DVertexList *getElementContactVertices(elementID aFirstID, elementID aSecondID) = 0

Retrieves the contact vertices between two elements.

Parameters:

• aFirstID – [in] [elementID] The ID of the first element.

• aSecondID – [in] [elementID] The ID of the second element.

Returns:

[ICwAPI3DVertexList*] The list of contact vertices between the two elements.

virtual elementID getNestingParentId(elementID aElementId) = 0

Retrieves the parent ID of a nested element.

Parameters:

aElementId – [in] [elementID] The ID of the nested element.

Returns:

[elementID] The ID of the parent element.

virtual ICwAPI3DElementIDList *getUserElementIDsWithExisting(ICwAPI3DElementIDList *aElementIdList) = 0

Retrieves a list of user element IDs that exist in the provided list.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to check for existence.

Returns:

[ICwAPI3DElementIDList*] The list of existing user element IDs.

virtual void clearErrors() = 0

Clears all errors.

virtual void glideElements(ICwAPI3DElementIDList *aElementIdList, vector3D aGlideOriginPoint) = 0

Glides elements to a specified point.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList] The element list id to move.

• aGlidePoint – [in] [vector3D] The glide origin point.

virtual ICwAPI3DFacetList *getElementContactFacets(elementID aFirstID, elementID aSecondID) = 0

Retrieves the contact facets between two elements.

Parameters:

• aFirstID – [in] [elementID] The ID of the first element.

• aSecondID – [in] [elementID] The ID of the second element.

Returns:

[ICwAPI3DFacetList*] The list of contact facets between the two elements.

virtual ICwAPI3DVertexList *getElementRawInterfaceVertices(elementID aFirstID, elementID aSecondID) = 0

Retrieves the raw interface vertices between two elements.

Parameters:

• aFirstID – [in] [elementID] The ID of the first element.

• aSecondID – [in] [elementID] The ID of the second element.

Returns:

[ICwAPI3DVertexList*] The list of raw interface vertices between the two elements.

virtual bool cutElementsWithMiter(elementID aFirstID, elementID aSecondID) = 0

Cuts two elements with a miter joint.

Parameters:

• aFirstID – [in] [elementID] The ID of the first element.

• aSecondID – [in] [elementID] The ID of the second element.

Returns:

[bool] True if the operation was successful, false otherwise.

virtual bool cutElementWithPlane(elementID aElementId, vector3D aCutPlaneNormalVector, double aDistanceFromGlobalOrigin) = 0

Cuts an element with a plane.

Example:

double beamHeight = 240.0;

vector3D origin{0.0, 0.0, 0.0};
vector3D xDir{0.0, 0.0, 1.0};
vector3D zDir{0.0, 1.0, 0.0};

elementID beamID = aFactory.getElementController()->createRectangularBeamVectors(
    120.0,
    beamHeight,
    3000.0,
    origin,
    xDir,
    zDir
);

double angleRad = M_PI / 6.0;  // 30°
vector3D planeNormal{0.0, -std::sin(angleRad), std::cos(angleRad)};
planeNormal = planeNormal.normalized();

vector3D planePoint{0.0, beamHeight * 0.5, 1500.0};
double distance = planePoint.dot(planeNormal);

bool result = aFactory.getElementController()->cutElementWithPlane(beamID, planeNormal, distance);

Parameters:

• aElementId – [in] [elementID] The ID of the element to be cut.

• aCutPlaneNormalVector – [in] [vector3D] The normal vector of the cutting plane.

• aDistanceFromGlobalOrigin – [in] [double] The distance from the global origin to the cutting plane.

Returns:

[bool] True if the operation was successful, false otherwise.

virtual elementID createCircularMEP(double aDiameter, ICwAPI3DVertexList *aPoints) = 0

Creates a circular MEP (Mechanical, Electrical, and Plumbing) element.

Parameters:

• aDiameter – [in] [double] The diameter of the MEP element.

• aPoints – [in] [ICwAPI3DVertexList*] The points defining the path of the MEP element.

Returns:

[elementID] The ID of the created MEP element.

virtual elementID createRectangularMEP(double aWidth, double aDepth, ICwAPI3DVertexList *aPoints) = 0

Creates a rectangular MEP (Mechanical, Electrical, and Plumbing) element.

Parameters:

• aWidth – [in] [double] The width of the MEP element.

• aDepth – [in] [double] The depth of the MEP element.

• aPoints – [in] [ICwAPI3DVertexList*] The points defining the path of the MEP element.

Returns:

[elementID] The ID of the created MEP element.

virtual bool sliceElementWithPlane(elementID aElementId, vector3D aCutPlaneNormalVector, double aDistanceFromGlobalOrigin) = 0

Slices an element with a plane.

Example:

const double panelWidth = 1200.0;
const double panelThickness = 20.0;
const double panelLength = 2400.0;

// Create a panel to slice
vector3D origin{0.0, 0.0, 0.0};
vector3D xDir{1.0, 0.0, 0.0};
vector3D zDir{0.0, 0.0, 1.0};

elementID panelID = aFactory.getElementController()->createRectangularPanelVectors(
    panelWidth,
    panelThickness,
    panelLength,
    origin,
    xDir,
    zDir
);

// Define plane normal vector (45° in XY plane)
const double angleRad = M_PI / 4.0;
vector3D planeNormal{std::cos(angleRad), std::sin(angleRad), 0.0};
planeNormal = planeNormal.normalized();

// Calculate distance from origin to plane - slice through center of panel
vector3D panelCenter{panelLength * 0.5, panelWidth * 0.5, 0.0};
aFactory.getElementController()->createNode(panelCenter);  // Create a node at the center of the panel

double distance = panelCenter.dot(planeNormal);

// Verify plane equation: dot(point_on_plane, normal) = distance
// Any point on the plane should satisfy this equation

bool result = aFactory.getElementController()->sliceElementWithPlane(panelID, planeNormal, distance);

// Note: sliceElementWithPlane keeps both parts as a joined element

Parameters:

• aElementId – [in] [elementID] The ID of the element to be sliced.

• aCutPlaneNormalVector – [in] [vector3D] The normal vector of the slicing plane.

• aDistanceFromGlobalOrigin – [in] [double] The distance from the global origin to the slicing plane.

Returns:

[bool] True if the operation was successful, false otherwise.

virtual elementID createAutoContainerFromStandard(ICwAPI3DElementIDList *aElementIdList, const character *aOutputName, const character *aStandardElementName) = 0

Creates an auto container from a standard element.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be used in the auto container.

• aOutputName – [in] [const character*] The name of the output.

• aStandardElementName – [in] [const character*] The name of the standard element.

Returns:

[elementID] The ID of the created auto container.

virtual elementID createAutoExportSolidFromStandardWithReference(ICwAPI3DElementIDList *aElementIdList, const character *aOutputName, const character *aStandardElementName, elementID aReferenceID) = 0

Creates an auto export solid from a standard element with a reference.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be used in the auto export solid.

• aOutputName – [in] [const character*] The name of the output.

• aStandardElementName – [in] [const character*] The name of the standard element.

• aReferenceID – [in] [const character*] The ID of the reference element.

Returns:

[elementID] The ID of the created auto export solid.

virtual elementID createAutoContainerFromStandardWithReference(ICwAPI3DElementIDList *aElementIdList, const character *aOutputName, const character *aStandardElementName, elementID aReferenceID) = 0

Creates an auto container from a standard element with a reference.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be used in the auto container.

• aOutputName – [in] [const character*] The name of the output.

• aStandardElementName – [in] [const character*] The name of the standard element.

• aReferenceID – [in] [const character*] The ID of the reference element.

Returns:

[elementID] The ID of the created auto container.

virtual ICwAPI3DElementIDList *sliceElementWithPlaneAndGetNewElements(elementID aElementId, vector3D aCutPlaneNormalVector, double aDistanceFromGlobalOrigin) = 0

Slices an element with a plane and returns the new elements.

Example:

double beamWidth = 150.0;
double beamHeight = 300.0;
double beamLength = 4000.0;

// Create a beam to slice
elementID beamID = aFactory.getElementController()->createRectangularBeamVectors(
    beamWidth,
    beamHeight,
    beamLength,
    vector3D{0.0, 0.0, 0.0},
    vector3D{1.0, 0.0, 0.0},
    vector3D{0.0, 0.0, 1.0}
);

// Define a vertical cutting plane through the middle of the beam
vector3D planeNormal{1.0, 0.0, 0.0};  // Normal vector points along X-axis
// A point on the plane (midpoint of the beam)
vector3D planePoint{beamLength / 2.0, 0.0, 0.0};
double distance = planePoint.dot(planeNormal);  // Distance from origin to plane

// Verify with additional points on the plane
vector3D testPoint{beamLength / 2.0, 100.0, 200.0};
bool onPlane = std::abs(testPoint.dot(planeNormal) - distance) < 0.001;
printf("Test point is on plane: %s\n", onPlane ? "true" : "false");

// Slice the beam at the midpoint and get the resulting pieces
ICwAPI3DElementIDList* newElementIDs = aFactory.getElementController()->sliceElementsWithPlaneAndGetNewElements(
    beamID,
    planeNormal,
    distance
);

printf("Created %d new elements\n", newElementIDs->size());

// Visualization: different pen colors for the new elements
for (size_t i = 0; i < newElementIDs->size(); ++i)
{
    aFactory.getViewController()->setColor({newElementIDs->at(i)}, i + 5);
}

Parameters:

• aElementId – [in] [elementID] The ID of the element to be sliced.

• aCutPlaneNormalVector – [in] [vector3D] The normal vector of the cutting plane.

• aDistanceFromGlobalOrigin – [in] [double] The distance from the global origin to the cutting plane.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the new elements created by the slicing operation.

virtual elementID createSurface(ICwAPI3DVertexList *aSurfaceVertices) = 0

Creates a surface.

Example:

// Create a rectangular surface
ICwAPI3DVertexList vertices;

vertices.append(vector3D{0.0, 0.0, 0.0});
vertices.append(vector3D{1000.0, 0.0, 0.0});
vertices.append(vector3D{1000.0, 800.0, 0.0});
vertices.append(vector3D{0.0, 800.0, 0.0});

elementID surfaceID = aFactory.getElementController()->createSurface(&vertices);

Parameters:

aSurfaceVertices – [in] [ICwAPI3DVertexList*] The vertices of the surface.

Returns:

[elementID] The ID of the created surface.

virtual void convertCircularBeamToDrilling(ICwAPI3DElementIDList *aElementIdList) = 0

Converts circular/round beams into drillings.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

virtual ICwAPI3DStringList *getStandardExportSolidList() = 0

Retrieves a list of standard export solid names.

Returns:

[ICwAPI3DStringList*] A list of names of standard export solids.

virtual ICwAPI3DStringList *getStandardContainerList() = 0

Retrieves a list of standard container names.

Returns:

[ICwAPI3DStringList*] A list of names of standard containers.

virtual void stretchStartFace(ICwAPI3DElementIDList *aElementIdList, vector3D aStretchVector) = 0

Stretches the start face.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to strech.

• aStretchVector – [in] [vector3D] The stretch vector (direction and distance).

virtual void stretchEndFace(ICwAPI3DElementIDList *aElementIdList, vector3D aStretchVector) = 0

Stretches the end face.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to strech.

• aStretchVector – [in] [vector3D] The stretch vector (direction and distance).

virtual ICwAPI3DElementIDList *getVariantSiblingElementIDs(elementID aElementId) = 0

Retrieves a list of variant sibling element IDs.

Parameters:

aElementId – [in] [elementID] The ID of the element to retrieve variant siblings for.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of the variant sibling elements.

virtual void setExportSolidContents(elementID aExportSolidID, ICwAPI3DElementIDList *aElementIdList) = 0

Sets the contents of an export solid.

Parameters:

• aExportSolidID – [in] [elementID] The ID of the export solid to set the contents for.

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of element IDs to set as the contents of the export solid.

virtual void setContainerContents(elementID aContainerID, ICwAPI3DElementIDList *aElementIdList) = 0

Sets the contents of a container.

Parameters:

• aContainerID – [in] [elementID] The ID of the container to set the contents for.

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of element IDs to set as the contents of the container.

virtual void setParentOpeningVariantsOpeningAngle(ICwAPI3DElementIDList *aElementIdList, double aAngle) = 0

Sets the opening angle for parent opening variants.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of element IDs to set the opening angle for.

• aAngle – [in] [double] The opening angle to set.

virtual elementID createCircularAxisPoints(double aDiameter, vector3D aFirstPoint, vector3D aSecondPoint) = 0

Creates a circular axis using points.

Example :

double axisDiameter = 50.0;
vector3D axisStartPt{100.0, 100.0, 0.0};
vector3D axisEndPt{100.0, 100.0, 300.0};
elementID circularAxisID = aFactory.getElementController()->createCircularAxisPoints(axisDiameter, axisStartPt, axisEndPt);

Parameters:

• aDiameter – [in] [double] The diameter of the circular axis.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

Returns:

[elementID] The ID of the created circular axis.

virtual elementID createCircularAxisVector(double aDiameter, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal) = 0

Creates a circular axis using vectors.

Example :

double axisDiameter = 60.0;
double axisLength = 400.0;
vector3D axisStartPt{200.0, 200.0, 200.0};
vector3D axisDirection{0.0, 1.0, 0.0};
elementID circularAxisID = aFactory.getElementController()->createCircularAxisVector(axisDiameter, axisLength, axisStartPt, axisDirection);

Parameters:

• aDiameter – [in] [double] The diameter of the circular axis.

• aLength – [in] [double] The length of the circular axis.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

Returns:

[elementID] The ID of the created circular axis.

virtual void convertElementsToAuxiliaryElements(ICwAPI3DElementIDList *aElementIdList) = 0

Converts elements to auxiliary elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

virtual ICwAPI3DElementIDList *getElementsInContact(elementID aElement) = 0

Retrieves a list of elements in contact with a specific element.

Parameters:

aElement – [in] [elementID] The ID of the element to check for contact.

Returns:

[ICwAPI3DElementIDList*] The list of elements in contact with the specified element.

virtual ICwAPI3DFacetList *getFacetsWithLasso(ICwAPI3DElementIDList *aElementIdList) = 0

Retrieves the facets of elements within a lasso selection.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to check for facets within the lasso selection.

Returns:

[ICwAPI3DFacetList*] The list of facets within the lasso selection.

virtual void cutElementsWithOvermeasure(ICwAPI3DElementIDList *aHardElements, ICwAPI3DElementIDList *aSoftElements) = 0

Cuts elements with overmeasure.

Parameters:

• aHardElements – [in] [ICwAPI3DElementIDList*] The list of “hard” elements.

• aSoftElements – [in] [ICwAPI3DElementIDList*] The list of “soft” elements.

virtual ICwAPI3DEdgeList *getEdgeSelection(ICwAPI3DElementIDList *aElementIdList) = 0

Retrieves the edge selection of the provided elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to retrieve the edge selection from.

Returns:

[ICwAPI3DEdgeList*] The list of edges selected.

virtual elementID createPolygonPanel(ICwAPI3DVertexList *aPolygonVertices, double aThickness, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a polygon panel.

Example :

// Create a hexagonal panel
ICwAPI3DVertexList* vertices = aFactory.createVertexList();
double radius = 500.0;
int sides = 6;
for (int i = 0; i < sides; ++i)
{
    double angle = 2 * M_PI * i / sides;
    vertices->append(vector3D{radius * std::cos(angle), radius * std::sin(angle), 0.0});
}
vertices->append(vertices->at(0));  // Close the polygon
double panelThickness = 20.0;
vector3D extrusionVector{0.0, 0.0, 1.0};  // Normal direction
vector3D zVector{1.0, 0.0, 0.0};  // Orientation vector
elementID polygonPanelID = aFactory.getElementController()->createPolygonPanel(vertices, panelThickness, extrusionVector, zVector);

Parameters:

• aPolygonVertices – [in] The vertices of the polygon.

• aThickness – [in] [double] The thickness of the panel.

• aXDirectionLocal – [in] [vector3D] The X-axis direction of the panel.

• aZDirectionLocal – [in] [vector3D] The Z-axis direction of the panel.

Returns:

[elementID] The ID of the created polygon panel.

virtual void mirrorMoveElements(ICwAPI3DElementIDList *aElementIdList, vector3D aPlane, double aPlaneDistance) = 0

Moves elements by mirroring them across a plane.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to move.

• aPlane – [in] [vector3D] The plane to mirror the elements across.

• aPlaneDistance – [in] [double] The distance from the plane to move the elements.

virtual ICwAPI3DElementIDList *mirrorCopyElements(ICwAPI3DElementIDList *aElementIdList, vector3D aPlane, double aPlaneDistance) = 0

Copies elements by mirroring them across a plane.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to copy.

• aPlane – [in] [vector3D] The plane to mirror the elements across.

• aPlaneDistance – [in] [double] The distance from the plane to copy the elements.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the copied elements.

virtual void resetElementCadworkGuid(elementID aElementId) = 0

Sets the Cadwork Guid of an element to NULL.

Parameters:

aElementId – [in] [elementID] The id of the element to reset.

virtual ICwAPI3DStringList *getStandardBeamList() = 0

Retrieves a list of standard beam names.

Returns:

[ICwAPI3DStringList*] A list of names of standard beams.

virtual ICwAPI3DStringList *getStandardPanelList() = 0

Retrieves a list of standard panel names.

Returns:

[ICwAPI3DStringList*] A list of names of standard panels.

virtual elementID createStandardBeamPoints(const character *aStandardElementName, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a standard beam using points.

Example:

// Create a standard beam from the library using 3 points
const character* stdBeamName = L"Standard-Timber-120x240";  // Name from standard elements library

vector3D beamStartPt{0.0, 0.0, 0.0};
vector3D beamEndPt{0.0, 0.0, 3000.0};

vector3D lengthVector = (beamEndPt - beamStartPt).normalized();
vector3D refVector{1.0, 0.0, 0.0};
vector3D orientationVector = lengthVector.cross(refVector).normalized();

vector3D orientationPt = beamStartPt + orientationVector;

elementID stdBeamID = aFactory.getElementController()->createStandardBeamPoints(
    stdBeamName,
    beamStartPt,
    beamEndPt,
    orientationPt
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard beam.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created standard beam.

virtual elementID createStandardBeamVectors(const character *aStandardElementName, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a standard beam using vectors.

Example:

// Create a standard beam from the library using vectors
const character* stdBeamName = L"Standard-Timber-100x100";  // Name from standard elements library

double beamLength = 2500.0;
vector3D originPoint{100.0, 100.0, 100.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Direction along length
vector3D zDirection{0.0, 0.0, 1.0};  // Orientation vector

elementID stdBeamID = aFactory.getElementController()->createStandardBeamVectors(
    stdBeamName,
    beamLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard beam.

• aLength – [in] [double] The length of the beam.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created standard beam.

virtual elementID createStandardPanelPoints(const character *aStandardElementName, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a standard panel using points.

Example:

// Create a standard panel from the library using 3 points
const character* stdPanelName = L"Standard-Panel-27mm";  // Name from standard elements library

vector3D panelCornerPt{0.0, 0.0, 0.0};
vector3D panelWidthPt{1200.0, 0.0, 0.0};

// Calculate normal point for panel orientation (assuming Z is up)
vector3D panelNormal{0.0, 0.0, 1.0};
vector3D orientationPt = panelCornerPt + panelNormal;

elementID stdPanelID = aFactory.getElementController()->createStandardPanelPoints(
    stdPanelName,
    panelCornerPt,
    panelWidthPt,
    orientationPt
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard panel.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created standard panel.

virtual elementID createStandardPanelVectors(const character *aStandardElementName, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocalaXL, vector3D aZDirectionLocal) = 0

Creates a standard panel using vectors.

Example:

// Create a standard panel from the library using vectors
const character* stdPanelName = L"Standard-Panel-20mm";  // Name from standard elements library

double panelLength = 2400.0;
vector3D originPoint{0.0, 0.0, 0.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Direction along length
vector3D zDirection{0.0, 0.0, 1.0};  // Panel normal direction

elementID stdPanelID = aFactory.getElementController()->createStandardPanelVectors(
    stdPanelName,
    panelLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard panel.

• aLength – [in] [double] The length of the panel.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created standard panel.

virtual elementID createStandardSteelPoints(const character *aStandardElementName, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a standard steel element using points.

Example:

// Create a standard steel profile using start and end points
const character* stdSteelName = L"IPE 200";  // Name of standard steel profile from library

vector3D steelStartPt{0.0, 0.0, 500.0};
vector3D steelEndPt{3000.0, 0.0, 500.0};

vector3D lengthVector = (steelEndPt - steelStartPt).normalized();
vector3D upVector{0.0, 0.0, 1.0};
vector3D sideVector = lengthVector.cross(upVector).normalized();

vector3D orientationPt = steelStartPt + upVector;

elementID steelID = aFactory.getElementController()->createStandardSteelPoints(
    stdSteelName,
    steelStartPt,
    steelEndPt,
    orientationPt
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard steel element.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created standard steel element.

virtual elementID createStandardSteelVectors(const character *aStandardElementName, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a standard steel element using vectors.

Example:

// Create a standard steel profile using length and direction vectors
const character* stdSteelName = L"HEA 220";  // Name of standard steel profile from library

double steelLength = 4500.0;
vector3D originPoint{200.0, 0.0, 200.0};
vector3D xDirection{0.0, 1.0, 0.0};  // Direction along Y axis
vector3D zDirection{0.0, 0.0, 1.0};  // Up direction

elementID steelID = aFactory.getElementController()->createStandardSteelVectors(
    stdSteelName,
    steelLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aStandardElementName – [in] [const character*] The name of the standard steel element.

• aLength – [in] [double] The length of the steel element.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created standard steel element.

virtual void moveElementWithUndo(ICwAPI3DElementIDList *aElementIdList, vector3D aMoveVector) = 0

Moves an element with undo functionality.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to move.

• aMoveVector – [in] [vector3D] The vector by which to move the elements.

virtual elementID createLinearOptimization(ICwAPI3DElementIDList *aElementIdList, uint32_t aOptimizationNumber, double aTotalLength, double aStartCut, double aEndCut, double aSawKerf, bool aIsProductionList) = 0

Creates a linear optimization.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be optimized.

• aOptimizationNumber – [in] [uint32_t] The optimization number, nested parent element id.

• aTotalLength – [in] [double] The total length for the optimization.

• aStartCut – [in] [double] The start cut for the optimization.

• aEndCut – [in] [double] The end cut for the optimization.

• aSawKerf – [in] [double] The saw kerf for the optimization.

• aIsProductionList – [in] [bool] A flag indicating if this is a production list.

Returns:

[elementID] The ID of the created linear optimization.

virtual ICwAPI3DElementIDList *checkElementDuplicates(ICwAPI3DElementIDList *aElementIdList) = 0

Checks for duplicate elements in the provided list.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to check for duplicates.

Returns:

[ICwAPI3DElementIDList*] The list of duplicate elements.

virtual elementID createNormalAxisPoints(vector3D aFirstPoint, vector3D aSecondPoint) = 0

Creates a normal axis using points.

Example :

vector3D axisStartPt{0.0, 0.0, 0.0};
vector3D axisEndPt{0.0, 0.0, 2000.0};
elementID axisID = aFactory.getElementController()->createNormalAxisPoints(axisStartPt, axisEndPt);

Parameters:

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

Returns:

[elementID] The ID of the created normal axis.

virtual elementID createNormalAxisVectors(double aLength, vector3D aAxisStartingPoint, vector3D aAxisDirection) = 0

Creates a normal axis using vectors.

Example :

double axisLength = 1500.0;
vector3D axisStartPt{200.0, 200.0, 0.0};
vector3D axisDirection{1.0, 0.0, 0.0};  // Direction along X axis
elementID axisID = aFactory.getElementController()->createNormalAxisVectors(axisLength, axisStartPt, axisDirection);

Parameters:

• aLength – [in] [double] The length of the axis.

• aAxisStartingPoint – [in] [vector3D] The starting point of the axis.

• aAxisDirection – [in] [vector3D] The direction of the axis.

Returns:

[elementID] The ID of the created normal axis.

virtual void convertBoltToStandardConnector(ICwAPI3DElementIDList *aElementIdList, const character *aStandardElementName) = 0

Converts bolts to standard connectors.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of bolts to be converted.

• aStandardElementName – [in] [const character*] The name of the standard element.

virtual elementID getReferenceElement(elementID aElement) = 0

Retrieves the reference element for a given element.

Parameters:

aElement – [in] [elementID] The ID of the element for which to retrieve the reference.

Returns:

[elementID] The ID of the reference element.

virtual elementID extrudeSurfaceToAuxiliaryVector(elementID aSurface, vector3D aExtrudeDirection) = 0

Extrudes a surface to create an auxiliary element.

Parameters:

• aSurface – [in] [elementID] The ID of the surface to be extruded.

• aExtrudeDirection – [in] [vector3D] The vector along which to extrude the surface.

Returns:

[elementID] The ID of the created auxiliary element.

virtual elementID extrudeSurfaceToPanelVector(elementID aSurface, vector3D aExtrudeDirection) = 0

Extrudes a surface to create a panel element.

Parameters:

• aSurface – [in] [elementID] The ID of the surface to be extruded.

• aExtrudeDirection – [in] [vector3D] The vector along which to extrude the surface.

Returns:

[elementID] The ID of the created panel element.

virtual elementID extrudeSurfaceToBeamVector(elementID aSurface, vector3D aExtrudeDirection) = 0

Extrudes a surface to create a beam element.

Parameters:

• aSurface – [in] [elementID] The ID of the surface to be extruded.

• aExtrudeDirection – [in] [vector3D] The vector along which to extrude the surface.

Returns:

[elementID] The ID of the created beam element.

virtual bool checkIfPointIsInElement(vector3D aPoint, elementID aElementID) = 0

Checks if a point is inside an element.

Parameters:

• aPoint – [in] [vector3D] The point to check.

• aElementID – [in] [elementID] The ID of the element to check against.

Returns:

[bool] True if the point is inside the element, false otherwise.

virtual bool checkIfPointIsOnElement(vector3D aPoint, elementID aElementID) = 0

Checks if a point is on an element.

Parameters:

• aPoint – [in] [vector3D] The point to check.

• aElementID – [in] [elementID] The ID of the element to check against.

Returns:

[bool] True if the point is on the element, false otherwise.

virtual void convertContainerToContainerBlock(ICwAPI3DElementIDList *aElementIdList) = 0

Converts a container to a container block.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

virtual elementID createBoundingBoxLocal(elementID aReferenceElementId, ICwAPI3DElementIDList *aElementIdList) = 0

Creates a local bounding box for a list of elements relative to a reference element.

Parameters:

• aReferenceElementId – [in] [elementID] The ID of the reference element.

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to create the bounding box.

Returns:

[elementID] The ID of the created bounding box.

virtual elementID createBoundingBoxGlobal(ICwAPI3DElementIDList *aElementIdList) = 0

Creates a global bounding box for a list of elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to create the bounding box.

Returns:

[elementID] The ID of the created bounding box.

virtual void cutLogCornerJoint(const character *aSettingsName, ICwAPI3DElementIDList *aElementIdList) = 0

Cuts a log corner joint.

Parameters:

• aSettingsName – [in] [const character*] The name of the settings to be used for the cut.

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

virtual void convertAuxiliaryToPanel(ICwAPI3DElementIDList *aElementIdList) = 0

Converts auxiliary elements to panels.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of auxiliary elements to be converted.

virtual void convertAuxiliaryToBeam(ICwAPI3DElementIDList *aElementIdList) = 0

Converts auxiliary elements to beams.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of auxiliary elements to be converted.

virtual void autoSetRoughVolumeSituation(ICwAPI3DElementIDList *aElementIdList) = 0

Automatically sets the rough volume situation for a list of elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to set the rough volume situation.

virtual void roughVolumeSituationManual(elementID aCover, ICwAPI3DElementIDList *aAddPartner, ICwAPI3DElementIDList *aRemovePartner) = 0

Manually sets the rough volume situation for a cover element.

Parameters:

• aCover – [in] [elementID] The ID of the cover element.

• aAddPartner – [in] [ICwAPI3DElementIDList*] The list of partner elements to be added.

• aRemovePartner – [in] [ICwAPI3DElementIDList*] The list of partner elements to be removed.

virtual void autoSetPartsSituation(ICwAPI3DElementIDList *aElementIdList) = 0

Automatically sets the parts situation for a list of elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to set the parts situation.

virtual void partsSituationManual(elementID aCover, ICwAPI3DElementIDList *aAddChilds, ICwAPI3DElementIDList *aRemoveChilds) = 0

Manually sets the parts situation for a cover element.

Parameters:

• aCover – [in] [elementID] The ID of the cover element.

• aAddChilds – [in] [ICwAPI3DElementIDList*] The list of child elements to be added.

• aRemoveChilds – [in] [ICwAPI3DElementIDList*] The list of child elements to be removed.

virtual ICwAPI3DElementIDList *activateRvWithoutSituation() = 0

Activates the rough volume situation for elements without a situation.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the elements for which the rough volume situation was activated.

virtual ICwAPI3DElementIDList *activatePartsWithoutSituation() = 0

Activates the parts situation for elements without a situation.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the elements for which the parts situation was activated.

virtual void addElementToDetail(ICwAPI3DElementIDList *aElementIdList, int32_t aDetail) = 0

Adds elements to a detail.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be added to the detail.

• aDetail – [in] [int32_t] The ID of the detail.

virtual ICwAPI3DVertexList *getBoundingBoxVerticesLocal(elementID aReferenceElementId, ICwAPI3DElementIDList *aElementIdList) = 0

Retrieves the local bounding box vertices for a list of elements relative to a reference element.

Parameters:

• aReferenceElementId – [in] [elementID] The ID of the reference element.

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to retrieve the bounding box vertices.

Returns:

[ICwAPI3DVertexList*] A list of vertices representing the local bounding box of the elements.

virtual ICwAPI3DVertexList *getBoundingBoxVerticesGlobal(ICwAPI3DElementIDList *aElementIdList) = 0

Retrieves the global bounding box vertices for a list of elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements for which to retrieve the bounding box vertices.

Returns:

[ICwAPI3DVertexList*] A list of vertices representing the global bounding box of the elements.

virtual ICwAPI3DElementIDList *getAllNestingRawParts() = 0

Retrieves a list of all raw parts in a nesting operation.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of all raw parts in a nesting operation.

virtual ICwAPI3DElementIDList *subtractElementsWithUndo(ICwAPI3DElementIDList *aHardElements, ICwAPI3DElementIDList *aSoftElements, bool aWithUndo) = 0

Subtracts a list of “soft” elements from a list of “hard” elements with undo functionality.

Parameters:

• aHardElements – [in] [ICwAPI3DElementIDList*] The list of “hard” elements.

• aSoftElements – [in] [ICwAPI3DElementIDList*] The list of “soft” elements.

• aWithUndo – [in] [bool] Indicate whether the operation should be added to the undo stack.

Returns:

[ICwAPI3DElementIDList*] The list of elements resulting from the subtraction.

virtual void startElementModuleCalculationSilently(ICwAPI3DElementIDList *aCoverIdList) = 0

Starts the calculation of the element module for a list of covers silently (without user interaction).

Parameters:

aCoverIdList – [in] [ICwAPI3DElementIDList*] The list of covers for which to start the element module calculation.

virtual ICwAPI3DElementIDList *getJoinedElements(elementID aElementID) = 0

Retrieves the IDs of elements that have been joined with the specified element.

Parameters:

aElementID – [in] [elementID] The ID of the element.

Returns:

[ICwAPI3DElementIDList*] A list of IDs of the joined elements.

virtual ICwAPI3DElementIDList *replacePhysicalDrillingsWithDrillingAxes(ICwAPI3DElementIDList *aElementIdList, double aMininumDiameter, double aMaximumDiameter) = 0

Replaces physical drillings with drilling axes based on diameter range.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be processed.

• aMininumDiameter – [in] [double] The minimum diameter of the drilling.

• aMaximumDiameter – [in] [double] The maximum diameter of the drilling.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the elements where the replacement was successful.

virtual void cutElementWithProcessingGroup(elementID aSoftElement, elementID aProcessing) = 0

Cuts an element with a processing group.

Parameters:

• aSoftElement – [in] [elementID] The ID of the element to be cut.

• aProcessing – [in] [elementID] The ID of the processing group.

virtual elementID createTextObjectWithOptions(vector3D aPosition, vector3D aXDirectionLocal, vector3D aZDirectionLocal, ICwAPI3DTextObjectOptions *aTextOptions) = 0

Creates a text object with specific options.

Example:

vector3D textPosition{0.0, 0.0, 0.0};
vector3D xDirection{1.0, 0.0, 0.0};  // Text direction
vector3D zDirection{0.0, 0.0, 1.0};  // Text orientation

ICwAPI3DTextObjectOptions options;
options.setText(L"Advanced Text");
options.setHeight(200.0);
options.setFontName(L"Verdana");
options.setBold(true);

elementID textID = aFactory.getElementController()->createTextObjectWithOptions(
    textPosition,
    xDirection,
    zDirection,
    &options
);

Parameters:

• aPosition – [in] The position of the text object.

• aXDirectionLocal – [in] [vector3D] The X-axis direction of the text object.

• aZDirectionLocal – [in] [vector3D] The Z-axis direction of the text object.

• aTextOptions – [in] [ICwAPI3DTextObjectOptions*] The options for the text object.

Returns:

[elementID] The ID of the created text object.

virtual elementID createStandardElementFromGuidPoints(const character *aGuid, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a standard element from GUID points.

Parameters:

• aGuid – [in] [const character*] The GUID of the standard element.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created standard element.

virtual elementID createStandardElementFromGuidVectors(const character *aGuid, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a standard element from GUID vectors.

Parameters:

• aGuid – [in] [const character*] The GUID of the standard element.

• aLength – [in] [double] The length of the standard element.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created standard element.

virtual void filletEdge(elementID aElementID, vector3D aEdgeStart, vector3D aEdgeEnd, double aRadius) = 0

Fillets an edge of an element.

Parameters:

• aElementID – [in] [elementID] The ID of the element.

• aEdgeStart – [in] [vector3D] The starting point of the edge.

• aEdgeEnd – [in] [vector3D] The ending point of the edge.

• aRadius – [in] [double] The radius of the fillet.

virtual void chamferEdge(elementID aElementID, vector3D aEdgeStart, vector3D aEdgeEnd, double aLength) = 0

Chamfers an edge of an element.

Parameters:

• aElementID – [in] [elementID] The ID of the element.

• aEdgeStart – [in] [vector3D] The starting point of the edge.

• aEdgeEnd – [in] [vector3D] The ending point of the edge.

• aLength – [in] [double] The length of the chamfer.

virtual void convertDrillingToCircularBeam(ICwAPI3DElementIDList *aElementIdList) = 0

Converts drillings to circular beams.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

virtual ICwAPI3DElementIDList *convertLinesToSurfaces(ICwAPI3DElementIDList *aElementIdList) = 0

Converts lines to surfaces.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

Returns:

[ICwAPI3DElementIDList*] The list of IDs of the created surfaces.

virtual elementID convertSurfacesToVolume(ICwAPI3DElementIDList *aElementIdList) = 0

Converts surfaces to a volume.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

Returns:

[elementID] The ID of the created volume.

virtual void cutCornerLap(ICwAPI3DElementIDList *aElementIdList, double aDepth, double aClearanceBase, double aClearanceSide, double aBackcut, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a corner-lap joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aDepth – [in] [double] The vertical depth of the lap cut applied to each element.

• aClearanceBase – [in] [double] Additional clearance applied at the bottom (base) of the lap cut for fitting tolerance.

• aClearanceSide – [in] [double] Additional clearance on the side faces of the cut to prevent tight joints or interference.

• aBackcut – [in] [double] A small offset or undercut applied to the outer face of the cut to improve fit or reduce friction during assembly.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual void cutTLap(ICwAPI3DElementIDList *aElementIdList, double aDepth, double aClearanceBase, double aClearanceSide, double aBackcut, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a T-lap joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aDepth – [in] [double] The vertical depth of the cut where the intersecting element will be placed.

• aClearanceBase – [in] [double] Additional clearance at the base (bottom) of the cut to ensure a proper fit.

• aClearanceSide – [in] [double] Additional clearance on the side faces of the cut to avoid tight fitting.

• aBackcut – [in] [double] A small offset or undercut applied inward to improve fitting during assembly.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual void cutCrossLap(ICwAPI3DElementIDList *aElementIdList, double aDepth, double aClearanceBase, double aClearanceSide, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a cross-lap joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aDepth – [in] [double] The vertical depth of the cross-lap cut, typically half the thickness of the material.

• aClearanceBase – [in] [double] Additional clearance at the bottom of the cut to ensure a proper fit between intersecting elements.

• aClearanceSide – [in] [double] Additional clearance on the side walls of the cut to prevent tight fits or friction.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual ICwAPI3DElementIDList *deleteProcessesKeepCuttingBodies(ICwAPI3DElementIDList *aElementIdList, bool aKeepCuttingElementsOnly) = 0

Gets the cutting bodies of all processes (and deletes processes), like Ctrl+D Action.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The elements to process.

• aKeepCuttingElementsOnly – [in] [bool] True if the return element id contains only cutting elements, false otherwise.

Returns:

[ICwAPI3DElementIDList*] The id list of all removed geometry, cuttings bodies.

virtual void cutDoubleTenon(ICwAPI3DElementIDList *aElementIdList, double aDepth1, double aDepth2, double aClearance, double aBackcut, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a double tenon joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aDepth1 – [in] [double] The depth of the first tenon shoulder.

• aDepth2 – [in] [double] The depth of the second tenon shoulder.

• aClearance – [in] [double] Additional clearance applied around the tenons for fitting tolerance during assembly.

• aBackcut – [in] [double] A small undercut or inward offset to ensure the tenons fit without surface interference.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual ICwAPI3DCoordinateSystemData *getCoordinateSystemDataNestingChild(elementID aNestingParentId, elementID aNestingChildId) = 0

Get the coordinate system of nesting child.

Parameters:

• aNestingParentId – [in] [elementID] The nesting parent id.

• aNestingChildId – [in] [elementID] The nesting child id.

Returns:

[ICwAPI3DCoordinateSystemData*] A global element coordinate-system of the nested child element consisting of a Point1, a Point2 and a Point3. You can get the local placement by subtracting the parent coordinate - system with child coordinate - system.

virtual void cutHalfLap(ICwAPI3DElementIDList *aElementIdList, double aLength, double aClearanceLength, double aClearanceDepth, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a half-lap joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aLength – [in] [double] The length of the half-lap joint along the main axis of the elements.

• aClearanceLength – [in] [double] Additional clearance along the length of the cut to ensure proper fitting.

• aClearanceDepth – [in] [double] Additional clearance in the depth direction to avoid tight joints or surface interference.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual void cutSimpleScarf(ICwAPI3DElementIDList *aElementIdList, double aLength, double aDepth, double aClearanceLength, double aClearanceDepth, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a simple scarf joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aLength – [in] [double] The distance between the two starting points of the cut.

• aDepth – [in] [double] The vertical depth of the initial straight cut before the diagonal cut begins.

• aClearanceLength – [in] [double] The additional length clearance applied along the initial (depth) cut.

• aClearanceDepth – [in] [double] The additional depth clearance applied along the diagonal cut.

• aDrillingCount – [in] [uint64_t] The number of drill holes to be created for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size, typically for fitting the bolt head or allowing easier assembly.

virtual void cutDiagonalCut(ICwAPI3DElementIDList *aElementIdList, double aLength, double aClearanceLength, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a diagonal cut joint with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be cut.

• aLength – [in] [double] The total length of the diagonal cut applied along the element.

• aClearanceLength – [in] [double] Additional clearance along the cut length to ensure proper fitting between elements.

• aDrillingCount – [in] [uint64_t] The number of drill holes to create for fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] The tolerance applied to the hole size for bolt head clearance or easier insertion.

virtual void convertSurfacesToRoofSurfaces(ICwAPI3DElementIDList *aElementIdList, const character *aRoofName) = 0

converts surfaces to roof surfaces

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be converted.

• aRoofName – [in] [const character*] The roof name.

virtual ICwAPI3DString *startStandardElementDialog(standardElementType aStandardElementType) = 0

Starts the standard element dialogue based on the chosen element type.

Parameters:

aStandardElementType – [in] [standardElementType] The chosen element type.

Returns:

[ICwAPI3DString*] The guid of selected standard element if item is valid, else null.

virtual void removeStandardConnectorAxis(const character *aGuid) = 0

Removes a standard connector axis.

Parameters:

aGuid – [in] [const character*] The unique identifier of the standard connector axis to be removed.

virtual void removeStandardBeam(const character *aGuid) = 0

Removes a standard beam.

Parameters:

aGuid – [in] [const character*] The unique identifier of the standard beam to be removed.

virtual void removeStandardPanel(const character *aGuid) = 0

Removes a standard panel.

Parameters:

aGuid – [in] [const character*] The unique identifier of the standard panel to be removed.

virtual void removeStandardContainer(const character *aGuid) = 0

Removes a standard container.

Parameters:

aGuid – [in] [const character*] The unique identifier of the standard container to be removed.

virtual void removeStandardExportSolid(const character *aGuid) = 0

Removes a standard export solid.

Parameters:

aGuid – [in] [const character*] The unique identifier of the standard export solid to be removed.

virtual ICwAPI3DElementIDList *getUserElementIDsWithCount(uint64_t aCount) = 0

Retrieves a list of user element IDs.

Parameters:

aCount – [in] [uint64_t] The maximal number of elements to select.

Returns:

[ICwAPI3DElementIDList*] The list of user element IDs.

virtual void cutScarfStraight(ICwAPI3DElementIDList *aElementIdList, double aLength, double aDepth, double aClearanceLength, double aClearanceDepth, double aClearanceHook, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a straight scarf joint (lengthwise) with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to apply the scarf cut to.

• aLength – [in] [double] The total length of the scarf joint cut, measured along the element’s longitudinal axis.

• aDepth – [in] [double] The depth of the vertical cut where both side join.

• aClearanceLength – [in] [double] Additional clearance along the length direction to ensure proper fitting of the joint.

• aClearanceDepth – [in] [double] Additional clearance in the depth direction to avoid tight fits or interference.

• aClearanceHook – [in] [double] Clearance added specifically at the hook or notch feature of the joint, if any.

• aDrillingCount – [in] [uint64_t] The number of holes to be drilled, typically for bolts, pegs, or dowels to reinforce the joint.

• aDrillingDiameter – [in] [double] The diameter of each drilled hole.

• aDrillingTolerance – [in] [double] The tolerance added to the hole size for easier assembly or bolt head fitting.

virtual void cutScarfDiagonal(ICwAPI3DElementIDList *aElementIdList, double aLength, double aDepth, double aClearanceLength, double aClearanceDepth, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a diagonal scarf joint (lengthwise) with specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements on which the diagonal scarf cut will be applied.

• aLength – [in] [double] The total length of the scarf joint measured along the element’s axis.

• aDepth – [in] [double] The vertical depth of the initial straight section before the diagonal cut begins.

• aClearanceLength – [in] [double] Additional clearance along the length direction to facilitate proper fitting of the joint.

• aClearanceDepth – [in] [double] Additional clearance along the depth direction to avoid tight joints or misalignment.

• aDrillingCount – [in] [uint64_t] The number of drill holes for mechanical fasteners (e.g., bolts or dowels).

• aDrillingDiameter – [in] [double] The diameter of each drill hole.

• aDrillingTolerance – [in] [double] Tolerance added to the hole diameter for ease of insertion or head fit.

virtual void cutScarfWithWedge(ICwAPI3DElementIDList *aElementIdList, double aLength, double aDepth, double aClearanceLength, double aClearanceDepth, double aWedgeWidth, uint64_t aDrillingCount, double aDrillingDiameter, double aDrillingTolerance) = 0

Cuts a diagonal scarf joint with an added wedge, using specific parameters.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements on which to apply the scarf-with-wedge cut.

• aLength – [in] [double] The total length of the scarf joint, measured along the main axis of the element.

• aDepth – [in] [double] The vertical depth of the straight portion of the cut before the diagonal section.

• aClearanceLength – [in] [double] Additional clearance along the length direction for proper fit of the joint.

• aClearanceDepth – [in] [double] Additional clearance in the depth direction to avoid interference.

• aWedgeWidth – [in] [double] The width of the wedge feature inserted or carved as part of the joint geometry.

• aDrillingCount – [in] [uint64_t] The number of drill holes used to secure the joint (e.g., for bolts, pegs, or dowels).

• aDrillingDiameter – [in] [double] The diameter of the drilled holes.

• aDrillingTolerance – [in] [double] Tolerance applied to the hole size, often used for easier bolt fitting or head clearance.

virtual void cutBeamEndProfile(ICwAPI3DElementIDList *aElementIdList, const character *aProfileName, bool aOnStartFace, bool aOnEndFace) = 0

adds end profiles to a beam with the given name

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be modified

• aProfileName – [in] [const character*] The name of the profile.

• aOnStartFace – [in] [bool] Cut on the start face ?

• aOnEndFace – [in] [bool] Cut on the end face ?

virtual elementID createTruncatedConeBeamPoints(double aStartDiameter, double aEndDiameter, vector3D aFirstPoint, vector3D aSecondPoint, vector3D aThirdPoint) = 0

Creates a truncated cone beam using points.

Example:

double startDia = 200.0;
double endDia = 150.0;
vector3D coneStartPt{0.0, 0.0, 0.0};
vector3D coneEndPt{0.0, 0.0, 3000.0};

// Calculate orientation point
vector3D lengthVector = (coneEndPt - coneStartPt).normalized();
vector3D refVector{1.0, 0.0, 0.0};
vector3D orientationVector = lengthVector.cross(refVector).normalized();
vector3D orientationPt = coneStartPt + orientationVector;

elementID coneID = aFactory.getElementController()->createTruncatedConeBeamPoints(
    startDia,
    endDia,
    coneStartPt,
    coneEndPt,
    orientationPt
);

Parameters:

• aStartDiameter – [in] [double] The starting diameter of the beam.

• aEndDiameter – [in] [double] The ending diameter of the beam.

• aFirstPoint – [in] [vector3D] The first point.

• aSecondPoint – [in] [vector3D] The second point.

• aThirdPoint – [in] [vector3D] The third point.

Returns:

[elementID] The ID of the created beam.

virtual elementID createTruncatedConeBeamVectors(double aStartDiameter, double aEndDiameter, double aLength, vector3D aStartingPoint, vector3D aXDirectionLocal, vector3D aZDirectionLocal) = 0

Creates a truncated cone beam using vectors.

Example:

double startDia = 120.0;
double endDia = 80.0;
double coneLength = 2500.0;
vector3D originPoint{0.0, 0.0, 0.0};
vector3D xDirection{0.0, 0.0, 1.0};  // Direction along Z axis
vector3D zDirection{1.0, 0.0, 0.0};  // Orientation vector

elementID coneID = aFactory.getElementController()->createTruncatedConeBeamVectors(
    startDia,
    endDia,
    coneLength,
    originPoint,
    xDirection,
    zDirection
);

Parameters:

• aStartDiameter – [in] [double] The starting diameter of the beam.

• aEndDiameter – [in] [double] The ending diameter of the beam.

• aLength – [in] [double] The length of the beam.

• aStartingPoint – [in] [vector3D] The starting point.

• aXDirectionLocal – [in] [vector3D] The direction of the X-axis.

• aZDirectionLocal – [in] [vector3D] The direction of the Z-axis.

Returns:

[elementID] The ID of the created beam.

virtual elementID createSplineLine(ICwAPI3DVertexList *aSplinePoints) = 0

Creates a spline line using a list of points.

Parameters:

aSplinePoints – [in] [ICwAPI3DVertexList*] The points of the line.

Returns:

[elementID] The ID of the created line.

// Create a spline through multiple points
ICwAPI3DVertexList* points = aFactory.createVertexList();
points->append(vector3D{0.0, 0.0, 0.0});
points->append(vector3D{500.0, 200.0, 0.0});
points->append(vector3D{1000.0, 0.0, 200.0});
points->append(vector3D{1500.0, -100.0, 100.0});

elementID splineID = aFactory.getElementController()->createSplineLine(points);

virtual bool unjoinElements(ICwAPI3DElementIDList *aElementIdList) = 0

Unjoins the specified elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements to be unjoined.

Returns:

[bool] True if the operation was successful, false if an error occured.

virtual bool unjoinTopLevelElements(ICwAPI3DElementIDList *aElementIdList) = 0

Unjoins the specified top-level elements.

Parameters:

aElementIdList – [in] [ICwAPI3DElementIDList*] The list of top-level elements to be unjoined.

Returns:

[bool] True if the operation was successful, false if an error occured.

virtual void setElementGroupSingleSelectMode() = 0

Switches the current element group selection mode so that single elements of a group are selectable.

virtual void setElementGroupMultiSelectMode() = 0

Switches the current element group selection mode so that all elements of a group are selected when selecting one of it.

virtual ICwAPI3DElementIDList *getElementsInCollision(elementID aElementId) = 0

Retrieves a list of elements in collision with a specific element.

Parameters:

aElementId – [in] [elementID] The ID of the element to check for collision.

Returns:

[ICwAPI3DElementIDList*] The list of elements in collision with the specified element.

virtual ICwAPI3DTextObjectOptions *getTextObjectOptions(elementID aElementId) = 0

Retrieve the data of a text object, e.g. font, text content, etc.

Parameters:

aElementId – [in] [elementID] The ID of a Text Object.

Returns:

[ICwAPI3DTextObjectOptions*]

virtual bool getIsElementGroupSingleSelectMode() = 0

Gets whether the current element group selection mode is setup to select single elements.

Returns:

[bool] True if the current element group selection mode is setup to select single elements, false otherwise.

virtual bool getIsElementGroupMultiSelectMode() = 0

Gets whether the current element group selection mode is setup to select groups when a grouped element is selected.

Returns:

[bool] True if the current element group selection mode is setup to select groups when a grouped element is selected, false otherwise.

virtual bool applyImageToSurface(elementID aElement, const character *aImageFilePath, vector3D aAlignmentStart, vector3D aAlignmentEnd) = 0

Applies an image texture to a specified surface element. This function allows you to set an image as a texture on a given surface element. The image is mapped to the surface between two specified points that define the alignment and scaling.

Note

Ensure that the file path is valid and accessible, and that the surface element exists Proper error handling for invalid inputs is recommended.

Parameters:

• aElement – [in] [elementID] Surface element

• aImageFilePath – [in] [const character*] The file path to the image to be applied. Supported formats include .jpg, .png, .bmp, and .tif. Path example: LR"(C:/path/to/Image.png)".

• aAlignmentStart – [in] [vector3D] The starting alignment point for mapping the image on the surface.

• aAlignmentEnd – [in] [vector3D] The ending alignment point for mapping the image on the surface.

Returns:

[bool] Returns true if the image was successfully applied to the surface; otherwise, returns false in case of failure. Failures can occur due to invalid file paths, unsupported formats, or issues with the surface element.

virtual void setShoulderOptions(ICwAPI3DShoulderOptions *aOptions) = 0

Sets shoulder cut options.

Parameters:

aOptions – [in] [ICwAPI3DShoulderOptions*] The shoulder options.

virtual void setHeelShoulderOptions(ICwAPI3DHeelShoulderOptions *aOptions) = 0

Sets heel shoulder cut options.

Parameters:

aOptions – [in] [ICwAPI3DHeelShoulderOptions*] The heel shoulder options.

virtual void setDoubleShoulderOptions(ICwAPI3DDoubleShoulderOptions *aOptions) = 0

Sets double shoulder cut options.

Parameters:

aOptions – [in] [ICwAPI3DDoubleShoulderOptions*] The double shoulder options.

virtual void cutShoulder(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementIDList *aConnectingElementIDList) = 0

Cuts shoulder with current 3D options.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements where the shoulder cut will be applied.

• aConnectingElementIDList – [in] [ICwAPI3DElementIDList*] The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.

virtual void cutHeelShoulder(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementIDList *aConnectingElementIDList) = 0

Cuts heel shoulder with current 3D options.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements where the heel shoulder cut will be applied.

• aConnectingElementIDList – [in] [ICwAPI3DElementIDList*] The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.

virtual void cutDoubleShoulder(ICwAPI3DElementIDList *aElementIdList, ICwAPI3DElementIDList *aConnectingElementIDList) = 0

Cuts a double shoulder joint using the current 3D cutting options.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] The list of elements where the double shoulder cut will be applied.

• aConnectingElementIDList – [in] [ICwAPI3DElementIDList*] The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.

virtual ICwAPI3DHitResult *castRayAndGetElementIntersections(ICwAPI3DElementIDList *aElementIdList, vector3D aRayStartPosition, vector3D aRayEndPosition, double aRadius) = 0

Casts a ray through the 3D model and calculates all intersection points between the ray and specified elements. This function performs ray casting against each specified element to find intersection points. For each element hit by the ray, it returns the element ID and all points where the ray intersects with that element. The ray is defined by a start point, end point, and radius.

Example :

ICwAPI3DElementIDList* activeElements = aFactory.getElementController()->getActiveIdentifiableElementIDs();
vector3D rayStart{0, 0, 0};
vector3D rayEnd{1000, 0, 0};
ICwAPI3DRayHitResult* hits = aFactory.getElementController()->castRayAndGetElementIntersections(activeElements, rayStart, rayEnd, 40.0);
ICwAPI3DElementIDList* hitElementIDs = hits->getHitElementIDs();
for (int i = 0; i < hitElementIDs->size(); ++i)
{
    elementID* element = hitElementIDs->at(i);
    printf("ElementID %d:\n", *element);
    ICwAPI3DVertexList* hitVertices = hits->getHitVerticesByElement(*element);
    for (int j = 0; j < hitVertices->size(); ++j)
    {
        const vector3D& pos = hitVertices->at(j);
        aFactory.getElementController()->createNode(pos);
    }
}

Note

The ray direction is calculated as the normalized vector from aRayStart to aRayEnd.

Parameters:

• aElementIdList – [in] [ICwAPI3DElementIDList*] List of element IDs to test against the ray.

• aRayStartPosition – [in] [vector3D] 3D start point of the ray.

• aRayEndPosition – [in] [vector3D] 3D end point of the ray.

• aRadius – [in] [double] Radius of the ray cylinder (allows testing against a volume rather than just a line).

Returns:

[ICwAPI3DHitResult*] Contains list of elements that were hit by the ray and list of vertices that are queried via ElementID.

virtual ICwAPI3DShoulderOptions *getShoulderOptions() = 0

Gets shoulder cut options.

Returns:

Shoulder options

virtual ICwAPI3DHeelShoulderOptions *getHeelShoulderOptions() = 0

Gets heel shoulder cut options.

Returns:

Heel shoulder options

virtual ICwAPI3DDoubleShoulderOptions *getDoubleShoulderOptions() = 0

Gets double shoulder cut options.

Returns:

Double shoulder options

virtual activePointResult getElementActivePoint(elementID aElementID) = 0

Gets the active point of an element.

Parameters:

aElementID – [in] The ID of the element to query.

Returns:

The active point result containing the active point information.

virtual ICwAPI3DStringList *getStandardBeamGuidList() = 0

Retrieves a list of standard beam GUIDs.

Returns:

[ICwAPI3DStringList*] A list of guids of standard beams.

virtual ICwAPI3DStringList *getStandardPanelGuidList() = 0

Retrieves a list of standard panel GUIDs.

Returns:

[ICwAPI3DStringList*] A list of guids of standard panels.

virtual void importStandardBeamFromFile(const character *aFilePath) = 0

Imports a standard beam from a file.

Parameters:

aFilePath – [in] The path to the file to be imported.

virtual void importStandardPanelFromFile(const character *aFilePath) = 0

Imports a standard panel from a file.

Parameters:

aFilePath – [in] The path to the file to be imported.