IPCB_ComponentBody interface
A body that encapsulates a component in 3 dimensions on a PCB document; it is handled like other primitives and is contained in the component, whether in a library or on a board.
public interface IPCB_ComponentBody : IPCB_Region
Namespace: PCB · Assembly: Altium.SDK.Interfaces
Inherits: IPCB_Primitive → IPCB_Region
Remarks
A component body is a child object of a component: to retrieve the bodies of a component, iterate over the component with a group iterator filtered to TObjectId.eComponentBodyObject.
A component body is a region with a 2D outline (it derives from IPCB_Region) and a 3D model (Model) that is an extruded shape, a cylinder, a sphere or a generic model loaded from a file.
Properties
| Property | Type | Access | Description |
|---|---|---|---|
| BodyColor3D | uint | get; set | The colour of the body in the 3D view. |
| BodyOpacity3D | float | get; set | The opacity of the body in the 3D view, from 0 (fully transparent) to 1 (opaque). |
| BodyProjection | TBoardSide | get; set | The side of the board the body is placed on. |
| Identifier | string | set | The identifier of the body. |
| Model | IPCB_Model | get; set | The 3D model of the body. |
| ModelHasChanged | bool | get | Whether the body's model has changed and must be rebuilt. |
| OverallHeight | int | get; set | The distance from the board surface to the far side of the body, in internal units (10,000 per mil). |
| OverrideColor | bool | get; set | |
| SnapCount | int | get; set | The number of snap points of the body, including the origin snap point at index 0. |
| SnapPoint | CoordPoint3D | get; set | The snap point at the given index, with X, Y and Z coordinates in internal units (10,000 per mil). |
| StandoffHeight | int | get; set | The distance from the board surface to the near side of the body, in internal units (10,000 per mil). |
| Texture | string | get; set | The name of the texture image drawn on the body in the 3D view; empty for no texture. |
| TextureCenter | CoordPoint | get; set | The offset of the texture's center from the center of the body's bounding rectangle, in internal units (10,000 per mil). |
| TextureRotation | double | get; set | The rotation of the texture, in degrees. |
| TextureSize | CoordPoint | get; set | The width and height of the texture image on the board, in internal units (10,000 per mil). |
BodyColor3D
The colour of the body in the 3D view.
uint GetBodyColor3D();
void SetBodyColor3D(uint argValue);
Type: uint · Access: read/write
The colour is used for bodies whose model is not a generic model.
Examples: Extension_CreatePCBLib
BodyOpacity3D
The opacity of the body in the 3D view, from 0 (fully transparent) to 1 (opaque).
float GetBodyOpacity3D();
void SetBodyOpacity3D(float argValue);
Type: float · Access: read/write
Assigning a value outside 0 to 1 has no effect.
BodyProjection
The side of the board the body is placed on.
TBoardSide GetBodyProjection();
void SetBodyProjection(TBoardSide argValue);
Type: TBoardSide · Access: read/write
The accessors are extension methods of IPCB_ComponentBodyHelper (using PCB;).
StandoffHeight and OverallHeight are measured from the board surface on this side, away from the board: up from the top surface for TBoardSide.eBoardSide_Top, down from the bottom surface for TBoardSide.eBoardSide_Bottom.
Identifier
The identifier of the body.
void SetState_Identifier(string argValue);
Type: string · Access: write-only
You can set it, for example, to the name of the STEP file that the body's model was loaded from.
Examples: Extension_CreatePCBLib
Model
The 3D model of the body.
IPCB_Model GetModel();
void SetModel(IPCB_Model argValue);
Type: IPCB_Model · Access: read/write
The accessors are extension methods of IPCB_ComponentBodyHelper (using PCB;).
A new body has an extruded model. Assigning a model stores a copy of it, so the assigned object can be destroyed afterwards with ModelFactory_Destroy. Assigning a model other than the current one also recalculates the body's outline and heights from the new model, as SetState_FromModel does; assigning the model the body already has (the object read from this property) does nothing. Assigning null removes the model.
Examples: Extension_CreatePCBLib
ModelHasChanged
Whether the body's model has changed and must be rebuilt.
bool GetState_ModelHasChanged();
Type: bool · Access: read-only
A new body starts with the value true. Assigning OverrideColor sets it to true; ValidateMesh sets it to false.
OverallHeight
The distance from the board surface to the far side of the body, in internal units (10,000 per mil).
int GetOverallHeight();
void SetOverallHeight(int argValue);
Type: int · Access: read/write
The distance is measured from the board surface on the side given by BodyProjection, away from the board. For a body with an extruded model the value is the upper Z limit of the model, and assigning it changes that limit. For other models, assigning Model or calling SetState_FromModel recalculates the value from the model's extent.
Examples: Extension_CreatePCBLib
OverrideColor
No description yet.
bool GetOverrideColor();
void SetOverrideColor(bool argValue);
Type: bool · Access: read/write
Assigning a value sets ModelHasChanged to true.
SnapCount
The number of snap points of the body, including the origin snap point at index 0.
int GetState_SnapCount();
void SetState_SnapCount(int argCount);
Type: int · Access: read/write
Assigning 0 or a negative value sets the count to 1, which keeps the origin snap point. Snap points added by increasing the count start at (0, 0, 0).
SnapPoint
The snap point at the given index, with X, Y and Z coordinates in internal units (10,000 per mil).
CoordPoint3D GetState_SnapPoint(int argIndex);
void SetState_SnapPoint(int argIndex, CoordPoint3D argPoint);
Type: CoordPoint3D · Access: read/write · Index: argIndex (int): The zero-based index of the snap point, from 0 to SnapCount - 1.
The accessors are extension methods of IPCB_ComponentBodyHelper (using PCB;).
The point at index 0 is the origin snap point; assigning it has no effect.
StandoffHeight
The distance from the board surface to the near side of the body, in internal units (10,000 per mil).
int GetStandoffHeight();
void SetStandoffHeight(int argValue);
Type: int · Access: read/write
The distance is measured from the board surface on the side given by BodyProjection, away from the board. For a body with an extruded model the value is the lower Z limit of the model, and assigning it changes that limit. For other models, assigning Model or calling SetState_FromModel recalculates the value from the model's extent.
Examples: Extension_CreatePCBLib
Texture
The name of the texture image drawn on the body in the 3D view; empty for no texture.
string GetTexture();
void SetTexture(string argValue);
Type: string · Access: read/write
The texture is drawn only when the body's model is an extruded model.
TextureCenter
The offset of the texture's center from the center of the body's bounding rectangle, in internal units (10,000 per mil).
CoordPoint GetTextureCenter();
void SetTextureCenter(CoordPoint argValue);
Type: CoordPoint · Access: read/write
The accessors are extension methods of IPCB_ComponentBodyHelper (using PCB;).
TextureRotation
The rotation of the texture, in degrees.
double GetTextureRotation();
void SetTextureRotation(double argValue);
Type: double · Access: read/write
TextureSize
The width and height of the texture image on the board, in internal units (10,000 per mil).
CoordPoint GetTextureSize();
void SetTextureSize(CoordPoint argValue);
Type: CoordPoint · Access: read/write
The accessors are extension methods of IPCB_ComponentBodyHelper (using PCB;).
Methods
| Method | Returns | Description |
|---|---|---|
| AddAxis | IPCB_Axis | Does nothing and returns null; no axis is added to the body. |
| AxisCount | int | Returns the number of axes of the body. |
| ClearAxes | void | Removes all axes from the body. |
| Fade | void | Fades the body in the 3D view by the given amount, on top of any fade already applied. |
| GetAxis | IPCB_Axis | Returns the axis at the given index. |
| ModelFactory_Create | IPCB_Model | Creates a model of the given type. |
| ModelFactory_CreateCylinder | IPCB_Model | Creates a cylinder model. |
| ModelFactory_CreateExtruded | IPCB_Model | Creates an extruded model from the body's outline. |
| ModelFactory_CreateSphere | IPCB_Model | Creates a sphere model. |
| ModelFactory_Destroy | void | Destroys the given model. |
| ModelFactory_FromFilename | IPCB_Model | Creates a model from a 3D model file. |
| ModelFactory_FromVault | IPCB_Model | Creates a model from a revision of a 3D model item in a vault. |
| ModelFactory_Replace | void | Destroys a model and replaces the reference with a new model of the given type. |
| ModelFactory_UpdateModel | bool | Changes the dimensions of the body's cylinder or sphere model. |
| ResetDisplacement | void | Removes any temporary displacement transform applied to the body. |
| ResetFade | void | Removes the fade applied with Fade, so that the body is drawn with its BodyOpacity3D. |
| SaveModelToFile | bool | Saves the body's model to a file. |
| SetState_FromModel | void | Recalculates the body's outline and heights from its model. |
| UniqueName | string | Returns a text that identifies the body's model. |
| ValidateMesh | void | Rebuilds the body's extruded model when it has changed. |
AddAxis
Does nothing and returns null; no axis is added to the body.
IPCB_Axis AddAxis();
Returns: IPCB_Axis
Extension method of IPCB_ComponentBodyHelper (using PCB;).
AxisCount
Returns the number of axes of the body.
int AxisCount();
Returns: int
ClearAxes
Removes all axes from the body.
void ClearAxes();
Returns: nothing (void)
Fade
Fades the body in the 3D view by the given amount, on top of any fade already applied.
void Fade(float argValue);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argValue | float | value | The fade amount, from 0 (no change) to 1 (fully faded). |
Returns: nothing (void)
Each call multiplies the remaining opacity by 1 minus the amount, and the body is drawn with BodyOpacity3D multiplied by the remaining opacity. BodyOpacity3D itself does not change; ResetFade removes the fade.
GetAxis
Returns the axis at the given index.
IPCB_Axis GetAxis(int argIndex);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argIndex | int | value | The zero-based index of the axis, from 0 to AxisCount - 1. |
Returns: IPCB_Axis
Extension method of IPCB_ComponentBodyHelper (using PCB;).
ModelFactory_Create
Creates a model of the given type.
IPCB_Model ModelFactory_Create(T3DModelType argModelType);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argModelType | T3DModelType | value | The type of the model to create. |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
The model is not attached to the body; assign it to Model to use it.
ModelFactory_CreateCylinder
Creates a cylinder model.
IPCB_Model ModelFactory_CreateCylinder(int argRadius, int argHeight, uint argColor);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argRadius | int | value | The radius of the cylinder, in internal units (10,000 per mil). |
argHeight | int | value | The height of the cylinder, in internal units (10,000 per mil). |
argColor | uint | value | The colour of the model. |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
The model is not attached to the body; assign it to Model to use it.
ModelFactory_CreateExtruded
Creates an extruded model from the body's outline.
IPCB_Model ModelFactory_CreateExtruded(int argMinZ, int argMaxZ, uint argColor);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argMinZ | int | value | The near Z limit of the extrusion (the standoff height), in internal units (10,000 per mil). |
argMaxZ | int | value | The far Z limit of the extrusion (the overall height), in internal units (10,000 per mil). |
argColor | uint | value | The colour of the model. |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
When the outline has an area and argMaxZ is greater than argMinZ, the outline is extruded from argMinZ to argMaxZ; otherwise the model gets only that Z range. The call also sets the body's StandoffHeight to argMinZ and OverallHeight to argMaxZ. The model is not attached to the body; assign it to Model to use it.
Examples: Extension_CreatePCBLib
ModelFactory_CreateSphere
Creates a sphere model.
IPCB_Model ModelFactory_CreateSphere(int argRadius, uint argColor);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argRadius | int | value | The radius of the sphere, in internal units (10,000 per mil). |
argColor | uint | value | The colour of the model. |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
The model is not attached to the body; assign it to Model to use it.
ModelFactory_Destroy
Destroys the given model.
void ModelFactory_Destroy(ref IPCB_Model argValue);
void ModelFactory_Destroy(ref object argValue);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argValue | IPCB_Model | ref | The model to destroy. |
Returns: nothing (void)
The first overload is an extension method of IPCB_ComponentBodyHelper (using PCB;) with typed parameters; the second is declared by the interface.
Does nothing when argValue is null. The reference passed in is not set to null.
ModelFactory_FromFilename
Creates a model from a 3D model file.
IPCB_Model ModelFactory_FromFilename(string argFileName, bool argWatchDirectory);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argFileName | string | value | The path of the 3D model file. |
argWatchDirectory | bool | value |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
The model is not attached to the body; assign it to Model to use it.
ModelFactory_FromVault
Creates a model from a revision of a 3D model item in a vault.
IPCB_Model ModelFactory_FromVault(string argTitle, string argVaultGUID, string argItemGUID, string argItemRevisionGUID);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argTitle | string | value | The name given to the created model. |
argVaultGUID | string | value | The GUID of the vault that holds the item. |
argItemGUID | string | value | The GUID of the item. |
argItemRevisionGUID | string | value | The GUID of the item revision. |
Returns: IPCB_Model
Extension method of IPCB_ComponentBodyHelper (using PCB;).
ModelFactory_Replace
Destroys a model and replaces the reference with a new model of the given type.
void ModelFactory_Replace(T3DModelType argModelType, ref IPCB_Model argValue);
void ModelFactory_Replace(int argModelType, ref object argValue);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argModelType | T3DModelType | value | The type of the new model. |
argValue | IPCB_Model | ref | The model to destroy; receives the new model. |
Returns: nothing (void)
The first overload is an extension method of IPCB_ComponentBodyHelper (using PCB;) with typed parameters; the second is declared by the interface.
The body's own model is not changed.
ModelFactory_UpdateModel
Changes the dimensions of the body's cylinder or sphere model.
bool ModelFactory_UpdateModel(int argRadius, int argHeight, T3DModelType argModelType);
bool ModelFactory_UpdateModel(int argRadius, int argHeight, int argModelType);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argRadius | int | value | The new radius, in internal units (10,000 per mil). |
argHeight | int | value | The new height of a cylinder, in internal units (10,000 per mil); not used for a sphere. |
argModelType | T3DModelType | value | Not used; the type of the body's current model decides what is changed. |
Returns: bool
The first overload is an extension method of IPCB_ComponentBodyHelper (using PCB;) with typed parameters; the second is declared by the interface.
For a cylinder model the radius and the height are set; for a sphere model the radius. Does nothing when the body has no model or its model is an extruded or a generic model. The method always returns false.
ResetDisplacement
Removes any temporary displacement transform applied to the body.
void ResetDisplacement();
Returns: nothing (void)
ResetFade
Removes the fade applied with Fade, so that the body is drawn with its BodyOpacity3D.
void ResetFade();
Returns: nothing (void)
SaveModelToFile
Saves the body's model to a file.
bool SaveModelToFile(string argFullPath);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argFullPath | string | value | The full path of the file to write. |
Returns: bool
When the model is a generic model loaded from a file with the same extension as argFullPath, the original model file is copied; otherwise the model is exported as a STEP file, except for a .sldprt target, which is written only by copying. Returns true when the file was written.
SetState_FromModel
Recalculates the body's outline and heights from its model.
void SetState_FromModel();
Returns: nothing (void)
For a model that is not an extruded model, the outline becomes a rectangle around the model's extent in the board plane, turned by the model's Z rotation, and StandoffHeight and OverallHeight are set from the model's lowest and highest Z. For an extruded model, the outline and heights are kept and the model's origin is moved to the center of the body's bounding rectangle. Does nothing when the body has no model or the model is empty.
UniqueName
Returns a text that identifies the body's model.
string UniqueName();
Returns: string
For a non-empty model it is a text that identifies the loaded model data during the current session; it is not persistent. For an empty model it is the model's GUID.
ValidateMesh
Rebuilds the body's extruded model when it has changed.
void ValidateMesh();
Returns: nothing (void)
When ModelHasChanged is true and the model is an extruded model, the model is created again from the body's current outline and the model's Z limits, and the outline and heights are recalculated as by SetState_FromModel. The rebuild needs an outline with an area and at least 3 vertices and an upper Z limit greater than the lower one. Afterwards ModelHasChanged is false when the body has a model.
Inherited members
- From IPCB_Region: Area, CavityHeight, GeometricPolygon, GetHole, GetHoleCount, GetMainContour, IsSimpleRegion, Kind, Name, RotateAroundXY, SetOutlineContour
- From IPCB_Primitive: AllowGlobalEdit, BeginModify, Board, BoundingRectangle, BoundingRectangleChildren, BoundingRectangleForPainting, BoundingRectangleForSelection, CancelModify, Component, Coordinate, DescriptorString, DetailString, Dimension, DrawAsPreview, DRCError, Enabled, Enabled_Direct, Enabled_vComponent, Enabled_vCoordinate, Enabled_vDimension, Enabled_vNet, Enabled_vPolygon, EnableDraw, EndModify, Export_ToParameters, FlipXY, GraphicallyInvalidate, Handle, InBoard, InComponent, InCoordinate, Index, InDimension, InNet, InPolygon, InSelectionMemory, IsAssyTestPoint_Bottom, IsAssyTestPoint_Top, IsElectricalPrim, IsFreePrimitive, IsHidden, IsKeepout, IsPreRoute, IsSaveable, IsTenting, IsTenting_Bottom, IsTenting_Top, IsTestPoint_Bottom, IsTestPoint_Top, Layer, MiscFlag1, MiscFlag2, MiscFlag3, Moveable, MoveByXY, MoveToXY, Net, ObjectID, ObjectIDString, PadCacheRobotFlag, PasteMaskExpansion, Polygon, PolygonOutline, PowerPlaneClearance, PowerPlaneConnectStyle, PowerPlaneReliefExpansion, Preview, ReliefAirGap, ReliefConductorWidth, ReliefEntries, Replicate, RequiredParamterSpace, RotateBy, Selected, SolderMaskExpansion, SwapLayerPairs, TearDrop, UnionIndex, UniqueId, UniqueID, Used, UserRouted, V7Layer, ViewableObjectID
Examples
Used in the SDK examples: Extension_CreatePCBLib.