- Undocumented Matlab - https://undocumentedmatlab.com -

Matlab's HG2 mechanism

Posted By Yair Altman On May 7, 2010 | 13 Comments

A few days ago I posted [1] a lengthy article about Matlab’s undocumented feature function. In it, I mentioned a feature called HG2, that I believe merits a dedicated article, due to its potential high impact on future Matlab releases.
HG2, which presumably stands for “Handle Graphics 2nd generation”, was already reported in the past as an undocumented hidden figure property [2] (UseHG2). In normal Matlab usage, this boolean property is ‘off’:

>> get(gcf,'usehg2')
ans =

HG2 is mentioned in quite a few Matlab files:

  • clf.m, hgload.m, ishg2figure.m, datetick.m, linkdata.m, linkplotfunc.m, cameratoolbar, /bin/registry/handle_graphics.xml, /ja/xlate and many more
  • uimodemanager.m (and others) temporarily disables a ‘MATLAB:handle:hg2’ warning
  • defaulterrorcallback.m mentions ‘MATLAB:HG2:SceneNode’ and ‘MATLAB:HG2:Property’
  • getplotbrowserproptable.m mentions several special HG2 types (hg2.Line, hg2.Lineseries, hg2.Patch etc.)
  • There’s even a dedicated /toolbox/matlab/graphics/private/ishg2figure.m function that determines whether a figure contains any HG2 graphics based on the existence of ‘hg2peer’ appdata (getappdata(fig,’hg2peer’)).
  • /toolbox/matlab/plottools/@objutil/@eventmanager/schema.m (and a few others) has the following comment:
     % may contain either UDD or MCOS listeners during the hg2 migration.

Obviously, much effort was invested in HG2 functionality. The fact that HG2 has been under development at least since 2007 (when I first discovered and reported [3] it) seems to indicate a major upheaval in Matlab’s Handle Graphics mechanism. This hunch is reinforced by cryptic comments made by MathWorks personnel over the past few years that they are indeed looking at the HG system, which in their opinion is nearing its limitations. Perhaps I’m mixing unrelated stuff here, but it does make sense in light of Matlab’s push of its OOP class system over the past few releases.
To preview this HG2 system, we need to turn it on. Unfortunately, when we set the figure’s UseHG2 to ‘on’ there doesn’t seem to be any visible effect. However, this changes after we use the corresponding ‘UseHG2’ feature using the feature function (this caused lots of nasty-looking errors in past releases but works ok in R2010a):

>> feature('usehg2',1)

The /ja/xlate file (which is used in conjunction with the undocumented xlate function to translates Matlab messages from English to Japanese) has another key to unlocking HG2: This file contains the following message: “feature(‘useGBT2’) is only available when Matlab is started with -hgVersion 2 option.“. So let’s do as the xlate message advises and start a new Matlab session with the undocumented “-hgVersion 2” command-line option. Now feature(‘usehg2’) is true by default and we can test the HG2 system.
Matlab looks basically the same in HG2 as in HG1. All the regular graphic functions behave just as we would expect from the existing (HG1) implementation. There are two major differences though:

  • the figure toolbars/menubars are missing and cannot be shown, even when the relevant figure properties are set. Without a menubar and toobar, Matlab figures are extremely less useful than their HG1 counterparts. This problem does not occur in HG2-enabled figures in the regular Matlab session (i.e., without using the “-hgVersion 2” command-line option)
  • all the HG handles are now Matlab class handles rather than numeric values (These class handles are similar to those returned today (in HG1) using the undocumented handle function). There’s an exception to this rule: in regular Matlab sessions (i.e., without using the “-hgVersion 2” command-line option), after setting the ‘UseHG2’ feature on, the returned figure handle is numeric rather than a class handle (but if you now plot within this figure you get the class object handles). Here’s the output from the “-hgVersion 2” Matlab session:
    >> hFig = figure
    hFig =
    >> hLine = plot(1:5)
    hLine =
    >> get(hLine,'Parent')
    ans =
    >> findprop(gcf,'Tag')
    ans =
      meta.property handle
      Package: meta
                       Name: 'Tag'
                Description: 'Tag PropInfo'
        DetailedDescription: ''
                  GetAccess: 'public'
                  SetAccess: 'public'
                  Dependent: 1
                   Constant: 0
                   Abstract: 0
                  Transient: 0
                     Hidden: 0
              GetObservable: 1
              SetObservable: 1
                   AbortSet: 0
                  GetMethod: []
                  SetMethod: []
                 HasDefault: 0
              DefiningClass: [1x1 meta.class]
      Methods, Events, Superclasses
    >> methods(gcf)
    Methods for class ui.Figure:
    Figure                  disp                    get                     horzcat                 lt                      subsasgn
    addlistener             double                  getParentImpl           ishghandlewithargs      ne                      vertcat
    addprop                 eq                      getSceneViewer          ishghandlewoargs        notify
    applydefaultproperties  findobj                 getdisp                 isvalid                 reset
    cat                     findprop                gt                      java                    set
    delete                  ge                      hgclose                 le                      setdisp
    Static methods:
    >> methods(gcf,'-full')
    Methods for class ui.Figure:
    ui.Figure lhs1 Figure(rhs0)
    event.listener L addlistener(handle sources, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
    event.proplistener L addlistener(handle sources, meta.property propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
    event.proplistener L addlistener(handle sources, string propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
    event.proplistener L addlistener(handle sources, cell propertyname, char vector eventname, function_handle scalar callback)  % Inherited from hg2utils.HGHandle
    meta.property prop addprop(handle scalar object, string propname)  % Inherited from dynamicprops
    applydefaultproperties(HGHandle object, rhs1)  % Inherited from hg2utils.HGHandle
    HeterogeneousHandle lhs3 cat(double rhs0, rhs1, rhs2)  % Inherited from HeterogeneousHandle
    delete(handle obj)  % Inherited from handle
    disp(object)  % Inherited from hg2utils.HGHandle
    lhs1 double(handle object)  % Inherited from hg2utils.HGHandle
    logical TF eq(A, B)  % Inherited from hg2utils.HGHandle
    handle output findobj(handle object, varargin)  % Inherited from hg2utils.HGHandle
    meta.property prop findprop(handle scalar object, string propname)  % Inherited from handle
    logical TF ge(A, B)  % Inherited from handle
    varargout get(hgsetget object, rhs1)  % Inherited from hg2utils.HGHandle
    Static HeterogeneousHandle lhs0 getDefaultObject  % Inherited from hg2utils.HGHandle
    lhs2 getParentImpl(handle scalar object, rhs1)  % Inherited from hg2utils.HGObject
    lhs2 getSceneViewer(handle scalar object, rhs1)  % Inherited from ui.UISceneViewerParent
    getdisp(hgsetget rhs0)  % Inherited from hgsetget
    logical TF gt(A, B)  % Inherited from handle
    hgclose(handle scalar object)
    HeterogeneousHandle lhs2 horzcat(rhs0, rhs1)  % Inherited from HeterogeneousHandle
    lhs2 ishghandlewithargs(handle scalar object, rhs1)  % Inherited from hg2utils.HGObject
    lhs1 ishghandlewoargs(handle scalar object)  % Inherited from hg2utils.HGObject
    logical validity isvalid(handle obj)  % Inherited from handle
    j java(JavaVisible scalar h)  % Inherited from JavaVisible
    logical TF le(A, B)  % Inherited from handle
    logical TF lt(A, B)  % Inherited from handle
    logical TF ne(A, B)  % Inherited from hg2utils.HGHandle
    notify(handle sources, string eventname, event.EventData scalar eventdata)  % Inherited from handle
    notify(handle sources, string eventname)  % Inherited from handle
    reset(handle scalar object)  % Inherited from hg2utils.HGHandle
    varargout set(hgsetget object, rhs1)  % Inherited from hg2utils.HGHandle
    setdisp(hgsetget rhs0)  % Inherited from hgsetget
    varargout subsasgn(rhs0, rhs1, rhs2, rhs3)  % Inherited from HeterogeneousHandle
    HeterogeneousHandle lhs2 vertcat(rhs0, rhs1)  % Inherited from HeterogeneousHandle

The latest Matlab releases have shown how the Matlab handle class can be extended using user-created derived classes. It stands to reason that so do all the new HG2 objects. This would theoretically enable Matlab programmers to customize graphic objects appearance to suit their needs in a more intuitive manner than possible using HG1.
Many mysteries remain:

  • is it possible to mix HG1 and HG2 objects in the same figure?
  • can we switch between HG1 and HG2 in the same Matlab session (I got some crashes…)?
  • why is there a need for the separate feature options ‘UseHG2’, ‘UseGBT2’ and ‘HGUsingMatlabClasses’?
  • why is there a need for “-hgVersion 2” Matlab sessions if we can simply use feature(‘UseHG2’)?
  • is it possible to restore the figure menubar and toolbar in “-hgVersion 2” Matlab sessions?
  • is it indeed possible to extend HG2 objects using user-defined classes? and if so, can we modify the appearance/behavior beyond what is available in the existing list of HG2 properties?
  • beyond changing numeric handles into class handles, are there any actual benefits to the HG2 system over HG1?
  • what is the difference between HG2, GBT2 and GBT1.5 (which are mentioned together as separate entities in cameratoolbar.m)?

HG2 is still buggy, which explains why it is still not officially released. For example, the inspect(gca) function crashes Matlab, figure toolbars/menubars are missing, and some properties that are available in HG1 are missing in HG2. Also, we can add Java components to a Matlab figure using javacomponent as in HG1 (the returned container handles is a ui.HGJavaComponent class handle), but we get an error when we close the figure…
Still, with all this effort invested into HG2 I believe that it is only a matter of time before HG2 becomes officially released. This could happen perhaps even as soon as the upcoming R2010b release, but with the current state as seen above I suspect it will not happen before 2011. Also, my gut feeling is that Matlab will define any release that includes HG2 as a major release and we will finally have Matlab 8.0.
I would dearly love to hear any further information anyone discovers about HG2 and related issues. Please share your findings by email or in the comments section below.
Addendum Oct 3 2014: HG2 is finally released in Matlab release R2014b (8.4). It took more than 4 years after this article was posted for Mathworks to sort out all the problems in the new graphics engine. While HG2 is now fully supported, it contains numerous undocumented features and properties. I plan to discuss them in a separate upcoming series of articles.

Categories: Handle graphics, Hidden property, High risk of breaking in future versions, Undocumented feature, Undocumented function

13 Comments (Open | Close)

13 Comments To "Matlab's HG2 mechanism"

#1 Comment By Drazick On May 7, 2010 @ 05:07

That would be great if Mathworks would rewrite Matlab’s graphic stack.
It needs a major performance overhaul.

#2 Comment By SrSwEngr On August 10, 2010 @ 08:21

MATLAB should say goodbye to JAVA for all kinds of reason, performance is just one of them.

#3 Pingback By Is it possible to extend graphics objects’ functionality through inheritance? – Programmers Goodies On September 7, 2011 @ 08:01

[…] is a suggestion that it may be possible to extend the new HG2 classes here but this is not official Mathworks information […]

#4 Pingback By HG2 update | Undocumented Matlab On May 15, 2013 @ 17:38

[…] Exactly three years ago, I posted information (here and here) about Matlab’s upcoming new graphics engine, so-called HG2 […]

#5 Comment By Chandrakanth On May 16, 2013 @ 21:15

Any idea how to enable HG2 on linux/osx versions? Even after setting feature to use hg2, it returns hg1 handles in 8.0

#6 Comment By Yair Altman On May 17, 2013 @ 00:11

@Chandrakanth – you need to use the -hgVersion 2 startup switch in your Matlab command-line. feature is not the way

#7 Comment By ZZ On November 7, 2013 @ 05:04

This undocumented feature seems really attractive. I tried “open /Applications/MATLAB_R2013a.app -hgVersion 2” in the terminal in the OSX system, but it does not run the app. Would you teach me a right command ?

many thanks!

#8 Comment By Malcolm Lidierth On November 7, 2013 @ 09:25

I am not near a Mac at the moment, but think you need to add /bin/matlab.exe to the end of the application path.

#9 Comment By zz On November 7, 2013 @ 11:16

Thank you for your reply. Now it works quite well by following Chandrakanth’s method.

#10 Comment By Chandrakanth On November 7, 2013 @ 10:25

add /bin/matlab (NO exe)
/Applications/MATLAB_R2012b.app/bin/matlab -hgVersion 2
Works for me.

#11 Comment By zz On November 7, 2013 @ 11:20

A bunch of thanks !!!!
In fact I’ve tried “open /Applications/MATLAB_R2012b.app/bin/matlab -hgVersion 2” rather than your line. Now it works and I should to explore it more.

#12 Pingback By Customizing axes rulers | Undocumented Matlab On October 8, 2014 @ 07:43

[…] feed for updates on Undocumented Matlab topics.Over 4 years have passed since I’ve posted my scoop on Matlab upcoming new graphics system (a.k.a. HG2, Handle Graphics version 2). At that time HG2 […]

#13 Pingback By Render MATLAB figure in memory – DexPage On July 25, 2015 @ 14:59

[…] function named CAPTURESCREEN (although it seems that it will be using PRINT for the upcoming HG2 system where there is a new -RGBImage print […]

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/matlab-hg2

URLs in this post:

[1] posted: http://undocumentedmatlab.com/blog/undocumented-feature-function/

[2] hidden figure property: http://undocumentedmatlab.com/blog/displaying-hidden-handle-properties/

[3] discovered and reported: https://www.mathworks.com/matlabcentral/newsreader/view_thread/154510#387811

[4] UDD Properties : https://undocumentedmatlab.com/articles/udd-properties

[5] getundoc – get undocumented object properties : https://undocumentedmatlab.com/articles/getundoc-get-undocumented-object-properties

[6] Performance: accessing handle properties : https://undocumentedmatlab.com/articles/performance-accessing-handle-properties

[7] New information on HG2 : https://undocumentedmatlab.com/articles/new-information-on-hg2

[8] Adding dynamic properties to graphic handles : https://undocumentedmatlab.com/articles/adding-dynamic-properties-to-graphic-handles

[9] Draggable plot data-tips : https://undocumentedmatlab.com/articles/draggable-plot-data-tips

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.