Matlab Core Graphics Objects

Core graphics objects include basic drawing primitives:

• Line, text, and polygon shells (patch objects)
• Specialized objects like surfaces, which are composed of a rectangular grid of vertices
• Images
• Light objects, which are not visible but affect the way some objects are colored

Axes contain objects that represent data, such as line, surfaces, contourgroups, etc.

The following table lists the core graphics objects and contains links to the reference pages of the functions used to create each object.

Core Graphics Objects

The following picture illustrates some typical core graphics objects.

Core Graphics Objects

This section describes the core graphics objects.

Axes

Axes objects define a frame of reference in a figure window for the display objects that are generally defined by data. For example, MATLAB creates a line by connecting each data point with a line segment. The axes determines the location of each data point in the figure by defining axis scales (x, y, and z, or radius and angle, etc.)

Axes are children of figures and are parents of core, plot, and group objects.

While annotation objects are also children of axes, they can be parented only to the hidden annotation axes. (See the annotation function for more information.)

All functions that draw graphics (e.g., plot, surf, mesh, and bar) create an axes object if one does not exist. If there are multiple axes within the figure, one axes is always designated as the “current” axes, and is the target for display of the above-mentioned graphics objects. (Uicontrols and uimenus are not children of axes.)

Image

A MATLAB image consists of a data matrix and possibly a colormap. There are three basic image types that differ in the way that data matrix elements are interpreted as pixel colors—indexed, intensity, and truecolor. Since images are strictly 2-D, you can view them only at the default 2-D view.

Light

Light objects define light sources that affect all patch and surface objects within the axes. You cannot see lights, but you can set properties that control the style of light source, color, location, and other properties common to all graphics objects.

Line

Line objects are the basic graphics primitives used to create most 2-D and some 3-D plots. High-level functions plot, plot3, and loglog (and others) create line objects. The coordinate system of the axes positions and orients the line.

Patch

Patch objects are filled polygons with edges. A single patch can contain multiple faces, each colored independently with solid or interpolated colors. fill, fill3, and contour3 create patch objects. The coordinate system of the axes positions and orients the patch.

Rectangle

Rectangle objects are 2-D filled areas having a shape that can range from a rectangle to an ellipse. Rectangles are useful for creating flowchart-type drawings.

Surface

Surface objects are 3-D representations of matrix data created by plotting the value of each matrix element as a height above the x-y plane. Surface plots are composed of quadrilaterals whose vertices are specified by the matrix data. MATLAB can draw surfaces with solid or interpolated colors or with only a mesh of lines connecting the points. The coordinate system of the axes positions and orients the surface.

The high-level function pcolor and the surf and mesh group of functions create surface objects.

Text

Text objects are character strings. The coordinate system of the parent axes positions the text. The high-level functions title, xlabel, ylabel, zlabel, and gtext create text objects.

Example — Creating Core Graphics Objects

Object creation functions have a syntax of the form

handle = function('propertyname',propertyvalue,...)

You can specify a value for any object property (except those that are read only) by passing property name/value pairs as arguments. The function returns the handle of the object it creates, which you can use to query and modify properties after creating the object.

This example evaluates a mathematical function and creates three graphics objects using the property values specified as arguments to the figure, axes, and surface commands. MATLAB uses default values for all other properties.

[x,y] = meshgrid([-2:.4:2]);
Z = x.*exp(-x.^2-y.^2);
fh = figure('Position',[350 275 400 300],'Color','w');
ah = axes('Color',[.8 .8 .8],'XTick',[-2 -1 0 1 2],...
          'YTick',[-2 -1 0 1 2]);
sh = surface('XData',x,'YData',y,'ZData',Z,...
             'FaceColor',get(ah,'Color')+.1,...
             'EdgeColor','k','Marker','o',...
             'MarkerFaceColor',[.5 1 .85]);

The surface function does not use a 3-D view like the high-level surf functions. Object creation functions simply add new objects to the current axes without changing axes properties, except the Children property, which now includes the new object and the axis limits (XLim, YLim, and ZLim), if necessary.

You can change the view using the camera commands or use the view command.
view(3)

Parenting

view(3)

By default, all statements that create graphics objects do so in the current figure and the current axes (if the object is an axes child). However, you can specify the parent of an object when you create it. For example,

axes('Parent',figure_handle,...)

creates an axes in the figure identified by figure_handle. You can also move an object from one parent to another by redefining its Parent property:

High-Level Versus Low-Level Functions

set(gca,'Parent',figure_handle)

Many MATLAB graphics functions call the object creation functions to draw graphics objects. However, high-level routines also clear the axes or create a new figure, depending on the settings of the axes and figure NextPlot properties.

In contrast, core object creation functions simply create their respective graphics objects and place them in the current parent object. They do not respect the settings of the figure or axes NextPlot property.

For example, if you call the line function,

line('XData',x,'YData',y,'ZData',z,'Color','r')

MATLAB draws a red line in the current axes using the specified data values. If there is no axes, MATLAB creates one. If there is no figure window in which to create the axes, MATLAB creates it as well.

If you call the line function a second time, MATLAB draws the second line in the current axes without erasing the first line. This behavior is different from high-level functions like plot that delete graphics objects and reset all axes properties (except Position and Units). You can change the behavior of high-level functions by using the hold command or by changing the setting of the axes NextPlot property.

See Controlling Graphics Output for more information on this behavior and on using the NextPlot property.

Simplified Calling Syntax

Object creation functions have convenience forms that allow you to use a simpler syntax. For example,

text(.5,.5,.5,'Hello')

is equivalent to

text('Position',[.5 .5 .5],'String','Hello')

Using the convenience form of an object creation function can cause subtle differences in behavior when compared to formal property name/property value syntax.

[note]

A Note About Property Names

[/note]

By convention, MATLAB documentation capitalizes the first letter of each word that makes up a property name, such as LineStyle or XTickLabelMode. While this makes property names easier to read, MATLAB does not check for uppercase letters. In addition, you need to use only enough letters to identify the name uniquely, so you can abbreviate most property names.

In your code, however, using the full property name can prevent problems with futures releases of MATLAB if a shortened name is no longer unique because of the addition of new properties.