IscDiagram
- class ipsa.IscDiagram
The
IscDiagramclass provides access to graphical data on a single IPSA diagram. These functions allow network components to be drawn, display options to be set and deleted.The creation of items on the diagram also creates the associated network components. The parameters of these components can then be set using the functions described for the particular component types.
The origin for the co-ordinates is normally the top left corner of the diagram. Positive values of X are to the right whilst positive values of Y are down below the origin.
- SetName(strName: str) None
Sets the name of the diagram.
- Parameters:
strName (str) – The name of the diagram.
- CreateBusbarPoint(strName: str, dX: float, dY: float) int
Creates a new busbar component on the diagram. A point busbar symbol is a small dot which does not resize as the diagram zoom level is changed.
- CreateBusbarJunction(strName: str, dX: float, dY: float) int
Creates a new busbar component on the diagram. A junction busbar symbol is the circular junction symbol.
- CreateBusbarHexagonal(strName: str, dX: float, dY: float) int
Creates a new busbar component on the diagram. A hexagonal busbar symbol has six sides.
- CreateBusbarCircular(strName: str, dX: float, dY: float) int
Creates a new busbar component on the diagram. A circular busbar symbol is a circle.
- CreateBusbarRectangular(strName: str, bHorizontal: bool, dX: float, dY: float) int
Creates a new busbar component on the diagram. The rectangular symbol is the standard horizontal or vertical busbar.
- DrawBusbarPoint(nUID: int, dX: float, dY: float) bool
Draws an existing busbar component on the diagram as defined by the busbar UID. A point busbar symbol is displayed as a small dot which does not resize as the diagram zoom level is changed.
Note this will only have an effect if the busbar is not already drawn.
- DrawBusbarJunction(nUID: int, dX: float, dY: float) bool
Draws an existing busbar component on the diagram as defined by the busbar UID. A junction busbar symbol is the solid circular junction symbol.
Note this will only have an effect if the busbar is not already drawn.
- DrawBusbarHexagonal(nUID: int, dX: float, dY: float) bool
Draws an existing busbar component on the diagram as defined by the busbar UID. The hexagonal symbol is the standard filled hexagonal busbar.
Note this will only have an effect if the busbar is not already drawn.
- DrawBusbarRectangular(nUID: int, bHorizontal: bool, dSize: float, dX: float, dY: float) bool
Draws an existing busbar component on the diagram as defined by the busbar UID. The rectangular symbol is the standard horizontal or vertical busbar.
Note this will only have an effect if the busbar is not already drawn.
- Parameters:
- Returns:
Boolean denoting whether the busbar was drawn.
- Return type:
- DrawBusbarCircular(nUID: int, dSize: float, dX: float, dY: float) bool
Draws an existing busbar component on the diagram as defined by the busbar UID. The circular symbol is the larger unfilled circle.
Note this will only have an effect if the busbar is not already drawn.
- CreateLine(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Deprecated in IPSA 2.10.2. Instead, use CreateBranch.
Creates a new branch component on the diagram.
- Parameters:
strName (str) – The branch name.
dXFrom (float) – The x coordinate of the busbar where the branch starts.
dYFrom (float) – The y coordinate of the busbar where the branch starts.
dXTo (float) – The x coordinate of the busbar where the branch ends.
dYTo (float) – The y coordinate of the busbar where the branch ends.
- Returns:
The unique positive ID of the new branch. A negative value is returned if the “from” end busbar is not found, and zero is returned if the “to” end busbar is not found.
- Return type:
- CreateBranch(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Creates a new branch component on the diagram.
- Parameters:
strName (str) – The branch name.
dXFrom (float) – The x coordinate of the busbar where the branch starts.
dYFrom (float) – The y coordinate of the busbar where the branch starts.
dXTo (float) – The x coordinate of the busbar where the branch ends.
dYTo (float) – The y coordinate of the busbar where the branch ends.
- Returns:
The unique positive ID of the new branch. If the branch cannot be drawn, the return value is 0.
- Return type:
- DrawLine(nUID: int) bool
Draws the symbol for the line identified by the unique ID. The line is drawn as a single segment between two busbars.
Note this will only have an effect if the line is not already drawn.
- CreateBreaker(strName: str, dX: float, dY: float) int
Creates a new circuit breaker on the diagram. Note branch has to have already been drawn.
- DrawBreaker(nBreakerUID: int, dX: float, dY: float) bool
Draws the symbol for the breaker identified by the unique ID nBreakerUID at the location dX,dY.
- CreateTransformer(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Deprecated in IPSA 2.10.2. Instead, use Create2WTransformer.
Creates a new transformer component on the diagram.
- Parameters:
strName (str) – The branch name.
dXFrom (float) – The x coordinate of the busbar where the branch starts.
dYFrom (float) – The y coordinate of the busbar where the branch starts.
dXTo (float) – The x coordinate of the busbar where the branch ends.
dYTo (float) – The y coordinate of the busbar where the branch ends.
- Returns:
The unique positive ID of the new transformer. A negative value is returned if the “from” end busbar is not found, and zero is returned if the “to” end busbar is not found.
- Return type:
- Create2WTransformer(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Creates a new transformer component on the diagram.
- Parameters:
strName (str) – The transformer name.
dXFrom (float) – The x coordinate of the busbar where the transformer starts.
dYFrom (float) – The y coordinate of the busbar where the transformer starts.
dXTo (float) – The x coordinate of the busbar where the transformer ends.
dYTo (float) – The y coordinate of the busbar where the transformer ends.
- Returns:
The unique positive ID of the new transformer. If the transformer cannot be drawn, the return value is 0.
- Return type:
- DrawTransformer(nUID: int) bool
Draws the symbol for the transformer identified by the unique ID. The transformer is drawn as a single segment between two busbars.
Note this will only have an effect if the transformer is not already drawn.
- CreateUnbalancedLine(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Deprecated in IPSA 2.10.2. Instead, use CreateUnbalancedBranch.
Creates a new unbalanced line component on the diagram.
- Parameters:
strName (str) – The unbalanced line name.
dXFrom (float) – The x coordinate of the busbar where the branch starts.
dYFrom (float) – The y coordinate of the busbar where the branch starts.
dXTo (float) – The x coordinate of the busbar where the branch ends.
dYTo (float) – The y coordinate of the busbar where the branch ends.
- Returns:
The unique positive ID of the new unbalanced line component. A negative value is returned if the “from” end busbar is not found, and zero is returned if the “to” end busbar is not found.
- Return type:
- CreateUnbalancedBranch(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Creates a new unbalanced line component on the diagram.
- Parameters:
strName (str) – The unbalanced line name.
dXFrom (float) – The x coordinate of the busbar where the unbalanced line starts.
dYFrom (float) – The y coordinate of the busbar where the unbalanced line starts.
dXTo (float) – The x coordinate of the busbar where the unbalanced line ends.
dYTo (float) – The y coordinate of the busbar where the unbalanced line ends.
- Returns:
The unique positive ID of the new unbalanced line component. If the unbalanced line cannot be drawn, the return value is 0.
- Return type:
- CreateUnbalancedTransformer(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Deprecated in IPSA 2.10.2. Instead, use CreateUnbalanced2WTransformer.
Creates a new unbalanced transformer component on the diagram.
- Parameters:
strName (str) – The unbalanced transformer name.
dXFrom (float) – The x coordinate of the busbar where the branch starts.
dYFrom (float) – The y coordinate of the busbar where the branch starts.
dXTo (float) – The x coordinate of the busbar where the branch ends.
dYTo (float) – The y coordinate of the busbar where the branch ends.
- Returns:
The unique positive ID of the new unbalanced transformer component. A negative value is returned if the “from” end busbar is not found, and zero is returned if the “to” end busbar is not found.
- Return type:
- CreateUnbalanced2WTransformer(strName: str, dXFrom: float, dYFrom: float, dXTo: float, dYTo: float) int
Creates a new unbalanced transformer component on the diagram.
- Parameters:
strName (str) – The unbalanced transformer name.
dXFrom (float) – The x coordinate of the busbar where the unbalanced transformer starts.
dYFrom (float) – The y coordinate of the busbar where the unbalanced transformer starts.
dXTo (float) – The x coordinate of the busbar where the unbalanced transformer ends.
dYTo (float) – The y coordinate of the busbar where the unbalanced transformer ends.
- Returns:
The unique positive ID of the new unbalanced transformer component. If the unbalanced transformer cannot be drawn, the return value is 0.
- Return type:
- AddPointToLine(nLineUID: int, dX: float, dY: float, bFromEnd: bool, bRefreshLine: bool) bool
Adds a knee point to the line identified by the unique ID. By default, this function will fully redraw the line the knee point has been added to. This can be disabled by setting bRefreshLine to False. The kneepoint will be added nearest to the line centrepoint on the from or to end.
Deprecated in IPSA 2.10.3 instead use AddKneepoint
- Parameters:
nLineUID (int) – The line UID.
dX (float) – The knee point x coordinate.
dY (float) – The knee point y coordinate.
bFromEnd (float) – If True then the knee point is added to the last segment, i.e. furthest from the From end. If False then the knee point is added to the first segment.
bRefreshLine (bool) – Defaults to True. If True, the line is fully redrawn when the knee point is added.
- Returns:
Boolean denoting whether the knee point was added.
- Return type:
- AddKneepoint(nLineUID: int, dX: float, dY: float, bFromEnd: bool, bRefreshLine: bool) bool
Adds a knee point to the line identified by the unique ID. By default, this function will fully redraw the line the knee point has been added to. This can be disabled by setting bRefreshLine to False. The kneepoint will be added nearest to the line centrepoint on the from or to end.
- Parameters:
nLineUID (int) – The line UID.
dX (float) – The knee point x coordinate.
dY (float) – The knee point y coordinate.
bFromEnd (float) – If True then the knee point is added to the last segment, i.e. furthest from the From end. If False then the knee point is added to the first segment.
bRefreshLine (bool) – Defaults to True. If True, the line is fully redrawn when the knee point is added.
- Returns:
Boolean denoting whether the knee point was added.
- Return type:
- AddKneepoints(nLineUID: int, listX: List[float], listY: List[float], bFromEnd: bool, bRefreshLine: bool) bool
Adds multiple knee points to the line identified by the unique ID. By default, this function will fully redraw the line the knee point has been added to. This can be disabled by setting bRefreshLine to False. The kneepoints will be added in order of from end to to end.
If listX and listY are not of the same length, no kneepoints will be added.
- Parameters:
nLineUID (int) – The line UID.
listX (list(float)) – A list of x coordinates for each knee point to be added.
listY (list(float)) – A corresponding list of y coordinates for each knee point to be added.
bFromEnd (float) – If True then the knee point is added to the last segment, i.e. furthest from the From end. If False then the knee point is added to the first segment.
bRefreshLine (bool) – Defaults to True. If True, the line is fully redrawn when the knee point is added.
- Returns:
Boolean denoting whether the knee points were added.
- Return type:
- DeleteKneepoint(nLineUID: int, dX: float, dY: float) bool
Deletes a specific knee point from the line identified by the unique ID. If no kneepoint is found at the provided coordinates, nothing will occur.
- DeleteAllKneepoints(nLineUID: int) bool
Deletes all the knee points from the line identified by the unique ID.
- RefreshLine(nLineUID: int) None
Redraws the line identified by the line UID after knee points have been added.
- Parameters:
nLineUID (int) – The line UID.
- SplitBranch(nLineUID: int, nSection: int, dRatio: float, strName: str) int
Deprecated. Instead, use IscNetwork.SplitBranch. Splits a branch into two sections connected by a new busbar. This will only act if the branch is only drawn in this IscDiagram instance.
- Parameters:
nLineUID (int) – The line UID.
nSection (int) – Specifies which section of a multi-section branch is split. For branches with only one section then nSection should be set to 0.
dRatio (float) – Specifies how the branch impedances are divided between the new branches. A value of 0.0 sets the split position to be at the “From” end whilst a value of 1.0 specifies the “To” end. Values between 0.0 and 1.0 split the branch in proportion. For multi-section branches dRatio splits the section identified by nSection.
strName (str) – The name of the busbar.
- Returns:
The UID of the new branch if it is greater than 0. ) if the branch has not been split. This is because there is a circuit breaker on the branch or the branch is drawn on more than one diagram.
- Return type:
- DrawRadial(nRadialUID: int, dX: float, dY: float) bool
Draws the symbol for the radial object (i.e., an object connected to one busbar only) identified by the unique ID nRadialUID. The radial symbol will be drawn at the location dX,dY and connected to its busbar.
Note this function will return false if the provided UID is not a radial or is already drawn.
- DrawBranchItem(nBranchItemUID: int) bool
Draws the symbol for the branch item object (i.e., an object connected to exactly two busbars) identified by the unique ID nBranchItemUID. The branch item will be drawn as a straight line between its busbars.
Note this function will return false if the provided UID is not a branch item or is already drawn.
- Draw3Port(n3PortUID: int, dX: float, dY: float) bool
Draws the symbol for the 3Port object (i.e., an object connected to exactly three busbars) identified by the unique ID nRadialUID. The 3Port symbol will be drawn at the location dX,dY and connected with straight lines to its busbars.
Note this function will return false if the provided UID is not a 3Port component or is already drawn.
- DrawInline(nInlineUID: int, dX: float, dY: float) bool
Draws the symbol for the inline object (i.e., an object that sits upon a branch item) identified by the unique ID nInlineUID. The inline symbol will be drawn on its branch at the nearest point to the location dx,dY.
Note this function will return false if the provided UID is not an inline or is already drawn.
- MoveItemCentre(nItemUID: int, dX: float, dY: float) bool
Moves the item specifed by nItemUID to the location dX,dY. For busbars this will relocate the busbar (bringing its connected radials). For radials and 3Ports this will relocate the symbol of the object, leaving its busbars inplace. For inlines this will move the inline to the point on its branch closest to the specified point. For branch items this will move the branch as close to the specified point as possible if the branch is free to move.
Note this function will return false if the provided UID is not already drawn.
- DrawUndrawnItemsAttachedToBusbar(nBusbarUID: int) None
Draws items attached to the busbar identified by the busbar UID if they are not already drawn on the diagram. Note that this will draw branch items as well.
- Parameters:
nBusbarUID (int) – The busbar UID.
- DeleteItem(nUID: int) bool
Deletes the graphic item identified by the UID. This may be a line, radial component or busbar.
- GetLineLength(nUID: int) float
- GetLineLength(pComponent) float
Returns the component length for the graphic symbol on the current diagram. On geographic diagrams this function returns the actual line length, assuming that the diagram is correctly scaled.
- SetItemPenColour(nUID: int, nRed: int, nGreen: int, nBlue: int, nAlpha: int)
Sets the outline colour of the diagram object. The colour is set by the RGB parameters. All colour parameters should be between 0 and 255.
- SetItemBrushColour(nUID: int, nRed: int, nGreen: int, nBlue: int, nAlpha: int)
Sets the fill colour of the diagram object. The colour is set by the RGB parameters. All colour parameters should be between 0 and 255.
- MapToLatLong(dDiagramX: float, dDiagramY: float) Tuple[float]
Returns the latitude and longitude in decimal degrees of the specified diagram pixel position. Note that the diagram X is south/north and diagram Y is east/west.
This function will return (0.0, 0.0) unless the diagram has a tiled geographic map.
- LatLongToMap(fN: float, fE: float) Tuple[float]
Returns the diagram pixel X and Y coordinates of the latitude and longitude. Note that the diagram X is south/north and diagram Y is east/west.
This function will return (0.0, 0.0) unless the diagram has a tiled geographic map.
- GetUIDFromCoordinates(dX: float, dY: float) int
Returns the UID of a component at coordinates (dX, dY).
- GetBusbarUIDFromCoordinates(dX: float, dY: float) int
Returns the UID of a busbar at coordinates (dX, dY).
- GetItemX(nUID: int) float
Returns the diagram X coordinate of the specified item. Note for branches and transformers this will return the midpoint of the object.
- GetItemY(nUID: int) float
Returns the diagram Y coordinate of the specified item. Note for branches and transformers this will return the midpoint of the object.
- GetItemFromXPoints(nUID: int) List[float]
Returns a list of floats for the diagram X coordinates of the edge of the FROM busbar, the middle point of the line or the edge of the central graphic and all knee points lying on the branch item between these two points. The coordinates are for the FROM end of the line.
- GetItemFromYPoints(nUID: int) List[float]
Returns a list of floats for the diagram Y coordinates of the edge of the FROM busbar, the middle point of the line or the edge of the central graphic and all knee points lying on the branch item between these two points. The coordinates are for the FROM end of the line.
- GetItemToXPoints(nUID: int) List[float]
Returns a list of floats for the diagram X coordinates of the edge of the TO busbar, the middle point of the line or the edge of the central graphic and all knee points lying on the branch item between these two points. The coordinates are for the TO end of the line.
- GetItemToYPoints(nUID: int) List[float]
Returns a list of floats for the diagram Y coordinates of the edge of the TO busbar,the middle point of the line or the edge of the central graphic and all knee points lying on the branch item between these two points. The coordinates are for the TO end of the line.
- CreateAnnotation(strName: str, strAnnotationText: str, dX: float, dY: float) int
Creates a new diagram annotation.
- Parameters:
- Returns:
The diagram annotation.
- Return type:
- PrintPDF(strFileName: str, bRefreshDiagram: bool = True) None
Print the diagram to a PDF format file with name strFileName.
- SetLabelCharacteristics(nUID: int, bShowLabel: bool, bFixedSize: bool) bool
Sets whether the label for the component identified by the given UID is visible, and whether it scales with zoom. This can also be set from Data Display Styles.
- SetBackgroundColour(strHexColour: str) None
Sets the diagram background colour to the specified hex colour. strHexColour can either be set as a hex colour code (i.e., “#BA4675”) or as one of the SVG color keyword names.
- Parameters:
strHexColour (str) – The hex colour to set the diagram background to.
- SetBackgroundImage(dOpacity: float, strImageFile: str, dWidth: float, dHeight: float, bKeepAspectRatio: bool) None
Sets the background image of a diagram to the image found in strImageFile. The background image is displayed with the opacity defined by dOpacity, and the image size defined by dWidth and dHeight. If bKeepAspectRatio is set to True, dHeight is ignored, and the image is displayed with the width determined by dWidth and a height automatically calculated to maintain the image aspect ratio.
Note, if strImageFile is not a valid image path, the background image will be cleared.
- Parameters:
dOpacity (float) – The opacity of the background image in the range 0-1.
strImageFile (str) – The path to the new background image.
dWidth (float) – The pixel width the background image will be displayed with.
dHeight (float) – The pixel height the background image will be displayed with.
bKeepAspectRatio (bool) – If True, dHeight is auto-calculated to maintain the provided image aspect ratio.
- RefreshDiagram() None
Refreshes the diagram to ensure that the diagram window is up to date with the data held in IPSA.
- GetBusbarSize(nUID: int) float
Returns the size of the graphical item for the busbar identified by nUID. This will return 0.0 if the busbar isn’t found. Note this returns the radius of circular busbars.
- GetBusbarGraphicsType(nUID: int) int
Returns an int identifying what type of graphic the busbar identified by nUID is drawn with. This will return -1 if the busbar isn’t found. The busbar graphic types are:
0 = Horizontal rectangular
1 = Vertical rectangular
2 = Junction
3 = Circular
4 = Point
5 = Hexagonal
- IsGeographic() bool
Returns if the diagram is a geographic diagram or a single line diagram.
- Returns:
True if the diagram is a geographic diagram and false if it is an SLD.
- Return type:
- HasTiledGeographicMap() bool
Returns if the diagram has a tiled geographic map.
- Returns:
True if the diagram has a tiled geographic map.
- Return type:
- GetMapCentre() Tuple[float]
Returns the centre position of the map. Returns lat-long centre for diagrams with tiled geographic maps and (0,0) otherwise.