ACAPI::MEP::v1::RoutingElement Class Reference

The RoutingElement can contain Routing Segments and Routing Nodes. More...

#include <MEPRoutingElement.hpp>

Inheritance diagram for ACAPI::MEP::v1::RoutingElement:

Public Member Functions
std::vector< UniqueID >	GetRoutingSegmentIds () const
std::vector< UniqueID >	GetRoutingNodeIds () const
std::vector< API_Coord3D >	GetPolyLine () const
double	GetOffsetFromHomeStory () const
Domain	GetDomain () const
API_AttributeIndex	GetMEPSystem () const
Result< UniqueID >	GetBranchPreferenceTableId () const
RoutingElementDefault	PickUpDefault () const
	Picks up and returns the Default of the RoutingElement.
RoutingSegmentDefault	GetRoutingSegmentDefaultParameters () const
RoutingNodeDefault	GetRoutingNodeDefaultParameters () const
std::optional< UniqueID >	GetLogicallyConnectedPortIdAtRouteBegin ()
std::optional< UniqueID >	GetLogicallyConnectedPortIdAtRouteEnd ()
template<typename ModifierFunc >
Result< void >	Modify (const ModifierFunc &modifierFunc, const GS::UniString &undoString)
	Executes the passed modifier scope in an Undoable command.
Result< void >	Inject (const RoutingElementDefault &routingElementDefault)
	Injects the given Default settings to the RoutingElement.
void	SetMEPSystem (const API_AttributeIndex &index)
	Sets the MEPSystem attribute of the RoutingElement.
Result< void >	SetBranchPreferenceTableId (const UniqueID &uniqueId)
	Sets the Branch PreferenceTable of the RoutingElement.
Result< void >	SetRoutingSegmentDefaultParameters (const RoutingSegmentDefault &routingSegmentDefault)
	Sets the parameters of the uncustomized RoutingSegments.
Result< void >	SetRoutingNodeDefaultParameters (const RoutingNodeDefault &routingNodeDefault)
	Sets the parameters of the uncustomized RoutingNodes.
Result< RouteConnectionResult >	ConnectLogically (const UniqueID &uniqueId)
	Connects logically this RoutingElement with the parameter MEPElement or RoutingElement, if they can be connected.
Public Member Functions inherited from ACAPI::v1::ElementBase
UniqueID	GetElemId () const
	Get unique identifier of the ElementBase object.
Result< void >	IsEditable () const
	Checks whether the element is editable.
Public Member Functions inherited from ACAPI::v1::Object
	Object (std::shared_ptr< Impl::ObjectImpl > impl)
	Constructs a new object.
const API_Token &	GetToken () const
	Get the token for this object.

Static Public Member Functions
static Result< RoutingElement >	Get (const UniqueID &uniqueId)
	Returns a Routing Element.

Protected Member Functions
void	FinalizeModification () override
	Finalizes the modifications.
Protected Member Functions inherited from ACAPI::v1::ElementBase
	ElementBase (std::shared_ptr< Impl::ObjectImpl > impl)
	Constructs a new ElementBase.
Protected Member Functions inherited from ACAPI::v1::Object
	~Object ()
	Default destructor.

Additional Inherited Members
Protected Attributes inherited from ACAPI::v1::Object
std::shared_ptr< Impl::ObjectImpl >	mImpl
	Impl object given by constructor.

Detailed Description

The RoutingElement can contain Routing Segments and Routing Nodes.

RoutingElement is on the highest level of the hierarchy.

Since

Archicad 27

Example code snippet from Test / New MEP

Getters

    ACAPI::Result<RoutingElement> routingElement = RoutingElement::Get (id);
    if (routingElement.IsErr ()) {
        ACAPI_WriteReport (routingElement.UnwrapErr ().text.c_str (), false);
        return;
    }
 
    Reporter routingElementReporter;
 
    Domain domain = routingElement->GetDomain ();
    routingElementReporter.Add ("Domain", domain);
 
    std::vector<API_Coord3D> polyLine = routingElement->GetPolyLine ();
    routingElementReporter.Add ("Polyline of the routing element:");
 
    routingElementReporter.SetTabCount (1);
    for (const API_Coord3D& node : polyLine)
        routingElementReporter.Add (node);
 
    routingElementReporter.SetTabCount (0);
    if (domain != Domain::CableCarrier)
        routingElementReporter.Add ("Branch Preference Table Id", *routingElement->GetBranchPreferenceTableId ());
 
    routingElementReporter.Add ("Offset from Home Story", routingElement->GetOffsetFromHomeStory ());
 
    if (routingElement->GetMEPSystem () == APIInvalidAttributeIndex) {
        routingElementReporter.Add ("MEP System", GS::UniString { "Undefined" });
    } else {
        API_Attribute attribute = {};
        attribute.header.typeID = API_MEPSystemID;
        attribute.header.index = routingElement->GetMEPSystem ();
        const GSErrCode err = ACAPI_Attribute_Get (&attribute);
        if DBVERIFY (err == NoError)
            routingElementReporter.Add ("MEP System", GS::UniString { attribute.header.name });
    }
 
    std::optional<UniqueID> portOnBegin = routingElement->GetLogicallyConnectedPortIdAtRouteBegin ();
    portOnBegin.has_value () ? routingElementReporter.Add ("Logically connected Port Id at begin", *portOnBegin) : routingElementReporter.Add ("Unconnected begin node.");
 
    std::optional<UniqueID> portOnEnd = routingElement->GetLogicallyConnectedPortIdAtRouteEnd ();
    portOnEnd.has_value () ? routingElementReporter.Add ("Logically connected Port Id at end", *portOnEnd) : routingElementReporter.Add ("Unconnected end node.");

    // Write informations about placed Routing Segments
    std::vector<UniqueID> segmentIds = routingElement->GetRoutingSegmentIds ();
    ACAPI_WriteReport ("List of Routing Segments:\n", false);
    for (const UniqueID& id : segmentIds)
        WriteRoutingSegmentDetails (id);
 
    // Write informations about placed Routing Nodes
    std::vector<UniqueID> nodeIds = routingElement->GetRoutingNodeIds ();
    ACAPI_WriteReport ("List of Routing Nodes:\n", false);
    for (const UniqueID& id : nodeIds)
        WriteRoutingNodeDetails (id);

Modification

    ACAPI::Result<RoutingElement> routingElement = RoutingElement::Get (id);
    if (routingElement.IsErr ()) {
        ACAPI_WriteReport (routingElement.UnwrapErr ().text.c_str (), false);
        return routingElement.UnwrapErr ().kind;
    }
 
    ERRCHK_NO_ASSERT (ModifyRoutingMEPSystem (*routingElement));
 
    std::vector<UniqueID> routingNodeIds = routingElement->GetRoutingNodeIds ();
    std::vector<UniqueID> routingSegmentIds = routingElement->GetRoutingSegmentIds ();
 
    ACAPI::Result<RoutingNode> node = RoutingNode::Get (routingNodeIds[0]);
    if (node.IsErr ())
        return node.UnwrapErr ().kind;
 
    ERRCHK_NO_ASSERT (ModifyRoutingNode (*node));
 
    ACAPI::Result<RoutingSegment> segment = RoutingSegment::Get (routingSegmentIds[0]);
    if (segment.IsErr ())
        return segment.UnwrapErr ().kind;
 
    ERRCHK_NO_ASSERT (ModifyRoutingSegment (*segment));
 
    ERRCHK_NO_ASSERT (ModifyDefaultRoutingNode (*routingElement));
    ERRCHK_NO_ASSERT (ModifyDefaultRoutingSegment (*routingElement));
 
    return NoError;

Connection of two RoutingElements

ACAPI::Result<std::vector<RouteConnectionResult>> ConnectRoutes (const std::vector<UniqueID>& routeIds)
{
    if (routeIds.empty ())
        return { ACAPI::Error (ErrParam, "Route vector is empty."), ACAPI_GetToken () };
 
    ACAPI::Result<RoutingElement> routingElem = RoutingElement::Get (routeIds[0]);
    if (routingElem.IsErr ())
        return { routingElem.UnwrapErr (), ACAPI_GetToken () };
 
    std::vector<RouteConnectionResult> routeConnectionResults;
 
    for (size_t i = 1; i < routeIds.size (); ++i) {
        ACAPI::Result<void> modifyResult = routingElem->Modify ([&](RoutingElement::Modifier& modifier) -> GSErrCode {
            ACAPI::Result<RouteConnectionResult> connectionResult = modifier.ConnectLogically (routeIds[i]);
            if (connectionResult.IsErr ())
                return connectionResult.UnwrapErr ().kind;
 
            routeConnectionResults.push_back (*connectionResult);
            return NoError;
        }, "Connect routes.");
 
        if (modifyResult.IsErr ())
            return { modifyResult.UnwrapErr (), ACAPI_GetToken () };
    }
 
    return ACAPI::Ok (routeConnectionResults);
}

Placement and Connection wrapped together

    ACAPI::Result<void> commandResult = ACAPI::CallUndoableCommand ([&]() -> GSErrCode {
        ACAPI::Result<std::vector<UniqueID>> routeIds = PlaceRoutes (placementData, domain);
 
        if (routeIds.IsErr ())
            return routeIds.UnwrapErr ().kind;
 
        ACAPI::Result<std::vector<RouteConnectionResult>> connectionResult = ConnectRoutes (*routeIds);
 
        if (connectionResult.IsErr ())
            return connectionResult.UnwrapErr ().kind;
 
        return NoError;
    }, ACAPI_GetToken (), "Place and connect routes.");

Connection of RoutingElement with element

        ACAPI::Result<FlexibleSegment> flexibleSegment = FlexibleSegment::Get (*flexibleSegmentId);
        if (flexibleSegment.IsErr ())
            return flexibleSegment.UnwrapErr ().kind;
 
        ACAPI::Result<Port> flexibleSegmentPort = Port::Get (flexibleSegment->GetPortIDs ()[0]);
        if (flexibleSegmentPort.IsErr ())
            return flexibleSegmentPort.UnwrapErr ().kind;
 
        ACAPI::Result<Port> flexibleSegmentPort2 = Port::Get (flexibleSegment->GetPortIDs ()[1]);
        flexibleSegmentPort->Modify ([&](Port::Modifier& modifier) {
            modifier.SetShape (ConnectorShape::Circular);
            modifier.SetWidth (0.35);
 
            flexibleSegmentPort2->Modify ([&](Port::Modifier& modifier) {
                modifier.SetShape (ConnectorShape::Circular);
                modifier.SetWidth (0.35);
            }, "Set FlexibleSegment Port2 size.");
        }, "Set FlexibleSegment Port size.");
 
        ACAPI::Result<TerminalDefault> terminalDefault = CreateTerminalDefault (Domain::Ventilation);
        if (terminalDefault.IsErr ())
            return terminalDefault.UnwrapErr ().kind;
 
        ACAPI::Result<UniqueID> terminalId = terminalDefault->Place (flexibleSegment->GetPortIDs ()[0]);
        if (terminalId.IsErr ())
            return terminalId.UnwrapErr ().kind;
 
        std::vector<API_Coord3D> referenceCoords;
        referenceCoords.push_back ({ 5.0, -10.0, 0.0 });
        referenceCoords.push_back ({ 8.0, -10.0, 0.0 });
        referenceCoords.push_back ({ 8.0, -10.0, 10.0 });
 
        std::map<UInt32, ACAPI::MEP::RoutingSegmentRectangularCrossSectionData> rectangularCrossSectionData;
        std::map<UInt32, ACAPI::MEP::RoutingSegmentCircularCrossSectionData> circularCrossSectionData;
 
        rectangularCrossSectionData.emplace (0, ACAPI::MEP::RoutingSegmentRectangularCrossSectionData (0.3, 0.5));
        rectangularCrossSectionData.emplace (1, ACAPI::MEP::RoutingSegmentRectangularCrossSectionData (0.8, 0.5));
 
        ACAPI::Result<std::vector<UniqueID>> routingElementId = PlaceRoutes ({ { referenceCoords, std::make_pair (rectangularCrossSectionData, circularCrossSectionData) } }, Domain::Ventilation);
        if (routingElementId.IsErr ())
            return routingElementId.UnwrapErr ().kind;
 
        ACAPI::Result<RoutingElement> routingElement = RoutingElement::Get ((*routingElementId)[0]);
        if (routingElement.IsErr ())
            return routingElement.UnwrapErr ().kind;
 
        ACAPI::Result connectResult = routingElement->Modify ([&](RoutingElement::Modifier& modifier) -> GSErrCode {
            modifier.SetMEPSystem (flexibleSegmentPort2->GetMEPSystem ());
            ACAPI::Result<RouteConnectionResult> connectionResult = modifier.ConnectLogically (*flexibleSegmentId);
            if (connectionResult.IsErr ())
                return connectionResult.UnwrapErr ().kind;
 
            return NoError;
        }, "Connect RoutingElement to FlexibleSegment.");

Member Function Documentation

ConnectLogically()

Result< RouteConnectionResult > ACAPI::MEP::v1::RoutingElement::ConnectLogically

(

const UniqueID &

uniqueId

)

Connects logically this RoutingElement with the parameter MEPElement or RoutingElement, if they can be connected.

In case of RoutingElements, the two of them have to match in domain, MEPSystem and they need to have an intersection point which will serve as a connection. Depending on geometry this could mean the merge of two RoutingElements (when one is a continuation of the other), or insertion of a Branch element (when three RoutingElements meet, or one is connected into another's RoutingSegment). Either the beginning or the end node of the RoutingElement given as a parameter must intersect the RoutingElement from which Connect was called. In case of other MEPElements, their connecting ports have to match in domain, MEPSystem and have to be positioned and oriented correctly. The direction vector of the ports have to point in opposite directions. The above mentioned requirements are enough to form a logical connection, however for a physical Port-Port connection to be created, please look for further guidance at PortBase::IsPhysicallyConnectable.

Parameters

uniqueId

The UniqueID of the MEPElement or RoutingElement which will be connected to this RoutingElement.

Returns

Returns an error in case of domain, MEPSystem mismatch or if they can not be connected geometrically, otherwise RouteConnectionResult will contain as deletedRoutingElementId the RoutingElement given as parameter, or the id of the newly created RoutingElement, splitted from the original RoutingElement.

Get()

static Result< RoutingElement > ACAPI::MEP::v1::RoutingElement::Get ( const UniqueID &  uniqueId )

static

Returns a Routing Element.

Parameters

uniqueId

The UniqueID of the requested Routing Element.

Returns

If the uniqueId belongs to a RoutingElement, returns the object associated to it, otherwise Error.

GetBranchPreferenceTableId()

Result< UniqueID > ACAPI::MEP::v1::RoutingElement::GetBranchPreferenceTableId

(

)

const

Returns

Returns the UniqueID of the Branch PreferenceTable of a Duct or Pipe Routing Element, in case of Cable Carrier returns Error.

GetDomain()

Domain ACAPI::MEP::v1::RoutingElement::GetDomain

(

)

const

Returns

Returns the domain of the RoutingElement.

GetLogicallyConnectedPortIdAtRouteBegin()

std::optional< UniqueID > ACAPI::MEP::v1::RoutingElement::GetLogicallyConnectedPortIdAtRouteBegin

(

)

Returns

Returns the id of the Port which is at least logically connected to the RoutingElement's first RoutingSegment's first Port, otherwise std::nullopt. This does not necessarily mean that the RoutingSegment's first Port is in a physical connection with it. For that, please call PortBase::IsPhysicallyConnceted.

GetLogicallyConnectedPortIdAtRouteEnd()

std::optional< UniqueID > ACAPI::MEP::v1::RoutingElement::GetLogicallyConnectedPortIdAtRouteEnd

(

)

Returns

Returns the id of the Port which is at least logically connected to the RoutingElement's last RoutingSegment's last Port, otherwise std::nullopt. This does not necessarily mean that the RoutingSegment's last Port is in a physical connection with it. For that, please call PortBase::IsPhysicallyConnceted.

GetMEPSystem()

API_AttributeIndex ACAPI::MEP::v1::RoutingElement::GetMEPSystem

(

)

const

Returns

Returns the AttributeIndex of the MEPSystem attribute to which it belongs.

GetOffsetFromHomeStory()

double ACAPI::MEP::v1::RoutingElement::GetOffsetFromHomeStory

(

)

const

Returns

Returns the relative offset level from the lowest node of the RoutingElement to the level of Home Story.

GetPolyLine()

std::vector< API_Coord3D > ACAPI::MEP::v1::RoutingElement::GetPolyLine

(

)

const

Returns

Returns the list of 3D coordinates which form the polyline of the RoutingElement.

GetRoutingNodeDefaultParameters()

RoutingNodeDefault ACAPI::MEP::v1::RoutingElement::GetRoutingNodeDefaultParameters

(

)

const

On Archicad's user interface, in the editing mode of a RoutingElement, its RoutingNodes can be customized separately. This function provides the opportunity for querying the uncustomized RoutingNode settings from the RoutingElement.

Returns

Returns the parameters of the uncustomized RoutingNodes.

GetRoutingNodeIds()

std::vector< UniqueID > ACAPI::MEP::v1::RoutingElement::GetRoutingNodeIds

(

)

const

Returns

Returns the UniqueIDs of the Routing Nodes contained by the RoutingElement.

GetRoutingSegmentDefaultParameters()

RoutingSegmentDefault ACAPI::MEP::v1::RoutingElement::GetRoutingSegmentDefaultParameters

(

)

const

On Archicad's user interface, in the editing mode of a RoutingElement, its RoutingSegments can be customized separately. This function provides the opportunity for querying the uncustomized RoutingSegment settings from the RoutingElement.

Returns

Returns the parameters of the uncustomized RoutingSegments.

GetRoutingSegmentIds()

std::vector< UniqueID > ACAPI::MEP::v1::RoutingElement::GetRoutingSegmentIds

(

)

const

Returns

Returns the UniqueIDs of the Routing Segments contained by the RoutingElement.

Inject()

Result< void > ACAPI::MEP::v1::RoutingElement::Inject

(

const RoutingElementDefault &

routingElementDefault

)

Injects the given Default settings to the RoutingElement.

Parameters

routingElementDefault

The Default which will be injected. One should pay attention to the parameter, it has to belong to the same domain than the object it is called for.

Returns

Returns an error if the injection fails for some reason, otherwise nothing.

Modify()

template<typename ModifierFunc >

Result< void > ACAPI::MEP::v1::RoutingElement::Modify	(	const ModifierFunc &	modifierFunc,
		const GS::UniString &	undoString
	)

Executes the passed modifier scope in an Undoable command.

Parameters

modifierFunc	The modifier scope (lambda, std::function or function pointer) the caller wants to execute.
undoString	The text which appears in the undo queue of Archicad after executing the command.

Returns

Returns an error if the process of modification fails for some reason, otherwise nothing.

PickUpDefault()

RoutingElementDefault ACAPI::MEP::v1::RoutingElement::PickUpDefault

(

)

const

Picks up and returns the Default of the RoutingElement.

Returns

Returns a BendDefault with the parameters of the object it was called for.

SetBranchPreferenceTableId()

Result< void > ACAPI::MEP::v1::RoutingElement::SetBranchPreferenceTableId

(

const UniqueID &

uniqueId

)

Sets the Branch PreferenceTable of the RoutingElement.

Parameters

uniqueId

The UniqueID of the PreferenceTable.

Returns

Returns an error if the parameter does not identify a Branch PreferenceTable, otherwise nothing.

SetMEPSystem()

void ACAPI::MEP::v1::RoutingElement::SetMEPSystem

(

const API_AttributeIndex &

index

)

Sets the MEPSystem attribute of the RoutingElement.

Parameters

index

The AttributeIndex of the MEPSystem attribute.

SetRoutingNodeDefaultParameters()

Result< void > ACAPI::MEP::v1::RoutingElement::SetRoutingNodeDefaultParameters

(

const RoutingNodeDefault &

routingNodeDefault

)

Sets the parameters of the uncustomized RoutingNodes.

On Archicad's user interface, in the editing mode of a RoutingElement, its RoutingNodes can be customized separately. This function provides the opportunity for setting the uncustomized RoutingNode parameters in the RoutingElement.

Parameters

routingNodeDefault

The Default to be set. One should pay attention to the parameter, it has to belong to the same domain than the object it is called for.

Returns

Returns an error in case of domain mismatch or if the set operation fails for some internal reason, otherwise nothing.

SetRoutingSegmentDefaultParameters()

Result< void > ACAPI::MEP::v1::RoutingElement::SetRoutingSegmentDefaultParameters

(

const RoutingSegmentDefault &

routingSegmentDefault

)

Sets the parameters of the uncustomized RoutingSegments.

On Archicad's user interface, in the editing mode of a RoutingElement, its RoutingSegments can be customized separately. This function provides the opportunity for setting the uncustomized RoutingSegment parameters in the RoutingElement.

Parameters

routingSegmentDefault

The Default to be set. One should pay attention to the parameter, it has to belong to the same domain than the object it is called for.

Returns

Returns an error in case of domain mismatch or if the set operation fails for some internal reason, otherwise nothing.