iicom

SDT-base Contents Functions

iicom

Purpose

UI command function for FRF data visualization.

Syntax

iicom CommandString
iicom(ci,'CommandString') % specify target figure with pointer
out = iicom('CommandString')

Description

iicom is a standard UI command function which performs operations linked to the data visualization within the iiplot interface. A tutorial can be found in section 2.1.

Commands are text strings telling iicom what to do. If many iiplot figures are open, one can define the target giving an iiplot figure handle ci as a first argument.

iicom uses data stored in a stack (see section 2.1.2). iicom does not modify data. A list of commands available through iicom is given below. These commands provide significant extensions to capabilities given by the menus and buttons of the iiplot command figure.

Commands

command;

The commode help details generic command building mechanisms. Commands with no input (other than the command) or output argument, can be chained using a call of the form iicom(';Com1;Com2'). commode is then used for command parsing.

cax i, ca+

Change current axes. cax i makes the axis i (an integer number) current. ca+ makes the next axis current. For example, iicom(';cax1;show rea;ca+;show ima') displays the real part of the current FRFs in the first axis and their imaginary part in the second. (See also the iicom Sub command). The button indicates the number of the current axis. Pressing the button executes the ca+ command.

ch+, ch-, ch[+,-]i : next/previous

Next/Previous . These commands/buttons are used to scan through plots of the same kind. For iiplot axes, this is applied to the current data sets. For feplot axes, the current deformation is changed. You can also increment/decrement channels using the + and - keys when the current axis is a plot axis or increment by more than 1 using iicom('ch+i').

ch i, chc i, chall, ... select channel

Display channels/poles/deformations i. Channels refer to columns of datasets, poles or deformations. ch / chc respectively define the indices of the channels to be displayed in all /the current drawing axes. The vector of indices is defined by evaluating the string i. For example iicom ch[1:3], displays channels 1 to 3 in all axes.

For curve Multi-dim curve with dimension labels in the .Xlab field,ChAllMyLabel selects all channels associated with dimension MyLabel. This can be used to show responses at multiple operating conditions (typically stored as third or fourth dimension of curve.Y).

For multi-channel curves one can define the dimension name referring to the Xlab field in a cell array iicom(ci,'ch','Xlabname',i). For this to work properly note that all Xlabname entries must be different (e.g. several Unknown entries must thus be avoided).

% Build a multi-dim curve, see sdtweb('demosdt.m#DemoGartteCurve')
r1=demosdt('demoGartteCurve')
ci=iicom('curveInit','Example',r1);
iicom('ChAllzeta') % All channels that correspond to 'zeta' r1.Xlab{4}
% Cell selection with Xlab string and indices (each row picks a dimension)
iicom('ch',{'Output DOFs',4;'Input DOFs',[1,2]}) % Accessible with 'pick' button
iicom('curtabChannel')

Cursor, ods

The cursor is usually started with the axes context menu (right click on a given axis).

iicom CursorOnFeplotshows a cursor on the iiplot curve that let you show corresponding time deformation in feplot.

fecom CursorNodeIiplot gives more details.

iicom('ods') provides an operational deflection shape cursor.

Curve [Init,Load,Save,Reset, ...]

These commands are used to manipulate datasets.
Most of them are of the form iicom('Curve...',CurveNames). Then CurveNames can be a string with a curve name, a cell array of string with curve names or a regular expression (beginning by #) to select some curve names. If CurveNames is omitted, a curve a dialog box is opened to select targeted curves. Otherwise these commands can be accessed through the GUI, in the Stack tab of the iiplot properties figure.

CurveInit is used to initialize a display with a new dataset. iicom('CurveInit','Name',C1) is used to initialize a display with a new dataset. iicom('CurveInit','Name',C1) adds a 'curve','Name' entry and displays this set in a new tab. To add dans display multiple curves use
```
iicom('CurveInit',{'curve','N1',C1; 'curve','N2',C2}) 
```
The field PlotInfo can be used to control how this initial display is performed.
CurveLoad lets you load datasets.
iicom('CurveLoad FileName') loads curves stored in Filename.
iicom('CurveLoad') opens a dialog box to choose the file containing curves to load. If the file contains multiple curves, one can select the curves to be loaded in a cell array given as a second argument. For example,
```
ci=iicom('CurveLoad','gartid.mat')
```
loads the gartid data in an iiplot figure. Command option -append (iicom(ci,'CurveLoad -append MyFile')) lets you append loaded curves to existing curves in the stack (by default existing curves are replaced). Command option -hdf (iicom(ci,'CurveLoad -hdf MyFile')) lets you load curves under the sdthdfformat. Only pointers to the data stacked in iiplotare thus loaded. Visualizations and data transformation can be performed afterwards. Command option -back does not generate any visualization in iiplot. This can be useful in combination to -hdf, as the user can then fully control the data loaded in RAM.
CurveSave lets you save iiplot stack data.
iicom('CurveSave FileName',CurveNames) saves the curves CurveNames in the .mat file given by FileName. If FileName is omitted a GUI is opened. To save more than 2 GB of data, or to save in the new MATLAB file formats (-v7.3), use the SDT V6Flag: setpref('SDT','V6Flag','-v7.3').
```
fname=fullfile(sdtdef('tempdir'),'IicomSaveTestmat')
iicom(['CurveSave' fname],{'IIxi';'IdMain'})
```
CurveNewId CurveName opens new iiplot figure for identification of the curve CurveName of the ci stack with idcom.
iicom('CurveLoadId',FileName) loads from FileName into for identification.
CurveRemove removes the curves from the stack of the iiplot figure.
iicom('CurveRemove',CurveNames);
CurveReset defines an empty curve stack to renew your work.
CurveJoin combines datasets that have comparable dimensions. In particular first dimension (time, frequencies ...) must be the same. For example it is useful to combine dataset from parameter studies (same dimension). iicom('CurveJoin',CurveNames);
Curves targeted by CurveNames (or selected curves in iiplot) are joined and replace the first curve in the iiplot stack.
iicom CurveJoin command. One can use following command options:
- -follow to remove last value of first abscissa before concatenate.
- -shift to shift abscissa of second dataset of the last value of first dataset abscissa.

Dock Id, MAC, TestBas

Starting with SDT 7, classical SDT uses are guided through multiple figures combined in docks.

DockId is used for identification of modeshapes. You can force the selection of iiplot and feplot figure using iicom(ci,'DockId',cf).
dockCoShape is used for shape correlation.
dockCoTopo is used for topology correlation.

ga i

Get handle to a particular axis. This is used to easily modify handle graphics properties of iiplot axes accessed by their number. For example, you could use set(iicom('ga1:2'),'xgrid','on') to modify the grid property of iiplot axes 1 and 2.

If you use more than one feplot or iiplot figure, you will prefer the calling format cf=iiplot; set(cf.ga(1:2),'xgrid','on').

head [Main,Text,Clear]

Note : the preferred approach is now to define fixed displays using comgui objSet commands stored in the curve PlotInfo ua.axProp entry. For example

 C1=fe_curve('testSin T 0.2',linspace(0,10,100e3));
 C1.Xlab={'Time','Resp'};
 r1={'@title',{'String','Main Title','FontSize',16}};
 C1=sdsetprop(C1,'PlotInfo.ua.axProp',r1{:});
 iicom('curveinit','SineWithFixedTitle',C1);

For backward compatibility, header axes are still supported (the change is to objSet allows better tab switching). Header axes are common to all plot functions and span the full figure area (normalized position [0 0 1 1]). You can get a pointer to this axis with cf.head and add any relevant object there.

ci=iicom('curveload','gartid'); % Load a test case
h=text(0,0,'Main Title', ...
 'parent',ci.head,'unit','normalized','position',[.05 .95], ...
 'fontsize',20,'fontname','Times', ...
 'tag','iimain');
iimouse('textmenu',h); % Allow Editing

iicom('HeadClear') deletes all objects from the header axis of the current figure.

IIxData set selection iicomIIx:name [On,Off,Only], cIIx ...

Curve set selection for display in the current axis.

IIx:TestOnly displays the ci.Stack{'Test'} data set only in all axes (on and off turn the display on or off respectively). By adding a c in front of the command (cIIx:Test for example), the choice is only applied to the current axis. You can also toggle which of the data sets are shown using the Variables menu (applies to all axes) or axis context menu applies to (current axis).

The alternate calling format iicom('iix',{'Test','IdFrf'}) can be used to specify multiple sets to display. iicom('iixOnly',{'Test','IdFrf'}) will display those two sets only.

IIxf, IIxe, IIxh, IIxi [0n,Off] are still supported for backward compatibility.

Polar

Polar plots are used for cases where the abscissa is not the standard value. Accepted values (use a command of the form Polar val) are

-1 abscissa is the channel before the one displayed. In a curve with channels [X Y] display Y, channel 2, and use X,channel 1, as abscissa.
xi uses i^th column of def.data when displaying FEM time signals or XF.X1 for curves. This is typically used when this second column is an other form of abscissa (angle for rotating machines, ...)
i with i>0 uses the specified channel as abscissa.
Off or 0 turns off polar plots.

PoleLine [ ,c] [ ,3], IIpo, ...

Pole line display. are dotted vertical lines placed at relevant abscissa values. These lines can come from

standard curves with an curve.ID field, see ii_plp Call from iiplot.
frequencies of poles in ci.Stack{'IdMain'} in black and ci.Stack{'IdAlt'} in red.

By itself, PoleLine toggles the state of pole line display. The c option applies the command to the current axis only. PoleLine3 places the lines on the pole norm rather than imaginary part used by default (this corresponds to the ii_plp formats 2 and 3).

The state of the current axis (if it is an iiplot axis) can also be changed using the IIplot:PoleLine menu (PoleLineTog command).

Low level commands IIpo and IIpo1 are low level commands force/disable display of pole lines in the main identified model
ci.Stack{'IdMain'}.po or the alternate set ci.Stack{'IdAlt'}.po. With cIIpo the choice is only applied to the current axis. These options are usually accessed through menus.

ImWrite, ...

comgui ImWrite is the generic command used to generate a clean printout of figures. It supports many basic capabilities, filename generation, cropping, ... When using iiplot and feplot, it may often be interesting to generate multiple images by scanning through a selected range of channels. A command of the form iicom(cf,'ImWrite',RO) is then used with RO a structure containing generic image capture fields (see comgui ImWrite) and fields specific to multi-image capture

.ShowFcn the callback that is executed for each image to be generated. The default is fecom(cf,sprintf('ch %i',ch)); for feplot. The loop index is j1.
.ch a vector of channel indices that will give an index for each image. With the string all, all the channels are used.
.ImWrite is the command used to call comgui with the default 'imwrite -ftitle'.
.FileName if present replaces any other file name generation mechanism. Your ShowFcn callback can thus implement your own file name generation mechanism.
.Movie can be a structure for movie generation using fecom AnimMovie.
.HtmWidth can specify an HTML view size which differs from the image size. The input is either a string in the format width=val height=val1, or a line with 4 columns in the format [Width Height MaxWidth MaxHeight], it is possible to let free a value by provided Inf instead of a numerical value. At least Height or Width must be defined. Depending on the input, the behavior is
- if a scalar is given or if the Height is set to Inf,the width is fixed and the height is set to keep the image ratio. If a MaxHeight is provided and the resulting height overcomes it, the width is adapted to maximize the possible size.
- if Width is set to Inf, the height must be defined and the width is set to keep the image ratio. If a MaxWidth is provided and the resulting width overcomes it, the height is adapted to maximize the possible size.
- is both Width and Height are provided, the values are fixed and non further control is performed.
.RestoreFig=1 can be used to restore the figure and display after image generation.
.RelPath optional integer giving the level of relative path to be retained (1 keeps just the file name, 2 the directory containing the images, ...). This is useful to create HTML report files that can be moved.

To automate figure generation, it is typically desirable to store image capture information in the set of deformations or the curve. A curve.ImWrite field in iiplot can be used to predefine the option structure, for user defined dynamic change of settings, defining a ua.PostFcn callback (see iiplot PlotInfo) is typically the appropriate approach. For feplot, def.ImWrite is used for multi-image capture but more evolved file name generation is found using comgui def.Legend.

% Example of 4 views in feplot
 cf=demosdt('DemoGartFEplot')
 cingui('PlotWd',cf,'@OsDic(SDT Root)','FniiLeg');
 cf.def=sdsetprop(cf.def,'Legend', ...
     'string',{'Garteur FE';'$Title'}) % Define a two line title
 RO=comgui('imfeplot4view'); % Predefined strategy to generate 4 views
 comgui('PlotWd',cf,'FileName', ...
  {'@PlotWd','Root','@ii_legend(1:2)','@cf.ga.View','.png'});
 fecom(cf,'ImWrite');comgui('iminfo',cf)

% Example of two channels in iiplot, with finish on same view
 ci=iicom('curveload -noDock','gartid');iicom('ch20')
 cingui('PlotWd',ci,'@OsDic(SDT Root)', ...
     {'ImToFigN','ImSw50','WrW49c',  ... % Duplicate, Large wide
      'FniC'});%FileName generation instruction
 ci.Report_('ch',1:2);

comgui('ImFeplot') returns a list of standard calls to options for image generation.

Pro

iicom('ProFig') shows or hides the properties figure.
iicom(ci,'ProRefreshIfVisible') refreshes the property figure when it is visible.
iicom(ci,'ProInit') reinits the property figure.

Show plot type

Specify the current axis type. The iiplot plot functions support a number of plot types which can be selected using the Show menu/command. From command line, you can specify the target axis with a-cax i option.

The main plot types are

2D (f(x)) plots are associated with the following buttons Abs (absolute value), Pha phase, Phu unwrapped phase, Rea real part, Ima imaginary part, R&I real and imaginary, Nyq Nyquist.
3D (f(x,y)) plots are image, mesh, contour and surface. Show3D gives time-frequency representation of the log of the abs of the signal displayed as and image. The ua.yFcn callback operates on the variable called r3 and can be used for transformations (absolute value, phase, ...). Note that you may then want to define a colorbar see iiplot PlotInfo.
```
 R1=d_signal('Resp2d'); % load 2d map
 R1.PlotInfo= ii_plp('plotinfoTimeFreq -yfcn="r3=r3" type "contour"');
 ci=iicom('curveinit','2DMap',R1);

 % or
 R1.PlotInfo={}; ci=iicom('curveinit','2DMap',R1);
 ci=iicom('curveinit','2DMap',R1);
 iicom('show3D -yfcn="r3=log10(abs(r3))" type "contour"')
```
idcom specialized plots see iiplot TypeIDcom : mmi MMIF of Test, fmi forces of MMIF of Test, ami alternate mode indicator of Test, SUM of Test, CMIF of Test, sumi sum imaginary part of Test, pol poles in IdMain, fre freq. vs. damping in IdMain, rre real residue in IdMain , cre complex residue of IdMain, lny local Nyquist of Test (superposition around current pole), err Nyquist Error for current pole, Quality for all poles
feplot plots.

SubSave, SubSet

SubSavei saves the current configuration of the interface in a stack entry TabInfo. This configuration can then be recalled with SubSeti. The TabInfo entry is also augmented when new curves are shown so that you can come back to earlier displays. SubSetIi selects an index in the TabInfo stack.

SubToFig

SubToFig copies the iiplot figure visualization to a standard matlab figure, thus allowing an easier handling to produce customized snapshots (see also iicom ImWrite). Reformatting is then typically performed with comgui objSet.

Command option -cfi forces the visualization output to figure i.

Command option legi allows iiplot legend handling in the visualization. leg0 removes the legend, leg1 keeps it as in iiplot, leg2 transforms the iiplot legend in a standard matlab legend. The legend is removed by default.

Sub plot init

This command is the entry point to generate multiple drawing axes within the same figure.

iicom Sub by itself checks all current axes and fixes anything that is not correctly defined.

Accepted command options are

MagPha gives a standard subdivision showing a large amplitude plot and a small wrapped phase plot below.
Iso gives a standard 2 by 2 subdivision showing four standard 2-D projections of a 3-D structure (this is really used by feplot).
i j k divides the figure in the same manner as the MATLAB subplot command. If k is set to zero all the i times j axes of the subplot division are created. Thus the default call to the Sub command is Sub 2 1 which creates two axes in the current figure. If k is non zero only one of these axes is created as when calling subplot(i,j,k).
As the subplot function, the Sub command deletes any axis overlapping with the new axis. You can prevent this with command option nd.
Standard subdivisions are accessible by the IIplot:Sub commands menu.
Note that set(cf.ga(i),'position',Rect) will modify the position of iiplot axis i. This axis will remain in the new position for subsequent refreshing with iiplot.
step increments the deformation shown in each subplot. This is generally used to show various modeshapes in the same figure.
Reset forces a reinit of all properties. For example SubMapha Reset.

TitOpt [ ,c]i, title and label options

Automated title/label generation options. TitOpti sets title options for all axes to the value i. i is a 5 digit number with

units corresponding to title. For modes [None,ModeNumber,Name].
decades to xlabel 0 none, 1 label and units, 2 label.
hundreds to ylabel 0 none, 1 label and units, 2 label.
thousands to zlabel 0 none, 1 label and units, 2 label.
1e4 to legend/title switching.

The actual meaning of options depends on the plot function (see iiplot for details). By adding a c after the command (titoptc 111 for example), the choice is only applied to the current axis.

When checking the axes data (using iicom Sub command), one rebuilds the list of labels for each dataset using iicom('chlab'). This cell array of labels, stored in ci.ua.chlab, gives title strings for each channel (in rows) of datasets (in columns) with names given in ci.ua.sList. The label should start with a space and end with a comma. The dataset name is added if multiple datasets are shown. Not to display the curve name in the legend you can define and set ci.ua.LegName = 0, going back to default behavior is obtained by ci.ua.LegName = 1.

Modifying the ci.IDopt.unit value changes the unit assumed for identification but not the dataset units.

Titles and labels are not regenerated when using ch commands. If something is not up to date, use iicom Sub which rechecks everything.

Scale : xlin,xlog ...

Default values for xscale and yscale. xlin, xlog, ylin, ylog, set values. xy+1, xy+2 are used to toggle the xscale and yscale respectively (you can also use the IIplot:xlin and IIplot:ylin menus). Other commands are xy1 for x-lin/y-lin, xy2 for x-log/y-lin, xy3 for x-lin/y-log, xy4 for x-log/y-log.

You can all use the all option to change all axes: iicom('xlog all').

ytight[on,off,] can be used to obtain tight scales on the y axis. The x axis is typically always tight. Automated ztight is not yet supported.

Limits : wmin, xlim, xmin, xmax, wmo, w0, ...

Min/max abscissa selection is handled using the fixed zoom (graphically use button). Accepted commands are

xlim min max (or the legacy wmin f1 f2). For 2D plots, use xlim xmin xmax ymin ymax to allow selection of a 2D area.
xmin min (or the legacy wmin f1)
xmax max (or the legacy wmax f1)
wmo allows a mouse selection of the minimum and maximum value (same as button).
w0 resets values (same as double click after hitting the button)

The limit value(s) can also be forwarded as last argument : iicom('xlim',[min max]).

When performing identification with idcom the fixed zoom corresponds to the working frequency range and corresponds to indices in ci.IDopt(4:5) (see IDopt, turn off with idcom('Off')). The index of the frequency closest to the specified min/max is used. When viewing general responses, the information for the abscissa limits is stored in the axis and is thus lost if that axis is cleared.

Min/max ordinate selection (fixed limits of y axis or z axis for 2D plots) is also sometimes desirable.

This can be performed by providing ylim axes property through the iiplothandle ci with command ci.ua.axProp={'ylim',[ymin ymax]};