MATLAB R2014b Graphics – Part 2: Using Graphics Objects

Today, David Garrison, our guest blogger, will continue his series on the new graphics system in R2014b.

Here is Part 2 of the series.

Contents

What have we learned so far?

In Part 1 of this series, I provided an introduction to the new MATLAB graphics system in R2014b. I described a number of new features and alluded to one of the big changes in R2014b -- graphics functions return MATLAB objects, not numeric handles.

The MATLAB Graphics System

When I use MATLAB, I usually don't think about the internal graphics system. Usually, I'm just trying to visualize some data. I might call one of the MATLAB charting functions, like plot or bar to understand something important about my data. I also create user interfaces using functions like uicontrol or uipanel. These are functions that are part of the MATLAB graphics system.

Let's suppose that I am creating a plot and I want the line in the plot to be red. I can do that in one of two ways. I can call the plot function with some extra arguments like this.

x = 0:0.1:10;
y = sin(x);
plot(x,y,'Color','red')

I can also use the output argument of the plot command to modify my plot after I've created it. Here I created the plot first, then used the set command to change the color of the line.

p = plot(x,y) ;
set(p, 'Color', 'red')

Pre-R2014b Numeric Handles

Prior to R2014b, a call to a graphics function would return a number like this

p = plot(x,y)

p =

    174.346

The value of the variable p was a special kind of number called a handle. The handle was a reference to a graphics object. The object itself was not available to the user but you could use the handle to retrieve or change properties of the object using the set and get commands. In the example above, we used the handle of the line object to set its color. In fact, when this capability first became available in MATLAB, this approach was so new and useful it was given a special name -- Handle Graphics.

All graphics handles were just numeric values. Those values were integers for figures and fractional values for everything else. You could use a handle anywhere you could use a number. I've seen MATLAB code where people stored their handles with other data in a double array or used handles in functions where a number is expected as the argument (e.g. math functions).

As you probably know, graphics objects are stored as a tree structure with parents and children. There is a special object at the top of the tree called the graphics root. Prior to R2014b, the handle to the graphics root was always 0. For example to get the list of all open figures, you could type:

myFigures = get(0, 'Children');

R2014b Graphics Objects

In R2014b, graphics functions do not return numeric handles any more. They now return MATLAB objects. Now when you call a graphics function with an output argument, you see something like this:

p = plot(x,y)

p = 

  Line with properties:

              Color: [0 0.4470 0.7410]
          LineStyle: '-'
          LineWidth: 0.5000
             Marker: 'none'
         MarkerSize: 6
    MarkerFaceColor: 'none'
              XData: [1x101 double]
              YData: [1x101 double]
              ZData: [1x0 double]

  Use GET to show all properties

The plot function now returns a Line object. That line object has properties. When MATLAB displays the line object in the command window, it shows the object's most common properties. The all properties text is a hyperlink that you can click to see all the properties of the object.

If you use the whos function to see more information about p, you see something like this:

whos p

  Name      Size            Bytes  Class                                   Attributes

  p         1x1               112  matlab.graphics.chart.primitive.Line              

The Class column in the whos output indicates what kind of object if is. What you see here is the full class name of the object. Don't worry too much about the details of the class name. Most of you will never need to use it.

In R2014b, use the groot function to refer to the graphics root.

groot

ans = 

  Graphics Root with properties:

          CurrentFigure: [1x1 Figure]
    ScreenPixelsPerInch: 96
             ScreenSize: [1 1 1920 1200]
       MonitorPositions: [1 1 1920 1200]
                  Units: 'pixels'

  Use GET to show all properties

Getting and Setting Object Properties

One of the benefits of having graphic objects is that you can now get and set their values using dot notation. Dot notation has the form object.Property. It is the same syntax that you use when you want to refer to the field of a structure. For example, in R2014b, you can get the color of the line above like this:

p.Color

ans =

         0    0.4470    0.7410

Similarly, you can set the line width of the line using dot notation.

p.LineWidth = 2;

Dot notation is also useful if you want to set properties of two objects to be the same. Prior to R2014b, you might write code that looks like this:

set(p2, 'Color', get(p1, 'Color'))

With dot notation, you can do the same thing with

p2.Color = p1.Color;

With dot notation you can also use tab completion when you are trying to access a graphics object property.

You can still use the set and get functions but I find dot notation a much more convenient way to refer to object properties. One note of caution, however. When you use dot notation you must use the correct capitalization of the property name. For example,

p.LineWidth

will return the value of the line width but

p.linewidth

will cause an error.

Using set and get

As I mentioned above, you can still use the set and get functions and there are cases where set and get are useful.

You can use the get command if you want to know all the properties of a graphics object. This is the same list of properties you see if you click the all properties link in the example above.

get(p)

    AlignVertexCenters: 'off'
            Annotation: [1x1 matlab.graphics.eventdata.Annotation]
          BeingDeleted: 'off'
            BusyAction: 'queue'
         ButtonDownFcn: ''
              Children: []
              Clipping: 'on'
                 Color: [0 0.4470 0.7410]
             CreateFcn: ''
             DeleteFcn: ''
           DisplayName: ''
      HandleVisibility: 'on'
               HitTest: 'on'
         Interruptible: 'on'
             LineStyle: '-'
             LineWidth: 2
                Marker: 'none'
       MarkerEdgeColor: 'auto'
       MarkerFaceColor: 'none'
            MarkerSize: 6
                Parent: [1x1 Axes]
         PickableParts: 'visible'
              Selected: 'off'
    SelectionHighlight: 'on'
                   Tag: ''
                  Type: 'line'
         UIContextMenu: []
              UserData: []
               Visible: 'on'
                 XData: [1x101 double]
             XDataMode: 'manual'
           XDataSource: ''
                 YData: [1x101 double]
           YDataSource: ''
                 ZData: [1x0 double]
           ZDataSource: ''

The set function is useful if you want to know what options are available for a given property. In this case you can call set with the property name but no value for the property.

set(p,'LineStyle')

    '-'
    '--'
    ':'
    '-.'
    'none'

Another use of set occurs when you need to reference a property from an array of graphics objects. Suppose you have an array of line objects created by the plot command:

x = 0:0.1:10;
y1 = sin(x);
y2 = cos(x);
lineArray = plot(x,y1,x,y2)

lineArray = 

  2x1 Line array:

  Line
  Line

You can use the set function to change the colors of all the lines in the array in a single command.

set(lineArray, 'Color', 'blue')

Have you starting using graphics objects in R2014b?

What do you think about the change to graphics objects in R2014b? Have you tried using dot notation for getting and setting graphics object properties?

Next up -- Part 3: Compatibility Considerations in the New Graphics System

There are some other changes in R2014b that will impact some existing MATLAB code. These changes mostly impact advanced graphics users and people who build more complicated user interfaces. Next time, I will describe the important changes and what steps you should take to make your code compatible with R2014b. I'll also give you some guidance on how to write code that works in multiple releases.

Get the MATLAB code

Published with MATLAB® R2014b