Working with legends in Mechanical scripting

In 2020R2, new ACT features have been released to expose legend settings.

Legend Settings can either be Global (common to all results) or result specific. You can use the following Legend Settings objects to perform various operations like: • Modify the behavior and appearance of a legend being displayed on screen • Construct an independent Legend Settings object and apply it to the current result • Copy the Legend Settings from one result object and apply it to another result. There are examples later in the document to illustrate the same.

1. Global Legend Settings

Graphics.GlobalLegendSettings # Access these settings
LegendOrientation   # Gets or sets the Legend Orientation.
ShowDateAndTime # Gets or sets whether the date and time is shown.
ShowMaxMin  # Gets or sets whether the Min and Max value are shown.
ShowDeformationScaling  # Gets or sets whether the Deformation Scaling is shown.

Example: Changes the legend orientation to horizontal and hides the deformation scaling:

gls = Graphics.GlobalLegendSettings
gls.LegendOrientation = LegendOrientationType.Horizontal
gls.ShowDateAndTime = True
gls.ShowMaxMin = True
gls.ShowDeformationScaling = False

2. Result specific Legend Settings

Some of the legend settings are specific to each result object. To access these settings, you must first navigate to the result you want to manipulate and use this command:

Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings()

Note: You can only manipulate the legend of the currently active result.

The following properties are available within this object:

NumberOfBands   # Gets or sets the number of bands on the legend
AllScientificNotation   # Gets or sets whether the result values are displayed in scientific notation
Digits  # Gets or sets the number of significant digits
ColorScheme # Gets or sets the Color Scheme for the legend.
SemiTransparency    # Gets or sets whether the legend is semi-transparent.
LogarithmicScale    # Gets or sets whether the result values are distributed in a Logarithmic scale.
HighFidelity    # Gets or sets whether the High Fidelity mode is on.
GetLowerBound   # Gets lower bound value of the specified band.
SetLowerBound   # Sets lower bound value of the specified band.
GetUpperBound   # Gets upper bound value of the specified band.
SetUpperBound   # Sets upper bound value of the specified band.
GetBandColor    # Gets the color of the specified band.
SetBandColor    # Sets the color of the specified band.
GetBandColorAuto    # Gets whether the specified band is set to Automatic or not.
SetBandColorAuto    # Sets the specified band to Automatic.
ResetColors # Resets all colors to default values.
Reset   # Resets all legend customizations into default values.

Example:

legendSettings = Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings()
legendSettings.AllScientificNotation = False
legendSettings.Digits = 4
legendSettings.NumberOfBands = 7 
legendSettings.ColorScheme = LegendColorSchemeType.ReverseGrayScale
legendSettings.SemiTransparent = True
legendSettings.SetLowerBound(0, Quantity(2.38e-8,”m”))
legendSettings.SetUpperBound(0, Quantity(3.38e-8,”m”))
legendSettings.SetUpperBound(1, Quantity(4.38e-8,”m”))
legendSettings.SetUpperBound(2, Quantity(5.38e-8,”m”))
legendSettings.SetBandColor(0, Ansys.Mechanical.DataModel.Constants.Colors.Gray)
legendSettings.SetBandColor(1, Ansys.Mechanical.DataModel.Constants.Colors.Blue)
legendSettings.SetBandColor(2, Ansys.Mechanical.DataModel.Constants.Colors.Cyan)
legendSettings.SetBandColor(3, Ansys.Mechanical.DataModel.Constants.Colors.Green)
legendSettings.SetBandColor(4, Ansys.Mechanical.DataModel.Constants.Colors.Yellow)
legendSettings.SetBandColor(5, Ansys.Mechanical.DataModel.Constants.Colors.Red)
legendSettings.SetBandColor(6, Ansys.Mechanical.DataModel.Constants.Colors.White)

3. Standalone Legend Settings

You can create a standalone Legend Settings object, modify the properties on it and then copy it onto an existing result object.

You create the standalone legend by:

legendSettings = Ansys.Mechanical.Graphics.Tools.LegendSettings()

or:

legendSettings = Ansys.Mechanical.Graphics.Tools.LegendSettings(“mm”)

if you want to assign a default unit system to this legend settings object.

The standalone LegendSettings comes with a default set of band values (from 0 to 9) and a default color scheme (Rainbow). You can set or modify any other properties that you care about.

It is also possible to set the Min and Max for the standalone legend. (to mimic the result Min and Max of a result):

legendSettings.Min = Quantity(1,”m”) 
legendSettings.Max = Quantity(100,”m”)

4. Copying Legends

You can copy the current result’s legend onto a standalone Legend Settings object. Similarly, you can create a standalone Legend Settings object and then copy it onto a current result. These capabilities allow you to reuse a set of legend settings in various places.

The following methods are available for these copy operations:

MakeCopy()  # Returns a standalone LegendSettings object that is a copy of the current result’s legend
CopyTo()    # Copies a standalone LegendSettings object onto the current result’s legend

Example:

# Navigate to a Total deformation object
totalDeform = DataModel.GetObjectsByName("Total Deformation")[0]
# Make a copy of its legend settings
totDefLegend = Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings().MakeCopy()

Example:

# Create a standalone legend settings object 
legendSetting = Ansys.Mechanical.Graphics.Tools.LegendSettings()
legendSetting.NumberOfBands = 3
legendSetting.SetBandColor(1, Ansys.Mechanical.DataModel.Constants.Colors.Red)

# Navigate to a result object
totalDeform = DataModel.GetObjectsByName("Total Deformation")[0]
totalDeform.Activate()

# Copy the standalone legend to this result
legendSetting.CopyTo(Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings())

These copy operations can also be used for copying legends between different results.

Example: This code copies the legend from one result object onto another

# Navigate to a result object
eqvStress = DataModel.GetObjectsByName("Equivalent Stress")[0]
eqvStress.Activate()

# Make a copy of its legend settings
eqvStressLegend = Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings().MakeCopy()

# Navigate to a different result object
principalStress = DataModel.GetObjectsByName("Maximum Principal Stress")[0]
principalStress.Activate()

# Copy the previous legend to this result

eqvStressLegend.CopyTo(
Ansys.Mechanical.Graphics.Tools.CurrentLegendSettings())

  5. Miscellaneous Global View Options

These are some miscellaneous global view options. They can be accessed using this command:

Graphics.ViewOptions

The various properties under this object are:

ShowLegend  #Gets or sets whether the legend is shown.
ShowTriad   #Gets or sets whether the triad is shown.
ShowRuler   #Gets or sets whether the ruler is shown.

Example: The example below hides the ruler and the triad and shows the legend:

Graphics.ViewOptions.ShowRuler = False
Graphics.ViewOptions.ShowLegend = True
Graphics.ViewOptions.ShowTriad = False