Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

Customizing axes part 4 – additional properties

October 29, 2014 5 Comments

In the past three weeks I explained how HG2 (in R2014b) enables us to customize the axes rulers, back-drop, baselines, box and grid-lines in ways that were previously impossible in HG1 (R2014a or earlier). Today I will conclude the mini-series on axes customizations by describing other useful undocumented customizations of the HG2 axes:

  • Camera
  • SortMethod
  • WarpToFill
  • Additional properties

Camera

The Camera object (matlab.graphics.axis.camera.Camera3D) controls the 3D camera/lighting of the axes. Camera is a new hidden property of HG2 axes, that did not exist in earlier Matlab releases (HG1). This functionality is normally controlled via the 3D figure toolbar and related functions (view, camup, campos etc.). We can have better granularity by discretely customizing Camera‘s properties:

>> hAxes.Camera.get
               AspectRatio: 1
                  Children: []
      DepthCalculationHint: 'careful'
                 DepthSort: 'on'
          HandleVisibility: 'off'
                    Parent: [1x1 Axes]
        PlotBoxAspectRatio: [1 1 1]
    PlotBoxAspectRatioMode: 'auto'
                  Position: [-4.06571071756541 -5.45015005218426 4.83012701892219]
                Projection: 'orthographic'
                    Target: [0.5 0.5 0.5]
    TransparencyMethodHint: 'depthpeel'
                  UpVector: [0 0 1]
                 ViewAngle: 10.339584907202
                  Viewport: [1x1 matlab.graphics.general.UnitPosition]
                   Visible: 'on'
                WarpToFill: 'vertical'

>> hAxes.Camera.get AspectRatio: 1 Children: [] DepthCalculationHint: 'careful' DepthSort: 'on' HandleVisibility: 'off' Parent: [1x1 Axes] PlotBoxAspectRatio: [1 1 1] PlotBoxAspectRatioMode: 'auto' Position: [-4.06571071756541 -5.45015005218426 4.83012701892219] Projection: 'orthographic' Target: [0.5 0.5 0.5] TransparencyMethodHint: 'depthpeel' UpVector: [0 0 1] ViewAngle: 10.339584907202 Viewport: [1x1 matlab.graphics.general.UnitPosition] Visible: 'on' WarpToFill: 'vertical'

SortMethod

SortMethod is a newly-supported axes property in R2014b. It is new only in the sense that it became documented: It has existed in its present form also in previous Matlab releases, as a hidden axes property (I’m not sure exactly from which release). This is yet another example of an undocumented Matlab functionality that existed for many years before MathWorks decided to make it official (other examples in R2014b are the set of uitab/uitabgroup functions).
SortMethod is important due to its impact on graphic rendering performance: By default, Matlab draws objects in a back-to-front order based on the current view. This means that objects (lines, patches etc.) which should appear “on top” of other objects are drawn last, overlapping the objects “beneath” them. Calculating the order of the objects, especially in complex plots having multiple overlapping segments, can take noticeable time. We can improve performance by telling the renderer to draw objects in the order of the Children property, which is typically the order in which the objects were created. This can be done by setting the axes’ SortMethod property to ‘childorder’ (default=’depth’). Since SortOrder existed in past Matlab releases as well, we can use this technique on the older MATLAB releases just as for R2014b or newer.
In a related matter, we should note that transparent/translucent patches and lines (having a 4th Color element (alpha) value between 0.0 and 1.0) are slower to render for much the same reasons. Reducing the number of transparent/translucent objects will improve graphics rendering performance. Note that specifying a 4th Color element is again an undocumented feature: Matlab officially only supports RGB triplets and named color strings, not RGBA quadruplets. I’ll discuss this aspect next week.

WarpToFill

WarpToFill (default=’on’) is a simple flag that controls whether or not the axes should fill its container (panel or figure), leaving minimal margins. We can consider this as another variant to the documented alternatives of the axis function:

surf(peaks);
set(gca,'WarpToFill','off');

surf(peaks); set(gca,'WarpToFill','off');

HG2 axes WarpToFill on HG2 axes WarpToFill off
HG2 axes WarpToFill (on, off)

Note that WarpToFill is not new in R2014b – it has existed in its present form also in previous Matlab releases, as a hidden axes property. One would hope that it will finally become officially supported, as SortMethod above has.

Additional properties

Additional undocumented aspects of Matlab axes that I have reported over the years, including the LooseInset property and determining axes zoom state, still work in HG2 (R2014b). They might be removed someday, but hopefully they will take the opposite path that SortMethod did, of becoming fully supported.
On the other hand, some important undocumented HG1 axes properties have been removed: x_NormRenderTransform, x_ProjectionTransform, x_RenderOffset, x_RenderScale, x_RenderTransform, x_ViewPortTransform and x_ViewTransform could be used in HG1 axes to map between 3D and 2D data spaces. Some users have already complained about this. I have [still] not found a simple workaround for this, but I’m pretty sure that there is one. Maybe the hidden axes DataSpace property could be used for this, but I’m not sure how exactly. Edit: see my post on view transformations (and the reader comments on it).
This concludes my series on undocumented HG2 axes customizations (at least for now). Next week, I will describe undocumented HG2 plot-line customizations.

Related posts:

  1. Customizing axes part 2 – Matlab HG2 axes can be customized in many different ways. This article explains some of the undocumented aspects. ...
  2. Customizing axes part 3 – Backdrop – Matlab HG2 axes can be customized in many different ways. This article explains some of the undocumented aspects. ...
  3. Customizing axes rulers – HG2 axes can be customized in numerous useful ways. This article explains how to customize the rulers. ...
  4. Customizing axes part 5 – origin crossover and labels – The axes rulers (axles) can be made to cross-over at any x,y location within the chart. ...
  5. Customizing axes tick labels – Multiple customizations can be applied to tick labels. ...
  6. Plot LimInclude properties – The plot objects' XLimInclude, YLimInclude, ZLimInclude, ALimInclude and CLimInclude properties are an important feature, that has both functional and performance implications....
Handle graphics HG2 Hidden property Performance Pure Matlab Undocumented feature
Print Print
« Previous
Next »
5 Responses
  1. Jill B February 16, 2015 at 19:08 Reply

    Hi Yair-

    Great information. I’ve been using some code that accessed x_RenderTransform, x_RenderOffset, and x_RenderScale undocumented properties in HG1, that “broke” in HG2. I’ve been in search of a solution, and your tips in your blog are the closest I’ve come. I’m ever hopeful that a workaround will arise, but I’m not experienced enough to take it myself.

    Thanks for the blog,
    Jill

  2. Sher Raza May 6, 2015 at 23:46 Reply

    Has anyone found an alternative to the x_RenderOffset, x_RenderScale, x_RenderTransform axes properties? I have been working for a long time and have not found a workaround.

    Sher

    • Yair Altman May 7, 2015 at 00:56 Reply

      @Sher – have you seen my recent post on view transformations (and the reader comments on it)?

  3. Konstantin Alexeev May 7, 2015 at 05:14 Reply

    Hello Yair,

    I used the select3d tool from matlab file exchange to find, where the mouse clicked on 3d, surface. Since matlab 2014, the select3d function seems to don’t work anymore because, “x_RenderTransform” and other propertiese were removed.

    However, now the matlab provides the coordinates of the section of mouse point and the surface as the second parameter of the surface callback.

    K>> varargin{2}

    ans =

    Hit with properties:

    Button: 1
    IntersectionPoint: [20.8219 16.8589 20.7370]
    Source: [1×1 Surface]
    EventName: ‘Hit’

  4. RayInos November 15, 2015 at 08:33 Reply

    Hey everybody!

    I got a little update on this one, fixing the select3d for Matlab >= R14b.

    Replacing

    % Transform vertices from data space to pixel space
    xvert = local_Data2PixelTransform(ax,vert)';
    xcp = local_Data2PixelTransform(ax,cp')';

    % Transform vertices from data space to pixel space xvert = local_Data2PixelTransform(ax,vert)'; xcp = local_Data2PixelTransform(ax,cp')';

    with

    % Transform vertices from data space to pixel space (fixed for Matlab R2014b+)
    if ~graphicsversion(get(ax,'Parent'),'handlegraphics')
      xvert = specgraphhelper('convertDataSpaceCoordsToViewerCoords', axchild, vert');
      xcp   = specgraphhelper('convertDataSpaceCoordsToViewerCoords', ax, cp);
    else
      xvert = local_Data2PixelTransform(ax,vert)';
      xcp   = local_Data2PixelTransform(ax,cp')';
    end

    % Transform vertices from data space to pixel space (fixed for Matlab R2014b+) if ~graphicsversion(get(ax,'Parent'),'handlegraphics') xvert = specgraphhelper('convertDataSpaceCoordsToViewerCoords', axchild, vert'); xcp = specgraphhelper('convertDataSpaceCoordsToViewerCoords', ax, cp); else xvert = local_Data2PixelTransform(ax,vert)'; xcp = local_Data2PixelTransform(ax,cp')'; end

    should work perfectly all right (tested with linear axes and DataAspectRatio=1).

    One might change the condition

      ~graphicsversion(get(ax,'Parent'),'handlegraphics')

    ~graphicsversion(get(ax,'Parent'),'handlegraphics')

    to something more elegant. This code line assumes the axes object ax is direct child to the figure (which fits in my case). An alternative might be checking the matlab version with

      ~verLessThan('matlab','8.4')

    ~verLessThan('matlab','8.4')

    , since the graphics update came in 8.4 (R14b).

    Note, that the transposition of vert and cp in the arguments of specgraphhelper(…) is crucial to the result. Transposing one of them leads to wrong results.

    Hope it helps,
    Ray

Leave a Reply
HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:
<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>
I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitable (6) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top