API 参考

第七章：API 参考手册

本章每个 API 独立成节，方便速查。

---

7.1 Beam —— 梁 / 柱 / 支撑

作用： 在场景中创建一根线性构件（梁、柱、斜撑等）。这是最核心的建模对象。

属性	类型	说明
StartPoint	Point	起点（世界坐标或当前工作平面坐标）
EndPoint	Point	终点
StartPointOffset	double	起点端偏移量 (mm)
EndPointOffset	double	终点端偏移量 (mm)
CurvePlane	Vector	曲梁弯曲平面的法向量
CurveRadius	double	曲梁弯曲半径 (mm)
CurveSegs	int	曲梁分段数
Profile.ProfileString	string	截面型材名称，如 "HN400*200"、"HW300*300"、"PL12*200"
Material.MaterialString	string	材质牌号，如 "Q355B"、"Q235B"
Position.Depth	DepthEnum	截面深度方向偏移：MIDDLE / FRONT / BEHIND
Position.Rotation	RotationEnum	截面旋转：TOP / FRONT / BELOW / BEHIND
Name	string	构件名称，显示在模型树中
PartNumber.Prefix	string	构件编号前缀，如 "GL"、"GZ"
Class	string	构件分类，如 "3"

创建示例：

Beam b = new Beam();
b.StartPoint = new Point(0, 0, 0);
b.EndPoint   = new Point(0, 0, 6000);
b.Profile.ProfileString   = "HN400*200";
b.Material.MaterialString = "Q355B";
b.Position.Depth          = Position.DepthEnum.MIDDLE;
b.Position.Rotation       = Position.RotationEnum.TOP;
b.Name = "框架梁";
b.PartNumber.Prefix = "GL";
b.Class = "3";
b.Insert();  // 提交到场景（必须调用）

获取轴线：

beam.Select();  // ⚠️ 必须先 Select()

// 基准轴线 —— 用户建模时的两个控制点，不受 Position 偏移影响
List<Point> refPts = beam.GetReferanceLine(false);

// 形心轴线 —— 考虑 Position 偏移/旋转后的实际位置
List<Point> centerPts = beam.GetCenterLine(false);

获取坐标系：

beam.Select();
CoordinateSystem cs = beam.GetCoordinateSystem();
// cs.Origin → 截面形心位置
// cs.AxisX  → 截面宽度方向（翼缘展开方向）
// cs.AxisY  → 截面高度方向（腹板平面内）
// cs.AxisZ  → 构件轴线方向（起点 → 终点）

获取截面属性：

beam.Select();
beam.GetReportProperty(PartReportProperties.PROFILE_HEIGHT,            out double h);
beam.GetReportProperty(PartReportProperties.PROFILE_WIDTH,             out double w);
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_WIDTH,      out double bf);
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_WIDTH1,     out double bf1); // 上翼缘
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_WIDTH2,     out double bf2); // 下翼缘
beam.GetReportProperty(PartReportProperties.PROFILE_WEB_THICKNESS,     out double tw);
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_THICKNESS,  out double tf);
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_THICKNESS1, out double tf1); // 上翼缘
beam.GetReportProperty(PartReportProperties.PROFILE_FLANGE_THICKNESS2, out double tf2); // 下翼缘
beam.GetReportProperty(PartReportProperties.LENGTH,                    out double len);
beam.GetReportProperty(PartReportProperties.WEIGHT,                    out double wt);
beam.GetReportProperty(PartReportProperties.AREA,                      out double area);

⚠️ 重要： 每次使用 Beam 对象之前必须调用 .Select()，否则 GetCenterLine()、GetCoordinateSystem()、GetReportProperty() 等返回的数据可能为旧值或零值。

---

7.2 ContourPlate —— 多边形轮廓板

作用： 通过一组轮廓点创建任意形状的多边形板件。每个轮廓点可附带倒角（直角或圆角）。

属性	类型	说明
AddContourPoint(ContourPoint)	方法	按逆时针顺序添加轮廓顶点
Thickness	double	板厚 (mm)，直接属性
AdaptiveDirection	bool	true=深度方向受工作平面影响；false=由轮廓点顺序决定
ContourPoint.Point	Point	顶点坐标
ContourPoint.Chamfer	Chamfer	该顶点处的倒角
Profile.ProfileString	string	型材字符串，如 "PL12"（12mm 板厚）
Material.MaterialString	string	材质，如 "Q355B"
Position.Depth	DepthEnum	厚度方向偏移：MIDDLE / FRONT / BEHIND
Name	string	板件名称
PartNumber.Prefix	string	编号前缀，如 "B"

倒角类型：

// 不倒角
new Chamfer()

// 直角倒角：x 方向长，y 方向长
new Chamfer(ChamferTypeEnum.CHAMFER_LINE, x, y)

// 圆角：半径 r
new Chamfer(ChamferTypeEnum.CHAMFER_ARC, r, 0)

创建示例：

ContourPlate plate = new ContourPlate();

// 逆时针添加四个角点（以 X 轴为板法向，YZ 平面为板面）
plate.AddContourPoint(new ContourPoint(new Point(0,  100,  200), new Chamfer()));
plate.AddContourPoint(new ContourPoint(new Point(0,  100, -200), new Chamfer()));
plate.AddContourPoint(new ContourPoint(new Point(0, -100, -200),
    new Chamfer(ChamferTypeEnum.CHAMFER_LINE, 10, 10)));  // 左下角倒直角
plate.AddContourPoint(new ContourPoint(new Point(0, -100,  200), new Chamfer()));

plate.Position.Depth          = Position.DepthEnum.MIDDLE;
plate.Profile.ProfileString   = "PL12";
plate.Material.MaterialString = "Q355B";
plate.Name = "连接板";
plate.PartNumber.Prefix = "B";
plate.Insert();

💡 要点： 轮廓点按逆时针顺序，板的法向由轮廓点顺序决定（右手定则）。板厚在 Profile.ProfileString 中指定（如 "PL12" 表示 12mm），Position.Depth 控制厚度方向居中/偏置。

---

7.3 Fitting —— 端面切割 / 对齐

作用： 用一个平面对目标构件进行端面切割，常用于节点中让次梁端头贴合主梁表面。

属性	类型	说明
CutTarget	ModelObject	被切割的构件（通常是 Beam）
Plane	Plane	切割平面：new Plane(原点, 法向量)

创建示例：

// 在次梁端头向内 5mm 处切割（留 10mm 间隙）
new Fitting
{
    CutTarget = subBeam,
    Plane     = new Plane(new Point(5, 0, 0), Vector.AXIS_X)
}.Insert();

// 主梁侧切割
new Fitting
{
    CutTarget = mainBeam,
    Plane     = new Plane(new Point(-5, 0, 0), -Vector.AXIS_X)
}.Insert();

⚠️ 注意法向量方向： Plane 的法向量决定切割方向——法向量指向的一侧被保留，背向的一侧被切掉。如果切反了，试试把法向量取反（-normalVec）。

---

7.4 BoltArray / BoltGroup —— 螺栓组

作用： 在指定位置创建一组规则排列的螺栓（矩形阵列），自动处理孔洞、螺母、垫片。BoltArray 继承自 BoltGroup。

BoltArray 专属方法

方法	说明
AddBoltDistX(double)	添加 X 方向间距
AddBoltDistY(double)	添加 Y 方向间距
RemoveBoltDistX(int)	移除指定位置 X 间距
RemoveBoltDistY(int)	移除指定位置 Y 间距
GetBoltDistX(int)	获取指定位置 X 间距
GetBoltDistY(int)	获取指定位置 Y 间距
SetBoltDistX(int, double)	设置指定位置 X 间距
SetBoltDistY(int, double)	设置指定位置 Y 间距
GetBoltDistXCount()	获取 X 间距个数
GetBoltDistYCount()	获取 Y 间距个数
SetBoltArrayShape(enum)	设置螺栓排列方式
GetBoltArrayShape()	获取螺栓排列方式

BoltGroup 通用属性

属性	类型	说明
FirstPosition	Point	第一个螺栓位置（阵列起点）
SecondPosition	Point	第二个螺栓位置（决定方向）
StartPointOffset	double	起始端偏移
EndPointOffset	double	末尾端偏移
PartToBoltTo	ModelObject	螺栓穿过的主零件
PartToBeBolted	ModelObject	承载面零件（第一层板）
OtherPartsToBolt	List<ModelObject>	额外穿过的零件
Bolt	bool	true=螺栓，false=纯孔洞
BoltStandard	string	螺栓标准，如 "HS10.9"
BoltSize	double	螺栓直径 (mm)
Tolerance	double	孔径公差 (mm)
BoltType	BoltTypeEnum	BOLT_TYPE_SITE / BOLT_TYPE_SHOP
ThreadInMaterial	bool	孔内是否允许有螺纹
CutLength	double	切割长度
ExtraLength	double	附加长度
Position	—	螺栓组方位信息
Washer1	bool	上垫片
Washer2	bool	第一下垫片
Washer3	bool	第二下垫片
Nut1	bool	螺母 1
Nut2	bool	螺母 2
HoleType	int	孔类型
SlottedHoleX	double	X 方向槽口长度
SlottedHoleY	double	Y 方向槽口长度
RotateSlots	int	槽口旋转角度
ConnectAssemblies	bool	是否作为子构件连接
Shape	—	螺栓布局方式
CircleBoltCount	int	环形布局螺栓数量
CircleDiameter	double	环形布局直径

创建示例：

BoltArray bolts = new BoltArray();

bolts.FirstPosition  = new Point(marginL,              tw / 2, marginT);
bolts.SecondPosition = new Point(marginL + spacingCol, tw / 2, marginT);

bolts.AddBoltDistX(spacingCol);
bolts.AddBoltDistX(spacingCol);  // 3 列
bolts.AddBoltDistY(spacingRow);  // 2 行

bolts.PartToBoltTo   = subBeam;
bolts.PartToBeBolted = plate;

bolts.BoltStandard     = "HS10.9";
bolts.BoltSize         = 20.0;
bolts.Tolerance        = 2.0;
bolts.ThreadInMaterial = false;
bolts.BoltType         = BoltGroup.BoltTypeEnum.BOLT_TYPE_SITE;

bolts.Insert();

---

7.5 Weld —— 焊缝

作用： 在两个零件之间创建焊缝连接。Weld 继承自 BaseWeld，BaseWeld 包含完整焊缝参数。

BaseWeld 通用属性

属性	类型	说明
MainObject	ModelObject	主零件
SecondaryObject	ModelObject	次零件
TypeAbove / TypeBelow	—	线上/线下焊缝类型
SizeAbove / SizeBelow	double	线上/线下焊脚尺寸 (mm)
LengthAbove / LengthBelow	double	线上/线下焊缝长度 (mm)
PitchAbove / PitchBelow	double	线上/线下焊缝斜度
AngleAbove / AngleBelow	double	线上/线下坡口角度
RadiusAbove / RadiusBelow	double	线上/线下坡口半径
RootFaceAbove / RootFaceBelow	double	线上/线下钝边高度
ThroatAbove / ThroatBelow	double	线上/线下有效喉深
RootOpeningAbove / RootOpeningBelow	double	线上/线下对接间隙
PrefixAboveLine / PrefixBelowLine	string	线上/线下焊缝前缀
ContourAbove / ContourBelow	—	线上/线下焊缝轮廓
FinishAbove / FinishBelow	—	线上/线下焊缝抛光
ReferenceText	string	参考文本
IntermittentType	—	是否跳焊
AroundWeld	—	焊缝边缘类型
ShopWeld	—	工厂/工地
ConnectAssemblies	bool	是否作为子构件连接
NDTInspection	—	NDT 检查等级
ProcessType	—	焊接过程类型

Weld 专属属性

属性	类型	说明
Position	WeldPositionEnum	自动焊缝位置搜索方向

创建示例：

new Weld
{
    MainObject      = mainBeam,
    SecondaryObject = plate,
    Position        = BaseWeld.WeldPositionEnum.WELD_POSITION_PLUS_X
}.Insert();

---

7.6 Picker —— 用户交互拾取

作用： 在场景中让用户点选点、线、面、构件。仅自定义组件 (CustomPlugin) 及独立程序线程中可用。

构造函数：

var picker = new Picker();                       // 默认
var picker = new Picker(document);               // 指定关联的 Document

拾取点：

picker.PickPoint();                              // 捕捉一个点
picker.PickPoint("提示文字");                     // 带提示
picker.PickPoint("提示", refPoint);               // 带参考点
picker.PickPoints(PickPointEnum.PICK_TWO_POINTS); // 捕捉两个点
picker.PickPoints(PickPointEnum.PICK_TWO_POINTS, "选择起点和终点");

拾取线/面：

picker.PickLine();           // 捕捉一根线
picker.PickLine("提示");
picker.PickFace();           // 捕捉零件几何体的一个面
picker.PickFace("提示");

拾取对象：

var obj = picker.PickObject(PickObjectEnum.PICK_ONE_PART) as Beam;
var objs = picker.PickObjects(PickObjectsEnum.PICK_MANY_PARTS);

处理用户取消：

public override List<InputDefinition> DefineInput()
{
    try
    {
        var pts = new Picker().PickPoints(
            Picker.PickPointEnum.PICK_TWO_POINTS, "选择两个点");
        if (pts == null || pts.Count < 2)
            return new List<InputDefinition>();

        var input = new List<InputDefinition>();
        input.Add(new InputDefinition(pts));
        return input;
    }
    catch (UserInterruptException)
    {
        return null;  // 用户按 ESC 取消，返回 null
    }
}

---

7.7 辅助调试对象

在 #if DEBUG 块中使用，帮助你在 3D 场景中可视化坐标系和计算点。

ControlPoint —— 标记一个点：

new ControlPoint { Point = new Point(0, 0, 100) }.Insert();

ControlLine —— 绘制一条辅助线：

new ControlLine
{
    Line      = new LineSegment(new Point(0, 0, 0), new Point(500, 0, 0)),
    Color     = new Color(1, 0, 0),   // 红色
    Extension = 100,                   // 两端延长 100mm
    IsMagnetic = true                  // 是否具有磁性吸附
}.Insert();

ControlPlane —— 辅助面：

new ControlPlane
{
    Plane  = new Plane(origin, normal), // 空间坐标面
    Width  = 500,    // 显示宽度
    Height = 500,    // 显示高度
    Name   = "参考面"
}.Insert();

完整示例：绘制参考坐标系：

#if DEBUG
void DrawCoord(Vector x, Vector y, Vector z, Point origin, double len = 500)
{
    new ControlPoint { Point = new Point(origin) }.Insert();
    new ControlLine {
        Line  = new LineSegment(new Point(origin), new Point(origin + x * len)),
        Color = new Color(1, 0, 0)   // X: 红
    }.Insert();
    new ControlLine {
        Line  = new LineSegment(new Point(origin), new Point(origin + y * len)),
        Color = new Color(0, 1, 0)   // Y: 绿
    }.Insert();
    new ControlLine {
        Line  = new LineSegment(new Point(origin), new Point(origin + z * len)),
        Color = new Color(0, 0, 1)   // Z: 蓝
    }.Insert();
}
#endif

---

7.8 坐标系与工作平面

Matrix —— 自定义参考坐标系：

// 从原点和三轴构建
Matrix refMat = new Matrix(origin, axisX, axisY, axisZ);

// Inverse() 会将矩阵原地变为逆矩阵（注意：是 in-place 操作）
refMat.Inverse();

TransformationPlane —— 激活工作平面：

// 常用构造方式：
new TransformationPlane(refMat);                                  // 从 Matrix
new TransformationPlane(origin, axisX, axisY);                    // 从原点和两轴
new TransformationPlane(coordinateSystem);                        // 从 CoordinateSystem
new TransformationPlane(anotherPlane);                            // 复制一个平面

// 激活与还原
comp.Scene.SetCurrentTransformationPlane(new TransformationPlane(refMat));
// ... 创建几何对象 ...
refMat.Inverse();
comp.Scene.SetCurrentTransformationPlane(new TransformationPlane(refMat));

// 或者直接设为当前
new TransformationPlane(refMat).SetToCurrent();

CoordinateSystem —— 获取构件局部坐标系：

beam.Select();
CoordinateSystem cs = beam.GetCoordinateSystem();
// cs.Origin → 起点截面形心
// cs.AxisX  → 截面宽度方向
// cs.AxisY  → 截面高度方向
// cs.AxisZ  → 构件轴线方向

全局常量：

Vector.AXIS_X   // (1, 0, 0)
Vector.AXIS_Y   // (0, 1, 0)
Vector.AXIS_Z   // (0, 0, 1)  竖直向上
Point.ZERO      // (0, 0, 0)