IPCB_Polygon interface
A polygon pour on a PCB document, an irregular area of copper that connects to a net and is poured around existing objects.
public interface IPCB_Polygon : IPCB_Group
Namespace: PCB · Assembly: Altium.SDK.Interfaces
Inherits: IPCB_Primitive → IPCB_Group
Derived: IPCB_BoardOutline
Remarks
Polygons are similar to area fills, except that they can fill irregular shaped areas of a board and can connect to a specified net as they are poured. By adjusting the grid and track size, a polygon can be either a solid copper area or a cross-hatched lattice. Polygons can be placed on any layer except an internal plane layer; a polygon on a layer that is not a signal layer is not poured around existing objects.
Polygons are group objects: the tracks, arcs and regions created when a polygon is poured are its child objects. Use GroupIterator_Create and GroupIterator_Destroy to iterate them. To copy a polygon together with its poured copper, the examples use ReplicateWithChildren.
Split planes on internal plane layers are represented by IPCB_SplitPlane, not by this interface.
Example
Report the net, type, size and segments of every polygon on the current board.
using System.Collections.Generic;
using System.IO;
using DXP;
using PCB;
// Retrieve the current board.
IPCB_Board board = PCB.GlobalVars.PCBServer?.GetCurrentPCBBoard();
if (board == null)
return;
// Search for polygons and, for each polygon found, collect
// its attributes in a list to be saved as a text file.
IPCB_BoardIterator iterator = board.BoardIterator_Create();
iterator.AddFilter_ObjectSet(new PCB.TObjectSet { TObjectId.ePolyObject });
iterator.AddFilter_AllLayers();
iterator.AddFilter_Method(TIterationMethod.eProcessAll);
int polyNo = 0;
var polygonReport = new List<string>();
var polygon = iterator.FirstPCBObject() as IPCB_Polygon;
while (polygon != null)
{
polyNo++;
polygonReport.Add("Polygon No : " + polyNo);
// Check that the net exists before getting its name.
if (polygon.GetState_Net() != null)
polygonReport.Add(" Polygon Net : " + polygon.GetState_Net().GetState_Name());
if (polygon.GetState_PolygonType() == TPolygonType.eSignalLayerPolygon)
polygonReport.Add(" Polygon type : " + "Polygon on Signal Layer");
else
polygonReport.Add(" Polygon type : " + "Split plane polygon");
polygonReport.Add(" Polygon BorderWidth : " + polygon.GetState_BorderWidth());
polygonReport.Add(" Area size : " + polygon.GetState_AreaSize());
// Segments of the polygon.
for (int i = 0; i <= polygon.GetState_PointCount() - 1; i++)
{
PolySegment segment = polygon.GetState_Segments(i);
if (segment.Kind == TPolySegmentType.ePolySegmentLine)
{
polygonReport.Add(" Polygon Segment Line at X: " + segment.Vx);
polygonReport.Add(" Polygon Segment Line at Y: " + segment.Vy);
}
else
{
polygonReport.Add(" Polygon Segment Arc 1 : " + segment.Angle1);
polygonReport.Add(" Polygon Segment Arc 2 : " + segment.Angle2);
polygonReport.Add(" Polygon Segment Radius : " + segment.Radius);
}
}
polygonReport.Add("");
polygon = iterator.NextPCBObject() as IPCB_Polygon;
}
board.BoardIterator_Destroy(ref iterator);
// Save the polygon data as a text file next to the board file.
string fileName = Path.ChangeExtension(board.GetState_FileName(), ".pol");
File.WriteAllLines(fileName, polygonReport);
// Display the polygons report.
IClient client = DXP.GlobalVars.Client;
IServerDocument document = client.OpenDocument("Text", fileName);
if (document != null)
client.ShowDocument(document);
Properties
| Property | Type | Access | Description |
|---|---|---|---|
| ArcApproximation | int | get; set | The arc resolution of the pour, the maximum distance by which the line segments that approximate an arc, for example around a pad or via, may deviate from a perfect arc. |
| ArcPourMode | bool | get; set | |
| AreaSize | double | get; set | The area enclosed by the polygon's outline, in square internal units. |
| AutoGenerateName | bool | get; set | Whether the polygon's name is generated automatically. |
| AvoidObsticles | bool | get; set | Whether the polygon is poured around the other objects in its area. |
| BorderWidth | int | get; set | |
| ClipAcuteCorners | bool | get; set | |
| CopperPourInvalid | bool | get | Whether the polygon's pour is marked as out of date. |
| DrawDeadCopper | bool | get; set | A diagnostic drawing option for dead copper. |
| DrawRemovedIslands | bool | get; set | A diagnostic drawing option for the islands that the pour removes. |
| DrawRemovedNecks | bool | get; set | A diagnostic drawing option for the narrow necks that the pour removes. |
| ExpandOutline | bool | get; set | |
| Grid | int | get; set | The grid on which the hatch tracks of the polygon are placed, in internal units (10,000 per mil). |
| HitPrimitive | bool | get | Whether the given primitive touches the polygon's outline or lies inside it. |
| IgnoreViolations | bool | get; set | Whether on-line DRC violations are ignored for the polygon. |
| InRepour | bool | get | Whether the polygon is being repoured. |
| IslandAreaThreshold | double | get; set | The area below which the islands created when the polygon is poured are removed, in square internal units (100,000,000 per square mil). |
| MinTrack | int | get; set | The minimum length of the primitives created when the polygon is poured, in internal units (10,000 per mil). |
| MitreCorners | bool | get; set | |
| Name | string | get; set | The polygon's name. |
| NeckWidthThreshold | int | get; set | The width below which narrow sections of the pour are removed, in internal units (10,000 per mil). |
| PointCount | int | get; set | The number of segments in the polygon's outline. |
| PolygonType | TPolygonType | get; set | The kind of polygon. |
| PolyHatchStyle | TPolyHatchStyle | get; set | How the polygon is filled when it is poured. |
| Poured | bool | get; set | Whether the polygon is poured, that is, not shelved. |
| PourIndex | int | get; set | The polygon's position in the board's pour order. |
| PourOver | TPolygonPourOver | get; set | Which existing copper of the polygon's own net the polygon pours over. |
| RemoveDead | bool | get; set | Whether regions of dead copper are removed from the polygon when it is poured. |
| RemoveIslandsByArea | bool | get; set | Whether islands of the pour with an area less than IslandAreaThreshold are removed. |
| RemoveNarrowNecks | bool | get; set | Whether sections of the pour narrower than NeckWidthThreshold are removed. |
| Segments | PolySegment | get; set | The segments of the polygon's outline, by index. |
| StrictHitTest | bool | get | Whether the given point lies inside the polygon's bounding rectangle and inside its outline. |
| TrackSize | int | get; set | The width of the tracks that hatch the polygon, in internal units (10,000 per mil). |
| UseOctagons | bool | get; set | Whether pads are surrounded by octagons rather than arcs when the polygon is poured. |
ArcApproximation
The arc resolution of the pour, the maximum distance by which the line segments that approximate an arc, for example around a pad or via, may deviate from a perfect arc.
int GetState_ArcApproximation();
void SetState_ArcApproximation(int argValue);
Type: int · Access: read/write
The value is in internal units (10,000 per mil). The default value is 0.5 mil. The lower the value, the smoother the arc; the higher the value, the coarser the arc, with longer line segments.
ArcPourMode
No description yet.
bool GetState_ArcPourMode();
void SetState_ArcPourMode(bool argValue);
Type: bool · Access: read/write
AreaSize
The area enclosed by the polygon's outline, in square internal units.
double GetState_AreaSize();
void SetState_AreaSize(double argValue);
Type: double · Access: read/write
The value is approximate: it does not take the width of the outline or the hatching into account. SetState_XSizeYSize_1 recalculates it from the outline; an assigned value is stored as given.
AutoGenerateName
Whether the polygon's name is generated automatically.
bool GetState_AutoGenerateName();
void SetState_AutoGenerateName(bool argValue);
Type: bool · Access: read/write
Only polygons on signal layers are named automatically: on other layers the property reads false and assigning it does nothing. While it is true and the polygon is on a board, Name returns the generated name. Setting it to false keeps the last generated name as the polygon's name.
AvoidObsticles
Whether the polygon is poured around the other objects in its area.
bool GetState_AvoidObsticles();
void SetState_AvoidObsticles(bool argValue);
Type: bool · Access: read/write
When false, the pour does not cut voids around other objects.
BorderWidth
No description yet.
int GetState_BorderWidth();
void SetState_BorderWidth(int argValue);
Type: int · Access: read/write
ClipAcuteCorners
No description yet.
bool GetState_ClipAcuteCorners();
void SetState_ClipAcuteCorners(bool argValue);
Type: bool · Access: read/write
CopperPourInvalid
Whether the polygon's pour is marked as out of date.
bool GetState_CopperPourInvalid();
Type: bool · Access: read-only
DrawDeadCopper
A diagnostic drawing option for dead copper.
bool GetState_DrawDeadCopper();
void SetState_DrawDeadCopper(bool argValue);
Type: bool · Access: read/write
DrawRemovedIslands
A diagnostic drawing option for the islands that the pour removes.
bool GetState_DrawRemovedIslands();
void SetState_DrawRemovedIslands(bool argValue);
Type: bool · Access: read/write
DrawRemovedNecks
A diagnostic drawing option for the narrow necks that the pour removes.
bool GetState_DrawRemovedNecks();
void SetState_DrawRemovedNecks(bool argValue);
Type: bool · Access: read/write
ExpandOutline
No description yet.
bool GetState_ExpandOutline();
void SetState_ExpandOutline(bool argValue);
Type: bool · Access: read/write
Grid
The grid on which the hatch tracks of the polygon are placed, in internal units (10,000 per mil).
int GetState_Grid();
void SetState_Grid(int argValue);
Type: int · Access: read/write
Ideally this grid is a fraction of the component pin pitch, to allow the most effective placement of the polygon tracks.
HitPrimitive
Whether the given primitive touches the polygon's outline or lies inside it.
bool GetState_HitPrimitive(IPCB_Primitive argPrimitive);
Type: bool · Access: read-only · Index: argPrimitive (IPCB_Primitive)
The accessors are extension methods of IPCB_PolygonHelper (using PCB;).
Returns true when the primitive's reference point is inside the outline or the primitive overlaps one of the outline's segments. On a board outline (IPCB_BoardOutline) the primitive's layer is not taken into account.
See also: IPCB_BoardOutline
IgnoreViolations
Whether on-line DRC violations are ignored for the polygon.
bool GetState_IgnoreViolations();
void SetState_IgnoreViolations(bool argValue);
Type: bool · Access: read/write
InRepour
Whether the polygon is being repoured.
bool GetState_InRepour();
Type: bool · Access: read-only
IslandAreaThreshold
The area below which the islands created when the polygon is poured are removed, in square internal units (100,000,000 per square mil).
double GetState_IslandAreaThreshold();
void SetState_IslandAreaThreshold(double argValue);
Type: double · Access: read/write
Islands are removed only when RemoveIslandsByArea is true. The default value is 2500 square mils.
MinTrack
The minimum length of the primitives created when the polygon is poured, in internal units (10,000 per mil).
int GetState_MinTrack();
void SetState_MinTrack(int argValue);
Type: int · Access: read/write
MitreCorners
No description yet.
bool GetState_MitreCorners();
void SetState_MitreCorners(bool argValue);
Type: bool · Access: read/write
Name
The polygon's name.
string GetState_Name();
void SetState_Name(string argName);
Type: string · Access: read/write
While AutoGenerateName is true, assigning a name does nothing.
NeckWidthThreshold
The width below which narrow sections of the pour are removed, in internal units (10,000 per mil).
int GetState_NeckWidthThreshold();
void SetState_NeckWidthThreshold(int argValue);
Type: int · Access: read/write
Narrow sections are removed only when RemoveNarrowNecks is true. The default value is 5 mils.
PointCount
The number of segments in the polygon's outline.
int GetState_PointCount();
void SetState_PointCount(int argValue);
Type: int · Access: read/write
Segments accepts indexes from 0 to PointCount inclusive.
PolygonType
The kind of polygon.
TPolygonType GetState_PolygonType();
void SetState_PolygonType(TPolygonType argValue);
Type: TPolygonType · Access: read/write
The accessors are extension methods of IPCB_PolygonHelper (using PCB;).
The property is read-only in effect: it always returns TPolygonType.eSignalLayerPolygon, and assigning a value does not change it.
See also: TPolygonType
PolyHatchStyle
How the polygon is filled when it is poured.
TPolyHatchStyle GetState_PolyHatchStyle();
void SetState_PolyHatchStyle(TPolyHatchStyle argValue);
Type: TPolyHatchStyle · Access: read/write
The accessors are extension methods of IPCB_PolygonHelper (using PCB;).
TPolyHatchStyle.ePolySolid fills the polygon with solid copper regions. TPolyHatchStyle.ePolyHatch90, TPolyHatchStyle.ePolyHatch45, TPolyHatchStyle.ePolyVHatch and TPolyHatchStyle.ePolyHHatch fill it with a hatch of tracks and arcs (90 degree, 45 degree, vertical or horizontal).
TPolyHatchStyle.ePolyNoHatch does not fill the polygon at all: only the boundary tracks are present. You may wish to use this option if you want to place a polygon during the design phase, but do not want it to slow system performance. The polygon can be re-poured with the desired hatching before generating output.
See also: TPolyHatchStyle, IPCB_Region
Poured
Whether the polygon is poured, that is, not shelved.
bool GetState_Poured();
void SetState_Poured(bool argValue);
Type: bool · Access: read/write
Assigning a value does nothing.
PourIndex
The polygon's position in the board's pour order.
int GetState_PourIndex();
void SetState_PourIndex(int argValue);
Type: int · Access: read/write
When AutoGenerateName is true, assigning a value regenerates the polygon's name, which contains the pour index.
PourOver
Which existing copper of the polygon's own net the polygon pours over.
TPolygonPourOver GetState_PourOver();
void SetState_PourOver(TPolygonPourOver argValue);
Type: TPolygonPourOver · Access: read/write
The accessors are extension methods of IPCB_PolygonHelper (using PCB;).
With TPolygonPourOver.ePolygonPourOver_None the polygon pours around existing tracks and arcs of the same net. With TPolygonPourOver.ePolygonPourOver_SameNet it covers existing tracks and arcs of the same net. With TPolygonPourOver.ePolygonPourOver_SameNetPolygons it covers only same-net copper that belongs to a polygon.
See also: TPolygonPourOver
RemoveDead
Whether regions of dead copper are removed from the polygon when it is poured.
bool GetState_RemoveDead();
void SetState_RemoveDead(bool argValue);
Type: bool · Access: read/write
Dead copper is created when an area of the polygon can not be connected to the selected net. You can view dead copper as unconnected "islands" of copper within the polygon created when existing tracks, pads and vias prevent the plane pouring as one continuous area. If this property is false, areas of dead copper are not removed.
The entire polygon is removed if it does not enclose any pads on the selected net, as it is all viewed as dead copper.
RemoveIslandsByArea
Whether islands of the pour with an area less than IslandAreaThreshold are removed.
bool GetState_RemoveIslandsByArea();
void SetState_RemoveIslandsByArea(bool argValue);
Type: bool · Access: read/write
RemoveNarrowNecks
Whether sections of the pour narrower than NeckWidthThreshold are removed.
bool GetState_RemoveNarrowNecks();
void SetState_RemoveNarrowNecks(bool argValue);
Type: bool · Access: read/write
If false, narrow necks are left alone.
Segments
The segments of the polygon's outline, by index.
PolySegment GetState_Segments(int argI);
void SetState_Segments(int argI, PolySegment argValue);
Type: PolySegment · Access: read/write · Index: argI (int)
The accessors are extension methods of IPCB_PolygonHelper (using PCB;).
Each segment is a line (Kind is TPolySegmentType.ePolySegmentLine) given by its vertex Vx, Vy, or an arc (TPolySegmentType.ePolySegmentArc) given by its center Cx, Cy, its Radius and the angles Angle1 and Angle2. Coordinates are in internal units (10,000 per mil). Valid indexes are from 0 to PointCount inclusive; any other index returns a segment with all fields zero, and assigning a segment at such an index does nothing.
See also: PolySegment
StrictHitTest
Whether the given point lies inside the polygon's bounding rectangle and inside its outline.
bool GetState_StrictHitTest(int argHitX, int argHitY);
Type: bool · Access: read-only · Index: argHitX (int): The X coordinate of the point, in internal units (10,000 per mil)., argHitY (int): The Y coordinate of the point, in internal units (10,000 per mil).
TrackSize
The width of the tracks that hatch the polygon, in internal units (10,000 per mil).
int GetState_TrackSize();
void SetState_TrackSize(int argValue);
Type: int · Access: read/write
UseOctagons
Whether pads are surrounded by octagons rather than arcs when the polygon is poured.
bool GetState_UseOctagons();
void SetState_UseOctagons(bool argValue);
Type: bool · Access: read/write
Octagons give smaller Gerber files and faster photoplotting.
Methods
| Method | Returns | Description |
|---|---|---|
| AcceptsLayer | bool | Returns whether the polygon can be placed on the given layer. |
| CopperPourValidate | void | Repours the polygon if its pour is marked as out of date (CopperPourInvalid). |
| GetDefaultName | string | Returns a unique name for the polygon, generated for the board the polygon is on. |
| GrowPolyshape | void | Moves the edges of the polygon's outline outwards or inwards by the given distance. |
| Internal_xBoundingRectangle | ICoordRect | |
| PointInPolygon | bool | Returns whether the given point lies inside the polygon's outline. |
| PrimitiveInsidePoly | bool | Returns whether the given primitive lies completely inside the polygon's outline. |
| Rebuild | void | Repours the polygon, regenerating its child copper. |
| RotateAroundXY | void | Rotates the polygon about the given point. |
| SetState_AutoNameInvalidate | void | Marks the polygon's automatically generated name as out of date. |
| SetState_CopperPourInvalid | void | Marks the polygon's pour as out of date. |
| SetState_CopperPourValid | void | Marks the polygon's pour as up to date. |
| SetState_XSizeYSize_1 | bool | Recalculates the polygon's bounding rectangle and AreaSize from its outline. |
| XBoundingRectangle | CoordRect | Returns the bounding rectangle of the polygon's outline. |
AcceptsLayer
Returns whether the polygon can be placed on the given layer.
bool AcceptsLayer(TV6_Layer argLayer);
bool AcceptsLayer(int argLayer);
| Parameter | Type | Passing |
|---|---|---|
argLayer | TV6_Layer | value |
Returns: bool
The first overload is an extension method of IPCB_PolygonHelper (using PCB;) with typed parameters; the second is declared by the interface.
Returns false for internal plane layers and true for any other layer.
CopperPourValidate
Repours the polygon if its pour is marked as out of date (CopperPourInvalid).
void CopperPourValidate();
Returns: nothing (void)
GetDefaultName
Returns a unique name for the polygon, generated for the board the polygon is on.
string GetDefaultName();
Returns: string
Returns an empty string when the polygon is not on a board.
GrowPolyshape
Moves the edges of the polygon's outline outwards or inwards by the given distance.
void GrowPolyshape(int argDist);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argDist | int | value | The distance, in internal units (10,000 per mil). A positive value moves the edges outwards, so the area grows; a negative value moves them inwards. |
Returns: nothing (void)
Does nothing when the distance is 0 or the outline has fewer than two points.
Internal_xBoundingRectangle
No description yet.
ICoordRect Internal_xBoundingRectangle();
Returns: ICoordRect
PointInPolygon
Returns whether the given point lies inside the polygon's outline.
bool PointInPolygon(int argHitX, int argHitY);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argHitX | int | value | The X coordinate of the point, in internal units (10,000 per mil). |
argHitY | int | value | The Y coordinate of the point, in internal units (10,000 per mil). |
Returns: bool
PrimitiveInsidePoly
Returns whether the given primitive lies completely inside the polygon's outline.
bool PrimitiveInsidePoly(IPCB_Primitive argPrimitive);
bool PrimitiveInsidePoly(object argPrimitive);
| Parameter | Type | Passing |
|---|---|---|
argPrimitive | IPCB_Primitive | value |
Returns: bool
The first overload is an extension method of IPCB_PolygonHelper (using PCB;) with typed parameters; the second is declared by the interface.
Returns true when the primitive's reference point is inside the outline and the primitive does not touch any of the outline's segments.
Rebuild
Repours the polygon, regenerating its child copper.
void Rebuild();
Returns: nothing (void)
On a board outline (IPCB_BoardOutline) it rebuilds the outline instead and deletes all of the outline's bending lines.
See also: IPCB_BoardOutline
RotateAroundXY
Rotates the polygon about the given point.
void RotateAroundXY(int argX, int argY, double argngle);
| Parameter | Type | Passing | Description |
|---|---|---|---|
argX | int | value | The X coordinate of the point to rotate about, in internal units (10,000 per mil). |
argY | int | value | The Y coordinate of the point to rotate about, in internal units (10,000 per mil). |
argngle | double | value | The rotation angle, in degrees. |
Returns: nothing (void)
SetState_AutoNameInvalidate
Marks the polygon's automatically generated name as out of date.
void SetState_AutoNameInvalidate();
Returns: nothing (void)
SetState_CopperPourInvalid
Marks the polygon's pour as out of date.
void SetState_CopperPourInvalid();
Returns: nothing (void)
CopperPourValidate then repours the polygon.
SetState_CopperPourValid
Marks the polygon's pour as up to date.
void SetState_CopperPourValid();
Returns: nothing (void)
SetState_XSizeYSize_1
Recalculates the polygon's bounding rectangle and AreaSize from its outline.
bool SetState_XSizeYSize_1();
Returns: bool
Returns true. The examples call it after assigning PointCount and Segments of a board outline.
XBoundingRectangle
Returns the bounding rectangle of the polygon's outline.
CoordRect XBoundingRectangle();
Returns: CoordRect
Extension method of IPCB_PolygonHelper (using PCB;).
Inherited members
- From IPCB_Group: AddPCBObject, FastSetState_XSizeYSize, FreePrimitives, GetPrimitiveAt, GetPrimitiveCount, GroupIterator_Create, GroupIterator_Destroy, LayerUsed, PrimitiveLock, RemovePCBObject, ReplicateWithChildren, SetState_LayersUsedArray, SetState_XSizeYSize, XLocation, YLocation
- 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, Identifier, 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
Returned by
IPCB_BoardEx.GetVoidsOnPlaneLayer, IPCB_Primitive.Polygon
Accepted by
IPCB_ContourMaker.MakeContour_8, IPCB_ContourMaker2.MakeContour_18