ii_plp

SDT-base Contents Functions

ii_plp

Purpose

Pole line plots and other plot enhancement utilities.

Syntax

ii_plp(po)
ii_plp(po,color,Opt)

Description

plp

Generation of zoomable vertical lines with clickable information.

ii_plp(po) will plot vertical dotted lines indicating the pole frequencies of complex poles in po and dashed lines at the frequencies of real poles. The poles po can be specified in any of the 3 accepted formats (see ii_pof).

When you click on these lines, a text object indicating the properties of the current pole is created. You can delete this object by clicking on it. When the lines are part of iiplot axes, clicking on a pole line changes the current pole and updates any axis that is associated to a pole number (local Nyquist, residue and error plots, see iiplot).

.ID PoleLine Call from iiplot

When displaying a curve in iiplot, one can generate automatic calls to ii_plp. Curve.ID field can be used to automatically generate several type of lines in iiplot over the curve. It is a cell array with as many cell as line sets. Each cell is a data structure defining the line set. Following fields can be defined:

.marker defines the type of line to generate from .po :
- Without .marker field, the default is to generate vertical lines whose x-location are given by the first column of RO.po
- horizontal generates horizontal lines whose y-location are given by the first column of .po
- a+bx generates affine lines from a and b coefficients respectively given by first and second columns of .po
- xy displays the lines stored in .po as a curve with two fields : the cell-array X containing the abcissas and the matrix Y containing the ordinates. If defined .po.MainDim='y' the curves are assumed to be x=f(y) rather than the traditional y=f(x).
- harmh plots horizontal lines at each multiple value of .po
- harmh plots vertical lines at each multiple value of .po
- band displays grey vertical bands whose left and right limits are respectively given by the first and second columns of .po
.po can be a column vector defining abscissa of vertical lines. It can also be a string, possibly depending on the displayed curve XF1 and the channel through variable ch to be evaluated to define the ro.po vector, for example 'r1.po=XF1.Y2(:,ch);'.
.LineProp is optional. One can specify some MATLAB line properties in this field as a cell array {'prop1', value1, 'prop2', value2, ...}, for example {'LineStyle',':','color','r'}.
When using line sequencing, it is preferable to set the property using the line object tag now. Thus
```
 R1=sdsetprop(R1,'PlotInfo.ua.axProp', ...
     '@now',{'LineStyle','--','color','k','marker','none'});
```
.name is used to generate a text info displayed when the user clicks on the line.
.unit(obsolete) is used for Hz vs. rad/s unit conversion. With tens set to 1 (11 or 12) is used for poles in Hz, while those with tens set to 2 correspond to Rad/s. This value is typically obtained from IDopt(3).
.format an integer that specifies whether the imaginary part Im(λ) (Format=2 which is the default) or the amplitude |λ| (using Format=3 corresponding to format 3 of ii_pof) should be used as the "frequency" value for complex poles.

The example below shows main display possibilities :

XF=demosdt('curve phase_circle');
XF.ID={struct('po',[2.2;4.6],... % Thick vertical lines
  'LineProp',{{'LineStyle','-','Linewidth',2}});
 struct('marker','horizontal','po',[-0.4;0.2],... % Red horizontal lines
  'LineProp',{{'LineStyle','-','color','r'}});
 struct('marker','a+bx','po',[-0.4 0.2;0.6 -0.3],... % Dashed green affine lines
  'LineProp',{{'LineStyle','-.','color','g'}});
 struct('marker','xy','po',... % Dotted blue zigzag curve
  struct('X',{{(0:6)'}},'Y',[-1;0;1;0;-1;0;1]),...
  'LineProp',{{'color','b'}}); 
 struct('marker','harmh','po',0.4); % Horizontal harmonic lines
 struct('marker','harmv','po',0.8); % Vertical harmonic lines
 struct('marker','band','po',[1 2;5 6])}; % Vertical grey bands
iicom('curveinit','Temp',XF);iicom('Sub 1 1');

Legend

Dynamic multi-line legend generation used by iiplot and feplot.

ii_plp('legend',ga,prop) with properties a cell array detailed with in comgui def.Legend (typical legend generation associated with FEM solutions).

'set','legend -cornerx y' gives the position of the legend corner with respect to the current axis. -reset option deletes any legend existing in the current axis.
'string',StringCell cell array of strings with one per line of legend. Line specific text properties can be given in second column of StringCell.
'PropertyName',PropertyValue additional properties to be set on the created text.

ii_plp('legend -corner .01 .01 -reset ',ga,ua,StringCell,legProp) is an older format found in some calls, with ga handle to the axis where the axes is to be placed, see gca. ua if not empty provides additional properties .legProp, .Corner.

PlotSubMark

Generate subsampled markers.

spy

ii_plp('spy',k); Generates a spy plot with color coding associated with the non-zero element values of matrix k.

unsymm is used to force non symmetric plots.
threshold is used force small terms to zero.
msizeval allows specifying the plot MarkerSize to val
-nopbar avoids customizing the figure PlotBoxAspectRatio to respect the matrix one.

To perform block-wise spy plots of a single matrix, it is possible to provide matrix k as a structure with fields

K the matrix to spy
ind a cell array of disjoint sets of indices standing for a sequenced block-wise reodering of matrix K.
indC (optional) to provide a different ordering for columns than for lines (following ind), activated for the unsymm case. It can be useful to display rectangular matrices.

TickFcn

SDT implements a general mechanism for enhancing the basic dynamic tick label generation of MATLAB. This allows placement of strings are proper locations on an axis. ii_plp('TickFcn') list predefined ticks.

This functionality is not fully documented and you are encouraged to look-up the source code. SDT generated plots expect the following fields in the axis userdata ua.TickInfo for data and ua.TickFcn for the callback. A sample usage would be

C1=struct('X',{{num2cell(2:4)' 2}},'Xlab',{{'x','y'}}, ...
 'Y',(1:3)')
figure(1);plot(1:3,C1.Y);ii_plp('tickXCell',C1,gca);
C1=ii_plp('tickXCell',C1); %Defines the PlotInfo
iiplot(C1);

ColorMap[,RO]

FEM oriented color maps.

Predefined maps can be directly called and will apply to the current figure. feplot assignment can be performed by nesting the ColorMap call in a call to fecom. fecom('colormapjet(5)') thus generates a map with 5 colors and grey level bands on the current feplot figure. This is called using

Sample colormaps are featured in the example below,

% Example of colormaps provided by ii_plp
figure(1);h=mesh(peaks(300));
set(h,'edgecolor','none','facecolor','interp'); 
ii_plp('ColormapBandjet(5)')
ii_plp('ColormapFireIce 20')
ii_plp('ColormapSamcef')

An exhaustive list can be obtained using ii_plp('ColorMap') with no argument. This will open the tag list for colormap thus showing the currently available maps.

ii_plp('ColorMapWCenter Thres.1',jet(20)) uses the map given as second argument with a symmetric clim and a white band for values below the specified Thres.

In a more general context, one can define in any MATLAB figure a custom colormap with custom and unevenly spread thresholds by providing a structure in second argument with fields

map the chosen map in rgb format.
cval a vector of values at which colors switches. The color limits CLim properties of the figure current axis will be set to the extrema of cval. It is thus recommended to use clean min max values. Color distribution is performed sequentially, so that only one color per cval step is used. It is thus recommended to use a map with N-1 colors, N being the vector size.
refine, optional. This is used to provide the colormap refinement needed to place color switches accurately. The default is set to 100.
bSplit, optional. This is used to add black split lines between colors, with a specified thickness.
Band, optional. This is used to add a darkening nuance to each color step.
cf, optional. To provide a feplot or figure handle, by default the current figure is taken.

% Custom colormap setting using ii_plp
demosdt('demoubeam')
cf=feplot;
fecom(cf,'colordataa')
fecom(cf,'colorscale Unit 1e3');
fecom(cf,'colorbaron')
ii_plp('colormap',struct('map',[1 1 1;jet(7)], ...
 'cval',[0:4:10 11:2:21],'Band',0,'refine',10,'bSplit',2))

Cb

Callbacks for comgui objSet properties of colorbar. Accepted options are

No north (main location), eot east outside top.
String label of colorbar
map color map command.
cf figure number

figure(1);clf;mesh(peaks);
ii_plp('cbNo',struct('String','Z', ...
   'map','ii_plp(''ColormapBandjet(5)'')', ...
   'cf',1));