Customizing axes part 2

Last week I explained how HG2 (in R2014b) enables us to customize the axes rulers in ways that were previously impossible in HG1 (R2014a or earlier). Today I will describe other useful undocumented customizations of the HG2 axes:

• Baseline
• BoxFrame
• GridHandle

Baseline

A baseline is a line that has some important meaning. For example, in a plot of the sin function, we might want to place a horizontal baseline at Y=0 or Y=-1, and similarly a vertical baseline at X=0. In HG1, we could do this programmatically using extra line commands (presumably with the additional *LimInclude properties). In HG2 it becomes easier – we can simply update the relevant baseline’s properties: XBaseline, YBaseline and ZBaseLine. All baselines are automatically created with a value of 0, color=gray and Visible=’off’. For example, continuing last week’s example:

HG2 axes Baseline

% Create the plot
x = -10:0.1:10;
y = 1e7*sin(x)./x; 
hLine = plot(x,y);
hAxes = gca;
 
% Display the default YBaseline's property values
% Note: there are also plenty of hidden properties that can be gotten with getundoc()
>> hAxes.YBaseline.get
           BaseValue: 0
            Children: []
               Color: [0.15 0.15 0.15]
    HandleVisibility: 'off'
           LineStyle: '-'
           LineWidth: 0.5
              Parent: [1x1 DecorationContainer]
             Visible: 'off'
 
% Display a horizontal YBaseline with custom color
hAxes.YBaseline.Color = 'b';  % default: [0.15 0.15 0.15]
hAxes.YBaseline.Visible = 'on';  % default: 'off'
 
% Hide the bottom x-axis, to make the Y-baseline stand out
hAxes.XRuler.Axle.Visible = 'off';  % default: 'on'

Note the horizontal blue Y-baseline. also note how I hid the bottom x-axis, in order to make the Y-baseline stand out.

Translucent colors can be specified by entering a 4-element color vector. For example: [1, 0, 0, 0.5] means a 50%-transparent red.

For extra prominence, you might want to increase the baseline’s LineWidth from its default value of 0.5 to a value of 1 or 2.

Another useful customization is to set a non-zero BaseValue, or a non-solid baseline LineStyle.

While YBaseline is normally a horizontal line that relates to the Y-axis (hAxes.YBaseline.Axis==1), we can make it vertical attached to the X-axis by simply modifying its Axis value to 0 (0=X, 1=Y, 2=Z).

For the record, baselines are matlab.graphics.axis.decorator.Baseline class objects.

BoxFrame

The BoxFrame property controls the “box” lines that surround the plot when we issue a box(‘on’) command. This is normally a simple black square/rectangle for 2D plots, and a simple black background wireframe for a 3D plot. But who said it needs to be boring?

surf(peaks);  % 3D plot
box on;  % standard black box wireframe
boxFrame = get(gca,'BoxFrame');  % or: hAxes.BoxFrame
set(boxFrame, 'XColor','r', 'YColor','b', 'ZColor','g');  % default colors: [0.15 0.15 0.15]

HG2 axes BoxFrame

>> get(boxFrame)
           AxesLayer: 'bottom'
            BackEdge: [1x1 LineStrip]
            Children: []
           FrontEdge: [1x1 LineStrip]
    HandleVisibility: 'off'
           LineWidth: 0.5
              Parent: [1x1 DecorationContainer]
             Visible: 'off'
              XColor: [0.15 0.15 0.15]
              YColor: [0.15 0.15 0.15]
              ZColor: [0.15 0.15 0.15]

By default, only the box frame’s back-edge is displayed (axes BoxStyle property =’back’). We can modify this behavior by setting the axes’ BoxStyle to ‘full’, but we can have much more control if we simply update the properties of the box-frame object. For example:

set(boxFrame.FrontEdge, 'Visible','on', 'LineStyle','dashdot', 'LineWidth',1);  %defaults: 'off', 'solid', 0.5

As with the Ruler.Axle objects (see last week’s article), we can customize the Vertex points and colors to achieve very colorful effects (anyone say psychedelic?)

GridHandle

In HG2, MathWorks have dramatically improved the appearance of the grid-lines, making them a much lighter, less-obtrusive gray color. Even more importantly, we now have fine-grained control over the grid lines, via the axes’ hidden XGridHandle, YGridHandle and ZGridHandle properties. These return an empty handle when the grid is not shown, and a matlab.graphics.axis.decorator.SimpleGrid class object when the relevant grid-lines are displayed.

>> grid on
>> xgrid = get(gca,'XGridHandle');  % or: hAxes.XGridHandle
>> get(xgrid)
           BackMajorEdge: [1x1 LineStrip]
           BackMinorEdge: [1x1 LineStrip]
                Children: []
                   Color: [0.15 0.15 0.15]
      FirstCrossoverAxis: 0
     FirstCrossoverValue: 0
          FrontMajorEdge: [1x1 LineStrip]
          FrontMinorEdge: [1x1 LineStrip]
           GridLineStyle: '-'
        HandleVisibility: 'off'
               LineWidth: 0.5
              MajorMinor: 'major'
               MajorTick: [-10 -8 -6 -4 -2 0 2 4 6 8 10]
              MinorColor: [0.1 0.1 0.1]
      MinorGridLineStyle: ':'
          MinorLineWidth: 0.5
               MinorTick: []
                  Parent: [1x1 DecorationContainer]
    SecondCrossoverValue: 0
                 Visible: 'on'

As before, we can customize the grid line’s LineWidth, GridLineStyle, and Color. MajorMinor can accept ‘major’ (default), ‘minor’, or ‘majorandminor’, which is pretty intuitive.

customized HG2 axes X-grid

set(xgrid,'Color','r', 'GridLineStyle',':', 'LineWidth',1.5, 'MajorMinor','majorandminor');

To control the tick lines in 3D plot we can set BackMajorEdge, BackMinorEdge, FrontMajorEdge and FrontMinorEdge in the same way as we did for the BoxFrame. By default only the back-edges are visible. If you wish to also display the front edges, then set the front edge’s Visible to ‘on’ and don’t forget to modify its VertexData to different values than the back edge’s VertexData. As before, colorful effects can be achieved in the grid-lines by customizing the edge objects’ properties:

>> xgrid.BackMajorEdge.get
          AlignVertexCenters: 'on'
             AmbientStrength: 0.3
                ColorBinding: 'object'
                   ColorData: [4x1 uint8]
                   ColorType: 'truecolor'
             DiffuseStrength: 0.6
            HandleVisibility: 'off'
                     HitTest: 'off'
                       Layer: 'back'
                   LineStyle: 'dotted'
                   LineWidth: 1.5
               NormalBinding: 'none'
                  NormalData: []
                      Parent: [1x1 SimpleGrid]
               PickableParts: 'visible'
    SpecularColorReflectance: 1
            SpecularExponent: 10
            SpecularStrength: 0.9
                   StripData: [1 3 5 7 9 11]
                     Texture: []
                  VertexData: [3x10 single]
               VertexIndices: []
                     Visible: 'on'
       WideLineRenderingHint: 'software'

A note about performance

MATLAB HG2, on R2014b, relies on advanced OpenGL hardware features much more than earlier releases. When Matlab detects an incompatible display driver, it issues a warning and reverts to using the much slower software implementation. It is advisable to update the display driver to the very latest version, since this often solves such incompatibilities.

Some computer vendors use custom OEM drivers and their latest version might still be incompatible. For example, on my Lenovo E530 laptop, the latest Intel HG Graphics 4000 driver (v.9.15) was still incompatible; although the system told me that I have the very latest driver installed. I downloaded the latest generic driver (v.10.18) from Intel’s website and this fixed the issue: HG2 now uses hardware-accelerated OpenGL on my laptop, which is much faster. It may not be as 100% compatible with my laptop as the custom OEM version, but so far it appears to work ok and importantly Matlab graphics now work much better. I can always roll-back the driver to the OEM driver if I see a problem with the generic driver.

Next week I will continue my series on Matlab axes customizations, by describing Backdrop, WarpToFill and a few other aspects. Stay tuned!

1. Customizing axes rulers HG2 axes can be customized in numerous useful ways. This article explains how to customize the rulers. ...
2. Determining axes zoom state The information of whether or not an axes is zoomed or panned can easily be inferred from an internal undocumented object....
3. Axes LooseInset property Matlab plot axes have an undocumented LooseInset property that sets empty margins around the axes, and can be set to provide a tighter fit of the axes to their surroundings....
4. Customizing menu items part 1 Matlab menus can be customized in a variety of undocumented manners - first article of a series. ...