MATLAB Function Reference (Volume 2: Graphics)

MATLAB Function Reference (Volume 2: Graphics)
MATLAB

The Language of Technical Computing
Computation
Visualization
Programming
MATLAB Function Reference
(Volume 2: Graphics)
Version 5
How to Contact The MathWorks:
☎
(508) 647-7000
Phone
(508) 647-7001
Fax
The MathWorks, Inc.
24 Prime Park Way
Natick, MA 01760-1500
Mail
http://www.mathworks.com
Web
Anonymous FTP server
Newsgroup
FAX
MAIL
✉
INTERNET
ftp.mathworks.com
comp.soft-sys.matlab
@
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
Technical support
Product enhancement suggestions
Bug reports
Documentation error reports
Subscribing user registration
Order status, license renewals, passcodes
Sales, pricing, and general information
MATLAB Function Reference (online version, January 1998: Revised for MATLAB 5.2)
 COPYRIGHT 1984 - 1998 by The MathWorks, Inc. All Rights Reserved.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathWorks, Inc.
U.S. GOVERNMENT: If Licensee is acquiring the software on behalf of any unit or agency of the U. S.
Government, the following shall apply:
(a) for units of the Department of Defense:
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause
at DFARS 252.227-7013.
(b) for any other unit or agency:
NOTICE - Notwithstanding any other lease or license agreement that may pertain to, or accompany the
delivery of, the computer software and accompanying documentation, the rights of the Government
regarding its use, reproduction and disclosure are as set forth in Clause 52.227-19(c)(2) of the FAR.
Contractor/manufacturer is The MathWorks Inc., 24 Prime Park Way, Natick, MA 01760-1500.
MATLAB, Simulink, Handle Graphics, and Real-Time Workshop are registered trademarks and Stateflow and
Target Language Compiler are trademarks of The MathWorks, Inc.
Other product or brand names are trademarks or registered trademarks of their respective holders.
Contents
Command Summary
1
Graphical Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Graphical User Interface Creation . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Reference
2
List of Commands
Function Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–2
i
ii
Contents
1
Command Summary
This chapter lists MATLAB commands by functional area.
1
Command Summary
Graphical Visualization
Basic Plots and Graphs
bar
barh
hist
hold
loglog
pie
plot
polar
semilogx
semilogy
subplot
Vertical bar chart
Horizontal bar chart
Plot histograms
Hold current graph
Plot using log-log scales
Pie plot
Plot vectors or matrices.
Polar coordinate plot
Semi-log scale plot
Semi-log scale plot
Create axes in tiled positions
Three-Dimensional Plotting
bar3
bar3h
comet3
cylinder
fill3
plot3
quiver3
slice
sphere
stem3
waterfall
Vertical 3-D bar chart
Horizontal 3-D bar chart
3-D comet plot
Generate cylinder
Draw filled 3-D polygons in 3-space
Plot lines and points in 3-D space
3-D quiver (or velocity) plot
Volumetric slice plot
Generate sphere
Plot discrete surface data
Waterfall plot
Plot Annotation and Grids
clabel
datetick
grid
gtext
legend
plotyy
title
xlabel
ylabel
zlabel
1-2
Add contour labels to a contour plot
Date formatted tick labels
Grid lines for 2-D and 3-D plots
Place text on a 2-D graph using a mouse
Graph legend for lines and patches
Plot graphs with Y tick labels on the left and right
Titles for 2-D and 3-D plots
X-axis labels for 2-D and 3-D plots
Y-axis labels for 2-D and 3-D plots
Z-axis labels for 3-D plots
Surface, Mesh, and Contour Plots
contour
contourc
contourf
hidden
meshc
mesh
peaks
surf
surface
surfc
surfl
trimesh
trisurf
Contour (level curves) plot
Contour computation
Filled contour plot
Mesh hidden line removal mode
Combination mesh/contourplot
3-D mesh with reference plane
A sample function of two variables
3-D shaded surface graph
Create surface low-level objects
Combination surf/contourplot
3-D shaded surface with lighting
Triangular mesh plot
Triangular surface plot
Domain Generation
griddata
meshgrid
Data gridding and surface fitting
Generation of X and Y arrays for 3-D plots
Specialized Plotting
area
box
comet
compass
errorbar
ezplot
feather
fill
fplot
pareto
pie3
plotmatrix
pcolor
rose
quiver
ribbon
stairs
scatter
scatter3
stem
convhull
Area plot
Axis box for 2-D and 3-D plots
Comet plot
Compass plot
Plot graph with error bars
Easy to use function plotter
Feather plot
Draw filled 2-D polygons
Plot a function
Pareto chart
3-D pie plot
Scatter plot matrix
Pseudocolor (checkerboard) plot
Plot rose or angle histogram
Quiver (or velocity) plot
Ribbon plot
Stairstep graph
Scatter plot
3-D scatter plot
Plot discrete sequence data
Convex hull
1-3
1
Command Summary
delaunay
dsearch
inpolygon
polyarea
tsearch
voronoi
Delaunay triangulation
Search Delaunay triangulation for nearest point
True for points inside a polygonal region
Area of polygon
Search for enclosing Delaunay triangle
Voronoi diagram
View Control
camdolly
camlookat
camorbit
campan
campos
camproj
camroll
camtarget
camup
camva
camzoom
daspect
pbaspect
view
viewmtx
xlim
ylim
zlim
Move camera position and target
View specific objects
Orbit about camera target
Rotate camera target about camera position
Set or get camera position
Set or get projection type
Rotate camera about viewing axis
Set or get camera target
Set or get camera up-vector
Set or get camera view angle
Zoom camera in or out
Set or get data aspect ratio
Set or get plot box aspect ratio
3-D graph viewpoint specification.
Generate view transformation matrices
Set or get the current x-axis limits
Set or get the current y-axis limits
Set or get the current z-axis limits
Lighting
camlight
diffuse
lighting
material
specular
Cerate or position Light
Diffuse reflectance
Lighting mode
Material reflectance mode
Specular reflectance
Color Operations
brighten
bwcontr
caxis
colorbar
colorcube
1-4
Brighten or darken color map
Contrasting black and/or color
Pseudocolor axis scaling
Display color bar (color scale)
Enhanced color-cube color map
colordef
colormap
graymon
hsv2rgb
rgb2hsv
rgbplot
shading
spinmap
surfnorm
whitebg
Set up color defaults
Set the color look-up table
Graphics figure defaults set for grayscale monitor
Hue-saturation-value to red-green-blue conversion
RGB to HSVconversion
Plot color map
Color shading mode
Spin the colormap
3-D surface normals
Change axes background color for plots
Colormaps
autumn
bone
contrast
cool
copper
flag
gray
hot
hsv
jet
lines
prism
spring
summer
winter
Shades of red and yellow color map
Gray-scale with a tinge of blue color map
Gray color map to enhance image contrast
Shades of cyan and magenta color map
Linear copper-tone color map
Alternating red, white, blue, and black color map
Linear gray-scale color map
Black-red-yellow-white color map
Hue-saturation-value (HSV) color map
Variant of HSV
Line color colormap
Colormap of prism colors
Shades of magenta and yellow color map
. . . . . . . . . . . . . . . . . . . Shades of green and yellow colormap
Shades of blue and green color map
Printing
frameedit
hardcopy
orient
print
printopt
savtoner
Create or edit printframes
Save figure window to file
Hardcopy paper orientation
Print graph or save graph to file
Configure local printer defaults
Modify graphic objects to print on a white background
Handle Graphics, General
copyobj
findobj
gcbo
Make a copy of a graphics object and its children
Find objects with specified property values
Return object whose callback is currently executing
1-5
1
Command Summary
gco
get
rotate
ishandle
set
Return handle of current object
Get object properties
Rotate objects about specified origin and direction
True for graphics objects
Set object properties
Handle Graphics, Object Creation
axes
figure
image
light
line
patch
surface
text
uicontext
Create Axes object
Create Figure (graph) windows
Create Image (2-D matrix)
Create Light object (illuminates Patch and Surface)
Create Line object (3-D polylines)
Create Patch object (polygons)
Create Surface (quadrilaterals)
Create Text object (character strings)
Create context menu (popup associated with object)
Handle Graphics, Figure Windows
capture
clc
clf
clg
close
gcf
newplot
refresh
Screen capture of the current figure
Clear figure window
Clear figure
Clear figure (graph window)
Close specified window
Get current figure handle
Graphics M-file preamble for NextPlot property
Refresh figure
Handle Graphics, Axes
axis
cla
gca
Plot axis scaling and appearance
Clear Axes
Get current Axes handle
Object Manipulation
propedit
Edit all properties of any selected object
reset
Reset axis or figure
rotate3d
Interactively rotate the view of a 3-D plot
selectmoveresizeInteractively select, move, or resize objects
shg
Show graph window
1-6
Interactive User Input
ginput
zoom
Graphical input from a mouse or cursor
Zoom in and out on a 2-D plot
Region of Interest
dragrect
drawnow
rbbox
Drag XOR rectangles with mouse
Complete any pending drawing
Rubberband box
Graphical User Interface Creation
Dialog Boxes
dialog
errordlg
helpdlg
inputdlg
listdlg
msgbox
pagedlg
printdlg
questdlg
uigetfile
uiputfile
uisetcolor
uisetfont
warndlg
Create a dialog box
Create error dialog box
Display help dialog box
Create input dialog box
Create list selection dialog box
Create message dialog box
Display page layout dialog box
Display print dialog box
Create question dialog box
Display dialog box to retrieve name of file for reading
Display dialog box to retrieve name of file for writing
Interactively set a ColorSpec using a dialog box
Interactively set a font using a dialog box
Create warning dialog box
User Interface Objects
menu
Generate a menu of choices for user input
menuedit
Menu editor
uicontextmenu Create context menu
uicontrol
Create user interface control
uimenu
Create user interface menu
Other Functions
dragrect
Drag rectangles with mouse
gcbo
Return handle of object whose callback is executing
rbbox
Create rubberband box for area selection
selectmoveresizeSelect, move, resize, or copy Axes and Uicontrol graphics objects
textwrap
Return wrapped string matrix for given Uicontrol
1-7
1
Command Summary
uiresume
Used with uiwait, controls program execution
uiwait
Used with uiresume, controls program execution
waitbar
Display wait bar
waitforbuttonpressWait for key/buttonpress over figure
1-8
2
Reference
This chapter describes all MATLAB operators, commands,
and functions in alphabetical order.
2
2-2
Reference
area
Purpose
2area
Area fill of a two-dimensional plot
Syntax
area(Y)
area(X,Y)
area(...,ymin)
area(...,'PropertyName',PropertyValue,...)
h = area(...)
Description
An area plot displays elements in Y as one or more curves and fills the area
beneath each curve. When Y is a matrix, the curves are stacked showing the
relative contribution of each row element to the total height of the curve at each
x interval.
area(Y) plots the vector Y or the sum of each column in matrix Y. The x-axis
automatically scales depending on length(Y) when Y is a vector, and on
size(Y,1)when Y is a matrix.
area(X,Y) plots Y at the corresponding values of X. If X is a vector, length(X)
must equal length(Y) and X must be monotonic. If X is a matrix, size(X) must
equal size(Y) and each column in X must be monotonic. To make a vector or
matrix monotonic, use sort.
area(...,ymin) specifies the lower limit in the y direction for the area fill. The
default ymin is 0.
area(...,'PropertyName',PropertyValue,...) specifies property name
and property value pairs for the Patch graphics object created by area.
h = area(...) returns handles of Patch graphics objects. area creates one
Patch object per column in Y.
Remarks
area creates one curve from all elements in a vector or one curve per column in
a matrix. The colors of the curves are selected from equally spaced intervals
throughout the entire range of the colormap.
2-3
area
Examples
Plot the values in Y as a stacked area plot:
Y = [
1,
3,
1,
2,
5,
2,
5,
6,
3;
7;
3;
1];
area(Y)
grid on
colormap summer
set(gca,'Layer','top')
title 'Stacked Area Plot'
Stacked Area Plot
12
10
8
6
4
2
0
1
See Also
2-4
plot
1.5
2
2.5
3
3.5
4
axes
Purpose
2axes
Create Axes graphics object
Syntax
axes
axes('PropertyName',PropertyValue,...)
axes(h)
h = axes(...)
Description
axes is the low-level function for creating Axes graphics objects.
axes creates an Axes graphics object in the current Figure using default
property values.
axes('PropertyName',PropertyValue,...) creates an Axes object having
the specified property values. MATLAB uses default values for any properties
that you do not explicitly define as arguments.
axes(h) makes existing axes h the current Axes. It also makes h the first Axes
listed in the Figure’s Children property and sets the Figure’s CurrentAxes
property to h. The current Axes is the target for functions that draw Image,
Line, Patch, Surface, and Text graphics objects.
h = axes(...) returns the handle of the created Axes object.
Remarks
MATLAB automatically creates an Axes, if one does not already exist, when
you issue a command that draws Image, Light, Line, Patch, Surface, or Text
graphics objects.
The axes function accepts property name/property value pairs, structure
arrays, and cell arrays as input arguments (see the set and get commands for
examples of how to specify these data types). These properties, which control
various aspects of the Axes object, are described in the “Axes Properties”
section.
Use the set function to modify the properties of an existing Axes or the get
function to query the current values of Axes properties. Use the gca command
to obtain the handle of the current Axes.
The axis (not axes) function provides simplified access to commonly used
properties that control the scaling and appearance of Axes.
2-5
axes
While the basic purpose of an Axes object is to provide a coordinate system for
plotted data, Axes properties provide considerable control over the way
MATLAB displays data.
Stretch-to-Fill
By default, MATLAB stretches the Axes to fill the Axes position rectangle (the
rectangle defined by the last two elements in the Position property). This
results in graphs that use the available space in the rectangle. However, some
3-D graphs (such as a sphere) appear distorted because of this stretching, and
are better viewed with a specific three-dimensional aspect ratio.
Stretch-to-fill is active when the DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto (the
default). However, stretch-to-fill is turned off when the DataAspectRatio,
PlotBoxAspectRatio, or CameraViewAngle is user-specified, or when one or
more of the corresponding modes is set to manual (which happens
automatically when you set the corresponding property value).
This picture shows the same sphere displayed both with and without the
stretch-to-fill. The dotted lines show the Axes Position rectangle.
1
1
8
0.8
6
0.6
4
0.4
2
0.2
0
0
2
−0.2
4
−0.4
6
−0.6
8
−0.8
1
−1
−0.8
−0.6
−0.4
−0.2
0
0.2
0.4
Stretch-to-fill active
0.6
0.8
1
−1
−1
−0.5
0
0.5
1
Stretch-to-fill disabled
When stretch-to-fill is disabled, MATLAB sets the size of the Axes to be as large
as possible within the constraints imposed by the Position rectangle without
introducing distortion. In the picture above, the height of the rectangle
constrains the Axes size.
2-6
axes
Examples
Zooming
Zoom in using aspect ratio and limits:
sphere
set(gca,'DataAspectRatio',[1 1 1],...
'PlotBoxAspectRatio',[1 1 1],'ZLim',[−0.6 0.6])
Zoom in and out using the CameraViewAngle:
sphere
set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')−5)
set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')+5)
Note that both examples disable MATLAB’s stretch-to-fill behavior.
Positioning the Axes
The Axes Position property enables you to define the location of the Axes
within the Figure window. For example,
h = axes('Position',position_rectangle)
creates an Axes object at the specified position within the current Figure and
returns a handle to it. Specify the location and size of the Axes with a rectangle
defined by a four-element vector,
position_rectangle = [left, bottom, width, height];
The left and bottom elements of this vector define the distance from the
lower-left corner of the Figure to the lower-left corner of the rectangle. The
width and height elements define the dimensions of the rectangle. You specify
these values in units determined by the Units property. By default, MATLAB
uses normalized units where (0,0) is the lower-left corner and (1.0,1.0) is the
upper-right corner of the Figure window.
You can define multiple Axes in a single Figure window:
axes('position',[.1 .1
mesh(peaks(20));
axes('position',[.1 .7
pcolor([1:10;1:10]);
.8
.6])
.8
.2])
2-7
axes
In this example, the first plot occupies the bottom two-thirds of the Figure, and
the second occupies the top third.
2
1.5
1
1
2
3
4
5
6
7
8
9
10
10
5
0
−5
−10
20
15
20
15
10
10
5
0
See Also
2-8
5
0
axis, cla, clf, figure, gca, grid, subplot, title, xlabel, ylabel, zlabel,
view
axes
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Axes properties on the Figure and Root levels:
set(0,'DefaultAxesPropertyName',PropertyValue,...)
set(gcf,'DefaultAxesPropertyName',PropertyValue,...)
where PropertyName is the name of the Axes property and PropertyValue is
the value you are specifying. Use set and get to access Axes properties.
Property List
Property Name
The following table lists all Axes properties and provides a brief description of
each. The property name links take you an expanded description of the
properties.
Property Description
Property Value
Controlling Style and Appearance
Box
Toggle axes plot box on and off
Clipping
This property has no effect; axes are
always clipped to the figure window
GridLineStyle
Line style used to draw axes grid
lines
Values: −, −−, :, -., none
Default: : (dotted line)
Layer
Draw axes above or below graphs
Values: bottom, top
Default: bottom
Values: on, off
Default: off
2-9
axes
Property Name
Property Description
Property Value
LineStyleOrder
Sequence of line styles used for
multiline plots
Values: LineSpec
Default: − (solid line for)
LineWidth
Width of axis lines, in points (1/72"
per point)
Values: number of points
Default: 0.5 points
SelectionHighlight
Highlight axes when selected
(Selected property set to on)
Values: on, off Default: on
TickDir
Direction of axis tick marks
Values: in, out
Default: in (2-D), out (3-D)
TickDirMode
Use MATLAB or user-specified tick
mark direction
Values: auto, manual
Default: auto
TickLength
Length of tick marks normalized to
axis line length, specified as
two-element vector
Values: [2-D 3-D]
Default: [0.01 0.025}
Visible
Make axes visible or invisible
Values: on, off
Default: on
XGrid, YGrid, ZGrid
Toggle grid lines on and off in
respective axis
Values: on, off
Default: off
General Information About the Axes
Children
Handles of the Images, Lights, Lines,
Patches, Surfaces, and Text objects
displayed in the axes
Values: vector of handles
CurrentPoint
Location of last mouse button click
defined in the axes data units
Values: a 2-by-3 matrix
HitTest
Specify whether axes can become the
current object (see Figure
CurrentObject property)
Values: on, off
Default: on
Parent
Handle of the Figure window
containing the axes
Values: scalar Figure handle
2-10
axes
Property Name
Property Description
Property Value
Position
Location and size of axes within the
figure
Values: [left bottom width
height]
Default: [0.1300 0.1100
0.7750 0.8150] in
normalized Units
Selected
Indicate whether axes is in a
“selected” state
Values: on, off
Default: on
Tag
User-specified label
Values: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'axes'
Units
Units used to interpret the Position
property
Values: inches, centimeters,
characters, normalized,
points, pixels Default:
normalized
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
FontAngle
Select italic or normal font
Values: normal, italic,
oblique
Default: normal
FontName
Font family name (e.g., Helvetica,
Courier)
Values: a font supported by
your system
Default: Typically Helvetica
FontSize
Size of the font used for title and
labels
Selecting Fonts and Labels
FontUnits
Units used to interpret the FontSize
property
Values: an integer in
FontUnits Default: 10
Values: points, normalized,
inches, centimeters, pixels
Default: points
2-11
axes
Property Name
Property Description
FontWeight
Select bold or normal font
Property Value
Values: normal, bold, light,
demi
Default: normal
Title
Handle of the title text object
Values: any valid text object
handle
XLabel, YLabel, ZLabel
Handles of the respective axis label
text objects
Values: any valid text object
handle
XTickLabel, YTickLabel,
ZTickLabel
Specify tick mark labels for the
respective axis
Values: matrix of strings
Defaults: numeric values
selected automatically by
MATLAB
XTickLabelMode,
YTickLabelMode,
ZTickLabelMode
Use MATLAB or user-specified tick
mark labels
Values: auto, manual
Default: auto
Specify the location of the x-axis
Values: top, bottom
Default: bottom
Specify the location of the y-axis
Values: right left
Default: left
XDir, YDir, ZDir
Specify the direction of increasing
values for the respective axes
Values: normal, reverse
Default: normal
XLim, YLim, ZLim
Specify the limits to the respective
axes
Values: [min max]
Default: min and max
determined automatically by
MATLAB
XLimMode, YLimMode,
ZLimMode
Use MATLAB or user-specified
values for the respective axis limits
Values: auto, manual
Default: auto
Controlling Axis Scaling
XAxisLocation
YAxisLocation
2-12
axes
Property Name
Property Description
Property Value
XScale, YScale, ZScale
Select linear or logarithmic scaling of
the respective axis
Values: linear, log
Default: linear (changed by
plotting commands that
create nonlinear plots)
XTick, YTick, ZTick
Specify the location of the axis ticks
marks
Values: a vector of data
values locating tick marks
Default: MATLAB
automatically determines
tick mark placement
XTickMode, YTickMode,
ZTickMode
Use MATLAB or user-specified
values for the respective tick mark
locations
Values: auto, manual
Default: auto
CameraPosition
Specify the position of point from
which you view the scene
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
CameraPositionMode
Use MATLAB or user-specified
camera position
Values: auto, manual
Default: auto
CameraTarget
Center of view pointed to by camera
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
CameraTargetMode
Use MATLAB or user-specified
camera target
Values: auto, manual
Default: auto
CameraUpVector
Direction that is oriented up
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
Controlling the View
2-13
axes
Property Name
Property Description
Property Value
CameraUpVectorMode
Use MATLAB or user-specified
camera up vector
Values: auto, manual
Default: auto
CameraViewAngle
Camera field of view
Values: angle in degrees
between 0 and 180
Default: automatically
determined by MATLAB
CameraViewAngleMode
Use MATLAB or user-specified
camera view angle
Values: auto, manual
Default: auto
Projection
Select type of projection
Values: orthographic,
perspective
Default: orthographic
Controlling the Axes Aspect Ratio
DataAspectRatio
Relative scaling of data units
Values: three relative values
[dx dy dz]
Default: automatically
determined by MATLAB
DataAspectRatioMode
Use MATLAB or user-specified data
aspect ratio
PlotBoxAspectRatio
Relative scaling of axes plot box
Values: auto, manual
Default: auto
Values: three relative values
[dx dy dz]
Default: automatically
determined by MATLAB
PlotBoxAspectRatioMode
Use MATLAB or user-specified plot
box aspect ratio
Values: auto, manual Default:
auto
Controlling Callback Routine Execution
BusyAction
2-14
Specify how to handle events that
Values: cancel, queue
interrupt execution callback routines Default: queue
axes
Property Name
Property Description
Property Value
ButtonDownFcn
Define a callback routine that
executes when a button is pressed
over the axes
Values: string
Default: an empty strin
CreateFcn
Define a callback routine that
executes when an axes is created
Values: string
Default: an empty string
DeleteFcn
Define a callback routine that
executes when an axes is created
Values: string Default: an
empty string
Interruptible
Control whether an executing
callback routine can be interrupted
Values: on, off Default: on
UIContextMenu
Associate a context menu with the
axes
Values: handle of a
Uicontextmenu
Specifying the Rendering Mode
DrawMode
Specify the rendering method to use
with the Painters renderer
Values: normal, fast
Default: normal
Targeting Axes for Graphics Display
HandleVisibility
Control access to a specific axes’
handle
Values: on, callback, off
Default: on
NextPlot
Determine the eligibility of the axes
for displaying graphics
Values: add, replace,
replacechildren
Default: replace
Properties that Specify Color
AmbientLightColor
Color of the background light in a
scene
Values: ColorSpec
Default: [1 1 1]
CLim
Control how data is mapped to
colormap
Values: [cmin cmax]
Default: automatically
determined by MATLAB
CLimMode
Use MATLAB or user-specified
values for CLim
Values: auto, manual
Default: auto
2-15
axes
Property Name
Property Description
Property Value
Color
Color of the axes background
Values: none, ColorSpec
Default: none
ColorOrder
Line colors used for multiline plots
Values: m-by-3 matrix of
RGB values
Default: depends on color
scheme used
XColor, YColor, ZColor
Colors of the axis lines and tick
marks
Values: ColorSpec
Default: depends on current
color scheme
2-16
Axes Properties
Axes
Properties
2Axes Properties
This section lists property names along with the types of values each accepts.
Curly braces { } enclose default values.
AmbientLightColor ColorSpec
The background light in a scene. Ambient light is a directionless light that
shines uniformly on all objects in the Axes. However, if there are no visible
Light objects in the Axes, MATLAB does not use AmbientLightColor. If there
are Light objects in the Axes, the AmbientLightColor is added to the other light
sources.
AspectRatio
(Obsolete)
This property produces a warning message when queried or changed. It has
been superseded by the DataAspectRatio[Mode] and
PlotBoxAspectRatio[Mode] properties.
Box
on | {off}
Axes box mode. This property specifies whether to enclose the Axes extent in a
box for 2-D views or a cube for 3-D views. The default is to not display the box.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routines always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is within the Axes, but not over another
2-17
Axes Properties
graphics object displayed in the Axes. For 3-D views, the active area is defined
by a rectangle that encloses the Axes.
Define this routine as a string that is a valid MATLAB expression or the name
of an M-file. The expression executes in the MATLAB workspace.
CameraPosition
[x, y, z] Axes coordinates
The location of the camera. This property defines the position from which the
camera views the scene. Specify the point in Axes coordinates.
If you fix CameraViewAngle, you can zoom in and out on the scene by changing
the CameraPosition, moving the camera closer to the CameraTarget to zoom in
and farther away from the CameraTarget to zoom out. As you change the
CameraPosition, the amount of perspective also changes, if Projection is
perspective. You can also zoom by changing the CameraViewAngle; however,
this does not change the amount of perspective in the scene.
CameraPositionMode {auto} | manual
Auto or manual CameraPosition. When set to auto, MATLAB automatically
calculates the CameraPosition such that the camera lies a fixed distance from
the CameraTarget along the azimuth and elevation specified by view. Setting a
value for CameraPosition sets this property to manual.
CameraTarget
[x, y, z] Axes coordinates
Camera aiming point. This property specifies the location in the Axes that the
camera points to. The CameraTarget and the CameraPosition define the vector
(the view axis) along which the camera looks.
CameraTargetMode
{auto} | manual
Auto or manual CameraTarget placement. When this property is auto,
MATLAB automatically positions the CameraTarget at the centroid of the Axes
plotbox. Specifying a value for CameraTarget sets this property to manual.
CameraUpVector
[x, y, z] Axes coordinates
Camera rotation. This property specifies the rotation of the camera around the
viewing axis defined by the CameraTarget and the CameraPosition properties.
Specify CameraUpVector as a three-element array containing the x, y, and z
components of the vector. For example, [0 1 0] specifies the positive y-axis as
the up direction.
2-18
Axes Properties
The default CameraUpVector is [0 0 1], which defines the positive z-axis as the
up direction.
CameraUpVectorMode {auto} | manual
Default or user-specified up vector. When CameraUpVectorMode is auto,
MATLAB uses a value of [0 0 1] (positive z-direction is up) for 3-D views and
[0 1 0] (positive y-direction is up) for 2-D views. Setting a value for
CameraUpVector sets this property to manual.
CameraViewAngle
scalar greater than 0 and less than or equal to
180 (angle in degrees)
The field of view. This property determines the camera field of view. Changing
this value affects the size of graphics objects displayed in the Axes, but does not
affect the degree of perspective distortion. The greater the angle, the larger the
field of view, and the smaller objects appear in the scene.
CameraViewAngleMode{auto} | manual
Auto or manual CameraViewAngle. When in auto mode, MATLAB sets
CameraViewAngle to the minimum angle that captures the entire scene (up to
180˚).
The following table summarizes MATLAB’s automatic camera behavior.
CameraView
Angle
Camera
Target
Camera
Position
Behavior
auto
auto
auto
CameraTarget is set to plot box centroid,
CameraViewAngle is set to capture entire scene,
CameraPosition is set along the view axis.
auto
auto
manual
CameraTarget is set to plot box centroid,
CameraViewAngle is set to capture entire scene.
auto
manual
auto
CameraViewAngle is set to capture entire scene,
CameraPosition is set along the view axis.
auto
manual
manual
CameraViewAngle is set to capture entire scene.
manual
auto
auto
CameraTarget is set to plot box centroid,
CameraPosition is set along the view axis.
2-19
Axes Properties
CameraView
Angle
Camera
Target
Camera
Position
Behavior
manual
auto
manual
CameraTarget is set to plot box centroid
manual
manual
auto
CameraPosition is set along the view axis.
manual
manual
manual
All Camera properties are user-specified.
Children
vector of graphics object handles
Children of the Axes. A vector containing the handles of all graphics objects
rendered within the Axes (whether visible or not). The graphics objects that
can be children of Axes are Images, Lights, Lines, Patches, Surfaces, and Text.
The Text objects used to label the x-, y-, and z-axes are also children of Axes,
but their HandleVisibility properties are set to callback. This means their
handles do not show up in the Axes Children property unless you set the Root
ShowHiddenHandles property to on.
CLim
[cmin, cmax]
Color axis limits. A two-element vector that determines how MATLAB maps
the CData values of Surface and Patch objects to the Figure’s colormap. cmin is
the value of the data mapped to the first color in the colormap, and cmax is the
value of the data mapped to the last color in the colormap. Data values in
between are linearly interpolated across the colormap, while data values
outside are clamped to either the first or last colormap color, whichever is
closest.
When CLimMode is auto (the default), MATLAB assigns cmin the minimum
data value and cmax the maximum data value in the graphics object’s CData.
This maps CData elements with minimum data value to the first colormap
entry and with maximum data value to the last colormap entry.
If the Axes contains multiple graphics objects, MATLAB sets CLim to span the
range of all objects’ CData.
CLimMode
{auto} | manual
Color axis limits mode. In auto mode, MATLAB sets the CLim property to span
the CData limits of the graphics objects displayed in the Axes. If CLimMode is
manual, MATLAB does not change the value of CLim when the CData limits of
Axes children change. Setting the CLim property sets this property to manual.
2-20
Axes Properties
Clipping
{on} | off
This property has no effect on Axes.
Color
{none} | ColorSpec
Color of the Axes back planes. Setting this property to none means the Axes is
transparent and the Figure color shows through. A ColorSpec is a
three-element RGB vector or one of MATLAB’s predefined names. Note that
while the default value is none, the matlabrc.m file may set the Axes color to
a specific color.
ColorOrder
m-by-3 matrix of RGB values
Colors to use for multiline plots. ColorOrder is an m-by-3 matrix of RGB values
that define the colors used by the plot and plot3 functions to color each line
plotted. If you do not specify a line color with plot and plot3, these functions
cycle through the ColorOrder to obtain the color for each line plotted. To obtain
the current ColorOrder, which may be set during startup, get the property
value:
get(gca,'ColorOrder')
Note that if the Axes NextPlot property is set to replace (the default),
high-level functions like plot reset the ColorOrder property before
determining the colors to use. If you want MATLAB to use a ColorOrder that
is different from the default, set NextPlot to replacedata. You can also specify
your own default ColorOrder.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates an Axes object. You
must define this property as a default value for Axes. For example, the
statement,
set(0,'DefaultAxesCreateFcn','set(gca,''Color'',''b'')')
defines a default value on the Root level that sets the current Axes’ background
color to blue whenever you (or MATLAB) create an Axes. MATLAB executes
this routine after setting all properties for the Axes. Setting this property on an
existing Axes object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
2-21
Axes Properties
CurrentPoint
2-by-3 matrix
Location of last button click, in Axes data units. A 2-by-3 matrix containing the
coordinates of two points defined by the location of the pointer. These two
points lie on the line that is perpendicular to the plane of the screen and passes
through the pointer. The 3-D coordinates are the points, in the axes coordinate
system, where this line intersects the front and back surfaces of the Axes
volume (which is defined by the Axes x, y, and z limits).
The returned matrix is of the form:
x back y back z back
x front y front z front
MATLAB updates the CurrentPoint property whenever a button-click event
occurs. The pointer does not have to be within the Axes, or even the Figure
window; MATLAB returns the coordinates with respect to the requested Axes
regardless of the pointer location.
DataAspectRatio
[dx dy dz]
Relative scaling of data units. A three-element vector controlling the relative
scaling of data units in the x, y, and z directions. For example, setting this
property t o [1 2 1] causes the length of one unit of data in the x direction to
be the same length as two units of data in the y direction and one unit of data
in the z direction.
Note that the DataAspectRatio property interacts with the
PlotBoxAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control
how MATLAB scales the x-, y-, and z-axis. Setting the DataAspectRatio will
disable the Stretch-to-fill behavior, if DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto. The
following table describes the interaction between properties when
stretch-to-fill behavior is disabled.
2-22
Axes Properties
X-, Y-,
Z-Limits
DataAspectR
atio
PlotBox
AspectRatio
Behavior
auto
auto
auto
Limits chosen to span data range in all
dimensions.
auto
auto
manual
Limits chosen to span data range in all
dimensions. DataAspectRatio is modified to
achieve the requested PlotBoxAspectRatio
within the limits selected by MATLAB.
auto
manual
auto
Limits chosen to span data range in all
dimensions. PlotBoxAspectRatio is modified to
achieve the requested DataAspectRatio within
the limits selected by MATLAB.
auto
manual
manual
Limits chosen to completely fit and center the
plot within the requested PlotBoxAspectRatio
given the requested DataAspectRatio (this may
produce empty space around 2 of the 3
dimensions).
manual
auto
auto
Limits are honored. The DataAspectRatio and
PlotBoxAspectRatio are modified as necessary.
manual
auto
manual
Limits and PlotBoxAspectRatio are honored.
The DataAspectRatio is modified as necessary.
manual
manual
auto
Limits and DataAspectRatio are honored. The
PlotBoxAspectRatio is modified as necessary.
1 manual
2 auto
manual
manual
The 2 automatic limits are selected to honor the
specified aspect ratios and limit. See “Examples”
2 or 3
manual
manual
manual
Limits and DataAspectRatio are honored; the
PlotBoxAspectRatio is ignored.
DataAspectRatioMode{auto} | manual
User or MATLAB controlled data scaling. This property controls whether the
values of the DataAspectRatio property are user defined or selected
automatically by MATLAB. Setting values for the DataAspectRatio property
2-23
Axes Properties
automatically sets this property to manual. Changing DataAspectRatioMode to
manual disables the stretch-to-fill behavior, if DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.
DeleteFcn
string
Delete Axes callback routine. A callback routine that executes when the Axes
object is deleted (e.g., when you issue a delete or a close command). MATLAB
executes the routine before destroying the object’s properties so the callback
routine can query these values.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
DrawMode
{normal} | fast
Rendering method. This property controls the method MATLAB uses to render
graphics objects displayed in the Axes, when the Figure Renderer property is
painters.
• normal mode draws objects in back to front ordering based on the current
view in order to handle hidden surface elimination and object intersections.
• fast mode draws objects in the order in which you specify the drawing
commands, without considering the relationships of the objects in three
dimensions. This results in faster rendering because it requires no sorting of
objects according to location in the view, but may produce undesirable
results because it bypasses the hidden surface elimination and object
intersection handling provided by normal DrawMode.
When the Figure Renderer is zbuffer, DrawMode is ignored, and hidden surface
elimination and object intersection handling are always provided.
FontAngle
{normal} | italic | oblique
Select italic or normal font. This property selects the character slant for Axes
text. normal specifies a nonitalic font. italic and oblique specify italic font.
FontName
The default is Helvetica on many systems
Font family name. The font family name specifying the font to use for Axes
labels. To display and print properly, FontName must be a font that your system
supports. Note that the x-, y-, and z-axis labels do not display in a new font until
you manually reset them (by setting the XLabel, YLabel, and ZLabel properties
2-24
Axes Properties
or by using the xlabel, ylabel, or zlabel command). Tick mark labels change
immediately.
FontSize
Font size specified in FontUnits
Font size. An integer specifying the font size to use for Axes labels and titles, in
units determined by the FontUnits property. The default point size is 12. The
x-, y-, and z-axis text labels do not display in a new font size until you manually
reset them (by setting the XLabel, YLabel, or ZLabel properties or by using the
xlabel, ylabel, or zlabel command). Tick mark labels change immediately.
FontUnits
{points} | normalized | inches |
centimeters | pixels
Units used to interpret the FontSize property. When set to normalized,
MATLAB interprets the value of FontSize as a fraction of the height of the
Axes. For example, a normalized FontSize of 0.1 sets the text characters to a
font whose height is one tenth of the Axes’ height. The default units (points),
are equal to 1/72 of an inch.
FontWeight
{normal} | bold | light | demi
Select bold or normal font. The character weight for Axes text. The x-, y-, and
z-axis text labels do not display in bold until you manually reset them (by
setting the XLabel, YLabel, and ZLabel properties or by using the xlabel,
ylabel, or zlabel commands). Tick mark labels change immediately.
GridLineStyle
− | − −| {:} | −. | none
Line style used to draw grid lines. The line style is a string consisting of a
character, in quotes, specifying solid lines (−), dashed lines (−−), dotted lines(:),
or dash-dot lines (−.). The default grid line style is dotted. To turn on grid lines,
use the grid command.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
2-25
Axes Properties
within functions invoked from the command line. This provides a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string) and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Axes can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Axes. If HiTest is off, clicking on
the axes selects the object below it (which is usually the Figure containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether an Axes callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine. See the BusyAction property for
related information.
2-26
Axes Properties
Setting Interruptible to on allows any graphics object’s callback routine to
interrupt callback routines originating from an Axes property. Note that
MATLAB does not save the state of variables or the display (e.g., the handle
returned by the gca or gcf command) when an interruption occurs.
Layer
{bottom} | top
Draw axis lines below or above graphics objects. This property determines if
axis lines and tick marks draw on top or below Axes children objects for any 2-D
view (i.e., when you are looking along the x-, y-, or z-axis). This is useful for
placing grid lines and tick marks on top of images.
LineStyleOrder
LineSpec
Order of line styles and markers used in a plot. This property specifies which
line styles and markers to use and in what order when creating multiple-line
plots. For example,
set(gca,'LineStyleOrder', '−∗|:|o')
sets LineStyleOrder to solid line with asterisk marker, dotted line, and hollow
circle marker. The default is (−), which specifies a solid line for all data plotted.
Alternatively, you can create a cell array of character strings to define the line
styles:
set(gca,'LineStyleOrder',{'−*',':','o'})
MATLAB supports four line styles, which you can specify any number of times
in any order. MATLAB cycles through the line styles only after using all colors
defined by the ColorOrder property. For example, the first eight lines plotted
use the different colors defined by ColorOrder with the first line style.
MATLAB then cycles through the colors again, using the second line style
specified, and so on.
You can also specify line style and color directly with the plot and plot3
functions or by altering the properties of the Line objects.
Note that, if the Axes NextPlot property is set to replace (the default),
high-level functions like plot reset the LineStyleOrder property before
determining the line style to use. If you want MATLAB to use a
LineStyleOrder that is different from the default, set NextPlot to
replacedata. You can also specify your own default LineStyleOrder.
2-27
Axes Properties
LineWidth
linewidth in points
Width of axis lines. This property specifies the width, in points, of the x-, y-, and
z-axis lines. The default line width is 0.5 points (1 point = 1/72 inch).
NextPlot
add | {replace} | replacechildren
Where to draw the next plot. This property determines how high-level plotting
functions draw into an existing Axes.
• add — use the existing Axes to draw graphics objects.
• replace — reset all Axes properties, except Position, to their defaults and
delete all Axes children before displaying graphics (equivalent to cla reset).
• replacechildren — remove all child objects, but do not reset Axes
properties (equivalent to cla).
The newplot function simplifies the use of the NextPlot property and is used
by M-file functions that draw graphs using only low-level object creation
routines. See the M-file pcolor.m for an example. Note that Figure graphics
objects also have a NextPlot property.
Parent
Figure handle
Axes parent. The handle of the Axes’ parent object. The parent of an Axes object
is the Figure in which it is displayed. The utility function gcf returns the
handle of the current Axes’ Parent. You can reparent Axes to other Figure
objects.
PlotBoxAspectRatio [px py pz]
Relative scaling of Axes plotbox. A three-element vector controlling the relative
scaling of the plot box in the x-, y-, and z-directions. The plot box is a box
enclosing the Axes data region as defined by the x-, y-, and z-axis limits.
Note that the PlotBoxAspectRatio property interacts with the
DataAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control the
way graphics objects are displayed in the Axes. Setting the
PlotBoxAspectRatio disables stretch-to-fill behavior, if
DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode
are all auto.
PlotBoxAspectRatioMode{auto} | manual
User or MATLAB controlled axis scaling. This property controls whether the
values of the PlotBoxAspectRatio property are user defined or selected
2-28
Axes Properties
automatically by MATLAB. Setting values for the PlotBoxAspectRatio
property automatically sets this property to manual. Changing the
PlotBoxAspectRatioMode to manual disables stretch-to-fill behavior, if
DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode
are all auto.
Position
four-element vector
Position of Axes. A four-element vector specifying a rectangle that locates the
Axes within the Figure window. The vector is of the form:
[left bottom width height]
where left and bottom define the distance from the lower-left corner of the
Figure window to the lower-left corner of the rectangle. width and height are
the dimensions of the rectangle. All measurements are in units specified by the
Units property.
When Axes stretch-to-fill behavior is enabled (when DataAspectRatioMode,
PlotBoxAspectRatioMode, CameraViewAngleMode are all auto), the Axes are
stretched to fill the Position rectangle. When stretch-to-fill is disabled, the
Axes are made as large as possible, while obeying all other properties, without
extending outside the Position rectangle
Projection
{orthographic} | perspective
Type of projection. This property selects between two projection types:
• orthographic – This projection maintains the correct relative dimensions of
graphics objects with regard to the distance a given point is from the viewer.
Parallel lines in the data are drawn parallel on the screen.
• perspective – This projection incorporates foreshortening, which allows you
to perceive depth in 2-D representations of 3-D objects. Perspective
projection does not preserve the relative dimensions of objects; a distant line
segment displays smaller than a nearer line segment of the same length.
Parallel lines in the data may not appear parallel on screen.
Selected
on | off
Is object selected. When you set this property to on, MATLAB displays selection
“handles” at the corners and midpoints if the SelectionHighlight property is
also on (the default). You can, for example, define the ButtonDownFcn callback
2-29
Axes Properties
routine to set this property to on, thereby indicating that the axes has been
selected.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing four edge handles and four corner
handles. When SelectionHighlight is off, MATLAB does not draw the
handles.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines.
For example, suppose you want to direct all graphics output from an M-file to
a particular Axes, regardless of user actions that may have changed the
current Axes. To do this, identify the Axes with a Tag:
axes('Tag','Special Axes')
Then make that Axes the current Axes before drawing by searching for the Tag
with findobj:
axes(findobj('Tag','Special Axes'))
TickDir
in | out
Direction of tick marks. For 2-D views, the default is to direct tick marks
inward from the axis lines; 3-D views direct tick marks outward from the axis
line.
TickDirMode
{auto} | manual
Automatic tick direction control. In auto mode, MATLAB directs tick marks
inward for 2-D views and outward for 3-D views. When you specify a setting for
TickDir, MATLAB sets TickDirMode to manual. In manual mode, MATLAB
does not change the specified tick direction.
TickLength
[2DLength 3DLength]
Length of tick marks. A two-element vector specifying the length of Axes tick
marks. The first element is the length of tick marks used for 2-D views and the
2-30
Axes Properties
second element is the length of tick marks used for 3-D views. Specify tick mark
lengths in units normalized relative to the longest of the visible X-, Y-, or Z-axis
annotation lines.
Title
handle of text object
Axes title. The handle of the Text object that is used for the Axes title. You can
use this handle to change the properties of the title Text or you can set Title
to the handle of an existing Text object. For example, the following statement
changes the color of the current title to red:
set(get(gca,'Title'),'Color','r')
To create a new title, set this property to the handle of the Text object you want
to use:
set(gca,'Title',text('String','New Title','Color','r'))
However, it is generally simpler to use the title command to create or replace
an Axes title:
title('New Title','Color','r')
Type
string (read only)
Type of graphics object. This property contains a string that identifies the class
of graphics object. For Axes objects, Type is always set to 'axes'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the axes. Assign this property the handle of a
Uicontextmenu object created in the Axes’ parent Figure. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Axes (Control-click on
Macintosh systems).
Units
inches | centimeters | {normalized} |
points | pixels | characters
Position units. The units used to interpret the Position property. All units are
measured from the lower-left corner of the Figure window.
2-31
Axes Properties
• normalized units map the lower-left corner of the Figure window to (0,0) and
the upper-right corner to (1.0, 1.0).
• inches, centimeters, and points are absolute units (one point equals 1/72 of
an inch).
• Character units are defined by characters from the default system font; the
width of one character is the width of the letter x, the height of one character
is the distance between the baselines of two lines of text.
UserData
matrix
User specified data. This property can be any data you want to associate with
the Axes object. The Axes does not use this property, but you can access it using
the set and get functions.
View
Obsolete
The functionality provided by the View property is now controlled by the Axes
camera properties – CameraPosition, CameraTarget, CameraUpVector, and
CameraViewAngle. See the view command.
Visible
{on} | off
Visibility of Axes. By default, Axes are visible. Setting this property to off
prevents axis lines, tick marks, and labels from being displayed. The visible
property does not affect children of Axes.
XAxisLocation
top | {bottom}
Location of x-axis tick marks and labels. This property controls where
MATLAB displays the x-axis tick marks and labels. Setting this property to top
moves the x-axis to the top of the plot from its default position at the bottom.
YAxisLocation
right | {left}
Location of y-axis tick marks and labels. This property controls where
MATLAB displays the y-axis tick marks and labels. Setting this property to
right moves the y-axis to the right side of the plot from its default position on
the left side. See the plotyy function for a simple way to use two y-axes.
Properties That Control the X-, Y-, or Z-Axis
XColor, YColor, ZColorColorSpec
Color of axis lines. A three-element vector specifying an RGB triple, or a
predefined MATLAB color string. This property determines the color of the
2-32
Axes Properties
axis lines, tick marks, tick mark labels, and the axis grid lines of the respective
x-, y-, and z-axis. The default axis color is white. See ColorSpec for details on
specifying colors.
XDir, YDir, ZDir
{normal} | reverse
Direction of increasing values. A mode controlling the direction of increasing
axis values. Axes form a right-hand coordinate system. By default,
• x-axis values increase from left to right. To reverse the direction of increasing
x values, set this property to reverse.
• y-axis values increase from bottom to top (2-D view) or front to back (3-D
view). To reverse the direction of increasing y values, set this property to
reverse.
• z-axis values increase pointing out of the screen (2-D view) or from bottom to
top (3-D view). To reverse the direction of increasing z values, set this
property to reverse.
XGrid, YGrid, ZGrid on | {off}
Axis gridline mode. When you set any of these properties to on, MATLAB draws
grid lines perpendicular to the respective axis (i.e., along lines of constant x, y,
or z values). Use the grid command to set all three properties on or off at once.
XLabel, YLabel, ZLabelhandle of text object
Axis labels. The handle of the Text object used to label the x, y, or z-axis,
respectively. To assign values to any of these properties, you must obtain the
handle to the text string you want to use as a label. This statement defines a
Text object and assigns its handle to the XLabel property:
set(gca,'Xlabel',text('String','axis label'))
MATLAB places the string 'axis label' appropriately for an x-axis label. Any
Text object whose handle you specify as an XLabel, YLabel, or ZLabel property
is moved to the appropriate location for the respective label.
Alternatively, you can use the xlabel, ylabel, and zlabel functions, which
generally provide a simpler means to label axis lines.
XLim, YLim, ZLim
[minimum maximum]
Axis limits. A two-element vector specifying the minimum and maximum
values of the respective axis.
2-33
Axes Properties
Changing these properties affects the scale of the x-, y-, or z-dimension as well
as the placement of labels and tick marks on the axis. The default values for
these properties are [0 1].
XLimMode, YLimMode, ZLimMode{auto} | manual
MATLAB or user-controlled limits. The axis limits mode determines whether
MATLAB calculates axis limits based on the data plotted (i.e., the XData,
YData, or ZData of the Axes children) or uses the values explicitly set with the
XLim, YLim, or ZLim property, in which case, the respective limits mode is set to
manual.
XScale, YScale, ZScale{linear} | log
Axis scaling. Linear or logarithmic scaling for the respective axis. See also
loglog, semilogx, and semilogy.
XTick, YTick, ZTickvector of data values locating tick marks
Tick spacing. A vector of x-, y-, or z-data values that determine the location of
tick marks along the respective axis. If you do not want tick marks displayed,
set the respective property to the empty vector, [ ]. These vectors must contain
monotonically increasing values.
XTickLabel, YTickLabel, ZTickLabelstring
Tick labels. A matrix of strings to use as labels for tick marks along the
respective axis. These labels replace the numeric labels generated by
MATLAB. If you do not specify enough text labels for all the tick marks,
MATLAB uses all of the labels specified, then reuses the specified labels.
For example, the statement,
set(gca,'XTickLabel',{'One';'Two';'Three';'Four'})
labels the first four tick marks on the x-axis and then reuses the labels until all
ticks are labeled.
Labels can be specified as cell arrays of strings, padded string matrices, string
vectors separated by vertical slash characters, or as numeric vectors (where
2-34
Axes Properties
each number is implicitly converted to the equivalent string using num2str). All
of the following are equivalent:
set(gca,'XTickLabel',{'1';'10';'100'})
set(gca,'XTickLabel','1|10|100')
set(gca,'XTickLabel',[1;10;100])
set(gca,'XTickLabel',['1 ';'10 ';'100'])
Note that tick labels do not interpret TeX character sequences (however, the
Title, XLabel, YLabel, and ZLabel properties do).
XTickMode, YTickMode, ZTickMode{auto} | manual
MATLAB or user controlled tick spacing. The axis tick modes determine
whether MATLAB calculates the tick mark spacing based on the range of data
for the respective axis (auto mode) or uses the values explicitly set for any of
the XTick, YTick, and ZTick properties (manual mode). Setting values for the
XTick, YTick, or ZTick properties sets the respective axis tick mode to manual.
XTickLabelMode, YTickLabelMode, ZTickLabelMode{auto} | manual
MATLAB or user determined tick labels. The axis tick mark labeling mode
determines whether MATLAB uses numeric tick mark labels that span the
range of the plotted data (auto mode) or uses the tick mark labels specified with
the XTickLabel, YTickLabel, or ZTickLabel property (manual mode). Setting
values for the XTickLabel, YTickLabel, or ZTickLabel property sets the
respective axis tick label mode to manual.
2-35
axis
Purpose
Syntax
2axis
Axis scaling and appearance
axis([xmin xmax ymin ymax])
axis([xmin xmax ymin ymax zmin zmax])
v = axis
axis
axis
axis
axis
auto
manual
tight
fill
axis ij
axis xy
axis
axis
axis
axis
axis
equal
image
square
vis3d
normal
axis off
axis on
[mode,visibility,direction] = axis('state')
Description
axis manipulates commonly used Axes properties. (See Algorithm section.)
axis([xmin xmax ymin ymax]) sets the limits for the x- and y-axis of the
current Axes.
axis([xmin xmax ymin ymax zmin zmax]) sets the limits for the x-, y-, and
z-axis of the current Axes.
v = axis returns a row vector containing scaling factors for the x-, y-, and
z-axis. v has four or six components depending on whether the current Axes is
2-D or 3-D, respectively. The returned values are the current Axes’ XLim, Ylim,
and ZLim properties.
2-36
axis
axis auto sets MATLAB to its default behavior of computing the current
Axes’ limits automatically, based on the minimum and maximum values of x,
y, and z data. You can restrict this automatic behavior to a specific axis. For
example, axis 'auto x' computes only the x-axis limits automatically; axis
'auto yz' computes the y- and z-axis limits automatically.
axis manual and axis(axis) freezes the scaling at the current limits, so that
if hold is on, subsequent plots use the same limits. This sets the XLimMode,
YLimMode, and ZLimMode properties to manual.
axis tight sets the aspect ratio so that the data units are the same in every
direction. This differs from axis equal because the plot box aspect ratio
automatically adjusts.
axis fill sets the axis limits to the range of the data.
axis ij places the coordinate system origin in the upper-left corner. The
i-axis is vertical, with values increasing from top to bottom. The j-axis is
horizontal with values increasing from left to right.
axis xy draws the graph in the default Cartesian axes format with the
coordinate system origin in the lower-left corner. The x-axis is horizontal with
values increasing from left to right. The y-axis is vertical with values increasing
from bottom to top.
axis equal sets the aspect ratio so that the data units are the same in every
direction. The aspect ratio of the x-, y-, and z-axis is adjusted automatically
according to the range of data units in the x, y, and z directions.
axis image is the same as axis equal except that the plot box fits tightly
around the data.
axis square makes the current Axes region square (or cubed when
three-dimensional). MATLAB adjusts the x-axis, y-axis, and z-axis so that they
have equal lengths and adjusts the increments between data units accordingly.
axis vis3d freezes aspect ratio properties to enable rotation of 3-D objects
and overrides stretch-to-fill.
2-37
axis
axis normal automatically adjusts the aspect ratio of the Axes and the aspect
ratio of the data units represented on the Axes to fill the plot box.
axis off turns off all axis lines, tick marks, and labels.
axis on turns on all axis lines, tick marks, and labels.
[mode,visibility,direction] = axis('state') returns three strings
indicating the current setting of Axes properties:
Output Argument
Strings Returned
mode
'auto' | 'manual'
visibility
'on' | 'off'
direction
'xy' | 'ij'
mode is auto if XLimMode, YLimMode, and ZLimMode are all set to auto. If
XLimMode, YLimMode, or ZLimMode is manual, mode is manual.
Examples
The statements
x = 0:.025:pi/2;
plot(x,tan(x),'-ro')
2-38
axis
use the automatic scaling of the y-axis based on ymax = tan(1.57), which is
well over 1000:
1400
1200
1000
800
600
400
200
0
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
2-39
axis
The right figure shows a more satisfactory plot after typing
axis([0
pi/2
0
5])
5
4.5
4
3.5
3
2.5
2
1.5
1
0.5
0
Algorithm
0
0.5
1
1.5
When you specify minimum and maximum values for the x-, y-, and z-axes,
axis sets the XLim, Ylim, and ZLim properties for the current Axes to the
respective minimum and maximum values in the argument list. Additionally,
the XLimMode, YLimMode, and ZLimMode properties for the current Axes are set
to manual.
axis auto sets the current Axes’ XLimMode, YLimMode, and ZLimMode properties
to 'auto'.
axis manual sets the current Axes’ XLimMode, YLimMode, and ZLimMode
properties to 'manual'.
The following table shows the values of the Axes properties set by axis equal,
axis normal, axis square, and axis image.
2-40
axis
Axes Property
axis equal
axis normal
axis square
axis tightequal
DataAspectRatio
[1 1 1]
not set
not set
[1 1 1]
DataAspectRatioMode
manual
auto
auto
manual
PlotBoxAspectRatio
[3 4 4]
not set
[1 1 1]
auto
PlotBoxAspectRatioMode
manual
auto
manual
auto
Stretch-to-fill
disabled
active
disabled
disabled
See Also
axes, get, grid, set, subplot
Properties of Axes graphics objects.
2-41
bar, barh
Purpose
Syntax
2bar, barh
Bar chart
bar(Y)
bar(x,Y)
bar(...,width)
bar(...,'style')
bar(...,LineSpec)
[xb,yb] = bar(...)
h = bar(...)
barh(...)
[xb,yb] = barh(...)
h = barh(...)
Description
A bar chart displays the values in a vector or matrix as horizontal or vertical
bars.
bar(Y) draws one bar for each element in Y. If Y is a matrix, bar groups
together the bars produced by the elements in each row. The x-axis scale ranges
from 1 to length(Y) when Y is a vector, and 1 to size(Y,1), which is the
number of rows, when Y is a matrix.
bar(x,Y) draws a bar for each element in Y at locations specified in x, where x
is a monotonically increasing vector defining the x-axis intervals for the
vertical bars. If Y is a matrix, bar clusters the elements in the same row in Y at
locations corresponding to an element in x.
bar(...,width) sets the relative bar width and controls the separation of bars
within a group. The default width is 0.8, so if you do not specify x, the bars
within a group have a slight separation. If width is 1, the bars within a group
touch one another.
bar(...,'style') specifies the style of the bars. 'style' is 'group' or
'stack'. 'group' is the default mode of display.
2-42
bar, barh
• 'group' displays n groups of m vertical bars, where n is the number of rows
and m is the number of columns in Y. The group contains one bar per column
in Y.
• 'stack' displays one bar for each row in Y. The bar height is the sum of the
elements in the row. Each bar is multi-colored, with colors corresponding to
distinct elements and showing the relative contribution each row element
makes to the total sum.
bar(...,LineSpec) displays all bars using the color specified by LineSpec.
[xb,yb] = bar(...) returns vectors that you plot using plot(xb,yb) or
patch(xb,yb,C). This gives you greater control over the appearance of a graph,
for example, to incorporate a bar chart into a more elaborate plot statement.
h = bar(...) returns a vector of handles to Patch graphics objects. bar
creates one Patch graphics object per column in Y.
barh(...), [xb,yb] = barh(...), and h = barh(...) create horizontal
bars. Y determines the bar length. The vector x is a monotonic vector defining
the y-axis intervals for horizontal bars.
2-43
bar, barh
Examples
Plot a bell shaped curve:
x = –2.9:0.2:2.9;
bar(x,exp(–x.∗x))
colormap hsv
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
−3
−2
−1
0
1
2
3
Create four subplots showing the effects of some bar arguments:
Y = round(rand(5,3)∗10);
subplot(2,2,1)
bar(Y,'group')
title 'Group'
subplot(2,2,2)
bar(Y,'stack')
title 'Stack'
subplot(2,2,3)
barh(Y,'stack')
title 'Stack'
subplot(2,2,4)
bar(Y,1.5)
title 'Width = 1.5'
2-44
bar, barh
Group
Stack
10
25
8
20
6
15
4
10
2
5
0
0
1
2
3
4
5
1
Stack
2
3
4
5
Width = 1.5
10
5
8
4
6
3
4
2
2
1
0
0
See Also
5
10
15
20
25
1
2
3
4
5
bar3, ColorSpec, patch, stairs, hist
2-45
bar3, bar3h
Purpose
Syntax
2bar3, bar3h
Three-dimensional bar chart
bar3(Y)
bar3(x,Y)
bar3(...,width)
bar3(...,'style')
bar3(...,LineSpec)
h = bar3(...)
bar3h(...)
h = bar3h(...)
Description
bar3 and bar3h draw three-dimensional vertical and horizontal bar charts.
bar3(Y) draws a three-dimensional bar chart, where each element in Y
corresponds to one bar. When Y is a vector, the x-axis scale ranges from 1 to
length(Y). When Y is a matrix, the x-axis scale ranges from 1 to size(Y,2),
which is the number of columns, and the elements in each row are grouped
together.
bar3(x,Y) draws a bar chart of the elements in Y at the locations specified in
x, where x is a monotonic vector defining the y-axis intervals for vertical bars.
If Y is a matrix, bar3 clusters elements from the same row in Y at locations
corresponding to an element in x. Values of elements in each row are grouped
together.
bar3(...,width) sets the width of the bars and controls the separation of bars
within a group. The default width is 0.8, so if you do not specify x, bars within
a group have a slight separation. If width is 1, the bars within a group touch
one another.
bar3(...,'style') specifies the style of the bars. 'style' is 'detached',
'grouped', or 'stacked'. 'detached' is the default mode of display.
• 'detached' displays the elements of each row in Y as separate blocks behind
one another in the x direction.
2-46
bar3, bar3h
• 'grouped' displays n groups of m vertical bars, where n is the number of
rows and m is the number of columns in Y. The group contains one bar per
column in Y.
• 'stacked' displays one bar for each row in Y. The bar height is the sum of
the elements in the row. Each bar is multi-colored, with colors corresponding
to distinct elements and showing the relative contribution each row element
makes to the total sum.
bar3(...,LineSpec) displays all bars using the color specified by LineSpec.
h = bar3(...) returns a vector of handles to Patch graphics objects. bar3
creates one Patch object per column in Y.
bar3h(...) and h = bar3h(...) create horizontal bars. Y determines the bar
length. The vector x is a monotonic vector defining the y-axis intervals for
horizontal bars.
2-47
bar3, bar3h
Examples
This example creates six subplots showing the effects of different arguments
for bar3. The data Y is a seven-by-three matrix generated using the cool
colormap:
Y = cool(7);
subplot(3,2,1)
bar3(Y,’detached’)
title(‘Detached’)
subplot(3,2,2)
bar3(Y,0.25,’detached’)
title(‘Width = 0.25’)
subplot(3,2,3)
bar3(Y,’grouped’)
title(‘Grouped’)
subplot(3,2,4)
bar3(Y,0.5,’grouped’)
title(‘Width = 0.5’)
subplot(3,2,5)
bar3(Y,’stacked’)
title(‘Stacked’)
subplot(3,2,6)
bar3(Y,0.3,’stacked’)
title(‘Width = 0.3’)
colormap([1 0 0;0 1 0;0 0 1])
2-48
bar3, bar3h
Detached
Width = 0.25
1
1
0.5
0.5
0
0
1
2
1
3
4
5
6
Grouped
1
0.5
0.5
0
0
2
4
4
5
6
2
3
Stacked
1.5
1.5
1
1
0.5
0.5
0
0
See Also
1
3
4
5
6
7
4
5
7
6
7
Width = 0.3
2
2
6
7
2
1
5
Width = 0.5
1
3
3
7
1
1
2
2
3
4
5
6
7
bar, LineSpec, patch
2-49
box
Purpose
2box
Control Axes border
Syntax
box on
box off
box
Description
box on displays the boundary of the current Axes.
box off does not display the boundary of the current Axes.
box toggles the visible state of the current Axes’ boundary.
Algorithm
The box function sets the Axes Box property to on or off.
See Also
axes
2-50
brighten
Purpose
Syntax
Description
2brighten
Brighten or darken colormap
brighten(beta)
brighten(h,beta)
newmap = brighten(beta)
newmap = brighten(cmap,beta)
brighten increases or decreases the color intensities in a colormap. The
modified colormap is brighter if 0 < beta < 1 and darker if –1 < beta < 0.
brighten(beta) replaces the current colormap with a brighter or darker
colormap of essentially the same colors. brighten(beta), followed by
brighten(–beta), where beta < 1, restores the original map.
brighten(h,beta) brightens all objects that are children of the Figure having
the handle h.
newmap = brighten(beta) returns a brighter or darker version of the current
colormap without changing the display.
newmap = brighten(cmap,beta) returns a brighter or darker version of the
colormap cmap without changing the display.
Examples
Brighten then darken the current colormap:
beta = .5; brighten(beta);
beta = —.5; brighten(beta);
Algorithm
The values in the colormap are raised to the power of gamma, where gamma is
 1 – β,
γ=  1
------------1 + β,
β>0
β≤0
brighten has no effect on graphics objects defined with true color.
See Also
colormap, rgbplot
2-51
brighten
2-52
camdolly
Purpose
2camdolly
Move the camera position and target
Syntax
camdolly(dx,dy,dz)
camdolly(dx,dy,dz,'targetmode')
camdolly(dx,dy,dz,'targetmode','coordsys')
camdolly(axes_handle,...)
Description
camdolly moves the camera position and the camera target by the specified
amounts.
camdolly(dx,dy,dz) moves the camera position and the camera target by the
specified amounts (see Coordinate Systems).
camdolly(dx,dy,dz,'targetmode') The targetmode argument can take on
two values that determine how MATLAB moves the camera:
• movetarget (default) – move both the camera and the target
• fixtarget – move only the camera
camdolly(dx,dy,dz,'targetmode','coordsys') The coordsys argument
can take on three values that determine how MATLAB interprets dx, dy, and
dz:
Coordinate
Systems
• camera (default) – move in the camera’s coordinate system. dx moves left/
right, dy moves down/up, dz moves along the viewing axis. The units are
normalized to the scene.
For example, setting dx to 1 moves the camera to the right, which pushes the
scene to the left edge of the box formed by the axes position rectangle. A
negative value moves the scene in the other direction. Setting dz to .5 moves
the camera to a position half way in between the camera position and the
camera target
• pixels – interpret dx and dy as pixel offsets. dz is ignored.
• data – interpret dx, dy, and dz in axes data coordinates.
camdolly(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camdolly
operates on the current axes.
2-53
camdolly
Remarks
camdolly sets the Axes CameraPosition and CameraTarget properties, which
in turn causes the CameraPositionMode and CameraTargetMode properties to
be set to manual.
Examples
This example moves the camera along the x- and y-axes in a series of steps:
surf(peaks)
axis vis3d
t = 0:pi/20:2*pi;
dx = sin(t)./40;
dy = cos(t)./40;
for i = 1:length(t);
camdolly(dx(i),dy(i),0)
drawnow
end
See Also
axes, campos, camproj, camtarget, camup, camva
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
The “Camera Properties” section in the Using MATLAB Graphics manual
2-54
camlight
Purpose
2camlight
Create or move a Light object in camera coordinates
Syntax
camlight headlight
camlight right
camlight left
camlight
camlight(az,el)
camlight(...‘style’)
camlight(light_handle,...)
light_handle = camlight(...)
Description
camlight('headlight') creates a Light at the camera position.
camlight('right') creates a Light right and up from camera.
camlight('left') creates a Light left and up from camera.
camlight with no argments is the same as camlight('right').
camlight(az,el) creates a Light at the specified azimuth (az) and elevation
(el) with respect to the camera position. The camera target is the center of
rotation and az and el are in degrees.
camlight(...,'style') The style argument can take on the two values:
• local (default) – the Light is a point source that radiates from the location
in all directions.
• infinite – the Light shines in parallel rays
camlight(light_handle,...) uses the Light specified in light_handle.
light_handle = camlight(...) returns the Light’s handle.
Remarks
camlight sets the Light object Position and Style properties. A Light created
with camlight will not track the camera. In order for the Light to stay in a
constant position relative to the camera, you must call camlight whenever you
move the camera.
2-55
camlight
Examples
This example creates a Light positioned to the left of the camera and then
repositions the Light each time the camera is moved:
surf(peaks)
axis vis3d
h = camlight(‘left’);
for i = 1:20;
camorbit(10,0)
camlight(h, ‘left’)
drawnow;
end
2-56
camlookat
Purpose
2camlookat
Position the camera to view an object or group of objects
Syntax
camlookat(h)
camlookat(axes_handle)
camlookat
Description
camlookat(handles) views the objects identified in the vector handles. The
vector can contain the handles of Axes children.
camlookat(axes_handle) views the objects that are children of the Axes
identified by axes_handle.
camlookat views the objects that are in the current Axes.
Remarks
camlookat moves the camera position and camera target while preserving the
relative view direction and camera view angle. The object (or objects) being
viewed roughly fill the axes position rectangle.
camlookat sets the Axes CameraPosition and CameraTarget properties.
Examples
This example creates three spheres at different locations and then
progressively positions the camera so that each sphere is the object around
which the scene is composed:
[x y z] = sphere;
s1 = surf(x,y,z);
hold on
s2 = surf(x+3,y,z+3);
s3 = surf(x,y,z+6);
daspect([1 1 1])
view(30,10)
camproj perspective
camlookat(gca) % Compose
pause(2)
camlookat(s1) % Compose
pause(2)
camlookat(s2) % Compose
pause(2)
camlookat(s3) % Compose
pause(2)
camlookat(gca)
the scene around the current axes
the scene around sphere s1
the scene around sphere s2
the scene around sphere s3
2-57
camlookat
See Also
2-58
campos, camtarget
camorbit
Purpose
2camorbit
Rotate the camera position around the camera target
Syntax
camorbit(dtheta,dphi)
camorbit(dtheta,dphi,'coordsys')
camorbit(dtheta,dphi,'coordsys','direction')
camorbit(axes_handle,...)
Description
camorbit(dtheta,dphi) rotates the camera position around the camera
target by the amounts specified in dtheta and dphi (both in degrees). dtheta
is the horizontal rotation and dphi is the vertical rotation.
camorbit(dtheta,dphi,'coordsys') The coordsys argument determines
the center of rotation. It can take on two values:
• data (default) – rotate the camera around an axis defined by the camera
target and the direction (default is the positive z direction).
• camera – rotate the camera about the point defined by the camera target.
camorbit(dtheta,dphi,'coordsys','direction') The direction
argument, in conjunction with the camera target, defines the axis of rotation
for the data coordinate system. Specify direction as a three-element vector
containing the x, y, and z-components of the direction or one of the characters:
x, y, or z, to indicate [1 0 0], [0 1 0], or [0 0 1] respectively.
camorbit(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camorbit
operates on the current axes.
Examples
Compare rotation in the two coordinate systems with these for loops. The first
rotates the camera horizontally about a line defined by the camera target point
and a direction that is parallel to the y-axis. Visualize this rotation as a cone
2-59
camorbit
formed with the camera target at the apex and the camera position forming the
base:
surf(peaks)
axis vis3d
for i=1:36
camorbit(10,0,'data',[0 1 0])
drawnow
end
Rotation in the camera coordinate system orbits the camera around the axes
along a circle while keeping the center of a circle at the camera target.
surf(peaks)
axis vis3d
for i=1:36
camorbit(10,0,'camera')
drawnow
end
See Also
2-60
axes, axis('vis3d'), camdolly, campan, camzoom, camroll
campan
Purpose
2campan
Rotate the camera target around the camera position
Syntax
campan(dtheta,dphi)
campan(dtheta,dphi,'coordsys')
campan(dtheta,dphi,'coordsys','direction')
campan(axes_handle,...)
Description
campan(dtheta,dphi) rotates the camera target around the camera position
by the amounts specified in dtheta and dphi (both in degrees). dtheta is the
horizontal rotation and dphi is the vertical rotation.
campan(dtheta,dphi,'coordsys') The coordsys argument determines the
center of rotation. It can take on two values:
• data (default) – rotate the camera target around an axis defined by the
camera position and the direction (default is the positive z direction)
• camera – rotate the camera about the point defined by the camera target.
campan(dtheta,dphi,'coordsys','direction') The direction argument,
in conjunction with the camera position, defines the axis of rotation for the data
coordinate system. Specify direction as a three-element vector containing the
x, y, and z-components of the direction or one of the characters: x, y, or z, to
indicate [1 0 0], [0 1 0], or [0 0 1] respectively.
campan(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, campan
operates on the current axes.
See Also
axes, camdolly, camorbit, camtarget, camzoom, camroll
2-61
campos
Purpose
2campos
Set or query the camera position
Syntax
campos
campos([camera_position])
campos('mode')
campos('auto'
campos('manual')
campos(axes_handle,...)
Description
campos with no arguments returns the camera position in the current axes.
campos([camera_position]) sets the position of the camera in the current
axes to the specified value. Specify the position as a three-element vector
containing the x-, y-, and z-coordinates of the desired location in the data units
of the axes.
campos('mode') returns the value of the camera position mode, which can be
either auto (the default) or manual.
campos('auto') sets the camera position mode to auto.
campos('manual') sets the camera position mode to manual.
campos(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
campos operates on the current axes.
Remarks
campos sets or queries values of the Axes CameraPosition and
CameraPositionMode properties. The camera position is the point in the
Cartesian coordinate system of the axes from which you view the scene.
Examples
This example moves the camera along the x-axis in a series of steps:
surf(peaks)
axis vis3d off
for x = −200:5:200
campos([x,5,10])
drawnow
end
2-62
campos
See Also
axis, camproj, camtarget, camup, camva
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
2-63
camproj
Purpose
2camproj
Set or query the projection type
Syntax
camproj
camproj(projection_type)
camproj(axes_handle,...)
Description
The projection type determines whether MATLAB uses a perspective or
orthographic projection for 3-D views. (See the “View Projection Types” section
in the Using MATLAB Graphics manual for illustrations.)
camproj with no arguments returns the projection type setting in the current
axes.
camproj('projection_type') sets the projection type in the current axes to
the specified value. Possible values for projection_type are: orthographic
and perspective.
camproj(axes_handle,...) performs the set or query on the axes identified
by the first argument, axes_handle. When you do not specify an axes handle,
camproj operates on the current axes.
Remarks
camproj sets or queries values of the Axes object Projection property.
See Also
campos, camtarget, camup, camva
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
2-64
camroll
Purpose
2camroll
Rotate the camera about the view axis
Syntax
camroll(dtheta)
camroll(axes_handle,dtheta)
Description
camroll(dtheta) rotates the camera around the camera viewing axis by the
amounts specified in dtheta (in degrees). The viewing axis is defined by the
line passing through the camera position and the camera target.
camroll(axes_handle,dtheta) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camroll
operates on the current axes.
Remarks
camroll set the Axes CameraUpVector property and thereby also sets the
CameraUpVectorMode property to manual.
See Also
axes, axis('vis3d'), camdolly, camorbit, camzoom, campan
2-65
camtarget
Purpose
2camtarget
Set or query the location of the camera target
Syntax
camtarget
camtarget([camera_target])
camtarget('mode')
camtarget('auto')
camtarget('manual')
camtarget(axes_handle,...)
Description
The camera target is the location in the axes that the camera points to. The
camera remains oriented towards this point regardless of its position.
camtarget with no arguments returns the location of the camera target in the
current axes.
camtarget([camera_target]) sets the camera target in the current axes to
the specified value. Specify the target as a three-element vector containing the
x-, y-, and z-coordinates of the desired location in the data units of the axes.
camtarget('mode') returns the value of the camera target mode, which can be
either auto (the default) or manual.
camtarget('auto') sets the camera target mode to auto.
camtarget('manual') sets the camera target mode to manual.
camtarget(axes_handle,...) performs the set or query on the axes identified
by the first argument, axes_handle. When you do not specify an axes handle,
camtarget operates on the current axes.
Remarks
camtarget sets or queries values of the Axes object Cameratarget and
CameraTargetMode properties.
When the camera target mode is auto, MATLAB positions the camera target at
the center of the axes plot box.
2-66
camtarget
Examples
This example moves the camera position and the camera target along the
x-axis in a series of steps:
surf(peaks);
axis vis3d
xp = linspace(−150,40,50);
xt = linspace(25,50,50);
for i=1:50
campos([xp(i),25,5]);
camtarget([xt(i),30,0])
drawnow
end
See Also
axis, camproj, campos, camup, camva
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
2-67
camup
Purpose
2camup
Set or query the camera up vector
Syntax
camup
camup([up_vector])
camup('mode')
camup('auto')
camup('manual')
camup(axes_handle,...)
Description
The camera up vector specifies the direction that is oriented up in the scene.
camup with no arguments returns the camera up vector setting in the current
axes.
camup([up_vector]) sets the up vector in the current axes to the specified
value. Specify the up vector as x-, y-, and z-components. See Remarks.
camup('mode') returns the current value of the camera up vector mode, which
can be either auto (the default) or manual.
camup('auto') sets the camera up vector mode to auto. In auto mode,
MATLAB uses a value for the up vector of [0 1 0] for 2-D views. This means
the z-axis points up.
camup('manual') sets the camera up vector mode to manual. In manual mode,
MATLAB does not change the value of the camera up vector.
camup(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
camup operates on the current axes.
Remarks
camup sets or queries values of the Axes object CameraUpVector and
CameraUpVectorMode properties.
Specify the camera up vector as the x-, y-, and z-coordinates of a point in the
axes coordinate system that forms the directed line segment PQ, where P is the
point (0,0,0) and Q is the specified x-, y-, and z-coordinates. This line always
points up. The length of the line PQ has no effect on the orientation of the scene.
This means a value of [0 0 1] produces the same results as [0 0 25].
2-68
camup
See Also
axis, camproj, campos, camtarget, camva
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
The “Camera Properties” section in the Using MATLAB Graphics manual.
2-69
camva
Purpose
2camva
Set or query the camera view angle
Syntax
camva
camva(view_angle)
camva('mode')
camva('auto')
camva('manual')
camva(axes_handle,...)
Description
The camera view angle determines the field of view of the camera. Larger
angles produce a smaller view of the scene. You can implement zooming by
changing the camera view angle.
camva with no arguments returns the camera view angle setting in the current
axes.
camva(view_angle) sets the view angle in the current axes to the specified
value. Specify the view angle in degrees.
camva('mode') returns the current value of the camera view angle mode,
which can be either auto (the default) or manual. See Remarks.
camva('auto') sets the camera view angle mode to auto.
camva('manual') sets the camera view angle mode to manual. See Remarks.
camva(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
camva operates on the current axes.
Remarks
camva sets or queries values of the Axes object CameraViewAngle and
CameraViewAngleMode properties.
When the camera view angle mode is auto, MATLAB adjusts the camera view
angle so that the scene fills the available space in the window. If you move the
camera to a different position, MATLAB changes the camera view angle to
maintain a view of the scene that fills the available area in the window.
2-70
camva
Setting a camera view angle or setting the camera view angle to manual
disables MATLAB’s stretch-to-fill feature (stretching of the axes to fit the
window). This means setting the camera view angle to its current value,
camva(camva)
can cause a change it the way the graphs look. See the Remarks section of the
axes function description and the “Camera Properties” section in the Using
MATLAB Graphics manual.
Examples
This example creates two pushbuttons, one that zooms in and another that
zooms out.
uicontrol('Style','pushbutton',...
'String','Zoom In',...
'Position',[20 20 60 20],...
'Callback','if camva <= 1;return;else;camva(camva-1);end');
uicontrol('Style','pushbutton',...
'String','Zoom Out',...
'Position',[100 20 60 20],...
'Callback','if camva >= 179;return;else;camva(camva+1);end');
Now create a graph to zoom in and out on:
surf(peaks);
Note the range checking in the callback statements. This keeps the values for
the camera view angle in the range, greater than zero and less than 180.
See Also
axis, camproj, campos, camup, camtarget
The Axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
2-71
camzoom
Purpose
2camzoom
Zoom in and out on a scene
Syntax
camzoom(zoom_factor)
camzoom(axes_handle,...)
Description
camzoom(zoom_factor) zooms in or out on the scene depending on the value
specified by zoom_factor. If zoom_factor is greater than 1, the scene appears
larger; if zoom_factor is greater than zero and less than 1, the scene appears
smaller.
camzoom(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camzoom
operates on the current axes.
Remarks
camzoom sets the Axes CameraViewAngle property, which in turn causes the
CameraViewAngleMode property to be set to manual. Note that setting the
CameraViewAngle property disables MATLAB’s stretch-to-fill feature
(stretching of the axes to fit the window). This may result in a change to the
aspect ratio of your graph. See the axes function for more information on this
behavior.
See Also
axes, camorbit, campan, camroll, camdolly
The “Camera Properties” section in the Using MATLAB Graphics manual
2-72
capture
Purpose
2capture
Screen capture
Syntax
capture
capture(h)
[X,cmap] = capture(h)
Description
capture creates a bitmap copy of the contents of the current Figure, including
any Uicontrol graphics objects. It creates a new Figure and displays the bitmap
copy as an Image graphics object in the new Figure.
capture(h) creates a new Figure that contains a copy of the Figure identified
by h.
[X,cmap] = capture(h) returns an image matrix X and a colormap. You
display this information using the statements
colormap(cmap)
image(X)
Remarks
The resolution of a bitmap copy is less than that obtained with the print
command.
See Also
image, print
2-73
caxis
Purpose
2caxis
Color axis scaling
Syntax
caxis([cmin cmax])
caxis auto
caxis manual
caxis(caxis)
v = caxis
Description
caxis controls the mapping of data values to the colormap. It affects any
Surfaces, Patches, and Images with indexed CData and CDataMapping set to
scaled. It does not affect Surfaces, Patches, or Images with true color CData or
with CDataMapping set to direct.
caxis([cmin cmax]) sets the color limits to specified minimum and maximum
values. Data values less than cmin or greater than cmax map to cmin and cmax,
respectively. Values between cmin and cmax linearly map to the current
colormap.
caxis auto lets MATLAB compute the color limits automatically using the
minimum and maximum data values. This is MATLAB’s default behavior.
Color values set to Inf have the maximum color and values set to −Inf have the
minimum color. Faces or edges with color values set to NaN are not drawn.
caxis manual and caxis(caxis) freeze the color axis scaling at the current
limits. This enables subsequent plots to use the same limits when hold is on.
v = caxis returns a two-element row vector containing the [cmin cmax]
currently in use.
Remarks
caxis changes the CLim and CLimMode properties of Axes graphics objects.
Surface, Patch, and Image graphics objects with indexed CData and
CDataMapping set to scaled map CData values to colors in the Figure colormap
each time they render. CData values equal to or less than cmin map to the first
color value in the colormap, and CData values equal to or greater than cmax
map to the last color value in the colormap. MATLAB performs the following
linear transformation on the intermediate values (referred to as C below) to
2-74
caxis
map them to an entry in the colormap (whose length is m, and whose row index
is referred to as index below):
index = fix((C–cmin)/(cmax–cmin)∗m)+1
Examples
Create (X,Y,Z) data for a sphere and view the data as a Surface:
[X,Y,Z] = sphere;
C = Z;
surf(X,Y,Z,C)
Values of C have the range [−1 1]. Values of C near −1 are assigned the lowest
values in the colormap; values of C near 1 are assigned the highest values in
the colormap.
To map the top half of the surface to the highest value in the color table, set :
caxis([−1 0])
To use only the bottom half of the color table, enter
caxis([−1 3])
which maps the lowest CData values to the bottom of the colormap, and the
highest values to the middle of the colormap (by specifying a cmax whose value
is equal to cmin plus twice the range of the CData).
The command
caxis auto
resets axis scaling back to auto-ranging and you see all the colors in the
Surface. In this case, entering
caxis
returns
[–1 1]
Adjusting the color axis can be useful when using images with scaled color
data. For example, load the image data and colormap for Cape Code,
Massachusetts:
load cape
2-75
caxis
This command loads the images data X and the image’s colormap map into the
workspace. Now display the image with CDataMapping set to scaled and install
the image’s colormap:
image(X,'CDataMapping','scaled')
colormap(map)
MATLAB sets the color limits to span the range of the image data, which is 1
to 192:
caxis
ans =
1
2-76
192
caxis
The blue color of the ocean is the first color in the colormap and is mapped to
the lowest data value (1). We can effectively move sealevel by changing the
lower color limit value. For example:
Caxis = [1 192]
Caxis = [3 192]
50
50
100
100
150
150
200
200
250
250
300
300
100
200
300
100
Caxis = [5 192]
50
100
100
150
150
200
200
250
250
300
300
See Also
200
300
Caxis = [6 192]
50
100
200
300
100
200
300
axes, axis, colormap, get, mesh, pcolor, set, surf
The CLim and CLimMode properties of Axes graphics objects.
The Colormap property of Figure graphics objects.
The Axes chapter in the Using MATLAB Graphics manual.
2-77
cla
Purpose
2cla
Clear current Axes
Syntax
cla
cla reset
Description
cla deletes from the current Axes all graphics objects whose handles are not
hidden (i.e., their HandleVisibility property is set to on).
cla reset deletes from the current Axes all graphics objects regardless of the
setting of their HandleVisibility property and resets all Axes properties,
except Position and Units, to their default values.
Remarks
The cla command behaves the same way when issued on the command line as
it does in callback routines – it does not recognize the HandleVisibility
setting of callback. This means that when issued from within a callback
routine, cla deletes only those objects whose HandleVisibility property is set
to on.
See Also
clf, hold, newplot, reset
2-78
clabel
Purpose
Syntax
2clabel
Contour plot elevation labels
clabel(C,h)
clabel(C,h,v)
clabel(C,h,'manual')
clabel(C)
clabel(C,v)
clabel(C,'manual')
Description
The clabel function adds height labels to a two-dimensional contour plot.
clabel(C,h) rotates the labels and inserts them in the contour lines. The
function inserts only those labels that fit within the contour, due to the size of
the contour.
clabel(C,h,v) creates labels only for those contour levels given in vector v,
then rotates the labels and inserts them in the contour lines.
clabel(C,h,'manual') places contour labels at locations you select with a
mouse. Press the left mouse button (the mouse button on a single-button
mouse) or the space bar to label a contour at the closest location beneath the
center of the cursor. Press the Return key while the cursor is within the Figure
window to terminate labeling. The labels are rotated and inserted in the
contour lines.
clabel(C) adds labels to the current contour plot using the contour structure
C output from contour. The function labels all contours displayed and
randomly selects label positions.
clabel(C,v) labels only those contour levels given in vector v.
clabel(C,'manual') places contour labels at locations you select with a
mouse.
Remarks
When the syntax includes the argument h, this function rotates the labels and
inserts them in the contour lines (see Example). Otherwise, the labels are
displayed upright and a '+' indicates which contour line the label is
annotating.
2-79
clabel
Examples
Generate, draw, and label a simple contour plot:
[x,y] = meshgrid(–2:.2:2);
z = x.^exp(–x.^2–y.^2);
[C,h] = contour(x,y,z);
clabel(C,h);
2
1.5
0.6
1
8
0.6
0.2
2
−0.5
contour, contourc, contourf
8
0.6
0.
0.4
0.4
1
0.6
−1
0.2
0
1
0.2
−1.5
1
7
0.8
2-80
1
See Also
−1
0.6
−1.5
0.8
0.4
−1
−2
−2
−
0. 9.86
2 9e
0.4
0.8
−0.5
−0.2
0
−9.869e−17
0.5
0.2
−0.
0.
0.5
1
1.5
2
clc
Purpose
2clc
Clear command window
Syntax
clc
Description
clc clears the command window.
Examples
Display a sequence of random matrices at the same location in the command
window:
clc
for i =1:25
home
A = rand(5)
end
See Also
clf, home
2-81
clf
Purpose
2clf
Clear current Figure window
Syntax
clf
clf reset
Description
clf deletes from the current Figure all graphics objects whose handles are not
hidden (i.e., their HandleVisibility property is set to on).
clf reset deletes from the current Figure all graphics objects regardless of
the setting of their HandleVisibility property and resets all Figure
properties, except Position, Units, PaperPosition, and PaperUnits to their
default values.
Remarks
The clf command behaves the same way when issued on the command line as
it does in callback routines – it does not recognize the HandleVisibility
setting of callback. This means that when issued from within a callback
routine, clf deletes only those objects whose HandleVisibility property is set
to on.
See Also
cla, clc, hold, reset
2-82
close
Purpose
2close
Delete specified Figure
Syntax
close
close(h)
close name
close all
close all hidden
status = close(...)
Description
close deletes the current Figure or the specified Figure(s). It optionally
returns the status of the close operation.
close deletes the current Figure (equivalent to close(gcf)).
close(h) deletes the Figure identified by h. If h is a vector or matrix, close
deletes all Figures identified by h.
close name deletes the Figure with the specified name.
close all deletes all Figures whose handles are not hidden.
close all hidden deletes all figures including those with hidden handles.
status = close(...) returns 1 if the specified windows have been deleted
and 0 otherwise.
Remarks
The close function works by evaluating the specified Figure’s
CloseRequestFcn property with the statement:
eval(get(h,'CloseRequestFcn'))
The default CloseRequestFcn, closereq, deletes the current Figure using
delete(get(0,'CurrentFigure')). If you specify multiple Figure handles,
close executes each Figure’s CloseRequestFcn in turn. If MATLAB
encounters an error that terminates the execution of a CloseRequestFcn, the
Figure is not deleted. Note that using your computer’s window manager (i.e.,
the Close menu item) also calls the Figure’s CloseRequestFcn.
If a Figure’s handle is hidden (i.e., the Figure’s HandleVisibility property is
set to callback or off and the Root ShowHiddenHandles property is set no),
2-83
close
you must specify the hidden option when trying to access a Figure using the
all option.
To unconditionally delete all Figures, use the statements:
set(0,'ShowHiddenHandles','on')
delete(get(0,'Children'))
The delete function does not execute the Figure’s CloseRequestFcn; it simply
deletes the specified Figure.
The Figure CloseRequestFcn allows you to either delay or abort the closing of
a Figure once the close function has been issued. For example, you can display
a dialog box to see if the user really wants to delete the Figure or save and
cleanup before closing.
See Also
delete, figure, gcf
The Figure HandleVisibility property
The Root ShowHiddenHandles property
2-84
colorbar
Purpose
2colorbar
Display colorbar showing the color scale
Syntax
colorbar
colorbar('vert')
colorbar('horiz')
colorbar(h)
h = colorbar(...)
Description
The colorbar function displays the current colormap in the current Figure and
resizes the current Axes to accommodate the colorbar.
colorbar updates the most recently created colorbar or, when the current
Axes does not have a colorbar, colorbar adds a new vertical colorbar.
colorbar('vert') adds a vertical colorbar to the current Axes.
colorbar('horiz') adds a horizontal colorbar to the current Axes.
colorbar(h) places a colorbar in the Axes identified by h. The colorbar is
horizontal if the width of the Axes is greater than its height, as determined by
the Axes Position property.
h = colorbar(...) returns a handle to the colorbar, which is an Axes
graphics object.
Remarks
colorbar works with two-dimensional and three-dimensional plots.
2-85
colorbar
Examples
Display a colorbar beside the Axes:
surf(peaks(30))
colormap cool
colorbar
8
6
10
8
4
6
4
2
2
0
−2
0
−4
−6
−2
−8
30
25
30
20
15
20
15
10
10
5
5
0
See Also
2-86
colormap
−4
25
0
−6
colordef
Purpose
2colordef
Sets default property values to display different color schemes
Syntax
colordef white
colordef black
colordef none
colordef(fig,color_option)
h = colordef('new',color_option)
Description
colordef enables you to select either a white or black background for graphics
display. It sets axis lines and labels to show up against the background color.
colordef white sets the axis background color to white, the axis lines and
labels to black, and the Figure background color to light gray.
colordef black sets the axis background color to black, the axis lines and
labels to white, and the Figure background color to dark gray.
colordef none sets the Figure coloring to that used by MATLAB Version 4
(essentially a black background).
colordef(fig,color_option) sets the color scheme of the Figure identified
by the handle fig to the color option 'white', 'black', or 'none'.
h = colordef('new',color_option) returns the handle to a new Figure
created with the specified color options (i.e., 'white', 'black', or 'none').
Remarks
colordef affects only subsequently drawn Figures, not those currently on the
display. This is because colordef works by setting default property values (on
the Root or Figure level). You can list the currently set default values on the
Root level with the statement:
get(0,'defaults')
You can remove all default values using the reset command:
reset(0)
See the get and reset references pages for more information.
See Also
whitebg
2-87
colormap
Purpose
2colormap
Set and get the current colormap
Syntax
colormap(map)
colormap('default')
cmap = colormap
Description
A colormap is an m-by-3 matrix of real numbers between 0.0 and 1.0. Each row
is an RGB vector that defines one color. The kth row of the colormap defines the
k-th color, where map(k,:) = [r(k) g(k) b(k)]) specifies the intensity of red,
green, and blue.
colormap(map) sets the colormap to the matrix map. If any values in map are
outside the interval [0 1], MATLAB returns the error: Colormap must have
values in [0,1].
colormap('default') sets the current colormap to the default colormap.
cmap = colormap; retrieves the current colormap. The values returned are in
the interval [0 1].
Specifying Colormaps
M-files in the color directory generate a number of colormaps. Each M-file
accepts the colormap size as an argument. For example,
colormap(hsv(128))
creates an hsv colormap with 128 colors. If you do not specify a size, MATLAB
creates a colormap the same size as the current colormap.
Supported Colormaps
MATLAB supports a number of colormaps.
• autumn varies smoothly from red, through orange, to yellow.
• bone is a grayscale colormap with a higher value for the blue component.
This colormap is useful for adding an “electronic” look to grayscale images.
• colorcube contains as many regularly spaced colors in RGB colorspace as
possible, while attempting to provide more steps of gray, pure red, pure
green, and pure blue.
2-88
colormap
• cool consists of colors that are shades of cyan and magenta. It varies
smoothly from cyan to magenta.
• copper varies smoothly from black to bright copper.
• flag consists of the colors red, white, blue, and black. This colormap
completely changes color with each index increment.
• gray returns a linear grayscale colormap.
• hot varies smoothly from black, through shades of red, orange, and yellow,
to white.
• hsv varies the hue component of the hue-saturation-value color model. The
colors begin with red, pass through yellow, green, cyan, blue, magenta, and
return to red. The colormap is particularly appropriate for displaying
periodic functions. hsv(m) is the same as hsv2rgb([h ones(m,2)]) where h
is the linear ramp, h = (0:m–1)'/m.
• jet ranges from blue to red, and passes through the colors cyan, yellow, and
orange. It is a variation of the hsv colormap. The jet colormap is associated
with an astrophysical fluid jet simulation from the National Center for
Supercomputer Applications. See the “Examples” section.
• lines produces a colormap of colors specified by the Axes ColorOrder
property and a shade of gray.
• pink contains pastel shades of pink. The pink colormap provides sepia tone
colorization of grayscale photographs.
• prism repeats the six colors red, orange, yellow, green, blue, and violet.
• spring consists of colors that are shades of magenta and yellow.
• summer consists of colors that are shades of green and yellow.
• white is an all white monochrome colormap.
• winter consists of colors that are shades of blue and green.
Examples
The Images and colormaps demo, imagedemo, provides an introduction to
colormaps. Select Color Spiral from the menu (starts automatically on the
Macintosh). This uses the pcolor function to display a 16-by-16 matrix whose
elements vary from 0 to 255 in a rectilinear spiral. The hsv colormap starts
with red in the center, then passes through yellow, green, cyan, blue, and
magenta before returning to red at the outside end of the spiral. Selecting
Colormap Menu gives access to a number of other colormaps (except on the
Macintosh).
2-89
colormap
The rgbplot function plots colormap values. Try rgbplot(hsv),
rgbplot(gray), and rgbplot(hot).
The following commands display the flujet data using the jet colormap:
load flujet
image(X)
colormap(jet)
2-90
colormap
The demos directory contains a CAT scan image of a human spine. To view the
image:
load spine
image(X)
colormap bone
50
100
150
200
250
300
350
50
100
150
200
250
300
350
400
450
Algorithm
Each Figure has its own Colormap property. colormap is an M-file that sets and
gets this property.
See Also
brighten, caxis, contrast, hsv2rgb, pcolor, rgb2hsv, rgbplot
The Colormap property of Figure graphics objects.
2-91
ColorSpec
Purpose
2ColorSpec
Description
ColorSpec is not a command; it refers to the three ways in which you specify
color in MATLAB:
Color specification
• RGB triple
• Short name
• Long name
The short names and long names are MATLAB strings that specify one of eight
predefined colors. The RGB triple is a three-element row vector whose elements
specify the intensities of the red, green, and blue components of the color; the
intensities must be in the range [0 1]. The following table lists the predefined
colors and their RGB equivalents.
Remarks
2-92
RGB Value
Short Name
Long Name
[1 1 0]
y
yellow
[1 0 1]
m
magenta
[0 1 1]
c
cyan
[1 0 0]
r
red
[0 1 0]
g
green
[0 0 1]
b
blue
[1 1 1]
w
white
[0 0 0]
k
black
The eight predefined colors and any colors you specify as RGB values are not
part of a Figure’s colormap, nor are they affected by changes to the Figure’s
colormap. They are referred to as fixed colors, as opposed to colormap colors.
ColorSpec
Examples
To change the background color of a Figure to green, specify the color with a
short name, a long name, or an RGB triple. These statements generate
equivalent results:
whitebg('g')
whitebg('green')
whitebg([0 1 0]);
You can use ColorSpec anywhere you need to define a color. For example, this
statement changes the Figure background color to pink:
set(gcf,'Color',[1 .4 .6])
See Also
bar, bar3, colordef, colormap, fill, fill3, whitebg
2-93
comet
Purpose
2comet
Two-dimensional comet plot
Syntax
comet(y)
comet(x,y)
comet(x,y,p)
Description
A comet plot is an animated graph in which a circle (the comet head) traces the
data points on the screen. The comet body is a trailing segment that follows the
head. The tail is a solid line that traces the entire function.
comet(y) displays a comet plot of the vector y.
comet(x,y) displays a comet plot of vector y versus vector x.
comet(x,y,p) specifies a comet body of length p∗length(y). p defaults to 0.1.
Remarks
Note that the trace left by comet is created by using an EraseMode of none,
which means you cannot print the plot (you get only the comet head) and it
disappears if you cause a redraw (e.g., by resizing the window).
Examples
Create a simple comet plot:
t = 0:.01:2∗pi;
x = cos(2∗t).∗(cos(t).^2);
y = sin(2∗t).∗(sin(t).^2);
comet(x,y);
See Also
2-94
comet3
comet3
Purpose
2comet3
Three-dimensional comet plot
Syntax
comet3(z)
comet3(x,y,z)
comet3(x,y,z,p)
Description
A comet plot is an animated graph in which a circle (the comet head) traces the
data points on the screen. The comet body is a trailing segment that follows the
head. The tail is a solid line that traces the entire function.
comet3(z) displays a three-dimensional comet plot of the vector z.
comet3(x,y,z) displays a comet plot of the curve through the points
[x(i),y(i),z(i)].
comet3(x,y,z,p) specifies a comet body of length p∗length(y).
Remarks
Note that the trace left by comet3 is created by using an EraseMode of none,
which means you cannot print the plot (you get only the comet head) and it
disappears if you cause a redraw (e.g., by resizing the window).
Examples
Create a three-dimensional comet plot:
t = —10∗pi:pi/250:10∗pi;
comet3((cos(2∗t).^2).∗sin(t),(sin(2∗t).^2).∗cos(t),t);
See Also
comet
2-95
compass
Purpose
2compass
Plot arrows emanating from the origin
Syntax
compass(X,Y)
compass(Z)
compass(...,LineSpec)
h = compass(...)
Description
A compass plot displays direction or velocity vectors as arrows emanating from
the origin. X, Y, and Z are in Cartesian coordinates and plotted on a circular
grid.
compass(X,Y) displays a compass plot having n arrows, where n is the number
of elements in X or Y. The location of the base of each arrow is the origin. The
location of the tip of each arrow is a point relative to the base and determined
by [X(i),Y(i)].
compass(Z) displays a compass plot having n arrows, where n is the number
of elements in Z. The location of the base of each arrow is the origin. The
location of the tip of each arrow is relative to the base as determined by the real
and imaginary components of Z. This syntax is equivalent to
compass(real(Z),imag(Z)).
compass(...,LineSpec) draws a compass plot using the line type, marker
symbol, and color specified by LineSpec.
h = compass(...)
Examples
returns handles to Line objects.
Draw a compass plot of the eigenvalues of a matrix:
Z = eig(randn(20,20));
compass(Z)
2-96
compass
90
5.2689
60
120
4.2151
3.1613
30
150
2.1076
1.0538
180
0
210
330
240
300
270
See Also
feather, LineSpec, rose
2-97
contour
Purpose
2contour
Two-dimensional contour plot
Syntax
contour(Z)
contour(Z,n)
contour(Z,v)
contour(X,Y,Z)
contour(X,Y,Z,n)
contour(X,Y,Z,v)
contour(...,LineSpec)
[C,h] = contour(...)
Description
A contour plot displays isolines of matrix Z. Label the contour lines using
clabel.
contour(Z) draws a contour plot of matrix Z, where Z is interpreted as heights
with respect to the x-y plane. Z must be at least a 2-by-2 matrix. The number
of contour levels and the values of the contour levels are chosen automatically
based on the minimum and maximum values of Z. The ranges of the x- and
y-axis are [1:n] and [1:m], where [m,n] = size(Z).
contour(Z,n) draws a contour plot of matrix Z with n contour levels.
contour(Z,v) draws a contour plot of matrix Z with contour lines at the data
values specified in vector v. The number of contour levels is equal to length(v).
To draw a single contour of level i, use contour(Z,[i i]).
contour(X,Y,Z), contour(X,Y,Z,n), and contour(X,Y,Z,v) draw contour
plots of Z. X and Y specify the x- and y-axis limits. When X and Y are matrices,
they must be the same size as Z, in which case they specify a surface as surf
does.
contour(...,LineSpec) draws the contours using the line type and color
specified by LineSpec. contour ignores marker symbols.
[C,h] = contour(...) returns the contour matrix C (see contourc) and a
vector of handles to graphics objects. clabel uses the contour matrix C to create
the labels. contour creates Patch graphics objects unless you specify LineSpec,
in which case contour creates Line graphics objects.
2-98
contour
Remarks
If you do not specify LineSpec, colormap and caxis control the color.
If X or Y is irregularly spaced, contour calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
To view a contour plot of the function
z = xe ( – x
2
– y2 )
over the range –2 ≤ x ≤ 2, –2 ≤ y ≤ 3, create matrix Z using the statements
[X,Y] = meshgrid(–2:.2:2,–2:.2:3);
Z = X.∗exp(–X.^2–Y.^2);
Then, generate a contour plot of Z:
[C,h] = contour(X,Y,Z);
clabel(C,h)
colormap cool
3
2.5
2
1.5
0.1
1
−0.
1
0
−0.1
2
−0.
0.5
0.2
Examples
0.4
0
0.3
.3
−0.5
0.1
−0
−0.2
0.2
0.1
−1
−0.1
0
−1.5
−2
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
2-99
contour
View the same function over the same range with 20 evenly spaced contour
lines and colored with the default colormap jet:
contour(X,Y,Z,20)
3
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−2
−1.5
−1
−0.5
0
0.5
1
1.5
Use interp2 and contour to create smoother contours:
Z = magic(4);
[C,h] = contour(interp2(Z,4));
clabel(C,h)
2-100
2
45
10
contour
12
40
10
8
35
8
8
10
30
8
25
20
10
10
15
8
8
8
10
6
5
4
5
See Also
10
15
20
25
30
35
40
45
clabel, contour3, contourc, contourf, interp2, quiver
2-101
contour3
Purpose
2contour3
Three-dimensional contour plot
Syntax
contour3(Z)
contour3(Z,n)
contour3(Z,v)
contour3(X,Y,Z)
contour3(X,Y,Z,n)
contour3(X,Y,Z,v)
contour3(...,LineSpec)
[C,h] = contour3(...)
Description
contour3 creates a three-dimensional contour plot of a surface defined on a
rectangular grid.
contour3(Z) draws a contour plot of matrix Z in a three-dimensional view. Z
is interpreted as heights with respect to the x-y plane. Z must be at least a
2-by-2 matrix. The number of contour levels and the values of contour levels
are chosen automatically. The ranges of the x- and y-axis are [1:n] and [1:m],
where [m,n] = size(Z).
contour3(Z,n) draws a contour plot of matrix Z with n contour levels in a
three-dimensional view.
contour3(Z,v) draws a contour plot of matrix Z with contour lines at the
values specified in vector v. The number of contour levels is equal to length(v).
To draw a single contour of level i, use contour(Z,[i i]).
contour3(X,Y,Z), contour3(X,Y,Z,n), and contour3(X,Y,Z,v) use X and Y
to define the x- and y-axis limits. If X is a matrix, X(1,:) defines the x-axis. If
Y is a matrix, Y(:,1) defines the y-axis. When X and Y are matrices, they must
be the same size as Z, in which case they specify a surface as surf does.
contour3(...,LineSpec) draws the contours using the line type and color
specified by LineSpec.
[C,h] = contour3(...) returns the contour matrix C as described in the
function contourc and a column vector containing handles to graphics objects.
contour3 creates Patch graphics objects unless you specify LineSpec, in which
case contour3 creates Line graphics objects.
2-102
contour3
Remarks
If you do not specify LineSpec, colormap and caxis control the color.
If X or Y is irregularly spaced, contour3 calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
Examples
Plot the three-dimensional contour of a function and superimpose a surface
plot to enhance visualization of the function:
[X,Y] = meshgrid([-2:.25:2]);
Z = X.*exp(-X.^2-Y.^2);
contour3(X,Y,Z,30)
surface(X,Y,Z,’EdgeColor’,[.8 .8 .8],’FaceColor’,’none’)
grid off
view(-15,25)
colormap cool
0.5
0
−0.5
2
1
0
−1
−2
See Also
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
contour, contourc, meshc, meshgrid, surfc
2-103
contourc
Purpose
2contourc
Low-level contour plot computation
Syntax
C
C
C
C
C
C
Description
contourc calculates the contour matrix C used by contour, contour3, and
contourf. The values in Z determine the heights of the contour lines with
=
=
=
=
=
=
contourc(Z)
contourc(Z,n)
contourc(Z,v)
contourc(x,y,Z)
contourc(x,y,Z,n)
contourc(x,y,Z,v)
respect to a plane. The contour calculations use a regularly spaced grid
determined by the dimensions of Z.
C = contourc(Z) computes the contour matrix from data in matrix Z, where
Z must be at least a 2-by-2 matrix. The contours are isolines in the units of Z.
The number of contour lines and the corresponding values of the contour lines
are chosen automatically.
C = contourc(Z,n) computes contours of matrix Z with n contour levels.
C = contourc(Z,v) computes contours of matrix Z with contour lines at the
values specified in vector v. The length of v determines the number of contour
levels. To compute a single contour of level i, use contourc(Z,[i i]).
C = contourc(x,y,Z), C = contourc(x,y,Z,n), and
C = contourc(x,y,Z,v) compute contours of Z using vectors x and y to
determine the x- and y-axis limits. x and y must be monotonically increasing.
Remarks
C is a two-row matrix specifying all the contour lines. Each contour line defined
in matrix C begins with a column that contains the value of the contour
(specified by v and used by clabel), and the number of (x,y) vertices in the
contour line. The remaining columns contain the data for the (x,y)pairs.
C = [ value1 xdata(1) xdata(2)...value2 xdata(1) xdata(2)...;
dim1
ydata(1) ydata(2)...dim2
ydata(1) ydata(2)...]
Specifying irregularly spaced x and y vectors is not the same as contouring
irregularly spaced data. If x or y is irregularly spaced, contourc calculates
2-104
contourc
contours using a regularly spaced contour grid, then transforms the data to x
or y.
See Also
clabel, contour, contour3, contourf
2-105
contourf
Purpose
2contourf
Filled two-dimensional contour plot
Syntax
contourf(Z)
contourf(Z,n)
contourf(Z,v)
contourf(X,Y,Z)
contourf(X,Y,Z,n)
contourf(X,Y,Z,v)
[C,h,CF] = contourf(...)
Description
A filled contour plot displays isolines calculated from matrix Z and fills the
areas between the isolines using constant colors. The color of the filled areas
depends on the current Figure’s colormap.
contourf(Z) draws a contour plot of matrix Z, where Z is interpreted as
heights with respect to a plane. Z must be at least a 2-by-2 matrix. The number
of contour lines and the values of the contour lines are chosen automatically.
contourf(Z,n) draws a contour plot of matrix Z with n contour levels.
contourf(Z,v) draws a contour plot of matrix Z with contour levels at the
values specified in vector v.
contourf(X,Y,Z), contourf(X,Y,Z,n), and contourf(X,Y,Z,v) produce
contour plots of Z using X and Y to determine the x- and y-axis limits. When X
and Y are matrices, they must be the same size as Z, in which case they specify
a surface as surf does.
[C,h,CF] = contourf(...) returns the contour matrix C as calculated by the
function contourc and used by clabel, a vector of handles h to Patch graphics
objects, and a contour matrix CF for the filled areas.
Remarks
2-106
If X or Y is irregularly spaced, contourf calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
contourf
Examples
Create a filled contour plot of the peaks function:
[C,h] = contourf(peaks(20),10);
colormap autumn
20
18
16
14
12
10
8
6
4
2
2
See Also
4
6
8
10
12
14
16
18
20
clabel, contour, contour3, contourc, quiver
2-107
contrast
Purpose
2contrast
Grayscale colormap for contrast enhancement
Syntax
cmap = contrast(X)
cmap = contrast(X,m)
Description
The contrast function enhances the contrast of an image. It creates a new gray
colormap, cmap, that has an approximately equal intensity distribution. All
three elements in each row are identical.
cmap = contrast(X) returns a gray colormap that is the same length as the
current colormap.
cmap = contrast(X,m) returns an m-by-3 gray colormap.
Examples
Add contrast to the clown image defined by X:
load clown;
cmap = contrast(X);
image(X);
colormap(cmap);
See Also
2-108
brighten, colormap, image
copyobj
Purpose
2copyobj
Copy graphics objects and their descendants
Syntax
new_handle = copyobj(h,p)
Description
copyobj creates copies of graphics objects. The copies are identical to the
original objects except the copies have different values for their Parent
property and a new handle. The new parent must be appropriate for the copied
object (e.g., you can copy a Line object only to another Axes object).
new_handle = copyobj(h,p) copies one or more graphics objects identified by
h and returns the handle of the new object or a vector of handles to new objects.
The new graphics objects are children of the graphics objects specified by p.
Remarks
h and p can be scalars or vectors. When both are vectors, they must be the same
length and the output argument, new_handle, is a vector of the same length.
In this case, new_handle(i) is a copy of h(i) with its Parent property set to
p(i).
When h is a scalar and p is a vector, h is copied once to each of the parents in p.
Each new_handle(i) is a copy of h with its Parent property set to p(i), and
length(new_handle) equals length(p).
When h is a vector and p is a scalar, each new_handle(i) is a copy of h(i) with
its Parent property set to p. The length of new_handle equals length(h).
Graphics objects are arranged as a hierarchy. Here, each graphics object is
shown connected below its appropriate parent object.
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
2-109
copyobj
Examples
Copy a Surface to a new Axes within a different Figure:
h = surf(peaks);
colormap hot
figure
% Create a new Figure
axes
% Create an Axes object in the Figure
new_handle = copyobj(h,gca);
colormap hot
view(3)
grid on
Note that while the Surface is copied, the colormap (Figure property), view,
and grid (Axes properties) are not copies.
See Also
findobj, gcf, gca, gco, get, set
Parent property for all graphics objects
2-110
cylinder
Purpose
2cylinder
Generate cylinder
Syntax
[X,Y,Z] = cylinder
[X,Y,Z] = cylinder(r)
[X,Y,Z] = cylinder(r,n)
cylinder(...)
Description
cylinder generates x, y, and z coordinates of a unit cylinder. You can draw the
cylindrical object using surf or mesh, or draw it immediately by not providing
output arguments.
[X,Y,Z] = cylinder returns the x, y, and z coordinates of a cylinder with a
radius equal to 1. The cylinder has 20 equally spaced points around its
circumference.
[X,Y,Z] = cylinder(r) returns the x, y, and z coordinates of a cylinder using
r to define a profile curve. cylinder treats each element in r as a radius at
equally spaced heights along the unit height of the cylinder. The cylinder has
20 equally spaced points around its circumference.
[X,Y,Z] = cylinder(r,n) returns the x, y, and z coordinates of a cylinder
based on the profile curve defined by vector r. The cylinder has n equally
spaced points around its circumference.
cylinder(...), with no output arguments, plots the cylinder using surf.
Remarks
cylinder treats its first argument as a profile curve. The resulting Surface
graphics object is generated by rotating the curve about the x-axis, and then
aligning it with the z-axis.
2-111
cylinder
Examples
Create a cylinder with randomly colored faces.
cylinder
axis square
h = findobj('Type','surface');
set(h,'CData',rand(size(get(h,'CData'))))
1
0.8
0.6
0.4
0.2
0
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
Generate a cylinder defined by the profile function 2+sin(t):
t = 0:pi/10:2*pi;
[X,Y,Z] = cylinder(2+cos(t));
surf(X,Y,Z)
axis square
2-112
cylinder
1
0.8
0.6
0.4
0.2
0
4
4
2
2
0
0
−2
−2
−4
See Also
−4
sphere, surf
2-113
cylinder
2-114
daspect
Purpose
2daspect
Set or query the axes data aspect ratio
Syntax
daspect
daspect([aspect_ratio])
daspect('mode')
daspect('auto')
daspect('manual')
daspect(axes_handle,...)
Description
The data aspect ratio determines the relative scaling of the data units along the
x-, y-, and z-axes.
daspect with no arguments returns the data aspect ratio of the current axes.
daspect([aspect_ratio]) sets the data aspect ratio in the current axes to the
specified value. Specify the aspect ratio as three relative values representing
the ratio of the x-, y-, and z-axis scaling (e.g., [1 1 3] means one unit in x is
equal in length to one unit in y and three unit in z).
daspect('mode') returns the current value of the data aspect ratio mode,
which can be either auto (the default) or manual. See Remarks.
daspect('auto') sets the data aspect ratio mode to auto.
daspect('manual') sets the data aspect ratio mode to manual.
daspect(axes_handle,...) performs the set or query on the axes identified
by the first argument, axes_handle. When you do not specify an axes handle,
daspect operates on the current axes.
Remarks
daspect sets or queries values of the Axes object DataAspectRatio and
DataAspectRatioMode properties.
When the data aspect ratio mode is auto, MATLAB adjusts the data aspect
ratio so that each axis spans the space available in the Figure window. If you
are displaying a representation of a real-life object, you should set the data
aspect ratio to [1 1 1] to produce the correct proportions.
Setting a value for data aspect ratio or setting the data aspect ratio mode to
manual disables MATLAB’s stretch-to-fill feature (stretching of the axes to fit
2-115
daspect
the window). This means setting the data aspect ratio to a value, including its
current value,
daspect(daspect)
can cause a change in the way the graphs look. See the Remarks section of the
axes function description and the “Aspect Ratio” section in the Using MATLAB
Graphics manual for more information.
Examples
The following surface plot of the function z = xe ( – x – y ) is useful to illustrate
the data aspect ratio. First plot the function over the range –2 ≤ x ≤ 2, –2 ≤ y ≤ 2,
2
2
[x,y] = meshgrid([-2:.2:2]);
z = x.*exp(-x.^2 - y.^2);
surf(x,y,z)
0.5
0
−0.5
2
1
2
1
0
0
−1
−1
−2
−2
Querying the data aspect ratio shows how MATLAB has drawn the surface:
daspect
ans =
4 4
2-116
1
daspect
Setting the data aspect ratio to [1 1 1] produces a surface plot with equal
scaling alone each axis:
daspect([1 1 1])
0.5
0
−0.5
2
1.5
2
1
0.5
1
0
−0.5
0
−1
−1
−1.5
−2
See Also
−2
axis, pbaspect, xlim, ylim, zlim
The Axes properties DataAspectRatio, PlotBoxAspectRatio, XLim, YLim, ZLim
The “Aspect Ratio” section in the Using MATLAB Graphics manual.
2-117
datetick
Purpose
2datetick
Label tick lines using dates
Syntax
datetick(tickaxis)
datetick(tickaxis,dateform)
Description
datetick(tickaxis) labels the tick lines of an axis using dates, replacing the
default numeric labels. tickaxis is the string 'x', 'y', or 'z'. The default is
'x'. datetick selects a label format based on the minimum and maximum
limits of the specified axis.
datetick(tickaxis,dateform) formats the labels according to the integer
dateform (see table). To produce correct results, the data for the specified axis
must be serial date numbers (as produced by datenum).
2-118
Dateform
Format
Example
0
day-month-year hour:minute
01-Mar-1995 03:45
1
day-month-year
01-Mar-1995
2
month/day/year
03/01/95
3
month, three letters
Mar
4
month, single letter
M
5
month, numeral
3
6
month/day
03/01
7
day of month
1
8
day of week, three letters
Wed
9
day of week, single letter
W
10
year, four digit
1995
11
year, two digit
95
datetick
Remarks
Dateform
Format
Example
12
month year
Mar95
13
hour:minute:second
15:45:17
14
hour:minute:second AM or PM
03:45:17
15
hour:minute
15:45
16
hour:minute AM or PM
03:45 PM
datetick calls datestr to convert date numbers to date strings.
To change the tick spacing and locations, set the appropriate Axes property
(i.e., XTick, YTick, or ZTick) before calling datetick.
2-119
datetick
Example
Consider graphing population data based on the 1990 U.S. census:
t = (1900:10:1990)';
% Time interval
p = [75.995 91.972 105.711 123.203 131.669 ...
150.697 179.323 203.212 226.505 249.633]'; % Population
plot(datenum(t,1,1),p) % Convert years to date numbers and plot
grid on
datetick('x',11)
% Replace x-axis ticks with 2-digit year labels
260
240
220
200
180
160
140
120
100
80
60
00
See Also
20
60
The Axes properties XTick, YTick, and ZTick.
datenum, datestr
2-120
40
80
00
default4
Purpose
2default4
MATLAB Version 4.0 Figure and Axes defaults
Syntax
default4
default4(h)
Description
default4 sets Figure and Axes defaults to match MATLAB Version 4.0
defaults.
default4(h) only affects the Figure with handle h.
See Also
colordef
2-121
drawnow
Purpose
2drawnow
Complete pending drawing events
Syntax
drawnow
Description
drawnow flushes the event queue and updates the Figure window.
Remarks
Other events that cause MATLAB to flush the event queue and draw the
Figure windows include:
• Returning to the MATLAB prompt
• A pause statement
• A waitforbuttonpress statement
• A waitfor statement
• A getframe statement
• A figure statement
Examples
Executing the statements,
x = –pi:pi/20:pi;
plot(x,cos(x))
drawnow
title('A Short Title')
grid on
as an M-file updates the current Figure after executing the drawnow function
and after executing the final statement.
See Also
2-122
waitfor, pause, waitforbuttonpress
errorbar
Purpose
2errorbar
Plot error bars along a curve
Syntax
errorbar(Y,E)
errorbar(X,Y,E)
errorbar(X,Y,L,U)
errorbar(...,LineSpec)
h = errorbar(...)
Description
Error bars show the confidence level of data or the deviation along a curve.
errorbar(Y,E) plots Y and draws an error bar at each element of Y. The error
bar is a distance of E(i) above and below the curve so that each bar is
symmetric and 2∗E(i) long.
errorbar(X,Y,E) plots X versus Y with symmetric error bars 2∗E(i) long. X, Y,
E must be the same size. When they are vectors, each error bar is a distance of
E(i) above and below the point defined by (X(i),Y(i)). When they are
matrices, each error bar is a distance of E(i,j) above and below the point
defined by (X(i,j),Y(i,j)).
errorbar(X,Y,L,U) plots X versus Y with error bars L(i)+U(i) long specifying
the lower and upper error bars. X, Y, L, and U must be the same size. When they
are vectors, each error bar is a distance of L(i) below and U(i) above the point
defined by (X(i),Y(i)). When they are matrices, each error bar is a distance
of L(i,j) below and U(i,j) above the point defined by (X(i,j),Y(i,j)).
errorbar(...,LineSpec) draws the error bars using the line type, marker
symbol, and color specified by LineSpec.
h = errorbar(...) returns a vector of handles to Line graphics objects.
Remarks
When the arguments are all matrices, errorbar draws one line per matrix
column. If X and Y are vectors, they specify one curve.
2-123
errorbar
Examples
Draw symmetric error bars that are two standard deviation units in length:
X = 0:pi/10:pi;
Y = sin(X);
E = std(Y)*ones(size(X));
errorbar(X,Y,E)
1.4
1.2
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.5
See Also
2-124
0
0.5
LineSpec, plot, std
1
1.5
2
2.5
3
3.5
ezplot
Purpose
2ezplot
Easy to use function plotter.
Syntax
ezplot(f)
ezplot(f,[xmin xmax])
ezplot(f,[xmin xmax],fig)
Description
ezplot(f) plots a graph of f(x), where f is a symbolic expression representing
a mathematical expression involving a single symbolic variable, say x. The
domain on the x-axis is usually [–2*pi, 2*pi].
ezplot(f,[xmin xmax]) uses the specified x-domain instead of the default
[–2*pi, 2*pi].
ezplot(f,[xmin xmax],fig) uses the specified Figure number instead of the
current Figure. It also omits the title of the graph.
Examples
Either of the following commands,
ezplot('erf(x)')
ezplot erf(x)
2-125
ezplot
plot a graph of the error function::
erf(x)
1
0.5
0
−0.5
−1
−2
−1.5
−1
−0.5
The statement,
ezplot('sin(x)',[0 2*pi])
creates the plot:
2-126
0
x
0.5
1
1.5
2
ezplot
sin(x)
1
0.5
0
−0.5
−1
0
1
2
3
4
5
6
x
Algorithm
ezplot determines the interval of the x-axis by sampling the function between
–2*pi and 2*pi and then selecting a subinterval where the variation is
significant. For the range of the y-axis, ezplot omits extreme values associated
with singularities.
See Also
fplot
2-127
feather
Purpose
2feather
Plot velocity vectors
Syntax
feather(U,V)
feather(Z)
feather(...,LineSpec)
Description
A feather plot displays vectors emanating from equally spaced points along a
horizontal axis. You express the vector components relative to the origin of the
respective vector.
feather(U,V) displays the vectors specified by U and V, where U contains the
x components as relative coordinates, and V contains the y components as
relative coordinates.
feather(Z) displays the vectors specified by the complex numbers in Z. This
is equivalent to feather(real(Z),imag(Z)).
feather(...,LineSpec) draws a feather plot using the line type, marker
symbol, and color specified by LineSpec.
Examples
Create a feather plot showing the direction of theta:
theta = (–90:10:90)∗pi/180;
r = 2∗ones(size(theta));
[u,v] = pol2cart(theta,r);
feather(u,v);
2-128
feather
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
See Also
0
2
4
6
8
10
12
14
16
18
20
compass, LineSpec, rose
2-129
figflag
Purpose
2figflag
Test if Figure is on screen
Syntax
[flag] = figflag('figurename')
[flag,fig] = figflag('figurename')
[...] = figflag('figurename',silent)
Description
Use figflag to determine if a particular Figure exists, bring a Figure to the
foreground, or set the window focus to a Figure.
[flag] = figflag('figurename') returns a 1 if the Figure named
'figurename' exists and pops the Figure to the foreground; otherwise this
function returns 0.
[flag,fig] = figflag('figurename') returns a 1 in flag, returns the
Figure’s handle in fig, and pops the Figure to the foreground, if the Figure
named 'figurename' exists. Otherwise this function returns 0.
[...] = figflag('figurename',silent) pops the Figure window to the
foreground if silent is 0, and leaves the Figure in its current position if silent
is 1.
Examples
To determine if a Figure window named 'Fluid Jet Simulation' exists, type
[flag,fig] = figflag('Fluid Jet Simulation')
MATLAB returns:
flag =
1
fig =
1
If two Figures with handles 1 and 3 have the name 'Fluid Jet Simulation',
MATLAB returns:
flag =
1
fig =
1 3
See Also
2-130
figure
figure
Purpose
2figure
Create a Figure graphics object
Syntax
figure
figure('PropertyName',PropertyValue,...)
figure(h)
h = figure(...)
Description
figure creates Figure graphics objects. Figure objects are the individual
windows on the screen in which MATLAB displays graphical output.
figure creates a new Figure object using default property values.
figure('PropertyName',PropertyValue,...) creates a new Figure object
using the values of the properties specified. MATLAB uses default values for
any properties that you do not explicitly define as arguments.
figure(h) does one of two things, depending on whether or not a Figure with
handle h exists. If h is the handle to an existing Figure, figure(h) makes the
Figure identified by h the current Figure, makes it visible, and raises it above
all other Figures on the screen. The current Figure is the target for graphics
output. If h is not the handle to an existing Figure, but is an integer, figure(h)
creates a Figure, and assigns it the handle h. figure(h) where h is not the
handle to a Figure, and is not an integer, is an error.
h = figure(...) returns the handle to the Figure object.
Remarks
To create a Figure object, MATLAB creates a new window whose
characteristics are controlled by default Figure properties (both factory
installed and user defined) and properties specified as arguments. See the
“Figure Properties” section for a description of these properties.
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see the set and get reference pages for examples of how
to specify these data types).
Use set to modify the properties of an existing Figure or get to query the
current values of Figure properties.
The gcf command returns the handle to the current Figure and is useful as an
argument to the set and get commands.
2-131
figure
Example
To create a Figure window that is one quarter the size of your screen and is
positioned in the upper-left corner, use the Root object’s ScreenSize property
to determine the size. ScreenSize is a four-element vector: [left, bottom,
width, height]:
scrsz = get(0,'ScreenSize');
figure('Position',[1 scrsz(4)/2 scrsz(3)/2 scrsz(4)/2])
See Also
axes, uicontrol, uimenu, close, clf, gcf, rootobject
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Figure properties only on the Root level:
set(0,'DefaultFigureProperty',PropertyValue...)
Where Property is the name of the Figure property and PropertyValue is the
value you are specifying. Use set and get to access Figure properties.
Property List
2-132
The following table lists all Figure properties and provides a brief description
of each. The property name links bring you an expanded description of the
properties.
figure
Property Name
Property Description
Property Value
Position
Location and size of Figure
Value: a 4-element vector
[left, bottom, width, height]
Default: depends on display
Units
Units used to interpret the Position
property
Values: inches, centimeters,
normalized, points, pixels,
characters
Default: pixels
Positioning the Figure
Specifying Style and Appearance
Color
Color of the Figure background
Values: ColorSpec
Default: depends on color
scheme (see colordef)
MenuBar
Toggle the Figure menu bar on and
off
Values: none, figure
Default: figure
Name
Figure window title
Values: string
Default: '' (empty string)
NumberTitle
Display “Figure No. n”, where n is
the Figure number
Values: on, off
Default: on
Resize
Specify whether the Figure window
can be resized using the mouse
Values: on, off
Default: on
SelectionHighlight
Highlight Figure when selected
(Selected property set to on)
Values: on, off
Default: on
Visible
Make the Figure visible or invisible
Values: on, off
Default: on
WindowStyle
Select normal or modal window
Values: normal, modal
Default: normal
Controlling the Colormap
2-133
figure
Property Name
Property Description
Property Value
Colormap
The Figure colormap
Values: m-by-3 matrix of
RGB values
Default: the jet colormap
Dithermap
Colormap used for truecolor data on
pseudocolor displays
Values: m-by-3 matrix of
RGB values
Default: colormap with full
range of colors
DithermapMode
Enable MATLAB-generated
dithermap
Values: auto, manual
Default: manual
FixedColors
Colors not obtained from colormap
Values: m-by-3 matrix of
RGB values (read only)
MinColormap
Minimum number of system color
table entries to use
Values: scalar
Default: 64
ShareColors
Allow MATLAB to share system
color table slots
Values on, off
Default: on
BackingStore
Enable off screen pixel buffering
Values: on, off
Default: on
Renderer
Rendering method used for screen
and printing
Values: painters, zbuffer,
Specifying the Renderer
OpenGL
Default: automatic selection
by MATLAB
General Information About the Figure
Children
Handle of any Uicontrol, Uimenu,
and Uicontextmenu objects displayed
in the Figure
Values: vector of handles
Parent
The Root object is the parent of all
Figures
Value: always 0
2-134
figure
Property Name
Property Description
Property Value
Selected
Indicate whether Figure is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'figure'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
RendererMode
Automatic or user-selected renderer
Values: auto, manual
Default: auto
Information About Current State
CurrentAxes
Handle of the current Axes in this
Figure
Values: Axes handle
CurrentCharacter
The last key pressed in this Figure
Values: single character
(read only)
CurrentObject
Handle of the current object in this
Figure
Values: graphics object
handle
CurrentPoint
Location of the last button click in
this Figure
Values: 2-element vector
[x-coord, y-coord]
SelectionType
Mouse selection type (read only)
Values: normal, extended,
alt, open
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on an unoccupied spot in the
Figure
Values: string
Default: empty string
Callback Routine Execution
2-135
figure
Property Name
Property Description
Property Value
CloseRequestFcn
Define a callback routine that
executes when you call the close
command
Values: string
Default: empty string
CreateFcn
Define a callback routine that
executes when a Figure is created
Values: string
Default: empty string
DeleteFcn
Define a callback routine that
executes when the Figure is deleted
(via close or delete)
Values: string
Default: empty string
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
KeyPressFcn
Define a callback routine that
executes when a key is pressed in the
Figure window
Values: string
Default: empty string
ResizeFcn
Define a callback routine that
executes when the Figure is resized
Values: string
Default: empty string
UIContextMenu
Associate a context menu with the
Figure
Values: handle of a
Uicontrextmenu
WindowButtonDownFcn
Define a callback routine that
executes when you press the mouse
button down in the Figure
Values: string
Default: empty string
WindowButtonMotionFcn
Define a callback routine that
executes when you move the pointer
in the Figure
Values: string
Default: empty string
WindowButtonUpFcn
Define a callback routine that
executes when you release the mouse
button
Values: string
Default: empty string
Controlling Access to Objects
2-136
figure
Property Name
Property Description
Property Value
IntegerHandle
Specify integer or noninteger Figure
handle
Values: on, off
Default: on (integer handle)
HandleVisibility
Determine if Figure handle is visible
to users or not
Values: on, callback, off
Default: on
HitTest
Determine if the Figure can become
the current object (see the Figure
CurrentObject property)
Values: on, off
Default: on
NextPlot
Determine how to display additional
graphics to this Figure
Values: add, replace,
replacechildren
Default: add
Defining the Pointer
Pointer
Select the pointer symbol
Values: crosshair, arrow,
watch, topl, topr, botl, botr,
circle, cross, fleur, left,
right, top, bottom,
fullcrosshair, ibeam,
custom
Default: arrow
PointerShapeCData
Data that defines the pointer
Values: 16-by-16 matrix
Default: set Pointer to
custom and see
PointerShapeHotSpot
Specify the pointer active spot
Values: 2-element vector
[row, column]
Default: [1,1]
Properties That Affect Printing
InvertHardcopy
Change Figure colors for printing
Values: on, off
Default: on
PaperOrientation
Horizontal or vertical paper
orientation
Values: portrait, landscape
Default: portrait
2-137
figure
Property Name
Property Description
Property Value
PaperPosition
Control positioning Figure on printed
page
Values: 4-element vector
[left, bottom, width, height]
PaperPositionMode
Enable WYSIWYG printing of Figure Values: auto, manual
Default: manual
PaperSize
Size of the current PaperType
specified in PaperUnits (read only)
Values: [width, height]
PaperType
Select from standard paper sizes
Values: see property
description
Default: usletter
PaperUnits
Units used to specify the PaperSize
and PaperPosition
Values: normalized, inches,
centimeters, points
Default: inches
2-138
Figure Properties
Figure
Properties
2Figure Properties
This section lists property names along with the type of values each accepts.
Curly braces { } enclose default values.
BackingStore
{on} | off
Off screen pixel buffer. When BackingStore is on, MATLAB stores a copy of the
Figure window in an off-screen pixel buffer. When obscured parts of the Figure
window are exposed, MATLAB copies the window contents from this buffer
rather than regenerating the objects on the screen. This increases the speed
with which the screen is redrawn.
While refreshing the screen quickly is generally desirable, the buffers required
do consume system memory. If memory limitations occur, you can set
BackingStore to off to disable this feature and release the memory used by the
buffers. If your computer does not support backingstore, setting the
BackingStore property results in a warning message, but has no other effect.
Setting BackingStore to off can increase the speed of animations because it
eliminates the need to draw into both an off-screen buffer and the Figure
window.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routines always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback function. A callback routine that executes whenever you
press a mouse button while the pointer is in the Figure window, but not over a
child object (i.e., Uicontrol, Axes, or Axes child). Define this routine as a string
2-139
Figure Properties
that is a valid MATLAB expression or the name of an M-file. The expression
executes in the MATLAB workspace.
Children
vector of handles
Children of the Figure. A vector containing the handles of all Axes, Uicontrol,
and Uimenu objects displayed within the Figure. You can change the order of
the handles and thereby change the stacking of the objects on the display.
Clipping
{on} | off
This property has no effect on Figures.
CloseRequestFcn
string
Function executed on Figure close. This property defines a function that
MATLAB executes whenever you issue the close command (either a
close(figure_handle) or a close all) or when you close a Figure window
from the computer’s window manager menu.
The CloseRequestFcn provides a mechanism to intervene in the closing of a
Figure. It allows you to, for example, display a dialog box to ask a user to
confirm or cancel the close operation or to prevent users from closing a Figure
that contains a GUI.
The basic mechanism is:
• A user issues the close command from the command line or by closing the
window from the computer’s window manager menu.
• The close operation executes the function defined by the Figure
CloseRequestFcn. The default function is named closereq and is predefined
as:
delete(get(0,'CurrentFigure'))
This statement unconditionally deletes the current Figure, destroying the
window. closereq takes advantage of the fact that the close command makes
all Figures specified as arguments the current Figure before calling the
respective close request function.
You can set CloseRequestFcn to any string that is a valid MATLAB statement,
including the name of an M-file. For example,
set(gcf,'CloseRequestFcn','disp(''This window is immortal'')')
2-140
Figure Properties
This close request function never closes the Figure window; it simply echoes
“This window is immortal” on the command line. Unless the close request
function calls delete, MATLAB never closes the Figure.
A more useful application of the close request function is to display a question
dialog box asking the user to confirm the close operation. The following M-file
illustrates how to do this:
% my_closereq
% User-defined close request function
% to display a question dialog box
selection = questdlg('Close Specified Figure?',...
'Close Request Function',...
'Yes','No','Yes');
switch selection,
case 'Yes',
delete(get(0,'CurrentFigure'))
case 'No'
return
end
Now assign this M-file to the CloseRequestFcn of a Figure:
set(figure_handle,'CloseRequestFcn','my_closereq')
To make this M-file your default close request function, set a default value on
the Root level:
set(0,'DefaultFigureCloseRequestFcn','my_closereq')
MATLAB then uses this setting for the CloseRequestFcn of all subsequently
created Figures.
Color
ColorSpec
Background color. This property controls the Figure window background color.
You can specify a color using a three-element vector of RGB values or one of
MATLAB’s predefined names. See ColorSpec for more information.
Colormap
m-by-3 matrix of RGB values
Figure colormap. This property is an m-by-3 array of red, green, and blue
(RGB) intensity values that define m individual colors. MATLAB accesses
2-141
Figure Properties
colors by their row number. For example, an index of 1 specifies the first RGB
triplet, an index of 2 specifies the second RGB triplet, and so on. Colormaps can
be any length (up to 256 only on MS-Windows and Macintosh), but must be
three columns wide. The default Figure colormap contains 64 predefined
colors.
Colormaps affect the rendering of Surface, Image, and Patch objects, but
generally do not affect other graphics objects. See colormap and ColorSpec for
more information.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Figure object. You
must define this property as a default value for Figures. For example, the
statement,
set(0,'DefaultFigureCreateFcn',...
'set(gcbo,''IntegerHandle'',''off'')')
defines a default value on the Root level that causes the created Figure to use
noninteger handles whenever you (or MATLAB) create a Figure. MATLAB
executes this routine after setting all properties for the Figure. Setting this
property on an existing Figure object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
CurrentAxes
handle of current Axes
Target Axes in this Figure. MATLAB sets this property to the handle of the
Figure’s current Axes (i.e., the handle returned by the gca command when this
Figure is the current Figure). In all Figures for which Axes children exist, there
is always a current Axes. The current Axes does not have to be the topmost
axes, and setting an Axes to be the CurrentAxes does not restack it above all
other Axes.
You can make an Axes current using the axes and set commands. For
example, axes(axes_handle) and set(gcf,'CurrentAxes',axes_handle)
both make the Axes identified by the handle axes_handle the current Axes. In
addition, axes(axes_handle) restacks the Axes above all other Axes in the
Figure.
2-142
Figure Properties
If a Figure contains no Axes, get(gcf,'CurrentAxes') returns the empty
matrix. Note that the gca function actually creates an Axes if one does not
exist.
CurrentCharacter
single character (read only)
Last key pressed. MATLAB sets this property to the last key pressed in the
Figure window. CurrentCharacter is useful for obtaining user input.
CurrentMenu
(Obsolete)
This property produces a warning message when queried. It has been
superseded by the Root CallbackObject property.
CurrentObject
object handle
Handle of current object. MATLAB sets this property to the handle of the object
that is under the current point (see the CurrentPoint property). This object is
the front-most object in the stacking order. You can use this property to
determine which object a user has selected. The function gco provides a
convenient way to retrieve the CurrentObject of the CurrentFigure.
CurrentPoint
two-element vector: [x-coordinate, y-coordinate]
Location of last button click in this Figure. MATLAB sets this property to the
location of the pointer at the time of the most recent mouse button press.
MATLAB updates this property whenever you press the mouse button while
the pointer is in the Figure window.
In addition, MATLAB updates CurrentPoint before executing callback
routines defined for the Figure WindowButtonMotionFcn and
WindowButtonUpFcn properties. This enables you to query CurrentPoint from
these callback routines. It behaves like this:
• If there is no callback routine defined for the WindowButtonMotionFcn or the
WindowButtonUpFcn, then MATLAB updates the CurrentPoint only when
the mouse button is pressed down within the Figure window.
• If there is a callback routine defined for the WindowButtonMotionFcn, then
MATLAB updates the CurrentPoint just before executing the callback. Note
that the WindowButtonMotionFcn executes only within the Figure window
unless the mouse button is pressed down within the window and then held
down while the pointer is moved around the screen. In this case, the routine
2-143
Figure Properties
executes (and the CurrentPoint is updated) anywhere on the screen until
the mouse button is released.
• If there is a callback routine defined for the WindowButtonUpFcn, MATLAB
updates the CurrentPoint just before executing the callback. Note that the
WindowButtonUpFcn executes only while the pointer is within the Figure
window unless the mouse button is pressed down initially within the
window. In this case, releasing the button anywhere on the screen triggers
callback execution, which is preceded by an update of the CurrentPoint.
The Figure CurrentPoint is updated only when certain events occur, as
previously described. In some situations, (such as when the
WindowButtonMotionFcn takes a long time to execute and the pointer is moved
very rapidly) the CurrentPoint may not reflect the actual location of the
pointer, but rather the location at the time when the WindowButtonMotionFcn
began execution.
The CurrentPoint is measured from the lower-left corner of the Figure
window, in units determined by the Units property.
The Root PointerLocation property contains the location of the pointer
updated synchronously with pointer movement. However, the location is
measured with respect to the screen, not a Figure window.
DeleteFcn
string
Delete Figure callback routine. A callback routine that executes when the
Figure object is deleted (e.g., when you issue a delete or a close command).
MATLAB executes the routine before destroying the object’s properties so
these values are available to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
Dithermap
m-by-3 matrix of RGB values
Colormap used for true-color data on pseudocolor displays. This property
defines a colormap that MATLAB uses to dither true-color CData for display on
pseudocolor (8-bit or less) displays. MATLAB maps each RGB color defined as
true-color CData to the closest color in the dithermap. The default Dithermap
contains colors that span the full spectrum so any color values map reasonably
well.
2-144
Figure Properties
However, if the true-color data contains a wide range of shades in one color, you
may achieve better results by defining your own dithermap. See the
DithermapMode property.
DithermapMode
auto | {manual}
MATLAB generated dithermap. In manual mode, MATLAB uses the colormap
defined in the Dithermap property to display direct color on pseudocolor
displays. When DithermapMode is auto, MATLAB generates a dithermap based
on the colors currently displayed. This is useful if the default dithermap does
not produce satisfactory results.
The process of generating the dithermap can be quite time consuming and is
repeated whenever MATLAB re-renders the display (e.g., when you add a new
object or resize the window). You can avoid unnecessary regeneration by
setting this property back to manual and save the generated dithermap (which
MATLAB loaded into the Dithermap property).
FixedColors
m-by-3 matrix of RGB values (read only)
Non-colormap colors. Fixed colors define all colors appearing in a Figure
window that are not obtained from the Figure colormap. These colors include
axis lines and labels, the color of Line, Text, Uicontrol, and Uimenu objects, and
any colors that you explicitly define, for example, with a statement like:
set(gcf,'Color',[0.3 0.7 0.9]).
Fixed color definitions reside in the system color table and do not appear in the
Figure colormap. For this reason, fixed colors can limit the number of
simultaneously displayed colors if the number of fixed colors plus the number
of entries in the Figure colormap exceed your system’s maximum number of
colors.
(See the Root ScreenDepth property for information on determining the total
number of colors supported on your system. See the MinColorMap and
ShareColors properties for information on how MATLAB shares colors
between applications.)
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
2-145
Figure Properties
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provides a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Figure can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Figure. If HiTest is off, clicking
on the Figure sets the CurrentObject to the empty matrix.
2-146
Figure Properties
IntegerHandle
{on} | off
Figure handle mode. Figure object handles are integers by default. When
creating a new Figure, MATLAB uses the lowest integer that is not used by an
existing Figure. If you delete a Figure, its integer handle can be reused.
If you set this property to off, MATLAB assigns nonreusable real-number
handles (e.g., 67.0001221) instead of integers. This feature is designed for
dialog boxes where removing the handle from integer values reduces the
likelihood of inadvertently drawing into the dialog box.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Figure callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn,
KeyPressFcn, WindowButtonDownFcn, WindowButtonMotionFcn, and
WindowButtonUpFcn are affected by the Interruptible property. MATLAB
checks for events that can interrupt a callback routine only when it encounters
a drawnow, figure, getframe, or pause command in the routine. See the
BusyAction property for related information.
InvertHardcopy
{on} | off
Change hardcopy to black objects on white background. This property affects
only printed output. Printing a Figure having a background color (Color
property) that is not white results in poor contrast between graphics objects
and the Figure background and also consumes a lot of printer toner.
When InvertHardCopy is on, MATLAB eliminates this effect by changing the
color of the Figure and Axes to white and the axis lines, tick marks, axis labels,
etc., to black. Lines, Text, and the edges of Patches and Surfaces may be
changed depending on the print command options specified.
If you set InvertHardCopy to off, the printed output matches the colors
displayed on the screen.
See print for more information on printing MATLAB Figures.
KeyPressFcn
string
Key press callback function. A callback routine invoked by a key press occurring
in the Figure window. You can define KeyPressFcn as any legal MATLAB
expression or the name of an M-file.
2-147
Figure Properties
The callback routine can query the Figure’s CurrentCharacter property to
determine what particular key was pressed and thereby limit the callback
execution to specific keys.
The callback routine can also query the Root PointerWindow property to
determine in which Figure the key was pressed. Note that pressing a key while
the pointer is in a particular Figure window does not make that Figure the
current Figure (i.e., the one referred by the gcf command).
MenuBar
none | {figure}
Enable-disable Figure menu bar. This property enables you to display or hide
the menu bar placed at the top of a Figure window. The default (figure) is to
display the menu bar.
Note that on Macintosh systems, the menu bar for the active window appears
across the top of the screen. Menu bars are not displayed across the top of the
Figure window as they are on X-Windows and MS-Windows systems, and only
one window’s menu bar is visible at any given time.
This property affects only built in menus. Menus defined with the uimenu
command are not affected by this property.
MinColormap
scalar (default = 64)
Minimum number of color table entries used. This property specifies the
minimum number of system color table entries used by MATLAB to store the
colormap defined for the Figure (see the ColorMap property). In certain
situations, you may need to increase this value to ensure proper use of colors.
For example, suppose you are running color-intensive applications in addition
to MATLAB and have defined a large Figure colormap (e.g., 150 to 200 colors).
MATLAB may select colors that are close but not exact from the existing colors
in the system color table because there are not enough slots available to define
all the colors you specified.
To ensure MATLAB uses exactly the colors you define in the Figure colormap,
set MinColorMap equal to the length of the colormap:
set(gcf,'MinColormap',length(get(gcf,'ColorMap')))
Note that the larger the value of MinColorMap, the greater the likelihood other
windows (including other MATLAB Figure windows) will display in false
colors.
2-148
Figure Properties
Name
string
Figure window title. This property specifies the title displayed in the Figure
window. By default, Name is empty and the Figure title is displayed as
Figure No. 1, Figure No. 2, and so on. When you set this parameter to a
string, the Figure title becomes Figure No. 1: <string>. See the NumberTitle
property.
NextPlot
{add} | replace | replacechildren
How to add next plot. NextPlot determines which Figure MATLAB uses to
display graphics output. If the value of the current Figure is:
• add — use the current Figure to display graphics (the default).
• replace — reset all Figure properties, except Position, to their defaults and
delete all Figure children before displaying graphics (equivalent to clf
reset).
• replacechildren — remove all child objects, but do not reset Figure
properties (equivalent to clf).
The newplot function provides an easy way to handle the NextPlot property.
Also see the NextPlot property of Axes and the Using MATLAB Graphics
manual.
NumberTitle
{on} | off
Figure window title number. This property determines whether the string
Figure No. N (where N is the Figure number) is prefixed to the Figure window
title. See the Name property.
PaperOrientation
{portrait} | landscape
Horizontal or vertical paper orientation. This property determines how printed
Figures are oriented on the page. portrait orients the longest page dimension
vertically; landscape orients the longest page dimension horizontally. See the
orient command for more detail.
PaperPosition
four-element rect vector
Location on printed page. A rectangle that determines the location of the Figure
on the printed page. Specify this rectangle with a vector of the form
rect = [left, bottom, width, height]
where left specifies the distance from the left side of the paper to the left side
of the rectangle and bottom specifies the distance from the bottom of the page
2-149
Figure Properties
to the bottom of the rectangle. Together these distances define the lower-left
corner of the rectangle. width and height define the dimensions of the
rectangle. The PaperUnits property specifies the units used to define this
rectangle.
PaperPositionMode auto | {manual}
WYSIWYG printing of Figure. In manual mode, MATLAB honors the value
specified by the PaperPosition property. In auto mode, MATLAB prints the
Figure the same size as it appears on the computer screen, centered on the
page.
PaperSize
[width height] (read only)
Paper size. This property contains the size of the current PaperType, measured
in PaperUnits. See PaperType to select standard paper sizes.
PaperType
Select a value from the following table
Selection of standard paper size. This property sets the PaperSize to the one of
the following standard sizes:
2-150
Property Value
Size (Width x Height)
usletter (default)
8.5-by-11 inches
uslegal
11-by-14 inches
tabloid
11-by-17 inches
A0
841-by-1189mm
A1
594-by-841mm
A2
420-by-594mm
A3
297-by-420mm
A4
210-by-297mm
A5
148-by-210mm
B0
1029-by-1456mm
B1
728-by-1028mm
Figure Properties
Property Value
Size (Width x Height)
B2
514-by-728mm
B3
364-by-514mm
B4
257-by-364mm
B5
182-by-257mm
arch-A
9-by-12 inches
arch-B
12-by-18 inches
arch-C
18-by-24 inches
arch-D
24-by-36 inches
arch-E
36-by-48 inches
A
8.5-by-11 inches
B
11-by-17 inches
C
17-by-22 inches
D
22-by-34 inches
E
34-by-43 inches
Note that you may need to change the PaperPosition property in order to
properly position the printed Figure on the new paper size. One solution is to
use normalized PaperUnits which enables MATLAB to automatically size the
Figure to occupy the same relative amount of the printed page, regardless of
the paper size.
PaperUnits
normalized | {inches} | centimeters |
points
Hardcopy measurement units. This property specifies the units used to define
the PaperPosition and PaperSize properties. All units are measured from the
lower-left corner of the page. normalized units map the lower-left corner of the
page to (0, 0) and the upper-right corner to (1.0, 1.0). inches, centimeters, and
points are absolute units (one point equals 1/72 of an inch).
2-151
Figure Properties
If you change the value of PaperUnits, it is good practice to return it to its
default value after completing your computation so as not to affect other
functions that assume PaperUnits is set to the default value.
Parent
handle
Handle of Figure’s parent. The parent of a Figure object is the Root object. The
handle to the Root is always 0.
Pointer
crosshair | {arrow} | watch | topl |
topr | botl | botr | circle | cross |
fleur | left | right | top | bottom |
fullcrosshair | ibeam | custom
Pointer symbol selection. This property determines the symbol used to indicate
the pointer (cursor) position in the Figure window. Setting Pointer to custom
allows you to define your own pointer symbol. See the PointerShapeCData
property for more information. See also the Using MATLAB Graphics manual.
PointerShapeCData 16-by-16 matrix
User-defined pointer. This property defines the pointer that is used when you
set the Pointer property to custom. It is a 16-by-16 element matrix defining the
16-by-16 pixel pointer using the following values:
• 1 – color pixel black
• 2 – color pixel white
• NaN – make pixel transparent (underlying screen shows through)
Element (1,1) of the PointerShapeCData matrix corresponds to the upper-left
corner of the pointer. Setting the Pointer property to one of the predefined
pointer symbols does not change the value of the PointerShapeCData.
Computer systems supporting 32-by-32 pixel pointers fill only one quarter of
the available pixmap.
PointerShapeHotSpot2-element vector
Pointer active area. A two-element vector specifying the row and column
indices in the PointerShapeCData matrix defining the pixel indicating the
pointer location. The location is contained in the CurrentPoint property and
the Root object’s PointerLocation property. The default value is element (1,1),
which is the upper-left corner.
2-152
Figure Properties
Position
four-element vector
Figure position. This property specifies the size and location on the screen of
the Figure window. Specify the position rectangle with a four-element vector of
the form:
rect = [left, bottom, width, height]
where left and bottom define the distance from the lower-left corner of the
screen to the lower-left corner of the Figure window. width and height define
the dimensions of the window. See the Units property for information on the
units used in this specification. The left and bottom elements can be negative
on systems that have more than one monitor.
You can use the get function to obtain this property and determine the position
of the Figure and you can use the set function to resize and move the Figure to
a new location.
Renderer
painters | zbuffer
Rendering method used for screen and printing. This property enables you to
select the method used to render MATLAB graphics. The choices are:
• painters – MATLAB’s original rendering method is faster when the Figure
contains only simple or small graphics objects.
• zbuffer – MATLAB draws graphics object faster and more accurately
because objects are colored on a per pixel basis and MATLAB renders only
those pixels that are visible in the scene (thus eliminating front-to-back
sorting errors). Note that this method can consume a lot of system memory
if MATLAB is displaying a complex scene.
• OpenGL – OpenGL is a renderer that is available on many computer systems.
This renderer is generally faster than painters or zbuffer and in some cases
enables MATLAB to access graphics hardware that is available on some
systems.
Using the
OpenGL
Renderer
The Figure Renderer property supports a new value that enables MATLAB to
use OpenGL as the renderer. The command to enable OpenGL on the current
Figure is:
set(gcf,'Renderer','OpenGL')
2-153
Figure Properties
OpenGL increases performance for most 2-D and 3-D graphs drawn with
MATLAB.
Hardware Vs. Software OpenGL Implementations
There are two kinds of OpenGL implementations – hardware and software.
The hardware implementation makes use of special graphics hardware to
increase performance and is therefore significantly faster than the software
version. Many computers have this special hardware available as an option or
may come with this hardware right out of the box.
Software implementations of OpenGL are much like the ZBuffer renderer that
is available on MATLAB version 5.0, however, OpenGL generally provides
superior performance to ZBuffer.
OpenGL Availability
OpenGL is available on all computers that MATLAB runs on with the
exception of VMS. MATLAB automatically finds hardware versions of OpenGl
if they are available. If the hardware version is not available, then MATLAB
uses the software version.
The software versions that are available on different platforms are:
• On UNIX and MacIntosh systems, MATLAB uses the software version of
OpenGL that is included in the MATLAB distribution.
• On MS-Windows NT 4.0, OpenGL is available as part of the operating
system.
• On MS-Windows 95, OpenGL is included in the Windows 95 OSR 2 release.
If you do not have this release, the libraries are available on the Microsoft ftp
site:
Microsoft version is available at the URL:
ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe
There is also a Silicon Graphics version of OpenGL for Windows 95 that is
available at the URL:
http://www.sgi.com
2-154
Figure Properties
Tested Hardware Versions
On MS-Windows platforms, there are many graphics boards that accelerate
OpenGL. The MathWorks has tested MATLAB on the AccelECLIPSE board
from AccelGraphics.
On UNIX platforms, The MathWorks has tested MATLAB on Sparc Ultra with
the Creator 3D board and Silicon Graphics computers running IRIX 6.4 or
newer.
Determining What Version You Are Using
To determine the version and vendor of the OpenGL library that MATLAB is
using on your system, type the following command at the MATLAB prompt:
feature GetOpenGLInfo
This command also returns a string of extensions to the OpenGL specification
that are available with the particular library MATLAB is using. This
information is helpful to The MathWorks so please include this information if
you need to report bugs.
OpenGL Vs. Other MATLAB Renderers
There are some difference between drawings created with OpenGL and those
created with the other renderers. The OpenGL specific differences include:
• OpenGL does not do colormap interpolation. If you create a Surface or Patch
using indexed color and interpolated face or edge coloring, OpenGL will
interpolate the colors through the RGB color cube instead of through the
colormap.
• OpenGL does not support the phong value for the FaceLighting and
EdgeLighting properties of Surfaces and Patches.
MATLAB issues a warning if you request nonsupported behavior.
Printing from OpenGL
When you print a Figure that was drawn with OpenGL, MATLAB switches to
the ZBuffer renderer to produce output, which has a resolution determined by
the print command’s −r option. This may cause flashing of the Figure as the
renderer changes.
2-155
Figure Properties
Implementations of OpenGL Tested by TMW
The following hardware versions have been tested:
• AccelECLIPSE by AccelGraphics
• Sol2/Creator 3D
• SGI
The following software versions have been tested:
• Mesa
• CosmoGL
• Microsoft’s Windows 95 implementation
• NT 4.0
RendererMode
{auto} | manual
Automatic, or user selection of Renderer. This property enables you to specify
whether MATLAB should choose the Renderer based on the contents of the
figure window, or whether the Renderer should remain unchanged.
When the RendererMode property is set to auto, MATLAB selects the rendering
method for printing as well as for screen display based on the size and
complexity of the graphics objects in the Figure.
For printing, MATLAB switches to zbuffer at a greater scene complexity than
for screen rendering because printing from a Z-buffered Figure can be
considerably slower than one using the painters rendering method, and can
result in large PostScript files. However, the output does always match what is
on the screen. The same holds true for OpenGL, the output is the same as that
produced by the ZBuffer renderer – a bitmap with a resolution determined by
the print command’s −r option
When the RendererMode property is set to manual, MATLAB does not change
the Renderer, regardless of changes to the Figure contents.
Resize
{on} | off
Window resize mode. This property determines if you can resize the Figure
window with the mouse. on means you can resize the window, off means you
cannot. When Resize is off, the Figure window does not display any resizing
controls (such as boxes at the corners) to indicate that it cannot be resized.
2-156
Figure Properties
ResizeFcn
string
Window resize callback routine. MATLAB executes the specified callback
routine whenever you resize the Figure window. You can query the Figure’s
Position property to determine the new size and position of the Figure
window. During execution of the callback routine, the handle to the Figure
being resized is accessible only through the Root CallbackObject property,
which you can query using gcbo.
You can use ResizeFcn to maintain a GUI layout that is not directly supported
by MATLAB’s Position/Units paradigm.
For example, consider a GUI layout that maintains an object at a constant
height in pixels and attached to the top of the Figure, but always matches the
width of the Figure. The following ResizeFcn accomplishes this; it keeps the
Uicontrol whose Tag is 'StatusBar' 20 pixels high, as wide as the Figure, and
attached to the top of the Figure. Note the use of the Tag property to retrieve
the Uicontrol handle, and the gcbo function to retrieve the Figure handle. Also
note the defensive programming regarding Figure Units, which the callback
requires to be in pixels in order to work correctly, but which the callback also
restores to their previous value afterwards:
u = findobj('Tag','StatusBar');
fig = gcbo;
old_units = get(fig,'Units');
set(fig,'Units','pixels');
figpos = get(fig,'Position');
upos = [0, figpos(4) - 20, figpos(3), 20];
set(u,'Position',upos);
set(fig,'Units',old_units);
You can change the Figure Position from within the ResizeFcn callback;
however the ResizeFcn is not called again as a result.
Note that the print command can cause the ResizeFcn to be called if the
PaperPositionMode property is set to manual and you have defined a resize
function. If you do not want your resize function called by print, set the
PaperPositionMode to auto.
2-157
Figure Properties
Selected
on | off
Is object selected. This property indicates whether the Figure is selected. You
can, for example, define the ButtonDownFcn to set this property, allowing users
to select the object with the mouse.
SelectionHighlight {on} | off
Figures do not indicate selection.
SelectionType
{normal} | extend | alt | open
(this property is read only)
Mouse selection type. MATLAB maintains this property to provide information
about the last mouse button press that occurred within the Figure window.
This information indicates the type of selection made. Selection types are
actions that are generally associated with particular responses from the user
interface software (e.g., single clicking on a graphics object places it in move or
resize mode; double-clicking on a filename opens it, etc.).
The physical action required to make these selections varies on different
platforms. However, all selection types exist on all platforms.
Selection Type
MS-Windows
X-Windows
Macintosh
Normal
Click left
mouse button
Click left
mouse button
Click mouse
button
Extend
Shift - click left
mouse button or
click both left
and right mouse
buttons
Shift - click left
Shift - click
mouse button
or click
middle mouse
button
mouse button
Control - click
left mouse
button or click
right mouse
button
Control - click
Option - click
left mouse
button
or click
right mouse
button
mouse button
Double click any
mouse button
Double click any
mouse button
Double click
mouse button
Alternate
Open
2-158
Figure Properties
Note that the ListBox style of Uicontrols set the Figure SelectionType
property to normal to indicate a single mouse click or to open to indicate a
double mouse click.
ShareColors
{on} | off
Share slots in system colortable with like colors. This property affects the way
MATLAB stores the Figure colormap in the system color table. By default,
MATLAB looks at colors already defined and uses those slots to assign pixel
colors. This leads to an efficient use of color resources (which are limited on
systems capable of displaying 256 or less colors) and extends the number of
Figure windows that can simultaneously display correct colors.
However, in situations where you want to change the Figure colormap quickly
without causing MATLAB to re-render the displayed graphics objects, you
should disable color sharing (set ShareColors to off). In this case, MATLAB
can swap one colormap for another without changing pixel color assignments
since all the slots in the system color table used for the first colormap are
replaced with the corresponding color in the second colormap. (Note that this
applies only in cases where both colormaps are the same length and where the
computer hardware allows user modification of the system color table.)
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines.
For example, suppose you want to direct all graphics output from an M-file to
a particular Figure, regardless of user actions that may have changed the
current Figure. To do this, identify the Figure with a Tag:
figure('Tag','Plotting Figure')
Then make that Figure the current Figure before drawing by searching for the
Tag with findobj:
figure(findobj('Tag','Plotting Figure'))
2-159
Figure Properties
Type
string (read only)
Object class. This property identifies the kind of graphics object. For Figure
objects, Type is always the string 'figure'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Figure. Assign this property the handle of a
Uicontextmenu object created in the Figure. Use the uicontextmenu function
to create the context menu. MATLAB displays the context menu whenever you
right-click over the Figure (Control-click on Macintosh systems).
Units
{pixels} | normalized | inches |
centimeters | points | character
Units of measurement. This property specifies the units MATLAB uses to
interpret size and location data. All units are measured from the lower-left
corner of the window.
• normalized units map the lower-left corner of the Figure window to (0,0) and
the upper-right corner to (1.0,1.0).
• inches, centimeters, and points are absolute units (one point equals 1/72
of an inch).
• The size of a pixel depends on screen resolution.
• Character units are defined by characters from the default system font; the
width of one character is the width of the letter x, the height of one character
is the distance between the baselines of two lines of text.
This property affects the CurrentPoint and Position properties. If you change
the value of Units, it is good practice to return it to its default value after
completing your computation so as not to affect other functions that assume
Units is set to the default value.
When specifying the units as property/value pairs during object creation, you
must set the Units property before specifying the properties that you want to
use these units.
UserData
matrix
User specified data. You can specify UserData as any matrix you want to
associate with the Figure object. The object does not use this data, but you can
access it using the set and get commands.
2-160
Figure Properties
Visible
{on} | off
Object visibility. The Visible property determines whether an object is
displayed on the screen. If the Visible property of a Figure is off, the entire
Figure window is invisible.
WindowButtonDownFcnstring
Button press callback function. Use this property to define a callback routine
that MATLAB executes whenever you press a mouse button while the pointer
is in the Figure window. Define this routine as a string that is a valid MATLAB
expression or the name of an M-file. The expression executes in the MATLAB
workspace.
WindowButtonMotionFcnstring
Mouse motion callback function. Use this property to define a callback routine
that MATLAB executes whenever you move the pointer within the Figure
window. Define this routine as a string that is a valid MATLAB expression or
the name of an M-file. The expression executes in the MATLAB workspace.
WindowButtonUpFcn string
Button release callback function. Use this property to define a callback routine
that MATLAB executes whenever you release a mouse button. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
The button up event is associated with the Figure window in which the
preceding button down event occurred. Therefore, the pointer need not be in the
Figure window when you release the button to generate the button up event.
If the callback routines defined by WindowButtonDownFcn or
WindowButtonMotionFcn contain drawnow commands or call other functions
that contain drawnow commands and the Interruptible property is set to off,
the WindowButtonUpFcn may not be called. You can prevent this problem by
setting Interruptible to on.
WindowStyle
{normal} | modal
Normal or modal window behavior. When WindowStyle is set to modal, the
Figure window traps all keyboard and mouse events over all MATLAB
windows as long as they are visible. Windows belonging to applications other
than MATLAB are unaffected. Modal Figures remain stacked above all normal
Figures and the MATLAB command window. When multiple modal windows
2-161
Figure Properties
exist, the most recently created window keeps focus and stays above all other
windows until it becomes invisible, or is returned to WindowStyle normal, or is
deleted. At that time, focus reverts to the window that last had focus.
Figures with WindowStyle modal and Visible off do not behave modally until
they are made visible, so it is acceptable to hide a modal window instead of
destroying it when you want to reuse it.
You can change the WindowStyle of a Figure at any time, including when the
Figure is visible and contains children. However, on some systems this may
cause the Figure to flash or disappear and reappear, depending on the
windowing-system’s implementation of normal and modal windows. For best
visual results, you should set WindowStyle at creation time or when the Figure
is invisible.
Modal Figures do not display Uimenu children or built-in menus, but it is not
an error to create Uimenus in a modal Figure or to change WindowStyle to
modal on a Figure with Uimenu children. The Uimenu objects exist and their
handles are retained by the Figure. If you reset the Figure’s WindowStyle to
normal, the Uimenus are displayed.
Use modal Figures to create dialog boxes that force the user to respond without
being able to interact with other windows. Typing Control C at the MATLAB
prompt causes all Figures with WindowStyle modal to revert to WindowStyle
normal, allowing you to type at the command line.
2-162
fill
Purpose
2fill
Filled two-dimensional polygons
Syntax
fill(X,Y,C)
fill(X,Y,ColorSpec)
fill(X1,Y1,C1,X2,Y2,C2,...)
fill(...,'PropertyName',PropertyValue)
h = fill(...)
Description
The fill function creates colored polygons.
fill(X,Y,C) creates filled polygons from the data in X and Y with vertex color
specified by C. C is a vector or matrix used as an index into the colormap. If C is
a row vector, length(C) must equal size(X,2) and size(Y,2); if C is a column
vector, length(C) must equal size(X,1) and size(Y,1). If necessary, fill
closes the polygon by connecting the last vertex to the first.
fill(X,Y,ColorSpec) fills two-dimensional polygons specified by X and Y with
the color specified by ColorSpec.
fill(X1,Y1,C1,X2,Y2,C2,...) specifies multiple two-dimensional filled
areas.
fill(...,'PropertyName',PropertyValue) allows you to specify property
names and values for a Patch graphics object.
h = fill(...) returns a vector of handles to Patch graphics objects, one
handle per Patch object.
Remarks
If X or Y is a matrix, and the other is a column vector with the same number of
elements as rows in the matrix, fill replicates the column vector argument to
produce a matrix of the required size. fill forms a vertex from corresponding
elements in X and Y and creates one polygon from the data in each column.
The type of color shading depends on how you specify color in the argument list.
If you specify color using ColorSpec, fill generates flat-shaded polygons by
setting the Patch object’s FaceColor property to the corresponding RGB triple.
If you specify color using C, fill scales the elements of C by the values specified
by the Axes property CLim. After scaling C, C indexes the current colormap.
2-163
fill
If C is a row vector, fill generates flat-shaded polygons where each element
determines the color of the polygon defined by the respective column of the X
and Y matrices. Each Patch object’s FaceColor property is set to 'flat'. Each
row element becomes the CData property value for the n-th Patch object, where
n is the corresponding column in X or Y.
If C is a column vector or a matrix, fill uses a linear interpolation of the vertex
colors to generate polygons with interpolated colors. It sets the Patch graphics
object FaceColor property to 'interp' and the elements in one column become
the CData property value for the respective Patch object. If C is a column vector,
fill replicates the column vector to produce the required sized matrix.
Examples
Create a red octagon:
t = (1/16:1/8:1)'*2*pi;
x = sin(t);
y = cos(t);
fill(x,y,'r')
axis square
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−1
See Also
2-164
−0.8
−0.6
−0.4
−0.2
0
0.2
0.4
0.6
0.8
axis, caxis, colormap, ColorSpec, fill3, patch
1
fill3
Purpose
2fill3
Filled three-dimensional polygons
Syntax
fill3(X,Y,Z,C)
fill3(X,Y,Z,ColorSpec)
fill3(X1,Y1,Z1,C1,X2,Y2,Z2,C2,...)
fill3(...,'PropertyName',PropertyValue)
h = fill3(...)
Description
The fill3 function creates flat-shaded and Gouraud-shaded polygons.
fill3(X,Y,Z,C) fills three-dimensional polygons. X, Y, and Z triplets specify
the polygon vertices. If X, Y, or Z is a matrix, fill3 creates n polygons, where n
is the number of columns in the matrix. fill3 closes the polygons by
connecting the last vertex to the first when necessary.
C specifies color, where C is a vector or matrix of indices into the current
colormap. If C is a row vector, length(C) must equal size(X,2) and size(Y,2);
if C is a column vector, length(C) must equal size(X,1) and size(Y,1).
fill3(X,Y,Z,ColorSpec) fills three-dimensional polygons defined by X, Y,
and Z with color specified by ColorSpec.
fill3(X1,Y1,Z1,C1,X2,Y2,Z2,C2,...) specifies multiple filled
three-dimensional areas.
fill3(...,'PropertyName',PropertyValue) allows you to set values for
specific Patch properties.
h = fill3(...) returns a vector of handles to Patch graphics objects, one
handle per Patch.
Algorithm
If X, Y, and Z are matrices of the same size, fill3 forms a vertex from the
corresponding elements of X, Y, and Z (all from the same matrix location), and
creates one polygon from the data in each column.
If X, Y, or Z is a matrix, fill3 replicates any column vector argument to produce
matrices of the required size.
If you specify color using ColorSpec, fill3 generates flat-shaded polygons and
sets the Patch object FaceColor property to an RGB triple.
2-165
fill3
If you specify color using C, fill3 scales the elements of C by the Axes property
CLim, which specifies the color axis scaling parameters, before indexing the
current colormap.
If C is a row vector, fill3 generates flat-shaded polygons and sets the
FaceColor property of the Patch objects to 'flat'. Each element becomes the
CData property value for the respective Patch object.
If C is a column vector or a matrix, fill3 generates polygons with interpolated
colors and sets the patch object FaceColor property to 'interp'. fill3 uses a
linear interpolation of the vertex colormap indices when generating polygons
with interpolated colors. The elements in one column become the CData
property value for the respective Patch object. If C is a column vector, fill3
replicates the column vector to produce the required sized matrix.
Examples
Create four triangles with interpolated colors.
X
Y
Z
C
[0 1 1 2;1 1 2
[1 1 1 1;1 0 1
[1 1 1 1;1 0 1
[0.5000 1.0000
1.0000 0.5000
0.3330 0.3330
fill3(X,Y,Z,C)
2-166
=
=
=
=
2;0 0 1 1];
0;0 0 0 0];
0;0 0 0 0];
1.0000 0.5000;
0.5000 0.1667;
0.5000 0.5000];
fill3
See Also
axis, caxis, colormap, ColorSpec, fill, patch
2-167
findobj
Purpose
2findobj
Locate graphics objects
Syntax
h
h
h
h
Description
findobj locates graphics objects and returns their handles. You can limit the
=
=
=
=
findobj
findobj('PropertyName',PropertyValue,...)
findobj(objhandles,...)
findobj(objhandles,'flat','PropertyName',PropertyValue,...)
search to objects with particular property values and along specific branches of
the hierarchy.
h = findobj returns the handles of the Root object and all its descendants.
h = findobj('PropertyName',PropertyValue,...) returns the handles of
all graphics objects having the property PropertyName, set to the value
PropertyValue. You can specify more than one property/value pair, in which
case, findobj returns only those objects having all specified values.
h = findobj(objhandles,...) restricts the search to objects listed in
objhandles and their descendants.
h = findobj(objhandles,'flat','PropertyName',PropertyValue,...)
restricts the search to those objects listed in objhandles and does not search
descendants.
Remarks
findobj returns an error if a handle refers to a non-existent graphics object.
When you specify a property value, use the same format as get returns. For
example, you must use the RGB format to specify a color value and when the
value is a string, you must specify the entire character string.
When a graphics object is a descendant of more than one object identified in
objhandles, MATLAB searches the object each time findobj encounters its
handle. Therefore, implicit references to a graphics object can result in its
handle being returned multiple times.
Examples
Find all Line objects in the current Axes:
h = findobj(gca,'Type','line')
2-168
findobj
See Also
copyobj, gcf, gca, gcbo, gco, get, set
Graphics objects include:
axes, figure, image, light, line, patch, surface, text, uicontrol, uimenu
2-169
fplot
Purpose
2fplot
Plot a function between specified limits
Syntax
fplot('function',limits)
fplot('function',limits,LineSpec)
fplot('function',limits,tol)
fplot('function',limits,tol,LineSpec)
[x,Y] = fplot(...)
Description
fplot plots a function between specified limits. The function must be of the
form y = f(x), where x is a vector whose range specifies the limits, and y is a
vector the same size as x and contains the function’s value at the points in x
(see the first example). If the function returns more than one value for a given
x, then y is a matrix whose columns contain each component of f(x) (see the
second example).
fplot('function',limits) plots 'function' between the limits specified by
limits. limits is a vector specifying the x-axis limits ([xmin xmax]), or the xand y-axis limits, ([xmin xmax ymin ymax]).
fplot('function',limits,LineSpec) plots 'function' using the line
specification LineSpec. 'function' is a name of a MATLAB M-file or a string
containing the variable x.
fplot('function',limits,tol) plots 'function' using the relative error
tolerance tol (default is 2e–3). The maximum number of x steps is (1/tol)+1.
fplot('function',limits,tol,LineSpec) plots 'function' using the
relative error tolerance tol and a line specification that determines line type,
marker symbol, and color.
[x,Y] = fplot(...) returns the abscissas and ordinates for 'function' in x
and Y. No plot is drawn on the screen. You plot the function using plot(x,Y).
Remarks
fplot uses adaptive step control to produce a representative graph,
concentrating its evaluation in regions where the function’s rate of change is
the greatest.
2-170
fplot
Examples
Plot the hyperbolic tangent function from -2 to 2:
fplot('tanh',[-2 2])
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
Create an M-file, myfun, that returns a two column matrix:
function Y = myfun(x)
Y(:,1) = 200∗sin(x(:))./x(:);
Y(:,2) = x(:).^2;
Plot the function with the statement:
fplot('myfun',[–20 20]
2-171
fplot
400
350
300
250
200
150
100
50
0
−50
−20
See Also
2-172
−15
−10
−5
eval, feval, LineSpec, plot
0
5
10
15
20
frame2im
Purpose
2frame2im
Convert movie frame to indexed image
Syntax
[X,Map] = frame2im(F)
Description
[X,Map] = frame2im(F) converts the single movie frame F into the indexed
image X and associated colormap Map. A single column of a movie matrix is one
movie frame. The functions getframe and im2frame create a movie frame.
See Also
capture, im2frame, movie
2-173
frame2im
2-174
frameedit
Purpose
Create and edit printframes for Simulink block diagrams
Syntax
frameedit
frameedit filename
Description
frameedit invokes the printframe editor, a graphical user interface you use to
2frameedit
create printframes for Simulink block diagrams. Printframes are borders
containing information relevant to the Simulink block diagram, such as the
name of the block diagram. After creating a printframe, you can use Simulink
to print a block diagram with a printframe. See the sample below.
frameedit opens the PrintFrame Editor window with a new file.
frameedit filename opens the PrintFrame Editor window with the specified
filename, where filename is a .fig file you previously created and saved using
frameedit.
Printframe
borders
Engine Division
Advanced Design Group
Simulink
block
diagram
engine/Throttle & Manifold
1 of 3
Page
margins
Information included in printframe
175
frameedit
Printframe Editor Interface
Remarks
Type frameedit at the MATLAB prompt. The PrintFrame Editor window
appears. Below is an illustration of the PrintFrame Editor window including
the default printframe that the window opens with.
File menu for page setup, and saving and opening printframes
Information included in cells
Close box
Buttons to create and edit borders
List box and button for adding
information in cells, such as
text or the date
Buttons for aligning information
within a cell
Rows
Zoom in on
selected cell
Zoom out
Cells – areas where you can include information
The default printframe has two rows. The top row consists of one cell and the
bottom row has two cells. Default information (entries) appears in the cells, as
shown below. You can keep this information, or remove the default entries and
176
frameedit
add your own. You can also add new rows and cells and then add information
in them.
Default printframe includes
variable entries for:
The Simulink block diagram
%<blockdiagram>
The page number of the
Simulink block diagram
The full system name for the
Simulink block diagram
%<fullsystemname>
%<page>
Summary of the Printframe Process
Below are the basic steps to create and use printframes. Subsequent sections
provide details for performing each step.
• Design the printframe and specify the page setup.
• Create printframe borders (rows and cells), and then resize them as needed.
• Add information to the cells and edit it as needed.
• Save the printframe as a .fig file.
• Print a Simulink block diagram with the printframe.
Where to Start – Designing Printframes
Before you begin creating a printframe using the printframe editor, determine
the type of information you want to include in it and how you want the
information to appear.
In a printframe, you can include variable information that is automatically
supplied at the time of printing, such as the date the Simulink block diagram
is being printed, or fixed information, such as the name and address of your
organization.
177
frameedit
You can design a printframe you intend to use for one particular Simulink
block diagram, or you can design a more generic printframe for printing with
different Simulink block diagrams.
Specifying the Printframe Page Setup
After you have an idea of the design of your printframe, specify the page setup
for the printframe. In the PrintFrame Editor window, select Page Setup from
the File menu.
The PrintFrame Page Setup dialog box appears. In the dialog box, specify:
• Paper Type – for example, usletter
• Paper Orientation – portrait or landscape
• Margins for the printframe; note that you can select the Units in which to
specify the margins
Click Apply to see the effects of the changes you made. Then click OK to close
the dialog box.
178
frameedit
Always begin creating a new printframe with PrintFrame Page Setup. If
instead you begin by creating borders and adding information, and then later
change the page setup, you might have to correct the borders and placement of
the information. For example, if you add information to cells and then change
the page setup paper orientation from landscape to portrait, the information
you added might not fit in the cells, given the new orientation.
Note:
Creating Borders (Rows and Cells)
After setting up the page, specify borders (cells) in which the Simulink block
diagram and information will be placed. In the printframe editor, you create
borders using rows, and then create cells within the rows.
You can add and remove rows in a printframe. First, click within an existing
row to select it. If a row consists of multiple cells, click in any of the cells in the
row to select that row.
When a row is selected, handles appear on all four corners. If handles appear
on only two corners, you clicked on and only selected the line, not the row.
Cell (or row) selected - note
4 handles and arrow cursor
Line selected - note 2 handles
and double-arrow cursor
After selecting a row, click the add row button to create a new row. The new
row appears above the row you selected. To remove a row, select the row and
click the delete row button.
To create multiple cells within a row, select the row. Then click the split cell
button. The row is split into two cells. If the row already consists of more than
one cell, you can split any of the cells into two cells. First select the cell by
clicking within in it. Then click the split cell button – the cell splits. To remove
a cell, first select the cell and then click the delete cell button.
179
frameedit
Resizing Rows and Cells
To change the dimensions of a row or cell, drag one side of the row or cell. More
specifically, click on the line you want to move – a handle appears on both ends
of the line and the cursor becomes a double-arrow cursor. Then drag the line to
the new location. For example, to make a row taller, click on the top line that
forms the row. Then drag the line up and the height of the row increases.
Note that the overall size of the printframe is fixed so that when you change
the dimensions of one element, the dimensions of the element next to it change
in an inverse direction. For example, if you drag the top line of a row to make
it taller, the row above it becomes shorter by the same amount.
Adding Information to Cells
First select the cell where you want to add the information. Then, from the Fill
list box, select the type of information you want to add. Finally, click the Add
button – an edit box containing that information appears in the cell. (The edit
box for your platform might look slightly different from those in the figure
below.)
Select item from Fill list box.
Click Add button.
For Text, an empty
edit box appears.
For variable information, the
variable’s name appears in the
edit box. In this example, the
variable information is Date.
If you click the Add button and nothing happens, it might be because you
did not select a cell first.
Note:
For Text, type the text you want to include in that cell, for example, the name
of your organization. Press the Enter key (or Return key on a Macintosh) if you
want to type additional text on a new line. Note that you can type special
characters, for example, Greek symbols, using embedded TeX sequences – see
the Text command String property for a list of allowable sequences.
180
frameedit
All of the items in the Fill list box, except for the Text item, are for adding
variable information, which is supplied at the time of printing. When you print
a Simulink block diagram with a printframe that contains variable
information, the information for that particular Simulink block diagram prints
in those fields.
The variable entries you can include are:
• Block Diagram – This entry indicates where the Simulink block diagram is
to be printed. Block Diagram is a mandatory entry. If Block Diagram is not
in one of the cells, you cannot save the printframe and therefore cannot print
a Simulink block diagram with it.
• Date – The date that the Simulink block diagram and printframe are
printed, in dd-mmm-yyyy format, for example, 05-Dec.-1997.
• Time – The time that the Simulink block diagram and printframe are
printed, in hh:mm format, for example, 14:22.
• Page Number – The page of the Simulink block diagram being printed.
• Total Pages – The total number of pages being printed for the Simulink
block diagram, which depends on the Simulink printing options specified.
• System Name – The name of the Simulink block diagram being printed.
• Full System Name – The name of the Simulink block diagram being printed,
including its position from the root system through the current system, for
example, engine/Throttle & Manifold.
• File Name – The filename of the Simulink block diagram, for example,
engine.mdl.
• Full File Name – The full path and filename for the Simulink block diagram,
for example, \\matlab\toolbox\simulink\simdemos\engine.mdl.
Adding the system name or filename does not mean that you can specify
a Simulink system or filename in the printframe editor. It means that when
you print a block diagram from Simulink and specify that it print with a
printframe, the system name or filename of that Simulink block diagram
prints in the specified cell of the printframe.
Note:
181
frameedit
When you add a variable entry, a percent sign, %, is automatically included to
identify the entry as variable information rather than a text string, and the
type of entry, for example, page, appears in angle brackets, < >. The entry
consists of the entire string, for example, %<page>, for Page Number.
You can include multiple entries in one cell. Select the cell and then add
another item from the list box. The new entry is added after the last entry in
that cell. You can also type descriptive text to any of the variable entries
without using the Text item in the Fill list box – type text in the edit box before
or after an entry and the text prints with the block diagram.
You cannot include multiple entries or text in the cell that contains the
block diagram entry – %<blockdiagram> must be the only information in that
cell. If there is any other information in that cell, you cannot save the
printframe and therefore cannot print it with a Simulink block diagram.
Note:
Zooming
While using the printframe editor, you might need to zoom in on an area to
better see the information you added. Click in the cell you want to zoom in on
and then click the zoom in button. The area is magnified. Click the zoom in
button repeatedly to continue zooming in.
Zoom in
Zoom out
To zoom out, which reduces the magnification in an area, click the zoom out
button. Click the zoom out button repeatedly to continue zooming out.
Aligning the Information in a Cell
To align the information within a cell, click within the cell to select it and then
click on one of the Align buttons. L aligns the information with the left edge of
the cell, C centers the information within the cell, and R aligns the information
with the right edge of the cell. Alignment does not apply to the cell that
contains the %<blockdiagram> entry – the Simulink block diagram is
automatically scaled and centered to fit in that cell at the time of printing.
182
frameedit
Editing Text Strings
You can change text you typed in a cell:
1 Double-click on the information you want to edit.
An edit box appears around all of the information in that cell.
2 Click at the start of the text you want to change and drag to the end of the
text to be changed. This highlights the text.
3 Type the replacement text. It automatically replaces the highlighted text.
Be careful not to edit the text of a variable entry, because then the variable
information will not print. For example, if you accidentally remove the %
from the %<page> entry, the text <page> will print instead of the actual page
number.
4 Click somewhere outside of the edit box to end editing mode.
Removing and Copying Entries
You can cut, copy, paste, and delete an entry:
1 Double-click the cursor on the information you want to remove or copy.
An edit box appears around all of the information in that cell.
2 Click at the start of the entry you want to edit and drag to the end of that
entry. This highlights the entry.
For variable information, be sure to include the entire string, for example,
%<page>.
Note that for Windows, you can select all of the entries in a cell by
right-clicking on the information and choosing Select All from the pop-up
menu.
183
frameedit
3 Use the standard editing techniques for your platform to cut, copy or delete
the highlighted information.
- For Windows, right-click in the edit box and select Cut, Copy, or Delete
from the pop-up menu.
- For Macintosh, press the command+X keys to cut, command+C keys to
copy, or the Delete key to delete.
- For UNIX, highlighting the information automatically copies it to the
clipboard. If you want to remove it, press the Delete key.
If you make a mistake, use your platform’s standard undo technique. For
example for Windows, right-click in the edit box and select Undo from the
pop-up menu.
4 If you cut or copied the information to the clipboard and want to paste it,
double-click on the entry where you want to paste it and position the cursor
at the new location in that edit box. Then use the standard paste technique
for your platform.
- For Windows, right-click at the new location and select Paste from the
pop-up menu.
- For Macintosh, press the command+V keys at the new location.
- For UNIX, click at the new location and then click the middle mouse
button.
5 Click somewhere outside of the edit box to end editing mode.
Changing the Font Characteristics
You can change the font characteristics for the information in any cell.
Specifically, you can specify the font size, style, color, and family.
184
frameedit
1 Right-click on the information in the cell.
The information in the cell is selected and the pop-up menu for changing
font characteristics appears.
If this pop-up menu does not appear it is because you were in edit mode. To
get the font pop-up menu, click somewhere outside of the edit box
surrounding the information and then right-click.
2 Select an item from the pop-up menu. Choose Properties if you want to
change the font family or if you want to change multiple characteristics at
once.
Note that you can also select String from the pop-up menu, which allows
you to edit the text string.
3 Select the new font characteristic(s) for that cell. For example, for Font Size,
select the new size from its pop-up menu.
Note that changing the font characteristics for the %<blockdiagram> entry
is not relevant and does nothing.
Saving and Opening Printframes
You must save a printframe in order to print a Simulink block diagram with
that printframe. To save a printframe, select Save As from the File menu. Type
a name for the printframe in the File name edit box. Click the Save button and
the printframe is saved as a .fig file. A .fig file is a binary file used for
printframes.
You can open a saved printframe in the printframe editor, make changes to it,
and save it under the same or a different name. To open an existing printframe,
select Open from the File menu and then select the printframe you want to
open. All printframes are .fig files. Alternatively, you can open a printframe
from the MATLAB prompt: type frameedit <filename> and the printframe
editor opens with the printframe file you specified.
185
frameedit
Closing the Printframe Editor
To close the PrintFrame Editor window, click the close box in the upper right
corner, or select Close from the File menu.
Printing Simulink Block Diagrams with Printframes
When using Simulink, you can print a block diagram with the printframe.
Select Print from the Simulink File menu.
Print Model dialog box for Windows platform – the dialog box for your platform might look slightly different
Type the path and
filename of the
printframe you want
the block diagram to
print with,
or
Check this box to print
the block diagram
with a printframe.
186
click the ... button and
then select the
printframe file.
frameedit
In the Print Model dialog box:
1 Check the Frame box.
2 Supply the filename for the printframe you want to use. Either type the path
and filename directly in the edit box, or click the ... button and select the
printframe file you saved using the printframe editor.
Note that the default printframe filename, sldefaultframe.fig, appears in
the filename edit box until you specify a different filename.
3 Specify other printing options in the Print dialog box. For example, for
Windows, specify options under Properties.
Specify the paper orientation for printing the way you normally would.
The paper orientation you specified in the printframe editor’s PrintFrame
Page Setup dialog box is not the same as the paper orientation used for
printing. For example, assume you specified a landscape-oriented printframe
in the printframe editor. If you want the printed page to have a landscape
orientation, you must specify that at the time of printing. For example, for
Windows, click the Properties button in the Simulink Print Model dialog
box, and for Page Setup, specify the Orientation as Landscape.
Note:
4 Click OK in the Print dialog box.
The Simulink block diagram prints with the printframe you specified.
187
frameedit
Examples
This example uses a Simulink demo engine model. It involves two parts – first
creating a printframe, and then printing the engine model with that
printframe. The final result is:
Fixed information included in printframe
.75 inch
page
margins
Engine Division
Advanced Design Group
Simulink
block
diagram
Printframe
borders
engine/Throttle & Manifold
1 of 3
Variable information included in printframe
Create the Printframe
1 At the MATLAB prompt, type frameedit.
The PrintFrame Editor window appears.
2 Set up the page:
a Select Page Setup from the File menu.
The PrintFrame Page Setup dialog box opens.
b For Paper Type, select a size that is appropriate for your printer.
188
frameedit
c
For this example, keep the Paper Orientation as Landscape and the
Margins set to .75 inches.
d Click the OK button.
The dialog box closes. If you changed the Paper Type, the printframe you
see in the PrintFrame Editor window will reflect your change.
3 Add a row at the top.
a Click within the upper row in the printframe – this is the row that
contains the %<blockdiagram> entry.
Be sure that handles appear on all four corners of the row.
b Click the add row button.
A new row appears at the top, above the row you selected.
4 Make the new row shorter.
a Click on the horizontal line that separates the top row (the row you just
added) from the row beneath it (the row containing the %<blockdiagram>
entry).
Be sure that only two handles appear, one at each end of the line. If you
see four handles in either row, click directly on the horizontal line and the
other two handles disappear.
b Drag the line up until the top row is about the same height as the row at
the bottom of the printframe.
5 Add information in the top row.
a Click within the top row (the row you just added).
b Select Text from the Fill drop-down menu.
c
Click the Add button.
An edit box appears in the cell.
d Type Engine Division, press the Enter key to advance the cursor to the
next line, and then type Advanced Design Group.
Click the zoom in button if you need to magnify the entry.
e Click outside of the edit box to end editing mode.
189
frameedit
6 In the left cell of the bottom row, align the information on the left.
a Click the zoom out button if you need to.
b Click within the left cell of the bottom row to select it.
c
Click the L button.
The entry moves to the left.
7 Make the information in the left cell of the bottom row appear in bold.
a Right-click on the entry in the cell.
b Select Font Style from the pop-up menu.
If the pop-up menu for font properties does not appear, you are in editing
mode. Click outside of the edit box to end editing mode and then
right-click on the text to access the pop-up menu.
c
From the Font Style pop-up menu, select bold.
The entry in the cell appears in bold and the information will appear in bold
when the printframe is printed with a Simulink diagram.
8 Add the total number of pages to the right cell in the bottom row.
a Click within the cell to select it.
b Add the total pages entry: select Total Pages from the Fill drop-down
menu and click the Add button.
The %<npages> entry appears after the %<page> entry. If you need to,
zoom in to see the entry.
c
Add the text of after the page number entry: click the cursor after the
%<page> entry, and then type of (type a space before and after the word).
The information in the cell now is: %<page> of %<npages>.
9 Optional – you can experiment and make changes on your own.
10 Save the printframe – select Save As from the File menu. In the Save
Frame dialog box, type engdivl for the File name. Click the Save button.
The printframe is saved as a .fig file.
11 You can close the PrintFrame Editor window if you want to – click the close
box.
190
frameedit
Print the Simulink Block Diagram with the Printframe
1 To view the Simulink engine model, type engine at the MATLAB prompt.
The engine model appears in a Simulink window.
2 Double-click on the Throttle & Manifold block.
The Throttle & Manifold subsystem opens in a new window.
3 In the Throttle & Manifold window, select Print from the File menu.
The Print Model dialog box opens.
191
frameedit
4 In the Print Model dialog box, set the page orientation to landscape. This
example uses the techniques for the Windows platform. Use the methods for
your own platform to change the page orientation for printing.
a Click the Properties button.
The Document Properties dialog box opens.
b Go to the Page Setup tab.
c
For Orientation, select Landscape.
d Click OK.
The Document Properties dialog box closes.
5 In the Print Model dialog box, under Options, select Current system and
below.
This specifies that the Throttle & Manifold block diagram and its
subsystems will print.
6 Check the Frame check box.
7 Specify the printframe to use.
a Click the ... button
b In the Frame File Selection dialog box, find the filename of the
printframe you just created, engdivl.fig, and select it.
c
Click the Open button.
The path and filename appear in the Frame edit box.
8 Click the OK button in the Print Model dialog box.
The Throttle & Manifold block diagram prints with the printframe; it should
look similar to the figure shown at the start of this example.
In addition, the Throttle block diagram prints on page 2, and the Intake
Manifold block diagram on page 3. These block diagrams also print with the
engdivl printframe, but note that their variable information in the
printframe is different.
192
gca
Purpose
2gca
Get current Axes handle
Syntax
h = gca
Description
h = gca returns the handle to the current Axes for the current Figure. If no
Axes exists, MATLAB creates one and returns its handle. You can use the
statement,
get(gcf,'CurrentAxes')
if you do not want MATLAB to create an Axes if one does not already exist.
The current Axes is the target for graphics output when you create Axes
children. Graphics commands such as plot, text, and surf draw their results
in the current Axes. Changing the current Figure also changes the current
Axes.
See Also
axes, cla, delete, gcf, gcbo, gco, hold, subplot, findobj
Figure CurrentAxes property
2-193
gcf
Purpose
2gcf
Get current Figure handle
Syntax
h = gcf
Description
h = gcf returns the handle of the current Figure. The current Figure is the
Figure window in which graphics commands such as plot, title, and surf
draw their results. If no Figure exists, MATLAB creates one and returns its
handle. You can use the statement,
get(0,'CurrentFigure')
if you do not want MATLAB to create a Figure if one does not already exist.
See Also
axes, clf, close, delete, figure, gca, gcbo, gco, subplot
Root CurrentFigure property
2-194
gco
Purpose
2gco
Return handle of current object
Syntax
h = gco
h = gco(figure_handle)
Description
h = gco returns the handle of the current object.
h = gco(figure_handle) returns the value of the current object for the
Figure specified by figure_handle.
Remarks
The current object is the last object clicked on, excluding Uimenus. If the mouse
click did not occur over a Figure child object, the Figure becomes the current
object. MATLAB stores the handle of the current object in the Figure’s
CurrentObject property.
The CurrentObject of the CurrentFigure does not always indicate the object
whose callback is being executed. Interruptions of callbacks by other callbacks
can change the CurrentObject or even the CurrentFigure. Some callbacks,
such as CreateFcn and DeleteFcn, and Uimenu Callback intentionally do not
update CurrentFigure or CurrentObject.
gcbo provides the only completely reliable way to retrieve the handle to the
object whose callback is executing, at any point in the callback function,
regardless of the type of callback or of any previous interruptions.
Examples
This statement returns the handle to the current object in Figure window 2:
h = gco(2)
See Also
gca, gcbo, gcf
The Root object description
2-195
get
Purpose
2get
Get object properties
Syntax
get(h)
get(h,'PropertyName')
<m-by-n value cell array> = get(H,<property cell array>)
a = get(h)
a = get(0,'Factory')
a = get(0,'FactoryObjectTypePropertyName')
a = get(h,'Default')
a = get(h,'DefaultObjectTypePropertyName')
Description
get(h) returns all properties and their current values of the graphics object
identified by the handle h.
get(h,'PropertyName') returns the value of the property 'PropertyName' of
the graphics object identified by h.
<m-by-n value cell array> = get(H,pn) returns n property values for m
graphics objects in the m-by-n cell array, where m = length(H) and n is equal
to the number of property names contained in pn.
a = get(h) returns a structure whose field names are the object’s property
names and whose values are the current values of the corresponding
properties. h must be a scalar. If you do not specify an output argument,
MATLAB displays the information on the screen.
a = get(0,'Factory') returns the factory-defined values of all user-settable
properties. a is a structure array whose field names are the object property
names and whose field values are the values of the corresponding properties.
If you do not specify an output argument, MATLAB displays the information
on the screen.
a = get(0,'FactoryObjectTypePropertyName') returns the factory-defined
value of the named property for the specified object type. The argument,
FactoryObjectTypePropertyName is the word Factory concatenated with the
object type (e.g., Figure) and the property name (e.g., Color):
FactoryFigureColor
2-196
get
a = get(h,'Default') returns all default values currently defined on object
h. a is a structure array whose field names are the object property names and
whose field values are the values of the corresponding properties. If you do not
specify an output argument, MATLAB displays the information on the screen.
a = get(h,'DefaultObjectTypePropertyName') returns the factory-defined
value of the named property for the specified object type. The argument,
DefaultObjectTypePropertyName is the word Default concatenated with the
object type (e.g., Figure) and the property name (e.g., Color):
DefaultFigureColor
Examples
You can obtain the default value of the LineWidth property for Line graphics
objects defined on the Root level with the statement:
get(0,'DefaultLineLineWidth')
ans =
0.5000
To query a set of properties on all Axes children define a cell array of property
names:
props = {'HandleVisibility', 'Interruptible';
'SelectionHighlight', 'Type'};
output = get(get(gca,'Children'),props);
The variable output is a cell array of dimension:
length(get(gca,'Children')−by−4.
For example, type:
patch;surface;text;line
output = get(get(gca,'Children'),props)
output =
'on'
'on’
'on'
'on'
See Also
'on'
'off'
'on'
'on'
'on'
'on'
'on'
'on'
'line'
'text'
'surface'
'patch'
findobj, gca, gcf, gco, set
2-197
getframe
Purpose
2getframe
Get movie frame
Synopsis
M = getframe
M = getframe(h)
M = getframe(h,rect)
[X,Map] = getframe(...)
Description
getframe returns a column vector containing one movie frame. The frame is a
snapshot (pixmap) of the current Axes.
M = getframe gets a frame from the current Axes.
M = getframe(h) gets a frame from the Figure or Axes graphics object
identified by h.
M = getframe(h,rect) specifies a rectangular area from which to copy the
pixmap. rect is relative to the lower-left corner of the Figure or Axes graphics
object identified by h, in pixel units. rect is a four-element vector in the form
[left bottom width height], where width and height define the dimensions
of the rectangle.
[X,Map] = getframe(...) returns the frame as an indexed image matrix X
and a colormap Map. In this case, h is a handle to a Figure or Axes object. You
display the image matrix using image or imagesc.
Remarks
Usually, getframe is put in a for loop to assemble movie matrix M for playback
using movie. To provide more efficient memory use, use moviein to allocate
movie matrix M before building the movie. This generates an appropriate size
matrix of zeros.
Note that M = getframe; returns the contents of the current Axes, exclusive of
the axis labels, title, or tick labels. M = getframe(gcf); captures the entire
interior of the current Figure window.
If you plan to convert the MATLAB movie to another format (such as
QuickTime) and you want to include the axis labels in this new format, you
should capture the Figure, not just the Axes. If you are using moviein to
pre-allocate the movie matrix, be sure to specify the same Figure handle that
you use with getframe.
2-198
getframe
Examples
Make the peaks function vibrate:
Z = peaks; surf(Z)
M = moviein(20);
axis manual
% Freeze Axes limits
set(gca,'nextplot','replacechildren');
for j = 1:20
surf(sin(2*pi*j/20)*Z,Z)
M(:,j) = getframe;
end
movie(M,20) % Play the movie twenty times
See Also
movie, moviein,qtwrite
2-199
ginput
Purpose
2ginput
Input data using the mouse
Syntax
[x,y] = ginput(n)
[x,y] = ginput
[x,y,button] = ginput(...)
Description
ginput enables you to select points from the Figure using the mouse or arrow
keys for cursor positioning. The Figure must have focus before ginput receives
input.
[x,y] = ginput(n) enables you to select n points from the current Axes and
returns the x- and y-coordinates in the column vectors x and y, respectively.
You can press the Return key to terminate the input before entering n points.
[x,y] = ginput gathers an unlimited number of points until you press the
Return key.
[x,y,button] = ginput(...) returns the x-coordinates, the y-coordinates,
and the button or key designation. button is a vector of integers indicating
which mouse buttons you pressed (1 for left, 2 for middle, 3 for right), or ASCII
numbers indicating which keys on the keyboard you pressed.
Remarks
If you select points from multiple Axes, the results you get are relative to those
Axes coordinates systems.
Examples
Pick 10 two-dimensional points from the Figure window.
[x,y] = ginput(10)
Position the cursor with the mouse (or the arrow keys on terminals without a
mouse, such as Tektronix emulators). Enter data points by pressing a mouse
button or a key on the keyboard. To terminate input before entering 10 points,
press the Return key.
See Also
2-200
gtext
gplot
Purpose
2gplot
Plot set of nodes using an adjacency matrix
Synopsis
gplot(A,Coordinates)
gplot(A,Coordinates,LineSpec)
Description
The gplot function graphs a set of coordinates using an adjacency matrix.
gplot(A,Coordinates) plots a graph of the nodes defined in Coordinates
according to the n-by-n adjacency matrix A, where n is the number of nodes.
Coordinates is an n-by-2 or an n-by-3 matrix, where n is the number of nodes
and each coordinate pair or triple represents one node.
gplot(A,Coordinates,LineSpec) plots the nodes using the line type, marker
symbol, and color specified by LineSpec.
Remarks
For two-dimensional data, Coordinates(i,:) = [x(i) y(i)] denotes node i,
and Coordinates(j,:) = [x(j) y(j)] denotes node j. If node i and node j are
joined, A(i,j) or A(j,i) are nonzero; otherwise, A(i,j) and A(j,i) are zero.
2-201
gplot
Examples
To draw half of a Bucky ball with asterisks at each node:
k = 1:30;
[B,XY] = bucky;
gplot(B(k,k),XY(k,:),'-*')
axis square
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−1
See Also
2-202
−0.8
−0.6
−0.4
−0.2
LineSpec, sparse, spy
0
0.2
0.4
0.6
0.8
1
graymon
Purpose
2graymon
Set default Figure properties for grayscale monitors
Syntax
graymon
Description
graymon sets defaults for graphics properties to produce more legible displays
for grayscale monitors.
See Also
axes, figure
2-203
grid
Purpose
2grid
Grid lines for two- and three-dimensional plots
Syntax
grid on
grid off
grid
Description
The grid function turns the current Axes’ grid lines on and off.
grid on adds grid lines to the current Axes.
grid off removes grid lines from the current Axes.
grid toggles the grid visibility state.
Algorithm
grid sets the XGrid, YGrid, and ZGrid properties of the current Axes.
See Also
axes, plot
The XGrid, YGrid, and ZGrid properties of Axes objects.
2-204
gtext
Purpose
2gtext
Mouse placement of text in two-dimensional view
Syntax
gtext('string')
h = gtext('string')
Description
gtext displays a text string in the current Figure window after you select a
location with the mouse.
gtext('string') waits for you to press a mouse button or keyboard key while
the pointer is within a Figure window. Pressing a mouse button or any key
places 'string' on the plot at the selected location.
h = gtext('string') returns a handle to a Text graphics objects after you
place 'string' on the plot at the selected location.
Remarks
As you move the pointer into a Figure window, the pointer becomes a crosshair
to indicate that gtext is waiting for you to select a location. gtext uses the
functions ginput and text.
Examples
Place a label on the current plot:
gtext('Note this divergence!')
See Also
ginput, text
2-205
hidden
Purpose
2hidden
Remove hidden lines from a mesh plot
Syntax
hidden on
hidden off
hidden
Description
Hidden line removal draws only those lines that are not obscured by other
objects in the field of view.
hidden on turns on hidden line removal for the current graph so lines in the
back of a mesh are hidden by those in front. This is the default behavior.
hidden off turns off hidden line removal for the current graph.
hidden toggles the hidden line removal state.
Algorithm
hidden on sets the FaceColor property of a Surface graphics object to the
background Color of the Axes (or of the Figure if Axes Color is none).
Examples
Set hidden line removal off and on while displaying the peaks function:
mesh(peaks)
hidden off
hidden on
See Also
shading
The Surface properties FaceColor and EdgeColor
2-206
hist
Purpose
2hist
Histogram plot
Syntax
n = hist(Y)
n = hist(Y,x)
n = hist(Y,nbins)
[n,xout] = hist(...)
Description
A histogram shows the distribution of data values.
n = hist(Y) draws a histogram of the elements in Y, binning the data into ten
equally spaced containers and returns the number of elements in each
container. If Y is a matrix, hist works down the columns. hist distributes the
bins along the x-axis between the minimum and maximum values of Y.
n = hist(Y,x) draws a histogram using n bins, where n is length(x). x also
specifies the locations on the x-axis where hist places the bins. For example, if
x is a 5-element vector, hist distributes the elements of Y into five bins
centered on the x-axis at the elements in x.
n = hist(Y,nbins) draws a histogram with no more bins than nbins.
[n,xout] = hist(...) returns vectors n and xout containing the frequency
counts and the bin locations. This syntax does not generate a plot. This is useful
when you need more control over the appearance of a graph, for example, to
combine a histogram into a more elaborate plot. You can use bar(xout,n) to
plot the histogram.
Remarks
All elements in vector Y or in one column of matrix Y are grouped according to
their numeric range. Each group is shown as one bin.
The histogram’s x-axis reflects the range of values in Y. The histogram’s y-axis
shows the number of elements that fall within the groups; therefore, the y-axis
ranges from 0 to the greatest number of elements deposited in any bin.
The histogram is created with a Patch graphics object. If you want to change
the color of the graph, you can set Patch properties. See the “Example” section
for more information. By default, the graph color is controlled by the current
colormap, which maps the bin color to the first color in the colormap.
2-207
hist
Examples
Generate a bell-curve histogram from Gaussian data:
x = –2.9:0.1:2.9;
y = randn(10000,1);
hist(y,x)
400
350
300
250
200
150
100
50
0
−3
2-208
−2
−1
0
1
2
3
hist
Change the color of the graph so that the bins are red and the edges of the bins
are white:
h = get(gca,'Children');
set(h,'FaceColor','r',EdgeColor','w')
400
350
300
250
200
150
100
50
0
−3
See Also
−2
−1
0
1
2
3
bar,ColorSpec, patch, stairs
2-209
hold
Purpose
2hold
Hold current graph in the Figure
Syntax
hold on
hold off
hold
Description
The hold function determines whether new graphics objects are added to the
graph or replace objects in the graph.
hold on retains the current plot and certain Axes properties so that
subsequent graphing commands add to the existing graph.
hold off resets Axes properties to their defaults before drawing new plots.
hold off is the default.
hold toggles the hold state between adding to the graph and replacing the
graph.
Remarks
Test the hold state using the ishold function.
Although the hold state is on, some Axes properties change to accommodate
additional graphics objects. For example, the Axes’ limits increase when the
data requires them to do so.
Algorithm
The hold function sets the NextPlot property of the current Figure and the
current Axes. If several Axes objects exist in a Figure window, each Axes has
its own hold state. hold also creates an Axes if one does not exist.
hold on sets the NextPlot property of the current Figure and Axes to add.
hold off sets the NextPlot property of the current Axes to replace.
hold toggles the NextPlot property between the add and replace states.
See Also
axis, cla, ishold, newplot
The NextPlot property of Axes and Figure graphics objects.
2-210
home
Purpose
2home
Send the cursor home
Syntax
home
Description
home returns the cursor to the upper-left corner of the command window.
Examples
Display a sequence of random matrices at the same location in the command
window:
clc
for i =1:25
home
A = rand(5)
end
See Also
clc
2-211
hsv2rgb
Purpose
2hsv2rgb
Convert HSV colormap to RGB colormap
Syntax
M = hsv2rgb(H)
Description
M = hsv2rgb(H) converts a hue-saturation-value (HSV) colormap to a
red-green-blue (RGB) colormap. H is an m-by-3 matrix, where m is the number
of colors in the colormap. The columns of H represent hue, saturation, and
value, respectively. M is an m-by-3 matrix. Its columns are intensities of red,
green, and blue, respectively.
Remarks
As H(:,1) varies from 0 to 1, the resulting color varies from red, through
yellow, green, cyan, blue, and magenta, and returns to red. When H(:,2) is 0,
the colors are unsaturated (i.e., shades of gray). When H(:,2) is 1, the colors
are fully saturated (i.e., they contain no white component). As H(:,3) varies
from 0 to 1, the brightness increases.
The MATLAB hsv colormap uses hsv2rgb([hue saturation value]) where
hue is a linear ramp from 0 to 1, and saturation and value are all 1’s.
See Also
2-212
brighten, colormap, rgb2hsv
im2frame
Purpose
2im2frame
Convert indexed image into movie frame
Syntax
F = im2frame(X,Map)
Description
F = im2frame(X,Map) converts the indexed image X and associated colormap
Map into a movie frame F. You can use im2frame to convert a sequence of images
into a movie.
Example
To use im2frame to convert a sequence of images into a movie, first pre-allocate
matrix using movein:
M = moviein(n);
M(:,1) = im2frame(X1,map);
M(:,2) = im2frame(X2,map);
...
M(:,n) = im2frame(Xn,map);
movie(M)
See Also
capture, frame2im, movie, moviein
2-213
image
Purpose
2image
Display Image object
Syntax
image(C)
image(x,y,C)
image(...,'PropertyName',PropertyValue,...)
image('PropertyName',PropertyValue,...) Formal synatx – PN/PV only
handle = image(...)
Description
image creates an Image graphics object by interpreting each element in a
matrix as an index into the Figure’s colormap or directly as RGB values,
depending on the data specified.
The image function has two forms:
• A high-level function that calls newplot to determine where to draw the
graphics objects and sets the following Axes properties:
XLim and YLim to enclose the Image
Layer to top to place the Image in front of the tick marks and grid lines
YDir to reverse
View to [0 90]
• A low-level function that adds the Image to the current Axes without calling
newplot. The low-level function argument list can contain only property
name/property value pairs.
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see the set and get reference pages for examples of
how to specify these data types).
image(C) displays matrix C as an Image. Each element of C specifies the color
of a rectangular segment in the Image.
image(x,y,C) where x and y are two-element vectors, specifies the range of
the x- and y-axis labels, but produces the same Image as image(C). This can be
useful, for example, if you want the axis tick labels to correspond to real
physical dimensions represented by the image.
2-214
image
image(x,y,C,'PropertyName',PropertyValue,...) is a high-level function
that also specifies property name/property value pairs. This syntax calls
newplot before drawing the Image.
image('PropertyName',PropertyValue,...) is the low-level syntax of the
image function. It specifies only property name/property value pairs as input
arguments.
handle = image(...) returns the handle of the Image object it creates. You
can obtain the handle with all forms of the image function.
Remarks
Image data can be either indexed or true color. An indexed image stores colors
as an array of indices into the Figure colormap. A true color image does not use
a colormap; instead, the color values for each pixel are stored directly as RGB
triplets. In MATLAB , the CData property of a truecolor Image object is a
three-dimensional (m-by-n-by-3) array. This array consists of three m-by-n
matrices (representing the red, green, and blue color planes) concatenated
along the third dimension.
The imread function reads image data into MATLAB arrays from graphics files
in various standard formats, such as TIFF. You can write MATLAB image data
to graphics files using the imwrite function. imread and imwrite both support
a variety of graphics file formats and compression schemes.
When you read image data into MATLAB using imread, the data is stored as
an array of 8-bit integers. This is a much more efficient storage method than
the double-precision (64-bit) floating-point numbers that MATLAB typically
2-215
image
uses. However, it is necessary for MATLAB to interpret 8-bit image data
differently from 64-bit data. This table summarizes these differences:
Image
Type
Double-precision Data
(double array)
8-bit Data (uint8 array)
indexed
(colormap)
Image is stored as a
two-dimensional (m-by-n) array
of integers in the range [1,
length(colormap)]; colormap
is an m-by-3 array of
floating-point values in the
range [0, 1]
Image is stored as a
two-dimensional (m-by-n)
array of integers in the
range [0, 255]; colormap
is an m-by-3 array of
floating-point values in
the range [0, 1]
truecolor
(RGB)
Image is stored as a
three-dimensional
(m-by-n-by-3) array of
floating-point values in the
range [0, 1]
Image is stored as a
three-dimensional
(m-by-n-by-3) array of
integers in the range
[0, 255]
Indexed images
In an indexed image of class double, the value 1 points to the first row in the
colormap, the value 2 points to the second row, and so on. In a uint8 indexed
image, there is an offset; the value 0 points to the first row in the colormap, the
value 1 points to the second row, and so on. The uint8 convention is also used
in graphics file formats, and enables 8-bit indexed images to support up to 256
colors. Note that when you read in an indexed image with imread, the resulting
image array is always of class uint8. (The colormap, however, is of class
double; see below.)
If you want to convert a uint8 indexed image to double, you need to add 1 to
the result. For example:
X64 = double(X8) + 1;
To convert from double to uint8, you need to first subtract 1, and then use
round to ensure all the values are integers:
X8 = uint8(round(X64 – 1));
2-216
image
The order of the operations must be as shown in these examples, because you
cannot perform mathematical operations on uint8 arrays.
When you write an indexed image using imwrite, MATLAB automatically
converts the values if necessary.
Colormaps
Colormaps in MATLAB are alway m-by-3 arrays of double-precision
floating-point numbers in the range [0, 1]. In most graphics file formats,
colormaps are stored as integers, but MATLAB does not support colormaps
with integer values. imread and imwrite automatically convert colormap
values when reading and writing files.
True Color Images
In a truecolor image of class double, the data values are floating-point numbers
in the range [0, 1]. In a truecolor image of class uint8, the data values are
integers in the range [0, 255].
If you want to convert a truecolor image from one data type to the other, you
must rescale the data. For example, this call converts a uint8 truecolor image
to double:
RGB64 = double(RGB8)/255;
This statement converts a double truecolor image to uint8:
RGB8 = uint8(round(RGB*255));
The order of the operations must be as shown in these examples, because you
cannot perform mathematical operations on uint8 arrays.
When you write a truecolor image using imwrite, MATLAB automatically
converts the values if necessary.
2-217
image
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Image properties on the Axes, Figure, and Root levels:
set(0,'DefaultImageProperty',PropertyValue...)
set(gcf,'DefaultImageProperty',PropertyValue...)
set(gca,'DefaultImageProperty',PropertyValue...)
Where Property is the name of the Image property and PropertyValue is the
value you are specifying. Use set and get to access Image properties.
The following table lists all Image properties and provides a brief description
of each. The property name links take you to an expanded description of the
properties.
Property Name
Property Description
Property Value
The image data
Values: matrix or
m-by-n-by-3 array
Default: enter
Data Defining the Object
CData
image;axis image ij
and see
CDataMapping
2-218
Specify the mapping of data to
colormap
Values: scaled, direct
Default: direct
image
Property Name
Property Description
Property Value
XData
Control placement of image along
x-axis
Values: [min max]
Default: [1 size(CData,2)]
YData
Control placement of image along
y-axis
Values: [min max]
Default: [1 size(CData,1)]
Clipping
Clipping to Axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the
image (useful for animation)
Values: normal, none, xor,
background
Default: normal
SelectionHighlight
Highlight image when selected
(Selected property set to on)
Values: on, off
Default: on
Visible
Make the image visible or invisible
Values: on, off
Default: on
Controlling the Appearance
Controlling Access to Objects
HandleVisibility
Determines if and when the the
Line’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Determine if image can become the
current object (see the Figure
CurrentObject property)
Values: on, off
Default: on
General Information About the Image
Children
Image objects have no children
Values: [] (empty matrix)
Parent
The parent of an image object is
always an Axes object
Value: Axes handle
Selected
Indicate whether image is in a
“selected” state.
Values: on, off
Default: on
2-219
image
Property Name
Property Description
Property Value
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'image'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
Properties Related to Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on over the image
Values: string
Default: empty string
CreateFcn
Define a callback routine that
executes when an image is created
Values: string
Default: empty string
DeleteFcn
Define a callback routine that
executes when the image is deleted
(via close or delete)
Values: string
Default: empty string
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
Associate a context menu with the
image
Values: handle of a
Uicontrextmenu
2-220
Image Properties
Image
Properties
2Image Properties
This section lists property names along with the types of values each property
accepts.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routes always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is over the Image object. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
CData
matrix or m-by-n-by-3 array
The Image data. A matrix of values specifying the color of each rectangular
area defining the Image. image(C) assigns the values of C to CData. MATLAB
determines the coloring of the Image in one of three ways:
• Using the elements of CData as indices into the current colormap (the
default)
• Scaling the elements of CData to range between the values
min(get(gca,'CLim')) and max(get(gca,'CLim')) (CDataMapping set to
scaled)
• Interpreting the elements of CData directly as RGB values (true color
specification)
2-221
Image Properties
A true color specification for CData requires an m-by-n-by-3 array of RGB
values. The first page contains the red component, the second page the green
component, and the third page the blue component of each element in the
Image. RGB values range from 0 to 1. The following picture illustrates the
relative dimensions of CData for the two color models:
Indexed Colors
CData
True Colors
Blue
Green
Red
CData
If CData has only one row or column, the height or width respectively is always
one data unit and is centered about the first YData or XData element
respectively. For example, using a 4-by-1 matrix of random data,
C = rand(4,1);
image(C,'CDataMapping','scaled')
axis image
2-222
Image Properties
produces:
0.5
1
1.5
2
2.5
3
3.5
4
4.5
0.5
CDataMapping
1
1.5
scaled | {direct}
Direct or scaled indexed colors. This property determines whether MATLAB
interprets the values in CData as indices into the Figure colormap (the default)
or scales the values according to the values of the Axes CLim property.
When CDataMapping is direct, the values of CData should be in the range 1 to
length(get(gcf,'Colormap')). If you use true color specification for CData,
this property has no effect.
Children
handles
The empty matrix; Image objects have no children.
Clipping
on | off
Clipping mode. By default, MATLAB clips Images to the Axes rectangle. If you
set Clipping to off, the Image can display outside the Axes rectangle. For
example, if you create an Image, set hold to on, freeze axis scaling (axis
manual), and then create a larger Image, it extends beyond the axis limits.
2-223
Image Properties
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates an Image object. You
must define this property as a default value for Images. For example, the
statement,
set(0,'DefaultImageCreateFcn','axis image')
defines a default value on the Root level that sets the aspect ratio and the axis
limits so the Image has square pixels. MATLAB executes this routine after
setting all Image properties. Setting this property on an existing Image object
has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Image callback routine. A callback routine that executes when you
delete the Image object (i.e., when you issue a delete command or clear the
Axes or Figure containing the Image). MATLAB executes the routine before
destroying the object’s properties so these values are available to the callback
routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and
erase Image objects. Alternative erase modes are useful for creating animated
sequences, where control of the way individual objects redraw is necessary to
improve performance and obtain the desired effect.
• normal (the default) — Redraw the affected region of the display, performing
the three-dimensional analysis necessary to ensure that all objects are
rendered correctly. This mode produces the most accurate picture, but is the
slowest. The other modes are faster, but do not perform a complete redraw
and are therefore less accurate.
• none – Do not erase the Image when it is moved or changed. While the object
is still visible on the screen after erasing with EraseMode none, you cannot
print it because MATLAB stores no information about its former location.
2-224
Image Properties
• xor – Draw and erase the Image by performing an exclusive OR (XOR) with
the color of the screen beneath it. This mode does not damage the color of the
objects beneath the Image. However, the Image’s color depends on the color
of whatever is beneath it on the display.
• background – Erase the Image by drawing it in the Axes’ background Color,
or the Figure background Color if the Axes Color is set to none. This
damages objects that are behind the erased Image, but Images are always
properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints Figures as if the
EraseMode of all objects is normal. This means graphics objects created with
EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g.,
XORing a pixel color with that of the pixel behind it) and ignore
three-dimensional sorting to obtain greater rendering speed. However, these
techniques are not applied to the printed output.
You can use the MATLAB capture command or other screen capture
application to create an image of a Figure containing non-normal mode objects.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaling a user-typed string), and so
temporarily hides its own handles during the execution of that function.
2-225
Image Properties
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Image can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Image. If HiTest is off, clicking on
the Image selects the object below it (which maybe the Axes containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether an Image callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine.
Parent
handle of parent Axes
Image’s parent. The handle of the Image object’s parent Axes. You can move an
Image object to another Axes by changing this property to the new Axes
handle.
Selected
on | {off}
Is object selected. When this property is on, MATLAB displays selection
handles if the SelectionHighlight property is also on. You can, for example,
2-226
Image Properties
define the ButtonDownFcn to set this property, allowing users to select the
object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing four edge handles and four corner
handles. When SelectionHighlight is off, MATLAB does not draw the
handles.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Type of graphics object. This property contains a string that identifies the class
of graphics object. For Image objects, Type is always 'image'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Image. Assign this property the handle of a
Uicontextmenu object created in the same Figure as the Image. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Image (Control-click on
Macintosh systems).
UserData
matrix
User specified data. This property can be any data you want to associate with
the Image object. The Image does not use this property, but you can access it
using set and get.
Visible
{on} | off
Image visibility. By default, Image objects are visible. Setting this property to
off prevents the Image from being displayed. However, the object still exists
and you can set and query its properties.
XData
[1 size(CData,2)] by default
Control placement of image along x-axis. A vector specifying the locations of the
centers of the elements CData(1,1) and CData(m,n), where CData has a size of
2-227
Image Properties
m-by-n. Element CData(1,1) is centered over the coordinate defined by the first
elements in XData and YData. Element CData(m,n) is centered over the
coordinate defined by the last elements in XData and YData. The centers of the
remaining elements of CData are evenly distributed between those two points.
The width of each CData element is determined by the expression:
(XData(2)-XData(1))/(size(CData,2)-1)
You can also specify a single value for XData. In this case, image centers the
first element at this coordinate and centers each following element one unit
apart.
YData
[1 size(CData,1)] by default
Control placement of image along y-axis. A vector specifying the locations of the
centers of the elements CData(1,1) and CData(m,n), where CData has a size of
m-by-n. Element CData(1,1) is centered over the coordinate defined by the first
elements in XData and YData. Element CData(m,n) is centered over the
coordinate defined by the last elements in XData and YData. The centers of the
remaining elements of CData are evenly distributed between those two points.
The height of each CData element is determined by the expression:
(YData(2)-YData(1))/(size(CData,1)-1)
You can also specify a single value for YData. In this case, image centers the
first element at this coordinate and centers each following elements one unit
apart.
See Also
colormap, imfinfo, imread, imwrite, pcolor, newplot, surface
The “Image” chapter the Using MATLAB Graphics manual
2-228
imagesc
Purpose
2imagesc
Scale data and display an Image object
Syntax
imagesc(C)
imagesc(x,y,C)
imagesc(...,clims)
h = imagesc(...)
Description
The imagesc function scales image data to the full range of the current
colormap and displays the image. (See the illustration on the following page.)
imagesc(C) displays C as an image. Each element of C corresponds to a
rectangular area in the image. The values of the elements of C are indices into
the current colormap that determine the color of each patch.
imagesc(x,y,C) displays C as an Image and specifies the bounds of the x- and
y-axis with vectors x and y.
imagesc(...,clims) normalizes the values in C to the range specified by
clims and displays C as an Image. clims is a two-element vector that limits the
range of data values in C. These values map to the full range of values in the
current colormap.
h = imagesc(...) returns the handle for an Image graphics object.
Remarks
x and y do not affect the elements in C; they only affect the annotation of the
Axes. If length(x) > 2 or length(y) > 2, imagesc ignores all except the first
and last elements of the respective vector.
Algorithm
imagesc creates an image with CDataMapping set to scaled, and sets the Axes
CLim to the value passed in clims.
2-229
imagesc
Examples
If the size of the current colormap is 81-by-3,
the statements
Data
Values
81
clims = [10 60]
imagesc(C,clims)
60
59
58
map the data values in C to the colormap,
as shown to the right.
Colormap
Values
81
80
79
78
12
11
10
4
3
2
1
1
The left Image maps to the gray colormap using the statements
load clown
imagesc(X)
colormap(gray)
The right Image has values between 10 and 60 scaled to the full range of the
gray colormap using the statements
load clown
clims = [10 60];
imagesc(X,clims)
colormap(gray)
20
20
40
40
60
60
80
80
100
100
120
120
140
140
160
160
180
180
200
2-230
50
100
150
200
250
300
200
50
100
150
200
250
300
imagesc
See Also
image, colorbar
2-231
imfinfo
Purpose
2imfinfo
Return information about a graphics file
Synopsis
info = imfinfo(filename,fmt)
info = imfinfo(filename)
Description
info = imfinfo(filename,fmt) returns a structure whose fields contain
information about an image in a graphics file. filename is a string that
specifies the name of the graphics file, and fmt is a string that specifies the
format of the file. The file must be in the current directory or in a directory on
the MATLAB path. If imfinfo cannot find a file named filename, it looks for a
file named
filename.fmt.
This table lists the possible values for fmt:
Format
File type
'bmp'
Windows Bitmap (BMP)
'hdf'
Hierarchical Data Format (HDF)
'jpg' or 'jpeg'
Joint Photographic Experts Group (JPEG)
'pcx'
Windows Paintbrush (PCX)
'tif' or 'tiff'
Tagged Image File Format (TIFF)
'xwd'
X Windows Dump (XWD)
If filename is a TIFF or HDF file containing more than one image, info is a
structure array with one element (i.e., an individual structure) for each image
in the file. For example, info(3) would contain information about the third
image in the file.
2-232
imfinfo
The set of fields in info depends on the individual file and its format. However,
the first seven fields are always the same. This table lists these fields and
describes their values:
Field
Value
Filename
A string containing the name of the file; if the file is
not in the current directory, the string contains the
full pathname of the file
Format
A string containing the file format, as specified by fmt;
for JPEG and TIFF files, the three-letter variant is
returned
FormatVersion
A string or number describing the version of the
format
Width
An integer indicating the width of the image in pixels
Height
An integer indicating the height of the image in pixels
BitDepth
An integer indicating the number of bits per pixel
ColorType
A string indicating the type of image; either
'truecolor' for a truecolor RGB image, 'grayscale'
for a grayscale intensity image, or 'indexed' for an
indexed image
info = imfinfo(filename) attempts to infer the format of the file from its
content.
2-233
imfinfo
Example
info = imfinfo('flower.bmp')
info =
Filename:
Format:
FormatVersion:
Width:
Height:
BitDepth:
ColorType:
FormatSignature:
NumColormapEntries:
Colormap:
RedMask:
GreenMask:
BlueMask:
FileSize:
ImageDataOffset:
BitmapHeaderSize:
NumPlanes:
CompressionType:
BitmapSize:
HorzResolution:
VertResolution:
NumColorsUsed:
NumImportantColors:
See Also
2-234
imread, imwrite
'flower.bmp'
'bmp'
'Version 3 (Microsoft Windows 3.x)'
227
149
8
'indexed'
'BM'
256
[256x3 double]
[]
[]
[]
35050
1078
40
1
'none'
33972
0
0
256
0
imread
Purpose
2imread
Read image from graphics file
Synopsis
A = imread(filename,fmt)
[X,map] = imread(filename,fmt)
[...] = imread(filename)
[...] = imread(...,idx)
[...] = imread(...,ref)
Description
A = imread(filename,fmt) reads the image in filename into A, whose class is
uint8. If the file contains a grayscale intensity image, A is a two-dimensional
array. If the file contains a truecolor (RGB) image, A is a three-dimensional
(m-by-n-by-3) array. filename is a string that specifies the name of the graphics
file, and fmt is a string that specifies the format of the file. The file must be in
the current directory or in a directory in the MATLAB path. If imread cannot
find a file named filename, it looks for a file named filename.fmt.
This table lists the possible values for fmt:
Format
File type
'bmp'
Windows Bitmap (BMP)
'hdf'
Hierarchical Data Format (HDF)
'jpg' or 'jpeg'
Joint Photographic Experts Group (JPEG)
'pcx'
Windows Paintbrush (PCX)
'tif' or 'tiff'
Tagged Image File Format (TIFF)
'xwd'
X Windows Dump (XWD)
[X,map] = imread(filename,fmt) reads the indexed image in filename into
X and its associated colormap into map. X is of class uint8, and map is of class
double. The colormap values are rescaled when they are read to have the range
[0, 1].
[...] = imfread(filename) attempts to infer the format of the file from its
content.
2-235
imread
[...] = imread(...,idx) reads in one image from a multi-image TIFF file.
idx is an integer value that specifies the order that the image appears in the
file. For example, if idx is 3, imread reads the third image in the file. If you omit
this argument, imread reads the first image in the file.
[...] = imread(...,ref) reads in one image from a multi-image HDF file.
ref is an integer value that specifies the reference number used to identify the
image. For example, if ref is 12, imread reads the image whose reference
number is 12. (Note that in an HDF file the reference numbers do not
necessarily correspond with the order of the images in the file.) If you omit this
argument, imread reads the first image in the file.
This table summarizes the types of images that imread can read:
Examples
Format
Variants
BMP
1-bit, 4-bit, 8-bit, and 24-bit uncompressed images; 4-bit
and 8-bit run-length encoded (RLE) images
HDF
8-bit raster image datasets, with or without associated
colormap; 24-bit raster image datasets
JPEG
Any baseline JPEG image; JPEG images with some
commonly used extensions
PCX
1-bit, 8-bit, and 24-bit images
TIFF
Any baseline TIFF image, including 1-bit, 8-bit, and 24-bit
uncompressed images; 1-bit, 8-bit, and 24-bit images with
packbit compression; 1-bit images with CCITT compression
XWD
1-bit and 8-bit ZPixmaps; XYBitmaps; 1-bit XYPixmaps
This example reads the sixth image in a TIFF file:
[X,map] = imread('flower.tif',6);
This example reads the fourth image in an HDF file:
info = imfinfo('skull.hdf');
[X,map] = imread('skull.hdf',info(4).Reference);
See Also
2-236
imfinfo, imwrite
imwrite
Purpose
2imwrite
Write an image to a graphics file
Synopsis
imwrite(A,filename,fmt)
imwrite(X,map,filename,fmt)
imwrite(...,filename)
imwrite(...,Parameter,Value,...)
Description
imwrite(A,filename,fmt) writes the image in A to filename. filename is a
string that specifies the name of the output file, and fmt is a string that
specifies the format of the file. If A is a grayscale intensity image or a truecolor
(RGB) image of class uint8, imwrite writes the actual values in the array to
the file. If A is of class double, imwrite rescales the values in the array before
writing, using uint8(round(255*A)). This operation converts the
floating-point numbers in the range [0, 1] to 8-bit integers in the range [0, 255].
This table lists the possible values for fmt:
Format
File type
'bmp'
Windows Bitmap (BMP)
'hdf'
Hierarchical Data Format (HDF)
'jpg' or 'jpeg'
Joint Photographers Expert Group (JPEG)
'pcx'
Windows Paintbrush (PCX)
'tif' or 'tiff'
Tagged Image File Format (TIFF)
'xwd'
X Windows Dump (XWD)
imwrite(X,map,filename,fmt) writes the indexed image in X, and its
associated colormap map, to filename. If X is of class uint8, imwrite writes the
actual values in the array to the file. If X is of class double, imwrite offsets the
values in the array before writing, using uint8(X–1). map must be of class
double; imwrite rescales the values in map using uint8(round(255*map)).
imwrite(...,filename) writes the image to filename, inferring the format to
use from the filename’s extension. The extension must be one of the legal
values for fmt.
2-237
imwrite
imwrite(...,Parameter,Value,...) specifies parameters that control
various characteristics of the output file. Parameters are currently supported
for HDF, JPEG, and TIFF files.
This table describes the available parameters for HDF files:
Parameter
Values
Default
'Compression'
One of these strings: 'none', 'rle',
'rle'
'jpeg'
'Quality'
A number between 0 and 100;
parameter applies only if
'Compression' is 'jpeg'; higher
numbers mean quality is better (less
image degradation due to
compression), but the resulting file
size is larger
75
'WriteMode'
One of these strings: 'overwrite',
'overwrite'
'append'
This table describes the available parameters for JPEG files:
2-238
Parameter
Values
Default
'Quality'
A number between 0 and 100; higher
numbers mean quality is better (less
image degradation due to
compression), but the resulting file
size is larger
75
imwrite
This table describes the available parameters for TIFF files:
Parameter
Values
Default
'Compression
'
One of these strings: 'none',
'packbits', 'ccitt'; 'ccitt' is
valid for binary images only
'ccitt' for
'Description
'
Any string; fills in the
ImageDescription field returned by
empty
binary images;
'packbits' for all
other images
imfinfo
This table summarizes the types of images that imwrite can write:
Format
Variants
BMP
8-bit and 24-bit uncompressed images
HDF
8-bit raster image datasets, with or without associated
colormap; 24-bit raster image datasets
JPEG
Baseline JPEG images
PCX
8-bit images
TIFF
Baseline TIFF images, including 1-bit, 8-bit, and 24-bit
uncompressed images; 1-bit, 8-bit, and 24-bit images with
packbit compression; 1-bit images with CCITT compression
XWD
8-bit ZPixmaps
Example
imwrite(X,map,'eggs.hdf','Compression','none','WriteMode','append')
See Also
imfinfo, imread
2-239
ishandle
Purpose
2ishandle
Determines if values are valid graphics object handles
Syntax
array = ishandle(h)
Description
array = ishandle(h) returns an array that contains 1’s where the elements
of h are valid graphics handles and 0’s where they are not.
Examples
Determine whether the handles previously returned by fill remain handles
of existing graphical objects:
X = rand(4); Y = rand(4);
h = fill(X,Y,'blue')
.
.
.
delete(h(3))
.
.
.
ishandle(h)
ans =
1
1
0
1
See Also
2-240
findobj
ishold
Purpose
2ishold
Return hold state
Syntax
k = ishold
Description
k = ishold returns the hold state of the current Axes. If hold is on k = 1, if
hold is off, k = 0.
Examples
ishold is useful in graphics M-files where you want to perform a particular
action only if hold is not on. For example, these statements set the view to 3-D
only if hold is off:
if ~ishold
view(3);
end
See Also
axes, figure, hold, newplot
2-241
legend
Purpose
2legend
Display a legend for an Axes
Syntax
legend('string1','string2',...)
legend(Strings)
legend(h,Strings)
legend('off')
legend(h,...)
legend(...,pos)
h = legend(...)
Description
legend places a legend on a graph. For each line in the plot, the legend shows
a sample of the line type, marker symbol, and color beside the text label you
specify. When plotting filled areas, the legend contains a sample of the face
color next to the text label. After the legend appears, you can move it using the
mouse.
legend('string1','string2',...) displays a legend in the current Axes
using the specified strings to label each set of data.
legend(Strings) adds a legend containing the rows of the matrix Strings as
labels. This is the same as legend(Strings(1,:),Strings(2,:),...).
legend(h,Strings) associates each row of the matrix Strings with the
corresponding graphics object in the vector h.
legend('off') removes the legend from the current Axes or the Axes
specified by h.
legend(h,...) specifies the legend for the Axes specified by h.
legend(...,pos) uses pos to determine where to place the legend.
• pos = –1 places the legend outside the Axes boundary on the right side.
• pos = 0 places the legend inside the Axes boundary, obscuring as few points
as possible.
• pos = 1 places the legend in the upper-right corner of the Axes (default).
• pos = 2 places the legend in the upper-left corner of the Axes.
• pos = 3 places the legend in the lower-left corner of the Axes.
2-242
legend
• pos = 4 places the legend in the lower-right corner of the Axes.
• pos = [XlowerLeft YlowerLeft] explicitly specifies the lower-left legend
position in normalized coordinates.
h = legend(...) returns a handle to the legend, which is an Axes graphics
object.
Remarks
legend associates strings with the objects in the Axes in the same order that
they are listed in the Axes Children property. By default, the legend annotates
the current Axes.
MATLAB displays only one legend per Axes. legend positions the legend based
on a variety of factors, such as what objects the legend obscures. You move the
legend by pressing the mouse button while the cursor is over the legend and
dragging the legend to a new location. If your mouse has more than one button,
you press the left mouse button.
2-243
legend
Examples
Add a legend to a graph showing a sine and cosine function:
x = –pi:pi/20:pi;
plot(x,cos(x),'−r',x,sin(x),'−.b')
h = legend('cos','sin',0);
1
cos
sin
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−4
−3
−2
−1
0
1
2
3
4
In this example, the plot command specifies a solid, red line ('−r') for the
cosine function and a dash-dot, blue line ('−.b') for the sine function.
See Also
2-244
LineSpec, plot
light
Purpose
2light
Create a Light object
Syntax
light('PropertyName',PropertyValue,...)
handle = light(...)
Description
light creates a Light object in the current Axes. Lights affect only Patch and
Surface object.
light('PropertyName',PropertyValue,...) creates a Light object using the
specified values for the named properties. MATLAB parents the Light to the
current Axes unless you specify another Axes with the Parent property.
Remarks
You cannot see a Light object per se, but you can see the effects of the light
source on Patch and Surface objects. You can also specify an Axes-wide ambient
light color that illuminates these objects. However, ambient light is visible only
when at least one Light object is present and visible in the Axes.
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see set and get for examples of how to specify these
data types).
See also the Patch and Surface AmbientStrength, DiffuseStrength,
SpecularStrength, SpecularExponent, SpecularColorReflectance, and
VertexNormals properties. Also see the lighting and material commands.
Examples
Light the peaks surface plot with a light source located at infinity and oriented
along the direction defined by the vector [1 0 0], that is, along the x-axis.
h = surf(peaks);
set(h,’FaceLighting’,’phong’,'FaceColor',’interp’,...
'AmbientStrength',0.5)
light('Position’,[1 0 0],’Style’,’infinite’);
2-245
light
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Light properties on the Axes, Figure, and Root levels:
set(0,'DefaultLightProperty',PropertyValue...)
set(gcf,'DefaultLightProperty',PropertyValue...)
set(gca,'DefaultLightProperty',PropertyValue...)
Where Property is the name of the Light property and PropertyValue is the
value you are specifying. Use set and get to access Light properties.
The following table lists all Light properties and provides a brief description of
each. The property name links take you to an expanded description of the
properties.
Property Name
Property Description
Property Value
Color
Color of the light produced by the
Light object
Values: ColorSpec
Position
Location of Light in the axes
Values: x-, y-, z-coordinates
in Axes units
Default: [1 0 1]
Style
Parallel or divergent light source
Values: infinite, local
Defining the Light
Controlling the Appearance
2-246
light
Property Name
Property Description
Property Value
SelectionHighlight
This property is not used by Light
objects
Values: on, off
Default: on
Visible
Make the effects of the Light visible
or invisible
Values: on, off
Default: on
Controlling Access to Objects
HandleVisibility
Determines if and when the the
Line’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Light objects do use this property
Values: on, off
Default: on
General Information About the Light
Children
Light objects have no children
Values: [] (empty matrix)
Parent
The parent of a Light object is always
an Axes object
Value: Axes handle
Selected
Light objects do use this property
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'light'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
Properties Related to Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
This property is not used by Light
objects
Values: string
Default: empty string
2-247
light
Property Name
Property Description
Property Value
CreateFcn
Define a callback routine that
executes when a Light is created
Values: string (command or
M-file name)
Default: empty string
DeleteFcn
Define a callback routine that
executes when the Light is deleted
(via close or delete)
Values: string (command or
M-file name)
Default: empty string
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
This property is not used by Light
objects
Values: handle of a
Uicontrextmenu
2-248
Light Properties
Light
Properties
2Light Properties
This section lists property names along with the type of values each accepts.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routes always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
This property is not useful on Lights.
Children
handles
The empty matrix; Light objects have no children.
Clipping
on | off
Clipping has no effect on Light objects.
Color
ColorSpec
Color of Light. This property defines the color of the light emanating from the
Light object. Define it as three-element RGB vector or one of MATLAB’s
predefined names. See the ColorSpec reference page for more information.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Light object. You must
define this property as a default value for Lights. For example, the statement,
set(0,'DefaultLightCreateFcn','set(gcf,''Colormap'',hsv)')
2-249
Light Properties
sets the current Figure colormap to hsv whenever you create a Light object.
MATLAB executes this routine after setting all Light properties. Setting this
property on an existing Light object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Light callback routine. A callback routine that executes when you delete
the Light object (i.e., when you issue a delete command or clear the Axes or
Figure containing the Light). MATLAB executes the routine before destroying
the object’s properties so these values are available to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaling a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
2-250
Light Properties
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
This property is not used by Light objects.
Interruptible
{on} | off
Callback routine interruption mode. Light object callback routines defined for
the DeleteFcn property are not affected by the Interruptible property.
Parent
handle of parent Axes
Light objects parent. The handle of the Light object’s parent Axes. You can
move a Light object to another Axes by changing this property to the new Axes
handle.
Position
[x,y,z] in Axes data units
Location of Light object. This property specifies a vector defining the location of
the Light object. The vector is defined from the origin to the specified x, y, and
z coordinates. The placement of the Light depends on the setting of the Style
property:
• If the Style property is set to local, Position specifies the actual location of
the Light (which is then a point source that radiates from the location in all
directions).
• If the Style property is set to infinite, Position specifies the direction from
which the light shines in parallel rays.
Selected
on | off
This property is not used by Light objects.
2-251
Light Properties
SelectionHighlight {on} | off
This property is not used by Light objects.
Style
{infinite} | local
Parallel or divergent light source. This property determines whether MATLAB
places the Light object at infinity, in which case the light rays are parallel, or
at the location specified by the Position property, in which case the light rays
diverge in all directions. See the Position property.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Type of graphics object. This property contains a string that identifies the class
of graphics object. For Light objects, Type is always 'light'.
UIContextMenu
handle of a uicontextmenu object
This property is not used by Light objects.
UserData
matrix
User specified data. This property can be any data you want to associate with
the Light object. The Light does not use this property, but you can access it
using set and get.
Visible
{on} | off
Light visibility. While Light objects themselves are not visible, you can see the
light on Patch and Surface objects. When you set Visible to off, the light
emanating from the source is not visible. There must be at least one Light
object in the Axes whose Visible property is on for any lighting features to be
enabled (including the Axes AmbientLightColor and Patch and Surface
AmbientStrength).
See Also
2-252
lighting, material, patch, surface
lightangle
Purpose
2lightangle
Create or position a Light object in spherical coordinates
Syntax
lightangle(az,el)
light_handle = lightangle(az,el)
lightangle(light_handle,az,el)
[ax el] = lightangle(light_handle)
Description
lightangle(az,el) creates a Light at the position specified by azimuth and
elevation. az is the azimuthal (horizontal) rotation and el is the vertical
elevation (both in degrees). The interpretation of azimuth and elevation is the
same as that of the view command.
light_handle = lightangle(az,el) creates a Light and returns the handle
of the light in light_handle.
lightangle(light_handle,az,el) sets the position of the Light specified by
light_handle.
[az,el] = lightangle(light_handle) returns the azimuth and elevation of
the Light specified by light_handle.
Remarks
Examples
See Also
By default, when a Light is created, its style is infinite. If the Light handle
passed into lightangle refers to a local light, the distance between the light
and the camera target is preserved as the position is changed.
surf(peaks)
axis vis3d
h = light;
for az = −50:10:50
lightangle(h,az,30)
drawnow
end
light, camlight, view
2-253
lighting
Purpose
2lighting
Select the lighting algorithm
Syntax
lighting
lighting
lighting
lighting
Description
lighting selects the algorithm used to calculate the effects of Light objects on
flat
gouraud
phong
none
all Surface and Patch objects in the current Axes.
lighting flat selects flat lighting.
lighting gouraund selects gouraud lighting.
lighting phong selects phong lighting.
lighting none turns off lighting.
Remarks
The surf, mesh, pcolor, fill, fill3, surface, and patch functions create
graphics objects that are affected by light sources. The lighting command sets
the FaceLighting and EdgeLighting properties of Surfaces and Patches
appropriately for the graphics object.
See Also
light, material, patch, surface
2-254
line
Purpose
2line
Create Line object
Syntax
line(X,Y)
line(X,Y,Z)
line(X,Y,Z,'PropertyName',PropertyValue,...)
line('PropertyName',PropertyValue,...) Formal–PN/PV pairs only
h = line(...)
Description
line creates a Line object in the current Axes. You can specify the color, width,
line style, and marker type, as well as other characteristics.
The line function has two forms:
• Automatic color and line style cycling. When you specify matrix coordinate
data using the informal syntax (i.e., the first three arguments are
interpreted as the coordinates),
line(X,Y,Z)
MATLAB cycles through the Axes ColorOrder and LineStyleOrder property
values the way the plot function does. However, unlike plot, line does not
call the newplot function.
• Purely low-level behavior. When you call line with only property name/
property value pairs,
line('XData',x,'YData',y,'ZData',z)
MATLAB draws a Line object in the current Axes using the default Line color
(see the colordef function for information on color defaults). Note that you
cannot specify matrix coordinate data with the low-level form of the line
function.
line(X,Y) adds the Line defined in vectors X and Y to the current Axes. If X
and Y are matrices of the same size, line draws one Line per column.
line(X,Y,Z) creates Lines in three-dimensional coordinates.
line(X,Y,Z,'PropertyName',PropertyValue,...) creates a Line using the
values for the property name/property value pairs specified and default values
for all other properties.
See the LineStyle and Marker properties for a list of supported values.
2-255
line
line('XData',x,'YData',y,'ZData',z,'PropertyName',PropertyValue,..
.) creates a Line in the current Axes using the property values defined as
arguments. This is the low-level form of the line function, which does not
accept matrix coordinate data as the other informal forms described above.
h = line(...) returns a column vector of handles corresponding to each Line
object the function creates.
Remarks
In its informal form, the line function interprets the first three arguments
(two for 2-D) as the X, Y, and Z coordinate data, allowing you to omit the
property names. You must specify all other properties as name/value pairs. For
example,
line(X,Y,Z,'Color','r','LineWidth',4)
The low-level form of the line function can have arguments that are only
property name/property value paris. For example,
line('XData',x,'YData',y,'ZData',z,'Color','r','LineWidth',4)
Line properties control various aspects of the Line object and are described in
the “Line Properties” section. You can also set and query property values after
creating the Line using set and get.
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see the set and get reference pages for examples of
how to specify these data types).
Unlike high-level functions such as plot, line does not respect the setting of
the Figure and Axes NextPlot properties. It simply adds Line objects to the
current Axes. However, Axes properties that are under automatic control such
as the axis limits can change to accommodate the Line within the current Axes.
Examples
This example uses the line function to add a shadow to plotted data. First, plot
some data and save the Line’s handle:
t = 0:pi/20:2*pi;
hline1 = plot(t,sin(t),’k’);
Next, add a shadow by offsetting the x coordinates. Make the shadow Line light
gray and wider than the default LineWidth:
hline2 = line(t+.06,sin(t),'LineWidth',4,'Color',[.8 .8 .8]);
2-256
line
Finally, pop the first Line to the front:
set(gca,'Children',[hline1 hline2])
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
1
2
3
4
5
6
7
Input Argument Dimensions – Informal Form
This statement reuses the one column matrix specified for ZData to produce two
lines, each having four points.
line(rand(4,2),rand(4,2),rand(4,1))
If all the data has the same number of columns and one row each, MATLAB
transposes the matrices to produce data for plotting. For example,
line(rand(1,4),rand(1,4),rand(1,4))
is changed to:
line(rand(4,1),rand(4,1),rand(4,1))
2-257
line
This also applies to the case when just one or two matrices have one row. For
example, the statement,
line(rand(2,4),rand(2,4),rand(1,4))
is equivalent to:
line(rand(4,2),rand(4,2),rand(4,1))
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Line properties on the Axes, Figure, and Root levels:
set(0,'DefaultLinePropertyName',PropertyValue,...)
set(gcf,'DefaultLinePropertyName',PropertyValue,...)
set(gca,'DefaultLinePropertyName',PropertyValue,...)
Where PropertyName is the name of the Line property and PropertyValue is
the value you are specifying. Use set and get to access Line properties.
The following table lists all Line properties and provides a brief description of
each. The property name links take you to an expanded description of the
properties.
2-258
line
Property Name
Property Description
Property Value
XData
The x-coordinates defining the Line
Values: vector or matrix
Default: [0 1]
YData
The y-coordinates defining the Line
Values: vector or matrix
Default: [0 1]
ZData
The z-coordinates defining the Line
Values: vector or matrix
Default: [] empty matrix
Data Defining the Object
Defining Line Styles and Markers
LineStyle
Select from five line styles.
Values: −, −−, :, −., none
Default: −
LineWidth
The width of the Line in points
Values: scalar
Default: 0.5 points
Marker
Marker symbol to plot at data points
Values: see Marker property
Default: none
MarkerEdgeColor
Color of marker or the edge color for
filled markers
Values: ColorSpec, none,
auto
Default: auto
MarkerFaceColor
Fill color for markers that are closed
shapes
Values: ColorSpec, none,
auto
Default: none
MarkerSize
Size of marker in points
Values: size in points
Default: 6
Clipping
Clipping to Axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the
Line (useful for animation)
Values: normal, none, xor,
background
Default: normal
Controlling the Appearance
2-259
line
Property Name
Property Description
Property Value
SelectionHighlight
Highlight Line when selected
(Selected property set to on)
Values: on, off
Default: on
Visible
Make the Line visible or invisible
Values: on, off
Default: on
Color
Color of the Line
ColorSpec
XData
The x-coordinates defining the Line
Values: vector or matrix
Default: [0 1]
YData
The y-coordinates defining the Line
Values: vector or matrix
Default: [0 1]
ZData
The z-coordinates defining the Line
Values: vector or matrix
Default: [] empty matrix
Data Defining the Object
Controlling Access to Objects
HandleVisibility
Determines if and when the the
Line’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Determines if the Line can become
the current object (see the Figure
CurrentObject property)
Values: on, off
Default: on
General Information About the Line
Children
Line objects have no children
Values: [] (empty matrix)
Parent
The parent of a Line object is always
an Axes object
Value: Axes handle
Selected
Indicate whether the Line is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
2-260
line
Property Name
Property Description
Property Value
Type
The type of graphics object (read
only)
Value: the string 'line'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
Properties Related to Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on over the Line
Values: string
Default: '' (empty string)
CreateFcn
Define a callback routine that
executes when an Line is created
Values: string
Default: '' (empty string)
DeleteFcn
Define a callback routine that
executes when the Line is deleted
(via close or delete)
Values: string
Default: '' (empty string)
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
Associate a context menu with the
Line
Values: handle of a
Uicontrextmenu
2-261
Line Properties
Line Properties
2Line Properties
This section lists property names along with the type of values each accepts.
Curly braces { } enclose default values.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routes always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is over the Line object. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
Children
vector of handles
The empty matrix; Line objects have no children.
Clipping
{on} | off
Clipping mode. MATLAB clips Lines to the Axes plot box by default. If you set
Clipping to off, Lines display outside the Axes plot box. This can occur if you
create a Line, set hold to on, freeze axis scaling (axis manual), and then create
a longer Line.
Color
ColorSpec
Line color. A three-element RGB vector or one of MATLAB’s predefined names,
specifying the Line color. See the ColorSpec reference page for more
information on specifying color.
2-262
Line Properties
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Line object. You must
define this property as a default value for Lines. For example, the statement,
set(0,'DefaultLineCreateFcn','set(gca,''LineStyleOrder'',''-.|--'')')
defines a default value on the Root level that sets the Axes LineStyleOrder
whenever you create a Line object. MATLAB executes this routine after setting
all Line properties. Setting this property on an existing Line object has no
effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Line callback routine. A callback routine that executes when you delete
the Line object (e.g., when you issue a delete command or clear the Axes or
Figure). MATLAB executes the routine before deleting the object’s properties
so these values are available to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and
erase Line objects. Alternative erase modes are useful for creating animated
sequences, where control of the way individual objects redraw is necessary to
improve performance and obtain the desired effect.
• normal (the default) — Redraw the affected region of the display, performing
the three-dimensional analysis necessary to ensure that all objects are
rendered correctly. This mode produces the most accurate picture, but is the
slowest. The other modes are faster, but do not perform a complete redraw
and are therefore less accurate.
• none – Do not erase the Line when it is moved or destroyed. While the object
is still visible on the screen after erasing with EraseMode none, you cannot
print it because MATLAB stores no information about its former location.
• xor – Draw and erase the Line by performing an exclusive OR (XOR) with
the color of the screen beneath it. This mode does not damage the color of the
2-263
Line Properties
objects beneath the Line. However, the Line’s color depends on the color of
whatever is beneath it on the display.
• background – Erase the Line by drawing it in the Axes’ background Color,
or the Figure background Color if the Axes Color is set to none. This
damages objects that are behind the erased Line, but Lines are always
properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints Figures as if the
EraseMode of all objects is normal. This means graphics objects created with
EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g.,
XORing a pixel color with that of the pixel behind it) and ignore
three-dimensional sorting to obtain greater rendering speed. However, these
techniques are not applied to the printed output.
You can use the MATLAB capture command or other screen capture
application to create an image of a Figure containing non-normal mode objects.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Line can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Line. If HiTest is off, clicking on
the Line selects the object below it (which maybe the Axes containing it).
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
2-264
Line Properties
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invoke a function that might
potentially damage the GUI (such as evaling a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it can not be
returned by functions which obtain handles by searching the object hierarchy
or querying handle propertes. This includes get, findobj, gca, gcf, gco,
newplot, cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Line callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine.
2-265
Line Properties
{−} | −− | : | −. | none
LineStyle
Line style. This property specifies the line style. The available line styles are:
Symbol
Line Style
−
solid line (default)
−−
dashed line
:
dotted line
−.
dash-dot line
none
no line
You can use LineStyle none when you want to place a marker at each point,
but do not want the points connected with a Line (see the Marker property).
LineWidth
scalar
The width of the Line object. Specify this value in points (1 point = 1/72 inch).
The default LineWidth is 0.5 points.
Marker
character (see table)
Marker symbol. The Marker property specifies marks that display at data
points. You can set values for the Marker property independently from the
LineStyle property. Supported markers include:
2-266
Marker Specifier
Description
+
plus sign
o
circle
*
asterisk
.
point
x
cross
s
square
d
diamond
Line Properties
Marker Specifier
Description
^
upward pointing triangle
v
downward pointing triangle
>
right pointing triangle
<
left pointing triangle
p
five-pointed star (pentagram)
h
six-pointed star (hexagram)
none
no marker (default)
MarkerEdgeColor
ColorSpec | none | {auto}
Marker edge color. The color of the marker or the edge color for filled markers
(circle, square, diamond, pentagram, hexagram, and the four triangles).
ColorSpec defines the color to use. none specifies no color, which makes
nonfilled markers invisible. auto sets MarkerEdgeColor to the same color as
the Line’s Color property.
MarkerFaceColor
ColorSpec | {none} | auto
Marker face color. The fill color for markers that are closed shapes (circle,
square, diamond, pentagram, hexagram, and the four triangles). ColorSpec
defines the color to use. none makes the interior of the marker transparent,
allowing the background to show through. auto sets the fill color to the Axes
color, or the Figure color, if the Axes Color property is set to none (which is the
factory default for Axes).
MarkerSize
size in points
Marker size. A scalar specifying the size of the marker, in points. The default
value for MarkerSize is six points (1 point = 1/72 inch). Note that MATLAB
draws the point marker (specified by the '.' symbol) at one-third the specified
size.
Parent
handle
Line’s parent. The handle of the Line object’s parent Axes. You can move a Line
object to another Axes by changing this property to the new Axes handle.
2-267
Line Properties
Selected
on | off
Is object selected. When this property is on. MATLAB displays selection
handles if the SelectionHighlight property is also on. You can, for example,
define the ButtonDownFcn to set this property, allowing users to select the
object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing handles at each vertex. When
SelectionHighlight is off, MATLAB does not draw the handles.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Class of graphics object. For Line objects, Type is always the string 'line'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Line. Assign this property the handle of a
Uicontextmenu object created in same Figure as the Line. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Line (Control-click on
Macintosh systems).
UserData
matrix
User-specified data. Any data you want to associate with the Line object.
MATLAB does not use this data, but you can access it using the set and get
commands.
Visible
{on} | off
Line visibility. By default, all Lines are visible. When set to off, the Line is not
visible, but still exists and you can get and set its properties.
2-268
Line Properties
XData
vector of coordinates
X-coordinates. A vector of x-coordinates defining the Line. YData and ZData
must have the same number of rows. (See “Examples”).
YData
vector or matrix of coordinates
Y-coordinates. A vector of y-coordinates defining the Line. XData and ZData
must have the same number of rows. (See “Examples”).
ZData
vector of coordinates
Z-coordinates. A vector of z-coordinates defining the Line. XData and YData
must have the same number of rows. (See “Examples”).
See Also
axes,newplot, plot, plot3
2-269
LineSpec
Purpose
2LineSpec
Description
LineSpec is an argument to plotting functions, such as plot, that defines three
Line specification syntax
components used to specify lines in MATLAB:
• Line style
• Color
• Marker symbol
For example,
plot(x,y,'−.ro')
plots y versus x using a dash-dot line (−.), colored red (r), and places circular
markers (o) at the data points. If you specify a marker, but no a linesytle,
MATLAB plots only the markers.
The following tables list the symbols you use to define the line style, color, and
marker. Specify these symbols (in any order) as a quoted string after the data
arguments.
Symbol
Line Style
Symbol
Line Style
−
solid line (default)
:
dotted line
−−
dashed line
−.
dash-dot line
Symbol
2-270
Color
Symbol
Color
y
yellow
g
green
m
magenta
b
blue
c
cyan
w
white
r
red
k
black
LineSpec
Related
Properties
Marker Specifier
Description
+
plus sign
o
circle
*
asterisk
.
point
x
cross
s
square
d
diamond
^
upward pointing triangle
v
downward pointing triangle
>
right pointing triangle
<
left pointing triangle
p
five-pointed star (pentagram)
h
six-pointed star (hexagram)
When using the plot and plot3 functions, you can also specify other
characteristics of lines using graphics properties:
• LineWidth – specifies the width (in points) of the line
• MarkerEdgeColor – specifies the color of the marker or the edge color forfilled
markers (circle, square, diamond, pentagram, hexagram, and the four
triangles).
• MarkerFaceColor – specifies the color of the face of filled markers.
• MarkerSize – specifies the size of the marker in points.
In addition, you can specify the LineStyle, Color, and Marker properties
instead of using the symbol string. This is useful if you want to specific a color
that is not in the list by using RGB values. See the ColorSpec for more
information on color.
2-271
LineSpec
Examples
Plot the sine function over three different ranges using different line styles,
colors, and markers:
t = 0:pi/20:2*pi;
plot(t,sin(t),'−.r*')
hold on
plot(sin(t−pi/2),’−− mo’)
plot(sin(t−pi),’:bs’)
hold off
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
5
10
15
20
25
30
35
40
Create a plot illustrating how to set line graphics properties:
plot(t,sin(2*t),’−mo’,...
’LineWidth’,2,...
’MarkerEdgeColor’,’k’,...
’MarkerFaceColor’,[.49 1 .63],...
’MarkerSize’,12)
2-272
45
LineSpec
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
See Also
0
1
2
3
4
5
6
7
line, plot, surface, patch, Axes LineStyleOrder propert.
2-273
loglog
Purpose
2loglog
Log-log scale plot
Syntax
loglog(Y)
loglog(X1,Y1,...)
loglog(X1,Y1,LineSpec,...)
loglog(...,'PropertyName',PropertyValue,...)
h = loglog(...)
Description
loglog(Y) plots the columns of Y versus their index if Y contains real numbers.
If Y contains complex numbers, loglog(Y) and loglog(real(Y),imag(Y)) are
equivalent. loglog ignores the imaginary component in all other uses of this
function.
loglog(X1,Y1,...) plots all Xn versus Yn pairs. If only Xn or Yn is a matrix,
loglog plots the vector argument versus the rows or columns of the matrix,
depending on whether the vector’s row or column dimension matches the
matrix.
loglog(X1,Y1,LineSpec,...) plots all lines defined by the Xn,Yn,LineSpec
triples, where LineSpec determines line type, marker symbol, and color of the
plotted lines. You can mix Xn,Yn,LineSpec triples with Xn,Yn pairs, for
example,
loglog(X1,Y1,X2,Y2,LineSpec,X3,Y3)
loglog(...,'PropertyName',PropertyValue,...) sets property values for
all Line graphics objects created by loglog. See the line reference page for
more information.
h = loglog(...) returns a column vector of handles to Line graphics objects,
one handle per Line.
Remarks
2-274
If you do not specify a color when plotting more than one Line, loglog
automatically cycles through the colors and line styles in the order specified by
the current Axes.
loglog
Examples
Create a simple loglog plot with square markers:
x = logspace(−1,2);
loglog(x,exp(x),'−s')
grid on
45
10
40
10
35
10
30
10
25
10
20
10
15
10
10
10
5
10
0
10
−1
10
See Also
0
10
1
10
2
10
line, LineSpec, plot, semilogx, semilogy
2-275
loglog
2-276
material
Purpose
2material
Controls the reflectance properties of Surfaces and Patches
Syntax
material shiny
material dull
material metal
material([ka kd ks])
material([ka kd ks n])
material([ka kd ks n sc])
material default
Description
material sets the lighting characteristics of Surface and Patch objects.
material shiny sets the reflectance properties so that the object has a high
specular reflectance relative the diffuse and ambient light and the color of the
specular light depends only on the color of the light source.
material dull sets the reflectance properties so that the object reflects more
diffuse light, has no specular highlights, but the color of the reflected light
depends only on the light source.
material metal sets the reflectance properties so that the object has a very
high specular reflectance, very low ambient and diffuse reflectance, and the
color of the reflected light depends on both the color of the light source and the
color of the object.
material([ka kd ks]) sets the ambient/diffuse/specular strength of the
objects.
material([ka kd ks n]) sets the ambient/diffuse/specular strength and
specular exponent of the objects.
material([ka kd ks n sc]) sets the ambient/diffuse/specular strength,
specular exponent, and specular color reflectance of the objects.
material metal sets the ambient/diffuse/specular strength, specular
exponent, and specular color reflectance of the objects to their defaults.
Remarks
The material command sets the AmbientStrength, DiffuseStrength,
SpecularStrength, SpecularExponent, and SpecularColorReflectance
2-277
material
properties of all Surface and Patch objects in the Axes. There must be visible
Light objects in the Axes for lighting to be enabled. Look at the materal.m
M-file to see the actual values set (enter the command: type material).
See Also
2-278
light, lighting, patch, surface
mesh, meshc, meshz
Purpose
2mesh, meshc, meshz
Mesh plots
Syntax
mesh(X,Y,Z)
mesh(Z)
mesh(...,C)
meshc(...)
meshz(...)
h = mesh(...)
h = meshc(...)
h = meshz(...)
Description
mesh, meshc, and meshz create wireframe parametric surfaces specified by X, Y,
and Z, with color specified by C.
mesh(X,Y,Z) draws a wireframe mesh with color determined by Z, so color is
proportional to surface height. If X and Y are vectors, length(X) = n and
length(Y) = m, where [m,n] = size(Z). In this case, ( X ( j ), Y ( i ), Z ( i, j ) )
are the intersections of the wireframe grid lines; X and Y correspond to the
columns and rows of Z, respectively. If X and Y are matrices,
( X ( i, j ), Y ( i, j ), Z ( i, j ) )
are the intersections of the wireframe grid lines.
mesh(Z) draws a wireframe mesh using X = 1:n and Y = 1:m, where [m,n] =
size(Z). The height, Z, is a single-valued function defined over a rectangular
grid. Color is proportional to surface height.
mesh(...,C) draws a wireframe mesh with color determined by matrix C.
MATLAB performs a linear transformation on the data in C to obtain colors
from the current colormap. If X, Y, and Z are matrices, they must be the same
size as C.
meshc(...) draws a contour plot beneath the mesh.
meshz(...) draws a curtain plot (i.e., a reference plane) around the mesh.
h = mesh(...), h = meshc(...), and h = meshz(...) return a handle to a
Surface graphics object.
Remarks
A mesh is drawn as a Surface graphics object with the viewpoint specified by
view(3). The face color is the same as the background color (to simulate a
2-279
mesh, meshc, meshz
wireframe with hidden-surface elimination), or none when drawing a standard
see-through wireframe. The current colormap determines the edge color. The
hidden command controls the simulation of hidden-surface elimination in the
mesh, and the shading command controls the shading model.
Examples
Produce a combination mesh and contour plot of the peaks surface:
[X,Y] = meshgrid(–3:.125:3);
Z = peaks(X,Y);
meshc(X,Y,Z);
axis([–3 3 –3 3 –10 5])
5
0
−5
−10
3
2
1
0
−1
−2
−3
2-280
−3
−2
−1
0
1
2
3
mesh, meshc, meshz
Generate the curtain plot for the peaks function:
[X,Y] = meshgrid(–3:.125:3);
Z = peaks(X,Y);
meshz(X,Y,Z)
10
5
0
−5
−10
4
2
0
−2
−4
Algorithm
−3
−2
−1
0
1
2
3
The range of X, Y, and Z, or the current setting of the Axes XLimMode, YLimMode,
and ZLimMode properties determine the axis limits. axis sets these properties.
The range of C, or the current setting of the Axes CLim and CLimMode properties
(also set by the caxis function), determine the color scaling. The scaled color
values are used as indices into the current colormap.
The mesh rendering functions produce color values by mapping the z data
values (or an explicit color array) onto the current colormap. MATLAB’s default
behavior computes the color limits automatically using the minimum and
maximum data values (also set using caxis auto). The minimum data value
maps to the first color value in the colormap and the maximum data value
maps to the last color value in the colormap. MATLAB performs a linear
transformation on the intermediate values to map them to the current
colormap.
2-281
mesh, meshc, meshz
meshc calls mesh, turns hold on, and then calls contour and positions the
contour on the x-y plane. For additional control over the appearance of the
contours, you can issue these commands directly. You can combine other types
of graphs in this manner, for example surf and pcolor plots.
meshc assumes that X and Y are monotonically increasing. If X or Y is irregularly
spaced, contour3 calculates contours using a regularly spaced contour grid,
then transforms the data to X or Y.
See Also
contour, hidden, meshgrid, surf, surfc, surfl, waterfall
The functions axis, caxis, colormap, hold, shading, and view all set graphics
object properties that affect mesh, meshc, and meshz.
For a discussion of parametric surfaces plots, refer to surf.
2-282
movie
Purpose
2movie
Play recorded movie frames
Syntax
movie(M)
movie(M,n)
movie(M,n,fps)
movie(h,...)
movie(h,M,n,fps,loc)
Description
movie plays the movie defined by a matrix whose columns are movie frames
(usually produced by getframe).
movie(M) plays the movie in matrix M once.
movie(M,n) plays the movie n times. If n is negative, each cycle is shown
forward then backward. If n is a vector, the first element is the number of times
the movie is played, and the second through last elements specify the order in
which to play the frames. For example, if M has three columns, n = [10 3 2 1]
plays the movie backwards 10 times.
movie(M,n,fps) plays the movie at fps frames per second. The default is 12
frames per second. Computers that cannot achieve the specified speed play as
fast as possible.
movie(h,...) plays the movie in the Figure or Axes identified by h.
movie(h,M,n,fps,loc) specifies a four-element location vector, [x y 0 0],
where the lower-left corner of the movie frame is anchored (only the first two
elements in the vector are used). The location is relative to the lower-left corner
of the Figure or Axes specified by handle and in units of pixels, regardless of
the object’s Units property.
Remarks
The movie function displays each frame as it loads the data into memory, and
then plays the movie. This eliminates long delays with a blank screen when you
load a memory-intensive movie. The movie’s load cycle is not considered one of
the movie repetitions.
2-283
movie
Examples
Animate the peaks function as you scale the values of Z:
Z = peaks;
surf(Z);
M = moviein(20);
% Freeze Axes limits
axis manual
set(gca,'nextplot','replacechildren');
% Record the movie
for j = 1:20
surf(sin(2∗pi∗j/20)∗Z,Z)
M(:,j) = getframe;
end
% Play the movie twenty times
movie(M,20)
See Also
2-284
getframe, moviein
moviein
Purpose
2moviein
Allocate matrix for movie frames
Syntax
M = moviein(n)
M = moviein(n,h)
M = moviein(n,h,rect)
Description
moviein allocates an appropriately sized matrix for the getframe function.
M = moviein(n) creates matrix M having n columns to store n frames of a
movie based on the size of the current Axes.
M = moviein(n,h) specifies a handle for a valid Figure or Axes graphics object
on which to base the memory requirement. You must use the same handle with
getframe. If you want to capture the axis
M = moviein(n,h,rect) specifies the rectangular area from which to copy the
bitmap, relative to the lower-left corner of the Figure or Axes graphics object
identified by h. rect = [left bottom width height], where left and bottom
specify the lower-left corner of the rectangle, and width and height specify the
dimensions of the rectangle. Components of rect are in pixel units. You must
use the same handle and rectangle with getframe.
Examples
Use moviein to allocate a matrix for the movie frames and getframe to create
the movie:
Z = peaks;
surf(Z);
M = moviein(20);
% Freeze Axes limits
axis manual
set(gca,'nextplot','replacechildren');
% Record the movie
for j = 1:20
surf(sin(2∗pi∗j/20)∗Z,Z)
M(:,j) = getframe;
end
% Play the movie twenty times
movie(M,20)
2-285
moviein
See Also
2-286
getframe, movie
newplot
Purpose
2newplot
Determine where to draw graphics objects
Syntax
newplot
h = newplot
Description
newplot prepares a Figure and Axes for subsequent graphics commands.
h = newplot prepares a Figure and Axes for subsequent graphics commands
and returns a handle to the current Axes.
Remarks
Use newplot at the beginning of high-level graphics M-files to determine which
Figure and Axes to target for graphics output. Calling newplot can change the
current Figure and current Axes. Basically, there are three options when
drawing graphics in existing Figures and Axes:
• Add the new graphics without changing any properties or deleting any
objects.
• Delete all existing objects whose handles are not hidden before drawing the
new objects.
• Delete all existing objects regardless of whether or not their handles are
hidden and reset most properties to their defaults before drawing the new
objects (refer to the following table for specific information).
The Figure and Axes NextPlot properties determine how nextplot behaves.
The following two tables describe this behavior with various property values.
2-287
newplot
First, newplot reads the current Figure’s NextPlot property and acts
accordingly:
NextPlot
What Happens
add
Draw to the current Figure without clearing any
graphics objects already present.
replacechildren
Remove all child objects whose HandleVisibility
property is set to on and reset Figure NextPlot
property to add.
This clears the current Figure and is equivalent to
issuing the clf command.
replace
Remove all child objects (regardless of the setting of
the HandleVisibility property) and reset Figure
properties to their defaults, except:
• NextPlot is reset to add regardless of user-defined
defaults)
• Position, Units, PaperPosition, and PaperUnits
are not reset
This clears and resets the current Figure and is
equivalent to issuing the clf reset command.
2-288
newplot
After newplot establishes which Figure to draw in, it reads the current Axes’
NextPlot property and acts accordingly:
NextPlot
Description
add
Draw into the current Axes, retaining all graphics
objects already present.
replacechildren
Remove all child objects whose HandleVisibility
property is set to on, but do not reset Axes properties.
This clears the current Axes like the cla command.
replace
Removes all child objects (regardless of the setting of
the HandleVisibility property) and resets Axes
properties to their defaults, except Position and
Units
This clears and resets the current Axes like the cla
reset command.
See Also
axes, cla, clf, figure, hold, ishold, reset
The NextPlot property for Figure and Axes graphics objects.
2-289
noanimate
Purpose
2noanimate
Change EraseMode of all objects to normal
Syntax
noanimate(state,fig_handle)
noanimate(state)
Description
noanimate(state,fig_handle) sets the EraseMode of all Image, Line, Patch
Surface, and Text graphics object in the specified Figure to normal. state can
be the following strings:
• 'save' – set the values of the EraseMode properties to normal for all the
appropriate objects in the designated Figure.
• 'restore' – restore the EraseMode properties to the previous values (i.e., the
values before calling noanimate with the 'save' argument).
noanimate(state) operates on the current Figure.
noanimate is useful if you want to print the Figure to a Tiff or JPEG format.
See Also
2-290
print
orient
Purpose
2orient
Set paper orientation for printed output
Syntax
orient
orient landscape
orient portrait
orient tall
orient(fig_handle), orient(simulink_model)
orient(fig_handle,orientation), orient(simulink_model,orientation)
Description
orient returns a string with the current paper orientation, either portrait,
landscape, or tall.
orient landscape sets the paper orientation of the current Figure to full-page
landscape, orienting the longest page dimension horizontally. The Figure is
centered on the page and scaled to fit the page with a 0.25 inch border.
orient portrait sets the paper orientation of the current Figure to portrait,
orienting the longest page dimension vertically. The portrait option returns
the page orientation to MATLAB’s default. (Note that the result of using the
portrait option is affected by changes you make to Figure properties. See the
“Algorithm” section for more specific information.)
orient tall maps the current Figure to the entire page in portrait
orientation, leaving a 0.25 inch border.
orient(fig_handle), orient(simulink_model) returns the current
orientation of the specified Figure or Simulink model.
orient(fig_handle,orientation), orient(simulink_model,orientation)
sets the orientation for the specified Figure or Simulink model to the specified
orientation (landscape, portrait, or tall).
Algorithm
orient sets the PaperOrientation, PaperPosition, and PaperUnits
properties of the current Figure. Subsequent print operations use these
properties. The result of using the portrait option can be affected by default
property values as follows:
• If the current Figure PaperType is the same as the default Figure PaperType
and the default Figure PaperOrientation has been set to landscape, then
2-291
orient
the orient portrait command uses the current values of PaperOrientation
and PaperPosition to place the Figure on the page.
• If the current Figure PaperType is the same as the default Figure PaperType
and the default Figure PaperOrientation has been set to landscape, then
the orient portrait command uses the default Figure PaperPosition with
the x, y and width, height values reversed (i.e., [y,x,height,width]) to position
the Figure on the page.
• If the current Figure PaperType is different from the default Figure
PaperType, then the orient portrait command uses the current Figure
PaperPosition with the x, y and width, height values reversed (i.e.,
[y,x,height,width]) to position the Figure on the page.
See Also
print, set
PaperOrientation, PaperPosition, PaperSize, PaperType, and PaperUnits
properties of Figure graphics objects.
2-292
pareto
Purpose
2pareto
Pareto chart
Syntax
pareto(Y)
pareto(Y,names)
pareto(Y,X)
H = pareto(...)
Description
Pareto charts display the values in the vector Y as bars drawn in descending
order.
pareto(Y) labels each bar with its element index in Y.
pareto(Y,names) labels each bar with the associated name in the string matrix
or cell array names.
pareto(Y,X) labels each bar with the associated value from X.
H = pareto(...) returns a combination of Patch and Line object handles.
See Also
hist, bar
2-293
patch
Purpose
2patch
Create Patch graphics object
Syntax
patch(X,Y,C)
patch(X,Y,Z,C)
patch(...'PropertyName',PropertyValue...)
patch('PropertyName',PropertyValue...) PN/PV pairs only
handle = patch(...)
Description
patch is the low-level graphics function for creating Patch graphics objects. A
Patch object is one or more polygons defined by the coordinates of its vertices.
You can specify the coloring and lighting of the Patch. See the “3-D Modeling”
chapter in Using MATLAB Graphics for more information on Patches.
patch(X,Y,C) adds the filled two-dimensional Patch to the current Axes. The
elements of X and Y specify the vertices of a polygon. If X and Y are matrices,
MATLAB draws one polygon per column. C determines the color of the Patch.
It can be a single ColorSpec, one color per face, or one color per vertex (see
“Remarks”). If C is a 1-by-3 vector, it is assumed to be an RGB triplet,
specifying a color directly.
patch(X,Y,Z,C) creates a Patch in three-dimensional coordinates.
patch(...'PropertyName',PropertyValue...) follows the X, Y, (Z), and C
arguments with property name/property value pairs to specify additional
Patch properties.
patch('PropertyName',PropertyValue,...) specifies all properties using
property name/property value pairs. This form enables you to omit the color
specification because MATLAB uses the default face color and edge color,
unless you explicitly assign a value to the FaceColor and EdgeColor
properties. This form also allows you to specify the Patch using the Faces and
Vertices properties instead of x-, y-, and z-coordinates. See the “Examples”
section for more information.
handle = patch(...) returns the handle of the Patch object it creates.
Remarks
2-294
Unlike high-level area creation functions, such as fill or area, patch does not
check the settings of the Figure and Axes NextPlot properties. It simply adds
the Patch object to the current Axes.
patch
If the coordinate data does not define closed polygons, patch closes the
polygons. The data can define concave or intersecting polygons. However, if the
edges of an individual Patch face intersect themselves, the resulting face may
or may not be completely filled. In the case, it is better to break up the face into
smaller polygons.
Specifying Patch Properties
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see the set and get reference pages for examples of how
to specify these data types).
There are two Patch properties that specify color:
• CData – use when specifying x-, y-, and z-coordinates (XData, YData, ZData).
• FaceVertexCData – use when specifying vertices and connection matrix
(Vertices and Faces).
The CData and FaceVertexCData properties accept color data as indexed or true
color (RGB) values. See the CData and FaceVertexCData property descriptions
for information on how to specify color.
Indexed color data can represent either direct indices into the colormap or
scaled values that map the data linearly to the entire colormap (see the caxis
function for more information on this scaling). The CDataMapping property
determines how MATLAB interprets indexed color data:
Color Specification
CData
Color Interpretation by MATLAB
FaceVertexCData
True Color
Indexed
Color Mapping
(CDataMapping)
direct
scaled
2-295
patch
Color Data Interpretation
You can specify Patch colors as:
• A single color for all faces
• One color for each face enabling flat coloring
• One color for each vertex enabling interpolated coloring
The following tables summarize how MATLAB interprets color data defined by
the CData and FaceVertexCData properties.
Interpretation of the CData Property
[X,Y,Z]Data
Dimensions
CData Required for
Indexed
True Color
Results Obtained
m-by-n
scalar
1-by-1-by-3
Use the single color specified for all Patch faces.
Edges can be only a single color.
m-by-n
1-by-n
(n >= 4)
1-by-n-by-3
Use one color for each Patch face. Edges can be only a
single color.
m-by-n
m-by-n
m-by-n-3
Assign a color to each vertex. Patch faces can be flat (a
single color) or interpolated. Edges can be flat or
interpolated.
Interpretation of the FaceVertexCData Property
Vertices
Faces
Results Obtained
Dimensions
FaceVertexCData
Required for
Indexed
True Color
Dimensions
m-by-n
k-by-3
scalar
1-by-3
Use the single color specified for all
Patch faces. Edges can be only a single
color.
m-by-n
k-by-3
k-by-1
k-by-3
Use one color for each Patch face. Edges
can be only a single color.
m-by-n
k-by-3
m-by-1
m-by-3
Assign a color to each vertex. Patch faces
can be flat (a single color) or
interpolated. Edges can be flat or
interpolated.
2-296
patch
Examples
This example creates a Patch object using two different methods:
• Specifying x-, y-, and z-coordinates and color data (XData, YData, ZData, and
CData properties).
• Specifying vertices, the connection matrix, and color data (Vertices, Faces,
FaceVertexCData, and FaceColor properties).
Specifying X, Y, and Z Coordinates
The first approach specifies the coordinates of each vertex. In this example, the
coordinate data defines two triangular faces, each having three vertices. Using
true color, the top face is set to white and the bottom face to gray:
x = [0 0;0 1;1 1];
y = [1 1;2 2;2 1];
z = [1 1;1 1;1 1];
tcolor(1,1,1:3) = [1 1 1];
tcolor(1,2,1:3) = [.7 .7 .7];
patch(x,y,z,tcolor)
2
1.9
V3
V5
V2
1.8
1.7
1.6
1.5
1.4
1.3
1.2
1.1
1
0
V1
V4
V6
0.2
0.4
0.6
0.8
1
Notice that each face shares two vertices with the other face (V1-V4 and V3-V5).
2-297
patch
Specifying Vertices and Faces
The Vertices property contains the coordinates of each unique vertex defining
the Patch. The Faces property specifies how to connect these vertices to form
each face of the Patch. For this example, two vertices share the same location
so you need to specify only four of the six vertices. Each row contains the x, y,
and z-coordinates of each vertex:
vert = [0 1 1;0 2 1;1 2 1;1 1 1];
There are only two faces, defined by connecting the vertices in the order
indicated:
fac = [1 2 3;1 3 4];
To specify the face colors, define a 2-by-3 matrix containing two RGB color
definitions:
tcolor = [1 1 1;.7 .7 .7];
With two faces and two colors, MATLAB can color each face with flat shading.
This means you must set the FaceColor property to flat, since the faces/
vertices technique is available only as a low-level function call (i.e., only by
specifying property name/property value pairs).
Create the Patch by specifying the Faces, Vertices, and FaceVertexCData
properties as well as the FaceColor property :
patch('faces',fac,'vertices',vert,'FaceVertexCData',tcolor,...
'FaceColor','flat')
2-298
patch
V22
V3
1.9
1.8
1.7
Face 1
1.6
1.5
1.4
1.3
Face 2
1.2
1.1
1
V1 0
0.2
0.4
0.6
0.8
1
V4
Specifying only unique vertices and their connection matrix can reduce the size
of the data for Patches having many faces. See the descriptions of the Faces,
Vertices, and FaceVertexCData properties for information on how to define
them.
MATLAB does not require each face to have the same number of vertices. In
cases where they do not, pad the Faces matrix with NaNs. To define a Patch
with faces that do not close, add one or more NaN to the row in the Vertices
matrix that defines the vertex you do not want connected.
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
2-299
patch
Setting Default Properties
You can set default Patch properties on the Axes, Figure, and Root levels:
set(0,'DefaultPatchPropertyName',PropertyValue...)
set(gcf,'DefaultPatchPropertyName',PropertyValue...)
set(gca,'DefaultPatchPropertyName',PropertyValue...)
Where PropertyName is the name of the Patch property and PropertyValue is
the value you are specifying. Use set and get to access Patch properties.
Property List
The following table lists all Patch properties and provides a brief description of
each. The property name links take you to an expanded description of the
properties.
Property Name
Property Description
Property Value
Connection matrix for Vertices
Values: m-by-n matrix
Default: [1,2,3]
Vertices
Matrix of x-, y-, and z-coordinates of
the vertices (used with Faces)
Values: matrix
Default: [0,1;1,1;0,0]
XData
The x-coordinates of the vertices of
the Patch
Values: vector or matrix
Default: [0;1;0]
YData
The y-coordinates of the vertices of
the Patch
Values: vector or matrix
Default: [1;1;0]
ZData
The z-coordinates of the vertices of
the Patch
Values: vector or matrix
Default: [] empty matrix
CData
Color data for use with the XData/
YData/ZData method
Values: scalar, vector, or
matrix
Default: [] empty matrix
CDataMapping
Controls mapping of CData to
colormap
Values: scaled, direct
Default: scaled
Data Defining the Object
Faces
Specifying Color
2-300
patch
Property Name
Property Description
Property Value
EdgeColor
Color of face edges
Values: ColorSpec, none,
flat, interp
Default: ColorSpec
FaceColor
Color of face
Values: ColorSpec, none,
flat, interp
Default: ColorSpec
FaceVertexCData
Color data for use with Faces/
Vertices method
Values: matrix
Default: [] empty matrix
MarkerEdgeColor
Color of marker or the edge color for
filled markers
auto
Values: ColorSpec, none,
Default: auto
MarkerFaceColor
Fill color for markers that are closed
shapes
Values: ColorSpec, none,
auto
Default: none
Controlling the Effects of Lights
AmbientStrength
Intensity of the ambient light
Values: scalar >=0 and <=1
Default: 0.3
BackFaceLighting
Controls lighting of faces pointing
away from camera
Values: unlit, lit,
reverselit
Default: reverselit
DiffuseStrength
Intensity of diffuse light
Values: scalar >=0 and <=1
Default: 0.6
EdgeLighting
Method used to light edges
Values: none, flat, gouraud,
phong
Default: none
FaceLighting
Method used to light edges
Values: none, flat, gouraud,
phong
Default: none
2-301
patch
Property Name
Property Description
Property Value
NormalMode
MATLAB-generated or user-specified Values: auto, manual
normal vectors
Default: auto
SpecularColorReflectance
Composit color of specularly reflected
light
Values: scalar 0 to 1
Default: 1
SpecularExponent
Harshness of specular reflection
Values: scalar >= 1
Default: 10
SpecularStrength
Intensity of specular light
Values: scalar >=0 and <=1
Default: 0.9
VertexNormals
Vertex normal vectors
Values: matrix
Defining Edges and Markers
LineStyle
Select from five line styles.
Values: −, −−, :, −., none
Default: −
LineWidth
The width of the edge in points
Values: scalar
Default: 0.5 points
Marker
Marker symbol to plot at data points
Values: see Marker property
Default: none
MarkerSize
Size of marker in points
Values: size in points
Default: 6
Clipping
Clipping to Axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the
Patch (useful for animation)
Values: normal, none, xor,
Highlight Patch when selected
(Selected property set to on)
Values: on, off
Default: on
Controlling the Appearance
SelectionHighlight
2-302
background
Default: normal
patch
Property Name
Property Description
Property Value
Visible
Make the Patch visible or invisible
Values: on, off
Default: on
Controlling Access to Objects
HandleVisibility
Determines if and when the the
Patch’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Determines if the Patch can become
the current object (see the Figure
CurrentObject property)
Values: on, off
Default: on
Controlling Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on over the Patch
Values: string
Default: '' (empty string)
CreateFcn
Define a callback routine that
executes when an Patch is created
Values: string
Default: '' (empty string)
DeleteFcn
Define a callback routine that
executes when the Patch is deleted
(via close or delete)
Values: string
Default: '' (empty string)
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
Associate a context menu with the
Patch
Values: handle of a
Uicontrextmenu
General Information About the Patch
Children
Patch objects have no children
Values: [] (empty matrix)
2-303
patch
Property Name
Property Description
Property Value
Parent
The parent of a Patch object is
always an Axes object
Value: Axes handle
Selected
Indicate whether the Patch is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'patch'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
2-304
Patch Properties
Patch
Properties
2Patch Properties
This section lists property names along with the type of values each accepts.
Curly braces { } enclose default values.
AmbientStrength
scalar >= 0 and <= 1
Strength of ambient light. This property sets the strength of the ambient light,
which is a nondirectional light source that illuminates the entire scene. You
must have at least one visible Light object in the Axes for the ambient light to
be visible. The Axes AmbientColor property sets the color of the ambient light,
which is therefore the same on all objects in the Axes.
You can also set the strength of the diffuse and specular contribution of Light
objects. See the DiffuseStrength and SpecularStrength properties.
BackFaceLighting
unlit | lit | {reverselit}
Face lighting control. This property determines how faces are lit when their
vertex normals point away from the camera.
• unlit – face is not lit
• lit – face lit in normal way
• reverselit – face is lit as if the vertex pointed towards the camera
This property is useful for discriminating between the internal and external
surfaces of an object. See the Using MATLAB Graphics manual for an example.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routes always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
2-305
Patch Properties
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is over the Patch object. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
CData
scalar, vector, or matrix
Patch colors. This property specifies the color of the Patch. You can specify
color for each vertex, each face, or a single color for the entire Patch. The way
MATLAB interprets CData depends on the type of data supplied. The data can
be numeric values that are scaled to map linearly into the current colormap,
integer values that are used directly as indices into the current colormap, or
arrays of RGB values. RGB values are not mapped into the current colormap,
but interpreted as the colors defined. On true color systems, MATLAB uses the
actual colors defined by the RGB triples. On pseudocolor systems, MATLAB
uses dithering to approximate the RGB triples using the colors in the Figure’s
Colormap and Dithermap.
The following two diagrams illustrate the dimensions of CData with respect to
the coordinate data arrays, XData, YData, and ZData. The first diagram
illustrates the use of indexed color:
2-306
Patch Properties
One Color
Per Vertex
One Color
Per Face
Single Color
CData
CData
CData
[X,Y,Z]Data
[X,Y,Z]Data
F
a
c
e
1
F
a
c
e
2
F
a
c
e
3
F
a
c
e
4
F
a
c
e
5
[X,Y,Z]Data
2-307
Patch Properties
The second diagram illustrates the use of true color. True color requires
m-by-n-by-3 arrays to define red, green, and blue components for each color.
One Color
Per Face
Single Color
One Color
Per Vertex
CData
B
G
R
Blue
Green
B
G
Red
CData
R
[X,Y,Z]Data
CData
[X,Y,Z]Data
F
a
c
e
1
F
a
c
e
2
F
a
c
e
3
F
a
c
e
4
F
a
c
e
5
[X,Y,Z]Data
Note that if CData contains NaNs, MATLAB does not color the faces.
See also the Faces, Vertices, and FaceVertexCData properties for an
alternative method of Patch definition.
CDataMapping
{scaled} | direct
Direct or scaled color mapping. This property determines how MATLAB
interprets indexed color data used to color the Patch. (If you use true color
specification for CData or FaceVertexCData, this property has no effect.)
• scaled – transform the color data to span the portion of the colormap
indicated by the Axes CLim property, linearly mapping data values to colors.
See the caxis command for more information on this mapping.
• direct – use the color data as indices directly into the colormap. When not
scaled, the data are usually integer values ranging from 1 to
2-308
Patch Properties
length(colormap). MATLAB maps values less than 1 to the first color in the
colormap, and values greater than length(colormap) to the last color in the
colormap. Values with a decimal portion are fixed to the nearest, lower
integer.
Children
matrix of handles
Always the empty matrix; Patch objects have no children.
Clipping
{on} | off
Clipping to Axes rectangle. When Clipping is on, MATLAB does not display any
portion of the Patch outside the Axes rectangle.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Patch object. You
must define this property as a default value for Patches. For example, the
statement,
set(0,'DefaultPatchCreateFcn','set(gcf,''DitherMap'',my_dither_map)')
defines a default value on the Root level that sets the Figure DitherMap
property whenever you create a Patch object. MATLAB executes this routine
after setting all properties for the Patch created. Setting this property on an
existing Patch object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Patch callback routine. A callback routine that executes when you delete
the Patch object (e.g., when you issue a delete command or clear the Axes (cla)
or Figure (clf) containing the Patch). MATLAB executes the routine before
deleting the object’s properties so these values are available to the callback
routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
2-309
Patch Properties
DiffuseStrength
scalar >= 0 and <= 1
Intensity of diffuse light. This property sets the intensity of the diffuse
component of the light falling on the Patch. Diffuse light comes from Light
objects in the Axes.
You can also set the intensity of the ambient and specular components of the
light on the Patch object. See the AmbientStrength and SpecularStrength
properties.
EdgeColor
{ColorSpec} | none | flat | interp
Color of the Patch edge. This property determines how MATLAB colors the
edges of the individual faces that make up the Patch.
• ColorSpec – A three-element RGB vector or one of MATLAB’s predefined
names, specifying a single color for edges. The default edge color is black. See
ColorSpec for more information on specifying color.
• none – Edges are not drawn.
• flat – The color of each vertex controls the color of the edge that follows it.
This means flat edge coloring is dependent on the order you specify the
vertices:
Vertex controlling the
color of the following edge
• interp – Linear interpolation of the CData or FaceVertexCData values at the
vertices determines the edge color.
EdgeLighting
{none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm
used to calculate the effect of Light objects on Patch edges. Choices are:
• none – Lights do not affect the edges of this object.
• flat – The effect of Light objects is uniform across each edge of the Patch.
2-310
Patch Properties
• gouraud – The effect of Light objects is calculated at the vertices and then
linearly interpolated across the edge lines.
• phong – The effect of Light objects is determined by interpolating the vertex
normals across each edge line and calculating the reflectance at each pixel.
Phong lighting generally produces better results than Gouraud lighting, but
takes longer to render.
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and
erase Patch objects. Alternative erase modes are useful in creating animated
sequences, where control of the way individual objects redraw is necessary to
improve performance and obtain the desired effect.
• normal – Redraw the affected region of the display, performing the
three-dimensional analysis necessary to ensure that all objects are rendered
correctly. This mode produces the most accurate picture, but is the slowest.
The other modes are faster, but do not perform a complete redraw and are
therefore less accurate.
• none – Do not erase the Patch when it is moved or destroyed. While the object
is still visible on the screen after erasing with EraseMode none, you cannot
print it because MATLAB stores no information about its former location.
• xor– Draw and erase the Patch by performing an exclusive OR (XOR) with
each pixel index of the screen behind it. Erasing the Patch does not damage
the color of the objects behind it. However, Patch color depends on the color
of the screen behind it and is correctly colored only when over the Axes
background Color, or the Figure background Color if the Axes Color is set
to none.
• background – Erase the Patch by drawing it in the Axes’ background Color,
or the Figure background Color if the Axes Color is set to none. This
damages objects that are behind the erased Patch, but the Patch is always
properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints Figures as if the
EraseMode of all objects is normal. This means graphics objects created with
EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g.,
XORing a pixel color with that of the pixel behind it) and ignore
2-311
Patch Properties
three-dimensional sorting to obtain greater rendering speed. However, these
techniques are not applied to the printed output.
You can use the MATLAB capture command or other screen capture
application to create an image of a Figure containing non-normal mode objects.
FaceColor
{ColorSpec} | none | flat | interp
Color of the Patch face. This property can be any of the following:
• ColorSpec – A three-element RGB vector or one of MATLAB’s predefined
names, specifying a single color for faces. See ColorSpec for more
information on specifying color.
• none – Do not draw faces. Note that edges are drawn independently of faces.
• flat – The values of CData or FaceVertexCData determine the color for each
face in the Patch. The color data at the first vertex determines the color of
the entire face.
• interp – Bilinear interpolation of the color at each vertex determines the
coloring of each face.
FaceLighting
{none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm
used to calculate the effect of Light objects on Patch faces. Choices are:
• none – Lights do not affect the faces of this object.
• flat – The effect of Light objects is uniform across the faces of the Patch.
Select this choice to view faceted objects.
• gouraud – The effect of Light objects is calculated at the vertices and then
linearly interpolated across the faces. Select this choice to view curved
surfaces.
• phong – The effect of Light objects is determined by interpolating the vertex
normals across each face and calculating the reflectance at each pixel. Select
this choice to view curved surfaces. Phong lighting generally produces better
results than Gouraud lighting, but takes longer to render.
Faces
m-by-n matrix
Vertex connection defining each face. This property is the connection matrix
specifying which vertices in the Vertices property are connected. The Faces
matrix defines m faces with up to n vertices each. Each row designates the
2-312
Patch Properties
connections for a single face, and the number of elements in that row that are
not NaN defines the number of vertices for that face.
The Faces and Vertices properties provide an alternative way to specify a
Patch that can be more efficient than using x, y, and z coordinates in most
cases. For example, consider the following Patch. It is composed of eight
triangular faces defined by nine vertices:
Faces property Vertices property
V8
V7
2
V9
1.8
1.6
F5
F7
1.4
F6
1.2
F8
V5
V4 1
V6
0.8
F1
0.6
F3
F2
0.4
0
0
V1 V4 V55
V1 X1 Y1 Z1
F2
V1 V55 V2
V2 X2 Y2 Z2
F3
V2 V55 V6
V3 X3 Y3 Z3
F4
V2 V6 V3
V4 X4 Y4 Z4
F5
V4 V7 V8
F6
V4 V8 V75
F7 V5 V8 V9
F4
0.2
V1
F1
F8 5
V5 V9 V6
0.2
0.4
0.6
0.8
1
V2
1.2
1.4
1.6
1.8
2
V3
V5 X5 Y5 Z5
V6 X6 Y6 Z6
V7 X7 Y7 Z7
V8 X8 Y8 Z8
V9 X9 Y9 Z9
The corresponding Faces and Vertices properties are shown to the right of the
Patch. Note how some faces share vertices with other faces. For example, the
fifth vertex (V5) is used six times, once each by faces one, two, and three and
six, seven, and eight. Without sharing vertices, this same Patch requires 24
vertex definitions.
FaceVertexCData
matrix
Face and vertex colors. The FaceVertexCData property specifies the color of
Patches defined by the Faces and Vertices properties, and the values are used
when FaceColor, EdgeColor, MarkerFaceColor, or MarkerEdgeColor are set
appropriately. The interpretation of the values specified for FaceVertexCData
depends on the dimensions of the data:
For indexed colors, FaceVertexCData can be:
2-313
Patch Properties
• A single value, which applies a single color to the entire Patch
• An n-by-1 matrix, where n is the number of rows in the Faces property,
which specifies one color per face
• An n-by-1 matrix, where n is the number of rows in the Vertices property,
which specifies one color per vertex
For true colors, FaceVertexCData can be:
• A 1-by-3 matrix , which applies a single color to the entire Patch
• An n-by-3 matrix, where n is the number of rows in the Faces property,
which specifies one color per face
• An n-by-3 matrix, where n is the number of rows in the Vertices property,
which specifies one color per vertex
The following diagram illustrates the various forms of the FaceVertexCData
property for a Patch having eight faces and nine vertices. The CDataMapping
2-314
Patch Properties
property determines how MATLAB interprets the FaceVertexCData property
when you specify indexed colors.
FaceVertexCData
Indexed
One color
Single color per face
C
True color
One color
per vertex
Single color
R
G B
One color
per face
One color
per vertex
R1 G1 B1
R1 G1 B1
C1
C1
C2
C2
R2 G2 B2
R2 G2 B2
C3
C3
R3 G3 B3
R3 G3 B3
C4
C4
R4 G4 B4
R4 G4 B4
C5
C5
R5 G5 B5
R5 G5 B5
C6
C6
R6 G6 B6
R6 G6 B6
C7
C7
R7 G7 B7
R7 G7 B7
C8
C8
R8 G8 B8
R8 G8 B8
C9
HandleVisibility
R9 B9 B9
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
2-315
Patch Properties
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Patch can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Patch. If HiTest is off, clicking on
the Patch selects the object below it (which maybe the Axes containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Patch callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine. See the BusyAction property for
related information.
2-316
Patch Properties
{−} | −− | : | −. | none
LineStyle
Edge linestyle. This property specifies the line style of the Patch edges. The
available line styles are:
Symbol
Line Style
−
solid line (default)
−−
dashed line
:
dotted line
−.
dash-dot line
none
no line
You can use LineStyle none when you want to place a marker at each point but
do not want the points connected with a line (see the Marker property).
LineWidth
scalar
Edge line width. The width, in points, of the Patch edges (1 point = 1/72 inch).
The default LineWidth is 0.5 points.
Marker
character (see table)
Marker symbol. The Marker property specifies marks that locate vertices. You
can set values for the Marker property independently from the LineStyle
property. Supported markers include:
Marker Specifier
Description
+
plus sign
o
circle
*
asterisk
.
point
x
cross
s
square
2-317
Patch Properties
Marker Specifier
Description
d
diamond
^
upward pointing triangle
v
downward pointing triangle
>
right pointing triangle
<
left pointing triangle
p
five-pointed star (pentagram)
h
six-pointed star (hexagram)
none
no marker (default)
MarkerEdgeColor
ColorSpec | none | {auto} | flat
Marker edge color. The color of the marker or the edge color for filled markers
(circle, square, diamond, pentagram, hexagram, and the four triangles).
ColorSpec defines the color to use. none specifies no color, which makes
nonfilled markers invisible. auto sets MarkerEdgeColor to the same color as the
EdgeColor property.
MarkerFaceColor
ColorSpec | {none} | auto | flat
Marker face color. The fill color for markers that are closed shapes (circle,
square, diamond, pentagram, hexagram, and the four triangles). ColorSpec
defines the color to use. none makes the interior of the marker transparent,
allowing the background to show through. auto sets the fill color to the Axes
color, or the Figure color, if the Axes Color property is set to none.
MarkerSize
size in points
Marker size. A scalar specifying the size of the marker, in points. The default
value for MarkerSize is six points (1 point = 1/72 inch). Note that MATLAB
draws the point marker at 1/3 of the specified size.
NormalMode
{auto} | manual
MATLAB-generated or user-specified normal vectors. When this property is
auto, MATLAB calculates vertex normals based on the coordinate data. If you
2-318
Patch Properties
specify your own vertex normals, MATLAB sets this property to manual and
does not generate its own data. See also the VertexNormals property.
Parent
Axes handle
Patch’s parent. The handle of the Patch’s parent object. The parent of a Patch
object is the Axes in which it is displayed. You can move a Patch object to
another Axes by setting this property to the handle of the new parent.
Selected
on | {off}
Is object selected. When this property is on, MATLAB displays selection
handles or a dashed box (depending on the number of faces) if the
SelectionHighlight property is also on. You can, for example, define the
ButtonDownFcn to set this property, allowing users to select the object with the
mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by:
• Drawing handles at each vertex for a single-faced Patch.
• Drawing a dashed bounding box for a multi-faced Patch.
When SelectionHighlight is off, MATLAB does not draw the handles.
SpecularColorReflectancescalar in the range 0 to 1
Color of specularly reflected light. When this property is 0, the color of the
specularly reflected light depends on both the color of the object from which it
reflects and the color of the light source. When set to 1, the color of the
specularly reflected light depends only on the color or the light source (i.e., the
Light object Color property). The proportions vary linearly for values in
between.
SpecularExponent
scalar >= 1
Harshness of specular reflection. This property controls the size of the specular
spot. Most materials have exponents in the range of 5 to 20.
SpecularStrength
scalar >= 0 and <= 1
Intensity of specular light. This property sets the intensity of the specular
component of the light falling on the Patch. Specular light comes from Light
objects in the Axes.
2-319
Patch Properties
You can also set the intensity of the ambient and diffuse components of the
light on the Patch object. See the AmbientStrength and DiffuseStrength
properties.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines.
For example, suppose you use Patch objects to create borders for a group of
Uicontrol objects and want to change the color of the borders in a Uicontrol’s
callback routine. You can specify a Tag with the Patch definition:
patch(X,Y,'k','Tag','PatchBorder')
Then use findobj in the Uicontrol’s callback routine to obtain the handle of the
Patch and set its FaceColor property:
set(findobj('Tag','PatchBorder'),'FaceColor','w')
Type
string (read only)
Class of the graphics object. For Patch objects, Type is always the string
'patch'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Patch. Assign this property the handle of a
Uicontextmenu object created in the same Figure as the Patch. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Patch (Control-click on
Macintosh systems).
UserData
matrix
User-specified data. Any matrix you want to associate with the Patch object.
MATLAB does not use this data, but you can access it using set and get.
VertexNormals
matrix
Surface normal vectors. This property contains the vertex normals for the
Patch. MATLAB generates this data to perform lighting calculations. You can
2-320
Patch Properties
supply your own vertex normal data, even if it does not match the coordinate
data. This can be useful to produce interesting lighting effects.
Vertices
matrix
Vertex coordinates. A matrix containing the x-, y-, z-coordinates for each vertex.
See the Faces property for more information.
Visible
{on} | off
Patch object visibility. By default, all Patches are visible. When set to off, the
Patch is not visible, but still exists and you can query and set its properties.
XData
vector or matrix
X-coordinates. The x-coordinates of the points at the vertices of the Patch. If
XData is a matrix, each column represents the x-coordinates of a single face of
the Patch. In this case, XData, YData, and ZData must have the same
dimensions.
YData
vector or matrix
Y-coordinates. The y-coordinates of the points at the vertices of the Patch. If
YData is a matrix, each column represents the y-coordinates of a single face of
the Patch. In this case, XData, YData, and ZData must have the same
dimensions.
ZData
vector or matrix
Z-coordinates. The z-coordinates of the points at the vertices of the Patch. If
ZData is a matrix, each column represents the z-coordinates of a single face of
the Patch. In this case, XData, YData, and ZData must have the same
dimensions.
See Also
area, caxis, fill, fill3, surface
2-321
pbaspect
Purpose
2pbaspect
Set or query the plot box aspect ratio
Syntax
pbaspect
pbaspect([aspect_ratio])
pbaspect('mode')
pbaspect('auto')
pbaspect('manual')
pbaspect(axes_handle,...)
Description
The plot box aspect ratio determines the relative size of the x-, y-, and z-axes.
pbaspect with no arguments returns the plot box aspect ratio of the current
axes.
pbaspect([aspect_ratio]) sets the plot box aspect ratio in the current axes
to the specified value. Specify the aspect ratio as three relative values
representing the ratio of the x-, y-, and z-axes size. For example, a value of
[1 1 1] (the default) means the plot box is a cube (although with stretch-to-fill
enabled, it may not appear as a cube). See Remarks.
pbaspect('mode') returns the current value of the plot box aspect ratio mode,
which can be either auto (the default) or manual. See Remarks.
pbaspect('auto') sets the plot box aspect ratio mode to auto.
pbaspect('manual') sets the plot box aspect ratio mode to manual.
pbaspect(axes_handle,...) performs the set or query on the axes identified
by the first argument, axes_handle. If you do not specify an axes handle,
pbaspect operates on the current axes.
Remarks
pbaspect sets or queries values of the Axes object PlotBoxAspectRatio and
PlotBoxAspectRatioMode properties.
When the plot box aspect ratio mode is auto, MATLAB sets the ratio to
[1 1 1], but may change it to accommodate manual settings of the data aspect
ratio, camera view angle, or axis limits. See the Axes DataAspectRatio
property for a table listing the interactions between various properties.
2-322
pbaspect
Setting a value for the plot box aspect ratio or setting the plot box aspect ratio
mode to manual disables MATLAB’s stretch-to-fill feature (stretching of the
axes to fit the window). This means setting the plot box aspect ratio to its
current value,
pbaspect(pbaspect)
can cause a change it the way the graphs look. See the Remarks section of the
axes reference description and the “Aspect Ratio” section in the Using
MATLAB Graphics manual for a discussion of stretch-to-fill.
Examples
The following surface plot of the function z = xe ( – x – y ) is useful to illustrate
the plot box aspect ratio. First plot the function over the range
–2 ≤ x ≤ 2, –2 ≤ y ≤ 2,
2
2
[x,y] = meshgrid([-2:.2:2]);
z = x.*exp(-x.^2 - y.^2);
surf(x,y,z)
0.5
0
−0.5
2
1
2
1
0
0
−1
−1
−2
−2
Querying the plot box aspect ratio shows that the plot box is square:
pbaspect
ans =
1 1
1
2-323
pbaspect
It is also interesting to look at the data aspect ratio selected by MATLAB:
daspect
ans =
4 4
1
To illustrate the interaction between the plot box and data aspect ratios, set the
data aspect ratio to [1 1 1] and again query the plot box aspect ratio:
daspect([1 1 1])
0.5
0
−0.5
2
1.5
2
1
0.5
1
0
−0.5
0
−1
−1
−1.5
−2
pbaspect
ans =
4 4
2-324
1
−2
pbaspect
The plot box aspect ratio has changed to accommodate the specified data aspect
ratio. Now suppose you want the plot box aspect ratio to be [1 1 1] as well:
pbaspect([1 1 1])
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
2
2
1
1
0
0
−1
−1
−2
−2
Notice how MATLAB changed the axes limits because of the constraints
introduced by specifying both the plot box and data aspect ratios.
You can also use pbaspect to disable stretch-to-fill. For example, displaying
two subplots in one Figure can give surface plots a squashed appearance.
Disabling stretch-to-fill :
upper_plot = subplot(211);
surf(x,y,z)
lower_plot = subplot(212);
surf(x,y,z)
pbaspect(upper_plot,'manual')
2-325
pbaspect
0.5
0
−0.5
2
2
0
0
−2 −2
0.5
0
−0.5
2
1
0
−1
−2
See Also
−2
−1
0
1
2
axis, daspect, xlim, ylim, zlim
The Axes properties DataAspectRatio, PlotBoxAspectRatio, XLim, YLim, ZLim
The “Aspect Ratio” section in the Using MATLAB Graphics manual.
2-326
pcolor
Purpose
2pcolor
Pseudocolor plot
Syntax
pcolor(C)
pcolor(X,Y,C)
h = pcolor(...)
Description
A pseudocolor plot is a rectangular array of cells with colors determined by C.
MATLAB creates a pseudocolor plot by using each set of four adjacent points in
C to define a Surface patch (i.e., cell).
pcolor(C) draws a pseudocolor plot. The elements of C are linearly mapped to
an index into the current colormap. The mapping from C to the current
colormap is defined by colormap and caxis.
pcolor(X,Y,C) draws a pseudocolor plot of the elements of C at the locations
specified by X and Y. The plot is a logically rectangular, two-dimensional grid
with vertices at the points [X(i,j), Y(i,j)]. X and Y are vectors or matrices
that specify the spacing of the grid lines. If X and Y are vectors, X corresponds
to the columns of C and Y corresponds to the rows. If X and Y are matrices, they
must be the same size as C.
h = pcolor(...) returns a handle to a Surface graphics object.
Remarks
A pseudocolor plot is a flat Surface plot viewed from above. pcolor(X,Y,C) is
the same as viewing surf(X,Y,0∗Z,C) using view([0 90]).
When you use shading faceted or shading flat, the constant color of each cell
is the color associated with the corner having the smallest x-y coordinates.
Therefore, C(i,j) determines the color of the cell in the ith row and jth column.
The last row and column of C are not used.
When you use shading interp, each cell’s color results from a bilinear
interpolation of the colors at its four vertices and all elements of C are used.
2-327
pcolor
Examples
A Hadamard matrix has elements that are +1 and –1. A colormap with only two
entries is appropriate when displaying a pseudocolor plot of this matrix:
pcolor(hadamard(20))
colormap(gray(2))
axis ij
axis square
2
4
6
8
10
12
14
16
18
20
2-328
2
4
6
8
10
12
14
16
18
20
pcolor
A simple color wheel illustrates a polar coordinate system:
n = 6;
r = (0:n)'/n;
theta = pi∗(–n:n)/n;
X = r∗cos(theta);
Y = r∗sin(theta);
C = r∗cos(2∗theta);
pcolor(X,Y,C)
axis equal tight
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−1
−0.5
0
0.5
1
Algorithm
The number of vertex colors for pcolor(C) is the same as the number of cells
for image(C). pcolor differs from image in that pcolor(C) specifies the colors
of vertices, which are scaled to fit the colormap; changing the Axes clim
property changes this color mapping. image(C) specifies the colors of cells and
directly indexes into the colormap without scaling. Additionally,
pcolor(X,Y,C) can produce parametric grids, which is not possible with image.
See Also
caxis, image, mesh, shading, surf, view
2-329
peaks
Purpose
Syntax
2peaks
A sample function of two variables.
Z
Z
Z
Z
=
=
=
=
peaks;
peaks(n);
peaks(V);
peaks(X,Y);
peaks;
peaks(N);
peaks(V);
peaks(X,Y);
[X,Y,Z] = peaks;
[X,Y,Z] = peaks(n);
[X,Y,Z] = peaks(V);
Description
peaks is a function of two variables, obtained by translating and scaling
Gaussian distributions, which is useful for demonstrating mesh, surf, pcolor,
contour, etc.
Z = peaks; returns a 49-by-49 matrix.
Z = peaks(n); returns an n-by-n matrix.
Z = peaks(V); returns an n-by-n matrix, where n = length(V).
Z = peaks(X,Y); evaluates peaks at the given X and Y (which must be the same
size) and returns a matrix the same size.
peaks(...) (with no output argument), plots the peaks function with surf.
[X,Y,Z] = peaks(...); returns two additional matrices, X and Y, for
parametric plots, for example, surf(X,Y,Z,del2(Z)). If not given as input, the
underlying matrices X and Y are:
[X,Y] = meshgrid(V,V)
where V is a given vector, or V is a vector of length n with elements equally
spaced from −3 to 3. If no input argument is given, the default n is 49.
See Also
2-330
meshgrid, surf
pie
Purpose
2pie
Pie chart
Syntax
pie(X)
pie(X,explode)
h = pie(...)
Description
pie(X) draws a pie chart using the data in X. Each element in X is represented
as a slice in the pie chart.
pie(X,explode) offsets a slice from the pie. explode is a vector or matrix of
zeros and nonzeros that correspond to X. A non-zero value offsets the
corresponding slice from the center of the pie chart, so that X(i,j) is offset
from the center if explode(i,j) is nonzero. explode must be the same size as X.
h = pie(...) returns a vector of handles to Patch and Text graphics objects.
Remarks
The values in X are normalized via X/sum(X) to determine the area of each slice
of the pie. If sum(X)≤1, the values in X directly specify the are of the pie slices.
MATLAB draws only a partial pie if sum(X)<1.
2-331
pie
Examples
Emphasize the second slice in the chart by setting its corresponding explode
element to 1:
x = [1 3 0.5 2.5 2];
explode = [0 1 0 0 0];
pie(x,explode)
colormap jet
11%
22%
33%
28%
6%
See Also
2-332
pie3
pie3
Purpose
2pie3
Three-dimensional pie chart
Syntax
pie3(X)
pie3(X,explode)
h = pie3(...)
Description
pie3(X) draws a three-dimensional pie chart using the data in X. Each
element in X is represented as a slice in the pie chart.
pie3(X,explode) specifies whether to offset a slice from the center of the pie
chart. X(i,j) is offset from the center of the pie chart if explode(i,j) is
nonzero. explode must be the same size as X.
h = pie(...) returns a vector of handles to Patch, Surface, and Text graphics
objects.
Remarks
The values in X are normalized via X/sum(X) to determine the area of each slice
of the pie. If sum(X)≤1, the values in X directly specify the area of the pie slices.
MATLAB draws only a partial pie if sum(X)<1.
Examples
A slice in the pie chart is offset by setting the corresponding explode element
to 1:
x = [1 3 0.5 2.5 2]
explode = [0 1 0 0 0]
pie3(x,explode)
colormap hsv
22%
11%
28%
33%
6%
2-333
pie3
See Also
2-334
pie
plot
Purpose
2plot
Linear 2–D plot
Syntax
plot(Y)
plot(X1,Y1,...)
plot(X1,Y1,LineSpec,...)
plot(...,'PropertyName',PropertyValue,...)
h = plot(...)
Description
plot(Y) plots the columns of Y versus their index if Y is a real number. If Y is
complex, plot(Y) is equivalent to plot(real(Y),imag(Y)). In all other uses of
plot, the imaginary component is ignored.
plot(X1,Y1,...) plots all lines defined by Xn versus Yn pairs. If only Xn or Yn
is a matrix, the vector is plotted versus the rows or columns of the matrix,
depending on whether the vector’s row or column dimension matches the
matrix.
plot(X1,Y1,LineSpec,...) plots all lines defined by the Xn,Yn,LineSpec
triples, where LineSpec is a line specification that determines line type,
marker symbol, and color of the plotted lines. You can mix Xn,Yn,LineSpec
triples with Xn,Yn pairs: plot(X1,Y1,X2,Y2,LineSpec,X3,Y3)
plot(...,'PropertyName',PropertyValue,...) sets properties to the
specified property values for all Line graphics objects created by plot. (See the
“Examples” section for examples.)
h = plot(...) returns a column vector of handles to Line graphics objects,
one handle per Line.
Remarks
If you do not specify a color when plotting more than one line, plot
automatically cycles through the colors in the order specified by the current
Axes ColorOrder property. After cycling through all the colors defined by
ColorOrder, plot then cycles through the line styles defined in the Axes
LineStyleOrder property.
Note that by default, MATLAB resets the ColorOrder and LineStyleOrder
properties each time you call plot. If you want changes you make to these
2-335
plot
properties to persist, then you must define these changes as default values. For
example,
set(0,'DefaultAxesColorOrder',[0 0 0],...
'DefaultAxesLineStyleOrder','-|-.|--|:')
sets the default ColorOrder to use only the color black and sets the
LineStyleOrder to use solid, dash-dot, dash-dash, and dotted line styles.
See the “Axes” chapter in the Using MATLAB Graphics manual for more
information on the color of lines used for plotting. See axes for a list of
properties. See LineSpec for more information on specifying line styles and
colors. See set and get and the Using MATLAB Graphics manual for
information on default properties.
Examples
Plotting Only the Data Points
Suppose you have two vectors:
X = 0:pi/15:4*pi;
Y = exp(2*cos(X));
2-336
plot
plot(X,Y,'b+') plots a blue plus sign at each data point:
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
Plotting Data Points with Connecting Lines
plot(X,Y,'r–',X,Y,'ko') plots a solid red line and circular markers with
black edges at each data point:
2-337
plot
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
Specifying Line Styles
Line styles and markers allow you to discriminate different data sets on the
same plot when color is not available. For example, these statements
X = 0:pi/15:4*pi;
Y1 = exp(2*cos(X));
Y2 = exp(2*sin(X));
plot(X,Y1,'−k*',X,Y2,'−.ko')
create a graph using solid and dash-dot lines as well as different marker
symbols:
2-338
plot
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
Specifying the Color and Size of Markers
You can also specify other line characteristics using graphics properties (see
line for a description of these properties):
• LineWidth – specifies the width (in points) of the line
• MarkerEdgeColor – specifies the color of the marker or the edge color for
filled markers (circle, square, diamond, pentagram, hexagram, and the four
triangles).
• MarkerFaceColor – specifies the color of the face of filled markers.
• MarkerSize – specifies the size of the marker in units of points.
2-339
plot
For example, these statements,
x = −pi:pi/10:pi;
y = tan(sin(x)) − sin(tan(x));
plot(x,y,'−− rs','LineWidth',2,...
'MarkerEdgeColor','k',...
'MarkerFaceColor','g',...
'MarkerSize',10)
produce this graph:
3
2
1
0
−1
−2
−3
−4
−3
−2
−1
0
1
2
3
4
Specifying Tick Mark Location and Labeling
You can adjust the axis tick-mark locations and the labels appearing at each
tick. For example, this plot of the sine function relabels the x-axis with more
meaningful values:
x = −pi:.1:pi;
y = sin(x);
plot(x,y)
set(gca,'XTick',−pi:pi/2:pi)
set(gca,'XTickLabel',{'−pi','−pi/2','0','pi/2','pi'})
2-340
plot
Now add axis labels and annotate the point −pi/4, sin(−pi/4):
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−pi
−pi/2
0
pi/2
pi
Adding Titles, Axis Labels, and Annotations
MATLAB enables you to add axis labels and titles. For example, using the
graph from the previous example, add an x- and y-axis label:
xlabel('−\pi \leq \Theta \leq \pi')
ylabel('sin(\Theta)')
title('Plot of sin(\Theta)')
text(−pi/4,sin(−pi/4),'\leftarrow sin(−\pi\div4)',...
'HorizontalAlignment','left')
Now change the line color to red by first finding the handle of the Line object
created by plot and then setting its Color property. In the same statement, set
the LineWidth property to 2 points:
set(findobj(gca,'Type','line','Color',[0 0 1]),...
'Color','red',...
‘LineWidth',2)
2-341
plot
Plot of sin(Θ)
1
0.8
0.6
0.4
sin(Θ)
0.2
0
−0.2
−0.4
−0.6
← sin(−π÷4)
−0.8
−1
See Also
−pi
−pi/2
0
−π ≤ Θ ≤ π
pi/2
pi
axis, grid, line, LineSpec, loglog, plotedit, plotyy, semilogx, semilogy,
xlabel, xlim, ylabel, ylim, zlabel, zlim
See the text String property for a list of symbols and how to display them.
2-342
plot3
Purpose
2plot3
Linear 3-D plot
Syntax
plot3(X1,Y1,Z1,...)
plot3(X1,Y1,Z1,LineSpec,...)
plot3(...,'PropertyName',PropertyValue,...)
h = plot3(...)
Description
The plot3 function displays a three-dimensional plot of a set of data points.
plot3(X1,Y1,Z1,...), where X1, Y1, Z1 are vectors or matrices, plots one or
more lines in three-dimensional space through the points whose coordinates
are the elements of X1, Y1, and Z1.
plot3(X1,Y1,Z1,LineSpec,...) creates and displays all lines defined by the
Xn,Yn,Zn,LineSpec quads, where LineSpec is a line specification that
determines line style, marker symbol, and color of the plotted lines.
plot3(...,'PropertyName',PropertyValue,...) sets properties to the
specified property values for all Line graphics objects created by plot3.
h = plot3(...) returns a column vector of handles to Line graphics objects,
with one handle per Line.
Remarks
If one or more of X1, Y1, Z1 is a vector, the vectors are plotted versus the rows
or columns of the matrix, depending whether the vectors’ lengths equal the
number of rows or the number of columns.
You can mix Xn,Yn,Zn triples with Xn,Yn,Zn,LineSpec quads, for example,
plot3(X1,Y1,Z1,X2,Y2,Z2,LineSpec,X3,Y3,Z3)
See LineSpec and plot for information on line types and markers.
Examples
Plot a three-dimensional helix:
t = 0:pi/50:10∗pi;
plot3(sin(t),cos(t),t)
grid on
axis square
2-343
plot3
35
30
25
20
15
10
5
0
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
See Also
2-344
−1
axis, grid, line, LineSpec, loglog, plot, semilogx, semilogy
plotmatrix
Purpose
2plotmatrix
Draw scatter plots
Syntax
plotmatrix(X,Y)
plotmatrix(...,'LineSpec')
[H,AX,BigAx,P] = plotmatrix(...)
Description
plotmatrix(X,Y) scatter plots the columns of X against the columns of Y. If X
is p-by-m and Y is p-by-n, plotmatrix produces an n-by-m matrix of Axes.
plotmatrix(Y) is the same as plotmatrix(Y,Y) except that the diagonal is
replaced by hist(Y(:,i)).
plotmatrix(...,'LineSpec') uses a LineSpec to create the scatter plot.The
default is '.' (see LineSpec for possible values).
[H,AX,BigAx,P] = plotmatrix(...) returns a matrix of handles to the objects
created in H, a matrix of handles to the individual subaxes in AX, a handle to a
big (invisible) Axes that frames the subaxes in BigAx, and a matrix of handles
for the histogram plots in P. BigAx is left as the current Axes so that a
subsequent title, xlabel, or ylabel commands are centered with respect to
the matrix of Axes.
Examples
Generate plots of random data.
x = randn(50,3); y = x*[-1 2 1;2 0 1;1 -2 3;]';
plotmatrix(y,'*r')
2-345
plotmatrix
5
0
−5
10
5
0
−5
10
5
0
−5
−10
−5
See Also
2-346
0
scatter, scatter3
5
−5
0
5
10
−10
−5
0
5
10
plotyy
Purpose
2plotyy
Create graphs with y axes on both left and right side
Syntax
plotyy(X1,Y1,X2,Y2)
plotyy(X1,Y1,X2,Y2,'function')
plotyy(X1,Y1,X2,Y2,'function1','function2')
[AX,H1,H2] = plotyy(...)
Description
plotyy(X1,Y1,X2,Y2) plots X1 versus Y1 with y-axis labeling on the left and
plots X2 versus Y2 with y-axis labeling on the right.
plotyy(X1,Y1,X2,Y2,'function') uses the plotting function specified by the
string 'function' instead of plot to produce each graph. 'function' can be plot,
semilogx, semilogy, loglog, stem or any MATLAB function that accepts the
syntax:
h = function(x,y)
plotyy(X1,Y1,X2,Y2,'function1','function2') uses function1(X1,Y1) to
plot the data for the left axis and function1(X2,Y2) to plot the data for the
right axis.
[AX,H1,H2] = plotyy(...) returns the handles of the two Axes created in AX
and the handles of the graphics objects from each plot in H1 and H2. AX(1) is
the left Axes and AX(2) is the right Axes.
Examples
Create a graph using the plot function and two y-axes:
t = 0:pi/20:2*pi;
y1 = sin(t);
y2 = 0.5*sin(t-1.5);
plotyy(t,y1,t,y2,’plot’)
2-347
plotyy
1
0.5
0
0
−1
See Also
0
1
2
3
4
5
6
7
−0.5
plot, loglog, semilogx, semilogy, Axes properties: XAxisLocation,
YAxisLocation
The Axes chapter in the Using MATLAB Graphics manual for information on
multi-axis axes.
2-348
polar
Purpose
2polar
Plot polar coordinates
Syntax
polar(theta,rho)
polar(theta,rho,LineSpec)
Description
The polar function accepts polar coordinates, plots them in a Cartesian plane,
and draws the polar grid on the plane.
polar(theta,rho) creates a polar coordinate plot of the angle theta versus
the radius rho. theta is the angle from the x-axis to the radius vector specified
in radians; rho is the length of the radius vector specified in dataspace units.
polar(theta,rho,LineSpec) LineSpec specifies the line type, plot symbol,
and color for the lines drawn in the polar plot.
Examples
Create a simple polar plot using a dashed, red line:
t = 0:.01:2∗pi;
polar(t,sin(2∗t).∗cos(2∗t),'−− r')
90
0.5
60
120
0.375
150
30
0.25
0.125
180
0
210
330
240
300
270
2-349
polar
See Also
2-350
cart2pol, compass, LineSpec, plot, pol2cart, rose
print, printopt
Purpose
2print, printopt
Create hardcopy output
Syntax
print
print –devicetype –options filename
[pcmd,dev] = printopt
Description
print and printopt produce hardcopy output. All arguments to the print
command are optional. You can use them in any combination or order.
print sends the contents of the current Figure, including bitmap
representations of any user interface controls, to the printer using the device
and system print command defined by printopt.
print –devicetype specifies a device type, overriding the value returned by
printopt. The Devices section lists all supported device types.
print –options specifies print options that modify the action of the print
command. (For example, the –noui option suppresses printing of user interface
controls.) The Options section lists available options.
print filename directs the output to the file designated by filename. If
filename does not include an extension, print appends an appropriate
extension, depending on the device (e.g., .eps). If you omit filename, print
sends the file to the default output device (except for −dmeta and −dbitmap,
which place their output on the clipboard).
[pcmd,dev] = printopt returns strings containing the current
system-dependent print command and output device. printopt is an M-file
used by print to produce the hardcopy output. You can edit the M-file
printopt.m to set your default printer type and destination.
2-351
print, printopt
pcmd and dev are platform-dependent strings. pcmd contains the command that
print uses to send a file to the printer. dev contains the device option for the
print command. Their defaults are platform dependent.
Devices
Platform
pcmd
dev
UNIX
lpr –r –s
–dps2
VMS
PRINT/DELETE
–dps2
Windows
COPY /B %s LPT1:
–dwin
Macintosh
(not applicable)
–dps2
The table below lists device types supported by MATLAB’s built-in drivers.
Generally, Level 2 PostScript files are smaller and render more quickly when
printing than Level 1 PostScript files. However, not all PostScript printers
support Level 2, so determine the capabilities of your printer before using those
devices. Level 2 PostScript is the default for UNIX, VAX/VMS, and Macintosh
computers. You can change this default by editing the printopt.m file.
The TIFF image format is supported on all platforms by almost all word
processors for importing images. JPEG is a lossy highly compressed format
that is supported on all platforms for image processing and for inclusion into
HTML documents on the World Wide Web. To create these formats, MATLAB
renders the Figure using the Z-buffer rendering method and the resulting
pixmap is then saved to the specified file. You can specify the resolution of the
image using the −r resolution switch.
2-352
Device
Description
–dps
Level 1 black and white PostScript
–dpsc
Level 1 color PostScript
–dps2
Level 2 black and white PostScript
–dpsc2
Level 2 color PostScript
–deps
Level 1 black and white Encapsulated PostScript (EPS)
print, printopt
Device
Description
–depsc
Level 1 color Encapsulated PostScript (EPS)
–deps2
Level 2 black and white Encapsulated PostScript (EPS)
–depsc2
Level 2 color Encapsulated PostScript (EPS)
–dhpgl
HPGL compatible with HP 7475A plotter
–dill
Adobe Illustrator 88 compatible illustration file
–dmfile
M-file, and MAT-file when appropriate, containing Handle
Graphics commands to re-create the Figure and its children
–dtiff
24-bit RGB TIFF with packbits compression (Figures only)
–dtiffn
24-bit RGB TIFF with no compression (Figures only)
–djpeg
Baseline JPEG image, quality factor defaults to 75 (Figures
only)
–djpegnn
Baseline JPEG image with nn (0-100) quality factor
(Figures only)
This table lists additional devices supported via the Ghostscript
post-processor, which converts PostScript files into other formats. (This feature
is not available on Macintosh systems.)
Device
Description
–dlaserjet
HP LaserJet
–dljetplus
HP LaserJet+
–dljet2p
HP LaserJet IIP
–dljet3
HP LaserJet III
–ddeskjet
HP DeskJet and DeskJet Plus
–ddjet500
HP Deskjet 500
–dcdjmono
HP DeskJet 500C printing black only
2-353
print, printopt
2-354
Device
Description
–dcdjcolor
HP DeskJet 500C with 24 bit/pixel color and
high-quality color (Floyd-Steinberg) dithering
–dcdj500
HP DeskJet 500C
–dcdj550
HP Deskjet 550C
–dpaintjet
HP PaintJet color printer
–dpjxl
HP PaintJet XL color printer
–dpjetxl
HP PaintJet XL color printer
–dpjxl300
HP PaintJet XL300 color printer
–ddnj650c
HP DesignJet 650C
–dbj10e
Canon BubbleJet BJ10e
–dbj200
Canon BubbleJet BJ200
–dbjc600
Canon Color BubbleJet BJC-600 and BJC-4000
–dln03
DEC LN03 printer
–depson
Epson-compatible dot matrix printers (9- or 24-pin)
–depsonc
Epson LQ-2550 and Fujitsu 3400/2400/1200
–deps9high
Epson-compatible 9-pin, interleaved lines (triple
resolution)
–dibmpro
IBM 9-pin Proprinter
–dbmp256
8-bit (256-color) BMP file format
–dbmp16m
24-bit BMP file format
–dpcxmono
Monochrome PCX file format
–dpcx16
Older color PCX file format (EGA/VGA, 16-color)
–dpcx256
Newer color PCX file format (256-color)
print, printopt
Device
Description
–dpcx24b
24-bit color PCX file format, three 8-bit planes
–dpbm
Portable Bitmap (plain format)
–dpbmraw
Portable Bitmap (raw format)
–dpgm
Portable Graymap (plain format)
–dpgmraw
Portable Graymap (raw format)
–dppm
Portable Pixmap (plain format)
–dppmraw
Portable Pixmap (raw format)
This table summarizes additional devices available on Windows systems.
Device
Description
−dwin
Use Windows printing services (black and white)
−dwinc
Use Windows printing services (color)
–dmeta
Copy to clipboard in Enhanced Windows metafile format
(color)
–dbitmap
Copy to clipboard in Windows bitmap (BMP) format
(color)
–dsetup
Display Print Setup dialog box, but do not print
–v
Verbose mode to display Print dialog box (suppressed by
default)
2-355
print, printopt
This table summarizes additional devices available on Macintosh systems.
Options
2-356
Device
Description
–dpict
Create PICT file
–v
Verbose mode to display Print dialog box (suppressed by
default)
This table summarizes printing options that you can specify when you enter
the print command.
Option
Description
–tiff
Add color TIFF preview to Encapsulated PostScript
–loose
Use loose bounding box for EPS and PS devices
–cmyk
Use CMYK colors in PostScript instead of RGB
–append
Append to existing PostScript file without overwriting
–rnumber
Specify resolution in dots per inch
–adobecset
Use PostScript default character set encoding
–Pprinter
Specify printer to use (UNIX only)
–fhandle
Handle of a Figure graphics object to print (current
Figure by default; see gcf)
–swindowtitle
Name of SIMULINK system window to print (current
system by default; see gcs)
–painters
Render using painter’s algorithm
–zbuffer
Render using Z-buffer
–noui
Suppress printing of user interface controls
print, printopt
Paper Sizes
MATLAB supports a number of standard paper sizes. You can select from the
following list by setting the PaperType property of the Figure or selecting a
supported paper sizes from the print dialog box:
Property Value
Size (Width-by-Height)
usletter
8.5-by-11 inches
uslegal
11-by-14 inches
tabloid
11-by-17 inches
A0
841-by-1189mm
A1
594-by-841mm
A2
420-by-594mm
A3
297-by-420mm
A4
210-by-297mm
A5
148-by-210mm
B0
1029-by-1456mm
B1
728-by-1028mm
B2
514-by-728mm
B3
364-by-514mm
B4
257-by-364mm
B5
182-by-257mm
arch-A
9-by-12 inches
arch-B
12-by-18 inches
arch-C
18-by-24 inches
arch-D
24-by-36 inches
2-357
print, printopt
Printing Tips
Property Value
Size (Width-by-Height)
arch-E
36-by-48 inches
A
8.5-by-11 inches
B
11-by-17 inches
C
17-by-22 inches
D
22-by-34 inches
E
34-by-43 inches
This section includes information about specific printing issues.
Troubleshooting MS-Windows Printing
If you encounter problems such as segmentation violations , general protection
faults, application errors, or the output does not appear as you expect when
using MS-Windows printer drivers, try the following:
• If your printer is PostScript compatible, print with one of MATLAB’s built-in
PostScript drivers. There are various PostScript device options that you can
use with the print command: they all start with −dps, or −deps.
• The behavior you are experiencing may occur only with certain versions of
the print driver. Contact the print driver vendor for information on how to
obtain and install a different driver. If you are using Windows 95, try
installing the drivers that ship with the Windows 95 CD-ROM.
• Try printing with one of MATLAB’s built-in GhostScript devices. These
devices use GhostScript to convert PostScript files into other formats, such
as HP LaserJet, PCX, Canon BubbleJet, and so on.
• Copy the Figure as a Windows Metafile using the Edit-->CopyFigure menu
item on the Figure window menu or the print −dmeta option at the command
line. You can then import the file into another application for printing.
You can set copy options in the Figure’s File-->Preferences...-->Copying
Options dialog box. The Windows Metafile clipboard format produces a
better quality image than Windows Bitmap.
2-358
print, printopt
Printing Thick Lines on Windows95
Due to a limitation in Windows95, MATLAB is set up to print lines as either:
• Solid lines of the specified thickness (LineWidth)
• Thin (one pixel wide) lines with the specified line style (LineStyle)
If you create lines that are thicker than one pixel and use nonsolid line styles,
MATLAB prints these lines with the specified line style, but one pixel wide
(i.e., as thin lines).
However, you can change this behavior so that MATLAB prints thick, styled
lines as thick, solid lines by editing your matlab.ini file, which is in your
Windows directory. In this file, find the section:
[Matlab Settings]
and in this section change the assignment,
ThinLineStyles=1
to
ThinLineStyles=0
then restart MATLAB.
Printing MATLAB GUIs
You can generally obtain better results when printing a Figure window that
contains MATLAB uicontrols by setting these key properties:
• Set the Figure PaperPositionMode property to auto. This ensures the
printed version is the same size as the onscreen version. With
PaperPositionMode set to auto MATLAB does not resize the Figure to fit the
current value of the PaperPosition. This is particularly important if you
have specified a Figure ResizeFcn because if MATLAB resizes the Figure
during the print operation, the ResizeFcn is automatically called.
To set PaperPositionMode on the current Figure, use the command:
set(gcf,'PaperPositionMode','auto')
• Set the Figure InvertHardcopy property to off. By default, MATLAB
changes the Figure background color of printed output to white, but does not
change the color of Uicontrols. If you have set the background color to, for
2-359
print, printopt
example, match the gray of the GUI devices, you must set InvertHardcopy
to off to preserve the color scheme.
To set InvertHardcopy on the current Figure, use the command:
set(gcf,'InvertHardcopy','off')
• Use a color device if you want lines and text that are in color on the screen
to be written to the output file as colored objects. Black and white devices
convert colored lines and text to black or white to provide the best contrast
with the background and to aviod dithering.
• Use the print command’s −loose option to prevent MATLAB from using a
bounding box that is tightly wrapped around objects contained in the Figure.
This is important if you have intentionally used space between Uicontrols or
Axes and the edge of the Figure and you want to maintain this visual
appearance in the printed output.
Notes on Printing Interpolated Shading with PostScript Drivers
MATLAB can print Surface objects (such as graphs created with surf or mesh)
using interpolated colors. However, only Patch objects that are composed of
triangular faces can be printed using interpolated shading.
Printed output is always interpolated in RGB space, not in the colormap colors.
This means, if you are using indexed color and interpolated face coloring, the
printed output can look different from what is displayed on screen. See
“Interpolating in Indexed vs. Truecolor” in the Using MATLAB Graphics
manual for an illustration of each type of interpolation.
PostScript files generated for interpolated shading contain the color
information of the graphics object’s vertices and require the printer to perform
the interpolation calculations. This can take an excessive amount of time and
in some cases, printers may actually “time-out" before finishing the print job.
One solution to this problem is to interpolate the data and generate a greater
number of faces, which can then be flat shaded.
To ensure that the printed output matches what you see on the screen, print
using the -zbuffer option. To obtain higher resolution (for example, to make
text look better), use the −r option to increase the resolution. There is, however,
a trade-off between the resolution and the size of the created PostScript file,
which can be quite large at higher resolutions. The default resolution of 150 dpi
generally produces good results. You can reduce the size of the output file by
2-360
print, printopt
making the Figure smaller before printing it and setting the Figure
PaperPositionMode to auto, or by just setting the PaperPosition property to
a smaller size.
Note that in some UNIX environments, the default lpr command cannot print
files larger than 1 Mbyte unless you use the −s option, which MATLAB does
by default. See the lpr man page for more information.
Example
This example prints a surface plot with interploted shading. Setting the
current Figure’s (gcf) PaperPositionMode to auto enables you to resize the
Figure window and print it at the size you see on the screen. See Options and
the previous section for information on the −zbuffer and −r200 options.
surf(peaks)
shading interp
set(gcf,'PaperPositionMode','auto')
print −dpsc2 −zbuffer −r200
See Also
orient, figure
See the Using MATLAB Graphics manual for detailed information about
printing in MATLAB.
2-361
qtwrite
Purpose
2qtwrite
Write QuickTime movie file
Syntax
qtwrite(D,size,Map,'filename')
qtwrite(M,Map,'filename')
qtwrite(...,options)
Description
qtwrite(D,size,Map,'filename') writes the indexed image deck D with size
size and colormap Map to the QuickTime movie file 'filename'. If 'filename'
exists, it is replaced.
qtwrite(M,Map,'filename') writes the MATLAB movie matrix M with
colormap Map to the QuickTime movie file 'filename'.
qtwrite(...,options) sets the frame rate, spatial quality, and compressor
type:
Option
Description
options(1)
Frame rate in frames per second. The default is
10.
options(2)
Compressor type:
• 1 is video (default)
• 2 is jpeg
• 3 is animation
options(3)
Spatial quality:
• 1 - minimum
• 2 - low
• 3 - normal (default)
• 4 - high
• 5 - maximum
• 6 - lossless
Remarks
2-362
qtwrite requires QuickTime and works only on the Macintosh.
quiver
Purpose
2quiver
Quiver or velocity plot
Syntax
quiver(U,V)
quiver(X,Y,U,V)
quiver(...,scale)
quiver(...,LineSpec)
quiver(...,LineSpec,'filled')
h = quiver(...)
Description
A quiver plot displays vectors with components (u,v) at the points (x,y).
quiver(U,V) draws vectors specified by U and V at the coordinates defined by
x = 1:n and y = 1:m, where [m,n] = size(U) = size(V). This syntax plots U
and V over a geometrically rectangular grid. quiver automatically scales the
vectors based on the distance between them to prevent them from overlapping.
quiver(X,Y,U,V) draws vectors at each pair of elements in X and Y. If X and Y
are vectors, length(X) = n and length(Y) = m, where
[m,n] = size(U) = size(V). The vector X corresponds to the columns of U and
V, and vector Y corresponds to the rows of U and V.
quiver(...,scale) automatically scales the vectors to prevent them from
overlapping, then multiplies them by scale. scale = 2 doubles their relative
length and scale = 0.5 halves them. Use scale = 0 to plot the velocity vectors
without the automatic scaling.
quiver(...,LineSpec) specifies line style, marker symbol, and color using
any valid LineSpec. quiver draws the markers at the origin of the vectors.
quiver(...,LineSpec,'filled') fills markers specified by LineSpec.
h = quiver(...) returns a vector of Line handles.
Remarks
If X and Y are vectors, this function behaves as
[X,Y] = meshgrid(x,y)
quiver(X,Y,U,V)
2-363
quiver
Examples
Plot the gradient field of the function z = xe ( – x
2
– y2 )
:
[X,Y] = meshgrid(–2:.2:2);
Z = X.∗exp(–X.^2 – Y.^2);
[DX,DY] = gradient(Z,.2,.2);
contour(X,Y,Z)
hold on
quiver(X,Y,DX,DY)
colormap hsv
grid off
hold off
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−2
See Also
2-364
−1.5
−1
−0.5
0
contour, LineSpec, plot, quiver3
0.5
1
1.5
2
quiver3
Purpose
2quiver3
Three-dimensional velocity plot
Syntax
quiver3(Z,U,V,W)
quiver3(X,Y,Z,U,V,W)
quiver3(...,scale)
quiver3(...,LineSpec)
quiver3(...,LineSpec,'filled')
h = quiver3(...)
Description
A three-dimensional quiver plot displays vectors with components (u,v,w) at
the points (x,y,z).
quiver3(Z,U,V,W) plots the vectors at the equally spaced surface points
specified by matrix Z. quiver3 automatically scales the vectors based on the
distance between them to prevent them from overlapping.
quiver3(X,Y,Z,U,V,W) plots vectors with components (u,v,w) at the points
(x,y,z). The matrices X, Y, Z, U, V, W must all be the same size and contain the
corresponding position and vector components.
quiver3(...,scale) automatically scales the vectors to prevent them from
overlapping, then multiplies them by scale. scale = 2 doubles their relative
length and scale = 0.5 halves them. Use scale = 0 to plot the vectors without
the automatic scaling.
quiver3(...,LineSpec) specify line type and color using any valid LineSpec.
quiver3(...,LineSpec,'filled') fills markers specified by LineSpec.
h = quiver3(...) returns a vector of Line handles.
2-365
quiver3
Examples
Plot the surface normals of the function z = xe ( – x
2
– y2 ) :
[X,Y] = meshgrid(–2:0.25:2,–1:0.2:1);
Z = X.* exp(–X.^2 – Y.^2);
[U,V,W] = surfnorm(X,Y,Z);
quiver3(X,Y,Z,U,V,W,0.5);
hold on
surf(X,Y,Z);
colormap hsv
view(-35,45)
axis ([-2 2 -1 1 -.6 .6])
hold off
0.6
0.4
0.2
0
−0.2
−0.4
1
0.5
2
1
0
0
−0.5
−1
−1
See Also
2-366
−2
axis, contour, LineSpec, plot, plot3, quiver, surfnorm, view
refresh
Purpose
2refresh
Redraw current Figure
Syntax
refresh
refresh(h)
Description
refresh erases and redraws the current Figure.
refresh(h) redraws the Figure identified by h.
2-367
reset
Purpose
2reset
Reset graphics object properties to their defaults
Syntax
reset(h)
Description
reset(h) resets all properties having factory defaults on the object identified
by h. To see the list of factory defaults, use the statement,
get(0,'factory')
If h is a Figure, MATLAB does not reset Position, Units, PaperPosition, and
PaperUnits. If h is an Axes, MATLAB does not reset Position and Units.
Examples
reset(gca) resets the properties of the current Axes.
reset(gcf) resets the properties of the current Figure.
See Also
2-368
cla, clf, gca, gcf, hold
rgb2hsv
Purpose
2rgb2hsv
Convert RGB colormap to HSV colormap
Syntax
cmap = rgb2hsv(M)
Description
cmap = rgb2hsv(M) converts a RGB colormap, M, to a HSV colormap, cmap.
Both colormaps are m-by-3 matrices. The elements of both colormaps are in the
range 0 to 1.
The columns of the input matrix, M, represent intensities of red, green, and
blue, respectively. The columns of the output matrix, cmap, represent hue,
saturation, and value, respectively.
See Also
brighten, colormap, hsv2rgb,rgbplot
2-369
rgbplot
Purpose
2rgbplot
Plot colormap
Syntax
rgbplot(cmap)
Description
rgbplot(cmap) plots the three columns of cmap, where cmap is an m-by-3
colormap matrix. rgbplot draws the first column in red, the second in green,
and the third in blue.
Examples
Plot the RGB values of the copper colormap:
rgbplot(copper)
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
See Also
2-370
0
colormap
10
20
30
40
50
60
70
ribbon
Purpose
2ribbon
Ribbon plot
Syntax
ribbon(Y)
ribbon(X,Y)
ribbon(X,Y,width)
h = ribbon(...)
Description
ribbon(Y) plots the columns of Y as separate three-dimensional ribbons using
X = 1:size(Y,1).
ribbon(X,Y) plots X versus the columns of Y as three-dimensional strips. X
and Y are vectors of the same size or matrices of the same size. Additionally, X
can be a row or a column vector, and Y a matrix with length(X) rows.
ribbon(X,Y,width) specifies the width of the ribbons. The default is 0.75.
h = ribbon(...) returns a vector of handles to Surface graphics objects.
ribbon returns one handle per strip.
2-371
ribbon
Examples
Create a ribbon plot of the peaks function:
[x,y] = meshgrid(-3:.5:3,-3:.1:3);
z = peaks(x,y);
ribbon(y,z)
colormap hsv
10
5
0
−5
−10
4
2
15
0
10
−2
5
−4
See Also
2-372
plot, plot3, surface
0
root object
Purpose
2root object
Description
The Root is a graphics object that corresponds to the computer screen. There is
only one Root object and it has no parent. The children of the Root object are
Figures.
Root object properties
The Root object exists when you start MATLAB; you never have to create it and
you cannot destroy it. Use set and get to access the Root properties.
See Also
diary, echo, figure, format, gcf, get, set
Object
Hierarchy
Root
Figure
Property List
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
The following table lists all Root properties and provides a brief description of
each. The property name links take you to an expanded description of the
properties. This table does not include properties that are defined for, but not
used by the Root object.
Property Name
Property Description
Property Value
Information about MATLAB’s state
CallbackObject
Handle of object whose callback is
executing
Values: object handle
CurrentFigure
Handle of current Figure
Values: object handle
ErrorMessage
Text of last error message
Value: character string
2-373
root object
Property Name
Property Description
Property Value
PointerLocation
Current location of pointer
Values: x-, and y-coordinates
PointerWindow
Hanlde of window containing the
pointer
Values: Figure hanlde
ShowHiddenHandles
Show or hide handles marked as
hidden
Values: on, off
Default: off
Controlling MATLAB’s behavior
Diary
Enable the diary file
Values: on, off
Default: off
DiaryFile
Name of the diary file
Values: filename (string)
Default: diary
Echo
Display each line of script M-file as
executed
Values: on, off
Default: off
Format
Format used to display numbers
Values: short, shortE, long,
longE, bank, hex, +, rat
Default: shortE
FormatSpacing
Display or omit extra line feed
Values: compact, loose
Default: loose
Language
System environment setting
Values: string
Default: english
RecursionLimit
Maximum number of nested M-file
calls
Values: integer
Defalut: 2.1478e+009
Units
Units for PointerLocation and
ScreenSize properties
Values: pixels, normalized,
inches, centimeters, points
Default: pixels
Information about the display
ScreenDepth
2-374
Depth of the display bitmap
Values: bits per pixel
root object
Property Name
ScreenSize
Property Description
Size of the screen
Property Value
Values: [left, bottom, width,
height]
Information about terminals (X-Windows only)
TerminalHideGraphCommands
Command to hide graphics window
Values: string
TerminalOneWindow
Indicates if there is only one graphics
window
Values: on, off
Default: on
TerminalDimensions
Size of the terminal
Values: scalar in pixels
TerminalProtocol
Identifies the type of terminal
Values: none, x, tek401x,
tek410x
TerminalShowGraphCommand
Command to display graphics
window
Value: string
General Information About Root Objects
Children
Handles of all nonhidden Figue
objects
Values: vector of handles
Parent
The Root object has no parent
Value: [] (empty matrix)
Selected
Indicate whether the Text is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'root'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
Enable/disable profiler
Values: on, off
Default: off
MATLAB profiler
Profile
2-375
root object
Property Name
Property Description
Property Value
ProfileFile
Specify the name of M-file to profile
Values: pathname to M-file
ProfileCount
Output of profiler
Values: n-by-1 vector
ProfileInterval
Time increment at with to profile
M-file
Values: scalar (seconds)
Default: 0.01 seconds
2-376
Root Properties
Root Properties This section lists property names along with the type of values each accepts.
2Root Properties
Curly braces { } enclose default values.
BusyAction
cancel | {queue}
Not used by the Root object.
ButtonDownFcn
string
Not used by the Root object.
CallbackObject
handle (read only)
Handle of current callback’s object. This property contains the handle of the
object whose callback routine is currently executing. If no callback routines are
executing, this property contains the empty matrix [ ]. See also the gco
command.
CaptureMatrix
(obsolete)
This property has been superseded by the getframe command.
CaptureRect
(obsolete)
This property has been superseded by the getframe command.
Children
vector of handles
Handles of child objects. A vector containing the handles of all nonhidden
Figure objects. You can change the order of the handles and thereby change the
stacking order of the Figures on the display.
Clipping
{on} | off
Clipping has no effect on the Root object.
CreateFcn
The Root does not use this property.
CurrentFigure
Figure handle
Handle of the current Figure window, which is the one most recently created,
clicked in, or made current with the statement:
figure(h)
which restacks the Figure to the top of the screen, or
set(0,'CurrentFigure',h)
2-377
Root Properties
which does not restack the Figures. In these statements, h is the handle of an
existing Figure. If there are no Figure objects,
get(0,'CurrentFigure')
returns the empty matrix. Note, however, that gcf always returns a Figure
handle, and creates one if there are no Figure objects.
DeleteFcn
string
This property is not used since you cannot delete the Root object
Diary
on | {off}
Diary file mode. When this property is on, MATLAB maintains a file (whose
name is specified by the DiaryFile property) that saves a copy of all keyboard
input and most of the resulting output. See also the diary command.
DiaryFile
string
Diary filename. The name of the diary file. The default name is diary.
Echo
on | {off}
Script echoing mode. When Echo is on, MATLAB displays each line of a script
file as it executes. See also the echo command.
ErrorMessage
string
Text of last error message. This property contains the last error message issued
by MATLAB.
Format
short | {shortE} | long | longE | bank |
hex | + | rat
Output format mode. This property sets the format used to display numbers.
See also the format command.
• short – Fixed-point format with 5 digits.
• shortE – Floating-point format with 5 digits.
• shortG – Fixed- or floating-point format displaying as many significant
figures as possible with 5 digits.
• long – Scaled fixed-point format with 15 digits.
• longE – Floating-point format with 15 digits.
• longG – Fixed- or floating-point format displaying as many significant figures
as possible with 15 digits.
2-378
Root Properties
• bank – Fixed-format of dollars and cents.
• hex – Hexadecimal format.
• + – Displays + and – symbols.
• rat – Approximation by ratio of small integers.
FormatSpacing
compact | {loose}
Output format spacing (see also format command).
• compact — Suppress extra line feeds for more compact display.
• loose — Display extra line feeds for a more readable display.
HandleVisibility
{on} | callback | off
This property is not useful on the Root object.
HitTest
{on} | off
This property is not useful on the Root object.
Interruptible
{on} | off
This property is not useful on the Root object.
Language
string
System environment setting.
Parent
handle
Handle of parent object. This property always contains the empty matrix, as the
Root object has no parent.
PointerLocation
[x,y]
Current location of pointer. A vector containing the x- and y-coordinates of the
pointer position, measured from the lower-left corner of the screen. You can
move the pointer by changing the values of this property. The Units property
determines the units of this measurement.
This property always contains the instantaneous pointer location, even if the
pointer is not in a MATLAB window. A callback routine querying the
PointerLocation can get a different value than the location of the pointer when
the callback was triggered. This difference results from delays in callback
execution caused by competition for system resources.
2-379
Root Properties
PointerWindow
handle (read only)
Handle of window containing the pointer. MATLAB sets this property to the
handle of the Figure window containing the pointer. If the pointer is not in a
MATLAB window, the value of this property is 0. A callback routine querying
the PointerWindow can get the wrong window handle if you move the pointer to
another window before the callback executes. This error results from delays in
callback execution caused by competition for system resources.
Profile
on | {off}
M-file profiler on or off. Setting this property to on activates the profiler when
you execute the M-files named in ProfileFile. The profiler determines what
percentage of time MATLAB spends executing each line of the M-file. See also
the profile command.
ProfileFile
M-file name
M-file to profile. Set this property to the full path name of the M-file to profile.
ProfileCount
vector
Profiler output. This property is a n-by-1 vector, where n is the number of lines
of code in the profiled M-file. Each element in this vector represents the
number of times the profiler found MATLAB executing a particular line of
code. The ProfileInterval property determines how often MATLAB profiles
(i.e., determines which line is executing).
ProfileInterval
scalar
Time increment to profile M-file. This property sets the time interval at which
the profiler checks to see what line in the M-file is executing.
RecursionLimit
integer
Number of nested M-file calls. This property sets a limit to the number of
nested calls to M-files MATLAB will make before stoping (or potentially
running out of memory). By default the value is set to a large value. Setting this
property to a smaller value (something like 150, for example) should prevent
MATLAB from running out of memory and will instead cause MATLAB to
issue an error when the limit is reached.
2-380
Root Properties
ScreenDepth
bits per pixel
Screen depth. The depth of the display bitmap (i.e., the number of bits per
pixel). The maximum number of simultaneously displayed colors on the current
graphics device is 2 raised to this power.
ScreenDepth supersedes the BlackAndWhite property. To override automatic
hardware checking, set this property to 1. This value causes MATLAB to
assume the display is monochrome. This is useful if MATLAB is running on
color hardware but is displaying on a monochrome terminal. Such a situation
can cause MATLAB to determine erroneously that the display is color.
ScreenSize
4-element rectangle vector (read only)
Screen size. A four-element vector,
[left,bottom,width,height]
that defines the display size. left and bottom are 0 for all Units except pixels,
in which case left and bottom are 1. width and height are the screen
dimensions in units specified by the Units property.
Selected
on | off
This property has no effect on the Root level.
SelectionHighlight
{on} | off
This property has no effect on the Root level.
ShowHiddenHandles on | {off}
Show or hide handles marked as hidden. When set to on, this property disables
handle hiding and exposes all object handles, regardless of the setting of an
object’s HandleVisibility property. When set to off, all objects so marked
remain hidden within the graphics hierarchy.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. While it is not necessary to identify
the Root object with a tag (since its handle is always 0), you can use this
property to store any string value which you can later retrieve using set.
TerminalHideGraphCommandstring X-Windows only
Hide graph window command. This property specifies the escape sequence that
MATLAB issues to hide the graph window when switching from graph mode
2-381
Root Properties
back to command mode. This property is used only by the terminal graphics
driver. Consult your terminal manual for the correct escape sequence.
TerminalOneWindow
{on} | off X-Windows only
One window terminal. This property indicates whether there is only one
window on your terminal. If the terminal uses only one window, MATLAB
waits for you to press a key before it switches from graphics mode back to
command mode. This property is used only by the terminal graphics driver.
TerminalDimensions pixels X-Windows only
Size of default terminal. This property defines the size of the terminal.
TerminalProtocol
none | x | tek401x | tek410x X-Windows only
Type of terminal. This property tells MATLAB what type of terminal you are
using. Specify tek401x for terminals that emulate Tektronix 4010/4014
terminals. Specify tek410x for terminals that emulate Tektronix 4100/4105
terminals. If you are using X Windows and MATLAB can connect to your X
display server, this property is automatically set to x.
Once this property is set, you cannot change it unless you quit and restart
MATLAB.
TerminalShowGraphCommandstring X-Windows only
Display graph window command. This property specifies the escape sequence
that MATLAB issues to display the graph window when switching from
command mode to graph mode. This property is only used by the terminal
graphics driver. Consult your terminal manual for the appropriate escape
sequence.
Type
string (read only)
Class of graphics object. For the Root object, Type is always 'root'.
UIContextMenu
handle
This property has no effect on the Root level.
Units
|points
{pixels} | normalized | inches | centimeters
Unit of measurement. This property specifies the units MATLAB uses to
interpret size and location data. All units are measured from the lower-left
corner of the screen. Normalized units map the lower-left corner of the screen
2-382
Root Properties
to (0,0) and the upper right corner to (1.0,1.0). inches, centimeters, and points
are absolute units (one point equals 1/72 of an inch).
This property affects the PointerLocation and ScreenSize properties. If you
change the value of Units, it is good practice to return it to its default value
after completing your operation so as not to affect other functions that assume
Units is set to the default value.
UserData
matrix
User specified data. This property can be any data you want to associate with
the Root object. MATLAB does not use this property, but you can access it using
the set and get functions.
Visible
{on} | off
Object visibility. This property has no effect on the Root object.
2-383
rose
Purpose
2rose
Angle histogram
Syntax
rose(theta)
rose(theta,x)
rose(theta,nbins)
[tout,rout] = rose(...)
Description
rose creates an angle histogram, which is a polar plot showing the
distribution of values grouped according to their numeric range. Each group is
shown as one bin.
rose(theta) plots an angle histogram showing the distribution of theta in 20
angle bins or less. The vector theta, expressed in radians, determines the angle
from the origin of each bin. The length of each bin reflects the number of
elements in theta that fall within a group, which ranges from 0 to the greatest
number of elements deposited in any one bin.
rose(theta,x) uses the vector x to specify the number and the locations of
bins. length(x) is the number of bins and the values of x specify the center
angle of each bin. For example, if x is a five-element vector, rose distributes
the elements of theta in five bins centered at the specified x values.
rose(theta,nbins) plots nbins equally spaced bins in the range [0, 2∗pi].
The default is 20.
[tout,rout] = rose(...) returns the vectors tout and rout so
polar(tout,rout) generates the histogram for the data. This syntax does not
generate a plot.
Example
Create a rose plot showing the distribution of 50 random numbers:
theta = 2*pi*rand(1,50);
rose(theta)
2-384
rose
90
5
60
120
4
3
30
150
2
1
180
0
210
330
240
300
270
See Also
compass, feather, hist, polar
2-385
rotate
Purpose
2rotate
Rotate object about a specified direction
Syntax
rotate(h,direction,alpha)
rotate(...,origin)
Description
The rotate function rotates a graphics object in three-dimensional space,
according to the right-hand rule.
rotate(h,direction,alpha) rotates the graphics object h by alpha degrees.
direction is a two- or three-element vector that describes the axis of rotation
in conjunction with the origin.
rotate(...,origin) specifies the origin of the axis of rotation as a
three-element vector. The default is origin is the center of the plot box.
Remarks
The graphics object you want rotated must be a child of the same Axes. The
object’s data is modified by the rotation transformation. This is in contrast to
view and rotate3d, which only modify the viewpoint.
The axis of rotation is defined by an origin and a point P relative to the origin.
P is expressed as the spherical coordinates [theta phi], or as Cartesian
coordinates.
Z
Y
P
tion
ota
fr
is o
origin
ax
X
The two-element form for direction specifies the axis direction using the
spherical coordinates [theta phi]. theta is the angle in the xy plane
2-386
rotate
counterclockwise from the positive x-axis. phi is the elevation of the direction
vector from the xy plane.
Z
P
r
Y
phi
th
et
a
X
The three-element form for direction specifies the axis direction using
Cartesian coordinates. The direction vector is the vector from the origin to
(X,Y,Z).
Examples
Rotate a graphics object 180° about the x-axis:
h = surf(peaks(20));
rotate(h,[1 0 0],180)
Rotate a Surface graphics object 45° about its center in the z direction:
h = surf(peaks(20));
zdir = [0 0 1];
center = [10 10 0];
rotate(h,zdir,45,center)
Remarks
rotate changes the Xdata, Ydata, and Zdata properties of the appropriate
graphics object.
See Also
rotate3d, sph2cart, view
The Axes CameraPosition, CameraTarget, CameraUpVector, CameraViewAngle
2-387
rotate3d
Purpose
2rotate3d
Rotate Axes using mouse
Syntax
rotate3d
rotate3d on
rotate3d off
Description
rotate3d on enables interactive Axes rotation within the current Figure using
the mouse. When interactive Axes rotation is enabled, clicking on an Axes
draws an animated box, which rotates as the mouse is dragged, showing the
view that will result when the mouse button is released. A numeric readout
appears in the lower-left corner of the figure during this time, showing the
current azimuth and elevation of the animated box. Releasing the mouse
button removes the animated box and the readout, and changes the view of the
Axes to correspond to the last orientation of the animated box.
rotate3d off disables interactive Axes rotation in the current Figure.
rotate3d toggles interactive Axes rotation in the current Figure.
See Also
2-388
rotate, view
scatter
Purpose
2scatter
2-D Scatter plot
Syntax
scatter(X,Y,S,C)
scatter(X,Y)
scatter(X,Y,S)
scatter(...,markertype)
scatter(...,'filled')
h = scatter(...,)
Description
scatter(X,Y,S,C) displays colored circles at the locations specified by the
vectors X and Y (which must be the same size).
S determines the size of each marker (specified in points^2). S can be a vector
the same length as X and Y or a scalar. If S is a scalar, MATLAB draws all the
markers the same size.
C determines the colors of each marker. When C is a vector the same length as
X and Y, the values in C are linearly mapped to the colors in the current
colormap. When C is a length(X)-by-3 matrix, it specifies the colors of the
markers as RGB values. C can also be a color string (see ColorSpec for a list of
color string specifiers)
scatter(X,Y) draws the markers in the default size and color.
scatter(X,Y,S) draws the markers at the specified sizes (S) with a single color.
scatter(...,markertype) uses the marker type specified instead of 'o' (see
LineSpec for a list of marker specifiers).
scatter(...,'filled') fills the markers.
h = scatter(...) returns the handles to the Line objects created by scatter
(see line for a list of properties you can specify using the object handles and
set).
Remarks
Examples
Use plot for single color, single marker size scatter plots.
load seamount
scatter(x,y,5,z)
2-389
scatter
−47.95
−48
−48.05
−48.1
−48.15
−48.2
−48.25
−48.3
−48.35
−48.4
−48.45
210.8
See Also
2-390
210.9
211
211.1
211.2
scatter3, plot, plotmatrix
211.3
211.4
211.5
211.6
211.7
211.8
scatter3
Purpose
2scatter3
3-D scatter plot
Syntax
scatter3(X,Y,Z,S,C)
scatter3(X,Y,Z)
scatter3(X,Y,Z,S)
scatter3(...,markertype)
scatter3(...,'filled')
h = scatter3(...,)
Description
scatter3(X,Y,Z,S,C) displays colored circles at the locations specified by the
vectors X, Y, and Z (which must all be the same size).
S determines the size of each marker (specified in points). S can be a vector the
same length as X, Y, and Z or a scalar. If S is a scalar, MATLAB draws all the
markers the same size.
C determines the colors of each marker. When C is a vector the same length as
X, Y, and Z, the values in C are linearly mapped to the colors in the current
colormap. When C is a length(X)-by-3 matrix, it specifies the colors of the
markers as RGB values. C can also be a color string (see ColorSpec for a list of
color string specifiers)
scatter3(X,Y,Z) draws the markers in the default size and color.
scatter3(X,Y,Z,S) draws the markers at the specified sizes (S) with a single
color.
scatter3(...,markertype) uses the marker type specified instead of 'o' (see
LineSpec for a list of marker specifiers).
scatter3(...,'filled') fills the markers.
h = scatter3(...) returns the handles to the Line objects created by scatter3
(see line for a list of properties you can specify using the object handles and
set).
Remarks
Use plot3 for single color, single marker size 3-D scatter plots.
2-391
scatter3
Examples
[x,y,z] = sphere(16);
X = [x(:)*.5 x(:)*.75 x(:)];
Y = [y(:)*.5 y(:)*.75 y(:)];
Z = [z(:)*.5 z(:)*.75 z(:)];
S = repmat([1 .75 .5]*10,prod(size(x)),1);
C = repmat([1 2 3],prod(size(x)),1);
scatter3(X(:),Y(:),Z(:),S(:),C(:),’filled’), view(−60,60)
1
0.5
1
0
−0.5
0.5
−1
1
0
0.5
0
−0.5
−0.5
−1
See Also
2-392
scatter, plot3
−1
semilogx, semilogy
Purpose
Syntax
2semilogx, semilogy
Semi-logarithmic plots
semilogx(Y)
semilogx(X1,Y1,...)
semilogx(X1,Y1,LineSpec,...)
semilogx(...,'PropertyName',PropertyValue,...)
h = semilogx(...)
semilogy(...)
h = semilogy(...)
Description
semilogx and semilogy plot data as logarithmic scales for the x- and y-axis,
respectively. logarithmic
semilogx(Y) creates a plot using a base 10 logarithmic scale for the x-axis and
a linear scale for the y-axis. It plots the columns of Y versus their index if Y
contains real numbers. semilogx(Y) is equivalent to semilogx(real(Y),
imag(Y)) if Y contains complex numbers. semilogx ignores the imaginary
component in all other uses of this function.
semilogx(X1,Y1,...) plots all Xn versus Yn pairs. If only Xn or Yn is a matrix,
semilogx plots the vector argument versus the rows or columns of the matrix,
depending on whether the vector’s row or column dimension matches the
matrix.
semilogx(X1,Y1,LineSpec,...) plots all lines defined by the
Xn,Yn,LineSpec triples. LineSpec determines line style, marker symbol, and
color of the plotted lines.
semilogx(...,'PropertyName',PropertyValue,...) sets property values
for all Line graphics objects created by semilogx.
semilogy(...) creates a plot using a base 10 logarithmic scale for the y-axis
and a linear scale for the x-axis.
h = semilogx(...) and h = semilogy(...) return a vector of handles to
Line graphics objects, one handle per Line.
2-393
semilogx, semilogy
Remarks
If you do not specify a color when plotting more than one line, semilogx and
semilogy automatically cycle through the colors and line styles in the order
specified by the current Axes ColorOrder and LineStyleOrder properties.
You can mix Xn,Yn pairs with Xn,Yn,LineSpec triples, for example,
semilogx(X1,Y1,X2,Y2,LineSpec,X3,Y3)
Examples
A simple semilogy plot is:
x = 0:.1:10;
semilogy(x,10.^x)
10
10
9
10
8
10
7
10
6
10
5
10
4
10
3
10
2
10
1
10
0
10
See Also
2-394
0
1
2
3
4
line, LineSpec, loglog, plot
5
6
7
8
9
10
set
Purpose
2set
Set object properties
Syntax
set(H,'PropertyName',PropertyValue,...)
set(H,a)
set(H,pn,pv...)
set(H,pn,<m-by-n cell array>)
a= set(h)
a= set(0,'Factory')
a= set(0,'FactoryObjectTypePropertyName')
a= set(h,'Default')
a= set(h,'DefaultObjectTypePropertyName')
<cell array> = set(h,'PropertyName')
Description
set(H,'PropertyName',PropertyValue,...) sets the named properties to
the specified values on the object(s) identified by H. H can be a vector of handles,
in which case set sets the properties’ values for all the objects.
set(H,a) sets the named properties to the specified values on the object(s)
identified by H. a is a structure array whose field names are the object property
names and whose field values are the values of the corresponding properties.
set(H,pn,pv,...) sets the named properties specified in the cell array pn to
the corresponding value in the cell array pv for all objects identified in H.
set(H,pn,<m-by-n cell array>) sets n property values on each of m graphics
objects, where m = length(H) and n is equal to the number of property names
contained in the cell array pn. This allows you to set a given group of properties
to different values on each object.
a = set(h) returns the user-settable properties and possible values for the
object identified by h. a is a structure array whose field names are the object’s
property names and whose field values are the possible values of the
corresponding properties. If you do not specify an output argument, MATLAB
displays the information on the screen. h must be scalar.
a = set(0,'Factory') returns the properties whose defaults are user
settable for all objects and lists possible values for each property. a is a
structure array whose field names are the object’s property names and whose
field values are the possible values of the corresponding properties. If you do
2-395
set
not specify an output argument, MATLAB displays the information on the
screen.
a = set(0,'FactoryObjectTypePropertyName') returns the possible values
of the named property for the specified object type, if the values are strings.
The argument FactoryObjectTypePropertyName is the word Factory
concatenated with the object type (e.g., Axes) and the property name (e.g.,
CameraPosition).
a = set(h,'Default') returns the names of properties having default values
set on the object identified by h. set also returns the possible values if they are
strings. h must be scalar.
a = set(h,'DefaultObjectTypePropertyName') returns the possible values
of the named property for the specified object type, if the values are strings.
The argument DefaultObjectTypePropertyName is the word Default
concatenated with the object type (e.g., Axes) and the property name (e.g.,
CameraPosition). For example, DefaultAxesCameraPosition. h must be
scalar.
pv = set(h,'PropertyName') returns the possible values for the named
property. If the possible values are strings, set returns each in a cell of the cell
array, pv. For other properties, set returns an empty cell array. If you do not
specify an output argument, MATLAB displays the information on the screen.
h must be scalar.
Remarks
You can use any combination of property name/property value pairs, structure
arrays, and cell arrays in one call to set.
Examples
Set the Color property of the current Axes to blue:
set(gca,'Color','b')
Change all the Lines in a plot to black:
plot(peaks)
set(findobj('Type','line'),'Color','k')
You can define a group of properties in a structure to better organize your code.
For example, these statements define a structure called active, which
contains a set of property definitions used for the Uicontrol objects in a
2-396
set
particular Figure. When this Figure becomes the current Figure, MATLAB
changes colors and enables the controls:
active.BackgroundColor = [.7 .7 .7];
active.Enable = 'on';
active.ForegroundColor = [0 0 0];
if gcf == control_fig_handle
set(findobj(control_fig_handle,'Type','uicontrol'),active)
end
You can use cell arrays to set properties to different values on each object. For
example, these statements define a cell array to set three properties:
PropName(1) = {'BackgroundColor'};
PropName(2) = {'Enable'};
PropName(3) = {'ForegroundColor'};
These statements define a cell array containing three values for each of three
objects (i.e., a 3-by-3 cell array):
PropVal(1,1) = {[.5 .5 .5]};
PropVal(1,2) = {'off'};
PropVal(1,3) = {[.9 .9 .9]};
PropVal(2,1) = {[1 0 0]};
PropVal(2,2) = {'on'};
PropVal(2,3) = {[1 1 1]};
PropVal(3,1) = {[.7 .7 .7]};
PropVal(3,2) = {'on'};
PropVal(3,3) = {[0 0 0]};
Now pass the arguments to set,
set(H,PropName,PropVal)
where length(H) = 3 and each element is the handle to a Uicontrol.
See Also
findobj, gca, gcf, gco, gcbo, get
2-397
shading
Purpose
2shading
Set color shading properties
Syntax
shading flat
shading faceted
shading interp
Description
The shading function controls the color shading of Surface and Patch graphics
objects.
shading flat each mesh line segment and face has a constant color
determined by the color value at the end point of the segment or the corner of
the face that has the smallest index or indices.
shading faceted flat shading with superimposed black mesh lines. This is
the default shading mode.
shading interp varies the color in each line segment and face by
interpolating the colormap index or true color value across the line or face.
Examples
Compare a flat, faceted, and interpolated-shaded sphere:
subplot(3,1,1)
sphere(16)
axis square
shading flat
title('Flat Shading')
subplot(3,1,2)
sphere(16)
axis square
shading faceted
title('Faceted Shading')
subplot(3,1,3)
sphere(16)
axis square
shading interp
title('Interpolated Shading')
2-398
shading
Algorithm
shading sets the EdgeColor and FaceColor properties of all Surface and Patch
graphics objects in the current Axes. shading sets the appropriate values,
depending on whether the Surface or Patch objects represent meshes or solid
surfaces.
2-399
shading
See Also
fill, fill3, hidden, mesh, patch, pcolor, surf
The EdgeColor and FaceColor properties for Surface and Patch graphics
objects.
2-400
slice
Purpose
2slice
Volumetric slice plot
Syntax
slice(V,sx,sy,sz)
slice(X,Y,Z,V,sx,sy,sz)
slice(V,XI,YI,ZI)
slice(X,Y,Z,V,XI,YI,ZI)
slice(...,'method')
h = slice(...)
Description
slice displays orthogonal slice planes through volumetric data.
slice(V,sx,sy,sz) draws slices along the x, y, z directions in the volume V at
the points in the vectors sx, sy, and sz. V is an m-by-n-by-p volume array
containing data values at the default location X = 1:n, Y = 1:m, Z = 1:p. Each
element in the vectors sx, sy, and sz defines a slice plane in the x-, y-, or z-axis
direction.
slice(X,Y,Z,V,sx,sy,sz) draws slices of the volume V. X, Y, and Z are
three-dimensional arrays specifying the coordinates for V. X, Y, and Z must be
monotonic and orthogonally spaced (as if produced by the function meshgrid).
The color at each point is determined by 3-D interpolation into the volume V.
slice(V,XI,YI,ZI) draws data in the volume V for the slices defined by XI, YI,
and ZI. XI, YI, and ZI are matrices that define a surface, and the volume is
evaluated at the surface points. XI, YI, and ZI must all be the same size.
slice(X,Y,Z,V,XI,YI,ZI) draws slices through the volume V along the
surface defined by the arrays XI, YI, ZI.
slice(...,'method') specifies the interpolation method. 'method' is
'linear', 'cubic', or 'nearest'.
• 'linear' specifies trilinear interpolation (the default).
• 'cubic' specifies tricubic interpolation.
• 'nearest' specifies nearest neighbor interpolation.
h = slice(...) returns a vector of handles to Surface graphics objects.
2-401
slice
Remarks
The color drawn at each point is determined by interpolation into the volume V.
Examples
Visualize the function
v = xe ( – x
2
– y2 – z2 )
over the range –2 ≤x ≤2, –2 ≤y ≤2, – 2 ≤z ≤2:
[x,y,z] = meshgrid(−2:.2:2, −2:.25:2, −2:.16:2);
v = x.∗exp(−x.^2−y.^2−z.^2);
xslice = [−1.2 .8 2]; yslice = 2; zslice = [−2 0];
slice(x,y,z,v,xslice,yslice,zslice)
colormap hsv
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
2
1
2
1
0
0
−1
−1
−2
−2
You can also create slices that are oriented in arbitrary planes. To do this,
• Create a slice surface in the domain of the volume.
• Orient this surface with respect the the axes.
2-402
slice
• Get the XData, YData, and ZData of the surface.
• Use this data to draw the slice plane within the volume.
For example, these statements slice the volume in the first example with a
rotated plane. Placing these commands within a for loop “passes” the plane
through the volume along the z-axis:
for i = −2:.5:2
hsp = surf(linspace(−2,2,20),linspace(−2,2,20),zeros(20)+i);
rotate(hsp,[1 -1 1],30)
xd = get(hsp,’XData’);
yd = get(hsp,’YData’);
zd = get(hsp,’ZData’);
delete(hsp)
slice(x,y,z,v,[-2 2],2,-2) % Draw some volume boundaries
hold on
slice(x,y,z,v,xd,yd,zd)
hold off
axis tight
view(-5,10)
drawnow
end
The following picture illustrates three positons of the same slice surface as it
passes through the volume.
2-403
slice
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
2
0
−2
2-404
−2.5
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
2.5
slice
You can slice the volume with any surface. This example probes the volume
created in the previous example by passing a spherical slice surface through
the volume.
[xsp,ysp,zsp] = sphere;
slice(x,y,z,v,[-2 2],2,-2)
% Draw some volume boundaries
for i = -3:.2:3
hsp = surface(xsp+i,ysp,zsp);
rotate(hsp,[1 0 0],90)
xd = get(hsp,’XData’);
yd = get(hsp,’YData’);
zd = get(hsp,’ZData’);
delete(hsp)
hold on
hslicer = slice(x,y,z,v,xd,yd,zd);
axis tight
xlim([-3 3])
view(-10,35)
drawnow
delete(hslicer)
hold off
end
The following picture illustrates three positons of the same slice surface as it
passes through the volume.
2-405
slice
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
2
1
0
−1
−2
−3
See Also
2-406
interp3, meshgrid
−2
−1
0
1
2
3
sphere
Purpose
2sphere
Generate sphere
Syntax
sphere
sphere(n)
[X,Y,Z] = sphere(...)
Description
The sphere function generates the x-, y-, and z-coordinates of a unit sphere for
use with surf and mesh.
sphere generates a sphere consisting of 20-by-20 faces.
sphere(n) draws a surf plot of an n-by-n sphere in the current Figure.
[X,Y,Z] = sphere(n) returns the coordinates of a sphere in three matrices
that are (n+1)–by–(n+1) in size. You draw the sphere with surf(X,Y,Z) or
mesh(X,Y,Z).
Examples
Generate and plot a sphere:
sphere
axis equal
1
0.5
0
−0.5
−1
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
2-407
sphere
See Also
2-408
cylinder, axis
spinmap
Purpose
2spinmap
Spin colormap
Syntax
spinmap
spinmap(t)
spinmap(t,inc)
spinmap('inf')
Description
The spinmap function shifts the colormap RGB values by some incremental
value. For example, if the increment equals 1, color 1 becomes color 2, color 2
becomes color 3, etc.
spinmap cyclically rotates the colormap for approximately five seconds using
an incremental value of 2.
spinmap(t) rotates the colormap for approximately 10∗t seconds. The amount
of time specified by t depends on your hardware configuration (e.g., if you are
running MATLAB over a network).
spinmap(t,inc) rotates the colormap for approximately 10∗t seconds and
specifies an increment inc by which the colormap shifts. When inc is 1, the
rotation appears smoother than the default (i.e., 2). Increments greater than 2
are less smooth than the default. A negative increment (e.g., –2) rotates the
colormap in a negative direction.
spinmap('inf') rotates the colormap for an infinite amount of time. To break
the loop, press Ctrl-C.
See Also
colormap
2-409
stairs
Purpose
2stairs
Stairstep plot
Syntax
stairs(Y)
stairs(X,Y)
stairs(...,LineSpec)
[xb,yb] = stairs(Y)
[xb,yb] = stairs(X,Y)
Description
Stairstep plots are useful for drawing time-history plots of digitally sampled
data systems.
stairs(Y) draws a stairstep plot of the elements of Y. When Y is a vector, the
x-axis scale ranges from 1 to size(Y). When Y is a matrix, the x-axis scale
ranges from 1 to the number of rows in Y.
stairs(X,Y) plots X versus the columns of Y. X and Y are vectors of the same
size or matrices of the same size. Additionally, X can be a row or a column
vector, and Y a matrix with length(X) rows.
stairs(...,LineSpec) specifies a line style, marker symbol, and color for the
plot (see LineSpec for more information).
[xb,yb] = stairs(Y) and [xb,yb] = stairs(x,Y) do not draw graphs, but
return vectors xb and yb such that plot(xb,yb) plots the stairstep graph.
Examples
Create a stairstep plot of a sine wave:
x = 0:.25:10;
stairs(x,sin(x))
2-410
stairs
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
See Also
2
4
6
8
10
bar, hist
2-411
stem
Purpose
2stem
Plot discrete sequence data
Syntax
stem(Y)
stem(X,Y)
stem(...,'fill')
stem(...,LineSpec)
h = stem(...)
Description
A two-dimensional stem plot displays data as lines extending from the x-axis.
A circle (the default) or other marker whose y-position represents the data
value terminates each stem.
stem(Y) plots the data sequence Y as stems that extend from equally spaced
and automatically generated values along the x-axis. When Y is a matrix, stem
plots all elements in a row against the same x value.
stem(X,Y) plots X versus the columns of Y. X and Y are vectors or matrices of
the same size. Additionally, X can be a row or a column vector and Y a matrix
with length(X) rows.
stem(...,'fill') specifies whether to color the circle at the end of the stem.
stem(...,LineSpec) specifies the line style, marker symbol, and color for the
stem plot. See LineSpec for more information.
h = stem(...) returns handles to Line graphics objects.
2-412
stem
Examples
Create a stem plot of 10 random numbers:
y = linspace(0,2,10);
stem(exp(-y),'fill','–.')
axis ([0 11 0 1])
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
0
See Also
2
4
6
8
10
bar, plot, stairs, stem3
2-413
stem3
Purpose
2stem3
Plot three-dimensional discrete sequence data
Syntax
stem3(Z)
stem3(X,Y,Z)
stem3(...,'fill')
stem3(...,LineSpec)
h = stem3(...)
Description
Three-dimensional stem plots display lines extending from the xy-plane. A
circle (the default) or other marker symbol whose z-position represents the
data value, terminates each stem.
stem3(Z) plots the data sequence Z as stems that extend from the xy-plane.
x and y are generated automatically. When Z is a row vector, stem3 plots all
elements at equally spaced x values against the same y value. When Z is a
column vector, stem3 plots all elements at equally spaced y values against the
same x value.
stem3(X,Y,Z) plots the data sequence Z at values specified by X and Y. X, Y,
and Z must all be vectors or matrices of the same size.
stem3(...,'fill') specifies whether to color the interior of the circle at the
end of the stem.
stem3(...,LineSpec) specifies the line style, marker symbol, and color for
the stems. See LineSpec for more information.
h = stem3(...) returns handles to Line graphics objects.
Examples
Create a three-dimensional stem plot to visualize a function of two variables:
X = linspace(0,1,10);
Y = X./2;
Z = sin(X) + cos(Y);
stem3(X,Y,Z,'fill')
view(-25,30)
2-414
stem3
:
2
1.5
1
0.5
0
0.5
0.4
0.3
0.2
0.1
0
See Also
0
0.2
0.4
0.6
0.8
1
bar, plot, stairs, stem
2-415
subplot
Purpose
2subplot
Create and control multiple Axes
Syntax
subplot(m,n,p)
subplot(h)
subplot('Position',[left bottom width height])
h = subplot(...)
Description
subplot divides the current Figure into rectangular panes that are numbered
row-wise. Each pane contains an Axes. Subsequent plots are output to the
current pane.
subplot(m,n,p) creates an Axes in the p-th pane of a Figure divided into an
m-by-n matrix of rectangular panes. The new Axes becomes the current Axes.
subplot(h) makes the Axes with handle h current for subsequent plotting
commands.
subplot('Position',[left bottom width height]) creates an Axes at the
position specified by a four-element vector. left, bottom, width, and height
are in normalized coordinates in the range from 0.0 to 1.0.
h = subplot(...) returns the handle to the new Axes.
Remarks
If a subplot specification causes a new Axes to overlap an existing Axes,
subplot deletes the existing Axes. subplot(1,1,1) or clf deletes all Axes
objects and returns to the default subplot(1,1,1) configuration.
You can omit the parentheses and specify subplot as:
subplot mnp
where m refers to the row, n refers to the column, and p specifies the pane.
Special Case – subplot(111)
The command subplot(111) is not identical in behavior to subplot(1,1,1)
and exists only for compatibility with previous releases. This syntax does not
immediately create an Axes, but instead sets up the Figure so that the next
graphics command executes a clf reset (deleting all Figure children) and
creates a new Axes in the default position. This syntax does not return a
2-416
subplot
handle, so it is an error to specify a return argument. (This behavior is
implemented by setting the Figure’s NextPlot property to replace.)
Examples
To plot income in the top half of a Figure and outgo in the bottom half,
income = [3.2 4.1 5.0 5.6];
outgo = [2.5 4.0 3.35 4.9];
subplot(2,1,1); plot(income)
subplot(2,1,2); plot(outgo)
The following illustration shows four subplot regions and indicates the
command used to create each:
See Also
axes, cla, clf, figure, gca
2-417
surf, surfc
Purpose
2surf, surfc
3-D shaded surface plot
Syntax
surf(Z)
surf(X,Y,Z)
surf(X,Y,Z,C)
surf(...,'PropertyName',PropertyValue)
surfc(...)
h = surf(...)
h = surfc(...)
Description
Use surf and surfc to view mathematical functions over a rectangular region.
surf and surfc create colored parametric surfaces specified by X, Y, and Z, with
color specified by Z or C.
surf(Z) creates a a three-dimensional shaded surface from the z components
in matrix Z, using x = 1:n and y = 1:m, where [m,n] = size(Z). The height,
Z, is a single-valued function defined over a geometrically rectangular grid. Z
specifies the color data as well as surface height, so color is proportional to
surface height.
surf(X,Y,Z) creates a shaded Surface using Z for the color data as well as
surface height. X and Y are vectors or matrices defining the x and y components
of a Surface. If X and Y are vectors, length(X) = n and length(Y) = m, where
[m,n] = size(Z). In this case, the vertices of the surface faces are
( X ( j ), Y ( i ), Z ( i, j ) ) triples.
surf(X,Y,Z,C) creates a shaded surface, with color defined by C. MATLAB
performs a linear transformation on this data to obtain colors from the current
colormap.
surf(...,'PropertyName',PropertyValue) specifies Surface properties
along with the data.
surfc(...) draws a contour plot beneath the surface.
h = surf(...) and h = surfc(...) return a handle to a Surface graphics
object.
2-418
surf, surfc
Algorithm
Abstractly, a parametric surface is parametrized by two independent
variables, i and j, which vary continuously over a rectangle, for example,
1 ≤ i ≤ m and 1 ≤ j ≤ n. The three functions, x(i,j), y(i,j), and z(i,j)
specify the surface. When i and j are integer values, they define a rectangular
grid with integer grid points. The functions x(i,j), y(i,j), and z(i,j)
become three m-by-n matrices, X, Y and Z. Surface color is a fourth function,
c(i,j), denoted by matrix C.
Each point in the rectangular grid can be thought of as connected to its four
nearest neighbors:
i–1,j
|
i,j–1 – i,j – i,j+1
|
i+1,j
This underlying rectangular grid induces four-sided patches on the surface. To
express this another way, [X(:) Y(:) Z(:)] returns a list of triples specifying
points in 3-space. Each interior point is connected to the four neighbors
inherited from the matrix indexing. Points on the edge of the surface have
three neighbors; the four points at the corners of the grid have only two
neighbors. This defines a mesh of quadrilaterals or a quad-mesh.
Surface color can be specified in two different ways – at the vertices or at the
centers of each patch. In this general setting, the surface need not be a single
valued function of x and y. Moreover, the four-sided surface patches need not
be planar. For example, you can have surfaces defined in polar, cylindrical, and
spherical coordinate systems.
The shading function sets the shading. If the shading is interp, C must be the
same size as X, Y, and Z; it specifies the colors at the vertices. The color within
a surface patch is a bilinear function of the local coordinates. If the shading is
faceted (the default) or flat, C(i,j) specifies the constant color in the surface
patch:
(i,j)
–
(i,j+1)
|
C(i,j) |
(i+1,j) – (i+1,j+1)
2-419
surf, surfc
In this case, C can be the same size as X, Y, and Z and its last row and column
are ignored, Alternatively, its row and column dimensions can be one less than
those of X, Y, and Z.
The surf and surfc functions specify the view point using view(3).
The range of X, Y, and Z, or the current setting of the Axes XLimMode, YLimMode,
and ZLimMode properties (also set by the axis function) determine the axis
labels.
The range of C, or the current setting of the Axes CLim and ClimMode properties
(also set by the caxis function) determine the color scaling. The scaled color
values are used as indices into the current colormap.
Examples
Display a surface and contour plot of the peaks surface:
[X,Y,Z] = peaks(30);
surfc(X,Y,Z)
colormap hsv
axis([−3 3 −3 3 −10 5])
5
0
−5
−10
3
2
3
1
2
0
1
0
−1
−1
−2
−2
−3
2-420
−3
surf, surfc
Color a sphere with the pattern of +1s and -1s in a Hadamard matrix:
k = 5;
n = 2^k–1;
[x,y,z] = sphere(n);
c = hadamard(2^k);
surf(x,y,z,c);
colormap([1 1 0; 0
axis equal
1
1])
1
0.5
0
−0.5
−1
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
See Also
−1
axis, caxis, colormap, contour, mesh, pcolor, shading, view
Properties for Surface graphics objects
2-421
surface
Purpose
2surface
Create Surface object
Syntax
surface(Z)
surface(Z,C)
surface(X,Y,Z)
surface(X,Y,Z,C)
surface(...'PropertyName',PropertyValue,...)
h = surface(...)
Description
surface is the low-level function for creating Surface graphics objects. Surfaces
are plots of matrix data created using the row and column indices of each
element as the x- and y-coordinates and the value of each element as the
z-coordinate.
surface(Z) plots the Surface specified by the matrix Z. Here, Z is a
single-valued function, defined over a geometrically rectangular grid.
surface(Z,C) plots the Surface specified by Z and colors it according to the
data in C (see “Examples”).
surface(X,Y,Z,C) plots the parametric surface specified by X, Y and Z, with
color specified by C.
surface(X,Y,Z) uses C = Z, so color is proportional to surface height above the
x-y plane.
surface(x,y,Z), surface(x,y,Z,C) replaces the first two matrix arguments
with vectors and must have length(x) = n and length(y) = m where
[m,n] = size(Z). In this case, the vertices of the Surface facets are the triples
(x(j),y(i),Z(i,j)). Note that x corresponds to the columns of Z and y
corresponds to the rows of Z. For a complete discussion of parametric surfaces,
see the surf function.
surface(...'PropertyName',PropertyValue,...) follows the X, Y, Z, and C
arguments with property name/property value pairs to specify additional
Surface properties. These properties are described in the “Surface Properties”
section.
h = surface(...) returns a handle to the created Surface object.
2-422
surface
Remarks
Unlike high-level area creation functions, such as surf or mesh, surface does
not respect the settings of the Figure and Axes NextPlot properties. It simply
adds the Surface object to the current Axes.
If you do not specify separate color data (C), MATLAB uses the matrix (Z) to
determine the coloring of the Surface. In this case, color is proportional to
values of Z. You can specify a separate matrix to color the Surface
independently of the data defining the area of the Surface.
You can specify properties as property name/property value pairs, structure
arrays, and cell arrays (see set and get for examples of how to specify these
data types).
surface provides convenience forms that allow you to omit the property name
for the XData, YData, ZData, and CData properties. For example,
surface('XData',X,'YData',Y,'ZData',Z,'CData',C)
is equivalent to:
surface(X,Y,Z,C)
When you specify only a single matrix input argument,
surface(Z)
MATLAB assigns the data properties as if you specified,
surface('XData',[1:size(Z,2)],...
'YData',[1:size(Z,1)],...
'ZData',Z,...
'CData',Z)
The axis, caxis, colormap, hold, shading, and view commands set graphics
properties that affect Surfaces. You can also set and query Surface property
values after creating them using the set and get commands.
Example
This example creates a Surface using the peaks M-file to generate the data,
and colors it using the clown image. The ZData is a 49-by-49 element matrix,
2-423
surface
while the CData is a 200-by-320 matrix. You must set the Surface’s FaceColor
to texturemap to use ZData and CData of different dimensions.
load clown
surface(peaks,flipud(X),...
'FaceColor','texturemap',...
'EdgeColor','none',...
'CDataMapping','direct')
colormap(map)
view(-35,45)
Note the use of the surface(Z,C) convenience form combined with property
name/property value pairs.
Since the clown data (X) is typically viewed with the image command, which
MATLAB normally displays with 'ij' axis numbering and direct
CDataMapping, this example reverses the data in the vertical direction using
flipud and sets the CDataMapping property to direct.
See Also
2-424
ColorSpec, mesh, patch, pcolor, surf
surface
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Surface properties on the Axes, Figure, and Root levels:
set(0,'DefaultSurfaceProperty',PropertyValue...)
set(gcf,'DefaultSurfaceProperty',PropertyValue...)
set(gca,'DefaultSurfaceProperty',PropertyValue...)
Where Property is the name of the Surface property whose default value you
want to set and PropertyValue is the value you are specifying. Use set and get
to access the Surface properties.
Property List
The following table lists all Surface properties and provides a brief description
of each. The property name links take you to an expanded description of the
properties.
Property Name
Property Description
Property Value
XData
The x-coordinates of the vertices of
the Surface
Values: vector or matrix
YData
The y-coordinates of the vertices of
the Surface
Values: vector or matrix
ZData
The z-coordinates of the vertices of
the Surface
Values: matrix
Data Defining the Object
2-425
surface
Property Name
Property Description
Property Value
CData
Color data
Values: scalar, vector, or
matrix
Default: [] empty matrix
CDataMapping
Controls mapping of CData to
colormap
Values: scaled, direct
Default: scaled
EdgeColor
Color of face edges
Values: ColorSpec, none,
flat, interp
Default: ColorSpec
FaceColor
Color of face
Values: ColorSpec, none,
flat, interp
Default: ColorSpec
MarkerEdgeColor
Color of marker or the edge color for
filled markers
Values: ColorSpec, none,
Specifying Color
auto
Default: auto
MarkerFaceColor
Fill color for markers that are closed
shapes
Values: ColorSpec, none,
auto
Default: none
Controlling the Effects of Lights
AmbientStrength
Intensity of the ambient light
Values: scalar >=0 and <=1
Default: 0.3
BackFaceLighting
Controls lighting of faces pointing
away from camera
Values: unlit, lit,
DiffuseStrength
Intensity of diffuse light
Values: scalar >=0 and <=1
Default: 0.6
EdgeLighting
Method used to light edges
reverselit
Default: reverselit
Values: none, flat, gouraud,
phong
Default: none
2-426
surface
Property Name
Property Description
FaceLighting
Method used to light edges
Property Value
Values: none, flat, gouraud,
phong
Default: none
NormalMode
MATLAB-generated or user-specified Values: auto, manual
normal vectors
Default: auto
SpecularColorReflectance
Composit color of specularly reflected
light
Values: scalar 0 to 1
Default: 1
SpecularExponent
Harshness of specular reflection
Values: scalar >= 1
Default: 10
SpecularStrength
Intensity of specular light
Values: scalar >=0 and <=1
Default: 0.9
VertexNormals
Vertex normal vectors
Values: matrix
Defining Edges and Markers
LineStyle
Select from five line styles.
Values: −, −−, :, −., none
Default: −
LineWidth
The width of the edge in points
Values: scalar
Default: 0.5 points
Marker
Marker symbol to plot at data points
Values: see Marker property
Default: none
MarkerSize
Size of marker in points
Values: size in points
Default: 6
Clipping
Clipping to Axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the
Surface (useful for animation)
Values: normal, none, xor,
Controlling the Appearance
background
Default: normal
2-427
surface
Property Name
Property Description
Property Value
MeshStyle
Wpecifies whether to draw all edge
Values: both, row, column
lines or just row or column edge lines Defaults: both
SelectionHighlight
Highlight Surface when selected
(Selected property set to on)
Values: on, off
Default: on
Visible
Make the Surface visible or invisible
Values: on, off
Default: on
Controlling Access to Objects
HandleVisibility
Determines if and when the the
Surface’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Determines if the Surface can
become the current object (see the
Figure CurrentObject property)
Values: on, off
Default: on
Properties Related to Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on over the Surface
Values: string
Default: '' (empty string)
CreateFcn
Define a callback routine that
executes when an Surface is created
Values: string
Default: '' (empty string)
DeleteFcn
Define a callback routine that
executes when the Surface is deleted
(via close or delete)
Values: string
Default: '' (empty string)
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
Associate a context menu with the
Surface
Values: handle of a
Uicontrextmenu
2-428
surface
Property Name
Property Description
Property Value
General Information About the Surface
Children
Surface objects have no children
Values: [] (empty matrix)
Parent
The parent of a Surface object is
always an Axes object
Value: Axes handle
Selected
Indicate whether the Surface is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'surface'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
2-429
Surface Properties
Surface
Properties
2Surface Properties
This section lists property names along with the types of values each accepts.
Curly braces { } enclose default values.
AmbientStrength
scalar >= 0 and <= 1
Strength of ambient light. This property sets the strength of the ambient light,
which is a nondirectional light source that illuminates the entire scene. You
must have at least one visible Light object in the Axes for the ambient light to
be visible. The Axes AmbientLightColor property sets the color of the ambient
light, which is therefore the same on all objects in the Axes.
You can also set the strength of the diffuse and specular contribution of Light
objects. See the Surface DiffuseStrength and SpecularStrength properties.
BackFaceLighting
unlit | lit | reverselit
Face lighting control. This property determines how faces are lit when their
vertex normals point away from the camera.
• unlit – face is not lit
• lit – face lit in normal way
• reverselit – face is lit as if the vertex pointed towards the camera
This property is useful for discriminating between the internal and external
surfaces of an object. See the Using MATLAB Graphics manual for an example.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routines always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
2-430
Surface Properties
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is over the Surface object. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
CData
matrix
Vertex colors. A matrix containing values that specify the color at every point
in ZData. If you set the FaceColor property to texturemap, CData does not need
to be the same size as ZData. In this case, MATLAB maps CData to conform to
the Surface defined by ZData.
You can specify color as indexed values or true color. Indexed color data
specifies a single value for each vertex. These values are either scaled to map
linearly into the current colormap (see caxis) or interpreted directly as indices
into the colormap, depending on the setting of the CDataMapping property.
True color defines an RGB value for each vertex. If the coordinate data (XData
for example) are contained in m-by-n matrices, then CData must be an m-by-n-3
array. The first page contains the red components, the second the green
components, and the third the blue components of the colors.
On computer displays that cannot display true color (e.g., 8-bit displays),
MATLAB uses dithering to approximate the RGB triples using the colors in the
Figure’s Colormap and Dithermap. By default, Dithermap uses the
colorcube(64) colormap. You can also specify your own dithermap.
CDataMapping
{scaled} | direct
Direct or scaled color mapping. This property determines how MATLAB
interprets indexed color data used to color the Surface. (If you use true color
specification for CData, this property has no effect.)
• scaled – transform the color data to span the portion of the colormap
indicated by the Axes CLim property, linearly mapping data values to colors.
See the caxis reference page for more information on this mapping.
• direct – use the color data as indices directly into the colormap. The color
data should then be integer values ranging from 1 to length(colormap).
MATLAB maps values less than 1 to the first color in the colormap, and
values greater than length(colormap) to the last color in the colormap.
Values with a decimal portion are fixed to the nearest, lower integer.
2-431
Surface Properties
Children
matrix of handles
Always the empty matrix; Surface objects have no children.
Clipping
{on} | off
Clipping to Axes rectangle. When Clipping is on, MATLAB does not display any
portion of the Surface that is outside the Axes rectangle.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Surface object. You
must define this property as a default value for Surfaces. For example, the
statement,
set(0,'DefaultSurfaceCreateFcn',...
'set(gcf,''DitherMap'',my_dithermap)')
defines a default value on the Root level that sets the Figure DitherMap
property whenever you create a Surface object. MATLAB executes this routine
after setting all Surface properties. Setting this property on an existing Surface
object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Surface callback routine. A callback routine that executes when you
delete the Surface object (e.g., when you issue a delete command or clear the
Axes or Figure). MATLAB executes the routine before destroying the object’s
properties so these values are available to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DiffuseStrength
scalar >= 0 and <= 1
Intensity of diffuse light. This property sets the intensity of the diffuse
component of the light falling on the Surface. Diffuse light comes from Light
objects in the Axes.
You can also set the intensity of the ambient and specular components of the
light on the Surface object. See the AmbientStrength and SpecularStrength
properties.
2-432
Surface Properties
EdgeColor
{ColorSpec} | none | flat | interp
Color of the Surface edge. This property determines how MATLAB colors the
edges of the individual faces that make up the Surface:
• ColorSpec — A three-element RGB vector or one of MATLAB’s predefined
names, specifying a single color for edges. The default EdgeColor is black. See
ColorSpec for more information on specifying color.
• none — Edges are not drawn.
• flat — The CData value of the first vertex for a face determines the color of
each edge:
Direction of
increasing y data
Vertex controlling the
color of adjacent edges
Direction of
increasing x data
• interp — Linear interpolation of the CData values at the face vertices
determines the edge color.
EdgeLighting
{none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm
used to calculate the effect of Light objects on Surface edges. Choices are:
• none – Lights do not affect the edges of this object.
• flat – The effect of Light objects is uniform across each edge of the Surface.
• gouraud – The effect of Light objects is calculated at the vertices and then
linearly interpolated across the edge lines.
• phong – The effect of Light objects is determined by interpolating the vertex
normals across each edge line and calculating the reflectance at each pixel.
Phong lighting generally produces better results than Gouraud lighting, but
takes longer to render.
2-433
Surface Properties
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and
erase Surface objects. Alternative erase modes are useful for creating animated
sequences, where control of the way individual objects redraw is necessary to
improve performance and obtain the desired effect.
• normal — Redraw the affected region of the display, performing the
three-dimensional analysis necessary to ensure that all objects are rendered
correctly. This mode produces the most accurate picture, but is the slowest.
The other modes are faster, but do not perform a complete redraw and are
therefore less accurate.
• none — Do not erase the Surface when it is moved or destroyed. While the
object is still visible on the screen after erasing with EraseMode none, you
cannot print it because MATLAB stores no information about its former
location.
• xor — Draw and erase the Surface by performing an exclusive OR (XOR)
with each pixel index of the screen behind it. Erasing the Surface does not
damage the color of the objects behind it. However, Surface color depends on
the color of the screen behind it and is correctly colored only when over the
Axes background Color, or the Figure background Color if the Axes Color is
set to none.
• background — Erase the Surface by drawing it in the Axes’ background
Color, or the Figure background Color if the Axes Color is set to none. This
damages objects that are behind the erased object, but Surface objects are
always properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints Figures as if the
EraseMode of all objects is normal. This means graphics objects created with
EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g.,
XORing a pixel color with that of the pixel behind it) and ignore
three-dimensional sorting to obtain greater rendering speed. However, these
techniques are not applied to the printed output.
You can use the MATLAB capture command or other screen capture
application to create an image of a Figure containing non-normal mode objects.
2-434
Surface Properties
FaceColor
ColorSpec | none | {flat} | interp
Color of the Surface face. This property can be any of the following:
• ColorSpec — A three-element RGB vector or one of MATLAB’s predefined
names, specifying a single color for faces. See ColorSpec for more
information on specifying color.
• none — Do not draw faces. Note that edges are drawn independently of faces.
• flat — The values of CData determine the color for each face of the Surface.
The color data at the first vertex determines the color of the entire face.
• interp — Bilinear interpolation of the values at each vertex (the CData)
determines the coloring of each face.
• texturemap — Texture map the CData to the Surface. MATLAB transforms
the color data so that it conforms to the Surface. (See “Examples”)
FaceLighting
{none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm
used to calculate the effect of Light objects on the Surface. Choices are:
• none – Lights do not affect the faces of this object.
• flat – The effect of Light objects is uniform across the faces of the Surface.
Select this choice to view faceted objects.
• gouraud – The effect of Light objects is calculated at the vertices and then
linearly interpolated across the faces. Select this choice to view curved
surfaces.
• phong – The effect of Light objects is determined by interpolating the vertex
normals across each face and calculating the reflectance at each pixel. Select
this choice to view curved surfaces. Phong lighting generally produces better
results than Gouraud lighting, but takes longer to render.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. This property is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
2-435
Surface Properties
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Surface can become the
current object (as returned by the gco command and the Figure CurrentObject
property) as a result of a mouse click on the Surface. If HiTest is off, clicking
on the Surface selects the object below it (which maybe the Axes containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Surface callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
2-436
Surface Properties
getframe, or pause command in the routine. See the BusyAction property for
related information.
LineStyle
{-} | -- | : | -. | none
Edge line type. This property determines the line style used to draw Surface
edges. The available line styles are:
Symbol
Line Style
−
solid line (default)
−−
dashed line
:
dotted line
−.
dash-dot line
none
no line
LineWidth
scalar
Edge line width. The width of the lines in points used to draw Surface edges.
The default width is 0.5 points (1 point = 1/72 inch).
Marker
marker symbol (see table)
Marker symbol. The Marker property specifies symbols that display at vertices.
You can set values for the Marker property independently from the LineStyle
property.
2-437
Surface Properties
You can specify these markers:
Marker Specifier
Description
+
plus sign
o
circle
*
asterisk
.
point
x
cross
s
square
d
diamond
^
upward pointing triangle
v
downward pointing triangle
>
right pointing triangle
<
left pointing triangle
p
five-pointed star (pentagram)
h
six-pointed star (hexagram)
none
no marker (default)
MarkerEdgeColor
ColorSpec | none | {auto}
Marker edge color. The color of the marker or the edge color for filled markers
(circle, square, diamond, pentagram, hexagram, and the four triangles).
• ColorSpec defines a single color to use for the edge (see ColorSpec for more
information).
• none specifies no color, which makes nonfilled markers invisible.
• auto uses the same color as the EdgeColor property.
2-438
Surface Properties
MarkerFaceColor
ColorSpec | {none} | auto
Marker face color. The fill color for markers that are closed shapes (circle,
square, diamond, pentagram, hexagram, and the four triangles).
• ColorSpec defines a single color to use for all marker on the Surface (see
ColorSpec for more information).
• none makes the interior of the marker transparent, allowing the background
to show through.
• auto uses the CData for the vertex located by the marker to determine the
color.
MarkerSize
size in points
Marker size. A scalar specifying the marker size, in points. The default value
for MarkerSize is six points (1 point = 1/72 inch). Note that MATLAB draws the
point marker at 1/3 the specified marker size.
MeshStyle
{both} | row | column
Row and column lines. This property specifies whether to draw all edge lines
or just row or column edge lines.
• both draws edges for both rows and columns.
• row draws row edges only.
• column draws column edges only.
NormalMode
{auto} | manual
MATLAB -generated or user-specified normal vectors. When this property is
auto, MATLAB calculates vertex normals based on the coordinate data. If you
specify your own vertex normals, MATLAB sets this property to manual and
does not generate its own data. See also the VertexNormals property.
Parent
handle
Surface’s parent object. The parent of a Surface object is the Axes in which it is
displayed. You can move a Surface object to another Axes by setting this
property to the handle of the new parent.
Selected
on | {off}
Is object selected. When this property is on, MATLAB displays a dashed
bounding box around the Surface if the SelectionHighlight property is also
2-439
Surface Properties
on. You can, for example, define the ButtonDownFcn to set this property,
allowing users to select the object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing a dashed bounding box around the
Surface. When SelectionHighlight is off, MATLAB does not draw the
handles.
SpecularColorReflectancescalar in the range 0 to 1
Color of specularly reflected light. When this property is 0, the color of the
specularly reflected light depends on both the color of the object from which it
reflects and the color of the light source. When set to 1, the color of the
specularly reflected light depends only on the color or the light source (i.e., the
Light object Color property). The proportions vary linearly for values in
between.
SpecularExponent
scalar >= 1
Harshness of specular reflection. This property controls the size of the specular
spot. Most materials have exponents in the range of 5 to 20.
SpecularStrength
scalar >= 0 and <= 1
Intensity of specular light. This property sets the intensity of the specular
component of the light falling on the Surface. Specular light comes from Light
objects in the Axes.
You can also set the intensity of the ambient and diffuse components of the
light on the Surface object. See the AmbientStrength and DiffuseStrength
properties. Also see the material function.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Class of the graphics object. The class of the graphics object. For Surface
objects, Type is always the string 'surface'.
2-440
Surface Properties
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Surface. Assign this property the handle of a
Uicontextmenu object created in the same Figure as the Surface. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Surface (Control-click on
Macintosh systems).
UserData
matrix
User-specified data. Any matrix you want to associate with the Surface object.
MATLAB does not use this data, but you can access it using the set and get
commands.
VertexNormals
vector or matrix
Surface normal vectors. This property contains the vertex normals for the
Surface. MATLAB generates this data to perform lighting calculations. You
can supply your own vertex normal data, even if it does not match the
coordinate data. This can be useful to produce interesting lighting effects.
Visible
{on} | off
Surface object visibility. By default, all Surfaces are visible. When set to off,
the Surface is not visible, but still exists and you can query and set its
properties.
XData
vector or matrix
X-coordinates. The x-position of the surface points. If you specify a row vector,
surface replicates the row internally until it has the same number of columns
as ZData.
YData
vector or matrix
Y-coordinates. The y-position of the surface points. If you specify a row vector,
surface replicates the row internally until it has the same number of rows as
ZData.
ZData
matrix
Z-coordinates. Z-position of the surface points. See the Description section for
more information.
2-441
surfl
Purpose
2surfl
Surface plot with colormap-based lighting
Syntax
surfl(Z)
surfl(X,Y,Z)
surfl(...,s)
surfl(X,Y,Z,s,k)
h = surfl(...)
Description
The surfl function displays a shaded Surface based on a combination of
ambient, diffuse, and specular lighting models.
surfl(Z) and surfl(X,Y,Z) create three-dimensional shaded Surfaces using
the default direction for the light source and the default lighting coefficients for
the shading model. X, Y, and Z are vectors or matrices that define the x, y, and
z components of a Surface.
surfl(...,’light’) produces a colored, lighted surface using the Light
object. This produces different results than the default lighting method,
surfl(...,'cdata'), which changes the color data for the surface to be the
reflectance of the surface.
surfl(...,s) specifies the direction of the light source. s is a two- or
three-element vector that specifies the direction from a Surface to a light
source. s = [sx sy sz] or s = [azimuth elevation]. The default s is 45˚
counterclockwise from the current view direction.
surfl(X,Y,Z,s,k) specifies the reflectance constant. k is a four-element
vector defining the relative contributions of ambient light, diffuse reflection,
specular reflection, and the specular shine coefficient. k = [ka kd ks shine]
and defaults to [.55,.6,.4,10].
h = surfl(...) returns a handle to a Surface graphics object.
Remarks
For smoother color transitions, use colormaps that have linear intensity
variations (e.g., gray, copper, bone, pink).
The ordering of points in the X, Y, and Z matrices define the inside and outside
of parametric surfaces. If you want the opposite side of the surface to reflect the
2-442
surfl
light source, use surfl(X',Y',Z'). Due to the way surface normal vectors are
computed, surfl requires matrices that are at least 3-by-3.
Examples
View peaks using colormap-based lighting:
[x,y] = meshgrid(–3:1/8:3);
z = peaks(x,y);
surfl(x,y,z);
shading interp
colormap(gray);
axis([–3 3 –3 3 –8 8])
2-443
surfl
To plot a lighted surface from a view direction other than the default:
view([10 10])
grid on
hold on
surfl(peaks)
shading interp
colormap copper
hold off
See Also
2-444
colormap, shading, light
surfnorm
Purpose
2surfnorm
Compute and display 3-D surface normals
Syntax
surfnorm(Z)
surfnorm(X,Y,Z)
[Nx,Ny,Nz] = surfnorm(...)
Description
The surfnorm function computes surface normals for the Surface defined by X,
Y, and Z. The surface normals are unnormalized and valid at each vertex.
Normals are not shown for Surface elements that face away from the viewer.
surfnorm(Z) and surfnorm(X,Y,Z) plot a Surface and its surface normals. Z
is a matrix that defines the z component of the Surface. X and Y are vectors or
matrices that define the x and y components of the Surface.
[Nx,Ny,Nz] = surfnorm(...) returns the components of the
three-dimensional surface normals for the Surface.
Remarks
The direction of the normals is reversed by calling surfnorm with transposed
arguments:
surfnorm(X',Y',Z')
surfl uses surfnorm to compute surface normals when calculating the
reflectance of a Surface.
Algorithm
The surface normals are based on a bicubic fit of the data in X, Y, and Z. For
each vertex, diagonal vectors are computed and crossed to form the normal.
Examples
Plot the normal vectors for a truncated cone.
[x,y,z] = cylinder(1:10);
surfnorm(x,y,z)
axis([−12 12 −12 12 −0.1 1])
2-445
surfnorm
1
0.8
0.6
0.4
0.2
0
10
5
0
−5
−10
See Also
2-446
surf, quiver3
−10
−5
0
5
10
terminal
Purpose
2terminal
Set graphics terminal type
Syntax
terminal
terminal('type')
Description
To add terminal-specific settings (e.g., escape characters, line length), edit the
file terminal.m.
terminal displays a menu of graphics terminal types, prompts for a choice,
then configures MATLAB to run on the specified terminal.
terminal('type') accepts a terminal type string. Valid 'type' strings are
Type
Description
tek401x
Tektronix 4010/4014
tek4100
Tektronix 4100
tek4105
Tektronix 4105
retro
Retrographics card
sg100
Selanar Graphics 100
sg200
Selanar Graphics 200
vt240tek
VT240 & VT340 Tektronix mode
ergo
Ergo terminal
graphon
Graphon terminal
citoh
C.Itoh terminal
xtermtek
xterm, Tektronix graphics
wyse
Wyse WY-99GT
kermit
MS-DOS Kermit 2.23
2-447
terminal
2-448
Type
Description (Continued)
hp2647
Hewlett-Packard 2647
versa
Macintosh with VersaTerm (Tektronix 4010/4014)
versa4100
Macintosh with VersaTerm (Tektronix 4100)
versa4105
Color/grayscale Macintosh with VersaTerm (Tektronix
4105)
hds
Human Designed Systems
text
Purpose
2text
Create Text object in current Axes
Syntax
text(x,y,'string')
text(x,y,z,'string')
text(...'PropertyName',PropertyValue...)
h = text(...)
Description
text is the low-level function for creating Text graphics objects. Use text to
place character strings at specified locations.
text(x,y,'string') adds the string in quotes to the location specified by the
point (x,y).
text(x,y,z,'string') adds the string in 3-D coordinates.
text(x,y,z,'string','PropertyName',PropertyValue....) adds the
string in quotes to location defined by the coordinates and uses the values for
the specified Text properties. See the “Text Properties” section for a list of Text
object properties.
text('PropertyName',PropertyValue....) omits the coordinates entirely
and specifies all properties using property name/property value pairs.
h = text(..) returns a column vector of handles to Text objects, one handle
per object. All forms of the text function optionally return this output
argument.
See the String property for a list of symbols, including Greek letters.
Remarks
Specify the Text location coordinates (the x, y, and z arguments) in the data
units of the current Axes (see “Examples”). The Extent, VerticalAlignment,
and HorizontalAlignment properties control the positioning of the character
string with regard to the Text location point.
If the coordinates are vectors, text writes the string at all locations defined by
the list of points. If the character string is an array the same length as x, y, and
z, text writes the corresponding row of the string array at each point specified.
When specifying strings for multiple Text objects, the string can be
2-449
text
• a cell array of strings
• a padded string matrix
• a string vector using vertical slash characters (‘|’) as separators.
Each element of the specified string array creates a different Text object.
When specifying the string for a single Text object, cell arrays of strings and
padded string matrices result in a Text object with a multiline string, while
vertical slash characters are not interpreted as separators and result in a
single line string containing vertical slashes.
text is a low-level function that accepts property name/property value pairs as
input arguments, however, the convenience form,
text(x,y,z,'string')
is equivalent to:
text('XData',x,'YData',y,'ZData',z,'String','string')
You can specify other properties only as property name/property value pairs.
See the “Text Properties” section for a description of each property. You can
specify properties as property name/property value pairs, structure arrays, and
cell arrays (see the set and get reference pages for examples of how to specify
these data types).
text does not respect the setting of the Figure or Axes NextPlot property. This
allows you to add Text objects to an existing Axes without setting hold to on.
Examples
The statements,
plot(0:pi/20:2*pi,sin(0:pi/20:2*pi))
text(pi,0,' \leftarrow sin(\pi)','FontSize',18)
2-450
text
annotate the point at (pi,0) with the string sin(π):
1
0.8
0.6
0.4
0.2
← sin(π)
0
−0.2
−0.4
−0.6
−0.8
−1
0
1
2
3
4
5
6
7
The statement,
text(x,y,'\ite^{i\omega\tau} = cos(\omega\tau) + i sin(\omega\tau)')
uses embedded TeX sequences to produce:
eiωτ = cos(ωτ) + i sin(ωτ)
See Also
gtext, int2str, num2str, title, xlabel, ylabel, zlabel
The Axes chapter in the Using MATLAB Graphics manual discusses
positioning text.
2-451
text
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Surface
Text
Setting Default Properties
You can set default Text properties on the Axes, Figure, and Root levels:
set(0,'DefaulttextProperty',PropertyValue...)
set(gcf,'DefaulttextProperty',PropertyValue...)
set(gca,'DefaulttextProperty',PropertyValue...)
Where Property is the name of the Text property and PropertyValue is the
value you are specifying. Use set and get to access Text properties.
Property List
Property Name
The following table lists all Text properties and provides a brief description of
each. The property name links take you to an expanded description of the
properties.
Property Description
Property Value
Defining the character string
Editing
Enable or disable editing mode.
Values: on, off
Default: off
Interpreter
Enable or disable TeX interpretation
Values: tex, none
Default: tex
String
The character string (including list of
TeX character sequences)
Value: character string
Positioning the character string
2-452
text
Property Name
Property Description
Property Value
Extent
Position and size of Text object
Values: [left, bottom, width,
height]
HorizontalAlignment
Horizontal alignment of Text string
Values: left, center, right
Default: left
Position
Position of Text Extent rectangle
Values: [x, y, z] coordinates
Default: [] empty matrix
Rotation
Orientation of Text object
Values: scalar (degrees)
Default: 0
Units
Units for Extent and Position
properties
Values: pixels, normalized,
inches, centimeters,
points, data
Default: data
VerticalAlignment
Vertical alignment of Text string
Values: top, cap, middle,
baseline, bottom
Default: middle
FontAngle
Select italic-style font
Values: normal, italic,
oblique
Default: normal
FontName
Select font family
Values: font name
Default: Helvetica
FontSize
Size of font
Values: size in FontUnits
Default: 10 points
FontUnits
Units for FontSize property
Values: points, normalized,
inches, centimeters, pixels
Default: points
FontWeight
Weight of text characters
Values: light, normal, demi,
Specifying the Font
bold
Default: normal
2-453
text
Property Name
Property Description
Property Value
Clipping
Clipping to Axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the
Text (useful for animation)
Values: normal, none, xor,
background
Default: normal
SelectionHighlight
Highlight Text when selected
(Selected property set to on)
Values: on, off
Default: on
Visible
Make the Text visible or invisible
Values: on, off
Default: on
Color
Color of the Text
ColorSpec
Controlling the Appearance
Controlling Access to Text Objects
HandleVisibility
Determines if and when the the
Text’s handle is visible to other
functions
Values: on, callback, off
Default: on
HitTest
Determines if the Text can become
the current object (see the Figure
CurrentObject property)
Values: on, off
Default: on
General Information About Text Objects
Children
Text objects have no children
Values: [] (empty matrix)
Parent
The parent of a Text object is always
an Axes object
Value: Axes handle
Selected
Indicate whether the Text is in a
“selected” state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'text'
2-454
text
Property Name
Property Description
Property Value
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
Controlling Callback Routine Execution
BusyAction
Specify how to handle callback
routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a mouse button is
pressed on over the Text
Values: string
Default: '' (empty string)
CreateFcn
Define a callback routine that
executes when an Text is created
Values: string
Default: '' (empty string)
DeleteFcn
Define a callback routine that
executes when the Text is deleted
(via close or delete)
Values: string
Default: '' (empty string)
Interruptible
Determine if callback routine can be
interrupted
Values: on, off
Default: on (can be
interrupted)
UIContextMenu
Associate a context menu with the
Text
Values: handle of a
Uicontrextmenu
2-455
Text Properties
Text Properties
2Text Properties
This section lists property names along with the types of values each accepts.
Curly braces { } enclose default values.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routines always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is over the Text object. Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace.
Children
matrix (read only)
The empty matrix; Text objects have no children.
Clipping
on | {off}
Clipping mode. When Clipping is on, MATLAB does not display any portion
of the Text that is outside the Axes.
Color
ColorSpec
Text color. A three-element RGB vector or one of MATLAB ’s predefined names,
specifying the Text color. The default value for Color is white. See ColorSpec
for more information on specifying color.
2-456
Text Properties
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Text object. You must
define this property as a default value for Text. For example, the statement,
set(0,'DefaultTextCreateFcn',...
'set(gcf,''Pointer'',’'crosshair'')')
defines a default value on the Root level that sets the Figure Pointer property
to a crosshair whenever you create a Text object. MATLAB executes this
routine after setting all Text properties. Setting this property on an existing
Text object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
DeleteFcn
string
Delete Text callback routine. A callback routine that executes when you delete
the Text object (e.g., when you issue a delete command or clear the Axes or
Figure). MATLAB executes the routine before destroying the object’s
properties so these values are available to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
Editing
on | {off}
Enable or disable editing mode. When this property is set to the default of off,
you cannot edit the text string interactively (i.e., you must change the String
property to change the text). When this property is set to on, MATLAB places
an insert cursor at the beginning of the text string and enables editing. To
apply the new text string:
• Press the ESC key
• Clicking in any Figure window (including the current Figure)
• Reset the Editing property to off
MATLAB then updates the String property to contain the new text and resets
the Editing property to off. You must reset the Editing property to on to
again resume editing.
2-457
Text Properties
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and
erase Text objects. Alternative erase modes are useful for creating animated
sequences, where controlling the way individual object redraw is necessary to
improve performance and obtain the desired effect.
• normal — Redraw the affected region of the display, performing the
three-dimensional analysis necessary to ensure that all objects are rendered
correctly. This mode produces the most accurate picture, but is the slowest.
The other modes are faster, but do not perform a complete redraw and are
therefore less accurate.
• none — Do not erase the Text when it is moved or destroyed. While the object
is still visible on the screen after erasing with EraseMode none, you cannot
print it because MATLAB stores no information about its former location.
• xor — Draw and erase the Text by performing an exclusive OR (XOR) with
each pixel index of the screen beneath it. When the Text is erased, it does not
damage the objects beneath it. However, when Text is drawn in xor mode, its
color depends on the color of the screen beneath it and is correctly colored
only when over Axes background Color, or the Figure background Color if
the Axes Color is set to none.
• background — Erase the Text by drawing it in the background Color, or the
Figure background Color if the Axes Color is set to none. This damages
objects that are behind the erased Text, but Text is always properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints Figures as if the
EraseMode of all objects is normal. This means graphics objects created with
EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g.,
XORing a pixel color with that of the pixel behind it) and ignore
three-dimensional sorting to obtain greater rendering speed. However, these
techniques are not applied to the printed output.
You can use the MATLAB capture command or other screen capture
application to create an image of a Figure containing non-normal mode objects.
2-458
Text Properties
Extent
position rectangle (read only)
Position and size of Text. A four-element read-only vector that defines the size
and position of the Text string:
[left,bottom,width,height]
If the Units property is set to data (the default), left and bottom are the x and
y coordinates of the lower-left corner of the Text Extent rectangle.
For all other values of Units, left and bottom are the distance from the
lower-left corner of the Axes position rectangle to the lower-left corner of the
Text Extent rectangle. width and height are the dimensions of the Extent
rectangle. All measurements are in units specified by the Units property.
FontAngle
{normal} | italic | oblique
Character slant. MATLAB uses this property to select a font from those
available on your particular system. Generally, setting this property to italic
or oblique selects a slanted font.
FontName
string
Font family. A string specifying the name of the font to use for the Text object.
To display and print properly, this must be a font that your system supports.
The default font is Helvetica.
FontSize
size in FontUnits
Font size. An integer specifying the font size to use for Text, in units
determined by the FontUnits property. The default point size is 10 (1 point =
1/72 inch).
FontWeight
light | {normal} | demi | bold
Weight of Text characters. MATLAB uses this property to select a font from
those available on your particular system. Generally, setting this property to
bold or demi causes MATLAB to use a bold font.
FontUnits
{points} | normalized | inches |
centimeters | pixels
Font size units. MATLAB uses this property to determine the units used by the
FontSize property. Normalized units interpret FontSize as a fraction of the
height of the parent Axes. When you resize the Axes, MATLAB modifies the
screen FontSize accordingly. pixels, inches, centimeters, and points are
absolute units (1 point = 1/72 inch).
2-459
Text Properties
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be returned
by functions that obtain handles by searching the object hierarchy or querying
handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf,
and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the Text can become the
current object (as returned by the gco command and the Figure CurrentObject
2-460
Text Properties
property) as a result of a mouse click on the Text. If HiTest is off, clicking on
the Text selects the object below it (which is usually the Axes containing it).
For example, suppose you define the button down function of an Image (see the
ButtonDownFcn property) to display text at the location you click on with the
mouse,
First define the callback routine,
function bd_function
pt = get(gca,'CurrentPoint');
text(pt(1,1),pt(1,2),pt(1,3),...
'{\fontsize{20}\oplus} The spot to label',...
'HitTest','off')
Now display an Image, setting its ButtonDownFcn property to the callback
routine:
load earth
image(X,'ButtonDownFcn','bd_function'); colormap(map)
When you click on the Image, MATLAB displays the text string at that
location. With HitTest set to off, existing text cannot intercept any
subsequent button down events that occur over the text. This enables the
Image’s button down function to execute.
HorizontalAlignment{left} | center | right
Horizontal alignment of Text. This property specifies the horizontal
justification of the Text string. It determines where MATLAB places the string
with regard to the point specified by the Position property. The following
picture illustrates the alignment options:
Text HorizontalAlignment property viewed with the VerticalAlignment
property set to middle (the default).
Left
Center
Right
See the Extent property for related information.
2-461
Text Properties
Interpreter
{tex} | none
Interpret Tex instructions. This property controls whether MATLAB interprets
certain characters in the String property as Tex instructions (default) or
displays all characters literally. See the String property for a list of support
Tex instructions.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Text callback routine can be interrupted by subsequently invoked
callback routines. Text objects have four properties that define callback
routines: ButtonDownFcn, CreateFcn, and DeleteFcn. See the BusyAction
property for information on how MATLAB executes callback routines.
Parent
handle
Text object’s parent. The handle of the Text object’s parent object. The parent of
a Text object is the Axes in which it is displayed. You can move a Text object to
another Axes by setting this property to the handle of the new parent.
Position
[x,y,[z]]
Location of Text. A two- or three-element vector, [x y [z]], that specifies the
location of the text in three dimensions. If you omit the z value, it defaults to 0.
All measurements are in units specified by the Units property. Initial value is
[0 0 0].
Rotation
scalar (default = 0)
Text orientation. This property determines the orientation of the Text string.
Specify values of rotation in degrees (positive angles cause counterclockwise
rotation).
Selected
on | {off}
Is object selected. When this property is on, MATLAB displays selection handles
if the SelectionHighlight property is also on. You can, for example, define the
ButtonDownFcn to set this property, allowing users to select the object with the
mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing four edge handles and four corner
2-462
Text Properties
handles. When SelectionHighlight is off, MATLAB does not draw the
handles.
string
String
The Text string. Specify this property as a quoted string for single-line strings,
or as a cell array of strings or a padded string matrix for multiline strings.
MATLAB displays this string at the specified location. Vertical slash
characters are not interpreted as linebreaks in Text strings, and are drawn as
part of the Text string. See the “Remarks” section for more information.
When the Text Interpreter property is Tex (the default), you can use a subset
of TeX commands embedded in the string to produce special characters such as
Greek letters and mathematical symbols. The following table lists these
characters and the character sequence used to define them.
Character
Sequence
Symbol
Character
Sequence
Symbol
Character
Sequence
Symbol
\alpha
α
\upsilon
υ
\sim
∼
\beta
β
\phi
ϕ
\leq
≤
\gamma
γ
\chi
χ
\infty
∞
\delta
δ
\psi
ψ
\clubsuit
♣
\epsilon
ε
\omega
ω
\diamondsuit
♦
\zeta
ζ
\Gamma
Γ
\heartsuit
♥
\eta
η
\Delta
∆
\spadesuit
♠
\theta
θ
\Theta
Θ
\leftrightarrow
↔
\vartheta
υ
\Lambda
Λ
\leftarrow
←
\iota
ι
\Xi
Ξ
\uparrow
↑
\kappa
κ
\Pi
Π
\rightarrow
→
\lambda
λ
\Sigma
Σ
\downarrow
↓
\mu
µ
\Upsilon
Υ
\circ
°
2-463
Text Properties
Character
Sequence
Symbol
Character
Sequence
Symbol
Character
Sequence
Symbol
\nu
ν
\Phi
Φ
\pm
±
\xi
ξ
\Psi
Ψ
\geq
≥
\pi
π
\Omega
Ω
\propto
∝
\rho
ρ
\forall
∀
\partial
∂
\sigma
σ
\exists
∃
\bullet
•
\varsigma
ζ
\ni
∋
\div
÷
\tau
τ
\cong
≅
\neq
≠
\equiv
≡
\approx
≈
\aleph
ℵ
\Im
ℑ
\Re
ℜ
\wp
℘
\otimes
⊗
\oplus
⊕
\oslash
∅
\cap
∩
\cup
∪
\supseteq
⊇
\supset
⊃
\subseteq
⊆
\subset
⊂
\int
∫
\in
∈
\o
ο
\rfloor

\lceil

\nabla
∇
\lfloor

\cdot
⋅
\ldots
…
\perp
⊥
\neg
¬
\prime
′
\wedge
∧
\times
×
\0
∅
\rceil

\surd
√
\mid
|
\vee
∨
\varpi
ϖ
\copyright

\langle
〈
\rangle
〉
You can also specify stream modifiers that control the font used. The first four
modifiers are mutually exclusive. However, you can use \fontname in
combination with one of the other modifiers:
2-464
Text Properties
• \bf – bold font
• \it – italics font
• \sl – oblique font (rarely available)
• \rm – normal font
• \fontname{fontname} – specify the name of the font family to use.
• \fontsize{fontsize} – specify the font size in FontUnits.
Stream modifiers remain in effect until the end of the string or only within the
context defined by braces { }.
The subscript character “_” and the superscript character “^” modify the
character or substring defined in braces immediately following.
To print the special characters used to define the Tex strings when
Interpreter is Tex, prefix them with the backslash “\” character: \\, \{, \} \_,
\^.
See the “Example” section for more information.
When Interpreter is none, no characters in the String are interpreted, and all
are displayed when the text is drawn.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Class of graphics object. For Text objects, Type is always the string 'text'.
Units
pixels | normalized | inches |
centimeters | points | {data}
Units of measurement. This property specifies the units MATLAB uses to
interpret the Extent and Position properties. All units are measured from the
lower-left corner of the Axes plotbox. Normalized units map the lower-left
corner of the rectangle defined by the Axes to (0,0) and the upper-right corner
to (1.0,1.0). pixels, inches, centimeters, and points are absolute units (1
point = 1/72 inch). data refers to the data units of the parent Axes.
2-465
Text Properties
If you change the value of Units, it is good practice to return it to its default
value after completing your computation so as not to affect other functions that
assume Units is set to the default value.
UserData
matrix
User-specified data. Any data you want to associate with the Text object.
MATLAB does not use this data, but you can access it using set and get.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the Text. Assign this property the handle of a
Uicontextmenu object created in the same Figure as the Text. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the Text (Control-click on
Macintosh systems)
VerticalAlignment top | cap | {middle} | baseline |
bottom
Vertical alignment of Text. This property specifies the vertical justification of
the text string. It determines where MATLAB places the string with regard to
the value of the Position property. The possible values mean:
• top – Place the top of the string’s Extent rectangle at the specified y-position.
• cap – Place the string so that the top of a capital letter is at the specified
y-position.
• middle – Place the middle of the string at specified y-position.
• baseline – Place font baseline at the specified y-position.
• bottom – Place the bottom of the string’s Extent rectangle at the specified
y-position.
2-466
Text Properties
The following picture illustrates the alignment options:
Text VerticalAlignment property viewed with the HorizontalAlignment
property set to left (the default).
Middle
Baseline
Visible
Top
Cap
Bottom
{on} | off
Text visibility. By default, all Text is visible. When set to off, the Text is not
visible, but still exists and you can query and set its properties.
2-467
title
Purpose
2title
Add title to current Axes
Syntax
title('string')
title(fname)
title(...,'PropertyName',PropertyValue,...)
h = title(...)
Description
Each Axes graphics object can have one title. The title is located at the top and
in the center of the axes.
title('string') outputs the string at the top and in the center of the current
axes.
title(fname) evaluates the function that returns a string and displays the
string at the top and in the center of the current axes.
title(...,'PropertyName',PropertyValue,...) specifies property name
and property value pairs for the Text graphics object that title creates.
h = title(...)
Examples
returns the handle to the text object used as the title.
Display today’s date in the current Axes:
title(date)
Include a variable’s value in a title:
f = 70;
c = (f—32)/1.8;
title(['Temperature is ',num2str(c),'C'])
Include a variable’s value in a title and set the color of the title to yellow:
n = 3;
title(['Case number #',int2str(n)],'Color','y')
Include Greek symbols in a title:
title('\ite^{\omega\tau} = cos(\omega\tau) + isin(\omega\tau)’)
The Text object String property lists the available symbols.
2-468
title
Remarks
title sets the Title property of the current Axes graphics object to a new Text
graphics object. See the Text String property for more information.
See Also
gtext, int2str, num2str, plot, text, xlabel, ylabel, zlabel
2-469
trimesh
Purpose
2trimesh
Triangular mesh plot
Syntax
trimesh(Tri,X,Y,Z)
trimesh(Tri,X,Y,Z,C)
trimesh(...'PropertyName',PropertyValue...)
h = trimesh(...)
Description
trimesh(Tri,X,Y,Z) displays triangles defined in the m-by-3 face matrix Tri
as a mesh. Each row of Tri defines a single triangular face by indexing into the
vectors or matrices that contain the X, Y, and Z vertices.
trimesh(Tri,X,Y,Z,C) specifies color defined by C in the same manner as the
surf function. MATLAB performs a linear transformation on this data to
obtain colors from the current colormap.
trimesh(...'PropertyName',PropertyValue...) specifies additional Patch
property names and values for the Patch graphics object created by the
function.
h = trimesh(...) returns a handle to a Patch graphics object.
Example
Create vertex vectors and a face matrix, then create a triangular mesh plot.
x = rand(1,50);
y = rand(1,50);
z = peaks(6*x–3,6*x–3);
tri = delaunay(x,y);
trimesh(tri,x,y,z)
See Also
2-470
patch, trisurf, delaunay
trisurf
Purpose
2trisurf
Triangular surface plot
Syntax
trisurf(Tri,X,Y,Z)
trisurf(Tri,X,Y,Z,C)
trisurf(...'PropertyName',PropertyValue...)
h = trisurf(...)
Description
trisurf(Tri,X,Y,Z) displays triangles defined in the m-by-3 face matrix Tri
as a surface. Each row of Tri defines a single triangular face by indexing into
the vectors or matrices that contain the X, Y, and Z vertices.
trisurf(Tri,X,Y,Z,C) specifies color defined by C in the same manner as the
surf function. MATLAB performs a linear transformation on this data to
obtain colors from the current colormap.
trisurf(...'PropertyName',PropertyValue...) specifies additional Patch
property names and values for the Patch graphics object created by the
function.
h = trisurf(...) returns a Patch handle.
Example
Create vertex vectors and a face matrix, then create a triangular surface plot.
x = rand(1,50);
y = rand(1,50);
z = peaks(6*x–3,6*x–3);
tri = delaunay(x,y);
trisurf(tri,x,y,z)
See Also
patch, surf, trimesh, delaunay
2-471
view
Purpose
Syntax
2view
Viewpoint specification
view(az,el)
view([az,el])
view([x,y,z])
view(2)
view(3)
view(T)
[az,el] = view
T = view
Description
The position of the viewer (the viewpoint) determines the orientation of the
Axes. You specify the viewpoint in terms of azimuth and elevation, or by a point
in three-dimensional space.
view(az,el) and view([az,el]) set the viewing angle for a
three-dimensional plot. The azimuth, az, is the horizontal rotation about the
z-axis as measured in degrees from the negative y-axis. Positive values indicate
counterclockwise rotation of the viewpoint. el is the vertical elevation of the
viewpoint in degrees. Positive values of elevation correspond to moving above
the object; negative values correspond to moving below the object.
view([x,y,z]) sets the viewpoint to the Cartesian coordinates x, y, and z. The
magnitude of (x,y,z) is ignored.
view(2) sets the default two-dimensional view, az = 0, el = 90.
view(3) sets the default three-dimensional view, az = —37.5, el = 30.
view(T) sets the view according to the transformation matrix T, which is a
4-by-4 matrix such as a perspective transformation generated by viewmtx.
[az,el] = view returns the current azimuth and elevation.
T = view returns the current 4-by-4 transformation matrix.
2-472
view
Remarks
Azimuth is a polar angle in the x-y plane, with positive angles indicating counterclockwise rotation of the viewpoint. Elevation is the angle above (positive
angle) or below (negative angle) the x-y plane.
This diagram illustrates the coordinate system. The arrows indicate positive
directions:
z
y
Center of
Plot Box
Viewpoint
Elevation
x
Azimuth
-y
Examples
View the object from directly overhead:
az = 0;
el = 90;
view(az, el);
Set the view along the y-axis, with the x-axis extending horizontally and the
z-axis extending vertically in the Figure:
view([0 0]);
Rotate the view about the z-axis by 180°:
az = 180;
el = 90;
view(az, el);
See Also
viewmtx, axes
2-473
view
Axes graphics object properties: CameraPosition, CameraTarget,
CameraViewAngle, Projection.
2-474
viewmtx
Purpose
2viewmtx
View transformation matrices
Syntax
T = viewmtx(az,el)
T = viewmtx(az,el,phi)
T = viewmtx(az,el,phi,xc)
Description
viewmtx computes a 4-by-4 orthographic or perspective transformation matrix
that projects four-dimensional homogeneous vectors onto a two-dimensional
view surface (e.g., your computer screen).
T = viewmtx(az,el) returns an orthographic transformation matrix
corresponding to azimuth az and elevation el. az is the azimuth (i.e.,
horizontal rotation) of the viewpoint in degrees. el is the elevation of the
viewpoint in degrees. This returns the same matrix as the commands
view(az,el)
T = view
but does not change the current view.
T = viewmtx(az,el,phi) returns a perspective transformation matrix. phi is
the perspective viewing angle in degrees. phi is the subtended view angle of the
normalized plot cube (in degrees) and controls the amount of perspective
distortion:
Phi
Description
0 degrees
Orthographic projection
10 degrees
Similar to telephoto lens
25 degrees
Similar to normal lens
60 degrees
Similar to wide angle lens
You can use the matrix returned to set the view transformation with view(T).
The 4-by-4 perspective transformation matrix transforms four-dimensional
homogeneous vectors into unnormalized vectors of the form (x,y,z,w), where w is
not equal to 1. The x- and y-components of the normalized vector (x/w, y/w, z/w,
1) are the desired two-dimensional components (see example below).
2-475
viewmtx
T = viewmtx(az,el,phi,xc) returns the perspective transformation matrix
using xc as the target point within the normalized plot cube (i.e., the camera is
looking at the point xc). xc is the target point that is the center of the view. You
specify the point as a three-element vector, xc = [xc,yc,zc], in the interval
[0,1]. The default value is xc = [0,0,0].
Remarks
A four-dimensional homogenous vector is formed by appending a 1 to the
corresponding three-dimensional vector. For example, [x,y,z,1] is the
four-dimensional vector corresponding to the three-dimensional point [x,y,z].
Examples
Determine the projected two-dimensional vector corresponding to the
three-dimensional point (0.5,0.0,—3.0) using the default view direction. Note
that the point is a column vector.
A =
x4d
x2d
x2d
x2d
viewmtx(—37.5,30);
= [.5 0 —3 1]';
= A∗x4d;
= x2d(1:2)
=
0.3967
—2.4459
Vectors that trace the edges of a unit cube are
x = [0
y = [0
z = [0
2-476
1
0
0
1
1
0
0
1
0
0
0
0
0
0
1
1
0
1
1
1
1
0
1
1
0
0
1
1
0
1
1
0
0
1
1
0
1
1
1
0
1
1
0];
1];
0];
viewmtx
Transform the points in these vectors to the screen, then plot the object:
A = viewmtx(—37.5,30);
[m,n] = size(x);
x4d = [x(:),y(:),z(:),ones(m*n,1)]';
x2d = A*x4d;
x2 = zeros(m,n); y2 = zeros(m,n);
x2(:) = x2d(1,:);
y2(:) = x2d(2,:);
plot(x2,y2)
1.6
1.4
1.2
1
0.8
0.6
0.4
0.2
0
−0.8
−0.6
−0.4
−0.2
0
0.2
0.4
0.6
0.8
Use a perspective transformation with a 25 degree viewing angle:
A =
x4d
x2d
x2d
x2d
viewmtx(—37.5,30,25);
= [.5 0 —3 1]';
= A∗x4d;
= x2d(1:2)/x2d(4)
% Normalize
=
0.1777
—1.8858
2-477
viewmtx
Transform the cube vectors to the screen and plot the object:
A = viewmtx(—37.5,30,25);
[m,n] = size(x);
x4d = [x(:),y(:),z(:),ones(m*n,1)]';
x2d = A*x4d;
x2 = zeros(m,n); y2 = zeros(m,n);
x2(:) = x2d(1,:)./x2d(4,:);
y2(:) = x2d(2,:)./x2d(4,:);
plot(x2,y2)
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−0.6
See Also
2-478
view
−0.4
−0.2
0
0.2
0.4
0.6
0.8
waterfall
Purpose
Syntax
2waterfall
Waterfall plot
waterfall(Z)
waterfall(X,Y,Z)
waterfall(...,C)
h = waterfall(...)
Description
The waterfall function draws a mesh similar to the meshz function, but it does
not generate lines from the columns of the matrices. This produces a
“waterfall” effect.
waterfall(Z) creates a waterfall plot using x = 1:size(Z,1) and
y = 1:size(Z,1). Z determines the color, so color is proportional to surface
height.
waterfall(X,Y,Z) creates a waterfall plot using the values specified in X, Y,
and Z. Z also determines the color, so color is proportional to the surface height.
If X and Y are vectors, X corresponds to the columns of Z, and Y corresponds to
the rows, where length(x) = n, length(y) = m, and [m,n] = size(Z). X and
Y are vectors or matrices that define the x and y coordinates of the plot. Z is a
matrix that defines the z coordinates of the plot (i.e., height above a plane). If
C is omitted, color is proportional to Z.
waterfall(...,C) uses scaled color values to obtain colors from the current
colormap. Color scaling is determined by the range of C, which must be the
same size as Z. MATLAB performs a linear transformation on C to obtain colors
from the current colormap.
h = waterfall(...) returns the handle of the Patch graphics object used to
draw the plot.
Remarks
For column-oriented data analysis, use waterfall(Z') or
waterfall(X',Y',Z').
2-479
waterfall
Examples
Produce a waterfall plot of the peaks function:
[X,Y,Z] = peaks(30);
waterfall(X,Y,Z)
10
5
0
−5
−10
4
3
2
2
0
1
0
−2
−1
−4
Algorithm
−2
−3
The range of X, Y, and Z, or the current setting of the Axes Llim, YLim, and ZLim
properties, determines the range of the Axes (also set by axis). The range of C,
or the current setting of the Axes Clim property, determines the color scaling
(also set by caxis).
The CData property for the Patch graphics objects specifies the color at every
point along the edge of the Patch, which determines the color of the lines.
The waterfall plot looks like a mesh surface, however, it is a Patch graphics
object. To create a Surface plot similar to waterfall, use the meshz function
and set the MeshStyle property of the Surface to 'Row'. For a discussion of
parametric surfaces and related color properties, see surf.
See Also
axes, axis, caxis, meshz, surf
Properties for Patch graphics objects.
2-480
whitebg
Purpose
2whitebg
Change Axes background color
Syntax
whitebg
whitebg(h)
whitebg(ColorSpec)
whitebg(h,ColorSpec)
Description
whitebg complements the colors in the current Figure.
whitebg(h) complements colors in all Figures specified in the vector h.
whitebg(ColorSpec) and whitebg(h,ColorSpec) change the color of the
Axes, which are children of the Figure, to the color specified by ColorSpec.
Remarks
whitebg changes the colors of the Figure’s children, with the exception of
shaded surfaces. This ensures that all objects are visible against the new
background color. whitebg sets the default properties on the Root such that all
subsequent Figure use the new background color.
Examples
Set the background color to blue-gray:
whitebg([0 .5 .6])
Set the background color to blue:
whitebg('blue')
See Also
ColorSpec
The Figure graphics object property InvertHardCopy.
2-481
xlabel, ylabel, zlabel
Purpose
Syntax
2xlabel, ylabel, zlabel
Label the x-, y-, and z-axis
xlabel('string')
xlabel(fname)
xlabel(...,'PropertyName',PropertyValue,...)
h = xlabel(...)
ylabel(...)
h = ylabel(...)
zlabel(...)
h = zlabel(...)
Description
Each Axes graphics object can have one label for the x-, y-, and z-axis. The label
appears beneath its respective axis in a two-dimensional plot and to the side or
beneath the axis in a three-dimensional plot.
xlabel('string') labels the x-axis of the current Axes.
xlabel(fname) evaluates the function fname, which must return a string,
then displays the string beside the x-axis.
xlabel(...,'PropertName',PropertyValue,...) specifies property name
and property value pairs for the Text graphics object created by xlabel.
h = xlabel(...), h = ylabel(...), and h = zlabel(...) return the
handle to the Text object used as the label.
ylabel(...) and zlabel(...) label the y-axis and z-axis, respectively, of the
current Axes.
Remarks
Re-issuing an xlabel, ylabel, or zlabel command causes the new label to
replace the old label.
For three-dimensional graphics, MATLAB puts the label in the front or side,
so that it is never hidden by the plot.
See Also
2-482
text, title
xlim, ylim, zlim
Purpose
2xlim, ylim, zlim
Syntax
Note that the syntax for each of these three functions is the same; only the xlim
function is used for simplicity. Each operates on the respective x-, y-, or z-axis.
Set or query axis limits
xlim
xlim([xmin xmax])
xlim('mode')
xlim('auto')
xlim('manual')
xlim(axes_handle,...)
Description
xlim with no arguments return the respective limits of the current axes.
xlim([xmin xmax]) sets the axis limits in the current axes to the specified
values.
xlim('mode') returns the current value of the axis limits mode, which can be
either auto (the default) or manual.
xlim('auto') sets the axis limit mode to auto.
xlim('manual') sets the respective axis limit mode to manual.
xlim(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
these functions operate on the current axes.
Remarks
xlim, ylim, and zlim set or query values of the Axes object XLim, YLim, ZLim,
and XLimMode, YLimMode, ZLimMode properties.
When the axis limit modes are auto (the default), MATLAB uses limits that
span the range of the data being displayed and are round numbers. Setting a
value for any of the limits also sets the corresponding mode to manual. Note
that high-level plotting functions like plot and surf reset both the modes and
the limits. If you set the limits on an existing graph and want to maintain these
limits while adding more graphs, use the hold command.
2-483
xlim, ylim, zlim
Examples
This example illustrates how to set the x- and y-axis limits to match the actual
range of the data, rather than the rounded values of [-2 3] for the x-axis and
[-2 4] for the y-axis originally selected by MATLAB.
[x,y] = meshgrid([−1.75:.2:3.25]);
z = x.*exp(−x.^2−y.^2);
surf(x,y,z)
xlim([−1.75 3.25])
ylim([−1.75 3.25])
0.5
0
−0.5
3
2
3
2
1
1
0
−1
See Also
0
−1
axis
The Axes properties XLim, YLim, ZLim
The “Aspect Ratio” section in the Using MATLAB Graphics manual.
2-484
zoom
Purpose
2zoom
Zoom in and out on a 2-D plot
Syntax
zoom on
zoom off
zoom out
zoom reset
zoom
zoom xon
zoom yon
zoom(factor)
zoom(fig, option)
Description
zoom on turns on interactive zooming. When interactive zooming is enabled in
a Figure, pressing a mouse button while your cursor is within an Axes zooms
into the point or out from the point beneath the mouse. Zooming changes the
Axes limits.
• For a single-button mouse, zoom in by pressing the mouse button and zoom
out by simultaneously pressing Shift and the mouse button.
• For a two- or three-button mouse, zoom in by pressing the left mouse button
and zoom out by pressing the right mouse button.
Clicking and dragging over an Axes when interactive zooming is enabled draws
a rubber-band box. When the mouse button is released, the Axes zoom in to the
region enclosed by the rubber-band box.
Double-clicking over an Axes returns the Axes to its initial zoom setting.
zoom off turns interactive zooming off.
zoom out returns the plot to its initial zoom setting.
zoom reset remembers the current zoom setting as the initial zoom setting.
Later calls to zoom out, or double-clicks when interactive zoom mode is
enabled, will return to this zoom level.
zoom toggles the interactive zoom status.
zoom xon and zoom yon sets zoom on for the x- and y-axis, respectively.
2-485
zoom
zoom(factor) zooms in or out by the specified zoom factor, without affecting
the interactive zoom mode. Values greater than 1 zoom in by that amount,
while numbers greater than 0 and less than 1 zoom out by 1/factor.
zoom(fig, option) Any of the above options can be specified on a figure other
than the current figure using this syntax.
Remarks
zoom changes the Axes limits by a factor of two (in or out) each time you press
the mouse button while the cursor is within an Axes. You can also click and
drag the mouse to define a zoom area, or double-click to return to the initial
zoom level.
2-486
dialog
Purpose
2dialog
Create and display dialog box
Syntax
h = dialog('PropertyName',PropertyValue,...)
Description
h = dialog('PropertyName',PropertyValue,...) returns a handle to a
dialog box. This function creates a Figure graphics object and sets the Figure
properties recommended for dialog boxes. You can specify any valid Figure
property value.
See Also
errordlg, figure, helpdlg, inputdlg, pagedlg, printdlg, questdlg, uiwait,
uiresume, warndlg
2-487
dragrect
Purpose
2dragrect
Drag rectangles with mouse
Syntax
[finalrect] = dragrect(initialrect)
[finalrect] = dragrect(initialrect,stepsize)
Description
[finalrect] = dragrect(initialrect) tracks one or more rectangles
anywhere on the screen. The n-by-4 matrix, rect, defines the rectangles. Each
row of rect must contain the initial rectangle position as
[left bottom width height] values. dragrect returns the final position of the
rectangles in finalrect.
[finalrect] = dragrect(initialrect,steprize) moves the rectangles in
increments of stepsize. The lower-left corner of the first rectangle is
constrained to a grid of size stepsize starting at the lower-left corner of the
figure, and all other rectangles maintain their original offset from the first
rectangle. [finalRect] = dragrect(...) returns the final positions of the
rectangles when the mouse button is released. The default stepsize is 1.
Remarks
dragrect returns immediately if a mouse button is not currently pressed. Use
dragrect in a ButtonDownFcn, or from the commandline in conjunction with
waitforbuttonpress to ensure that the mouse button is down when dragrect
is called. dragrect returns when you release the mouse button.
Example
Drag a rectangle that is 50 pixels wide and 100 pixels in height.
waitforbuttonpress
point1 = get(gcf,'CurrentPoint') % button down detected
rect = [point1(1,1) point1(1,2) 50 100]
[r2] = dragrect(rect)
See Also
2-488
rbbox, waitforbuttonpress
errordlg
Purpose
2errordlg
Create and display an error dialog box
Syntax
errordlg
errordlg('errorstring')
errordlg('errorstring','dlgname')
errordlg('errorstring','dlgname','on')
h = errordlg(...)
Description
errordlg creates an error dialog box, or if the named dialog exists, errordlg
pops the named dialog in front of other windows.
errordlg displays a dialog box named 'Error Dialog' that contains the
string 'This is the default error string.'
errordlg('errorstring') displays a dialog box named 'Error Dialog' that
contains the string 'errorstring'.
errordlg('errorstring','dlgname') displays a dialog box named
'dlgname' that contains the string 'errorstring'.
errordlg('errorstring','dlgname','on') specifies whether to replace an
existing dialog box having the same name. 'on' brings an existing error dialog
having the same name to the foreground. In this case, errordlg does not create
a new dialog.
h = errordlg(...) returns the handle of the dialog box.
Remarks
MATLAB sizes the dialog box to fit the string 'errorstring'. The error dialog
box has an OK pushbutton and remains on the screen until you press the OK
button or the Return key. After pressing the button, the error dialog box
disappears.
The appearance of the dialog box depends on the windowing system you use.
Examples
The function
errordlg('File not found','File Error');
2-489
errordlg
displays this dialog box on an X-Windows system:
See Also
2-490
dialog, helpdlg, msgbox, questdlg, warndlg
gcbo
Purpose
Syntax
2gcbo
Return the handle of the object whose callback is currently executing
h = gcbo
[h, figure] = gcbo
Description
h = gcbo returns the handle of the graphics object whose callback is executing.
[h, figure] = gcbo returns the handle of the current callback object and the
handle of the Figure containing this object.
Remarks
MATLAB stores the handle of the object whose callback is executing in the
Root’s CallbackObject property. If a callback interrupts another callback,
MATLAB replaces the CallbackObject value with the handle of the object
whose callback is interrupting. When that callback completes, MATLAB
restores the handle of the object whose callback was interrupted.
The Root CallbackObject property is read-only, so its value is always valid at
any time during callback execution. The Root CurrentFigure property, and
the Figure CurrentAxes and CurrentObject properties (returned by gcf, gca,
and gco respectively) are user settable, so they can change during the
execution of a callback, especially if that callback is interrupted by another
callback. Therefore, those functions are not reliable indicators of which object’s
callback is executing.
When you write callback routines for the CreateFcn and DeleteFcn of any
object and the Figure ResizeFcn, you must use gcbo since those callbacks do
not update the Root’s CurrentFigure property, or the Figure’s CurrentObject
or CurrentAxis properties; they only update the Root’s CallbackObject
property.
When no callbacks are executing, gcbo returns [] (an empty matrix).
See Also
gca, gcf, gco, rootobject
2-491
helpdlg
Purpose
2helpdlg
Create a help dialog box
Syntax
helpdlg
helpdlg('helpstring')
helpdlg('helpstring','dlgname')
h = helpdlg(...)
Description
helpdlg creates a help dialog box or brings the named help dialog box to the
front.
helpdlg displays a dialog box named 'Help Dialog' containing the string
'This is the default help string.'
helpdlg('helpstring') displays a dialog box named 'Help Dialog'
containing the string specified by 'helpstring'.
helpdlg('helpstring','dlgname') displays a dialog box named 'dlgname'
containing the string 'helpstring'.
h = helpdlg(...) returns the handle of the dialog box.
Remarks
MATLAB wraps the text in 'helpstring' to fit the width of the dialog box. The
dialog box remains on your screen until you press the OK button or the Return
key. After pressing the button, the help dialog box disappears.
Examples
The statement,
helpdlg('Choose 10 points from the figure','Point Selection');
displays this dialog box:
See Also
2-492
dialog, errordlg, questdlg, warndlg
inputdlg
Purpose
2inputdlg
Create input dialog box
Syntax
answer
answer
answer
answer
answer
Description
answer = inputdlg(prompt) creates a modal dialog box and returns user
inputs in the cell array. prompt is a cell array containing prompt strings.
=
=
=
=
=
inputdlg(prompt)
inputdlg(prompt,title)
inputdlg(prompt,title,lineNo)
inputdlg(prompt,title,lineNo,defAns)
inputdlg(prompt,title,lineNo,defAns,Resize)
answer = inputdlg(prompt,title) title specifies a title for the dialog box.
answer = inputdlg(prompt,title,lineNo) lineNo specifies the number of
lines for each user entered value. lineNo can be a scalar, column vector, or
matrix.
• If lineNo is a scalar, it applies to all prompts.
• If lineNo is a column vector, each element specifies the number of lines of
input for a prompt.
• If lineNo is a matrix, it should be size m-by-2, where m is the number of
prompts on the dialog box. Each row refers to a prompt. The first column
specifies the number of lines of input for a prompt. The second column
specifies the width of the field in characters.
answer = inputdlg(prompt,title,lineNo,defAns) defAns specifies the
default value to display for each prompt. defAns must contain the same
number of elements as prompt and all elements must be strings.
answer = inputdlg(prompt,title,lineNo,defAns,Resize) Resize specifies
whether or not the dialog box can be resized. Permissible values are 'on' and
'off' where 'on' means that the dialog box can be resized and that the dialog
box is not modal.
2-493
inputdlg
Example
Create a dialog box to input an integer and colormap name. Allow one line for
each value.
prompt
title
lines=
def
answer
See Also
2-494
= {'Enter matrix size:','Enter colormap name:'};
= 'Input for peaks function';
1;
= {'20','hsv'};
= inputdlg(prompt,title,lines,def);
textwrap, dialog, warndlg, helpdlg, questdlg, errordlg
listdlg
Purpose
2listdlg
Create list selection dialog box
Syntax
[Selection,ok] = listdlg('ListString',S,...)
Description
[Selection,ok] = listdlg('ListString',S) creates a modal dialog box
that enables you to select one or more values from a list. Selection is a vector
of indices of the selected strings (in single selection mode, its length is 1).
Selection is [] when ok is 0. ok is 1 if you push the OK button, or 0 if you push
the Cancel button or close the dialog box. Double-clicking on an item or
pressing Return when multiple items are selected has the same effect as
clicking the OK button. The dialog box has a Select all button (when in
multiple selection mode) that enables you to select all list items.
Inputs are in parameter/value pairs:
Parameter
Description
'ListString'
Cell array of strings that specify the list box items.
'SelectionMode'
String indicating whether one or many items can be
selected:'single' or 'multiple' (the default).
'ListSize'
List box size in pixels, specified as a two element
vector, [width height]. Default is [160 300].
'InitialValue'
Vector of indices of the list box items that are
initially selected. Default is 1, the first item.
'Name'
String for the dialog box’s title. Default is ''.
'PromptString'
String matrix or cell array of strings that appears
as text above the list box. Default is {}.
'OKString'
String for the OK button. Default is 'OK'.
'CancelString'
String for the Cancel button. Default is 'Cancel'.
'uh'
Uicontrol button height, in pixels. Default is 18.
'fus'
Frame/uicontrol spacing, in pixels. Default is 8.
'ffs'
Frame/figure spacing, in pixels. Default is 8.
2-495
listdlg
Example
This example displays a dialog box that enables the user to select a file from
the current directory. The function returns a vector. Its first element is the
index to the selected file; its second element is 0 if no selection is made, or 1 if
a selection is made.
d = dir;
str = {d.name};
[s,v] = listdlg('PromptString','Select a file:',...
'SelectionMode','single',...
'ListString',str)
See Also
2-496
dir
msgbox
Purpose
2msgbox
Display message box
Syntax
msgbox(message)
msgbox(message,title)
msgbox(message,title,'icon')
msgbox(message,title,'custom',iconData,iconCmap)
msgbox(...,'createMode');
h = msgbox(...)
Description
msgbox(message) creates a message box that automatically wraps message to
fit an appropriately sized Figure. message is a string vector, string matrix, or
cell array.
msgbox(message,title) specifies the title of the message box.
msgbox(message,title,'icon') specifies which icon to display in the
message box. 'icon’ is 'none', 'error', 'help', 'warn', or 'custom'. The
default is 'none'.
Error Icon
Help Icon
Warning Icon
msgbox(message,title,'custom',iconData,iconCmap) defines a customized
icon. iconData contains image data defining the icon; iconCmap is the colormap
used for the image.
msgbox(...,'createMode') specifies whether the message box is modal or
nonmodal, and if it is nonmodal, whether to replace another message box with
the same title. Valid values for 'createMode' are 'modal', 'non-modal', and
'replace'.
h = msgbox(...) returns the handle of the box in h, which is a handle to a
Figure graphics object.
See Also
dialog, errordlg, questdlg, inputdlg, helpdlg, textwrap, warndlg
2-497
pagedlg
Purpose
2pagedlg
Display page position dialog box
Syntax
pagedlg
pagedlg(fig)
Description
pagedlg displays a page position dialog box for the current figure. The dialog
box enables you to set page layout properties.
pagedlg(fig) displays a page position dialog box for the Figure identified by
the handle fig.
Remarks
This dialog box enables you to set Figure properties that determine how
MATLAB lays out the Figure on the printed paper. See the dialog box help for
more information.
See Also
The Figure properties – PaperPosition, PaperOrientation, PaperUnits
2-498
printdlg
Purpose
2printdlg
Display print dialog box
Syntax
printdlg
printdlg(fig)
printdlg('-crossplatform’,fig)
Description
printdlg prints the current Figure.
printdlg(fig) creates a dialog box from which you can print the Figure
window identified by the handle fig. Note that Uimenus do not print.
printdlg('-crossplatform’,fig) displays the standard cross-platform
MATLAB printing dialog rather than the built-in printing dialog box for
Microsoft Windows and Macintosh computers. Insert this option before the fig
argument.
2-499
questdlg
Purpose
2questdlg
Create and display question dialog box
Syntax
button = questdlg('qstring')
button = questdlg('qstring','title')
button = questdlg('qstring','title','default')
button = questdlg('qstring','title','str1','str2','default')
button =
questdlg('qstring','title','str1','str2','str3','default')
Description
button = questdlg('qstring') displays a modal dialog presenting the
question 'qstring'. The dialog has three default buttons—No, Cancel, and
Yes. 'qstring' is a cell array or a string that automatically wraps to fit within
the dialog box. button contains the name of the button pressed.
button = questdlg('qstring','title') displays a question dialog with
'title' displayed in the dialog’s title bar.
button = questdlg('qstring','title','default') specifies which push
button is the default in the event that the Return key is pressed. 'default'
must be 'Yes', 'No', or 'Cancel'.
button = questdlg('qstring','title','str1','str2','default')
creates a question dialog box with two push buttons labeled 'str1' and
'str2'. 'default' specifies the default button selection and must be 'str1' or
'str2'.
button =
questdlg('qstring','title','str1','str2','str3','default') creates
a question dialog box with three push buttons labeled 'str1', 'str2', and
'str3'. 'default' specifies the default button selection and must be 'str1',
'str2', or 'str3'.
2-500
questdlg
Example
Create a question dialog asking the user whether to continue a hypothetical
operation:
button = questdlg('Do you want to continue?',...
'Continue Operation','Yes','No','Help','No')
if strcmp(button,'Yes')
disp('Creating file')
elseif strcmp(button,'No')
disp('Canceled file operation')
elseif strcmp(button,'Help')
disp('Sorry, no help available')
end
See Also
dialog, errordlg, helpdlg, inputdlg, msgbox, warndlg
2-501
rbbox
Purpose
2rbbox
Create rubberband box for area selection
Synopsis
rbbox
rbbox(initialRect)
rbbox(initialRect,fixedPoint)
rbbox(initialRect,fixedPoint,stepSize)
finalRect = rbbox(...)
Description
rbbox initializes and tracks a rubberband box in the current Figure. It sets the
initial rectangular size of the box to 0, anchors the box at the Figure’s
CurrentPoint, and begins tracking from this point.
rbbox(initialRect) specifies the initial location and size of the rubberband
box as [x y width height], where x and y define the lower-left corner, and
width and height define the size. initialRect is in the units specified by the
current Figure’s Units property, and measured from the lower-left corner of
the Figure window. The corner of the box closest to the pointer position follows
the pointer until rbbox receives a button-up event.
rbbox(initialRect,fixedPoint) specifies the corner of the box that remains
fixed. All arguments are in the units specified by the current Figure’s Units
property, and measured from the lower-left corner of the Figure window.
fixedPoint is a two-element vector, [x y]. The tracking point is the corner
diametrically opposite the anchored corner defined by fixedPoint.
rbbox(initialRect,fixedPoint,stepSize) specifies how frequently the
rubberband box is updated. When the tracking point exceeds stepSize Figure
units, rbbox redraws the rubberband box. The default stepsize is 1.
finalRect = rbbox(...) returns a four-element vector, [x y width height],
where x and y are the x and y components of the lower-left corner of the box,
and width and height are the dimensions of the box.
Remarks
2-502
rbbox is useful for defining and resizing a rectangular region:
rbbox
• For box definition, initialRect is [x y 0 0], where (x,y) is the Figure’s
CurrentPoint.
• For box resizing, initialRect defines the rectangular region that you resize
(e.g., a legend). fixedPoint is the corner diametrically opposite the tracking
point.
rbbox returns immediately if a button is not currently pressed. Therefore, you
use rbbox with waitforbuttonpress so that the mouse button is down when
rbbox is called. rbbox returns when you release the mouse button.
Examples
Assuming the current view is view(2), use the current Axes’ CurrentPoint
property to determine the extent of the rectangle in dataspace units:
k = waitforbuttonpress;
point1 = get(gca,'CurrentPoint');
finalRect = rbbox;
point2 = get(gca,'CurrentPoint');
% button down detected
% return Figure units
% button up detected
point1 = point1(1,1:2);
point2 = point2(1,1:2);
% extract x and y
p1 = min(point1,point2);
offset = abs(point1-point2);
% calculate locations
% and dimensions
x = [p1(1) p1(1)+offset(1) p1(1)+offset(1) p1(1) p1(1)];
y = [p1(2) p1(2) p1(2)+offset(2) p1(2)+offset(2) p1(2)];
hold on
axis manual
plot(x,y)
See Also
% redraw in dataspace units
axis, dragrect, waitforbuttonpress
2-503
selectmoveresize
Purpose
2selectmoveresize
Select, move, resize, or copy Axes and Uicontrol graphics objects
Syntax
A = selectmoveresize;
set(h,'ButtonDownFcn','selectmoveresize')
Description
selectmoveresize is a function that you can use as the callback routine for
Axes and Uicontrol button down functions. When executed, it selects the object
and allows you to move, resize, and copy it.
For example, this statement sets the button down function of the current Axes
to selectmoveresize:
set(gca,'ButtonDownFcn','selectmoveresize')
A = selectmoveresize returns a structure array containing:
• A.Type: a sting containing the action type, which can be Select, Move,
Resize, or Copy
• A.Handles: a list of the selected handles or for a Copy an m-by-2 matrix
containing the original handles in the first column and the new handles in
the second column.
See Also
2-504
The ButtonDownFcn of Axes and Uicontrol graphics objects
textwrap
Purpose
2textwrap
Return wrapped string matrix for given Uicontrol
Syntax
outstring = textwrap(h,instring)
[outstring,position] = textwrap(h,instring)
Description
outstring = textwrap(h,instring) returns a wrapped string cell array,
outstring, that fits inside the Uicontrol with handle h. instring is a cell
array, with each cell containing a single line of text. outstring is the wrapped
string matrix in cell array format. Each cell of the input string is considered a
paragraph.
[outstring,position]=textwrap(h,instring) returns the recommended
position of the Uicontrol in the units of the Uicontrol. position considers the
extent of the multi-line text in the x and y directions.
Example
Place a textwrapped string in a Uicontrol:
pos = [10 10 100 10];
h = uicontrol('Style','Text','Position',pos);
string = {'This is a string for the uicontrol.',
'It should be correctly wrapped inside.'};
[outstring,newpos] = textwrap(h,string);
pos(4) = newpos(4);
set(h,'String',outstring,'Position',[pos(1),pos(2),pos(3)+10,pos(4)])
See Also
uicontrol
2-505
textwrap
2-506
uicontextmenu
Purpose
2uicontextmenu
Create a context menu
Syntax
handle = uicontextmenu('PropertyName',PropertyValue,...);
Description
uicontextmenu creates a context menu, which is a menu that is accessed when
the user right-clicks on the graphics object associated with the menu. On a
Macintosh, perform a right-click using a Ctrl-click.
You create context menu items using the uimenu function. Menu items appear
in the order the uimenu statements appear. You associate a context menu with
an object using the UIContextMenu property for the object and specifying the
context menu’s handle as the property value.
More information about context menus.
Properties
This table lists all uicontextmenu properties, grouping them by function. Each
property name acts as a link to a description of the property.
Property Name
Property Description
Property Value
Controlling Style and Appearance
Clipping
This property has no effect on
Uicontextmenu objects
SelectionHighlight
This property has no effect on
Uicontextmenu objects
Visible
Uicontextmenu visibility
Value: on, off
Default: on
General Information About the Object
Children
The Uimenus defined for the
Uicontextmenu
Value: matrix
Parent
Uicontextmenu object’s parent
Value: scalar Figure handle
Selected
This property has no effect on
Uicontextmenu objects
Tag
User-specified object identifier
Value: string
2-507
uicontextmenu
Property Name
Property Description
Property Value
Type
Class of graphics object
Value: string (read-only)
Default: uicontrol
UserData
User-specified data
Value: matrix
Controlling Callback Routine Execution
BusyAction
Callback routine interruption
ButtonDownFcn
This property has no effect on
Uicontextmenu objects
Callback
Control action
Value: string
CreateFcn
Callback routine executed during
object creation
Value: string
DeleteFcn
Callback routine executed during
object deletion
Value: string
Interruptible
Callback routine interruption mode
Value: on, off
Default: on
UIContextMenu
This property has no effect on
Uicontextmenu objects
Value: cancel, queue
Default: queue
Controlling Access to Objects
HandleVisibility
Whether handle is accessible from
command line and GUIs
HitTest
This property has no effect on
Uicontextmenu objects
2-508
Value: on, callback, off
Default: on
uicontextmenu
Example
These statements define a context menu associated with a line. When the user
extend-clicks anywhere on the line, the menu appears. Menu items enable the
user to change the line style.
% Define the context menu
cmenu = uicontextmenu;
% Define the line and associate it with the context menu
hline = plot(1:10, 'UIContextMenu', cmenu);
% Define callbacks for context menu items
cb1 = ['set(hline, ''LineStyle'', ''--'')'];
cb2 = ['set(hline, ''LineStyle'', '':'')'];
cb3 = ['set(hline, ''LineStyle'', ''-'')'];
% Define the context menu items
item1 = uimenu(cmenu, 'Label', 'dashed', 'Callback', cb1);
item2 = uimenu(cmenu, 'Label', 'dotted', 'Callback', cb2);
item3 = uimenu(cmenu, 'Label', 'solid', 'Callback', cb3);
When the user extend-clicks on the line, the context menu appears, as shown
in this figure:
2-509
uicontextmenu
Object
Hierarchy
Root
Figure
Axes
See Also
2-510
Uicontrol
uicontrol, uimenu
Uimenu
Uicontextmenu
Uimenu
Uimenu
uicontextmenu Properties
Uicontextmenu
Properties
2uicontextmenu Properties
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If a callback routine is executing, subsequently invoked callback
routines always attempt to interrupt it. If the Interruptible property of the
object whose callback is executing is set to on (the default), then interruption
occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property of the object whose
callback is executing determines how MATLAB handles the event. The choices
are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
This property has no effect on Uicontextmenu objects.
Callback
string
Control action. A routine that executes whenever you right-click on an object
for which a context menu is defined. The routine executes immediately before
the context menu is posted. Define this routine as a string that is a valid
MATLAB expression or the name of an M-file. The expression executes in the
MATLAB workspace.
Children
matrix
The Uimenus defined for the Uicontextmenu.
Clipping
{on} | off
This property has no effect on Uicontextmenu objects.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Uicontextmenu object.
You must define this property as a default value for Uicontextmenus. For
example, this statement:
set(0,'DefaultUicontextmenuCreateFcn',...
'set(gcf,''IntegerHandle'',''off'')')
2-511
uicontextmenu Properties
defines a default value on the Root level that sets the Figure IntegerHandle
property to off whenever you create a Uicontextmenu object. MATLAB
executes this routine after setting all property values for the Uicontextmenu.
Setting this property on an existing Uicontextmenu object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
DeleteFcn
string
Delete Uicontextmenu callback routine. A callback routine that executes when
you delete the Uicontextmenu object (e.g., when you issue a delete command
or clear the Figure containing the Uicontextmenu). MATLAB executes the
routine before destroying the object’s properties so these values are available
to the callback routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provides a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be returned
by functions that obtain handles by searching the object hierarchy or querying
handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf,
and close.
2-512
uicontextmenu Properties
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
This property has no effect on Uicontextmenu objects.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Uicontextmenu callback routine can be interrupted by subsequently
invoked callback routines. By default (off), a callback routine executes to
completion before another can begin.
Only callback routines defined for the ButtonDownFcn and Callback properties
are affected by the Interruptible property. MATLAB checks for events that
can interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine.
Parent
handle
Uicontextmenu’s parent. The handle of the Uicontextmenu’s parent object. The
parent of a Uicontextmenu object is the Figure in which it appears. You can
move a Uicontextmenu object to another Figure by setting this property to the
handle of the new parent.
Selected
on | {off}
This property has no effect on Uicontextmenu objects.
SelectionHighlight {on} | off
This property has no effect on Uicontextmenu objects.
2-513
uicontextmenu Properties
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string
Class of graphics object. For Uicontextmenu objects, Type is always the string
'uicontextmenu'.
UIContextMenu
handle
This property has no effect on Uicontextmenus.
UserData
matrix
User-specified data. Any data you want to associate with the Uicontextmenu
object. MATLAB does not use this data, but you can access it using set and get.
Visible
{on} | off
Uicontextmenu visibility. The Visible property determines or indicates
whether the context menu is posted. The property is normally controlled
automatically, returning on when the menu is posted as a result of a right-click
and off after a menu item has been selected and the context menu is
withdrawn. You can use the property to force the context menu to be posted
without a menu click or to be withdrawn before an item is selected.
2-514
uicontrol
Purpose
2uicontrol
Create user interface control object
Syntax
handle = uicontrol(parent)
handle = uicontrol(...,'PropertyName',PropertyValue,...)
Description
uicontrol creates Uicontrol graphics objects (user interface controls). You
implement graphical user interfaces using Uicontrols. When selected, most
Uicontrol objects perform a predefined action. MATLAB supports numerous
styles of Uicontrols, each suited for a different purpose:
• Check boxes
• Editable text
• Frames
• List boxes
• Pop-up menus
• Push buttons
• Radio buttons
• Sliders
• Static text
• Toggle buttons
Check boxes generate an action when pressed. These devices are useful when
providing the user with a number of independent choices. To activate a check
box, click the mouse button on the object. The state of the device is indicated on
the display.
Editable text boxes are fields that enable users to enter or modify text values.
Use editable text when you want text as input. To execute the callback routine
for an editable text object, type in the desired text, then press Ctl-Return (for
multiline), Return (for single line) or move the focus off the object.
On Microsoft Windows and Macintosh systems, if an editable text box has
focus, clicking on the menu bar does not cause the editable text callback routine
to execute. However, it does cause execution on UNIX systems. Therefore, after
clicking on the menu bar, the statement,
get(edit_handle,'String')
2-515
uicontrol
does not return the current contents of the edit box on Microsoft Windows and
Macintosh systems because MATLAB must execute the callback routine to
update the String property (even though the text string has changed on the
screen). This behavior is consistent with the respective platform conventions.
Frames are boxes that visually enclose regions of a figure window. Frames can
make a user interface easier to understand by visually grouping related
controls. Frames have no callback routines associated with them. Only
Uicontrols can appear within frames.
Frames are opaque, not transparent, so the order you define Uicontrols is
important in determining whether Uicontrols within a frame are covered by
the frame or are visible. Stacking order determines the order objects are drawn:
objects defined first are drawn first; objects defined later are drawn over
existing objects. If you use frames to enclose objects, you must define the
frames before you define the objects.
List boxes display a list of items and enable users to select one or more items.
The Min and Max properties control the selection mode. The Value property
indicates selected entries and contains the indices into the list of strings; a
vector value indicates multiple selections. MATLAB evaluates the list box’s
callback routine after any mouse button up event that changes the Value
property. Therefore, you may need to add a “Done” button to delay action
caused by multiple clicks on list items. List boxes differentiate between single
and double clicks and set the Figure SelectionType property to normal or open
accordingly before evaluating the list box’s Callback property.
Pop-up menus open when pressed to display a list of choices. When not
activated, they display a single button with text indicating the current setting.
Pop-up menus are useful when you want to provide users with a number of
mutually exclusive choices, but do not want to take up the amount of space that
a series of radio buttons requires. You must specify a value for the String
property.
Push buttons generate an action with each press, but do not remain in a pressed
state. To activate a push button, click the mouse button on the object. Push
buttons are useful when the action you want to perform is not related to any
other action executable by the user interface (for example, an “OK” button).
Radio buttons are similar to check boxes, but are intended to be mutually
exclusive within a group of related radio buttons (i.e., only one is in a pressed
2-516
uicontrol
state at any given time). To activate a radio button, click the mouse button on
the object. The state of the device is indicated on the display. Note that your
code can implement the mutually exclusive behavior of radio buttons.
Sliders accept numeric input within a specific range by enabling the user to
move a sliding bar. Users move the bar by pressing the mouse button and
dragging the pointer over the bar, or by clicking in the trough or on an arrow.
The location of the bar indicates a numeric value, which is selected by releasing
the mouse button. You can set the minimum, maximum, and current values of
the slider.
Static text boxes display lines of text. Static text is typically used to label other
controls, provide directions to the user, or indicate values associated with a
slider. Users cannot change static text interactively and there is no way to
invoke the callback routine associated with it.
Toggle buttons are controls that execute callbacks when clicked on and indicate
their state, either on or off. Toggle buttons are useful for building toolbars.
More information about toggle buttons.
Remarks
The uicontrol function accepts property name/property value pairs,
structures, and cell arrays as input arguments and optionally returns the
handle of the created object. You can also set and query property values after
creating the object using the set and get functions.
Uicontrol objects are children of Figures and therefore do not require an Axes
to exist when placed in a Figure window.
Properties
This table lists all uicontrol properties, grouping them by function. Each
property name acts as a link to a description of the property.
2-517
uicontrol
Property Name
Property Description
Property Value
Controlling Style and Appearance
BackgroundColor
Object background color
Value: ColorSpec
Default: [0.8 0.8 0.8]
CData
Truecolor image displayed on the
control
Value: matrix
Clipping
This property has no effect on
Uicontrol objects
ForegroundColor
Color of text
Value: ColorSpec
Default: [0 0 0]
SelectionHighlight
Object highlighted when selected
Value: on, off
Default: on
String
Uicontrol label
Value: string
Visible
Uicontrol visibility
Value: on, off
Default: on
General Information About the Object
Children
Uicontrol objects have no children
Enable
Enable or disable the Uicontrol
Value: on, inactive, off
Default: on
Parent
Uicontrol object’s parent
Value: scalar Figure handle
Selected
Whether object is selected
Value: on, off
Default: off
SliderStep
Slider step size
Value: two-element vector
Default: [0.01 0.1]
2-518
uicontrol
Property Name
Property Description
Property Value
Style
Type of Uicontrol object
Value: pushbutton,
togglebutton,
radiobutton, checkbox,
edit, text, slider, frame,
listbox, popupmenu
Default: pushbutton
Tag
User-specified object identifier
Value: string
TooltipString
Content of object’s tooltip
Value: string
Type
Class of graphics object
Value: string (read-only)
Default: uicontrol
UserData
User-specified data
Value: matrix
Controlling the Object Position
Position
Size and location of Uicontrol object
Value: position rectangle
Default: [20 20 60 20]
Units
Units to interpret position vector
Value: pixels, normalized,
inches, centimeters,
points, characters
Default: pixels
Character slant
Value: normal, italic,
Controlling Fonts and Labels
FontAngle
oblique
Default: normal
FontName
Font family
Value: string
Default: system dependent
FontSize
Font size
Value: size in FontUnits
Default: system dependent
2-519
uicontrol
Property Name
Property Description
Property Value
FontUnits
Font size units
Value: points, normalized,
inches, centimeters,
pixels
Default: points
FontWeight
Weight of text characters
Value: light, normal, demi,
bold
Default: normal
HorizontalAlignment
Alignment of label string
Value: left, center, right
Default: depends on
Uicontrol object
String
Uicontrol object label
Value: string
Controlling Callback Routine Execution
BusyAction
Callback routine interruption
Value: cancel, queue
Default: queue
ButtonDownFcn
Button press callback routine
Value: string
Callback
Control action
Value: string
CreateFcn
Callback routine executed during
object creation
Value: string
DeleteFcn
Callback routine executed during
object deletion
Value: string
Interruptible
Callback routine interruption mode
Value: on, off
Default: on
UIContextMenu
Uicontextmenu object associated
with the Uicontrol
Value: handle
Information About the Current State
ListboxTop
2-520
Index of top-most string displayed
in list box
Value: scalar
Default: [1]
uicontrol
Property Name
Property Description
Property Value
Max
Maximum value (depends on
Uicontrol object)
Value: scalar
Default: object dependent
Min
Minimum value (depends on
Uicontrol object)
Value: scalar
Default: object dependent
Value
Current value of Uicontrol object
Value: scalar or vector
Default: object dependent
Controlling Access to Objects
HandleVisibility
Whether handle is accessible from
command line and GUIs
Value: on, callback, off
Default: on
HitTest
Whether selectable by mouse click
Value: on, off
Default: on
Examples
The following statement creates a push button that clears the current axes
when pressed:
h = uicontrol('Style', 'pushbutton', 'String', 'Clear',...
'Position', [20 150 100 70], 'Callback', 'cla');
You can create a Uicontrol object that changes Figure colormaps by specifying
a pop-up menu and supplying an M-file name as the object’s Callback:
hpop = uicontrol('Style', 'popup',...
'String', 'hsv|hot|cool|gray',...
'Position', [20 320 100 50],...
'Callback', 'setmap');
The above call to uicontrol defines four individual choices in the menu: hsv,
hot, cool, and gray. You specify these choices with the String property,
separating the choices with the “|” character.
2-521
uicontrol
The Callback, in this case setmap, is the name of an M-file that defines a more
complicated set of instructions than a single MATLAB command. setmap
contains these statements:
val = get(hpop,'Value');
if val == 1
colormap(hsv)
elseif val == 2
colormap(hot)
elseif val == 3
colormap(cool)
elseif val == 4
colormap(gray)
end
The Value property contains a number that indicates the selected choice. The
choices are numbered sequentially from one to four. The setmap M-file can get
and then test the contents of the Value property to determine what action to
take.
Object
Hierarchy
Root
Figure
Axes
See Also
2-522
Uicontrol
textwrap, uimenu
Uimenu
Uicontextmenu
Uimenu
Uimenu
uicontrol Properties
Uicontrol
Properties
2uicontrol Properties
You can set default Uicontrol properties on the Figure and Root levels:
set(0,'DefaultUicontrolProperty',PropertyValue...)
set(gcf,'DefaultUicontrolProperty',PropertyValue...)
where Property is the name of the Uicontrol property whose default value you
want to set and PropertyValue is the value you are specifying. Use set and get
to access Uicontrol properties.
Curly braces { } enclose the default value.
BackgroundColor
ColorSpec
Object background color. The color used to fill the rectangle defined by the
Uicontrol. Specify a color using a three-element RGB vector or one of
MATLAB’s predefined names. The default color is light gray. See ColorSpec for
more information on specifying color.
On Microsoft Windows systems, you cannot specify the background color of
push buttons because of Windows limitations.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If a callback routine is executing, subsequently invoked callback
routines always attempt to interrupt it. If the Interruptible property of the
object whose callback is executing is set to on (the default), then interruption
occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property of the object whose
callback is executing determines how MATLAB handles the event. The choices
are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is in a five-pixel wide border around the
Uicontrol. When the Uicontrol’s Enable property is set to inactive or off, the
ButtonDownFcn executes when you click the mouse in the five-pixel border or
2-523
uicontrol Properties
on the control itself. This is useful for implementing actions to interactively
modify control object properties, such as size and position, when they are
clicked on (using selectmoveresize, for example).
Define this routine as a string that is a valid MATLAB expression or the name
of an M-file. The expression executes in the MATLAB workspace.
The Callback property defines the callback routine that executes when you
activate the enabled Uicontrol (e.g., click on a push button).
Callback
string
Control action. A routine that executes whenever you activate the Uicontrol
object (e.g., when you click on a push button or move a slider). Define this
routine as a string that is a valid MATLAB expression or the name of an M-file.
The expression executes in the MATLAB workspace. Note that callback
routines defined for frames and static text do not execute because no action is
associated with these objects.
CData
matrix
Truecolor image displayed on control. A three-dimensional matrix of RGB
values that defines a truecolor image displayed on either a push button or
toggle button. Each value must be between 0.0 and 1.0. More information about
this property.
Children
matrix
The empty matrix; Uicontrol objects have no children.
Clipping
{on} | off
This property has no effect on Uicontrols.
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Uicontrol object. You
must define this property as a default value for Uicontrols. For example, this
statement:
set(0,'DefaultUicontrolCreateFcn',...
'set(gcf,''IntegerHandle'',''off'')')
defines a default value on the Root level that sets the Figure IntegerHandle
property to off whenever you create a Uicontrol object. MATLAB executes this
2-524
uicontrol Properties
routine after setting all property values for the Uicontrol. Setting this property
on an existing Uicontrol object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
DeleteFcn
string
Delete Uicontrol callback routine. A callback routine that executes when you
delete the Uicontrol object (e.g., when you issue a delete command or clear the
Figure containing the Uicontrol). MATLAB executes the routine before
destroying the object’s properties so these values are available to the callback
routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which you can query using gcbo.
Enable
{on} | inactive | off
Enable or disable the Uicontrol. This property controls how Uicontrols respond
to mouse button clicks.
• on – The Uicontrol is operational. When you activate the Uicontrol (generally
by clicking on it) MATLAB executes the callback routine defined by the
Callback property. When you click the mouse within a 5-pixel border outside
the Uicontrol, MATLAB executes the callback routine defined by the
ButtonDownFcn.
• inactive – The Uicontrol is not operational, but it is not dimmed (i.e., it
looks the same as when Enable is on). MATLAB executes the ButtonDownFcn
if you click the mouse on or within a 5-pixel border around the Uicontrol, but
does not execute the Callback routine.
• off – The Uicontrol does not respond visually to mouse actions, does not
execute its Callback routine, and its label (string property) is grayed out.
MATLAB executes the ButtonDownFcn if you click the mouse on or within a
5-pixel border around the Uicontrol.
Setting this property to inactive or off enables you to implement object
“dragging” via the ButtonDownFcn callback routine.
2-525
uicontrol Properties
Extent
position rectangle (read only)
Size of Uicontrol character string. A four-element vector that defines the size
and position of the character string used to label the Uicontrol. It has the form:
[0,0,width,height]
The first two elements are always zero. width and height are the dimensions
of the rectangle. All measurements are in units specified by the Units property.
Since the Extent property is defined in the same units as the Uicontrol itself,
you can use this property to determine proper sizing for the Uicontrol with
regard to its label. Do this by
• Defining the String property and selecting the font using the relevant
properties.
• Getting the value of the Extent property.
• Defining the width and height of the Position property to be somewhat
larger than the width and height of the Extent.
For multiline strings, the Extent rectangle encompasses all the lines of text.
For single line strings, the Extent is returned as a single line, even if the string
wraps when displayed on the control.
FontAngle
{normal} | italic | oblique
Character slant. MATLAB uses this property to select a font from those
available on your particular system. Setting this property to italic or oblique
selects a slanted version of the font, when it is available on your system.
FontName
string
Font family. The name of the font in which to display the String. To display
and print properly, this must be a font that your system supports. The default
font is system dependent.
FontSize
size in FontUnits
Font size. A number specifying the size of the font in which to display the
String, in units determined by the FontUnits property. The default point size
is system dependent.
2-526
uicontrol Properties
FontUnits
{points} | normalized | inches |
centimeters | pixels
Font size units. MATLAB uses this property to determine the units used by the
FontSize property. Normalized units interpret FontSize as a fraction of the
height of the Uicontrol. When you resize the Uicontrol, MATLAB modifies the
screen FontSize accordingly. pixels, inches, centimeters, and points are
absolute units (1 point = 1/72 inch).
FontWeight
light | {normal} | demi | bold
Weight of Text characters. MATLAB uses this property to select a font from
those available on your particular system. Setting this property to bold causes
MATLAB to use a bold version of the font, when it is available on your system.
ForegroundColor
ColorSpec
Color of text. This property determines the color of the text defined for the
String property (the Uicontrol label). Specify a color using a three-element
RGB vector or one of MATLAB ’s predefined names. The default text color is
black. See ColorSpec for more information on specifying color.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provides a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
2-527
uicontrol Properties
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. This property has no effect on Uicontrol objects.
HorizontalAlignment
left | {center} | right
Horizontal alignment of label string. This property determines the justification
of the text defined for the String property (the Uicontrol label):
• left — Text is left justified with respect to the Uicontrol.
• center — Text is centered with respect to the Uicontrol.
• right — Text is right justified with respect to the Uicontrol.
On Microsoft Windows and Macintosh systems, this property affects only edit
and text Uicontrols.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Uicontrol callback routine can be interrupted by subsequently
invoked callback routines. By default (off), a callback routine executes to
completion before another can begin.
Only callback routines defined for the ButtonDownFcn and Callback properties
are affected by the Interruptible property. MATLAB checks for events that
can interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine.
2-528
uicontrol Properties
ListboxTop
scalar
Index of top-most string displayed in list box. This property applies only to the
listbox style of Uicontrol. It specifies which string appears in the top-most
position in a list box that is not large enough to display all list entries.
ListboxTop is an index into the array of strings defined by the String property
and must have a value between 1 and the number of strings. Noninteger values
are fixed to the next lowest integer.
Max
scalar
Maximum value. This property specifies the largest value allowed for the Value
property. Different styles of Uicontrols interpret Max differently:
• Check boxes – Max is the setting of the Value property while the Uicontrol is
in the on position.
• Editable text – If Max − Min > 1, then editable text boxes accept multiline
input. If Max − Min <= 1, then editable text boxes accept only single line input.
• List boxes – If Max − Min > 1, then list boxes allow multiple item selection. If
Max − Min <= 1, then list boxes do not allow multiple item selection.
• Radio buttons – Max is the setting of the Value property while the Uicontrol
is in the on position.
• Sliders – Max is the largest value you can select and must be greater than the
Min property. The default maximum is 1.
• Toggle buttons – Max is the value of the Value property when the toggle
button is selected. The default is 1.
• Frames, pop-up menus, and static text do not use the Max property.
Min
scalar
Minimum value. This property specifies the smallest value allowed for the
Value property. Different styles of Uicontrols interpret Min differently:
• Check boxes – Min is the setting of the Value property while the Uicontrol is
in the off position.
• Editable text – If Max − Min > 1, then editable text boxes accept multiline
input. If Max − Min <= 1, then editable text boxes accept only single line input.
• List boxes – If Max − Min > 1, then list boxes allow multiple item selection. If
Max − Min <= 1, then list boxes allow only single item selection.
2-529
uicontrol Properties
• Radio buttons – Min is the setting of the Value property while the Uicontrol
is in the off position.
• Sliders – Min is the smallest value you can select and must be less than Max.
The default minimum is 0.
• Toggle buttons – Min is the value of the Value property when the toggle
button is not selected. The default is 0.
Parent
handle
Uicontrol’s parent. The handle of the Uicontrol’s parent object. The parent of a
Uicontrol object is the Figure in which it appears. You can move a Uicontrol
object to another Figure by setting this property to the handle of the new
parent.
Position
position rectangle
Size and location of Uicontrol. The rectangle defined by this property specifies
the size and location of the control within the Figure window. Specify Position
as
[left,bottom,width,height]
left and bottom are the distance from the lower-left corner of the Figure
window to the lower-left corner of the Uicontrol object. width and height are
the dimensions of the Uicontrol rectangle. All measurements are in units
specified by the Units property.
On Microsoft Windows systems, the height of pop-up menus is automatically
determined by the size of the font. The value you specify for the height of the
Postion property has no effect.
Selected
on | {off}
Is object selected. When this property is on, MATLAB displays selection
handles if the SelectionHighlight property is also on. You can, for example,
define the ButtonDownFcn to set this property, allowing users to select the
object with the mouse.
SelectionHighlight {on} | off
Object highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing four edge handles and four corner
handles. When SelectionHighlight is off, MATLAB does not draw the
handles.
2-530
uicontrol Properties
SliderStep
[min_step max_step]
Slider step size. This property controls the amount the slider Value changes
when you click the mouse on the arrow button (min_step) or on the slider
trough (max_step). Specify SliderStep as a two-element vector; each value
must be in the range [0, 1]. The actual step size is a function of the specified
SliderStep and the total slider range (Max − Min). The default, [0.01 0.10],
provides a 1 percent change for clicks on the arrow button and a 10 percent
change for clicks in the trough.
For example, if you create the following slider,
uicontrol('Style','slider','Min',1,'Max',7,...
'SliderStep',[0.1 0.6])
clicking on the arrow button moves the indicator by,
0.1*(7–1)
ans =
0.6000
and clicking in the trough moves the indicator by,
0.6*(7–1)
ans =
3.6000
Note that if the specified step size moves the slider to a value outside the range,
the indicator moves only to the Max or Min value.
See also the Max, Min, and Value properties.
String
string
Uicontrol label. A string specifying the text displayed on check boxes, editable
text, list boxes, pop-up menus, push buttons, radio buttons, static text, and
toggle buttons.
For multiple items on a pop-up menu or a list box, items can be specified as a
cell array of strings, a padded string matrix, or within a string vector separated
by vertical slash (‘|’) characters.
For multiple line editable text or static text controls, line breaks occur between
each row of the string matrix, each cell of a cell array of strings, and after any
\n characters embedded in the string. Vertical slash (‘|’) characters are not
2-531
uicontrol Properties
interpreted as linebreaks, and instead show up in the text displayed in the
uicontrol.
For the remaining Uicontrol objects, which display only one line of text, only
the first string of a cell array of strings or of a padded string matrix is
displayed; the rest are ignored. Vertical slash (‘|’) characters are not
interpreted as linebreaks and instead show up in the text displayed in the
Uicontrol.
For editable text, this property is set to the string typed in by the user.
Style
{pushbutton} | togglebutton | radiobutton |
checkbox | edit | text | slider | frame |
listbox | popupmenu
Style of Uicontrol object to create. The Style property specifies the kind of
Uicontrol to create. See the “Description” section for information on each type.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
TooltipString
string
Content of tooltip for object. The TooltipString property specifies the text of
the tooltip associated with the Uicontrol. When the user moves the mouse
pointer over the control and leaves it there, the tooltip is displayed. More
information about this property.
Type
string (read only)
Class of graphics object. For Uicontrol objects, Type is always the string
'uicontrol'.
UIContextMenu
handle
Associate a context menu with Uicontrol. Assign this property the handle of a
Uicontextmenu object. MATLAB displays the context menu whenever you
right-click over the Uicontrol (Ctrl-click on Macintosh systems). Use the
uicontextmenu function to create the context menu. More information about
this property.
2-532
uicontrol Properties
Units
{pixels} | normalized | inches |
centimeters | points | characters
Units of measurement. The units MATLAB uses to interpret the Extent and
Position properties. All units are measured from the lower-left corner of the
Figure window. Normalized units map the lower-left corner of the Figure
window to (0,0) and the upper-right corner to (1.0,1.0). pixels, inches,
centimeters, and points are absolute units (1 point = 1/72 inch). Character
units are characters using the default system font; the width of one character
is the width of the letter x, the height of one character is the distance between
the baselines of two lines of text. More information about character units.
If you change the value of Units, it is good practice to return it to its default
value after completing your computation so as not to affect other functions that
assume Units is set to the default value.
UserData
matrix
User-specified data. Any data you want to associate with the Uicontrol object.
MATLAB does not use this data, but you can access it using set and get.
Value
scalar or vector
Current value of Uicontrol. The Uicontrol style determines the possible values
this property can have:
• Check boxes set Value to Max when they are on (when the indicator is filled)
and Min when off (not filled).
• List boxes set Value to a vector of indices corresponding to the selected list
entries, where 1 corresponds to the first item in the list.
• Pop-up menus set Value to the index of the item selected, where 1
corresponds to the first item on the menu. The “Examples” section shows
how to use the Value property to determine which item has been selected.
• Radio buttons set Value to Max when they are on (when the indicator is filled)
and Min when off (not filled).
• Sliders set Value to the number indicated by the slider bar, which is within
the range established by Min and Max.
• Toggle buttons set Value to Max when they are down (selected) and Min when
up (not selected).
• Editable text, frames, push buttons, and static text do not set this property.
2-533
uicontrol Properties
Set the Value property either interactively with the mouse or through a call to
the set function. The display reflects changes made to Value.
Visible
{on} | off
Uicontrol visibility. By default, all Uicontrols are visible. When set to off, the
Uicontrol is not visible, but still exists and you can query and set its properties.
2-534
uigetfile
Purpose
2uigetfile
Interactively retrieve a filename
Syntax
uigetfile
uigetfile('FilterSpec')
uigetfile('FilterSpec','DialogTitle')
uigetfile('FilterSpec','DialogTitle',x,y)
[fname,pname] = uigetfile(...)
Description
uigetfile displays a dialog box used to retrieve a file. The dialog box lists the
files and directories in the current directory.
uigetfile('FilterSpec') displays a dialog box that lists files in the current
directory. FilterSpec determines the initial display of files and can be a full
filename or include the * wildcard. For example, '∗.m' (the default) causes the
dialog box list to show only MATLAB M-files. The Macintosh ignores this
argument.
uigetfile('FilterSpec','DialogTitle') displays a dialog box that has the
title DialogTitle. On the Macintosh, this argument specifies text that appears
above the current folder name.
uigetfile('FilterSpec','DialogTitle',x,y) positions the dialog box at
position [x,y], where x and y are the the distance in pixel units from the left and
top edges of the screen. Note that some platforms may not support dialog box
placement. On the Macintosh, the dialog box cannot overlap the menu bar.
[fname,pname] = uigetfile(...) returns the name and path of the file
selected in the dialog box. After you press the Done button, fname contains the
name of the file selected and pname contains the name of the path selected. If
you press the Cancel button or if an error occurs, fname and pname are set to 0.
Remarks
If you select a file that does not exist, an error dialog appears. You can then
enter another filename, or press the Cancel button.
Examples
This statement displays a dialog box that enables you to retrieve a file. The
statement lists all MATLAB M-files within a selected directory. The figure
2-535
uigetfile
shows the dialog box on a Macintosh. The name and path of the selected file are
returned in fname and pname.
[fname,pname] = uigetfile('*.m','Sample Dialog Box')
The exact appearance of the dialog box depends on your windowing system.
See Also
2-536
uiputfile
uimenu
Purpose
2uimenu
Create menus on Figure windows
Syntax
uimenu('PropertyName',PropertyValue,...)
uimenu(parent,'PropertyName',PropertyValue,...)
handle = uimenu('PropertyName',PropertyValue,...)
handle = uimenu(parent,'PropertyName',PropertyValue,...)
Description
uimenu creates a hierarchy of menus and submenus that are displayed in the
Figure window’s menu bar. You can also use uimenu to create menu items for
context menus. More information about context menus.
handle = uimenu('PropertyName',PropertyValue,...) creates a menu in
the current Figure’s menu bar using the values of the specified properties and
assigns the menu handle to handle.
handle = uimenu(parent,'PropertyName',PropertyValue,...) creates a
submenu of a parent menu or a menu item on a context menu specified by
parent and assigns the menu handle to handle. If parent refers to a Figure
instead of another Uimenu object or a Uicontextmenu, MATLAB creates a new
menu on the referenced Figure’s menu bar.
Remarks
MATLAB adds the new menu to the existing menu bar. Each menu choice can
itself be a menu that displays its submenu when selected.
uimenu accepts property name/property value pairs, as well as structures and
cell arrays of properties as input arguments. The Uimenu Callback property
defines the action taken when you activate the menu item. uimenu optionally
returns the handle to the created Uimenu object.
Uimenus only appear in Figures whose WindowStyle is normal. If a Figure
containing Uimenu children is changed to WindowStyle modal, the Uimenu
children still exist and are contained in the Children list of the Figure, but are
not displayed until the WindowStyle is changed to normal.
The value of the Figure MenuBar property affects the location of the Uimenu on
the Figure menu bar. When MenuBar is figure, a set of built-in menus precedes
the Uimenus on the menu bar (MATLAB controls the built-in menus and their
handles are not available to the user). When MenuBar is none, Uimenus are the
only items on the menu bar (that is, the built-in menus do not appear).
2-537
uimenu
You can set and query property values after creating the menu using set and
get.
Properties
This table lists all uimenu properties, grouping them by function. Each
property name acts as a link to a description of the property.
Property Name
Property Description
Property Value
Controlling Style and Appearance
Checked
Menu check indicator
Clipping
This property has no effect on
Uimenu objects
ForegroundColor
Color of text
Value: ColorSpec
Default: [0 0 0]
Label
Menu label
Value: string
SelectionHighlight
Object highlighted when selected
Value: on, off
Default: on
Separator
Separator line mode
Value: on, off
Default: off
Visible
Uimenu visibility
Value: on, off
Default: on
Value: on, off
Default: off
General Information About the Object
Accelerator
Keyboard equivalent
Value: character
Children
Handles of submenus
Value: vector of handles
Enable
Enable or disable the Uimenu
Value: on, off
Default: on
Parent
Uimenu object’s parent
Value: handle
Selected
This property has no effect on
Uimenu objects
2-538
uimenu
Property Name
Property Description
Property Value
Tag
User-specified object identifier
Value: string
Type
Class of graphics object
Value: string (read-only)
Default: uimenu
UserData
User-specified data
Value: matrix
Controlling the Object Position
Position
Relative Uimenu position
Value: scalar
Default: [1]
Controlling Callback Routine Execution
BusyAction
Callback routine interruption
Value: cancel, queue
Default: queue
ButtonDownFcn
Button press callback routine
Value: string
Callback
Control action
Value: string
CreateFcn
Callback routine executed during
object creation
Value: string
DeleteFcn
Callback routine executed during
object deletion
Value: string
Interruptible
Callback routine interruption mode
Value: on, off
Default: on
UIContextMenu
This property has no effect on
Uimenu objects
Controlling Access to Objects
HandleVisibility
Whether handle is accessible from
command line and GUIs
Value: on, callback, off
Default: on
HitTest
Whether selectable by mouse click
Value: on, off
Default: on
2-539
uimenu
Examples
This example creates a menu labeled Workspace whose choices allow users to
create a new Figure window, save workspace variables, and exit out of
MATLAB. In addition, it defines an accelerator key for the Quit option (which
would not work on a Macintosh because Command-Q is reserved).
f = uimenu('Label','Workspace');
uimenu(f,'Label','New Figure','Callback','figure');
uimenu(f,'Label','Save','Callback','save');
uimenu(f,'Label','Quit','Callback','exit',...
'Separator','on','Accelerator','Q');
Object
Hierarchy
Root
Figure
Axes
See Also
2-540
Uicontrol
Uimenu
Uicontextmenu
Uimenu
Uimenu
uicontrol, uicontextmenu, gcbo, set, get, figure
uimenu Properties
Uimenu
Properties
2uimenu Properties
This section lists property names along with the type of values each accepts.
Curly braces { } enclose default values.
You can set default Uimenu properties on the Figure and Root levels:
set(0,'DefaultUimenuPropertyName',PropertyValue...)
set(gcf,'DefaultUimenuPropertyName',PropertyValue...)
set(menu_handle,'DefaultUimenuProperty',PropertyValue...)
Where PropertyName is the name of the Uimenu property and PropertyValue
is the value you are specifying. Use set and get to access Uimenu properties.
Accelerator
character
Keyboard equivalent. A character specifying the keyboard equivalent for the
menu item. This allows users to select a particular menu choice by pressing the
specified character in conjunction with another key, instead of selecting the
menu item with the mouse. The key sequence is platform specific:
• For Microsoft Windows systems, the sequence is Ctrl-Accelerator. These
keys are reserved for default menu items: c, v, and x.
• For UNIX systems, the sequence is Ctrl-Accelerator. These keys are
reserved for default menu items: o, p, s, and w.
• For Macintosh systems, the sequence is Command-Accelerator. These
keys are reserved for default menu items: a, c, n, o, p, q, s, v, w, x, z, and the
number keys.
You can define an accelerator only for menu items that do not have children
menus. Accelerators work only for menu items that directly execute a callback
routine, not items that bring up other menus.
Note that the menu item does not have to be displayed (e.g., a submenu) for the
accelerator key to work. However, the window focus must be in the Figure
when the key sequence is entered.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routes always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
2-541
uimenu Properties
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string
The button down function has no effect on Uimenu objects.
Callback
string
Menu action. A callback routine that executes whenever you select the menu.
Define this routine as a string that is a valid MATLAB expression or the name
of an M-file. The expression executes in the MATLAB workspace.
A menu with children (submenus) executes its callback routine before
displaying the submenus. A menu without children executes its callback
routine when you release the mouse button (i.e., on the button up event).
Checked
on | {off}
Menu check indicator. Setting this property to on places a check mark next to
the corresponding menu item. Setting it to off removes the check mark. You
can use this feature to create menus that indicate the state of a particular
option. Note that there is no formal mechanism for indicating that an
unchecked menu item will become checked when selected. Also, this property
does not check top level menus or submenus, although you can change the
value of the property for these menus.
Children
vector of handles
Handles of submenus. A vector containing the handles of all children of the
Uimenu object. The children objects of Uimenus are other Uimenus, which
function as submenus. You can use this property to re-order the menus.
Clipping
{on} | off
Clipping has no effect on Uimenu objects.
2-542
uimenu Properties
CreateFcn
string
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates a Uimenu object. You
must define this property as a default value for Uimenus. For example, the
statement,
set(0,'DefaultUimenuCreateFcn','set(gcf,''IntegerHandle'',''off''’))
defines a default value on the Root level that sets the Figure IntegerHandle
property to off whenever you create a Uimenu object. Setting this property on
an existing Uimenu object has no effect. MATLAB executes this routine after
setting all property values for the Uimenu.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
DeleteFcn
string
Delete Uimenu callback routine. A callback routine that executes when you
delete the Uimenu object (e.g., when you issue a delete command or cause the
Figure containing the Uimenu to reset). MATLAB executes the routine before
destroying the object’s properties so these values are available to the callback
routine.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which is more simply queried
using gcbo.
Enable
{on} | off
Enable or disable the Uimenu. This property controls the selectability of a
menu item. When not enabled (set to off), the menu Label appears dimmed,
indicating the user cannot select it.
ForegroundColor
ColorSpec X-Windows only
Color of menu label string. This property determines color of the text defined
for the Label property. Specify a color using a three-element RGB vector or one
of MATLAB’s predefined names. The default text color is black. See ColorSpec
for more information on specifying color.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
2-543
uimenu Properties
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a Figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provide a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaling a user-typed string), and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, Figures do not
appear in the Root’s CurrentFigure property, objects do not appear in the
Root’s CallbackObject property or in the Figure’s CurrentObject property,
and Axes do not appear in their parent’s CurrentAxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether a Uimenu callback routine can be interrupted by subsequently
invoked callback routines. By default (off), a callback routine executes to
completion before another can begin. Only the Callback Uimenu property is
affected by the Interruptible property.
2-544
uimenu Properties
Label
string
Menu label. A string specifying the text label on the menu item. You can specify
a mnemonic using the “&” character. Whatever character follows the “&” in the
string appears underlined and selects the menu item when you type that
character while the menu is visible. The “&” character is not displayed. On
Macintosh systems, MATLAB ignores (and does not print) the “&” character.
To display the “&” character in a label, use two “&” characters in the string:
‘O&pen selection’ yields Open selection
‘Save && Go’ yields Save & Go
Parent
handle
Uimenu’s parent. The handle of the Uimenu’s parent object. The parent of a
Uimenu object is the Figure on whose menu bar it displays, or the Uimenu of
which it is a submenu. You can move a Uimenu object to another Figure by
setting this property to the handle of the new parent.
Position
scalar
Relative menu position. The value of Position indicates placement on the
menu bar or within a menu. Top-level menus are placed from left to right on
the menu bar according to the value of their Position property, with 1
representing the left-most position. The individual items within a given menu
are placed from top to bottom according to the value of their Position property,
with 1 representing the top-most position.
Selected
on | {off}
This property is not used for Uimenu objects.
SelectionHighlight
on | off
This property is not used for Uimenu objects.
Separator
on | {off}
Separator line mode. Setting this property to on draws a dividing line above the
menu item.
Tag
string
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
2-545
uimenu Properties
define object handles as global variables or pass them as arguments between
callback routines. You can define Tag as any string.
Type
string (read only)
Class of graphics object. For Uimenu objects, Type is always the string
'uimenu'.
UserData
matrix
User-specified data. Any matrix you want to associate with the Uimenu object.
MATLAB does not use this data, but you can access it using the set and get
commands.
Visible
{on} | off
Uimenu visibility. By default, all Uimenus are visible. When set to off, the
Uimenu is not visible, but still exists and you can query and set its properties.
2-546
uiputfile
Purpose
2uiputfile
Interactively select a file for writing
Syntax
uiputfile
uiputfile('InitFile')
uiputfile('InitFile','DialogTitle')
uiputfile('InitFile','DialogTitle',x,y)
[fname,pname] = uiputfile(...)
Description
uiputfile displays a dialog box used to select a file for writing. The dialog box
lists the files and directories in the current directory.
uiputfile('InitFile') displays a dialog box that contains a list of files in
the current directory determined by InitFile. InitFile is a full filename or
includes the * wildcard. For example, specifying '∗.m' (the default) causes the
dialog box list to show only MATLAB M-files. The Macintosh ignores the first
argument.
uiputfile('InitFile','DialogTitle') displays a dialog box that has the
title DialogTitle. On the Macintosh, the second argument is the label for the
filename prompt. See the example below.
uiputfile('InitFile','DialogTitle',x,y) positions the dialog box at
screen position [x,y], where x and y are the distance in pixel units from the left
and top edges of the screen. Note that positioning may not work on all
platforms. On the Macintosh, the dialog box cannot overlap the menu bar.
[fname,pname] = uiputfile(...) returns the name and path of the file
selected in the dialog box. If you press the Cancel button or an error occurs,
fname and pname are set to 0.
Remarks
If you select a file that already exists, a prompt asks whether you want to
overwrite the file. If you choose to, the function successfully returns but does
not delete the existing file (which is the responsibility of the calling routines).
If you select Cancel in response to the prompt, the function returns control back
to the dialog box so you can enter another filename.
Examples
This statement displays a dialog box titled 'Save file name' (the exact
appearance of the dialog box depends on your windowing system) with the
2-547
uiputfile
filename animinit.m. On the Macintosh, the second argument specifies the
filename prompt.
[newfile,newpath] = uiputfile('animinit.m','Save file name');
Microsoft
Windows
Macintosh
See Also
2-548
uigetfile
uiresume, uiwait
Purpose
2uiresume, uiwait
Control program execution
Syntax
uiwait(h)
uiwait
uiresume(h)
Description
The uiwait and uiresume functions block and resume MATLAB program
execution.
uiwait blocks execution until uiresume is called or the current Figure is
deleted. This syntax is the same as uiwait(gcf).
uiwait(h) blocks execution until uiresume is called or the Figure h is deleted.
uiresume(h) resumes the M-file execution that uiwait suspended.
Remarks
When creating a dialog, you should have a Uicontrol with a callback that calls
uiresume or a callback that destroys the dialog box. These are the only methods
that resume program execution after the uiwait function blocks execution.
uiwait is a convenient way to use the waitfor command. You typically use it
in conjunction with a dialog box. It provides a way to block the execution of the
M-file that created the dialog, until the user responds to the dialog box. When
used in conjunction with a modal dialog, uiwait/uiresume can block the
execution of the M-file and restrict user interaction to the dialog only.
See Also
uicontrol, uimenu, waitfor, figure, dialog
2-549
uisetcolor
Purpose
2uisetcolor
Set an object’s ColorSpec from a dialog box interactively
Syntax
c = uisetcolor(h_or_c, 'DialogTitle');
Description
uisetcolor displays a dialog box for the user to fill in, then applies the selected
color to the appropriate property of the graphics object identified by the first
argument.
h_or_c can be either a handle to a graphics object or an RGB triple. If you
specify a handle, it must specify a graphics object that have a Color property.
If you specify a color, it must be a valid RGB triple (e.g., [1 0 0] for red). The
color specified is used to initialize the dialog box. If no initial RGB is specified,
the dialog box initializes the color to black.
DialogTitle is a string that is used as the title of the dialog box.
c is the RGB value selected by the user. If the user presses Cancel from the
dialog box, or if any error occurs, c is set to the input RGB triple, if provided;
otherwise, it is set to 0.
See Also
2-550
ColorSpec
uisetfont
Purpose
2uisetfont
Modify font characteristics for objects interactively
Syntax
uisetfont
uisetfont(h)
uisetfont(S)
uisetfont(h,'DialogTitle')
uisetfont(S,'DialogTitle')
S = uisetfont(...)
Description
uisetfont enables you to change font properties (FontName, FontUnits,
FontSize, FontWeight, and FontAngle) for a Text, Axes, or Uicontrol object.
The function returns a structure consisting of font properties and values. You
can specify an alternate title for the dialog box.
uisetfont displays the dialog box and returns the selected font properties.
uisetfont(h) displays a dialog box, initializing the font property values with
the values of those properties for the object whose handle is h. Selected font
property values are applied to the current object. If a second argument is
supplied, it specifies a name for the dialog box (ignored on the Macintosh).
uisetfont(S) displays a dialog box, initializing the font property values with
the values defined for the specified structure (S). S must define legal values for
one or more of these properties: FontName, FontUnits, FontSize, FontWeight,
and FontAngle and the field names must match the property names exactly. If
other properties are defined, they are ignored. If a second argument is
supplied, it specifies a name for the dialog box (ignored on the Macintosh).
uisetfont('DialogTitle') displays a dialog box with the title DialogTitle
and returns the values of the font properties selected in the dialog box. The
Macintosh ignores this argument.
If a left-hand argument is specified, the properties FontName, FontUnits,
FontSize, FontWeight, and FontAngle are returned as fields in a structure. If
the user presses Cancel from the dialog box or if an error occurs, the output
value is set to 0.
2-551
uisetfont
Example
These statements create a Text object, then display a dialog box (labeled
Update Font) that enables you to change the font characteristics:
h = text(.5,.5,'Figure Annotation');
uisetfont(h,'Update Font')
These statements create two Uicontrol objects, then set the font properties of
one based on the values set for the other:
% Create push button with string ABC
c1 = uicontrol('Style', 'pushbutton', ...
'Position', [10 10 100 20], 'String', 'ABC');
% Create push button with string XYZ
c2 = uicontrol('Style', 'pushbutton', ...
'Position', [10 50 100 20], 'String', 'XYZ');
% Display set font dialog box for c1, make selections, save to d
d = uisetfont(c1)
% Apply those settings to c2
set(c2, d)
See Also
2-552
axes, text, uicontrol
waitbar
Purpose
2waitbar
Display waitbar
Syntax
h = waitbar(x,'title')
Description
A waitbar shows what percentage of a calculation is complete, as the
calculation proceeds.
h = waitbar(x,'title') creates and displays a waitbar of fractional length
x. The handle to the waitbar Figure is returned in h. x should be between 0 and
1. Each subsequent call to waitbar, waitbar(x), extends the length of the bar
to the new position x.
Example
waitbar is typically used inside a for loop that performs a lengthy
computation. For example,
h = waitbar(0,'Please wait...');
for i=1:100, % computation here %
waitbar(i/100)
end
close(h)
2-553
waitfor
Purpose
2waitfor
Wait for condition
Syntax
waitfor(h)
waitfor(h,'PropertyName')
waitfor(h,'PropertyName',PropertyValue)
Description
The waitfor function blocks the caller’s execution stream so that
command-line expressions, callbacks, and statements in the blocked M-file do
not execute until a specified condition is satisfied.
waitfor(h) returns when the graphics object identified by h is deleted or when
a Ctrl-C is typed in the Command Window. If h does not exist, waitfor returns
immediately without processing any events.
waitfor(h,'PropertyName'), in addition to the conditions in the previous
syntax, returns when the value of 'PropertyName' for the graphics object h
changes. If 'PropertyName' is not a valid property for the object, waitfor
returns immediately without processing any events.
waitfor(h,'PropertyName',PropertyValue), in addition to the conditions in
the previous syntax, waitfor returns when the value of 'PropertyName' for the
graphics object h changes to PropertyValue. waitfor returns immediately
without processing any events if 'PropertyName' is set to PropertyValue.
Remarks
While waitfor blocks an execution stream, other execution streams in the form
of callbacks may execute as a result of various events (e.g., pressing a mouse
button).
waitfor can block nested execution streams. For example, a callback invoked
during a waitfor statement can itself invoke waitfor.
See Also
2-554
uiresume, uiwait
waitforbuttonpress
Purpose
2waitforbuttonpress
Wait for key or mouse button press
Syntax
k = waitforbuttonpress
Description
k = waitforbuttonpress blocks the caller’s execution stream until the
function detects that the user has pressed a mouse button or a key while the
Figure window is active. The function returns
• 0 if it detects a mouse button press
• 1 if it detects a key press
Additional information about the event that causes execution to resume is
available through the Figure’s CurrentCharacter, SelectionType, and
CurrentPoint properties.
If a WindowButtonDownFcn is defined for the Figure, its callback is executed
before waitforbuttonpress returns a value.
Example
These statements display text in the Command Window when the user either
clicks a mouse button or types a key in the Figure window:
w = waitforbuttonpress;
if w == 0
disp('Button press')
else
disp('Key press')
end
See Also
dragrect, figure, gcf, ginput, rbbox, waitfor
2-555
warndlg
Purpose
2warndlg
Display warning dialog box
Syntax
h = warndlg('warningstring','dlgname')
Description
warndlg displays a dialog box named 'Warning Dialog' containing the string
'This is the default warning string.' The warning dialog box disappears
after you press the OK push button.
warndlg('warningstring') displays a dialog box with the title 'Warning
Dialog' containing the string specified by warningstring.
warndlg('warningstring','dlgname') displays a dialog box with the title
dlgname that contains the string warningstring.
h = warndlg(...) returns the handle of the dialog box.
Examples
The statement
warndlg('Pressing OK will clear memory','!! Warning !!')
displays this dialog box:
See Also
2-556
dialog, errordlg, helpdlg, msgbox
List of Commands
List of Commands
A
Function Names
area ………………………… 2-3
axes ………………………… 2-5
Axes Properties ……… 2-17
axis ……………………… 2-36
bar, barh ……………… 2-42
bar3, bar3h …………… 2-46
box ……………………… 2-50
brighten ………………… 2-51
camdolly ………………… 2-53
camlight ………………… 2-55
camlookat ……………… 2-57
camorbit ………………… 2-59
campan ………………… 2-61
campos ………………… 2-62
camproj ………………… 2-64
camroll ………………… 2-65
camtarget ……………… 2-66
camup …………………… 2-68
camva …………………… 2-70
camzoom………………… 2-72
capture ………………… 2-73
caxis …………………… 2-74
cla ……………………… 2-78
clabel …………………… 2-79
clc………………………… 2-81
clf ………………………… 2-82
close……………………… 2-83
colorbar ………………… 2-85
colordef ………………… 2-87
colormap………………… 2-88
ColorSpec ……………… 2-92
comet …………………… 2-94
comet3 ………………… 2-95
compass ………………… 2-96
contour ………………… 2-98
contour3 ………………… 2-102
contourc ………………… 2-104
contourf ………………… 2-106
contrast ………………… 2-108
copyobj ………………… 2-109
cylinder ………………… 2-111
-2
daspect …………………
datetick…………………
default4 ………………
drawnow ………………
errorbar ………………
ezplot……………………
feather …………………
figflag …………………
figure……………………
Figure Properties ……
fill ………………………
fill3 ……………………
findobj …………………
fplot ……………………
frame2im ………………
frameedit ………………
gca ………………………
gcf ………………………
gco ………………………
get ………………………
getframe ………………
ginput …………………
gplot ……………………
graymon ………………
grid ……………………
gtext ……………………
hidden …………………
hist………………………
hold ……………………
home ……………………
hsv2rgb…………………
im2frame ………………
image……………………
Image Properties ……
imagesc…………………
imfinfo …………………
imread …………………
imwrite …………………
ishandle ………………
ishold……………………
legend …………………
light ……………………
Light Properties ………
lightangle ………………
2-115
2-118
2-121
2-122
2-123
2-125
2-128
2-130
2-131
2-139
2-163
2-165
2-168
2-170
2-173
2-175
2-193
2-194
2-195
2-196
2-198
2-200
2-201
2-203
2-204
2-205
2-206
2-207
2-210
2-211
2-212
2-213
2-214
2-221
2-229
2-232
2-235
2-237
2-240
2-241
2-242
2-245
2-249
2-253
lighting …………………
line ………………………
Line Properties …………
LineSpec…………………
loglog ……………………
material …………………
mesh, meshc, meshz …
movie ……………………
moviein …………………
newplot …………………
noanimate ………………
orient ……………………
pareto ……………………
patch ……………………
Patch Properties ………
pbaspect …………………
pcolor ……………………
peaks ……………………
pie ………………………
pie3 ………………………
plot ………………………
plot3 ……………………
plotmatrix ………………
plotyy ……………………
polar ……………………
print, printopt …………
qtwrite …………………
quiver ……………………
quiver3 …………………
refresh……………………
reset………………………
rgb2hsv …………………
rgbplot……………………
ribbon ……………………
root object ………………
Root Properties …………
rose ………………………
rotate ……………………
rotate3d …………………
scatter ……………………
scatter3 …………………
semilogx, semilogy ……
set ………………………
shading …………………
2-254
2-255
2-262
2-270
2-274
2-277
2-279
2-283
2-285
2-287
2-290
2-291
2-293
2-294
2-305
2-322
2-327
2-330
2-331
2-333
2-335
2-343
2-345
2-347
2-349
2-351
2-362
2-363
2-365
2-367
2-368
2-369
2-370
2-371
2-373
2-377
2-384
2-386
2-388
2-389
2-391
2-393
2-395
2-398
List of Commands
slice …………………… 2-401
sphere ………………… 2-407
spinmap………………… 2-409
stairs …………………… 2-410
stem …………………… 2-412
stem3 …………………… 2-414
subplot ………………… 2-416
surf, surfc ……………… 2-418
surface ………………… 2-422
Surface Properties …… 2-430
surfl …………………… 2-442
surfnorm ……………… 2-445
terminal ……………… 2-447
text ……………………… 2-449
Text Properties ……… 2-456
title ……………………… 2-468
trimesh ………………… 2-470
trisurf…………………… 2-471
view …………………… 2-472
viewmtx………………… 2-475
waterfall ……………… 2-479
whitebg ………………… 2-481
xlabel, ylabel, zlabel … 2-482
xlim, ylim, zlim ……… 2-483
zoom …………………… 2-485
dialog …………………… 2-487
dragrect ………………… 2-488
errordlg ………………… 2-489
gcbo …………………… 2-491
helpdlg ………………… 2-492
inputdlg………………… 2-493
listdlg …………………… 2-495
msgbox ………………… 2-497
pagedlg ………………… 2-498
printdlg ………………… 2-499
questdlg………………… 2-500
rbbox …………………… 2-502
selectmoveresize ……… 2-504
textwrap ……………… 2-505
uicontextmenu ………… 2-507
uicontextmenu Properties……
2-511
uicontrol ……………… 2-515
uicontrol Properties … 2-523
uigetfile ………………… 2-535
uimenu…………………… 2-537
uimenu Properties …… 2-541
uiputfile ………………… 2-547
uiresume, uiwait ……… 2-549
uisetcolor………………… 2-550
uisetfont ………………… 2-551
waitbar ………………… 2-553
waitfor …………………… 2-554
waitforbuttonpress …… 2-555
warndlg ………………… 2-556
-3
-4
Index
A
Accelerator
Box, Axes property 2-17
Uimenu property 2-541
all 2-175
AmbientLightColor, Axes property 2-17
brighten 2-51
BusyAction
Axes property 2-17
Figure property 2-139
Image property 2-221
Light property 2-249
Line property 2-262
Patch property 2-305
Root property 2-377
Surface property 2-430
Text property 2-456
Uicontextmenu property 2-511
Uicontrol property 2-523
Uimenu property 2-541
AmbientStrength
Patch property 2-305
Surface property 2-430
area 2-3
aspect ratio of axes 2-115, 2-322
Axes
creating 2-5
defining default properties 2-9
property descriptions 2-17
axes
setting and querying data aspect ratio 2-115
setting and querying limits 2-483
setting and querying plot box aspect ratio
2-322
axes 2-5
axis 2-36
azimuth of viewpoint 2-473
ButtonDownFcn
Axes property 2-17
Figure property 2-139
Image property 2-221
Light property 2-249
Line property 2-262
Patch property 2-306
Root property 2-377
Surface property 2-431
Text property 2-456
Uicontextmenu property 2-511
Uicontrol property 2-523
Uimenu property 2-542
B
BackFaceLighting
Patch property 2-305
Surface property 2-430
BackGroundColor
Uicontrol property 2-523
BackingStore, Figure property 2-139
bar 2-42
bar3 2-46
bar3h 2-46
barh 2-42
bold font 2-465
box 2-50
C
CallBack
Uicontextmenu property 2-511
Uicontrol property 2-524
Uimenu property 2-542
CallbackObject, Root property 2-377
I-1
Index
camdolly 2-53
camera
dollying position 2-53
moving camera and target postions 2-53
placing a light at 2-55
positioning to view objects 2-57
rotating around camera target 2-59, 2-61
rotating around viewing axis 2-65
setting and querying position 2-62
setting and querying projection type 2-64
setting and querying target 2-66
setting and querying up vector 2-68
setting and querying view angle 2-70
CameraPosition, Axes property 2-18
CameraPositionMode, Axes property 2-18
CameraTarget, Axes property 2-18
CameraTargetMode, Axes property 2-18
CameraUpVector, Axes property 2-18
CameraUpVectorMode, Axes property 2-19
CameraViewAngle, Axes property 2-19
CameraViewAngleMode, Axes property 2-19
camlight 2-55
camlookat 2-57
camorbit 2-59
campan 2-61
campos 2-62
camproj 2-64
camroll 2-65
camtarget 2-66
camup 2-68
camva 2-70
camzoom 2-72
capture 2-73
CaptureMatrix, Root property 2-377
CaptureRect, Root property 2-377
caxis 2-74
CData
I-2
Image property 2-221
Patch property 2-306
Surface property 2-431
Uicontrol property 2-524
CDataMapping
Image property 2-223
Patch property 2-308
Surface property 2-431
check boxes 2-515
Checked, Uimenu property 2-542
Children
Axes property 2-20
Figure property 2-140
Image property 2-223
Light property 2-249
Line property 2-262
Patch property 2-309
Root property 2-377
Surface property 2-432
Text property 2-456
Uicontextmenu property 2-511
Uicontrol property 2-524
Uimenu property 2-542
cla 2-78
clabel 2-79
clc 2-81
clf 2-82
CLim, Axes property 2-20
CLimMode, Axes property 2-20
Clipping
Axes property 2-21
Figure property 2-140
Image property 2-223
Light property 2-249
Line property 2-262
Patch property 2-309
Root property 2-377
Index
Surface property 2-432
Text property 2-456
Uicontextmenu property 2-511
Uicontrol property 2-524
Uimenu property 2-542
close 2-83
CloseRequestFcn, Figure property 2-140
Color
Axes property 2-21
Figure property 2-141
Light property 2-249
Line property 2-262
Text property 2-456
colorbar 2-85
colormap 2-88
ColorMap, Figure property 2-141
colormaps
converting from RGB to HSV 2-369
plotting RGB components 2-370
ColorOrder, Axes property 2-21
ColorSpec 2-92
comet 2-94
comet3 2-95
compass 2-96
contour 2-98
contour3 2-102
contourc 2-104
contourf 2-106
contrast 2-108
coordinate system and viewpoint 2-473
copyobj 2-109
CreateFcn
Axes property 2-21
Figure property 2-142
Image property 2-224
Light property 2-249
Line property 2-263
Patch property 2-309
Root property 2-377
Surface property 2-432
Text property 2-457
Uicontextmenu property 2-511
Uicontrol property 2-524
Uimenu property 2-543
CurrentAxes 2-142
CurrentAxes, Figure property 2-142
CurrentCharacter, Figure property 2-143
CurrentFigure, Root property 2-377
CurrentMenu, Figure property (obsolete) 2-143
CurrentObject, Figure property 2-143
CurrentPoint
Axes property 2-22
Figure property 2-143
cylinder 2-111
D
daspect 2-115
data aspect ratio of axes 2-115
DataAspectRatio, Axes property 2-22
DataAspectRatioMode, Axes property 2-23
default4 2-121
DeleteFcn 2-263
Axes property 2-24
Figure property 2-144
Image property 2-224
Light property 2-250
Patch property 2-309
Root property 2-378
Surface property 2-432
Text property 2-457
Uicontextmenu property 2-512
Uicontrol property 2-525
Uimenu property 2-543
I-3
Index
Diary, Root property 2-378
DiaryFile, Root property 2-378
DiffuseStrength
Patch property 2-310
Surface property 2-432
Dithermap 2-144
Dithermap, Figure property 2-144
DithermapMode, Figure property 2-145
dolly camera 2-53
dragrect 2-488
DrawMode, Axes property 2-24
drawnow 2-122
E
Echo, Root property 2-378
EdgeColor
Patch property 2-310
Surface property 2-433
EdgeLighting
Patch property 2-310
Surface property 2-433
editable text 2-515
elevation of viewpoint 2-473
Enable
Uicontrol property 2-525
Uimenu property 2-543
EraseMode
Image property 2-224
Line property 2-263
Patch property 2-311
Surface property 2-434
Text property 2-458
errorbar 2-123
ErrorMessage, Root property 2-378
ErrorType, Root property 2-378
Extent
I-4
Text property 2-459
Uicontrol property 2-526
ezplot 2-125
F
FaceColor
Patch property 2-312
Surface property 2-435
FaceLighting
Patch property 2-312
Surface property 2-435
Faces, Patch property 2-312
FaceVertexCData, Patch property 2-313
feather 2-128
fig file 2-175
figflag 2-130
Figure
creating 2-131
defining default properties 2-132
properties 2-139
redrawing 2-367
figure 2-131
file
fig 2-175
fill 2-163
fill3 2-165
findobj 2-168
FixedColors, Figure property 2-145
FontAngle
Axes property 2-24
Text property 2-459
Uicontrol property 2-526
FontName
Axes property 2-24
Text property 2-459
Uicontrol property 2-526
Index
fonts
bold 2-465
italics 2-465
specifying family 2-465
specifying size of TeX characters 2-465
FontSize
Axes property 2-25
Text property 2-459
Uicontrol property 2-526
FontUnits
Axes property 2-25
Text property 2-459
Uicontrol property 2-527
FontWeight
Axes property 2-25
Text property 2-459
Uicontrol property 2-527
ForegroundColor
Uicontrol property 2-527
Uimenu property 2-543
Format 2-378
FormatSpacing, Root property 2-379
fplot 2-170
frame 2-175
frame2im 2-173
frameedit 2-175
frames 2-516
G
gca 2-193
gcf 2-194
gco 2-195
get 2-196
getframe 2-198
ginput 2-200
gplot 2-201
graphics objects
Axes 2-5
Figure 2-131
getting properties 2-196
Light 2-245
Line 2-255
Patch 2-294
resetting properties 2-368
Root 2-373
setting properties 2-395
Surface 2-422
Text 2-449
Uicontrol 2-515
Uimenu 2-537
graymon 2-203
Greek letters and mathematical symbols 2-463
grid 2-204
GridLineStyle, Axes property 2-25
gtext 2-205
GUIs, printing 2-359
H
HandleVisibility
Axes property 2-25
Figure property 2-145
Image property 2-225
Light property 2-250
Line property 2-264
Patch property 2-315
Root property 2-379
Surface property 2-435
Text property 2-460
Uicontextmenu property 2-512
Uicontrol property 2-527
Uimenu property 2-543
hidden 2-206
I-5
Index
hist 2-207
HitTest
Axes property 2-26
Figure property 2-146
Image property 2-226
Light property 2-251
Line property 2-264
Patch property 2-316
Root property 2-379
Surface property 2-436
Text property 2-460
Uicontextmenu property 2-513
Uicontrol property 2-528
hold 2-210
home 2-211
Patch property 2-316
Root property 2-379
Surface property 2-436
Text property 2-462
Uicontextmenu property 2-513
Uicontrol property 2-528
Uimenu property 2-544
InvertHardCopy, Figure property 2-147
ishandle 2-240
ishold 2-241
italics font 2-465
K
KeyPressFcn, Figure property 2-147
HorizontalAlignment
Text property 2-461
Uicontrol property 2-528
hsv2rgb 2-212
I
im2frame 2-213
Image
creating 2-214
defining default properties 2-218
properties 2-221
image 2-214
imagesc 2-229
interpolated shading and printing 2-360
Interpreter, Text property 2-462
Interruptible
Axes property 2-26
Figure property 2-147
Image property 2-226
Light property 2-251
Line property 2-265
I-6
L
Label, Uimenu property 2-545
labeling
axes 2-482
LaTeX, see TeX 2-463
Layer, Axes property 2-27
legend 2-242
Light
creating 2-245
defining default properties 2-246
positioning in camera coordinates 2-55
properties 2-249
light 2-245
lightangle 2-253
lighting 2-254
limits of axes, setting and querying 2-483
Line
creating 2-255
defining default properties 2-258
properties 2-262
Index
line 2-255
material 2-277
LineSpec 2-270
Max, Uicontrol property 2-529
LineStyle
MenuBar, Figure property 2-148
Line property 2-266
Patch property 2-317
Surface object 2-437
LineStyleOrder
Axes property 2-27
mesh 2-279
meshc 2-279
MeshStyle, Surface property 2-439
meshz 2-279
Min, Uicontrol property 2-529
LineWidth
MinColorMap, Figure property 2-148
Axes property 2-28
Line property 2-266
Patch property 2-317
Surface property 2-437
list boxes 2-516
ListboxTop, Uicontrol property 2-529
logarithm
plotting 2-274
loglog 2-274
movie 2-283
moviein 2-285
N
Name, Figure property 2-149
newplot 2-287
NextPlot
Axes property 2-28
Figure property 2-149
NormalMode
M
Marker
Line property 2-266
Patch property 2-317
Surface property 2-437
MarkerEdgeColor
Line property 2-267
Patch property 2-318
Surface property 2-438
MarkerFaceColor
Line property 2-267
Patch property 2-318
Surface property 2-439
MarkerSize
Line property 2-267
Patch property 2-318
Surface property 2-439
Patch property 2-318
Surface property 2-439
NumberTitle, Figure property 2-149
O
OpenGL 2-153
orient 2-291
orthographic projection, setting and querying
2-64
P
page setup 2-178
pagedlg 2-498
PaperOrientation, Figure property 2-149
PaperPosition, Figure property 2-149
I-7
Index
PaperPositionMode, Figure property 2-150
PaperSize, Figure property 2-150
PaperType, Figure property 2-150
PaperUnits, Figure property 2-151
Parent
Axes property 2-28
Figure property 2-152
Image property 2-226
Light property 2-251
Line property 2-267
Patch property 2-319
Root property 2-379
Surface property 2-439
Text property 2-462
Uicontextmenu property 2-513
Uicontrol property 2-530
Uimenu property 2-545
pareto 2-293
Patch
creating 2-294
defining default properties 2-300
properties 2-305
patch 2-294
pbaspect 2-322
pcolor 2-327
perspective projection, setting and querying 2-64
pie 2-331
pie3 2-333
plot 2-335
plot box aspect ratio of axes 2-322
plot, volumetric
slice plot 2-401
plot3 2-343
PlotBoxAspectRatio, Axes property 2-28
PlotBoxAspectRatioMode, Axes property 2-28
plotmatrix 2-345
plotting
I-8
2-D plot 2-335
3-D plot 2-343
errorbars 2-123
feather plots 2-128
function plots 2-125, 2-170
histogram plots 2-207
loglog plot 2-274
mesh plot 2-279
plot with two y-axes 2-347
ribbon plot 2-371
rose plot 2-384
scatter plot 2-345, 2-389
scatter plot, 3-D 2-391
semilogarithmic plot 2-393
stairstep plot 2-410
stem plot 2-412
stem plot, 3-D 2-414
surface plot 2-418
volumetric slice plot 2-401
plotyy 2-347
Pointer, Figure property 2-152
PointerLocation, Root property 2-379
PointerShapeCData, Figure property 2-152
PointerShapeHotSpot, Figure property 2-152
PointerWindow, Root property 2-380
polar 2-349, 2-349
polygon
creating with patch 2-294
pop-up menus 2-516
Position
Axes property 2-29
Figure property 2-153
Light property 2-251
Text property 2-462
Uicontrol property 2-530
Uimenu property 2-545
position of camera
Index
dollying 2-53
position of camera, setting and querying 2-62
PostScript
printing interpolated shading 2-360
print 2-351
print drivers
interploated shading 2-360
supported 2-352
printdlg 2-499
printframe 2-175
printframe editor 2-176
printing
GUIs 2-359
interpolated shading 2-360
line styles on Windows95 2-359
on MS-Windows 2-358
thick lines on Windows95 2-359
with frames 2-175
with non-normal EraseMode 2-225, 2-264, 2-311,
2-434, 2-458
with printframes 2-186
printing tips 2-358
printopt 2-351
Profile, Root property 2-380
ProfileFile, Root property 2-380
ProfileFunction, Root property 2-380
ProfileInterval, Root property 2-380
projection type, setting and querying 2-64
ProjectionType, Axes property 2-29
push buttons 2-516
Q
R
radio buttons 2-516
rbbox 2-367
RecursionLimit
Root property 2-380
refresh 2-367
renderer
OpenGL 2-153
painters 2-153
zbuffer 2-153
Renderer, Figure property 2-153
RendererMode, Figure property 2-156
reset 2-368
Resize, Figure property 2-156
ResizeFcn, Figure property 2-157
RGB, converting to HSV 2-369
rgb2hsv 2-369
rgbplot 2-370
ribbon 2-371
rolling camera 2-65
root 2-373
Root graphics object 2-373
root object 2-373
root, see rootobject 2-373
rose 2-383, 2-384
rotate 2-386
rotate3d 2-388
rotating camera 2-59
rotating camera target 2-61
Rotation, Text property 2-462
rubberband 2-502
qtwrite 2-362
S
QuickTime movie 2-362
quiver 2-363
quiver3 2-365
scatter 2-389
scatter3 2-391
ScreenDepth, Root property 2-381
I-9
Index
ScreenSize, Root property 2-381
Selected
Axes property 2-29
Figure property 2-158
Image property 2-226
Light property 2-251
Line property 2-268
Patch property 2-319
Root property 2-381
Surface property 2-439
Text property 2-462
Uicontextmenu property 2-513
Uicontrol property 2-530
Uimenu property 2-545
selecting areas 2-502
SelectionHighlight
Axes property 2-30
Figure property 2-158
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-319
Surface property 2-440
Text property 2-462
Uicontextmenu property 2-513
Uicontrol property 2-530
SelectionType, Figure property 2-158
semilogx 2-393
semilogy 2-393
Separator, Uimenu property 2-545
set 2-395
shading 2-398
shading colors in surface plots 2-398
ShareColors, Figure property 2-159
ShowHiddenHandles, Root property 2-381
Simulink
printing with frames 2-175
I-10
size of fonts, see also FontSize property 2-465
slice 2-401
sliders 2-517
SliderStep, Uicontrol property 2-531
SpecularColorReflectance
Patch property 2-319
Surface property 2-440
SpecularExponent
Patch property 2-319
Surface property 2-440
SpecularStrength
Patch property 2-319
Surface property 2-440
sphere 2-407
sphereical coordinates
defining a Light position in 2-253
spinmap 2-409
stairs 2-410
static text 2-517
stem 2-412
stem3 2-414
stretch-to-fill 2-6
String
Text property 2-463
Uicontrol property 2-531
Style
Light property 2-252
Uicontrol property 2-532
subplot 2-416
surf 2-418
Surface
creating 2-422
defining default properties 2-425
properties 2-430
surface 2-422
surfc 2-418
surfl 2-442
Index
surfnorm 2-445
TooltipString
symbols in text 2-463
Uicontrol property 2-532
trimesh 2-470
trisurf 2-471
T
Type
Tag
Axes property 2-30
Figure property 2-159
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-320
Root property 2-381
Surface property 2-440
Text property 2-465
Uicontextmenu property 2-514
Uicontrol property 2-532
Uimenu property 2-545
target, of camera 2-66
terminal 2-447
TerminalDimensions, Root property 2-382
TerminalHideGraphCommand, Root property 2-381
TerminalOneWindow, Root property 2-382
TerminalProtocol, Root property 2-382
TerminalShowGraphCommand, Root property 2-382
TeX commands in text 2-463
Text
creating 2-449
defining default properties 2-452
properties 2-456
text 2-449
TickDir, Axes property 2-30
TickDirMode, Axes property 2-30
TickLength, Axes property 2-30
title 2-468
Title, Axes property 2-31
toggle buttons 2-517
Axes property 2-31
Figure property 2-160
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-320
Root property 2-382
Surface property 2-440
Text property 2-465
Uicontextmenu property 2-514
Uicontrol property 2-532
Uimenu property 2-546
U
UIContextMenu
Axes property 2-31
Figure property 2-160
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-320
Surface property 2-441
Text property 2-466
UiContextMenu
Uicontrol property 2-532
Uicontextmenu
properties 2-511
Uicontextmenu
Uicontextmenu property 2-514
Uicontrol
creating 2-515
I-11
Index
defining default properties 2-523
properties 2-523
types of 2-515
uicontrol 2-487, 2-515
uigetfile 2-535
Uimenu
creating 2-537
defining default properties 2-541
properties 2-541
uimenu 2-537
uiputfile 2-547
uiresume 2-549
uisetcolor 2-550
uisetfont 2-551
Units
Axes property 2-31
Figure property 2-160
Root property 2-382
Text property 2-465
Uicontrol property 2-533
up vector, of camera 2-68
V
Value, Uicontrol property 2-533
VertexNormals
Patch property 2-320
Surface property 2-441
VerticalAlignment, Text property 2-466
Vertices, Patch property 2-321
view 2-57
azimuth of viewpoint 2-473
coordinate system defining 2-473
elevation of viewpoint 2-473
view 2-472
view angle, of camera 2-70
View, Axes property (obsolete) 2-32
viewing
a group of object 2-57
a specific object in a scene 2-57
viewmtx 2-475
Visible
Axes property 2-32
Figure property 2-161
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-321
Root property 2-383
Surface property 2-441
Text property 2-467
Uicontextmenu property 2-514
Uicontrol property 2-534
Uimenu property 2-546
UserData
Axes property 2-32
Figure property 2-160
Image property 2-227
Light property 2-252
Line property 2-268
Patch property 2-320
Root property 2-383
Surface property 2-441
Text property 2-466
Uicontextmenu property 2-514
Uicontrol property 2-533
Uimenu property 2-546
W
waitbar 2-553
waitfor 2-554
waitforbuttonpress 2-555
I-12
Index
warndlg 2-556
YColor, Axes property 2-32
waterfall 2-479
YData
whitebg 2-481
Image property 2-228
Line property 2-269
Patch property 2-321
Surface property 2-441
YDir, Axes property 2-33
YGrid, Axes property 2-33
ylabel 2-482
YLabel, Axes property 2-33
ylim 2-483
YLim, Axes property 2-33
YLimMode, Axes property 2-34
YScale, Axes property 2-34
YTick, Axes property 2-34
YTickLabel, Axes property 2-34
YTickLabelMode, Axes property 2-35
YTickMode, Axes property 2-35
WindowButtonDownFcn, Figure property 2-161
WindowButtonMotionFcn, Figure property 2-161
WindowButtonUpFcn, Figure property 2-161
Windows95, printing 2-359
WindowStyle, Figure property 2-161
X
x-axis limits, setting and querying 2-483
XAxisLocation, Axes property 2-32
XColor, Axes property 2-32
XData
Image property 2-227
Line property 2-269
Patch property 2-321
Surface property 2-441
XDir, Axes property 2-33
XGrid, Axes property 2-33
xlabel 2-482
XLabel, Axes property 2-33
xlim 2-483
XLim, Axes property 2-33
XLimMode, Axes property 2-34
XOR, printing 2-225, 2-264, 2-311, 2-434, 2-458
XScale, Axes property 2-34
XTick, Axes property 2-34
XTickLabel, Axes property 2-34
XTickLabelMode, Axes property 2-35
XTickMode, Axes property 2-35
Y
y-axis limits, setting and querying 2-483
YAxisLocation, Axes property 2-32
Z
z-axis limits, setting and querying 2-483
ZColor, Axes property 2-32
ZData
Line property 2-269
Patch property 2-321
Surface property 2-441
ZDir, Axes property 2-33
ZGrid, Axes property 2-33
zlabel 2-482
zlim 2-483
ZLim, Axes property 2-33
ZLimMode, Axes property 2-34
zoom 2-485
ZScale, Axes property 2-34
ZTick, Axes property 2-34
ZTickLabel, Axes property 2-34
I-13
Index
ZTickLabelMode, Axes property 2-35
ZTickMode, Axes property 2-35
I-14
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement