How to use EngineeringObjectConnector

Table of Contents

• Overview
• Accessing the connector
• Project operation
• Pipe system connection
  • Parameters
  • Creating a connection
  • Connecting to an existing route
  • System categories
  • Minimal pipe routing
• Duct system connection
• Electrical system connection
• Port indices and endpoints
• Validation and errors

Overview

IEngineeringObjectConnector is obtained from the EngineeringObjectConnector property. It lets a plugin or automation code create connections in pipe, duct, and electrical systems between model objects that have ports or between port and route.

Typical workflow:

1. Get IEngineeringObjectConnector from the current IProject.
2. Create a connection parameter object: CreatePipeSystemConnectionParameters, CreateDuctSystemConnectionParameters, or CreateElectricalSystemConnectionParameters.
3. Set connection parameters (height, offset, enclosing structures) and styles (pipe/duct styles with optional insulation, fitting styles, or electrical circuit line styles).
4. Call a project's StartOperation, call the corresponding Create*SystemConnection, then Apply the operation.

Important: Connection creation is synchronous. Long calculations can make the Renga UI appear frozen or show a black screen until the call returns.

C# / .NET: Examples below demonstrate how to work with IEngineeringObjectConnector.

Accessing the connector

using Renga;
 
// Inside a plugin after Initialize, or wherever you have a project:
IProject project = application.Project;
IEngineeringObjectConnector connector = project.EngineeringObjectConnector;

Project operation

Always perform connection creation inside a project operation:

var op = project.StartOperation();
 
connector.CreatePipeSystemConnection(parameters, sourceId, sourcePortIndex, targetId, targetPortIndex, systemCategory);
 
op.Apply();

If the call of CreatePipeSystemConnection does nothing you can clear and then inspect IApplication.LastError after the call to find out what happened.

Pipe system connection

Parameters

Pipe and duct parameters differentiate main and branch. You can set:

• HeightMagistral, HeightBranch, OffsetMagistral, OffsetBranch, ConsiderEnclosingStructuresMagistral, ConsiderEnclosingStructuresBranch.
• AddPipeStyleMagistral(pipeStyleId, insulationId), AddPipeStyleBranch(pipeStyleId, insulationId) a?? use 0 for insulation if none.
• AddPipeFittingStyle(pipeFittingStyleId) a?? fitting styles must be compatible with the pipe styles (material, connection type, and connection geometry).

You can also set insulation with SetInsulationIdMagistral / SetInsulationIdBranch, and remove styles with DeletePipeStyleMagistral / DeletePipeStyleBranch and DeletePipeFittingStyle.

Creating a connection

var connector = project.EngineeringObjectConnector;
var pipeParams = connector.CreatePipeSystemConnectionParameters();
 
pipeParams.OffsetMagistral = 142.0;
pipeParams.HeightMagistral = 200.0;
pipeParams.ConsiderEnclosingStructuresMagistral = true;
 
// Optional: branch topology
pipeParams.OffsetBranch = 100.0;
pipeParams.HeightBranch = 200.0;
 
int pipeStyleId = /* from project.PipeStyles */;
int insulationMaterialId = 0; // or layered material id from project.LayeredMaterials
pipeParams.AddPipeStyleMagistral(pipeStyleId, insulationMaterialId);
 
int fittingStyleId = /* from project.PipeFittingStyles */;
pipeParams.AddPipeFittingStyle(fittingStyleId);
 
var op = project.StartOperation();
connector.CreatePipeSystemConnection(
    pipeParams,
    sourceObjectId,
    sourcePortIndex,
    targetObjectId,
    targetPortIndex,
    SystemCategory.SystemCategory_DomesticColdWater);
op.Apply();

Connecting to an existing route

When the target (or source) is a route object, the port index for that side is ignored by the API; so use -1 for the route side:

// After first segment exists, routeId identifies the Route entity:
connector.CreatePipeSystemConnection(
    pipeParams,
    sourceObjectId,
    0,
    routeId,
    -1,
    SystemCategory.SystemCategory_DomesticColdWater);

System categories

SystemCategory must match the available category of the ports. If the category does not match the available category of the ports, no route is created.

Minimal pipe routing

Routing may succeed even with an empty parameter object (defaults):

var pipeParams = connector.CreatePipeSystemConnectionParameters();
var op = project.StartOperation();
connector.CreatePipeSystemConnection(
    pipeParams, srcRoutePointId, 0, trgRoutePointId, 0, SystemCategory.SystemCategory_DomesticColdWater);
op.Apply();

Duct system connection

The API mirrors pipes with IDuctSystemConnectionParameters:

var connector = project.EngineeringObjectConnector;
var ductParams = connector.CreateDuctSystemConnectionParameters();
 
ductParams.OffsetMagistral = 500.0;
ductParams.HeightMagistral = 2500.0;
ductParams.ConsiderEnclosingStructuresMagistral = true;
 
int ductStyleId = /* from project.DuctStyles */;
int insulationId = /* from project.LayeredMaterials or 0 */;
ductParams.AddDuctStyleMagistral(ductStyleId, insulationId);
 
foreach (int fittingId in compatibleDuctFittingStyleIds)
    ductParams.AddDuctFittingStyle(fittingId);
 
var op = project.StartOperation();
connector.CreateDuctSystemConnection(
    ductParams,
    sourceObjectId,
    sourcePortIndex,
    targetObjectId,
    targetPortIndex,
    SystemCategory.SystemCategory_Ventilation);
op.Apply();

Connection to route uses the same -1 port convention as for pipes when the route is one endpoint.

Electrical system connection

var connector = project.EngineeringObjectConnector;
var elecParams = connector.CreateElectricalSystemConnectionParameters();
 
elecParams.offset = 20.0;
elecParams.Height = 2400.0;
elecParams.ConsiderEnclosingStructures = true;
 
int lineStyleId = /* from project.ElectricalCircuitLineStyles */;
elecParams.AddElectricalCircuitLineStyle(lineStyleId);
 
var op = project.StartOperation();
connector.CreateElectricalSystemConnection(
    elecParams,
    sourceObjectId,
    sourcePortIndex,
    targetObjectId,
    targetPortIndex,
    SystemCategory.SystemCategory_LightingCircuit);
op.Apply();

Difference from pipe/duct: connecting to an existing electrical route (target is a Route with port -1) does not create a second connection. For electrical systems, connection is allowed only for objects with ports, not routes.

Port indices and endpoints

• Use valid zero-based port indices for objects with ports. Invalid indices result in no new route.
• Endpoints must be objects suitable for the operation (for all available object types, see the Renga help).
• You cannot connect a route to another route; electrical routing similarly does not add a second route when targeting an existing route.
• Do not use the same object and same port on both sides.
• Ports that are already connected cannot be used to start another connection.

Validation and errors

• Parameters: Offset and height must stay within the valid numeric range enforced by the application (A±50a??000a??000 mm).
• Styles: Invalid insulation id can prevent routing; 0 means no insulation for that pipe/duct style.
• Consistency: SystemCategory must agree with port compatibility; otherwise no Route appears after Apply.
• Errors: For UI plugins, it is a good practice to clear the Application.LastError before performing an operation and read it after creating any system connection to get a possible error description.