The Viewer displays all model objects and conditions as symbols, either vector symbols or raster symbols. This symbology system is made up of four types of symbols (with the indicated symbol identifier (SIN) range):

Firm and Hard symbols are generally used for linear objects like conductors, roads, and boundaries. Soft, pixmap, and SVG symbols are generally used for devices (switches, transformers, shunt devices, etc.) and other "point" devices.

Firm symbols have an eight digit SIN based on the pattern: TTTLSDCC. Each digit defines an aspect of the 1D symbol that is drawn in the Viewer.

Firm symbols are indicated by SINs ranging from 30000 to 99999.

L: Long Dash Length. The long dash length is the continuous part of the line between the spaces and short dashes, if any. This digit determines how many pixels the long dash will be. It must be 3 or greater to classify as a firm symbol.

S: Space Length. The space length is the gap between long dashes and short dashes. This digit defines the space’s pixel length as 2*S. An S value of zero results in a solid line even when the dash pattern is greater than zero.

 

D: Dash Pattern. The short dash pattern defines the number and size of short dashes in the line. There can be from zero to three short dashes in each line pattern. The short dashes can be one pixel points, space sized dashes or double space sized dashes.

 

CC - Color Code. The line color is specified by a two digit color code.

 

Hard symbols have an eight digit SIN based on the pattern: TTT0LLCC.

Hard symbols are indicated by SINs ranging from 100 to 2100; if the SIN is less than 1000, assume a zero before the first digit.

LL: Line style. Choose a line style number based on the desired dash pattern and background color. Dash pattern refers to the alternating number of pixels to draw of specified color and background color. The first number draws the prescribed color, CC; the second number draws the background color; the third number, if any, draws the prescribed color and so on.

 

CC: Color Code. The color codes are the same as those listed under firm symbols. Use the color code to prescribe the foreground color of the dash pattern. The SIN 106 is drawn in the Viewer as a solid blue line. The SIN 1614 is drawn in the Viewer as a dashed line with 50 pixels of purple, 10 pixels of gray30, 10 pixels of purple and 10 pixels of gray30.

The width multiplier increases the thickness of the firm or hard 1D symbol. Add one or more digits ranging from 1 to 29999 to the base SIN to increase the width of the line drawn on the Viewer. The multiplier increases the width of the line proportionally to the map scale so that the line width increases and decreases with zoom level. If no multiplier is specified or if the multiplier is 1, the line width is always one pixel regardless of zoom level. The actual width of the symbol in pixels is calculated at run time. Note that the results of the multiplier vary with each model.

The width multiplier is added to the beginning or left side of the base SIN starting with the sixth digit. Since hard SINs only have four digits, a zero must be added prior to adding the multiplier. For example, 5001324 is a hard symbol with base SIN 1324. The width multiplier is 50. The extra zero is a placeholder only. The firm symbol 5045733 with base SIN 45733 also has a width multiplier of 50. Divide the symbol id number by 100,000 to determine the width multiplier.

Soft symbols are classified as a point or line. There is no graphic editor for the soft symbols, which are considered to be legacy symbols and customers are encouraged to move to SVG symbols. They are indicated by SINs ranging from 2101 to 29999. Symbol definitions, in the [project]_SYMBOLS.sym file, have a regular pattern consisting of a header and a body. The first line of the header is called the header line and is followed by additional required key attribute lines.

The first header line begins with SH and is then followed by the symbol type, symbol code, and the symbol name:

Anchor points determine the default focus point for line and point symbols.

Once the drawing coordinates are determined, the symbol is scaled and rotated around its focus point.

A required record that defines the first anchor point of a line symbol or the only anchor point for a point symbol.

A required record that defines the colors used for filled objects and double dash lines. The foreground color for filled objects is the line color and the background color is the fill color, but can be configured to use any RGB color.

The first line of the symbol body contains only SB, which denotes that the symbol header has ended and the symbol body definition is beginning. Each subsequent line in the symbol body defines a new aspect of the soft symbol, including color changes, line style changes, draw actions, and movements.

The following sections describe valid actions for the symbol body.

Sets the pen to a specified color that cannot be overridden by the Viewer selection color. If a symbol drawn with this pen is selected in the Viewer, it does not blink or change colors.

Sets the pen to a specified color that can be overridden by the Viewer selection color. If a symbol drawn with this pen is selected in the Viewer, it blinks or changes color.

Specifies the line width. The results of this value varies for each model.

Sets the line style and dash pattern.

Valid values for [line_style_number] are:

The [length] parameters are optional. They specify the segment lengths for the dash pattern. There can be many [length] parameters, but the last one must be equal to zero.

Draws a line symbol between two points (x1, y1) and (x2, y2).

Draws a filled circle with center (x, y) and a specified radius.

Draws an open circle with center (x, y) and a specified radius.

 

 

Draws a filled box between the opposite corners, (x1, y1) and (x2, y2), with the specified angle of rotation.

Draws an open box between the opposite corners, (x1, y1) and (x2, y2), with the specified angle of rotation.

Sets the height and width of the text at a specified justification. Vertical and horizontal justification have the following values:

The text is drawn with the 'T' record, but the 't' record must be defined first.

 

Draw a diagonal line with a white pen color; define text attributes with vertical justification = 0 and horizontal justification = 0

Draws the text, "[string]", at (x, y). The text formatting is defined by the 't' record and must be defined prior to the 'T' record.

Defines the first coordinate for a filled polygon. This record must precede the 'P' action.

Defines the next coordinate for a filled polygon. Use this action to specify as many points as necessary. This record follows the ‘M’ action and precedes the ‘F’ action.

Defines the last coordinate for a filled polygon. This record follows the ‘P’ action and is the same as the ‘M’ action. It finishes and fills the polygon.

Draws a circular arc at (x, y) with radius from begin angle to end angle.

Defines the scaled line width as a percentage of the distance between anchor points.

No scale option for lines, circles, boxes or polygons. This must be defined on the same line as the object this record applies to.

Overrides the default focus point of a line, circle, box or polygon. This must be defined on the same line as the scaled object this record applies to.

Adds a tooltip that is activated when the user’s mouse hovers over the symbol.

Here are the base device symbols for the major device class types. Note that these examples are all 3-phase (ABC), nominally closed, and currently closed. Open symbols are green, and off-nominal symbols include a ring around them. Partially open symbols are yellow.

 

Use $NMS_CONFIG/jconfig/ops/viewer/properties/RasterSymbols.properties to specify the image file to use for a given symbol.

For example:

SVG symbols offer more complicated device, condition, and outage symbols than the standard .sym symbols, and can be edited and enhanced more easily using standard tools.

To use SVG symbols, add your .svg symbol files to your $NMS_CONFIG/jconfig/ops/viewer/images directory and add references to them to the $NMS_CONFIG/jconfig/ops/viewer/properties/SVGSymbols.properties file.

The SVGSymbols.properties file maps the SYMBOLOGY_STATE.symbology_id, CONDITION_RULES.symbol_num, ANALOG_RULES.symbol_num, or QUALITY_RULES.symbol_num database symbol numbers to a .svg symbol file. If you use a selection symbol, the symbol will define the complete visualization of the selected symbol and the viewer.selected_color value will have no impact on the selection symbol.

For example:

SVG symbols have a default selection capability in the Viewer that highlights the symbol when selected using the VIEWER_GLOBAL_PROPERTIES.inc file's viewer.selected_color StringProperty (configured to be orange in product). You can specify a selection symbol to use for any given symbol by adding a comma and then the selected symbol name to the properties record. For example:

 

To scan the .svg files in the $NMS_CONFIG/jconfig/ops/viewer/images directory and update the SVGSymbols.properties file, perform the following commands:

The script will scan the .svg files in the current directory/path, remove any previously auto-generated records in the SVGSymbols.properties file, and add in all new records found in the scan. It will use the Identifier attribute with a string in this format: urn:symid: iiiiiiiiii, where iiiiiiiiii is the symbology Id to associate with this symbol.

The SVG [title] element is used for hover text when the symbol is visualized in the Viewer.

 

In InkScape, the title is specified in the Document Metadata panel’s Title field:

 

 

 

Anchor points can be optionally hidden when drawn in the Viewer by using the Object Fill and Stroke panel and setting the Fill and Stroke Paint Opacity levels to zero. Do not set the Object Properties Hide check box since this will hide the anchor points from the Viewer, which will not know that the anchor points exist.

For condition symbols, SVG symbols work well if you follow these rules:

Natively, Inkscape’s text tool adds a non-standard SVG element that is not supported by the Viewer (or any standard SVG viewer). Therefore, when using Inkscape to create SVG symbols with text, you must convert the text with Inkscapes text conversion option.

The following example demonstrates the process of adding text, converting the text to a standard SVG element, and validating the file using the Apache Batik SVG Toolkit’s Squiggle viewer.

The SVG Master Symbol process generates all required variations (for example, open, closed) of a switchable device symbol from one master symbol definition. The master symbol’s metadata contains the symbol variation variables that are passed to a script that generates the permutations (svg‑symbol‑generator). The process is automated with a script that reads the master symbol directory and generates all symbol permutations (autoSvgGenerator).

The autoSvgGenerator script generates SVG symbols from master symbol files located in the $NMS_CONFIG/jconfig/ops/viewer/images/master directory. The generated .svg files are saved to the $NMS_CONFIG/jconfig/ops/viewer/images/auto-gen directory in sub-directories for each class name (for example, fuses, switches).

The master symbol .svg file requires the object IDs set as specified by the svg‑symbol‑generator -help information and an additional text string in the master .svg metadata description attribute with the following format:

These values are passed to the respective svg‑symbol‑generator command parameters (see “svg‑symbol‑generator Script”).

If the <normallyOpenTensDigit> is specified, autoSvgGenerator executes svg‑symbol‑generator a second time using the [normalOpenTensDigit] value rather than the -tens parameter and, optionally, the ‑normalopen parameter. This will use the inclusion of the symbols object with ObjectID = normal_open_indicator and mixed_status_indicator.

If the -normalopen parameter is not specified on the svg‑symbol‑generator, the ObjectID = normal_open_indicator and mixed_status_indicator will not be included in the resulting symbols.

For example, an overhead fuse (class name: fuse_oh/class number: 148) with a normally open tens digit of 5, would be defined as:

This script will read a single master file and generate the permutations. Format of the command is:

Command parameters:

The master symbol contains all the symbol objects for all permutations of the symbol. Each object that might have its visibility or color manipulated based on phases and status will be given an object ID based on the following:

The following three IDs will place the object based on phase and will color them black if the status is open or closed on all phases and will color them opencolor/closedcolor if the status is mixed

 

The following three IDs will place the object based on phase and will color them opencolor/closedcolor

 

The following three IDs will place the object based on phase and will not color them based on status

 

 

 

The following three IDs will place the object based on phase and will not color them based on status

 

The following three IDs will place the object based on phase and will color them opencolor/closedcolor

 

The following three IDs will place the object based on phase and will not color them based on status

The following three IDs will place the object based on phase and will color them opencolor/closedcolor

 

The following ID will color the gradient object based on status

 

The following ID will color the filled object based on status

 

The following ID will color the line object based on status

 

The following ID will place the object if the status is abnormal

 

The following ID will place the object if it is normally open

The following ID will place the object if its status is mixed

 

The following IDs two will identify the anchor points if the device is open

 

 

Example running the script:

The nms‑sym‑to‑svg script converts .sym files to .svg files. The script will create one .svg file for each .sym symbology preserving the symbology name, ID, anchor points, and all graphic components.

Usage: nms‑sym‑to‑svg [sym_file] [hideanchors] [createselectionsymbols [colornum]] [oversizecanvas [percentage]] [[symId]]

 

where:

 

To convert your sym files, perform the following steps:

 

SVG symbols open up many possibilities to symbol creativity however, complex symbols can cause NMS Viewer performance issues too. There are two tools to help the project team to measure SVG symbol rendering performance:

Both tools require a display to be available to render the symbols, please specify a DISPLAY location before running the commands.

The svgTestSymbolPerformance script has the following parameters:

Enter the following commands:

The system will output:

The svgTestSymbolPerformanceReport has the following parameters:

Enter the following commands:

 

We can clearly see the OPAL_Service_Truck takes a long time to render in larger pixel renderings. This can cause issues with high-resolution displays, such as 4K monitors. Consider simplifying this symbol to minimize any performance impacts.

After the symbology file has been updated and the svg files have been installed, the following command will update the java application server:

Any running clients will need to be restarted to pick up the new symbology.

The SYMBOLOGY_STATE database table contains the mapping from each device's symbology class, state, and off-nominal status to the symbol used for it.

The QUALITY_RULES database table contains the mapping from device class and quality code to the desired symbol or text.

The CONDITION_RULES database table contains the mapping from device class and condition type to the desired symbol.

 

If there are multiple conditions of the same type on a device, the symbol will normally stack on the device in the Viewer. For example, if you have two Notes on a device, two Notes symbols will be displayed. If you would rather have multiple occurrences of a condition display as a single symbol with the count adjacent, you can add those condition classes to the condition_aggregate_symbols (in [project]_inheritance.dat).