A few days ago I posted 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 (UseHG2). In normal Matlab usage, this boolean property is ‘off’:
>> get(gcf,'usehg2') ans = off |
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 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 = ui.Figure >> hLine = plot(1:5) hLine = hg2.Lineseries >> get(hLine,'Parent') ans = hg2.Axes >> findprop(gcf,'Tag') ans = meta.property handle Package: meta Properties: 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: getDefaultObject >> 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.
That would be great if Mathworks would rewrite Matlab’s graphic stack.
It needs a major performance overhaul.
MATLAB should say goodbye to JAVA for all kinds of reason, performance is just one of them.
[…] is a suggestion that it may be possible to extend the new HG2 classes here but this is not official Mathworks information […]
[…] Exactly three years ago, I posted information (here and here) about Matlab’s upcoming new graphics engine, so-called HG2 […]
Any idea how to enable HG2 on linux/osx versions? Even after setting feature to use hg2, it returns hg1 handles in 8.0
Thanks.
@Chandrakanth – you need to use the
-hgVersion 2startup switch in your Matlab command-line. feature is not the wayThis 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!
@ZZ
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.
ML
Thank you for your reply. Now it works quite well by following Chandrakanth’s method.
@ZZ
add /bin/matlab (NO exe)
/Applications/MATLAB_R2012b.app/bin/matlab -hgVersion 2
Works for me.
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.
[…] 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 […]
[…] function named CAPTURESCREEN (although it seems that it will be using PRINT for the upcoming HG2 system where there is a new -RGBImage print […]