OpenSeesMatlabVis

plotter.OpenSeesMatlabVis

Bases: handle

OpenSeesMatlabVis Visualization interface for OpenSeesMatlab.

OpenSeesMatlabVis provides high-level plotting utilities for OpenSees models and analysis results. It is created automatically by OpenSeesMatlab and is normally accessed through the vis property:

  opsmat = OpenSeesMatlab();
  vis = opsmat.vis;

The visualization methods use model information collected by opsmat.post.getModelData or response/eigen data collected by the post-processing interface. Most plotting methods accept an optional opts struct and an optional target axes handle. Default option templates are exposed as public properties and can be copied before customization.

Common workflow

  opsmat = OpenSeesMatlab();
  ops = opsmat.opensees;

  % Build or load an OpenSees model with ops...
  % ops.wipe();
  % ops.model(...);

  modelInfo = opsmat.post.getModelData();
  hModel = opsmat.vis.plotModel();

  eigenData = opsmat.post.getEigenData(numModes=3);
  hMode1 = opsmat.vis.plotEigen(1, eigenData);

Properties:

• defaultPlotModelOptions (_tZ0Ul) –

  Default option template used by plotModel. See .help for details.

• defaultPlotEigenOptions (_m0re1) –

  Default option template used by plotEigen. See .help for details.

• defaultPlotNodalResponseOptions (_InSLM) –

  Default option template used by plotNodalResponse and plotDeformation. See .help for details.

• defaultPlotFrameResponseOptions (_mem9K) –

  Default option template used by plotFrameResponse. See .help for details.

• defaultPlotShellResponseOptions (_DqULf) –

  Default option template used by shell response plotting. See .help for details.

• defaultPlotContinuumResponseOptions (_h1YlZ) –

  Default option template used by continuum response plotting. See .help for details.

Methods:

• plotModel –

  Visualize the current OpenSees model.

• plotEigen –

  Visualize one mode shape from eigenvalue analysis results.

• plotNodalResponse –

  Visualize nodal response data at a selected analysis step.

• plotDeformation –

  Visualize deformed model geometry from nodal displacement data.

• plotFrameResponse –

  Visualize frame element response at a selected analysis step.

• plotShellResponse –

  Visualize Shell element response for a specific step.

• plotContinuumResponse –

  Visualize Plane or Solid continuum element response for a step.

Properties:

• defaultPlotModelOptions (None) –
• defaultPlotEigenOptions (None) –
• defaultPlotNodalResponseOptions (None) –
• defaultPlotFrameResponseOptions (None) –
• defaultPlotShellResponseOptions (None) –
• defaultPlotContinuumResponseOptions (None) –

defaultPlotModelOptions

defaultPlotModelOptions = plotter.PlotModel.defaultOptions()

defaultPlotEigenOptions

defaultPlotEigenOptions = plotter.PlotEigen.defaultOptions()

defaultPlotNodalResponseOptions

defaultPlotNodalResponseOptions = plotter.PlotNodalResp.defaultOptions()

defaultPlotFrameResponseOptions

defaultPlotFrameResponseOptions = plotter.PlotFrameResp.defaultOptions()

defaultPlotShellResponseOptions

defaultPlotShellResponseOptions = plotter.PlotUnstruResponse.defaultOptions()

defaultPlotContinuumResponseOptions

defaultPlotContinuumResponseOptions = plotter.PlotUnstruResponse.defaultOptions()

plotModel

(opts: struct = struct(), ax=[])

Visualize the current OpenSees model.

plotModel collects model information from the current OpenSees model through obj.parent.post.getModelData and renders the model geometry using plotter.PlotModel.

Syntax

h = vis.plotModel()
h = vis.plotModel(opts=opts)
h = vis.plotModel(ax=ax)
h = vis.plotModel(opts=opts, ax=ax)

Input arguments:

• opts (struct) –

  Visualization options passed to plotter.PlotModel. Start from vis.defaultPlotModelOptions when you want to customize the default model-plot appearance.

• ax (matlab.graphics.axis.Axes) –

  Target axes. If omitted or empty, a new figure/axes is created by the underlying plotter.

Output arguments:

• h ( array of graphics objects ) –

  Handles to the created graphics objects.

Example

opsmat = OpenSeesMatlab();
% Build model with opsmat.opensees...
h = opsmat.vis.plotModel();

opts = opsmat.vis.defaultPlotModelOptions;
figure;
ax = axes();
h = opsmat.vis.plotModel(opts=opts, ax=ax);

plotEigen

(modeTag: double, eigenData: struct, opts: struct = struct(), ax=[])

Visualize one mode shape from eigenvalue analysis results.

eigenData is usually collected with opsmat.post.getEigenData or loaded from a file generated by opsmat.post.saveEigenData.

Syntax

h = vis.plotEigen(modeTag, eigenData)
h = vis.plotEigen(modeTag, eigenData, opts=opts)
h = vis.plotEigen(modeTag, eigenData, ax=ax)
h = vis.plotEigen(modeTag, eigenData, opts=opts, ax=ax)

Input arguments:

• modeTag (integer) –

  Mode number to visualize. For example, modeTag=1 plots the first mode shape.

• eigenData (struct) –

  Eigenvalue analysis results, typically returned by opsmat.post.getEigenData.

• opts (struct) –

  Visualization options passed to plotter.PlotEigen. Start from vis.defaultPlotEigenOptions for customization.

• ax (matlab.graphics.axis.Axes) –

  Target axes. If omitted or empty, a new figure/axes is created.

Output arguments:

• h ( array of graphics objects ) –

  Handles to the created graphics objects.

Example

eigenData = opsmat.post.getEigenData(numModes=3);
h = opsmat.vis.plotEigen(1, eigenData);

opts = opsmat.vis.defaultPlotEigenOptions;
opts.deform.scale = 10;
h = opsmat.vis.plotEigen(2, eigenData, opts=opts);

plotNodalResponse

(nodeRespData: struct, respType="disp", respComponent="magnitude", stepIdx="absMax", opts: struct = struct(), ax=[])

Visualize nodal response data at a selected analysis step.

plotNodalResponse renders nodal scalar or vector response fields such as displacement, velocity, acceleration, reaction, Rayleigh force, or pressure. The model information is loaded from the ODB referenced by nodeRespData.odbTag.

Syntax

vis.plotNodalResponse(nodeRespData)
vis.plotNodalResponse(nodeRespData, respType=respType)
vis.plotNodalResponse(nodeRespData, respComponent=component)
vis.plotNodalResponse(nodeRespData, stepIdx=stepIdx)
vis.plotNodalResponse(nodeRespData, opts=opts, ax=ax)

Input arguments:

• nodeRespData (struct) –

  Nodal response data, typically obtained from opsmat.post.getNodalResponse(odbTag). The struct must include an odbTag field so the corresponding model information can be loaded.

• respType (string) –

  Response type to visualize. Default is "disp". Common values include "disp", "vel", "accel", "reaction", "reactionIncInertia", "rayleighForces", and "pressure".

• respComponent (string) –

  Response component to visualize. Default is "magnitude". For vector responses, common values include "ux", "uy", "uz", "rx", "ry", "rz", and "magnitude".

• stepIdx (integer or string) –

  Analysis step selector. Default is "absMax".

  • "absMax": step with the maximum absolute response.
  • "absMin": step with the minimum absolute response.
  • "Max": step with the maximum response.
  • "Min": step with the minimum response.
  • integer: explicit step index.
• opts (struct) –

  Visualization options passed to plotter.PlotNodalResp. Start from vis.defaultPlotNodalResponseOptions for customization.

• ax (matlab.graphics.axis.Axes) –

  Target axes. If omitted or empty, a new figure/axes is created.

Example

nodeRespData = opsmat.post.getNodalResponse("MyODB");
opsmat.vis.plotNodalResponse(nodeRespData);
opsmat.vis.plotNodalResponse(nodeRespData, ...
    respType="disp", ...
    respComponent="magnitude", ...
    stepIdx="absMax");

plotDeformation

(nodeRespData: struct, stepIdx="absMax", color: string = "blue", useInterpolation: logical = true, scaleFactor: double = 1.0, showUndeformed: logical = false, ax=[])

Visualize deformed model geometry from nodal displacement data.

plotDeformation is a convenience wrapper around the nodal response plotter. It enables deformation display, uses displacement data from nodeRespData, and allows direct control of deformation color, interpolation, scale factor, and undeformed-shape visibility.

Syntax

vis.plotDeformation(nodeRespData)
vis.plotDeformation(nodeRespData, stepIdx=stepIdx)
vis.plotDeformation(nodeRespData, color=color)
vis.plotDeformation(nodeRespData, useInterpolation=tf)
vis.plotDeformation(nodeRespData, scaleFactor=scale)
vis.plotDeformation(nodeRespData, showUndeformed=tf)
vis.plotDeformation(nodeRespData, ax=ax)

Input arguments:

• nodeRespData (struct) –

  Nodal response data containing displacement information, typically obtained from opsmat.post.getNodalResponse(odbTag). The struct must include an odbTag field.

• stepIdx (integer or string) –

  Analysis step selector. Default is "absMax". Supported string selectors include "absMax", "absMin", "Max", and "Min".

• color (char or string) –

  Solid color used for the deformed shape. Default is "blue".

• useInterpolation (logical) –

  Whether to use interpolation for smoother visualized deformation. Default is true.

• scaleFactor (double) –

  Deformation scale factor. Default is 1.0.

• showUndeformed (logical) –

  Whether to show the undeformed model together with the deformed shape. Default is false.

• ax (matlab.graphics.axis.Axes) –

  Target axes. If omitted or empty, a new figure/axes is created.

Example

nodeRespData = opsmat.post.getNodalResponse("MyODB");
opsmat.vis.plotDeformation(nodeRespData, ...
    stepIdx="absMax", ...
    color="red", ...
    useInterpolation=true, ...
    scaleFactor=20, ...
    showUndeformed=true);

plotFrameResponse

(respData: struct, respType="sectionForces", respComponent="MZ", stepIdx="absMax", opts: struct = struct(), ax=[])

Visualize frame element response at a selected analysis step.

plotFrameResponse displays frame-element result fields such as section forces, section deformations, basic forces, basic deformations, local forces, and plastic deformation. The response data is typically collected from an ODB through the post-processing interface.

Syntax

vis.plotFrameResponse(respData)
vis.plotFrameResponse(respData, respType=respType)
vis.plotFrameResponse(respData, respComponent=component)
vis.plotFrameResponse(respData, stepIdx=stepIdx)
vis.plotFrameResponse(respData, opts=opts, ax=ax)

Input arguments:

• respData (struct) –

  Frame response data containing element response information, typically obtained from opsmat.post.getElementResponse(odbTag, eleType="Frame").

• respType (string, optional. The type of response to visualize. Default is "sectionForces". Common options include) –
  • 'sectionForces'
  • 'sectionDeformations'
  • 'basicForces'
  • 'basicDeformations'
  • 'localForces'
  • 'plasticDeformation'
• respComponent (string, optional. The component of the response to visualize. Default is "MZ". Common options include) –
  • For 'sectionForces' and 'sectionDeformations', components include 'N','MZ','VY','MY','VZ','T'.
  • For 'basicForces', 'basicDeformations' and 'plasticDeformation', components include 'N','MZ','MY','T'.
  • For 'localForces', components include 'FX','FY','FZ','MX','MY','MZ'.
• stepIdx (integer or 'absMax') –
  • The index of the analysis step to visualize. Default is "absMax".
  • If "absMax", the step with the maximum absolute response will be visualized.
  • If "absMin", the step with the minimum absolute response will be visualized.
  • If "Max", the step with the maximum response will be visualized.
  • If "Min", the step with the minimum response will be visualized.
  • If an integer, the step with the specified index will be visualized.

  For large response histories, passing a numeric step index is faster than using "absMax", "absMin", "Max", or "Min", because those string selectors scan all analysis steps to find the requested peak step.

• opts (struct) –

  Visualization options. Use vis.defaultPlotFrameResponseOptions to get default options. For large frame models, the following options can significantly reduce plotting time:

  • opts.showMaxMinLabel = "none" or "global" to avoid creating one or more text labels per element.
  • opts.performance.fastMode = true to skip expensive auxiliary geometry such as unstructured wireframes and element/all labels. In fast mode, color limits also use the current step unless opts.color.clim is explicitly specified.
  • opts.performance.maxElementLabels = N to automatically skip element/all labels when the number of beam elements exceeds N. Use Inf to disable this automatic limit.
  • opts.performance.maxSectionsPerElement = N to downsample section-point diagrams for each beam element. Use Inf to keep all recorded section points.
  • opts.surf.show = false to skip non-frame surface wireframes.
  • opts.color.climMode = "current" to compute color limits from only the plotted step. Use "global" only when consistent color limits across all steps are required.
  • opts.color.clim = [cmin cmax] to use fixed color limits and avoid scanning response data for color limits.
  • opts.cbar.show = false to skip colorbar creation/update.
  • opts.color.useColormap = false to use a solid color diagram.
• ax (matlab.graphics.axis.Axes) –

  Target axes. If omitted, a new figure/axes will be created.

Large-model example

opts = opsmat.vis.defaultPlotFrameResponseOptions;
opts.showMaxMinLabel = "none";
opts.performance.fastMode = true;
opts.performance.maxSectionsPerElement = 12;
opts.surf.show = false;
opts.cbar.show = false;
opts.color.useColormap = false;

opsmat.vis.plotFrameResponse(frameRespData, ...
    respType="sectionForces", ...
    respComponent="MZ", ...
    stepIdx=0, ...  % numeric step index is faster than "absMax"
    opts=opts);

plotShellResponse

(respData: struct, respType="SecForceAtGP", respComponent="mxx", fiberPoint="top", stepIdx="absMax", opts: struct = struct(), ax=[])

Visualize Shell element response for a specific step.

Example

plotShellResponse(respData)
plotShellResponse(respData, respType="StressAtGP", ...
    respComponent="sxx", fiberPoint="top", ...
    stepIdx="absMax", ax=ax, opts=opts)

Input arguments:

• respData (struct) –

  Shell element response data. Typically obtained from post.getElementResponse(odbTag, eleType="Shell").

• respType (string, optional (default "SecForceAtGP")) –
  • "SecForceAtGP" | "SecDefoAtGP" | "SecForceAtNode" | "SecDefoAtNode"
  • "StressAtGP" | "StrainAtGP" | "StressAtNode" | "StrainAtNode"
• respComponent (string, optional (default "mxx")) –
  • Section responses : "fxx" "fyy" "fxy" "mxx" "myy" "mxy" "vxz" "vyz"
  • Stress / Strain : "sxx" "syy" "sxy" "syz" "sxz" | "exx" "eyy" "exy" "eyz" "exz"
• fiberPoint (string or integer, optional (default "top")) –

  Through-thickness location for stress/strain responses. "top" | "bottom" | "middle" or 1-based integer fiber index.

• stepIdx (integer or string, optional (default "absMax")) –

  "absMax" | "absMin" | "Max" | "Min" | integer step index.

• opts (struct) –

  Visualisation options. Obtain defaults via plotter.PlotUnstruResponse.defaultOptions().

• ax (matlab.graphics.axis.Axes) –

  Target axes. A new figure is created when omitted.

plotContinuumResponse

(respData: struct, respType="StressAtGP", respComponent="sxx", stepIdx="absmax", opts: struct = struct(), ax=[])

Visualize Plane or Solid continuum element response for a step.

Example

plotContinuumResponse(respData)
plotContinuumResponse(respData, eleType="Solid", ...
    respType="StressAtGP", respComponent="sigmavm", ...
    stepIdx="absMax", ax=ax, opts=opts)

Input arguments:

• respData (struct) –

  Continuum element response data. Typically obtained from post.getElementResponse(odbTag, eleType="Plane") or post.getElementResponse(odbTag, eleType="Solid").

• respType (string, optional (default "StressAtGP")) –
  • "StressAtGP" | "StressAtNode" | "StrainAtGP" | "StrainAtNode"
  • "StressMeasureAtGP" | "StressMeasureAtNode"
• respComponent (string, optional (default "sxx")) –
  • Plane stress : "sxx" "syy" "sxy" "szz"
  • Solid stress : "sxx" "syy" "szz" "sxy" "syz" "sxz"
  • Plane strain : "exx" "eyy" "exy"
  • Solid strain : "exx" "eyy" "ezz" "exy" "eyz" "exz"
  • Measures : "sigmaOct" "tauOct" "tauMax" "vonMises" "p1" "p2" "p3"
• stepIdx (integer or string, optional (default "absMax")) –

  "absmax" | "absmin" | "max" | "min" | 0-based integer step index.

• opts (struct) –

  Visualisation options. Obtain defaults via plotter.PlotUnstruResponse.defaultOptions().

• ax (matlab.graphics.axis.Axes) –

  Target axes. A new figure is created when omitted.