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:


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

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 class objects.


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

HG2 axes BoxFrame

The BoxFrame object is a class object that, like the rulers and baseline, can be customized (once the box(‘on’) command has been issued):

>> 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?)


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 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

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!

Categories: Handle graphics, Low risk of breaking in future versions, Stock Matlab function, Undocumented feature

Tags: , , , , ,

Bookmark and SharePrint Print

16 Responses to Customizing axes part 2

  1. Tobias Gram says:

    Hi, how can I change the grid-linewidth? It seems too prominent.

  2. Brad Stiritz says:

    Hi Yair, thanks for the very informative HG2 series.

    >MATLAB HG2, on R2014b, relies on advanced OpenGL hardware features..

    For convenient reference: it looks like OpenGL 3.0 is the minimum version needed to take full advantage of HG2.

  3. Ralf Hielscher says:

    Hi Yair,

    thanks for your comments. One thing that drives me around with HG2 is the fact that colorbar is not an axis anymore. As a consequence we can not do anymore

    h = colorbar

    to compute the actual size of the colorbar. Also


    does not work – Formerly, you could get informed about each newly created axis.


  4. Pingback: Customizing axes part 3 – Backdrop | Undocumented Matlab

  5. gang says:


    Thanks for good info.
    I have a question about the axis baseline.
    Is it possible to change the position of baseline (from zero to say 1.6)?
    And if so, is it possible to have multiple baselines?

    Thanks a lot.

    • @Gang – there’s a BaseValue property (value=0), but changing it apparently has no effect (at least in R2014b). Maybe this will be fixed in future Matlab releases.

      Re multiple baselines, you can create multiple Baseline objects like this, but unfortunately it doesn’t work (no visible effect) – maybe I did something wrong or maybe it’s blocked in some way. Feel free to experiment and let us all know if you discover anything useful:

      hNewBaseline ='BaseValue',3, 'Parent',gca, 'Axis',1, 'Visible','on')
  6. Mark says:

    I’m finding that the minimum line width for HG2 export is 1, or 0.5. This looks like a bug.

    The following code incorrectly produces PDFs with axis lines 1.0 pts wide:

    figH = figure;
    plot([0,1], [0,1], 'k');
    set(gca, 'LineWidth', 0.25);
    print(gcf, '-dpdf', 'test.pdf')

    Using the HG2 properties does not work either: axH.XRuler.Axle.LineWidth = 0.1

    hgexport and print both show the bug. It happens with svg, pdf, and epsc files. (Be careful with hgexport – it embeds a preview in the eps file that looks correct, but the eps linewidths are wrong, as you can see by embedding in Illustrator or Inkscape).

    I’ll report this to the Mathworks but perhaps this saves time for others.

    p.s. Yair – thanks for your work on export_fig on github. Glad you picked it up. It’s a workaround for this problem but not a direct substitute, as I want to specify print/paper sizes and not copy what’s onscreen.

    • Yair Altman says:

      @Mark – indeed, an internal bug in Matlab causes the minimal line width to be apparently 0.75. The export_fig utility works-around this bug and exports a file (EPS/PDF) having the correct line-width. See issue #31.

      For anyone interested @TMW, this is case #01249115 that I reported on Feb 24. Apparently, LineWidths<0.75 use EPS's default line width, rather than computing the actual value. This affects regular plot lines as well as axes Ruler Axles and grid lines (that have LineWidth=0.5 by default).

  7. W.T. Door says:

    Yair —

    Just wanted to add a comment to let you know that this post was extremely helpful; I was trying to figure out a way to help highlight some differences between surface plots and modifying the Z-axis gridlines worked perfectly. FWIW, I bought your “Undocumented Matlab” book a couple of years ago and it has proved useful time and again — thanks for both the book and the blog.


  8. Fred Vanner says:

    I’m having problems with XGridHandle (etc.) in scripts / functions (I’ve had no problems from the command line). Example:

    grid on;
    xgh.BackMajorEdge.ColorData=cast([0; 20; 20; 200],'uint8');

    Running this script (R2014b, 32 bit) I get:
    “No appropriate method, property, or field BackMajorEdge for class”
    If I put a breakpoint after the “grid on” command, and continue from the breakpoint, I get no error (and the grid change works).
    This would be really useful if I could persuade it to work reliably. Any ideas?

Leave a Reply

Your email address will not be published. Required fields are marked *