Using MATLAB Graphics

Using MATLAB Graphics
MATLAB
®
The Language of Technical Computing
Computation
Visualization
Programming
Using MATLAB Graphics
Version 6
How to Contact The MathWorks:
www.mathworks.com
comp.soft-sys.matlab
Web
Newsgroup
[email protected]
Technical support
Product enhancement suggestions
Bug reports
Documentation error reports
Order status, license renewals, passcodes
Sales, pricing, and general information
508-647-7000
Phone
508-647-7001
Fax
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
Mail
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
For contact information about worldwide offices, see the MathWorks Web site.
Using MATLAB Graphics
 COPYRIGHT 1984 - 2001 by The MathWorks, Inc.
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.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by
or for the federal government of the United States. By accepting delivery of the Program, the government
hereby agrees that this software qualifies as "commercial" computer software within the meaning of FAR
Part 12.212, DFARS Part 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Part
252.227-7014. The terms and conditions of The MathWorks, Inc. Software License Agreement shall pertain
to the government’s use and disclosure of the Program and Documentation, and shall supersede any
conflicting contractual terms or conditions. If this license fails to meet the government’s minimum needs or
is inconsistent in any respect with federal procurement law, the government agrees to return the Program
and Documentation, unused, to MathWorks.
MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and
Target Language Compiler is a trademark of The MathWorks, Inc.
Other product or brand names are trademarks or registered trademarks of their respective holders.
Printing History: January 1997
January 1998
January 1999
September 2000
June 2001
First printing
Second printing
Third printing
Fourth printing
Online only
New for MATLAB 5.1
Revised for MATLAB 5.2
Revised for MATLAB 5.3 (Release 11)
Revised for MATLAB 6.0 (Release 12)
Revised for MATLAB 6.1 (Release 12.1)
Contents
Graphics
Overview of MATLAB Graphics
1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Plotting Your Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Anatomy of a Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Editing a Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Interactive Plot Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Using Functions to Edit Graphs . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Using Plot Editing Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting Plot Edit Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exiting Plot Edit Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Objects in a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cutting, Copying, and Pasting Objects . . . . . . . . . . . . . . . . . . .
Moving and Resizing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing Objects in a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-6
1-7
1-7
1-7
1-8
1-8
1-9
Saving Your Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving a Graph in MAT-File Format . . . . . . . . . . . . . . . . . . . .
Saving to a Different Format (Exporting Figures) . . . . . . . . .
Printing Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-10
1-10
1-11
1-11
1-12
Changing Your View of an Axes . . . . . . . . . . . . . . . . . . . . . . . 1-13
Zooming In and Out on an Axes . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Rotating 3-D Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Using the Property Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
iii
Starting the Property Editor . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing the Property Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigating Among Objects in a Graph . . . . . . . . . . . . . . . . . . .
Identifying Objects in a Graph . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Your Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-16
1-16
1-17
1-18
1-20
1-21
Using the Data Statistics Tool . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Adding Plots of Statistics to a Graph . . . . . . . . . . . . . . . . . . . . 1-22
Saving Statistics to the Workspace . . . . . . . . . . . . . . . . . . . . . . 1-23
Basic Plotting
2
Basic Plotting Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Creating Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Specifying Line Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Specifying the Color and Size of Lines . . . . . . . . . . . . . . . . . . . . 2-6
Adding Plots to an Existing Graph . . . . . . . . . . . . . . . . . . . . . . . 2-7
Plotting Only the Data Points . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Plotting Markers and Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Line Styles for Black and White Output . . . . . . . . . . . . . . . . . 2-10
Setting Default Line Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Line Plots of Matrix Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Plotting Imaginary and Complex Data . . . . . . . . . . . . . . . . . 2-15
Plotting with Two Y-Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Combining Linear and Logarithmic Axes . . . . . . . . . . . . . . . . . 2-16
Setting Axis Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Axis Limits and Ticks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example – Specifying Ticks and Tick Labels . . . . . . . . . . . . . .
Setting Aspect Ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
Contents
2-19
2-19
2-22
2-24
Figure Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Multiple Plots per Figure . . . . . . . . . . . . . . . . . . . .
Specifying the Target Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Color Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-26
2-26
2-28
2-28
Formatting Graphs
3
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Adding a Title to a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Title Option on the Insert Menu . . . . . . . . . . . . . . . .
Using the Property Editor to Add a Title . . . . . . . . . . . . . . . . . .
Using the title Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-3
3-3
3-4
3-5
Adding a Legend to a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Using the Legend Option on the Insert Menu . . . . . . . . . . . . . . 3-7
Using the Legend Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Positioning a Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Editing a Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Removing a Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Adding Axes Labels to a Graph . . . . . . . . . . . . . . . . . . . . . . . .
Using the Label Options on the Insert Menu . . . . . . . . . . . . . .
Using the Property Editor to Add Axes labels . . . . . . . . . . . . .
Using the Label Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-11
3-12
3-12
3-13
Adding Text Annotations to a Graph . . . . . . . . . . . . . . . . . . .
Creating Text Annotations in Plot Editing Mode . . . . . . . . . .
Creating Text Annotations with the text or gtext Command .
Example – Aligning Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing Text Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including Symbols and Greek Letters in Text Strings . . . . . .
Using Variables in Text Strings . . . . . . . . . . . . . . . . . . . . . . . .
Example - Multiline Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-15
3-16
3-16
3-21
3-22
3-23
3-25
3-25
Adding Arrows and Lines to a Graph . . . . . . . . . . . . . . . . . . 3-27
v
Creating Arrows and Lines in Plot Editing Mode . . . . . . . . . . 3-27
Editing Arrows and Line Annotations . . . . . . . . . . . . . . . . . . . 3-28
Adding Plots of Basic Statistics to a Graph . . . . . . . . . . . . .
Example - Plotting the Mean of a Data Set . . . . . . . . . . . . . . .
Formatting Plots of Data Statistics . . . . . . . . . . . . . . . . . . . . .
Statistics Plotted by the Data Statistics Tool . . . . . . . . . . . . . .
Viewing Statistics for Multiple Plots . . . . . . . . . . . . . . . . . . . .
Saving Statistics to the MATLAB Workspace . . . . . . . . . . . . .
3-29
3-30
3-32
3-32
3-33
3-34
Creating Specialized Plots
4
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Bar and Area Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Types of Bar Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Stacked Bar Graphs to Show Contributing Amounts . . . . . . . . 4-6
Specifying X-Axis Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Overlaying Plots on Bar Graphs . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Area Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Comparing Datasets with Area Graphs . . . . . . . . . . . . . . . . . . 4-13
Pie Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
Removing a Piece from a Pie Charts . . . . . . . . . . . . . . . . . . . . . 4-17
vi
Contents
Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Histograms in Cartesian Coordinate Systems . . . . . . . . . . . . .
Histograms in Polar Coordinate Systems . . . . . . . . . . . . . . . . .
Specifying Number of Bins . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-18
4-18
4-20
4-21
Discrete Data Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two–Dimensional Stem Plots . . . . . . . . . . . . . . . . . . . . . . . . . .
Combining Stem Plots with Line Plots . . . . . . . . . . . . . . . . . . .
Three-Dimensional Stem Plots . . . . . . . . . . . . . . . . . . . . . . . . .
Stairstep Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-23
4-23
4-26
4-27
4-30
Direction and Velocity Vector Graphs . . . . . . . . . . . . . . . . . .
Compass Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Feather Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two-Dimensional Quiver Plots . . . . . . . . . . . . . . . . . . . . . . . . .
Three-Dimensional Quiver Plots . . . . . . . . . . . . . . . . . . . . . . . .
4-32
4-32
4-33
4-35
4-36
Contour Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Simple Contour Plots . . . . . . . . . . . . . . . . . . . . . . . . .
Labeling Contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filled Contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Drawing a Single Contour Line at a Desired Level . . . . . . . . .
The Contouring Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Offset of a Contour . . . . . . . . . . . . . . . . . . . . . . .
Displaying Contours in Polar Coordinates . . . . . . . . . . . . . . . .
4-38
4-38
4-40
4-41
4-42
4-43
4-44
4-45
Interactive Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49
Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Movies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example – Visualizing an FFT as a Movie . . . . . . . . . . . . . . . .
Erase Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-51
4-51
4-52
4-53
Displaying Bit-Mapped Images
5
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Images in MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Image Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Indexed Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Intensity Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RGB (Truecolor) Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-6
5-6
5-7
5-9
Working with 8-Bit and 16-Bit Images . . . . . . . . . . . . . . . . . . 5-11
8-Bit and 16-Bit Indexed Images . . . . . . . . . . . . . . . . . . . . . . . 5-11
vii
8-Bit and 16-Bit Intensity Images . . . . . . . . . . . . . . . . . . . . . .
8-Bit and 16-Bit RGB Images . . . . . . . . . . . . . . . . . . . . . . . . . .
Mathematical Operations Support for uint8 and uint16 . . . . .
Other 8-Bit and 16-Bit Array Support . . . . . . . . . . . . . . . . . . .
Summary of Image Types and Numeric Classes . . . . . . . . . . .
5-12
5-12
5-13
5-13
5-14
Reading, Writing, and Querying Graphics Image Files . . .
Reading a Graphics Image . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing a Graphics Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Information About Graphics Files . . . . . . . . . . . . .
5-15
5-15
5-16
5-16
Displaying Graphics Images . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Summary of Image Types and Display Methods . . . . . . . . . . . 5-19
Controlling Aspect Ratio and Display Size . . . . . . . . . . . . . . . . 5-19
The Image Object and Its Properties . . . . . . . . . . . . . . . . . . .
CData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CDataMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XData and YData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EraseMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-23
5-23
5-23
5-24
5-26
Printing Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28
Converting the Data or Graphic Type of Images . . . . . . . . 5-29
Basic Printing and Exporting
6
Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialog Box Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing to a Printer Using the Defaults . . . . . . . . . . . . . . . . . .
Printing to a Printer at Screen Size . . . . . . . . . . . . . . . . . . . . . .
Printing to a Printer, Locking the Ticks and Limits of the Axes
Printing to a Printer, Setting the Paper Size . . . . . . . . . . . . . . .
Printing to a Printer, Setting the Size of and
Centering a Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii Contents
6-3
6-3
6-3
6-4
6-6
6-7
6-8
6-9
Printing to a Nondefault Printer . . . . . . . . . . . . . . . . . . . . . . . .
Printing to a Printer Using GhostScript . . . . . . . . . . . . . . . . . .
Printing a Figure to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appending a Figure to a PostScript File . . . . . . . . . . . . . . . . . .
Exporting a Figure to a File in a Specific Graphics Format . .
Exporting a Figure in EPS Format with a TIFF Preview . . . .
Exporting a Figure to the Clipboard . . . . . . . . . . . . . . . . . . . . .
6-11
6-13
6-14
6-16
6-16
6-18
6-18
Overview of Printing and Exporting . . . . . . . . . . . . . . . . . . .
What Is Printed or Exported . . . . . . . . . . . . . . . . . . . . . . . . . . .
Which Figure Is Printed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Print or Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Settings and How to Change Them . . . . . . . . . . . . . . .
6-22
6-22
6-22
6-23
6-23
Printing a Figure to a Printer or a File . . . . . . . . . . . . . . . . .
Using Print Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
From the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Figure’s Settings . . . . . . . . . . . . . . . . . . . . . . . . .
Printing the Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-26
6-26
6-27
6-30
6-41
Exporting a Figure in Graphics Format . . . . . . . . . . . . . . . . 6-47
Exporting to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
Exporting to the Clipboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exporting Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-55
6-56
6-59
6-63
Handle Graphics Objects
7
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Graphics Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Types of Graphics Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
ix
Handle Graphics Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Changing Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Properties Common to All Objects . . . . . . . . . . . . . . . . . . . . . . 7-10
x
Contents
Graphics Object Creation Functions . . . . . . . . . . . . . . . . . . .
Example – Creating Graphics Objects . . . . . . . . . . . . . . . . . . .
Parenting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
High-Level Versus Low-Level . . . . . . . . . . . . . . . . . . . . . . . . . .
Simplified Calling Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-12
7-13
7-15
7-15
7-16
Setting and Querying Property Values . . . . . . . . . . . . . . . . .
Setting Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Querying Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Factory-Defined Property Values . . . . . . . . . . . . . . . . . . . . . . .
7-18
7-18
7-20
7-22
Setting Default Property Values . . . . . . . . . . . . . . . . . . . . . . .
How MATLAB Searches for Default Values . . . . . . . . . . . . . . .
Defining Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples – Setting Default LineStyles . . . . . . . . . . . . . . . . . .
7-23
7-23
7-25
7-26
Accessing Object Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Current Figure, Axes, and Object . . . . . . . . . . . . . . . . . . .
Searching for Objects by Property Values — findobj . . . . . . . .
Copying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-30
7-30
7-32
7-33
7-35
Controlling Graphics Output . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying the Target for Graphics Output . . . . . . . . . . . . . . .
Preparing Figures and Axes for Graphics . . . . . . . . . . . . . . . .
Targeting Graphics Output with newplot . . . . . . . . . . . . . . . .
Example – Using newplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing for Hold State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protecting Figures and Axes . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Close Request Function . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handle Validity Versus Handle Visibility . . . . . . . . . . . . . . . .
7-37
7-37
7-37
7-39
7-40
7-42
7-43
7-45
7-46
Saving Handles in M-Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-48
Properties Changed by Built-In Functions . . . . . . . . . . . . . 7-49
Axes Properties
8
Axes Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Labeling and Appearance Properties . . . . . . . . . . . . . . . . . . . 8-3
Creating Axes with Specific Characteristics . . . . . . . . . . . . . . . 8-3
Positioning Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
The Position Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
Multiple Axes per Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Placing Text Outside the Axes . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Multiple Axes for Different Scaling . . . . . . . . . . . . . . . . . . . . . . 8-8
Individual Axis Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Axis Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Tick Mark Locations . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Axis Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-10
8-11
8-12
8-13
Using Multiple X and Y Axes . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
Example – Double Axis Graphs . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
Automatic-Mode Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Colors Controlled by Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Axes Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Axes Color Limits – The CLim Property . . . . . . . . . . . . . . . . .
Example – Simulating Multiple Colormaps in a Figure . . . . .
Calculating Color Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining the Color of Lines for Plotting . . . . . . . . . . . . . . . . . .
Line Styles Used for Plotting – LineStyleOrder . . . . . . . . . . . .
8-22
8-22
8-25
8-25
8-26
8-29
8-31
xi
Figure Properties
9
Figure Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Positioning Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
The Position Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Example – Specifying Figure Position . . . . . . . . . . . . . . . . . . . . 9-5
Controlling How MATLAB Uses Color . . . . . . . . . . . . . . . . . . 9-7
Indexed Color Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Colormap Colors and Fixed Colors . . . . . . . . . . . . . . . . . . . . . . . 9-8
Using a Large Number of Colors . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Nonactive Figures and Shared Colors . . . . . . . . . . . . . . . . . . . 9-11
Dithering Truecolor on Indexed Color Systems . . . . . . . . . . . . 9-12
Selecting Drawing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . .
Backing Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Double Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-15
9-15
9-15
9-16
Specifying the Figure Pointer . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
Defining Custom Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Interactive Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
3-D Visualization
Creating 3-D Graphs
10
Topics in 3-D Graphing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
A Typical 3-D Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
xii
Contents
Line Plots of 3-D Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Representing a Matrix As a Surface . . . . . . . . . . . . . . . . . . . . 10-6
Mesh and Surface Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
Visualizing Functions of Two Variables . . . . . . . . . . . . . . . . . . 10-7
Surface Plots of Nonuniformly Sampled Data . . . . . . . . . . . . . 10-9
Parametric Surfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Hidden Line Removal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Coloring Mesh and Surface Plots . . . . . . . . . . . . . . . . . . . . .
Colormaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Indexed Colors – Direct and Scaled Colormapping . . . . . . . .
Example – Mapping Surface Curvature to Color . . . . . . . . . .
Altering Colormaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10-14
10-14
10-17
10-18
10-20
Truecolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Texture Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Defining the View
11
View Definition Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Setting the Viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Specifying Azimuth and Elevation . . . . . . . . . . . . . . . . . . . . . . 11-4
Defining Scenes with Camera Graphics . . . . . . . . . . . . . . . . 11-8
View Control with the Camera Toolbar . . . . . . . . . . . . . . . . 11-9
Camera Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
Camera Motion Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
Orbit Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
Orbit Scene Light . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13
Pan/Tilt Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
Move Camera Horizontally/Vertically . . . . . . . . . . . . . . . . . . 11-15
Move Camera Forward and Backwards . . . . . . . . . . . . . . . . . 11-16
xiii
Zoom Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
Camera Roll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18
Walk Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
Camera Graphics Functions . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
Dollying the Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Moving the Camera Through a Scene . . . . . . . . . . . . . . . . .
Summary of Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Graphing the Volume Data . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up the View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying the Light Source . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining the Camera Path as a Stream Line . . . . . . . . . . . . .
Implementing the Fly-Through . . . . . . . . . . . . . . . . . . . . . . . .
11-24
11-24
11-24
11-25
11-25
11-26
11-26
11-26
Low-Level Camera Properties . . . . . . . . . . . . . . . . . . . . . . . .
Default Viewpoint Selection . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving In and Out on the Scene . . . . . . . . . . . . . . . . . . . . . . .
Making the Scene Larger or Smaller . . . . . . . . . . . . . . . . . . .
Revolving Around the Scene . . . . . . . . . . . . . . . . . . . . . . . . . .
Rotation Without Resizing of Graphics Objects . . . . . . . . . . .
Rotation About the Viewing Axis . . . . . . . . . . . . . . . . . . . . . .
11-30
11-31
11-31
11-33
11-33
11-33
11-34
View Projection Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Projection Types and Camera Location . . . . . . . . . . . . . . . . . 11-37
Understanding Axes Aspect Ratio . . . . . . . . . . . . . . . . . . . .
Stretch-to-Fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Axis Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Aspect Ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example – axis Command Options . . . . . . . . . . . . . . . . . . . . .
Additional Commands for Setting Aspect Ratio . . . . . . . . . . .
11-41
11-41
11-41
11-42
11-43
11-45
Axes Aspect Ratio Properties . . . . . . . . . . . . . . . . . . . . . . . . 11-46
Default Aspect Ratio Selection . . . . . . . . . . . . . . . . . . . . . . . . 11-47
Overriding Stretch-to-Fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-49
xiv Contents
Effects of Setting Aspect Ratio Properties . . . . . . . . . . . . . . . 11-50
Example – Displaying Real Objects . . . . . . . . . . . . . . . . . . . . 11-54
Lighting as a Visualization Tool
12
Lighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Lighting Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Lighting Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Light Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Adding Lights to a Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Properties That Affect Lighting . . . . . . . . . . . . . . . . . . . . . . . 12-8
Selecting a Lighting Method . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
Face and Edge Lighting Methods . . . . . . . . . . . . . . . . . . . . . . 12-10
Reflectance Characteristics of Graphics Objects . . . . . . .
Specular and Diffuse Reflection . . . . . . . . . . . . . . . . . . . . . . .
Ambient Light . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specular Exponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specular Color Reflectance . . . . . . . . . . . . . . . . . . . . . . . . . . .
Back Face Lighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Positioning Lights in Data Space . . . . . . . . . . . . . . . . . . . . . .
12-12
12-12
12-13
12-14
12-15
12-15
12-18
Transparency
13
Transparency Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Making Objects Transparent . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
xv
Specifying Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Specifying a Single Transparency Value . . . . . . . . . . . . . . . 13-6
Example – Transparent Isosurface . . . . . . . . . . . . . . . . . . . . . . 13-6
Mapping Data to Transparency . . . . . . . . . . . . . . . . . . . . . . . .
Size of the Alpha Data Array . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapping Alpha Data to the Alphamap . . . . . . . . . . . . . . . . . . .
Example: Mapping Data to Color or Transparency . . . . . . . . .
13-8
13-9
13-9
13-9
Selecting an Alphamap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Example: Modifying the Alphamap . . . . . . . . . . . . . . . . . . . . 13-13
Creating 3-D Models with Patches
14
Introduction to Patch Objects . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Behavior of the patch Function . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Single Polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14-2
14-2
14-2
14-4
Multi-Faceted Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Example – Defining a Cube . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Specifying Patch Coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
Face and Edge Coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Example – Specifying Flat Edge and Face Coloring . . . . . . . 14-13
Coloring Edges with Shared Vertices . . . . . . . . . . . . . . . . . . . 14-14
How MATLAB Interprets Patch Color Data . . . . . . . . . . . .
Indexed Color Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Truecolor Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interpolating in Indexed Color Versus Truecolor . . . . . . . . .
xvi Contents
14-16
14-16
14-19
14-19
Volume Visualization Techniques
15
Volume Visualization Topics . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2
Overview of Volume Visualization . . . . . . . . . . . . . . . . . . . . .
Examples of Volume Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Visualization Techniques . . . . . . . . . . . . . . . . . . . . .
Steps to Create a Volume Visualization . . . . . . . . . . . . . . . . . .
15-3
15-3
15-3
15-4
Volume Visualization Functions . . . . . . . . . . . . . . . . . . . . . . . 15-5
Visualizing Scalar Volume Data . . . . . . . . . . . . . . . . . . . . . . . 15-7
Techniques for Visualizing Scalar Data . . . . . . . . . . . . . . . . . . 15-7
Visualizing MRI Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Exploring Volumes with Slice Planes . . . . . . . . . . . . . . . . . 15-14
Example – Slicing Fluid Flow Data . . . . . . . . . . . . . . . . . . . . 15-14
Modifying the Color Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 15-17
Connecting Equal Values with Isosurfaces . . . . . . . . . . . . 15-19
Example – Isosurfaces in Fluid Flow Data . . . . . . . . . . . . . . . 15-19
Isocaps Add Context to Visualizations . . . . . . . . . . . . . . . . 15-21
Defining Isocaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-22
Example – Adding Isocaps to an Isosurface . . . . . . . . . . . . . . 15-23
Visualizing Vector Volume Data . . . . . . . . . . . . . . . . . . . . . .
Using Scalar Techniques with Vector Data . . . . . . . . . . . . . .
Specifying Starting Points for Stream Plots . . . . . . . . . . . . . .
Accessing Subregions of Volume Data . . . . . . . . . . . . . . . . . .
Stream Line Plots of Vector Data
15-25
15-25
15-26
15-28
. . . . . . . . . . . . . . . . . . . . 15-30
Displaying Curl with Stream Ribbons . . . . . . . . . . . . . . . . . 15-32
Displaying Divergence with Stream Tubes . . . . . . . . . . . . 15-34
xvii
Creating Stream Particle Animations . . . . . . . . . . . . . . . . . 15-37
Vector Field Displayed with Cone Plots . . . . . . . . . . . . . . . 15-40
xviii Contents
Graphics
MATLAB® provides many graphics functions that allow you to create 2-D plots
of your data. This collection includes the following topics.
• Overview of MATLAB Graphics – plot editing mode and the Property Editor.
• Basic Plotting – plotting vector and matrix data in 2-D representations.
• Formatting Graphs – describes how to customize the format of a plot to help
explain your data. This section includes information about adding labels,
titles, and annotations to a plot.
• Creating Specialized Plots – describes how to create bar graphs, histograms,
and contour plots.
• Basic Printing and Exporting – describes frequently used ways to print or
export a MATLAB figure, and explains the basic printing and exporting
interfaces.
• Handle Graphics® Objects – introduces MATLAB’s graphics objects and
properties.
• Figure Properties – discusses the features that are implemented with figure
properties.
• Axes Properties – discusses the features that are implemented with axes
properties.
Related Information
These other collections provide additional information about plotting.
• 3-D Visualization describes how to use views and lighting to achieve more
complex graphic effects than can be achieved using the basic plotting
functions.
• Creating GUIs describes how to include menus, push buttons, text boxes,
and other user interface objects in MATLAB applications.
1
Overview of MATLAB
Graphics
Introduction . . . . . . . . . . . . . . . . . . . . 1-2
Plotting Your Data . . . . . . . . . . . . . . . . . 1-3
Editing a Plot
. . . . . . . . . . . . . . . . . . . 1-5
Using Plot Editing Mode
Saving Your Work
. . . . . . . . . . . . . . 1-6
. . . . . . . . . . . . . . . . . 1-10
Changing Your View of an Axes . . . . . . . . . . . 1-13
Using the Property Editor . . . . . . . . . . . . . . 1-15
Using the Data Statistics Tool . . . . . . . . . . . . 1-22
1
Overview of MATLAB Graphics
Introduction
MATLAB includes extensive plotting capabilities. This section provides an
overview of these capabilities, including:
• “Plotting Your Data” on page 1-3
• “Editing a Plot” on page 1-5
• “Saving Your Work” on page 1-10
• “Changing Your View of an Axes” on page 1-13
• “Using the Property Editor” on page 1-15
• “Using the Data Statistics Tool” on page 1-22
1-2
Plotting Your Data
Plotting Your Data
The process of constructing a basic graph to meet your presentation graphics
requirements is outlined in the following table. The table shows seven typical
steps and some example code for each.
If you are performing analysis only, you may want to view various graphs just
to explore your data. In this case, steps 1 and 3 may be all you need. If you are
creating presentation graphics, you may want to fine-tune your graph by
positioning it on the page, setting line styles and colors, adding annotations,
and making other such improvements.
Step
Typical Code
1 Prepare your data
x = 0:0.2:12;
y1 = bessel(1,x);
y2 = bessel(2,x);
y3 = bessel(3,x);
2 Select a window and position a
figure(1)
subplot(2,2,1)
plot region within the window
3 Call elementary plotting
h = plot(x,y1,x,y2,x,y3);
function
4 Select line and marker
characteristics
5 Set axis limits, tick marks, and
grid lines
6 Annotate the graph with axis
labels, legend, and text
7 Export graph
set(h,'LineWidth',2,{'LineStyle'},{'--';':';'-.'})
set(h,{'Color'},{'r';'g';'b'})
axis([0 12 −0.5 1])
grid on
xlabel('Time')
ylabel('Amplitude')
legend(h,'First','Second','Third')
title('Bessel Functions')
[y,ix] = min(y1);
text(x(ix),y,'First Min \rightarrow',...
'HorizontalAlignment','right')
print −depsc -tiff -r200 myplot
1-3
1
Overview of MATLAB Graphics
Anatomy of a Plot
MATLAB plotting functions direct their output to a window that is separate
from the command window. In MATLAB this window is referred to as a figure.
For example, the following illustrates the plot of the Bessel functions, described
in “Plotting Your Data” on page 1-3, highlighting the basic components of the
graph.
MATLAB figure
window
Axes on which
MATLAB plots
data
Line plots
representing
data
By default, MATLAB uses line style and color to distinguish the data sets
plotted in the graph. However, you can change the appearance of these graphic
components or add annotations to the graph to help explain your data for
presentation graphics. For information, see “Editing a Plot” on page 1-5.
1-4
Editing a Plot
Editing a Plot
MATLAB formats a graph to provide readability, setting the scale of axes,
including tick marks on the axes, and using color and line style to distinguish
the plots in the graph. However, if you are creating presentation graphics, you
may want to change this default formatting or add descriptive labels, titles,
legends and other annotations to help explain your data.
MATLAB supports two ways to edit the plots you create.
• Using the mouse to select and edit objects interactively
• Using MATLAB functions at the command-line or in an M-file
Interactive Plot Editing
If you enable plot editing mode in the MATLAB figure window, you can perform
point-and-click editing of your graph. In this mode, you can change the format
of objects in your graph by double-clicking on the object and changing the
values of its properties. In plot editing mode, you access the properties through
the a graphical user interface, called the Property Editor.
For more information about interactive editing, see “Using Plot Editing Mode”
on page 1-6. For information about editing object properties in plot editing
mode, see “Using the Property Editor” on page 1-15.
Using Functions to Edit Graphs
If you prefer to work from the MATLAB command line or if you are creating an
M-file, you can use MATLAB commands to edit the graphs you create. Taking
advantage of MATLAB’s Handle Graphics system, you can use the set and get
commands to change the properties of the objects in a graph.
Note Plot editing mode provides an alternative way to access the properties
of MATLAB graphic objects. However, you can only access a subset of object
properties through this mechanism. You may need to use a combination of
interactive editing and command line editing to achieve the effect you desire.
1-5
1
Overview of MATLAB Graphics
Using Plot Editing Mode
To start plot edit mode, click
this button.
Use these toolbar buttons to add text, arrows, and lines.
Use the Edit, Insert, and
Tools menus to add objects
or edit existing objects in a
graph.
Double-click on an object to
select it.
Position labels, legends, and
other objects by clicking and
dragging.
Access object-specific plot
edit functions through
context-sensitive pop-up
menus.
The MATLAB figure window supports a point-and-click style editing mode that
you can use to customize the appearance of your graph. This section describes
how to start plot edit mode and perform basic editing tasks, including:
• “Selecting Objects in a Graph” on page 1-7
• “Cutting, Copying, and Pasting Objects” on page 1-8
• “Moving and Resizing Objects” on page 1-8
• “Editing Objects in a Graph” on page 1-9
• “Saving Your Work” on page 1-10
• “Changing Your View of an Axes” on page 1-13
1-6
Using Plot Editing Mode
Starting Plot Edit Mode
Before you can select objects in a figure by clicking on them, you must activate
plot editing mode. There are several ways to activate plot edit mode:
• Choose the Edit Plot option on the figure window Tools menu.
• Click on the selection button in the figure window toolbar.
Click this button to start plot edit mode.
• Choose an option from the Edit or Insert menu. For example, if you choose
the Axes Properties option on the Edit menu, MATLAB activates plot edit
mode and the axes appear selected.
• Run the plotedit command in the MATLAB command window.
When a figure window is in plot edit mode, the Edit Plot option on the Tools
menu is checked and the selection button in the toolbar is highlighted.
Exiting Plot Edit Mode
To exit plot edit mode, click the selection button or click the Edit Plot option
on the Tools menu. When plot edit mode is turned off, the selection button is
no longer highlighted.
Selecting Objects in a Graph
To select an object in a graph:
1 Start plot edit mode.
2 Move the cursor over the object and click on it.
Selection handles appear on the selected object.
Selecting Multiple Objects
To select multiple objects at the same time:
1 Start plot edit mode.
1-7
1
Overview of MATLAB Graphics
2 Move the cursor over an object and shift-click to select it. Repeat for each
object you want to select.
You can perform actions on all of the selected objects. For example, to remove
a text annotation and an arrow annotation from a graph, select the objects and
then select Cut from the Edit menu.
Deselecting Objects
To deselect an object, move the cursor off the object onto the figure window
background and click the left mouse button. You can also shift-click on a
selected object to deselect it.
Cutting, Copying, and Pasting Objects
To cut an object from a graph, or copy and paste an object in a graph, perform
these steps.
1 Start plot edit mode.
2 Select the object.
3 Select the Cut, Copy, or Paste option from the Edit menu or use standard
shortcut keys for your platform.
Alternatively, with plot edit mode enabled, you can right-click on an object and
then select an editing command from the context menu associated with the
object.
Note If you cut an axes label or title and then paste it back into a figure, the
label or title is no longer anchored to the axis. If you move the axes, the label
or title will not move with the axes.
Moving and Resizing Objects
To move or resize an object in a graph, perform these steps.
1 Start plot edit mode.
1-8
Using Plot Editing Mode
2 For axes objects only: unlock the axes by right-clicking on it and choosing
Unlock Axes Position from the context menu.
3 Select the object. Selection handles appear on the object.
To move the object, drag it to the new location.
To resize the object, drag a selection handle.
Note You can move, but cannot resize text objects.
Editing Objects in a Graph
In MATLAB, every object in a graph supports a set of properties that control
the graph’s appearance and behavior. For example, line objects support
properties that control thickness, color, and line style.
In plot edit mode, MATLAB provides a graphical user interface to object
properties called the Property Editor. The Property Editor is a dialog box that
supports a specific set of tabbed panels for each object you can select. For more
information, see “Using the Property Editor” on page 1-15.
1-9
1
Overview of MATLAB Graphics
Saving Your Work
After editing a graph, you can:
• Save your work in a format that can be opened during another MATLAB
session.
• Save your work in a format that can be used by other applications.
Saving a Graph in MAT-File Format
MATLAB supports a binary format in which you can save figures so that they
can be opened in subsequent MATLAB sessions. MATLAB assigns these files
the .fig file name extension.
To save a graph in a figure file:
1 Select Save from the figure window File menu or click the Save button on
the toolbar. If this is the first time you are saving the file, the Save As dialog
box appears.
2 Make sure that the Save as type is Fig-file.
3 Specify the name you want assigned to the figure file.
4 Click OK.
The graph is saved as a figure file (.fig), which is a binary file format used to
store figures.
You can also use the saveas command.
If you want to save the figure in a format that can be used by another
application, see “Saving to a Different Format (Exporting Figures)” on
page 1-11.
Opening a Figure File
To open a figure file, perform these steps.
1 Select Open from the File menu or click the Open button on the toolbar.
1-10
Saving Your Work
2 Select the figure file you want to open and click OK.
The figure file appears in a new figure window.
You can also use the open command.
Saving to a Different Format (Exporting Figures)
To save a figure in a format that can be used by another application, such as
the standard graphics file formats TIFF or EPS, perform these steps:
1 Select Export from the figure window File menu. The Export dialog box
appears.
2 Select the format from the list of formats in the Save as type: menu. This
selects the standard filename extension given to files of that type.
3 Enter the name you want to give the file.
4 Click Save.
Copying a Figure to the Clipboard
On Windows systems, you can also copy a figure to the clipboard and then paste
it into another application:
1 Select Copy Options from the Figure window Edit menu. The Copying
Options page of the Preferences dialog box appears.
2 Complete the fields on the Copying Options page and click OK.
3 Select Copy Figure from the Edit menu.
The figure is copied to the Windows clipboard. You can then paste the figure
from the Windows clipboard into a file in another application.
Printing Figures
Before printing a figure:
1 Select Page Setup from the figure window File menu to set printing options.
The Page Setup dialog box opens.
1-11
1
Overview of MATLAB Graphics
2 Make changes in the dialog box. If you want the printed output to exactly
match the annotated plot you see on the screen:
a On the Axes and Figure tab, click Keep screen limits and ticks.
b On the Size and Position tab, click Use screen size, centered on page.
For more information about other options for page setup, click the Help
button in the dialog box.
To print a figure, select Print from the figure window File menu and complete
the Print dialog box that appears.
You can also use the print command.
Getting Help
To access help for the plot editing mode, select Plot Editing from the figure
window Help menu. You can also access help at the command line by typing
help plotedit or doc plotedit. For information about other graphics
features, select Graphics from the figure window Help menu.
1-12
Changing Your View of an Axes
Changing Your View of an Axes
MATLAB lets you change your view of axes by either zooming in for a closer
look at a portion of an axes or, for 3-D axes, rotating the axes.
• “Zooming In and Out on an Axes” on page 1-13
• “Rotating 3-D Axes” on page 1-14
The zoom and rotate 3-D options provides basic view changing capabilities. For
more advanced viewing, select the Camera option from the Tools menu. See for
more information.
Note Activating any of the zoom, rotate, or camera functions automatically
turns off plot editing mode.
Zooming In and Out on an Axes
The zoom in function lets you get a closer view of a portion of an axes. The zoom
out function lets you view a larger portion of an axes.
To zoom in on a portion of axes:
1 Activate the zoom function by choosing the Zoom In option on the Tools
menu or by clicking the Zoom In button in the toolbar.
Zoom out
Zoom in
2 Click on the area of the axes where you want to zoom in, or drag the cursor
to draw a box around the area where you want to zoom in.
MATLAB redraws the axes, zooming in on the area you specified. To further
magnify the area, click repeatedly in the axes or draw additional boxes in the
axes. To end zoom in mode, click the Zoom In button.
1-13
1
Overview of MATLAB Graphics
Note Properties of the axes, such as the tick marks, automatically adjust to
the new magnification or orientation. Annotations do not.
To zoom out from an axes, click the Zoom Out button on the toolbar and then
click on an area of the axes where you want to zoom out. To end zoom out mode,
click the Zoom Out button.
The zoom buttons use the camzoom command.
Rotating 3-D Axes
To rotate a 3-D axes:
1 Activate the rotate 3-D function by choosing the Rotate 3-D option on the
Tools menu or by clicking the Rotate 3-D button in the toolbar.
Rotate 3-D
Note Activating the rotate 3-D function automatically turns off plot editing
mode.
2 Click on the axes and an outline of the figure appears in the axes to help you
visualize the rotation. Drag the cursor in the direction you want to rotate.
When you release the mouse button, MATLAB redraws the axes in the new
orientation.
3 Click the rotate button again to end rotate 3-D mode.
The Rotate 3-D button uses the rotate3d command.
1-14
Using the Property Editor
Using the Property Editor
The Property Editor provides access to many properties of objects in a graph,
including figures, axes, lines, lights, patches, images, surfaces, rectangles, text,
and the root object.
Use these buttons to move back and forth among the graphics objects you have edited.
Use the navigation bar to select
the object you want to edit.
Click on a tab to view a
group of properties.
Click here to view a list of
values for this field.
Check this box to see the
effect of your changes as
you make them.
Click OK to apply your
changes and dismiss the
Property Editor.
Click Cancel to dismiss the Property Editor
without applying your changes.
Click Apply to apply your changes without
dismissing the Property Editor.
Click Help to get information about
particular properties.
This section describes:
• Starting the Property Editor
• “Editing Object Properties” on page 1-17
• “Navigating Among Objects in a Graph” on page 1-18
• “Applying Your Changes” on page 1-21
1-15
1
Overview of MATLAB Graphics
Starting the Property Editor
There are several ways to start the Property Editor.
If plot editing mode is enabled, you can:
• Double-click on an object in the graph.
Note Double-clicking on a text object does not start the Property Editor. It
opens a edit box around the text. To modify the properties of a text object, use
one of the other mechanisms.
• Right-click on an object, view the context menu, and select the Properties
option. The context menus associated with objects also provide direct access
to certain commonly used properties.
• Select Figure Properties, Axes Properties, or Current Object Properties
from the figure window Edit menu. These options automatically enable plot
editing mode, if it is not already enabled.
You can also start the Property Editor from the command line using the
propedit function.
Note Once you start the Property Editor, keep it open throughout an editing
session. If you click on another object in the graph, the Property Editor
displays the set of panels associated with that object type. You can also use the
navigation bar in the Property Editor to select other objects to edit in the
graph.
Closing the Property Editor
Once activated, the Property Editor remains on your screen until you explicitly
dismiss it by clicking either the Cancel button or the OK button. The Cancel
button dismisses the Property Editor without applying any changes that may
have been made to property values that haven’t been applied. The OK button
dismisses the Property Editor dialog box and applies any changes that have
been made to property values.
1-16
Using the Property Editor
Editing Object Properties
To edit the properties of an object:
1 Start plot editing mode.
2 Start the Property Editor by double-clicking on the object in the graph or
using one of the other mechanisms.
The Property Editor displays the set of panels associated with the object you
have selected.
3 Click on the tab of the panel that contains the property you want to modify.
4 Change the value of the property. For some properties, you must select a
value from a menu of values. For other fields, you can either select a value
or type a value directly into the field.
Note If you place the cursor over a field, a data tip appears that displays the
name of the property being edited and its current value.
5 Click the Apply button.
For example, if you double-click on a line object in a graph, the Property Editor
displays the set of tabbed panels specific to line objects: Data, Style, and Info.
To change the style of a line from solid to dashed, click on the Style tab to view
1-17
1
Overview of MATLAB Graphics
the style panel and click on the Line style menu. Select Dashed line from the
list of styles.
Line style
property
menu
Editing Multiple Objects
If you select multiple objects of the same type, the Property Editor displays the
set of panels specific to that object type. For example, if you select several lines
in a graph, the Property Editor displays the panels associated with line objects.
If you change the value of a line property and apply your change, it affects all
the objects you have selected.
If you select multiple objects of different types, for example, a line and an axes,
the Property Editor displays only the Info panel, which provides access to
properties that are common to all object types.
For information about navigating among multiple selections, see “Multiple
Selections and the Navigation Bar” on page 1-20.
Navigating Among Objects in a Graph
The navigation bar at the top of the Property Editor, labeled Edit Properties
for, identifies the object being edited by its type (class) and tag, if the object’s
tag property has a value. (A tag is a user-defined text string associated with an
object.)
1-18
Using the Property Editor
You can also use the navigation bar to select other objects, or groups of objects,
in the graph that you want to edit. The following sections describe how to use
the navigation bar.
• “Selecting Objects from the Navigation Bar” on page 1-19
• “Using the Navigation Bar To Search for Objects” on page 1-20
• “Multiple Selections and the Navigation Bar” on page 1-20
Selecting Objects from the Navigation Bar
To edit one of the other objects in the graph:
1 Click on the navigation bar menu. The Property Editor displays a
hierarchical list of all the objects in the current figure. (The Property Editor
includes other figures that may be open in the list but does not include the
child objects of these figures.)
Click here to display the navigation bar menu.
Navigation bar identifies
object being edited.
Navigation bar menu
lists all the objects in the
current figure.
2 Select the object you want to edit from this list. The Property Editor displays
the set of panels associated with the type of object you have selected. See
“Identifying Objects in a Graph” on page 1-20 for more information.
Note Only objects that have their HandleVisibility property set to On
appear in the navigation bar hierarchical list. However, objects appear in the
navigation bar even if their Visibility property is set to Off.
1-19
1
Overview of MATLAB Graphics
Using the Navigation Bar To Search for Objects
You can use the navigation bar to search for a particular object, or group of
objects, in a figure by a tag, type (class), or handle.
For example, to edit every line in a figure, enter the text string line in the
navigation bar. The Property Editor displays the set of property panels
associated with line objects and lists all the lines in the navigation bar.
Individual line objects are identified by their tags, if present.
Multiple Selections and the Navigation Bar
When you select multiple objects, the Property Editor’s navigation bar displays
the objects’ ancestors and children if the objects share a common parent. The
Property Editor displays all the children in a single, non-hierarchical list. If
you select objects that do not have a common parent, the Property Editor
navigation bar only displays the selected objects.
For example, if you create a graph containing multiple line plots and you select
several of the lines, the Property Editor’s navigation bar display looks like this.
Navigation bar identifies
objects being edited.
Navigation bar lists the
selected objects and
their common parents.
Identifying Objects in a Graph
In the hierarchical display of the navigation bar, the Property Editor lists all
the objects in a graph by their type and tag, if the object has a tag.
If a graph contains numerous line objects, tags can help identify which line
object listed in the navigation bar list represents which line in the graph.
To create a tag for a particular object in a graph:
1 Double-click on the object in the graph. Plot editing mode must be enabled.
1-20
Using the Property Editor
2 Click on the Info tab in the Property Editor.
3 Enter a text string in the Tag field that identifies the object in the graph.
4 Click Apply.
The Property Editor immediately updates the navigation bar display with the
tag value.
Applying Your Changes
To apply your changes, click the Apply button.
If you have checked the Immediate Apply box, your changes will appear
automatically; you do not need to click on the Apply button.
If you make changes to fields on a panel and then attempt to switch panels
without applying your changes, the Property Editor displays a warning
message, asking you if you want to apply your changes before moving.
If you click OK, you apply your changes and dismiss the Property Editor.
Note During an editing session, keep the Property Editor open. Throughout
the session, you can edit the properties of any object in your graph without
restarting the Property Editor.
Canceling Changes
If you have changed the values of properties and decide not to apply the
changes, click on the Revert button. The Revert button resets all the
properties to their values at the last Apply.
To reset a property value change and close the Property Editor, click the
Cancel button.
1-21
1
Overview of MATLAB Graphics
Using the Data Statistics Tool
The Data Statistics tool:
• Calculates basic statistics about the central tendency and variability of data
plotted in a graph
• Plots any of the statistics in a graph.
When you select Data Statistics from the MATLAB figure window Tools
menu, MATLAB calculates the statistics for each data set plotted in the graph
and displays the results in the Data Statistics dialog box.
Identifies the figure in which the data is plotted.
Identifies the data set for
which statistics have been
calculated.
Lists the statistics calculated
for both the x- and y-data
that define the plot.
To add a plot of a statistic to
a graph, click in the check
box next to the value.
Click here to create workspace variables of the statistics.
Adding Plots of Statistics to a Graph
To plot a statistic in a graph, click in the check box next to its value. “Adding
Plots of Data Statistics to a Graph” in the “Formatting Graphs” chapter
provides an example of using the Data Statistics tool.
1-22
Using the Data Statistics Tool
Saving Statistics to the Workspace
To save a set of statistics as a workspace variable, click on the Save to
workspace... button. The Data Statistics tool saves the statistics as a
structure.
1-23
1
Overview of MATLAB Graphics
1-24
2
Basic Plotting
Basic Plotting Commands . . . . .
Creating Plots . . . . . . . . . . .
Specifying Line Style . . . . . . . .
Specifying the Color and Size of Lines .
Adding Plots to an Existing Graph . . .
Plotting Only the Data Points . . . . .
Plotting Markers and Lines . . . . .
Line Styles for Black and White Output
Setting Default Line Styles . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 2-2
. 2-2
. 2-4
. 2-6
. 2-7
. 2-8
. 2-9
. 2-10
. 2-11
Line Plots of Matrix Data . . . . . . . . . . . . . . 2-13
Plotting Imaginary and Complex Data . . . . . . . . 2-15
Plotting with Two Y-Axes . . . . . . . . . . . . . . 2-16
Combining Linear and Logarithmic Axes . . . . . . . . . 2-16
Setting Axis Parameters . . . . . . .
Axis Limits and Ticks . . . . . . . . .
Example – Specifying Ticks and Tick Labels
Setting Aspect Ratio . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 2-19
. 2-19
. 2-22
. 2-24
Figure Windows . . . . . . .
Displaying Multiple Plots per Figure
Specifying the Target Axes . . . .
Default Color Scheme . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 2-26
. 2-26
. 2-28
. 2-28
.
.
.
.
.
.
.
.
.
.
.
.
2
Basic Plotting
Basic Plotting Commands
MATLAB® provides a variety of functions for displaying vector data as line
plots, as well as functions for annotating and printing these graphs. The
following table summarizes the functions that produce basic line plots. These
functions differ in the way they scale the plot’s axes. Each accepts input in the
form of vectors or matrices and automatically scales the axes to accommodate
the data.
Function
Description
plot
Graph 2-D data with linear scales for both axes
plot3
Graph 3-D data with linear scales for both axes
loglog
Graph with logarithmic scales for both axes
semilogx
Graph with a logarithmic scale for the x-axis and a
linear scale for the y-axis
semilogy
Graph with a logarithmic scale for the y-axis and a
linear scale for the x-axis
plotyy
Graph with y-tick labels on the left and right side
Creating Plots
The plot function has different forms depending on the input arguments. For
example, if y is a vector, plot(y) produces a linear graph of the elements of y
versus the index of the elements of y. If you specify two vectors as arguments,
plot(x,y) produces a graph of y versus x.
For example, these statements create a vector of values in the range [0, 2π] in
increments of π/100 and then use this vector to evaluate the sine function over
that range. MATLAB plots the vector on the x-axis and the value of the sine
function on the y-axis.
t = 0:pi/100:2*pi;
y = sin(t);
plot(t,y)
grid on
2-2
Basic Plotting Commands
MATLAB automatically selects appropriate axis ranges and tick mark
locations.
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
You can plot multiple graphs in one call to plot using x-y pairs. MATLAB
automatically cycles through a predefined list of colors to allow discrimination
between each set of data. Plotting three curves as a function of t produces
y2 = sin(t-0.25);
y3 = sin(t-0.5);
plot(t,y,t,y2,t,y3)
2-3
2
Basic Plotting
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
Specifying Line Style
You can assign different line styles to each data set by passing line style
identifier strings to plot. For example,
t = 0:pi/100:2*pi;
y = sin(t);
y2 = sin(t-0.25);
y3 = sin(t-0.5);
plot(t,y,'−',t,y2,'--',t,y3,':')
2-4
Basic Plotting Commands
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
Colors, Line Styles, and Markers
The basic plotting functions accepts character-string arguments that specify
various line styles, marker symbols, and colors for each vector plotted. In the
general form,
plot(x,y,'linestyle_marker_color')
linestyle_marker_color is a character string (delineated by single quotation
marks) constructed from:
• A line style (e.g., dashed, dotted, etc.)
• A marker type (e.g., x, *, o, etc.)
• A predefined color specifier (c, m, y, k, r, g, b, w)
For example,
plot(x,y,':squarey')
plots a yellow dotted line and places square markers at each data point. If you
specify a marker type, but not a line style, MATLAB draws only the marker.
2-5
2
Basic Plotting
The specification can consist of one or none of each specifier in any order. For
example, the string,
'go--'
defines a dashed line with circular markers, both colored green.
You can also specify the size of the marker and, for markers that are closed
shapes, you can specify separately the color of the edges and the face.
See the LineSpec discussion for more information.
Specifying the Color and Size of Lines
You can control a number of line style characteristics by specifying values for
line properties:
• LineWidth – specifies the width of the line in units of points.
• 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.
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 a graph with:
• A red dashed line with square markers
• A line width of two points
• The edge of the marker colored black
• The face of the marker colored green
• The size of the marker set to 10 points
2-6
Basic Plotting Commands
3
2
1
0
−1
−2
−3
−4
−3
−2
−1
0
1
2
3
4
Adding Plots to an Existing Graph
You can add plots to an existing graph using the hold command. When you set
hold to on, MATLAB does not remove the existing graph; it adds the new data
to the current graph, rescaling if the new data falls outside the range of the
previous axis limits.
For example, these statements first create a semilogarithmic plot, then add a
linear plot.
semilogx(1:100,'+')
hold on
plot(1:3:300,1:100,'--')
hold off
While MATLAB resets the x-axis limits to accommodate the new data, it does
not change the scaling from logarithmic to linear.
2-7
2
Basic Plotting
100
90
80
70
60
50
40
30
20
10
0 0
10
1
10
2
10
3
10
Plotting Only the Data Points
To plot a marker at each data point without connecting the markers with lines,
use a specification that does not contain a line style. For example, given two
vectors,
x = 0:pi/15:4*pi;
y = exp(2*cos(x));
calling plot with only a color and marker specifier
plot(x,y,'r+')
plots a red plus sign at each data point.
2-8
Basic Plotting Commands
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
See LineSpec for a list of available line styles, markers, and colors.
Plotting Markers and Lines
To plot both markers and the lines that connect them, specify a line style and
a marker type. For example, the following command plots the data as a red,
solid line and then adds circular markers with black edges at each data point.
x = 0:pi/15:4*pi;
y = exp(2*cos(x));
plot(x,y,'−r',x,y,'ok')
2-9
2
Basic Plotting
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
Line Styles for Black and White Output
Line styles and markers enable you to discriminate different plots on the same
graph when color is not available. For example, the following statements create
a graph using a solid ('−*k') line with asterisk markers colored black and a
dash-dot ('−.ok') line with circular markers colored black.
x = 0:pi/15:4*pi;
y1 = exp(2*cos(x));
y2 = exp(2*sin(x));
plot(x,y1,'−*k',x,y2,'−.ok')
2-10
Basic Plotting Commands
8
7
6
5
4
3
2
1
0
0
2
4
6
8
10
12
14
Setting Default Line Styles
You can configure MATLAB to use line styles instead of colors for multi-line
plots by setting a default value for the axes LineStyle property. For example,
the command,
set(0,'DefaultAxesLineStyleOrder',{'-o',':s','--+'})
defines three line styles and makes them the default for all plots.
To set the default line color to dark gray, use the statement
set(0,'DefaultAxesColorOrder',[0.4,0.4,0.4])
See ColorSpec for information on how to specify color as a three-element vector
of RGB values.
Now the plot command uses the line styles and colors you have defined as
defaults. For example, these statements create a multiline plot.
x = 0:pi/10:2*pi;
y1 = sin(x);
2-11
2
Basic Plotting
y2 = sin(x-pi/2);
y3 = sin(x-pi);
plot(x,y1,x,y2,x,y3)
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
The default values persist until you quit MATLAB. To remove default values
during your MATLAB session, use the reserved word remove.
set(0,'DefaultAxesLineStyleOrder','remove')
set(0,'DefaultAxesColorOrder','remove')
See “Setting Default Property Values” in the “Handle Graphics Objects”
chapter for more information.
2-12
Line Plots of Matrix Data
Line Plots of Matrix Data
When you call the plot function with a single matrix argument
plot(Y)
MATLAB draws one line for each column of the matrix. The x-axis is labeled
with the row index vector, 1:m, where m is the number of rows in Y. For example,
Z = peaks;
returns a 49-by-49 matrix obtained by evaluating a function of two variables.
Plotting this matrix
plot(Z)
produces a graph with 49 lines.
10
8
6
4
2
0
−2
−4
−6
−8
0
5
10
15
20
25
30
35
40
45
50
In general, if plot is used with two arguments and if either X or Y has more
than one row or column, then
• If Y is a matrix, and x is a vector, plot(x,Y) successively plots the rows or
columns of Y versus vector x, using different colors or line types for each. The
2-13
2
Basic Plotting
row or column orientation varies depending on whether the number of
elements in x matches the number of rows in Y or the number of columns. If
Y is square, its columns are used.
• If X is a matrix and y is a vector, plot(X,y) plots each row or column of X
versus vector y. For example, plotting the peaks matrix versus the vector
1:length(peaks) rotates the previous plot.
y = 1:length(peaks);
plot(peaks,y)
50
45
40
35
30
25
20
15
10
5
0
−8
−6
−4
−2
0
2
4
6
8
10
• If X and Y are both matrices of the same size, plot(X,Y) plots the columns of
X versus the columns of Y.
You can also use the plot function with multiple pairs of matrix arguments.
plot(X1,Y1,X2,Y2,...)
This statement graphs each X-Y pair, generating multiple lines. The different
pairs can be of different dimensions.
2-14
Plotting Imaginary and Complex Data
Plotting Imaginary and Complex Data
When the arguments to plot are complex (i.e., the imaginary part is nonzero),
MATLAB ignores the imaginary part except when plot is given a single
complex argument. For this special case, the command is a shortcut for a plot
of the real part versus the imaginary part. Therefore,
plot(Z)
where Z is a complex vector or matrix, is equivalent to
plot(real(Z),imag(Z))
For example, this statement plots the distribution of the eigenvalues of a
random matrix using circular markers to indicate the data points.
plot(eig(randn(20,20)),'o','MarkerSize',6)
5
4
3
2
1
0
−1
−2
−3
−4
−5
−6
−5
−4
−3
−2
−1
0
1
2
3
4
To plot more than one complex matrix, there is no shortcut; the real and
imaginary parts must be taken explicitly.
2-15
2
Basic Plotting
Plotting with Two Y-Axes
The plotyy command enables you to create plots of two data sets and use both
left and right side y-axes. You can also apply different plotting functions to
each data set. For example, you can combine a line plot with a stem plot of the
same data.
t = 0:pi/20:2*pi;
y = exp(sin(t));
plotyy(t,y,t,y,'plot','stem')
3
3
2.5
2.5
2
2
1.5
1.5
1
1
0.5
0
0
0.5
1
2
3
4
5
6
0
7
Combining Linear and Logarithmic Axes
You can use plotyy to apply linear and logarithmic scaling to compare two data
sets having a different range of values.
t = 0:900; A = 1000; a = 0.005; b = 0.005;
z1 = A*exp(-a*t);
z2 = sin(b*t);
[haxes,hline1,hline2] = plotyy(t,z1,t,z2,'semilogy','plot');
2-16
Plotting with Two Y-Axes
This example saves the handles of the lines and axes created to adjust and label
the graph. First, label the axes whose y value ranges from 10 to 1000. This is
the first handle in haxes because we specified this plot first in the call to
plotyy. Use the axes command to make haxes(1) the current axes, which is
then the target for the ylabel command.
axes(haxes(1))
ylabel('Semilog Plot')
Now make the second axes current and call ylabel again.
axes(haxes(2))
ylabel('Linear Plot')
You can modify the characteristics of the plotted lines in a similar way. For
example, to change the line style of the second line plotted to a dashed line, use
the statement
set(hline2,'LineStyle','--')
3
10
1
0.8
0.6
0.2
2
10
0
Linear Plot
Semilog Plot
0.4
−0.2
−0.4
−0.6
−0.8
1
10
0
100
200
300
400
500
600
700
800
−1
900
2-17
2
Basic Plotting
See “Using Multiple X and Y Axes” in the “Axes Properties” chapter for an
example that employs double x- and y-axes.
See LineSpec for additional line properties.
2-18
Setting Axis Parameters
Setting Axis Parameters
When you create a graph, MATLAB automatically selects the axis limits and
tick-mark spacing based on the data plotted. However, you can specify your
own values for axis limits and tick marks by overriding MATLAB’s values. You
can do this with the following commands:
• axis – sets values that affect the current axes object (the most recently
created or the last clicked on).
• axes – (not axis) creates a new axes object with the specified characteristics.
• get and set – enable you to query and set a wide variety of properties of
existing axes.
• gca – returns the handle (identifier) of the current axes. If there are multiple
axes in the figure window, the current axes is the last graph created or the
last graph you clicked on with the mouse.
Related Information
See the chapter “Defining the View” for more extensive information on
manipulating 3-D views.
Axis Limits and Ticks
MATLAB selects axis limits based on the range of the plotted data. You can
specify the limits manually using the axis command. Call axis with the new
limits defined as a four-element vector.
axis([xmin,xmax,ymin,ymax])
Note that the minimum values must be less than the maximum values.
Semiautomatic Limits
If you want MATLAB to autoscale only one of a min/max set of axis limits, but
you want to specify the other, use the MATLAB variable Inf or −Inf for the
autoscaled limit. For example, this graph uses default scaling.
2-19
2
Basic Plotting
2.5
2
1.5
1
0.5
0
0
1
2
3
4
5
6
7
8
9
10
Compare the default limits to the following graph, which sets the maximum
limit of the x-axis, but autoscales the minimum limit.
axis([−Inf 5 2 2.5])
2-20
Setting Axis Parameters
2.5
2.45
2.4
2.35
2.3
2.25
2.2
2.15
2.1
2.05
2
0
0.5
1
1.5
2
2.5
3
3.5
4
4.5
5
Axis Tick Marks
MATLAB selects the tick mark locations based on the range of data so as to
produce equally spaced ticks (for linear graphs). You can specify different tick
marks by setting the axes XTick and YTick properties. Define tick marks as a
vector of increasing values. The values do not need to be equally spaced.
For example, setting the y-axis tick marks for the graph from the preceding
example,
set(gca,'ytick',[2 2.1 2.2 2.3 2.4 2.5])
produces a graph with only the specified ticks on the y-axis.
2-21
2
Basic Plotting
2.5
2.4
2.3
2.2
2.1
2
0
0.5
1
1.5
2
2.5
3
3.5
4
4.5
5
Note that if you specify tick mark values that are outside the axis limits,
MATLAB does not display them (that is, specifying tick marks cannot cause
axis limits to change).
Example – Specifying Ticks and Tick Labels
You can adjust the axis tick-mark locations and the labels appearing at each
tick mark. 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'})
These commands (xlabel, ylabel, title, text) add axis labels and draw an
arrow that points to the location on the graph where y = sin(−pi/4).
xlabel('−\pi \leq \Theta \leq \pi')
ylabel('sin(\Theta)')
2-22
Setting Axis Parameters
title('Plot of sin(\Theta)')
text(−pi/4,sin(−pi/4),'\leftarrow sin(−\pi\div4)',...
'HorizontalAlignment','left')
Setting Line Properties on an Existing Plot
Change the line color to purple by first finding the handle of the line object
created by plot and then setting its Color property. Use findobj and the fact
that MATLAB creates a blue line (RGB value [0 0 1]) by default. In the same
statement, set the LineWidth property to 2 points.
set(findobj(gca,'Type','line','Color',[0 0 1]),...
'Color',[0.5,0,0.5],'LineWidth',2)
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
−pi
−pi/2
0
−π ≤ Θ ≤ π
pi/2
pi
The Greek symbols are created using TeX character sequences.
2-23
2
Basic Plotting
Setting Aspect Ratio
By default, MATLAB displays graphs in a rectangular axes that has the same
aspect ratio as the figure window. This makes optimum use of space available
for plotting. MATLAB provides control over the aspect ratio with the axis
command.
For example,
t = 0:pi/20:2*pi;
plot(sin(t),2*cos(t))
grid on
produces a graph with the default aspect ratio. The command
axis square
makes the x- and y-axes equal in length.
2
2
1.5
1.5
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
−1.5
−1.5
−2
−1
−0.5
0
axis normal
0.5
1
−2
−1
−0.5
0
0.5
1
axis square
The square axes has one data unit in x to equal two data units in y. If you want
the x- and y-data units to be equal, use the command
axis equal
This produces an axes that is rectangular in shape, but has equal scaling along
each axis.
2-24
Setting Axis Parameters
2
2
1.5
1.5
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
−1.5
−1.5
−2
−2
−1
0
axis equal
1
2
−2
−1
0
1
axis equal tight
If you want the axes shape to conform to the plotted data, use the tight option
in conjunction with equal.
axis equal tight
2-25
2
Basic Plotting
Figure Windows
MATLAB directs graphics output to a window that is separate from the
command window. In MATLAB this window is referred to as a figure. The
characteristics of this window are controlled by your computer’s windowing
system and MATLAB figure properties.
Graphics functions automatically create new figure windows if none currently
exist. If a figure already exists, MATLAB uses that window. If multiple figures
exist, one is designated as the current figure and is used by MATLAB (this is
generally the last figure used or the last figure you clicked the mouse in).
The figure function creates figure windows. For example,
figure
creates a new window and makes it the current figure. You can make an
existing figure current by clicking on it with the mouse or by passing its handle
(the number indicated in the window title bar), as an argument to figure.
figure(h)
Displaying Multiple Plots per Figure
You can display multiple plots in the same figure window and print them on
the same piece of paper with the subplot function.
subplot(m,n,i) breaks the figure window into an m-by-n matrix of small
subplots and selects the ith subplot for the current plot. The plots are
numbered along the top row of the figure window, then the second row, and so
forth.
For example, the following statements plot data in four different subregions of
the figure window.
t = 0:pi/20:2*pi;
[x,y] = meshgrid(t);
subplot(2,2,1)
plot(sin(t),cos(t))
axis equal
2-26
Figure Windows
subplot(2,2,2)
z = sin(x)+cos(y);
plot(t,z)
axis([0 2*pi −2 2])
subplot(2,2,3)
z = sin(x).*cos(y);
plot(t,z)
axis([0 2*pi −1 1])
subplot(2,2,4)
z = (sin(x).^2)−(cos(y).^2);
plot(t,z)
axis([0 2*pi −1 1])
1
2
0.5
1
0
0
−0.5
−1
−1
−1
0
−2
0
1
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
0
2
4
6
−1
0
2
4
6
2
4
6
2-27
2
Basic Plotting
Each subregion contains its own axes with characteristics you can control
independently of the other subregions. This example uses the axis command
to set limits and change the shape of the subplots.
See the axes, axis, and subplot functions for more information.
Specifying the Target Axes
The current axes is the last one defined by subplot. If you want to access a
previously defined subplot, for example to add a title, you must first make that
axes current.
You can make an axes current in three ways:
• Click on the subplot with the mouse
• Call subplot the m, n, i specifiers
• Call subplot with the handle (identifier) of the axes
For example,
subplot(2,2,2)
title('Top Right Plot')
adds a title to the plot in the upper-right side of the figure.
You can obtain the handles of all the subplot axes with the statement
h = get(gcf,'Children');
MATLAB returns the handles of all the axes, with the most recently created
one first. That is, h(1) is subplot 224, h(2) is subplot 223, h(3) is subplot 222,
and h(4) is subplot 221. For example, to replace subplot 222 with a new plot,
first make it the current axes with
subplot(h(3))
Default Color Scheme
The default figure color scheme produces good contrast and visibility for the
various graphics functions. This scheme defines colors for the window
background, the axis background, the axis lines and labels, the colors of the
lines used for plotting and surface edges, and other properties that affect
appearance.
2-28
Figure Windows
The colordef function enables you to select from predefined color schemes and
to modify colors individually. colordef predefines three color schemes:
• colordef white – sets the axis background color to white, the window
background color to gray, the colormap to jet, surface edge colors to black,
and defines appropriate values for the plotting color order and other
properties.
• colordef black – sets the axis background color to black, the window
background color to dark gray, the colormap to jet, surface edge colors to
black, and defines appropriate values for the plotting color order and other
properties.
• colordef none – set the colors to match that of MATLAB 4. This is basically
a black background with white axis lines and no grid. MATLAB programs
that are based on the MATLAB 4 color scheme may need to call colordef
with the none option to produce the expected results.
You can examine the colordef.m M-file to determine what properties it sets
(enter type colordef at the MATLAB prompt).
2-29
2
Basic Plotting
2-30
3
Formatting Graphs
Overview . . . . . . . . . . . . . . . . . . . . . . 3-2
Adding a Title to a Graph
. . . . . . . . . . . . . . 3-3
Adding a Legend to a Graph . . . . . . . . . . . . . 3-6
Adding Axes Labels to a Graph . . . . . . . . . . . . 3-11
Adding Text Annotations to a Graph . . . . . . . . . 3-15
Adding Arrows and Lines to a Graph . . . . . . . . . 3-27
Adding Plots of Basic Statistics to a Graph
. . . . . . 3-29
3
Formatting Graphs
Overview
When creating presentation graphics, you may want to add labels and
annotations to your graph to help explain your data. MATLAB provides
mechanisms that let you:
• Add a title at the top of an axes
• Add a legend
• Add labels to axes
• Add free-form text annotations anywhere on your graph
• Add arrows and lines anywhere on your graph
• Add plots of basic data statistics, such as the maximum, minimum, and
mean
The following figure shows a graph that uses all of these labels and
annotations. Click on any of the labels and annotations in this figure to get
more information about how to create the label or annotation.
Title
Legend
Text annotation
Plot of
data statistic
Arrow
Axes label
3-2
Adding a Title to a Graph
Adding a Title to a Graph
In MATLAB, a title is a text string at the top of an axes. Titles typically define
the subject of the graph.
Title
There are several ways to add a title to a graph:
• “Using the Title Option on the Insert Menu” on page 3-3
• “Using the Property Editor to Add a Title” on page 3-4
• “Using the title Function” on page 3-5
Note While you can use free-form text annotations to create a title for your
graph, it is not recommended. Titles are anchored to the axes they describe;
text annotations are not. If you move or resize your axes, the title
automatically moves with the axes. Additionally, if you cut a title and then
paste it back into a figure, the title will no longer be anchored to the axes.
Using the Title Option on the Insert Menu
To add a title to a graph using the Insert menu:
3-3
3
Formatting Graphs
1 Click the Insert menu in the Figure window menu bar and choose Title.
MATLAB opens a text entry box at the top of the axes.
Note When you select the Title option, MATLAB enables plot editing mode
automatically.
2 Enter the text of the label.
3 When you are finished entering text, click anywhere in the figure
background to close the text entry box around the title. If you click on
another object in the figure, such as an axes or line, you close the title text
entry box but also automatically select the object you clicked on.
To change the font used in the title to bold, you must edit the title. You can edit
the title as you would any other text object in a graph. See “Editing Text
Annotations” on page 3-22 for more information.
Using the Property Editor to Add a Title
To add a title to a graph using the Property Editor:
1 Start plot editing mode.
2 Double-click on the axes in the graph. This starts the Property Editor. You
can also start the Property Editor by right-clicking on the axes and selecting
Properties from the context menu.
In MATLAB Handle Graphics, titles are a property of axes objects. The
Property Editor displays the set of property panels specific to axes objects.
3 Select the Labels panel and type in the text of your title in the Title text
entry box.
3-4
Adding a Title to a Graph
4 Click Apply.
The title you create is a text object and, as such, you can change the font, font
style, position and many other aspects of its format. To view the properties
associated with a text object, click the Edit button next to the Title text entry
box. For more information about text object properties, see “Editing Text
Annotations” on page 3-22.
Using the title Function
To add a title to a graph at the MATLAB command prompt or from an M-file,
use the title function. The title function lets you specify the value of title
properties at the time you create it.
For example, the following code adds a title to the current axes and sets the
value of the FontWeight property to bold.
title('Lotka-Volterra Predator-Prey Population Model',...
'FontWeight','bold')
To edit a title from the MATLAB command prompt or from an M-file, use the
set function. See “Setting and Querying Object Properties” in the “Handle
Graphics Objects” chapter for more information.
3-5
3
Formatting Graphs
Adding a Legend to a Graph
Legends identify each data set plotted in your graph. In a legend, MATLAB
includes a small sample of the line or marker used to represent each data set
in the graph, in the same color and style as it appears in the graph. MATLAB
also includes a text label to identify each data set.
Legend
This section includes these topics:
• “Using the Legend Option on the Insert Menu” on page 3-7
• “Using the Legend Function” on page 3-7
• “Positioning a Legend” on page 3-8
• “Editing a Legend” on page 3-9
• “Removing a Legend” on page 3-10
Note The legend is implemented as a separate axes overlaying the axes it
describes. The legend axes is not anchored to the main axes. If you resize or
move the main axes, or create new subplots, you may need to reposition the
legend.
3-6
Adding a Legend to a Graph
Using the Legend Option on the Insert Menu
To add a legend to a graph, click on the Insert menu and choose Legend.
MATLAB creates a legend, placing it in the upper right corner of the plot.
Legend
MATLAB creates text labels to identify each data set in the graph, using data1
to identify the first data set, data2 to identify the second data set, and so on.
To learn how to customize a legend, such as changing its position or changing
the text labels, see “Positioning a Legend” on page 3-8 and “Editing a Legend”
on page 3-9.
Using the Legend Function
To add a legend to a graph at the MATLAB command prompt or from an M-file,
use the legend function. You must specify the text labels when you create a
legend using the legend function.
For example, the following code adds a legend to the current axes.
legend('Y1 Predator','Y2 Prey')
The legend function lets you specify many other aspects of the legend, such as
its position. For more information, see the legend function reference
information.
3-7
3
Formatting Graphs
Positioning a Legend
There are two ways to change the position of a legend in a graph, depending on
whether plot editing mode is enabled.
If Plot Editing Mode Is Not Enabled
1 Move the mouse over the legend and press and hold down the left mouse
button. MATLAB changes the cursor to the indicate possible directions of
movement.
2 With the mouse button still pressed, move the legend anywhere in the
graph.
3 Release the mouse button.
If Plot Editing Mode Is Enabled
1 Right-click on the legend. This selects the legend and triggers the display of
the context menu for the legend.
2 Select Unlock Axes Position from the context menu. (The legend is an axes
object.)
Note If the context menu does not include the Unlock Axes Position option,
you probably selected the text labels in the legend or the line objects and not
the legend axes. Every object in a legend is individually selectable. Make sure
you have selected the legend axes.
3 Move the cursor back over the legend axes (it should still be selected) and
press and hold down either mouse button. MATLAB changes the cursor to
indicate possible directions of movement.
4 Move the legend anywhere in the graph.
5 Release the mouse button.
3-8
Adding a Legend to a Graph
Editing a Legend
A legend is implemented as a separate axes object containing one or more line
objects, representing samples of the plots in the graph, and one or more text
objects, representing the labels for each data set plotted in a graph.
Line
objects
Text objects
Axes object
You can edit a legend when plot editing mode is enabled or when it is not
enabled.
Editing a Legend in Plot Editing Mode
When you enable plot editing mode, you can edit any of the objects that make
up a legend as you would any other axes, line, or text object in a graph. For
example, if you double-click on the legend axes, the Property Editor displays
the set of property panels for axes objects. Change the value of an axes property
and click Apply.
If you double-click on a text label in a legend, MATLAB opens a text editing box
around all the text labels in the legend. You can edit any of the text labels in
the legend. To access the properties of these text objects, right-click on a text
label and select Properties from the context-sensitive pop-up menu.
Editing a Legend When Plot Editing Mode Is Not Enabled
When plot editing mode is not enabled, you can still edit the text labels in a
legend.
1 Double-click on a text label in the legend.
MATLAB opens a text edit box around the text label you selected. All the
other text labels are temporarily hidden. You can only edit one text label at
a time.
2 Make changes to the text label and then click anywhere in the figure outside
of the text edit box when you are finished.
MATLAB automatically resizes the legend box to fit long or multiline labels.
3-9
3
Formatting Graphs
Resizing a Legend
To resize a legend:
1 Start plot editing mode.
2 Right-click on its axes and select Unlock Axes Position from the pop-up
menu.
3 Move the cursor back to the legend axes, which is selected, and grab one of
the selection handles. MATLAB changes the cursor to indicate possible
directions.
Note If the text labels extend past the legend axes border, you cannot grab
the selection handles on the right side of the legend axes. Resize the axes from
the left side to fit the new text labels.
4 Drag the selection handle to resize the legend.
Removing a Legend
If you have enabled plot editing mode, you can remove a legend by clicking on
it and choosing the Cut option on the Edit menu. You can also remove a legend
by right-clicking on it and selecting Cut from the context-sensitive pop-up
menu.
If plot editing mode is not enabled, you can remove a legend by selecting the
Legend option on the Insert menu. The Legend options acts as a toggle switch
— selecting it alternately adds or removes a legend.
3-10
Adding Axes Labels to a Graph
Adding Axes Labels to a Graph
In MATLAB, an axes label is a text string aligned with the x-, y-, or z-axis in a
graph. Axes labels can help explain the meaning of the units that each axis
represents.
Axes labels
Note While you can use free-form text annotations to create axes labels, it is
not recommended. Axes labels are anchored to the axes they describe; text
annotations are not. If you move or resize your axes, the labels automatically
move with the axes. Additionally, if you cut a label and then paste it back into
a figure, the label will no longer be anchored to the axes.
To add axes labels to a graph, you can use any of these mechanisms:
• “Using the Label Options on the Insert Menu” on page 3-12
• “Using the Property Editor to Add Axes labels” on page 3-12
• “Using the Label Commands” on page 3-13
3-11
3
Formatting Graphs
Using the Label Options on the Insert Menu
1 Click on the Insert menu and choose the label option that corresponds to the
axes you want to label: X Label, Y Label, or Z Label. MATLAB opens a text
entry box along the axes, or around an existing axes label.
Note MATLAB opens up a horizontal text editing box for the Y- and Z- axes
labels and automatically rotates the label into alignment with the axes when
you finish entering text.
2 Enter the text of the label, or edit the text of an existing label.
3 Click anywhere else in the figure background to close the text entry box
around the label. If you click on another object in the figure, such as an axes
or line, you close the label text entry box but also automatically select the
object you clicked on.
Note After you use the Insert menu to add an axes label, plot edit mode is
enabled in the figure, if it was not already enabled.
Using the Property Editor to Add Axes labels
To add labels to a graph using the Property Editor:
1 Start plot editing mode.
2 Start the Property Editor by either double-clicking on the axes in the graph
or by right-clicking on the axes and selecting Properties from the
context-sensitive pop-up menu.
The Property Editor displays the set of property panels specific to axes
objects.
3 Select the Labels panel. Enter the text of the label in the appropriate text
entry box.
3-12
Adding Axes Labels to a Graph
4 Click Apply.
Using the Label Commands
You can add x-, y-, and z-axis labels using the xlabel, ylabel, and zlabel
commands. For example, these statements label the axes and add a title.
xlabel('t = 0 to 2\pi','FontSize',16)
ylabel('sin(t)','FontSize',16)
title('\it{Value of the Sine from Zero to Two Pi}','FontSize',16)
3-13
3
Formatting Graphs
The Sine of 0 to 2π
1
0.8
0.6
0.4
sin(τ)
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
1
2
3
4
τ = 0 to 2π
5
6
7
The labeling commands automatically position the text string appropriately.
MATLAB interprets the characters immediately following the backslash “\” as
TeX commands. These commands draw symbols such as Greek letters and
arrows. See the text String property for a list of TeX character sequences.
3-14
Adding Text Annotations to a Graph
Adding Text Annotations to a Graph
You can add free-form text annotations anywhere in a MATLAB figure to help
explain your data or bring attention to specific points in your data sets.
Text annotations
If you enable plot editing mode, you can create text annotations by clicking in
an area of the graph or the figure background and entering text. You can also
add text annotations from the command line, using the text or gtext
command.
Using plot editing mode or gtext make it easy to place a text annotation
anywhere in graph. Use the text command when you want to position a text
annotation at a specific point in a data set.
Note Text annotations created using the text or gtext command are
anchored to the axes. Text annotations created in plot edit mode are not. If you
move or resize your axes, you will have to reposition your text annotations.
3-15
3
Formatting Graphs
Creating Text Annotations in Plot Editing Mode
Note Add text annotations after you are finished moving or resizing your
axes. Text annotations created in plot edit mode are not anchored to axes. If
you move or resize an axes, you will have to move the text annotations as well.
To add a text annotation to a graph:
1 Click on the Insert menu and choose the Text option or click the text button
in the figure window toolbar.
Insert Text
MATLAB changes the cursor to a text insertion cursor.
Note After you use insert text, plot edit mode is enabled in the figure, if it
was not already enabled.
2 Position the cursor where you want to add a text annotation in the graph
and click. MATLAB opens a text editing box at that point in the graph.
3 Enter text.
4 Click anywhere in the figure background to close the text entry box. If you
click on another object in the figure, such as an axes or line, you close the
title text entry box but also automatically select the object you clicked on.
Creating Text Annotations with the text or gtext
Command
To create a text annotation using the text function, you must specify the the
text and its location in the graph, using x- and y-coordinates. You specify the
coordinates in the units of the graph.
3-16
Adding Text Annotations to a Graph
For example, the following code creates text annotations at specific points in
the Lotka-Volterra Predator-Prey Population Model graph.
str1(1) = {'Many Predators;'};
str1(2) = {'Prey Population'};
str1(3) = {'Will Decline'};
text(7,220,str1)
str2(1) = {'Few Predators;'};
str2(2) = {'Prey Population'};
str2(3) = {'Will Increase'};
text(5.5,125,str2)
This example also illustrates how to create multi-line text annotations with cell
arrays.
Calculating the Position of Text Annotations
You can also calculate the positions of text annotations in a graph. The
following code adds annotations at three data points on a graph.
text(3*pi/4,sin(3*pi/4),...
'\leftarrowsin(t) = .707',...
'FontSize',16)
text(pi,sin(pi),'\leftarrowsin(t) = 0',...
'FontSize',16)
text(5*pi/4,sin(5*pi/4),'sin(t) = −.707\rightarrow',...
'HorizontalAlignment','right',...
'FontSize',16)
The HorizontalAlignment of the text string 'sin(t) = −.707 \rightarrow'
is set to right to place it on the left side of the point [5*pi/4,sin(5*pi/4)] on
the graph. For more information about aligning text annotations, see “Text
Alignment” on page 3-19.
3-17
3
Formatting Graphs
The Sine of 0 to 2π
1
0.8
←sin(t) = .707
0.6
0.4
sin(τ)
0.2
←sin(t) = 0
0
−0.2
−0.4
−0.6
sin(t) = −.707→
−0.8
−1
0
1
2
3
4
τ = 0 to 2π
5
6
7
You can use text objects to annotate axes at arbitrary locations. MATLAB
locates text in the data units of the axes. For example, suppose you plot the
– αt
function y = Ae
with A = 0.25, α = 0.005, and t = 0 to 900.
t = 0:900;
plot(t,0.25*exp(−0.005*t))
3-18
Adding Text Annotations to a Graph
Ae−αt
0.25
0.2
Amplitude
0.15
0.1
•←0.25e−0.005t at t = 300
0.05
0
0
100
200
300
400
500
Time µsec.
600
700
800
900
To annotate the point where the value of t = 300, calculate the text coordinates
using the function you are plotting.
text(300,.25*exp(−0.005*300),...
'\bullet\leftarrow\fontname{times}0.25{\ite}^{-0.005{\itt}} at {\itt} =
300',...
'FontSize',14)
This statement defines the text Position property as x = 300,
– 0.005 × 300
y = 0.25e
. The default text alignment places this point to the left of
the string and centered vertically with the rectangle defined by the text Extent
property. For information about changing this default text alignment, see the
following section, “Text Alignment.”
Text Alignment
The HorizontalAlignment and the VerticalAlignment properties control the
placement of the text characters with respect to the specified x-, y-, and
3-19
3
Formatting Graphs
z-coordinates. The following diagram illustrates the options for each property
and the corresponding placement of the text.
Text HorizontalAlignment property viewed with the VerticalAlignment
property set to middle (the default).
Left
Center
Right
Text VerticalAlignment property viewed with the HorizontalAlignment
property set to left (the default).
Middle
Top
Baseline
Cap
Bottom
The default alignment is:
• HorizontalAlignment = left
• VerticalAlignment = middle
MATLAB does not place the text String exactly on the specified Position. For
example, the previous section showed a plot with a point annotated with text.
Zooming in on the plot enables you to see the actual positioning of the text.
3-20
Adding Text Annotations to a Graph
Point defined by
text Position
−0.005t
•←0.25e
at t = 300
The small dot is the point specified by the text Position property. The larger
dot is the bullet defined as the first character in the text String property.
Example – Aligning Text
Suppose you want to label the minimum and maximum values in a plot with
text that is anchored to these points and that displays the actual values. This
example uses the plotted data to determine the location of the text and the
values to display on the graph. One column from the peaks matrix generates
the data to plot.
Z = peaks;
h = plot(Z(:,33));
The first step is to find the indices of the minimum and maximum values to
determine the coordinates needed to position the text at these points (get,
find). Then create the string by concatenating the values with a description of
what the values are.
x = get(h,'XData'); % Get the plotted data
y = get(h,'YData');
imin = find(min(y) == y);% Find the index of the min and max
imax = find(max(y) == y);
text(x(imin),y(imin),[' Minimum = ',num2str(y(imin))],...
'VerticalAlignment','middle',...
'HorizontalAlignment','left',...
'FontSize',14)
text(x(imax),y(imax),['Maximum = ',num2str(y(imax))],...
'VerticalAlignment','bottom',...
'HorizontalAlignment','right',...
3-21
3
Formatting Graphs
'FontSize',14)
4
Maximum = 3.254
3
2
1
0
−1
−2
Minimum = −2.7633
−3
0
5
10
15
20
25
30
35
40
45
50
The text function positions the string relative to the point specified by the
coordinates, in accordance with the settings of the alignment properties. For
the minimum value, the string appears to the right of the text position point;
for the maximum value the string appears above and to the left of the text
position point. The text always remains in the plane of the computer screen,
regardless of the view.
Editing Text Annotations
You can edit any of the text labels or annotations in a graph:
1 Start plot edit mode.
2 Double-click on the string. Or right-click on the string and select String
from the context-sensitive pop-up menu.
An editing box appears around the text.
3-22
Adding Text Annotations to a Graph
3 Make any changes to the text.
4 Click anywhere outside of the text edit box to end text editing.
Note To create special characters in text, such as Greek letters or
mathematical symbols, be sure to use TeX sequences – see the text command
string property. If you create special characters by using the Edit Font
Properties dialog box and selecting the Symbol font family, you will not be
able to edit that text object using MATLAB commands.
Including Symbols and Greek Letters in Text Strings
Text objects support a subset of TeX characters that enable you to use symbols
in the title and axis labels. See the text String property for a list of available
TeX characters.
For example,
title('{\itAe}^{−\alpha\itt}sin\beta{\itt} \alpha<<\beta')
xlabel('Time \musec.')
ylabel('Amplitude')
3-23
3
Formatting Graphs
Ae−αtsinβt α<<β
0.25
0.2
0.15
Amplitude
0.1
0.05
0
−0.05
−0.1
−0.15
−0.2
−0.25
0
100
200
300
400
500
Time µsec.
600
700
800
900
1000
The backslash character “\” precedes all TeX character sequences. Looking at
the string defining the title illustrates how to use these characters.
Ae−αtsinβt α<<β
Make the A
and e italics
Superscript using α
symbol and italic t
β symbol
and italic t
β and α symbol
following a space
{\itAe}^{−\alpha{\itt}}sin\beta{\itt} \alpha<<\beta
The text Interpreter property controls the interpretation of TeX characters. If
you set this property to none, MATLAB interprets the special characters
literally.
3-24
Adding Text Annotations to a Graph
Using Variables in Text Strings
Any string variable is a valid specification for the text String property. For
example, each row of the matrix PersonalData contains specific information
about a person (note that all but the longest row is padded with a space so that
each has the same number of columns).
PersonalData = ['Jack Straw
';'489 Main St.';'Wichita KN '];
To display the data, index into the desired row.
text(x1,y1,['Name: ',PersonalData(1,:)])
text(x2,y2,['Address: ',PersonalData(2,:)])
text(x3,y3,['City and State: ',PersonalData(3,:)])
You can specify numeric variables in text strings using the num2str (number
to string) function. For example, if you type on the command line,
x = 21;
['Today is the ',num2str(x),'st day.']
MATLAB concatenates the three separate strings into one.
Today is the 21st day.
Since the result is a valid string, you can specify it as a value for the text String
property.
text(xcoord,ycoord,['Today is the ',num2str(x),'st day.'])
Example - Multiline Text
MATLAB supports multiline text strings using cell arrays. Simply define a
string variable as a cell array with one line per cell. This example defines two
cell arrays, one used for a uicontrol and the other as text.
str1(1) = {'Center each line in the Uicontrol'};
str1(2) = {'Also check out the textwrap function'};
str2(1) = {'Each cell is a quoted string'};
str2(2) = {'You can specify how the string is aligned'};
str2(3) = {'You can use LaTeX symbols like \pi \chi \Xi'};
str2(4) = {'\bfOr use bold \rm\itor italic font\rm'};
str2(5) = {'\fontname{courier}Or even change fonts'};
plot(0:6,sin(0:6))
3-25
3
Formatting Graphs
uicontrol('Style','text','Position',[80 80 250 65],...
'String',str1);
text(5.75,sin(2.5),str2,'HorizontalAlignment','right')
1
Each cell is a quoted string
You can specify how the string is aligned
You can use LaTeX symbols likeπ χ Ξ
Or use bold or italic font
Or even change fonts
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
3-26
1
2
3
4
5
6
Adding Arrows and Lines to a Graph
Adding Arrows and Lines to a Graph
With plot editing mode enabled, you can add arrows and lines anywhere in a
figure window.
Arrows
You can also use arrow characters (TeX characters) to create arrows using the
text command. However, arrows created this way can only point to the left or
right, horizontally. See “Calculating the Position of Text Annotations” on
page 3-17 for an example.
Creating Arrows and Lines in Plot Editing Mode
Note Add arrow and line annotations after you are finished moving or
resizing your axes. Arrows and lines annotations are not anchored to the axes.
If you move or resize the axes, you will have to reposition your arrow and line
annotations as well.
To add an arrow or line annotation to a graph:
1 Click on the Insert menu and choose the Arrow or Line option, or click the
Arrow or Line buttons in the figure window toolbar.
3-27
3
Formatting Graphs
Arrow
Line
MATLAB changes the cursor to a cross-hair style.
2 Position the cursor in the figure where you want to start the line or arrow
and press either mouse button. Hold the button down and move the mouse
to define the length and direction of the line or arrow.
3 Release the mouse button.
Note After you add an arrow or line, plot edit mode is enabled in the figure, if
it was not already enabled.
Editing Arrows and Line Annotations
You can edit the appearance of arrow and line annotations using the Property
Editor.
With plot editing mode enabled, double-click on the arrow or line annotation to
start the Property Editor, if it is not already started. The Property Editor
displays the set of panels specific to arrow or line objects. Use the fields in the
panels to change the style, width, color, and many other characteristics of the
arrow or line annotation object.
3-28
Adding Plots of Basic Statistics to a Graph
Adding Plots of Basic Statistics to a Graph
The MATLAB Data Statistics tool:
• Calculates basic statistics about the central tendency and variability of data
plotted in a graph.
• Plots these statistics in the graph
For example, the following figure includes a plot of the mean of the Predator
y-data.
Plot of Data
Statistic
The following sections provide more information about using the Data
Statistics tool:
• “Example - Plotting the Mean of a Data Set” on page 3-30
• “Formatting Plots of Data Statistics” on page 3-32
• “Statistics Plotted by the Data Statistics Tool” on page 3-32
• “Viewing Statistics for Multiple Plots” on page 3-33
• “Saving Statistics to the MATLAB Workspace” on page 3-34
3-29
3
Formatting Graphs
Example - Plotting the Mean of a Data Set
To add a plot of the mean of a data set to a graph:
1 Plot your data. For example, use these commands to plot historical
population data from the United States census.
load census
plot(cdate,pop,'+')
2 Select the Data Statistics option from the figure window Tools menu.
The Data Statistics tool calculates basic statistics on the x-data and y-data
of the plot in the graph and displays the results in a dialog box.
Select the statistic
you want to plot
by clicking in its
check box.
3 Select the statistic you want to plot in your graph by clicking in the check
box next to the value.
For example, to add a plot of the mean of the population data (y-data) to the
graph, click in the check box next to the value (as shown in the figure). The
Data Statistics tool adds the plot of the mean to the graph.
3-30
Adding Plots of Basic Statistics to a Graph
The Data Statistics
tool adds a legend
automatically.
Plot of the mean of
the population data
Using a Legend with Data Statistics
When you activate the Data Statistics tool, it calculates statistics for the
plotted data and automatically adds a legend to the graph, if the graph doesn’t
already have one.
Initially, the legend only includes entries for the data sets plotted in the graph.
In the legend, each data set is identified by its tag. (A tag is a user-defined text
string that can be associated with any graphics object. For information about
creating tags, see “Identifying Objects in a Graph” on page 1-20.) If there are
data sets in the graph that do not have tags, the Data Statistics tool creates a
label for them, using data 1 to identify the first plot, data 2 to identify the
second plot, and so on.
When you add a plot of one or more statistics to the graph, the Data Statistics
tool adds an entry in the legend for the new plot. The Data Statistics tool
assigns the plotted statistic a descriptive name that identifies it in the legend.
In the example, the plotted statistic has the name y mean in the legend.
3-31
3
Formatting Graphs
Formatting Plots of Data Statistics
The Data Statistics tool uses color and line style to distinguish the plots of
statistics from the other plots in a graph. However, like any other plot in a
graph, you can change these characteristics.
Note Do not edit the format of the plots of data statistics, until you are
finished adding them to a graph. If you edit a plot of data statistics, delete the
plot, and then add it back, any formatting you did to the plotted statistics will
be lost.
To modify the properties of a plotted statistic:
1 Enable plot editing mode in the figure window.
2 Double-click on the plot of the statistic. This starts the MATLAB Property
Editor, which provides access to properties of the line object used to plot the
statistic.
You can also access a subset of these properties by right-clicking on the plot.
This brings up the plot’s context menu, which includes options for specifying
line width, line style, and color.
3 Change the properties of the plot and click Apply.
Statistics Plotted by the Data Statistics Tool
Note You can only use the Data Statistics tool to generate statistics for
two-dimensional data (vectors and matrices).
The following table lists the statistics calculated by the Data Statistics tool.
The table includes the name of the MATLAB function used to calculate the
3-32
Adding Plots of Basic Statistics to a Graph
statistic. For more information about these statistical functions, see the “Basic
Data Analysis Functions” in the “Data Analysis and Statistics” chapter.
Statistic
Description
MATLAB
Function
Maximum
The largest value in the data set
max
Minimum
The smallest value in the data set
min
Mean
The average of all the values in the data
set
mean
Median
The middle value in the data set
median
Range
The interval between the lowest value
and the highest value in the data set.
The Data Statistic tool does not plot the
range statistic.
n/a
Standard
deviation
A measure characterizing the amount
of variation among the values in the
data set
std
Note: The Data Statistics tool uses two
lines to plot the standard deviation in a
graph. The lines represent the
boundaries of one standard deviation on
either side of the mean of the data set.
Automatic Updating of Statistics
If you have the Data Statistics tool displayed and you change the x-data or
y-data of a plot, the Data Statistics tool automatically regenerates the statistics
for that plot.
Viewing Statistics for Multiple Plots
The Data Statistics tool calculates basic statistics for every 2-D plot in a graph,
but displays the statistics for only one plot at time.
To view the statistics for a particular plot in a graph:
3-33
3
Formatting Graphs
1 Click the Statistics for menu in the Data Statistics dialog box.
Lists the data sets on
which the statistics
have been calculated.
This menu lists all the data sets plotted in the graph, identifying each data
set by its tag. (A tag is a user-defined text string that can be associated with
any graphics object.) For plots in the graph that do not have tags, the Data
Statistics tool uses data1 to identify the first plot, data2 to identify the
second plot, and so on.
2 Select a plot from the list. The Data Statistics tool updates the values
displayed in the dialog box.
Saving Statistics to the MATLAB Workspace
To save the statistics generated by the Data Statistics tool to the MATLAB
workspace, follow this procedure:
Note You must repeat this procedure for each plot in a graph containing
multiple plots.
1 Click the Save to Workspace button.
2 In the Save Statistics to Workspace dialog box, specify which sets of
statistics you want to save, x-data or y-data, and specify the names you want
to assign to the variables in which the statistics will be stored.
Specify the set of
statistics you want to
save.
Assign a name to the
variable.
3-34
Adding Plots of Basic Statistics to a Graph
The Data Statistics tool saves each set of statistics in a structure. For example,
if you save the set of statistics on the x-data in the census in the variable
census_dates, the contents of the structure looks like this.
census_dates =
min:
max:
mean:
median:
std:
range:
1790
1990
1890
1890
62.0484
200
3-35
3
Formatting Graphs
3-36
4
Creating Specialized Plots
Introduction . . . . . . . . . . . . . . . . . . . . 4-2
Bar and Area Graphs . . . . . . . . . . . . . . . . 4-3
Pie Charts . . . . . . . . . . . . . . . . . . . . . 4-15
Histograms
. . . . . . . . . . . . . . . . . . . . 4-18
Discrete Data Graphs . . . . . . . . . . . . . . . . 4-23
Direction and Velocity Vector Graphs
Contour Plots
. . . . . . . . 4-32
. . . . . . . . . . . . . . . . . . . 4-38
Interactive Plotting
. . . . . . . . . . . . . . . . 4-49
Animation . . . . . . . . . . . . . . . . . . . . . 4-51
4
Creating Specialized Plots
Introduction
MATLAB supports a variety of graph types that enable you to present
information effectively. The type of graph you select depends, to a large extent,
on the nature of your data. The following list can help you select the
appropriate graph:
• Bar and area graphs are useful to view results over time, comparing results,
and displaying individual contribution to a total amount.
• Pie charts show individual contribution to a total amount.
• Histograms show the distribution of data values.
• Stem and stairstep plots display discrete data.
• Compass, feather, and quiver plots display direction and velocity vectors.
• Contour plots show equivalued regions in data.
• Interactive plotting enable you to select data points to plot with the pointer.
• Animations add an addition data dimension by sequencing plots.
4-2
Bar and Area Graphs
Bar and Area Graphs
Bar and area graphs display vector or matrix data. These types of graphs are
useful for viewing results over a period of time, comparing results from
different datasets, and showing how individual elements contribute to an
aggregate amount. Bar graphs are suitable for displaying discrete data,
whereas area graphs are more suitable for displaying continuous data.
Function
Description
bar
Displays columns of m-by-n matrix as m groups of n vertical
bars
barh
Displays columns of m-by-n matrix as m groups of n
horizontal bars
bar3
Displays columns of m-by-n matrix as m groups of n vertical
3-D bars
bar3h
Displays columns of m-by-n matrix as m groups of n
horizontal 3-D bars
area
Displays vector data as stacked area plots
Types of Bar Graphs
MATLAB has four specialized functions that display bar graphs. These
functions display 2- and 3-D bar graphs, and vertical and horizontal bar
graphs.
Two-Dimensional
Three-Dimensional
Vertical
bar
bar3
Horizontal
barh
bar3h
Grouped Bar Graph
By default, a bar graph represents each element in a matrix as one bar. Bars
in a 2-D bar graph, created by the bar function, are distributed along the x-axis
with each element in a column drawn at a different location. All elements in a
row are clustered around the same location on the x-axis.
4-3
4
Creating Specialized Plots
For example, define Y as a simple matrix and issue the bar statement in its
simplest form.
Y = [5
8
9
5
4
2
7
8
5
3
1
3
6
5
2];
bar(Y)
The bars are clustered together by rows and evenly distributed along the
x-axis.
9
8
7
The first cluster of
bars represents the
first row in Y.
6
5
4
3
Y(1,:) = [5 2 1]
2
1
0
1
2
3
4
5
Detached 3-D Bars
The bar3 function, in its simplest form, draws each element as a separate 3-D
block, with the elements of each column distributed along the y-axis. Bars that
represent elements in the first column of the matrix are centered at 1 along the
x-axis. Bars that represent elements in the last column of the matrix are
centered at size(Y,2) along the x-axis. For example,
bar3(Y)
displays five groups of three bars along the y-axis. Notice that larger bars
obscure Y(1,2) and Y(1,3).
4-4
Bar and Area Graphs
10
Z Axis
8
6
4
The last cluster of
bars represents
the last row in Y.
2
0
1
2
Y(5,:) = [4 3 2]
3
4
3
5
Y Axis
2
1
X Axis
By default, bar3 draws detached bars. The statement bar3(Y,'detach') has
the same effect.
Labeling the Graph. To add axes labels and x tick marks to this bar graph, use the
statements
xlabel('X Axis')
ylabel('Y Axis')
zlabel('Z Axis')
set(gca,'XTick',[1 2 3])
Grouped 3-D Bars
Cluster the bars from each row beside each other by specifying the argument
'group'. For example,
bar3(Y,'group')
groups the bars according to row and distributes the clusters evenly along the
y-axis.
4-5
4
Creating Specialized Plots
9
8
7
Z Axis
6
5
4
3
The last cluster of bars
represents the last row
2
1
0
Y(5,:) = [4 3 2]
1
2
3
4
5
Y Axis
Stacked Bar Graphs to Show Contributing Amounts
Bar graphs can show how elements in the same row of a matrix contribute to
the sum of all elements in the row. These types of bar graphs are referred to as
stacked bar graphs.
Stacked bar graphs display one bar per row of a matrix. The bars are divided
into n segments, where n is the number of columns in the matrix. For vertical
bar graphs, the height of each bar equals the sum of the elements in the row.
Each segment is equal to the value of its respective element.
Redefining Y
Y = [5
8
9
5
4
1
3
6
5
2
2
7
8
5
3];
Create stacked bar graphs using the optional 'stack' argument. For example,
bar(Y,'stack')
grid on
set(gca,'Layer','top') % display gridlines on top of graph
4-6
Bar and Area Graphs
creates a 2-D stacked bar graph, where all elements in a row correspond to the
same x location.
25
20
15
The first stack of
bars represents the
first row in Y.
Y(1,:) = [5 1 2]
10
5
0
1
2
3
4
5
Horizontal Bar Graphs
For horizontal bar graphs, the length of each bar equals the sum of the
elements in the row. The length of each segment is equal to the value of its
respective element.
barh(Y,'stack')
grid on
set(gca,'Layer','top') % Display gridlines on top of graph
4-7
4
Creating Specialized Plots
5
4
3
2
The lower stack
of bars
represents the
first row in Y.
1
0
5
10
15
20
25
Y(1,:) = [5 1 2]
Specifying X-Axis Data
Bar graphs automatically generate x-axis values and label the x-axis tick lines.
You can specify a vector of x values (or y values in the case of horizontal bar
graphs) to label the axes.
For example, given temperature data,
temp = [29 23 27 25 20 23 23 27];
obtained from samples taken every five days during a thirty-five day period,
days = 0:5:35;
you can display a bar graph showing temperature measured along the y-axis
and days along the x-axis using
bar(days,temp)
These statements add labels to the x- and y-axis.
xlabel('Day')
ylabel('Temperature (^{o}C)')
4-8
Bar and Area Graphs
30
25
Temperature (oC)
20
15
10
5
0
0
5
10
15
20
25
30
35
Day
Setting Y-Axis Limits
By default, the y-axis range is from 0 to 30. To focus on the temperature range
from 15 to 30, change the y-axis limits.
set(gca,'YLim',[15 30],'Layer','top')
4-9
4
Creating Specialized Plots
30
Temperature (oC)
25
20
15
0
5
10
15
20
25
30
35
Day
Overlaying Plots on Bar Graphs
You can overlay data on a bar graph by creating another axes in the same
position. This enables you to have an independent y-axis for the overlaid
dataset (in contrast to the hold on statement, which uses the same axes).
For example, consider a bioremediation experiment that breaks down
hazardous waste components into nontoxic materials. The trichloroethylene
(TCE) concentration and temperature data from this experiment are
TCE = [515 420 370 250 135 120 60 20];
temp = [29 23 27 25 20 23 23 27];
This data was obtained from samples taken every five days during a thirty-five
day period.
days = 0:5:35;
Display a bar graph and label the x- and y-axis using the statements
bar(days,temp)
xlabel('Day')
ylabel('Temperature (^{o}C)')
4-10
Bar and Area Graphs
Overlaying a Line Plot on the Bar Graph
To overlay the concentration data on the bar graph, position a second axes at
the same location as the first axes, but first save the handle of the first axes.
h1 = gca;
Create the second axes at the same location before plotting the second dataset.
h2 = axes('Position',get(h1,'Position'));
plot(days,TCE,'LineWidth',3)
To ensure that the second axes does not interfere with the first, locate the
y-axis on the right side of the axes, make the background transparent, and set
the second axes’ x-tick marks to the empty matrix.
set(h2,'YAxisLocation','right','Color','none','XTickLabel',[])
Align the x-axis of both axes and display the grid lines on top of the bars.
set(h2,'XLim',get(h1,'XLim'),'Layer','top')
25
500
20
400
en
nc
300
n
tio
tra
15
10
200
5
100
0
0
5
10
15
20
25
30
35
TCE Concentration (PPM)
600
Co
Temperature (oC)
Bioremediation
30
0
Day
Annotating the Graph. These statements annotate the graph.
text(11,380,'Concentration','Rotation',–55,'FontSize',16)
4-11
4
Creating Specialized Plots
ylabel('TCE Concentration (PPM)')
title('Bioremediation','FontSize',16)
To print the graph, set the current figure’s PaperPositionMode to auto, which
ensures the printed output matches the display.
set(gcf,'PaperPositionMode','auto')
Area Graphs
The area function displays curves generated from a vector or from separate
columns in a matrix. area plots the values in each column of a matrix as a
separate curve and fills the area between the curve and the x-axis.
Area Graphs Showing Contributing Amounts
Area graphs are useful for showing how elements in a vector or matrix
contribute to the sum of all elements at a particular x location. By default, area
accumulates all values from each row in a matrix and creates a curve from
those values.
Using this matrix,
Y = [5
8
9
5
4
1
3
6
5
2
2
7
8
5
3];
the statement,
area(Y)
displays a graph containing three area graphs, one per column.
The height of the area graph is the sum of the elements in each row. Each
successive curve uses the preceding curve as its base.
4-12
Bar and Area Graphs
25
20
15
10
The first row in Y
Y(1,:) = [5 1 2]
5
0
1
2
3
4
5
Displaying the Grid on Top. To display the grid lines in the foreground of the area
graph and display only five grid lines along the x-axis, use the statements
set(gca,'Layer','top')
set(gca,'XTick',1:5)
Comparing Datasets with Area Graphs
Area graphs are useful for comparing different datasets. For example, given a
vector containing sales figures,
sales = [51.6 82.4 90.8 59.1 47.0];
for the five-year period
x = 90:94;
and a vector containing profits figures for the same five-year period
profits = [19.3 34.2 61.4 50.5 29.4];
display both as two separate area graphs within the same axes. Set the color of
the area interior (FaceColor), its edges (EdgeColor), and the width of the edge
lines (LineWidth). See patch for a complete list of properties.
area(x,sales,'FaceColor',[.5 .9 .6],...
4-13
4
Creating Specialized Plots
'EdgeColor','b',...
'LineWidth',2)
hold on
area(x,profits,'FaceColor',[.9 .85 .7],...
'EdgeColor','y',...
'LineWidth',2)
hold off
To annotate the graph, use the statements
set(gca,'XTick',[90:94])
set(gca,'Layer','top')
gtext('\leftarrow Sales')
gtext('Profits')
gtext('Expenses')
xlabel('Years','FontSize',14)
ylabel('Expenses + Profits = Sales in 1,000''s','FontSize',14)
100
Expenses + Profits = Sales in 1,000’s
90
← Sales
80
70
Profits
60
50
40
Expenses
30
20
10
0
90
91
92
Years
4-14
93
94
Pie Charts
Pie Charts
Pie charts display the percentage that each element in a vector or matrix
contributes to the sum of all elements. pie and pie3 create 2-D and 3-D pie
charts.
Example – Pie Chart
Here is an example using the pie function to visualize the contribution that
three products make to total sales. Given a matrix X where each column of X
contains yearly sales figures for a specific product over a five-year period,
X = [19.3
34.2
61.4
50.5
29.4
22.1
70.3
82.9
54.9
36.3
51.6;
82.4;
90.8;
59.1;
47.0];
sum each row in X to calculate total sales for each product over the five-year
period.
x = sum(X);
You can offset the slice of the pie that makes the greatest contribution using
the explode input argument. This argument is a vector of zero and nonzero
values. Nonzero values offset the respective slice from the chart.
First, create a vector containing zeros.
explode = zeros(size(x));
Then find the slice that contributes the most and set the corresponding
explode element to 1.
[c,offset] = max(x);
explode(offset) = 1;
The explode vector contains the elements [0 0 1]. To create the exploded pie
chart, use the statement.
h = pie(x,explode); colormap summer
4-15
4
Creating Specialized Plots
Product X: 25%
Product Z: 42%
Product Y: 34%
Labeling the Graph
The pie chart’s labels are text graphics objects. To modify the text strings and
their positions, first get the objects’ strings and extents. Braces around a
property name ensure that get outputs a cell array, which is important when
working with multiple objects.
textObjs = findobj(h,'Type','text');
oldStr = get(textObjs,{'String'});
val = get(textObjs,{'Extent'});
oldExt = cat(1,val{:});
Create the new strings, then set the text objects’ String properties to the new
strings.
Names = {'Product X: ';'Product Y: ';'Product Z: '};
newStr = strcat(Names,oldStr);
set(textObjs,{'String'},newStr)
Find the difference between the widths of the new and old text strings and
change the values of the Position properties.
val1 = get(textObjs, {'Extent'});
newExt = cat(1, val1{:});
offset = sign(oldExt(:,1)).*(newExt(:,3)–oldExt(:,3))/2;
4-16
Pie Charts
pos = get(textObjs, {'Position'});
textPos = cat(1, pos{:});
textPos(:,1) = textPos(:,1)+offset;
set(textObjs,{'Position'},num2cell(textPos,[3,2]))
Removing a Piece from a Pie Charts
When the sum of the elements in the first input argument is equal to or greater
than 1, pie and pie3 normalize the values. So, given a vector of elements x,
each slice has an area of xi/sum(xi), where xi is an element of x. The normalized
value specifies the fractional part of each pie slice.
When the sum of the elements in the first input argument is less than 1, pie
and pie3 do not normalize the elements of vector x. They draw a partial pie.
For example,
x = [.19 .22 .41];
pie(x)
19%
22%
41%
4-17
4
Creating Specialized Plots
Histograms
MATLAB’s histogram functions show the distribution of data values. The
functions that create histograms are hist and rose.
Function
Description
hist
Displays data in a Cartesian coordinate system
rose
Displays data in a polar coordinate system
The histogram functions count the number of elements within a range and
display each range as a rectangular bin. The height (or length when using
rose) of the bins represents the number of values that fall within each range.
Histograms in Cartesian Coordinate Systems
The hist function shows the distribution of the elements in Y as a histogram
with equally spaced bins between the minimum and maximum values in Y. If
Y is a vector and is the only argument, hist creates up to 10 bins. For example,
yn = randn(10000,1);
hist(yn)
generates 10,000 random numbers and creates a histogram with 10 bins
distributed along the x-axis between the minimum and maximum values of yn.
4-18
Histograms
3000
2500
2000
1500
1000
500
0
−4
−3
−2
−1
0
1
2
3
4
Matrix Input Argument
When Y is a matrix, hist creates a set of bins for each column, displaying each
set in a separate color. The statements
Y = randn(10000,3);
hist(Y)
create a histogram showing 10 bins for each column in Y.
4-19
4
Creating Specialized Plots
3500
3000
2500
2000
1500
1000
500
0
−4
−3
−2
−1
0
1
2
3
4
5
Histograms in Polar Coordinate Systems
A rose plot is a histogram created in a polar coordinate system. For example,
consider samples of the wind direction taken over a 12-hour period.
wdir = [45 90 90 45 360 335 360 270 335 270 335 335];
To display this data using the rose function, convert the data to radians; then
use the data as an argument to the rose function. Increase the LineWidth
property of the line to improve the visibility of the plot (findobj).
wdir = wdir * pi/180;
rose(wdir)
hline = findobj(gca,'Type','line');
set(hline,'LineWidth',1.5)
The plot shows that the wind direction was primarily 335° during the 12-hour
period.
4-20
Histograms
90
4
60
120
3
150
30
2
1
180
0
210
330
240
300
270
Specifying Number of Bins
hist and rose interpret their second argument in one of two ways — as the
locations on the axis or the number of bins. When the second argument is a
vector x, it specifies the locations on the axis and distributes the elements in
length(x) bins. When the second argument is a scalar x, hist and rose
distribute the elements in x bins.
For example, compare the distribution of data created by two MATLAB
functions that generate random numbers. The randn function generates
normally distributed random numbers, whereas the rand function generates
uniformly distributed random numbers.
yn = randn(10000,1);
yu = rand(10000,1);
The first histogram displays the data distribution resulting from the randn
function. The locations on the x-axis and number of bins depend on the vector x.
x = min(yn):.2:max(yn);
subplot(1,2,1)
4-21
4
Creating Specialized Plots
hist(yn,x)
title('Normally Distributed Random Numbers','FontSize',16)
The second histogram displays the data distribution resulting from the rand
function and explicitly creates 25 bins along the x-axis.
subplot(1,2,2)
hist(yu,25)
title('Uniformly Distributed Random Numbers','FontSize',16)
Normally Distributed Random Numbers
Uniformly Distributed Random Numbers
900
450
800
400
700
350
600
300
500
250
400
200
300
150
200
100
100
50
0
−4
−2
0
2
4
0
0
0.2
0.4
0.6
0.8
1
Note You can change the aspect ratio of the histogram plots using the mouse
to resize the figure window. However, before creating hardcopy output, set the
figure’s PaperPositionMode to auto to produce printed output that matches
the display.
set(gcf,'PaperPositionMode','auto')
4-22
Discrete Data Graphs
Discrete Data Graphs
MATLAB has a number of specialized functions that are appropriate for
displaying discrete data. This section describes how to use stem plots and
stairstep plots to display this type of data. (Bar charts, discussed earlier in this
section, are also suitable for displaying discrete data.)
Discrete Data Plotting Commands
Function
Description
stem
Displays a discrete sequence of y-data as stems from x-axis
stem3
Displays a discrete sequence of z-data as stems from
xy-plane
stairs
Displays a discrete sequence of y-data as steps from x-axis
Two–Dimensional Stem Plots
A stem plot displays data as lines (stems) terminated with a marker symbol at
each data value. In a 2-D graph, stems extend from the x-axis.
The stem function displays two-dimensional discrete sequence data. For
– αt
example, evaluating the function y = e cos βt with the values,
alpha = .02; beta = .5; t = 0:4:200;
y = exp(–alpha*t).*sin(beta*t);
yields a vector of discrete values for y at given values of t. A line plot shows the
data points connected with a straight line.
plot(t,y)
4-23
4
Creating Specialized Plots
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
0
20
40
60
80
100
120
140
160
180
200
A stem plot of the same function plots only discrete points on the curve.
stem(t,y)
1
0.8
0.6
Magnitude
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
4-24
0
20
40
60
80
100
120
Time in µsecs
140
160
180
200
Discrete Data Graphs
Add axes labels to the x- and y-axis.
xlabel('Time in \musecs')
ylabel('Magnitude')
If you specify only one argument, the number of samples is equal to the length
of that argument. In this example, the number of samples is a function of t,
which contains 51 elements and determines the length of y.
Customizing the Graph
You can specify the line style, the type of marker, and the color used in the stem
plot. For example, adding the string ':sr' specifies a dotted line (:), a square
marker (s), and a red color (r). The 'fill' argument colors the face of the
marker.
stem(t,y,'−−sr','fill')
1
0.8
0.6
Magnitude
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
0
20
40
60
80
100
120
Time in µsecs
140
160
180
200
Setting the aspect ratio of the x- and y-axis to 2:1 improves the utility of the
graph. You can do this by setting the aspect ratio of the plot box using
pbaspect.
pbaspect([2,1,1])
This is equivalent to setting the PlotBoxApectRatio property directly.
set(gca,'PlotBoxAspectRatio',[2,1,1])
4-25
4
Creating Specialized Plots
See LineSpec for a list of line styles and marker types.
Combining Stem Plots with Line Plots
Sometimes it is useful to display more than one plot simultaneously with a
stem plot to show how you arrived at a result. For example, create a linearly
spaced vector with 60 elements and define two functions, a and b.
x = linspace(0,2*pi,60);
a = sin(x);
b = cos(x);
Create a stem plot showing the linear combination of the two functions.
stem_handles = stem(x,a+b);
Overlaying a and b as line plots helps visualize the functions. Before plotting
the two curves, set hold to on so MATLAB does not clear the stem plot.
hold on
plot_handles = plot(x,a,'− − r',x,b,'− − g');
hold off
Use legend to annotate the graph. The stem and plot handles passed to legend
identify which lines to label. Stem plots are composed of two lines; one draws
the markers and the other draws the vertical stems. To create the legend, use
the first handle returned by stem, which identifies the marker line.
legend_handles = [stem_handles(1);plot_handles];
legend(legend_handles,'a + b','a = sin(x)','b = cos(x)')
Labeling the axes and creating a title finishes the graph.
xlabel('Time in \musecs')
ylabel('Magnitude')
title('Linear Combination of Two Functions')
4-26
Discrete Data Graphs
Linear Combination of Two Functions
1.5
a+b
a = sin(x)
b = cos(x)
1
Magnitude
0.5
0
−0.5
−1
−1.5
0
1
2
3
4
Time in µsecs
5
6
7
Three-Dimensional Stem Plots
stem3 displays 3-D stem plots extending from the xy-plane. With only one
vector argument, MATLAB plots the stems in one row at x = 1 or y = 1,
depending on whether the argument is a column or row vector. stem3 is
intended to display data that you cannot visualize in a 2-D view.
Example – 3-D Stem Plot of an FFT
For example, fast Fourier transforms are calculated at points around the unit
circle on the complex plane. So, it is interesting to visualize the plot around the
unit circle. Calculating the unit circle
th = (0:127)/128*2*pi;
x = cos(th);
y = sin(th);
and the magnitude frequency response of a step function
4-27
4
Creating Specialized Plots
f = abs(fft(ones(10,1),128));
displays the data using a 3-D stem plot, terminating the stems with filled
diamond markers.
stem3(x,y,f','d','fill')
view([−65 30])
Magnitude Frequency Response
10
Amplitude
8
6
4
1
2
0.5
0
1
0
0.5
−0.5
0
−0.5
−1
−1
Real
Imaginary
Label the Graph
Label the graph with the statements
xlabel('Real')
ylabel('Imaginary')
zlabel('Amplitude')
title('Magnitude Frequency Response')
To change the orientation of the view, turn on mouse-based 3-D rotation.
rotate3d on
4-28
Discrete Data Graphs
Example – Combining Stem and Line Plots
Three-dimensional stem plots work well when visualizing discrete functions
that do not output a large number of data points. For example, you can use
– st
stem3 to visualize the Laplace transform basis function, y = e
, for a
particular constant value of s.
t = 0:.1:10;% Time limits
s = 0.1+i;% Spiral rate
y = exp(–s*t);% Compute decaying exponential
Using t as magnitudes that increase with time, create a spiral with increasing
height and draw a curve through the tops of the stems to improve definition.
stem3(real(y),imag(y),t)
hold on
plot3(real(y),imag(y),t,'r')
hold off
view(-39.5,62)
Magnitude
10
5
0
1
0.5
1
0
0.5
0
−0.5
−0.5
Imaginary
−1
−1
Real
Label the Graph
Add axes labels, with the statements
xlabel('Real')
4-29
4
Creating Specialized Plots
ylabel('Imaginary')
zlabel('Magnitude')
Stairstep Plots
Stairstep plots display data as the leading edges of a constant interval (i.e.,
zero-order hold state). This type of plot holds the data at a constant y-value for
all values between x(i) and x(i+1), where i is the index into the x data. This type
of plot is useful for drawing time-history plots of digitally sampled data
systems.
Example – Stairstep Plot of a Function
For example, define a function f that varies over time,
alpha = 0.01;
beta = 0.5;
t = 0:10;
f = exp(−alpha*t).*sin(beta*t);
Use stairs to display the function as a stairstep plot and a linearly
interpolated function.
stairs(t,f)
hold on
plot(t,f,'--*')
hold off
4-30
Discrete Data Graphs
1
0.8
0.6
0.4
0.2
0
Stairstep plot of e−(α*t) sinβ*t
−0.2
−0.4
−0.6
−0.8
−1
0
1
2
3
4
5
6
7
8
9
10
t = 0:10
Annotate the graph and set the axes limits.
label = 'Stairstep plot of e^{–(\alpha*t)} sin\beta*t';
text(0.5,–0.2,label,'FontSize',14)
xlabel('t = 0:10','FontSize',14)
axis([0 10 –1.2 1.2])
4-31
4
Creating Specialized Plots
Direction and Velocity Vector Graphs
Several MATLAB functions display data consisting of direction vectors and
velocity vectors. This section describes these functions.
Vector Plotting Commands
Function
Description
compass
Displays vectors emanating from the origin of a polar plot.
feather
Displays vectors extending from equally spaced points along
a horizontal line.
quiver
Displays 2-D vectors specified by (u,v) components.
quiver3
Displays 3-D vectors specified by (u,v,w) components.
You can define the vectors using one or two arguments. The arguments specify
the x and y components of the vectors relative to the origin.
If you specify two arguments, the first specifies the x components of the vectors
and the second the y components of the vectors. If you specify one argument,
the functions treat the elements as complex numbers. The real parts are the x
components and the imaginary parts are the y components.
Compass Plots
The compass function shows vectors emanating from the origin of a graph. The
function takes Cartesian coordinates and plots them on a circular grid.
Example – Compass Plot of Wind Direction and Speed
This example shows a compass plot indicating the wind direction and strength
during a 12-hour period. Two vectors define the wind direction and strength.
wdir = [45 90 90 45 360 335 360 270 335 270 335 335];
knots = [6 6 8 6 3 9 6 8 9 10 14 12];
Convert the wind direction, given as angles, into radians before converting the
wind direction into Cartesian coordinates.
rdir = wdir * pi/180;
[x,y] = pol2cart(rdir,knots);
compass(x,y)
4-32
Direction and Velocity Vector Graphs
Wind Direction and Strength at
Logan Airport for
Nov. 3 at 1800 through
Nov. 4 at 0600
90
15
60
120
10
30
150
5
180
0
210
330
240
300
270
Create text to annotate the graph.
desc = {'Wind Direction and Strength at',
'Logan Airport for ',
'Nov. 3 at 1800 through',
'Nov. 4 at 0600'};
text(–28,15,desc)
Feather Plots
The feather function shows vectors emanating from a straight line parallel to
the x-axis. For example, create a vector of angles from 90° to 0° and a vector the
same size, with each element equal to 1.
theta = 90:–10:0;
r = ones(size(theta));
Before creating a feather plot, transform the data into Cartesian coordinates
and increase the magnitude of r to make the arrows more distinctive.
[u,v] = pol2cart(theta*pi/180,r*10);
feather(u,v)
axis equal
4-33
4
Creating Specialized Plots
15
10
5
0
−5
−5
0
5
10
15
20
25
Plotting Complex Numbers
If the input argument, Z, is a matrix of complex numbers, feather interprets
the real parts of Z as the x components of the vectors and the imaginary parts
as the y components of the vectors.
t = 0:0.5:10;
s = 0.05+i;
Z = exp(–s*t);
feather(Z)
% Time limits
% Spiral rate
% Compute decaying exponential
1
0.5
0
−0.5
−1
0
4-34
5
10
15
20
25
Direction and Velocity Vector Graphs
Printing the Graph
This particular graph looks better if you change the figure’s aspect ratio by
stretching the figure lengthwise using the mouse. However, to maintain this
shape in the printed output, set the figure’s PaperPositionMode to auto.
set(gcf,'PaperPositionMode','auto')
In this mode, MATLAB prints the figure as it appears on screen.
Two-Dimensional Quiver Plots
The quiver function shows vectors at given points in two-dimensional space.
The vectors are defined by x and y components.
A quiver plot is useful when displayed with another plot. For example, create
10 contours of the peaks function (see the “Contour Plots” section for more
information).
n = –2.0:.2:2.0;
[X,Y,Z] = peaks(n);
contour(X,Y,Z,10)
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
2
4-35
4
Creating Specialized Plots
Now use gradient to create the vector components to use as inputs to quiver.
[U,V] = gradient(Z,.2);
Set hold to on and add the contour plot.
hold on
quiver(X,Y,U,V)
hold off
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
2
Three-Dimensional Quiver Plots
Three-dimensional quiver plots (quiver3) display vectors consisting of (u,v,w)
components at (x,y,z) locations. For example, you can show the path of a
projectile as a function of time,
2
at
z(t) = v z t + -------2
First, assign values to the constants vz and a.
vz = 10;
a = –32;
4-36
% Velocity
% Acceleration
Direction and Velocity Vector Graphs
Then, calculate the height z, as time varies from 0 to 1 in increments of 0.1.
t = 0:.1:1;
z = vz*t + 1/2*a*t.^2;
Calculate the position in the x and y directions.
vx = 2;
x = vx*t;
vy = 3;
y = vy*t;
Compute the components of the velocity vectors and display the vectors using
the 3-D quiver plot.
u = gradient(x);
v = gradient(y);
w = gradient(z);
scale = 0;
quiver3(x,y,z,u,v,w,scale)
view([70 18])
2
0
−2
−4
−6
−8
−10
0
0.5
1
1.5
2
2.5
0
0.5
1
1.5
2
2.5
3
3.5
4-37
4
Creating Specialized Plots
Contour Plots
The contour functions create, display, and label isolines determined by one or
more matrices.
Contour Plotting Commands
Function
Description
clabel
Generates labels using the contour matrix and displays the
labels in the current figure.
contour
Displays 2-D isolines generated from values given by a
matrix Z.
contour3
Displays 3-D isolines generated from values given by a
matrix Z.
contourf
Displays a 2-D contour plot and fills the area between the
isolines with a solid color.
contourc
Low-level function to calculate the contour matrix used by
the other contour functions.
Two other functions also create contours. meshc displays a contour in addition
to a mesh, and surfc displays a contour in addition to a surface.
Creating Simple Contour Plots
contour and contour3 display 2- and 3-D contours, respectively. They require
only one input argument — a matrix interpreted as heights with respect to a
plane. In this case, the contour functions determine the number of contours to
display based on the minimum and maximum data values.
To explicitly set the number of contour levels displayed by the functions, you
specify a second optional argument.
Contour Plot of the Peaks Function
The statements,
[X,Y,Z] = peaks;
contour(X,Y,Z,20)
4-38
Contour Plots
display 20 contours of the peaks function in a 2-D view.
Twenty Contours of the peaks Function
3
2
1
0
−1
−2
−3
−3
−2
−1
0
1
2
3
The statements
[X,Y,Z] = peaks;
contour3(X,Y,Z,20)
h = findobj('Type','patch');
set(h,'LineWidth',2)
title('Twenty Contours of the peaks Function')
display 20 contours of the peaks function in a 3-D view and increase the line
width to 2 points.
4-39
4
Creating Specialized Plots
Twenty Contours of the peaks Function
10
5
0
−5
−10
3
2
3
1
2
0
1
0
−1
−1
−2
−3
−2
−3
Labeling Contours
Each contour level has a value associated with it. clabel uses these values to
display labels for 2-D contour lines. The contour matrix contains the values
clabel uses for the labels. This matrix is returned by contour, contour3, and
contourf and is described in the “Contouring Algorithm” section.
clabel optionally returns the handles of the text objects used as labels. You
can then use these handles to set the properties of the label string.
For example, display 10 contour levels of the peaks function,
Z = peaks;
[C,h] = contour(Z,10);
then label the contours and display a title.
clabel(C,h)
title({'Contour Labeled Using','clabel(C,h)'})
Note that clabel labels only those contour lines that are large enough to have
an inline label inserted.
4-40
Contour Plots
Contour Labeled Using
clabel(C,h)
0.
9
1.42
45
09
96
2.758
4
42
1.
40
9
0.0
99
35
6.7
75 5.41 46
7
8
1.4
−1.2
29
3
2.
7
4.08
0.09964
30
64
2.
75
1.429
8
0.
09
96
4
25
1.
42
9
20
64
99
0.0
4
559
−2.
−1.2
64
10
0.0996
88
0.099
−3.8
3
−2.559
15
23
−1.
5
5
10
15
20
25
30
35
40
45
The 'manual' option enables you to add labels by selecting the contour you
want to label with the mouse.
You can also use this option to label only those contours you select
interactively.
For example,
clabel(C,h,'manual')
displays a crosshair cursor when your cursor is inside the figure. Pressing any
mouse button labels the contour line closest to the center of the crosshair.
Filled Contours
contourf displays a two-dimensional contour plot and fills the areas between
contour lines. Use caxis to control the mapping of contour to color. For
example, this filled contour plot of the peaks data uses caxis to map the fill
colors into the center of the colormap.
Z = peaks;
[C,h] = contourf(Z,10);
caxis([−20 20])
4-41
4
Creating Specialized Plots
title({'Filled Contour Plot Using','contourf(Z,10)'})
Filled Contour Plot Using
contourf(Z,10)
45
40
35
30
25
20
15
10
5
5
10
15
20
25
30
35
40
45
Drawing a Single Contour Line at a Desired Level
The contouring functions permit you to specify the number of contour levels or
the particular contour levels to draw. In the case of contour, the two forms of
the function are contour(Z,n) and contour(Z,v). Z is the data matrix, n is the
number of contour lines, and v is a vector of specific contour levels.
MATLAB does not differentiate between a scalar and a one-element vector. So,
if v is a one-element vector specifying a single contour at that level, contour
interprets it as the number of contour lines, not the contour level.
Consequently, contour(Z,v) behaves in the same manner as contour(Z,n).
To display a single contour line, define v as a two-element vector with both
elements equal to the desired contour level. For example, create a 3-D contour
of the peaks function.
xrange = –3:.125:3;
yrange = xrange;
[X,Y] = meshgrid(xrange,yrange);
4-42
Contour Plots
Z = peaks(X,Y);
contour3(X,Y,Z)
To display only one contour level at Z = 1, define v as [1 1].
v = [1 1]
contour3(X,Y,Z,v)
The Contouring Algorithm
The contourc function calculates the contour matrix for the other contour
functions. It is a low-level function that is not called from the command line.
The contouring algorithm first determines which contour levels to draw. If you
specified the input vector v, the elements of v are the contour level values, and
length(v) determines the number of contour levels generated. If you do not
specify v, the algorithm chooses no more than 20 contour levels that are
divisible by 2 or 5.
The contouring algorithm treats the input matrix Z as a regularly spaced grid,
with each element connected to its nearest neighbors. The algorithm scans this
matrix comparing the values of each block of four neighboring elements (i.e., a
cell) in the matrix to the contour level values. If a contour level falls within a
cell, the algorithm performs a linear interpolation to locate the point at which
the contour crosses the edges of the cell. The algorithm connects these points
to produce a segment of a contour line.
contour, contour3, and contourf return a two-row matrix specifying all the
contour lines. The format of the matrix is
C = [
value1
numv
xdata(1)
ydata(1)
xdata(2)...
ydata(2)...]
The first row of the column that begins each definition of a contour line
contains the value of the contour, as specified by v and used by clabel. Beneath
that value is the number of (x,y) vertices in the contour line. Remaining
4-43
4
Creating Specialized Plots
columns contain the data for the (x,y) pairs. For example, the contour matrix
calculated by C = contour(peaks(3)) is
Three vertices at
v = –0.2
Three vertices at
v=0
Five vertices at
v = 0.8
Columns 1 through 7
−0.2000
1.8165
2.0000
3.0000
1.0000
1.0367
2.1835
1.0000
0
3.0000
1.0003
1.0000
2.0000
1.1998
Columns 8 through 14
3.0000
0
1.0000
1.0002
3.0000
2.9991
1.0359
2.0000
1.0000
1.0018
0.2000
5.0000
1.6669
3.0000
Columns 15 through 21
1.2324
2.0000
2.8240
2.0000
1.3629
2.0000
2.3331
3.0000
0.4000
5.0000
2.0000
2.8530
2.6130
2.0000
Columns 22 through 28
2.0000
1.4290
2.0000
1.5261
2.0000
2.8530
0.6000
5.0000
2.0000
2.5594
2.4020
2.0000
2.0000
1.6892
Columns 29 through 35
1.6255
2.0000
0.8000
2.0000
2.5594
5.0000
2.0000
2.2657
2.1910
2.0000
2.0000
1.8524
1.8221
2.0000
Column 36
2.0000
2.2657
The circled values begin each definition of a contour line.
Changing the Offset of a Contour
The surfc and meshc functions display contours beneath a surface or a mesh
plot. These functions draw the contour plot at the axes’ minimum z-axis limit.
To specify your own offset, you must change the ZData values of the contour
lines. First, save the handles of the graphics objects created by meshc or surfc.
h = meshc(peaks(20));
The first handle belongs to the mesh or surface. The remaining handles belong
to the contours you want to change. To raise the contour plane, add 2 to the z
coordinate of each contour line.
for i = 2:length(h);
4-44
Contour Plots
newz = get(h(i),'Zdata') + 2;
set(h(i),'Zdata',newz)
end
Displaying Contours in Polar Coordinates
You can contour data defined in the polar coordinate system. As an example,
set up a grid in polar coordinates and convert the coordinates to Cartesian
coordinates,
[th,r] = meshgrid((0:5:360)*pi/180,0:.05:1);
[X,Y] = pol2cart(th,r);
Then, generate the complex matrix Z on the interior of the unit circle,
Z = X+i*Y;
X, Y, and Z are points inside the circle.
4
Create and display a surface of the function 4 Z – 1 .
f = (Z.^4–1).^(1/4);
surf(X,Y,abs(f))
Display the unit circle beneath the surface using the statements
hold on
surf(X,Y,zeros(size(X)))
hold off
4-45
4
Creating Specialized Plots
1.2
1
abs(f)
0.8
0.6
0.4
0.2
0
1
1
0.5
0.5
0
0
−0.5
Imaginary
−0.5
−1
−1
Real
Labeling the Graph
These statements add labels.
xlabel('Real','FontSize',14);
ylabel('Imaginary','FontSize',14);
zlabel('abs(f)','FontSize',14);
Contours in Cartesian Coordinates
These statements display a contour of the surface in Cartesian coordinates and
label the x- and y-axis.
contour(X,Y,abs(f),30)
axis equal
xlabel('Real','FontSize',14);
ylabel('Imaginary','FontSize',14);
4-46
Contour Plots
1
0.8
0.6
Imaginary
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−1
−0.5
0
0.5
1
Real
Contours on a Polar Axis
You can also display the contour within a polar axes. Create a polar axes using
the polar function, and then delete the line specified with polar.
h = polar([0 2*pi], [0 1]);
delete(h)
With hold on, display the contour on the polar grid.
hold on
contour(X,Y,abs(f),30)
4-47
4
Creating Specialized Plots
90
1
120
60
0.8
0.6
150
30
0.4
0.2
180
0
330
210
300
240
270
4-48
Interactive Plotting
Interactive Plotting
The ginput function enables you to use the mouse or the arrow keys to select
points to plot. ginput returns the coordinates of the pointer’s position; either
the current position or the position when a mouse button or key is pressed. See
the ginput function for more information.
Example – Selecting Plotting Points from the Screen
This example illustrates the use of ginput with the spline function to create a
curve by interpolating in two dimensions.
First, select a sequence of points, [x,y], in the plane with ginput. Then pass
two, one-dimensional splines through the points, evaluating them with a
spacing 1/10 of the original spacing.
axis([0 10 0 10])
hold on
% Initially, the list of points is empty.
xy = [];
n = 0;
% Loop, picking up the points.
disp('Left mouse button picks points.')
disp('Right mouse button picks last point.')
but = 1;
while but == 1
[xi,yi,but] = ginput(1);
plot(xi,yi,'ro')
n = n+1;
xy(:,n) = [xi;yi];
end
% Interpolate with a spline curve and finer spacing.
t = 1:n;
ts = 1: 0.1: n;
xys = spline(t,xy,ts);
% Plot the interpolated curve.
plot(xys(1,:),xys(2,:),'b-');
hold off
This plot shows some typical output.
4-49
4
Creating Specialized Plots
10
4
o
9
5
8
o
3
o
7
6
6
o
7
o
8
o
5
2
4
o
9
o
3
10
11
2
o
o
1
1
o
0
4-50
0
1
2
3
4
5
6
7
8
9
10
Animation
Animation
You can create animated sequences with MATLAB in two different ways:
• Save a number of different pictures and then play them back as a movie.
• Continually erase and then redraw the objects on the screen, making
incremental changes with each redraw.
Movies are better suited to situations where each frame is fairly complex and
cannot be redrawn rapidly. You create each movie frame in advance so the
original drawing time is not important during playback, which is just a matter
of blitting the frame to the screen. A movie is not rendered in real-time; it is
simply a playback of previously rendered frames.
The second technique, drawing, erasing, and then redrawing, makes use of
different drawing modes supported by MATLAB. These modes allow faster
redrawing at the expense of some rendering accuracy, so you must consider
which mode to select.
This section provides an example of each technique. To see more sophisticated
demonstrations of these features, type demo at the MATLAB prompt and
explore the animation demonstrations.
Movies
You can save any sequence of graphs and then play the sequence back in a
short movie. There are two steps to this process:
• Use getframe to generate each movie frame.
• Use movie to run the movie a specified number of times at the specified rate.
Typically, you use getframe in a for loop to assemble the array of movie
frames. getframe returns a structure having the following fields:
• cdata – image data in a uint8 matrix. The matrix has dimensions of
height-by-width on indexed-color systems and height-by-width-by-3 on
truecolor systems.
• colormap – the colormap in an n-by-3 matrix, where n is the number of
colors. On truecolor systems, the colormap field is empty.
See image for more information on images.
4-51
4
Creating Specialized Plots
Example – Visualizing an FFT as a Movie
This example illustrates the use of movies to visualize the quantity
fft(eye(n)), which is a complex n-by-n matrix whose elements are various
powers of the nth root of unity, exp(i*2*pi/n).
Creating the Movie
Create the movie in a for loop calling getframe to capture the graph. Since the
plot command resets the axes properties, call axis equal within the loop
before getframe.
for k = 1:16
plot(fft(eye(k+16)))
axis equal
M(k) = getframe;
end
Running the Movie
After generating the movie, you can play it back any number of times. To play
it back 30 times, type
movie(M,30)
You can readily generate and smoothly play back movies with a few dozen
frames on most computers. Longer movies require large amounts of primary
memory or a very effective virtual memory system.
Movies that Include the Entire Figure
If you want to capture the contents of the entire figure window (for example, to
include GUI components in the movie), specify the figure’s handle as an
argument to the getframe command. For example, suppose you want to add a
slider to indicate the value of k in the previous example.
h = uicontrol('style','slider','position',...
[10 50 20 300],'Min',1,'Max',16,'Value',1)
for k = 1:16
plot(fft(eye(k+16)))
axis equal
set(h,'Value',k)
M(k) = getframe(gcf);
end
4-52
Animation
In this example, the movie frame contains the entire figure. To play so that it
looks like the original figure, make the playback axes fill the figure window.
clf
axes('Position’,[0 0 1 1])
movie(M,30)
Erase Modes
You can select the method MATLAB uses to redraw graphics objects. One event
that causes MATLAB to redraw an object is changing the properties of that
object. You can take advantage of this behavior to create animated sequences.
A typical scenario is to draw a graphics object, then change its position by
respecifying the x-, y,- and z-coordinate data by a small amount with each pass
through a loop.
You can create different effects by selecting different erase modes. This section
illustrates how to use the three modes that are useful for dynamic redrawing:
• none – MATLAB does not erase the objects when it is moved.
• background – MATLAB erases the object by redrawing it in the background
color. This mode erases the object and anything below it (such as grid lines).
• xor – This mode erases only the object and is usually used for animation.
All three modes are faster (albeit less accurate) than the normal mode used by
MATLAB.
Example – Animating with Erase Modes
It is often interesting and informative to see 3-D trajectories develop in time.
This example involves chaotic motion described by a nonlinear differential
equation known as the Lorenz strange attractor. It can be written
dy
in the form ------ = Ay
dt
with a vector valued function y(t) and a matrix A, which depends upon y.
8
– --0 y(2)
3
A(y) =
0 – 10 10
– y ( 2 ) 28 – 1
4-53
4
Creating Specialized Plots
The solution orbits about two different attractive points without settling into a
steady orbit about either. This example approximates the solution with the
simplest possible numerical method – Euler’s method with fixed step size.The
result is not very accurate, but it has the same qualitative behavior as other
methods.
[ −8/3 0 0; 0 −10 10; 0 28 −1 ];
[35 −10 −7]’;
0.01;
plot3(y(1),y(2),y(3),'.', ...
'EraseMode','none','MarkerSize',5); % Set EraseMode to none
axis([0 50 -25 25 -25 25])
hold on
for i=1:4000
A(1,3) = y(2);
A(3,1) = −y(2);
ydot = A*y;
y = y + h*ydot;
% Change coordinates
set(p,'XData',y(1),'YData',y(2),'ZData',y(3))
drawnow
i=i+1;
end
A
y
h
p
=
=
=
=
The plot3 statement sets EraseMode to none, indicating that the points already
plotted should not be erased when the plot is redrawn. In addition, the handle
of the plot object is saved. Within the for loop, a set statement references the
plot object and changes its internally stored coordinates for the new location.
While this manual cannot show the dynamically evolving output, this picture
shows a snapshot.
4-54
Animation
20
10
0
−10
−20
20
50
10
40
0
30
−10
20
−20
10
0
Note that, as far as MATLAB is concerned, the graph created by this example
contains only one dot. What you see on the screen are remnants of previous
plots that MATLAB has been instructed not to erase. The only way to print this
graph from MATLAB is with a screen capture. You can use the capture
command to generate a MATLAB image of the figure window contents.
Background Erase Mode. To see the effect of EraseMode background, add these
statements to the previous program.
p = plot3(y(1),y(2),y(3),'square', ...
'EraseMode','background','MarkerSize',10,...
'MarkerEdgeColor',[1 .7 .7],'MarkerFaceColor',[1 .7 .7]);
for i=1:4000
A(1,3) = y(2);
A(3,1) = -y(2);
ydot = A*y;
y = y + h*ydot;
set(p,'XData',y(1),'YData',y(2),'ZData',y(3))
drawnow
i=i+1;
4-55
4
Creating Specialized Plots
end
hold off
Since hold is still on, this code erases the previously created graph by setting
the EraseMode property to background and changing the marker to a “pink
eraser” (a square marker colored pink).
Xor Erase Mode. If you change the EraseMode of the first plot3 statement from
none to xor, you will see a moving dot (Marker '.') only. Xor mode is used to
create animations where you do not want to leave remnants of previous
graphics on the screen.
Additional Examples
The MATLAB demo, lorenz, provides a more accurate numerical
approximation, and a more elaborate display of Lorenz strange attractor
example. Other MATLAB demos illustrate animation techniques.
4-56
5
Displaying Bit-Mapped
Images
Overview
. . . . . . . . . . . . . . . . . . . . . 5-2
Images in MATLAB . . . . . . . . . . . . . . . . . 5-4
Image Types . . . . . . . . . . . . . . . . . . . . 5-6
Working with 8-Bit and 16-Bit Images
. . . . . . . . 5-11
Reading, Writing, and Querying Graphics Image Files . 5-15
Displaying Graphics Images . . . . . . . . . . . . . 5-18
The Image Object and Its Properties . . . . . . . . . 5-23
Printing Images
. . . . . . . . . . . . . . . . . . 5-28
Converting the Data or Graphic Type of Images . . . . 5-29
5
Displaying Bit-Mapped Images
Overview
MATLAB provides commands for reading, writing, and displaying several
types of graphics file formats for images. As with MATLAB-generated images,
once a graphics file format image is displayed, it becomes a Handle Graphics
image object. MATLAB supports the following graphics file formats:
• BMP (Microsoft Windows Bitmap)
• HDF (Hierarchical Data Format)
• JPEG (Joint Photographic Experts Group)
• PCX (Paintbrush)
• PNG (Portable Network Graphics)
• TIFF (Tagged Image File Format)
• XWD (X Window Dump)
For information concerning the bit depths and image types supported for these
formats, see imread and imwrite.
MATLAB supports three different numeric classes for image display:
double-precision floating-point (double), 16-bit unsigned integer (uint16), and
8-bit unsigned integer (uint8). The image display commands interpret data
values differently depending on the numeric class the data is stored in.
This chapter discusses the different data and image types you can use, and
includes details on how to: read, write, work with, and display graphics images;
how to alter the display properties and aspect ratio of an image during display;
how to print an image; and how to convert the data type or graphics format of
an image.
This table lists the functions discussed in this chapter.
5-2
Function
Purpose
Function Group
axis
Plot axis scaling and appearance
Display
image
Display image (create image object)
Display
imagesc
Scale data and display as image
Display
imread
Read image from graphics file
File I/O
Overview
Function
Purpose
Function Group
imwrite
Write image to graphics file
File I/O
imfinfo
Get image information from graphics file
Utility
ind2rgb
Convert indexed image to RGB image
Utility
5-3
5
Displaying Bit-Mapped Images
Images in MATLAB
The basic data structure in MATLAB is the array, an ordered set of real or
complex elements. This object is naturally suited to the representation of
images, real-valued, ordered sets of color or intensity data. (MATLAB does not
support complex-valued images.)
MATLAB stores most images as two-dimensional arrays (i.e., matrices), in
which each element of the matrix corresponds to a single pixel in the displayed
image. For example, an image composed of 200 rows and 300 columns of
different colored dots would be stored in MATLAB as a 200-by-300 matrix.
Some images, such as RGB, require a three-dimensional array, where the first
plane in the 3rd dimension represents the red pixel intensities, the second
plane represents the green pixel intensities, and the third plane represents the
blue pixel intensities.
This convention makes working with graphics file format images in MATLAB
similar to working with any other type of matrix data. For example, you can
select a single pixel from an image matrix using normal matrix subscripting.
I(2,15)
This command returns the value of the pixel at row 2, column 15 of the image I.
Bit Depth Support
MATLAB supports reading the most commonly used bit depths (bits per pixel)
of any of the supported graphics file formats. When the data is in memory, it
can be stored as uint8, uint16, or double. For details on which bit depths are
appropriate for each supported format, see imread and imwrite.
Data Types
This section introduces you to the different data types that MATLAB uses to
store images. Details on the inner workings of the storage for 8- and 16-bit
images are included in “Working with 8-Bit and 16-Bit Images”.
By default, MATLAB stores most data in arrays of class double. The data in
these arrays is stored as double precision (64-bit) floating-point numbers. All
of MATLAB’s functions and capabilities work with these arrays.
For images stored in one of the graphics file formats supported by MATLAB,
however, this data representation is not always ideal. The number of pixels in
5-4
Images in MATLAB
such an image may be very large; for example, a 1000-by-1000 image has a
million pixels. Since each pixel is represented by at least one array element,
this image would require about 8 megabytes of memory if it were stored as
class double.
To reduce memory requirements, MATLAB supports storing image data in
arrays of class uint8 and uint16. The data in these arrays is stored as 8-bit or
16-bit unsigned integers. These arrays require one-eighth or one-fourth as
much memory as data in double arrays.
5-5
5
Displaying Bit-Mapped Images
Image Types
In MATLAB, an image consists of a data matrix and possibly a colormap
matrix. Three basic image types are used in MATLAB, each differing in the
way that the data matrix elements are interpreted:
• Indexed images
• Intensity (or grayscale) images
• RGB (or truecolor) images
This section discusses how MATLAB represents each of these image types.
Indexed Images
An indexed image consists of a data matrix, X, and a colormap matrix, map. map
is an m-by-3 array of class double containing floating-point values in the range
[0, 1]. Each row of map specifies the red, green, and blue components of a single
color. An indexed image uses “direct mapping” of pixel values to colormap
values. The color of each image pixel is determined by using the corresponding
value of X as an index into map. The value 1 points to the first row in map, the
value 2 points to the second row, and so on. You can display an indexed image
with the statements
image(X); colormap(map)
A colormap is often stored with an indexed image and is automatically loaded
with the image when you use the imread function. However, you are not limited
to using the default colormap—you can use any colormap that you choose. The
description for the property CDataMapping describes how to alter the type of
mapping used.
The next figure illustrates the structure of an indexed image. The pixels in the
image are represented by integers, which are pointers (indices) to color values
stored in the colormap.
5-6
Image Types
75 10 12 21 40 53 53
75 14 17 21 21 53 53
75
8
5
8 10 30 15
51 15 18 31 31 18 16
56 31 18 31 31 31 31
0
0.0627
0.2902
0
0.2902
0.3882
0.4510
0.2588
0
0.0627
0.0314
0
0.0627
0.0314
0.0627
0.1608
.
.
.
0
0.0314
0
1.0000
0.0627
0.0941
0
0.0627
The relationship between the values in the image matrix and the colormap
depends on the class of the image matrix. If the image matrix is 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. If the image matrix is of class uint8 or uint16, 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 offset is also used in graphics file formats, to
maximize the number of colors that can be supported. In the image above, the
image matrix is of class double. Because there is no offset, the value 5 points
to the fifth row of the colormap.
Intensity Images
An intensity image is a data matrix, I, whose values represent intensities
within some range. MATLAB stores an intensity image as a single matrix, with
each element of the matrix corresponding to one image pixel. The matrix can
be of class double, uint8, or uint16. While intensity images are rarely saved
with a colormap, MATLAB uses a colormap to display them. In essence,
MATLAB handles intensity images as indexed images.
This figure depicts an intensity image of class double.
5-7
5
Displaying Bit-Mapped Images
0.5342
0.5342
0.5342
0.4308
0.4510
0.2051
0.2251
0.1789
0.2483
0.3344
0.2157
0.2563
0.1307
0.2624
0.2624
0.2826
0.2826
0.1789
0.3344
0.3344
0.3822
0.2826
0.2051
0.3344
0.3344
0.4391
0.4391
0.3256
0.2624
0.3344
0.4391
0.4391
0.2483
0.2549
0.3344
To display an intensity image, use the imagesc (“image scale”) function, which
enables you to set the range of intensity values. imagesc scales the image data
to use the full colormap. Use the two-input form of imagesc to display an
intensity image. For example,
imagesc(I,[0 1]); colormap(gray);
The second input argument to imagesc specifies the desired intensity range.
The function imagesc displays I by mapping the first value in the range
(usually 0) to the first colormap entry, and the second value (usually 1) to the
last colormap entry. Values in between are linearly distributed throughout the
remaining colormap colors.
Although it is conventional to display intensity images using a grayscale
colormap, it is possible to use other colormaps. For example, the following
statements display the intensity image I in shades of blue and green.
imagesc(I,[0 1]); colormap(winter);
To display a matrix A with an arbitrary range of values as an intensity image,
use the single-argument form of imagesc. With one input argument, imagesc
maps the minimum value of the data matrix to the first colormap entry, and
5-8
Image Types
maps the maximum value to the last colormap entry. For example, these two
lines are equivalent.
imagesc(A); colormap(gray)
imagesc(A,[min(A(:)) max(A(:))]); colormap(gray)
RGB (Truecolor) Images
An RGB image, sometimes referred to as a “truecolor” image, is stored in
MATLAB as an m-by-n-by-3 data array that defines red, green, and blue color
components for each individual pixel. RGB images do not use a palette. The
color of each pixel is determined by the combination of the red, green, and blue
intensities stored in each color plane at the pixel’s location. Graphics file
formats store RGB images as 24-bit images, where the red, green, and blue
components are 8 bits each. This yields a potential of 16 million colors. The
precision with which a real-life image can be replicated has led to the nickname
“truecolor image”.
An RGB MATLAB array can be of class double, uint8, or uint16. In an RGB
array of class double, each color component is a value between 0 and 1. A pixel
whose color components are (0,0,0) displays as black, and a pixel whose color
components are (1,1,1) displays as white. The three color components for each
pixel are stored along the third dimension of the data array. For example, the
red, green, and blue color components of the pixel (10,5) are stored in
RGB(10,5,1), RGB(10,5,2), and RGB(10,5,3), respectively.
To display the truecolor image RGB, use the image function. For example,
image(RGB)
If MATLAB is running on a computer that does not have hardware support for
truecolor image display, MATLAB uses color approximation and dithering to
display an approximation of the image. See “Dithering Truecolor on Indexed
Color Systems” for more information.
The next figure shows an RGB image of class double.
5-9
5
Displaying Bit-Mapped Images
0.5804 0.2235 0.1294 0.2902
Blue 0.4196 0.4824 0.4824
0.5804 0.2902 0.0627 0.2902 0.2902 0.4824 0.4824
0.5804 0.0627 0.0627 0.0627 0.2235 0.2588 0.2588
0.5176
0.1922
0.0627
0.1294
0.1922
0.2588
0.2588
0.5176
0.2588
0.0627
0.0941
0.0941
0.0627
0.0627
Green
0.5176
0.1294
0.1608
0.1294
0.1294
0.2588
0.2588
0.4510
0.0941
0.0627
0.0941
0.0941
0.0941
0.0941
0.5176 0.1608 0.0627 0.1608 0.1922 0.2588 0.2588
0.4196
0.2588
0.3529
0.4196
0.4196
0.3529
0.2902
0.5490
0.2235
0.5490
0.5804
0.7412
0.7765
0.7765
Red
0.4510
0.4196
0.3529
0.4196
0.4196
0.4196
0.4196
0.5490
0.3882
0.5176
0.5804
0.5804
0.7765
0.7765
0.5490 0.2588 0.2902 0.2588 0.2235 0.4824 0.2235
0.4196 0.2235 0.1608 0.2588 0.2588 0.1608 0.2588
0.4510 0.2588 0.1608 0.2588 0.2588 0.2588 0.2588
To determine the color of the pixel at (2,3), you would look at the RGB triplet
stored in (2,3,1:3). Suppose (2,3,1) contains the value 0.5176, (2,3,2) contains
0.1608, and (2,3,3) contains 0.0627. The color for the pixel at (2,3) is
0.5176 0.1608 0.0627
5-10
Working with 8-Bit and 16-Bit Images
Working with 8-Bit and 16-Bit Images
MATLAB usually works with double-precision (64-bit) floating-point numbers.
However, to reduce memory requirements for working with images, MATLAB
provides limited support for storing images as 8-bit or 16-bit unsigned integers
by using the numeric classes uint8 or uint16, respectively. An image whose
data matrix has class uint8 is called an 8-bit image; an image whose data
matrix has class uint16 is called a 16-bit image.
The image function can display 8- or 16-bit images directly without converting
them to double precision. However, image interprets matrix values slightly
differently when the image matrix is uint8 or uint16. The specific
interpretation depends on the image type.
8-Bit and 16-Bit Indexed Images
If the class of X is uint8 or uint16, its values are offset by one before being used
as colormap indices. The value 0 points to the first row of the colormap, the
value 1 points to the second row, and so on. The image command automatically
supplies the proper offset, so the display method is the same whether X is
double, uint8, or uint16.
image(X); colormap(map);
The colormap index offset for uint8 and uint16 data is intended to support
standard graphics file formats, which typically store image data in indexed
form with a 256-entry colormap. The offset allows you to manipulate and
display images of this form in MATLAB using the more memory-efficient uint8
and uint16 arrays.
Because of the offset, you must add 1 to convert a uint8 or uint16 indexed
image to double. For example,
X64 = double(X8) + 1;
or
X64 = double(X16) + 1;
Conversely, subtract 1 to convert a double indexed image to uint8 or uint16.
X8 = uint8(X64 – 1);
or
X16 = uint16(X64 – 1);
5-11
5
Displaying Bit-Mapped Images
The order of operations must be as shown, because most of MATLAB’s
mathematical operations cannot be performed on uint8 and uint16 arrays.
8-Bit and 16-Bit Intensity Images
Whereas the range of double image arrays is usually [0, 1], the range of 8-bit
intensity images is usually [0, 255] and the range of 16-bit intensity images is
usually [0, 65535]. Use the following command to display an 8-bit intensity
image with a gray scale colormap.
imagesc(I,[0 255]); colormap(gray);
To convert an intensity image from double to uint16, first multiply by 65535.
I16 = uint16(round(I64*65535));
Conversely, divide by 65535 after converting a uint16 intensity image to
double.
I64 = double(I16)/65535;
8-Bit and 16-Bit RGB Images
The color components of an 8-bit RGB image are integers in the range [0, 255]
rather than floating-point values in the range [0, 1]. A pixel whose color
components are (255,255,255) displays as white. The image command displays
an RGB image correctly whether its class is double, uint8, or unit16.
image(RGB);
To convert an RGB image from double to uint8, first multiply by 255.
RGB8 = uint8(round(RGB64*255));
Conversely, divide by 255 after converting a uint8 RGB image to double.
RGB64 = double(RGB8)/255
To convert an RGB image from double to uint16, first multiply by 65535.
RGB16 = uint16(round(RGB64*65535));
Conversely, divide by 65535 after converting a uint16 RGB image to double.
RGB64 = double(RGB16)/65535;
5-12
Working with 8-Bit and 16-Bit Images
Mathematical Operations Support for uint8 and
uint16
The following MATLAB mathematical operations support uint8 and uint16
data: conv2,convn,fft2,fftn,sum. In these cases, the output is always
double.
If you attempt to perform an unsupported operation on one of these arrays, you
will receive an error. For example,
BW3 = BW1 + BW2
??? Function '+' not defined for variables of class 'uint8'.
Most of the functions in the Image Processing Toolbox accept uint8 and uint16
input. If you plan to do sophisticated image processing on uint8 or uint16 data,
you should consider adding the Image Processing Toolbox to your MATLAB
computing environment.
Other 8-Bit and 16-Bit Array Support
MATLAB supports several other operations on uint8 and uint16 arrays,
including:
• Reshaping, reordering, and concatenating arrays using the functions
reshape, cat, permute, and the [] and ' operators
• Saving and loading uint8 and uint16 arrays in MAT-files using save and
load. (Remember that if you are loading or saving a graphics file format
image, you must use the commands imread and imwrite, instead.)
• Locating the indices of nonzero elements in uint8 and uint16 arrays using
find. However, the returned array is always of class double.
• Relational operators
5-13
5
Displaying Bit-Mapped Images
Summary of Image Types and Numeric Classes
This table summarizes the way MATLAB interprets data matrix elements as
pixel colors, depending on the image type and data class.
Image Type
double Data
uint8 or uint16 Data
Indexed
Image is an m-by-n array of
integers in the range [1, p].
Image is an m-by-n array of
integers in the range
[0, p – 1].
Colormap is a p-by-3 array
of floating-point values in
the range [0, 1].
Intensity
Image is an m-by-n array of
floating-point values that
are linearly scaled by
MATLAB to produce
colormap indices. The
typical range of values is [0,
1].
Colormap is a p-by-3 array
of floating-point values in
the range [0, 1] and is
typically grayscale.
RGB
(Truecolor)
5-14
Image is an m-by-n-by-3
array of floating-point
values in the range [0, 1].
Colormap is a p-by-3 array
of floating-point values in
the range [0, 1].
Image is an m-by-n array of
integers that are linearly
scaled by MATLAB to
produce colormap indices.
The typical range of values
is [0, 255] or [0, 65535].
Colormap is a p-by-3 array
of floating-point values in
the range [0, 1] and is
typically grayscale.
Image is an m-by-n-by-3
array of integers in the
range [0, 255] or [0, 65535].
Reading, Writing, and Querying Graphics Image Files
Reading, Writing, and Querying Graphics Image Files
In its native form, a graphics file format image is not stored as a MATLAB
matrix, or even necessarily as a matrix. Most graphics files begin with a header
containing format-specific information tags, and continue with bitmap data
that can be read as a continuous stream. For this reason, you cannot use the
standard MATLAB I/O commands load and save to read and write a graphics
file format image.
MATLAB provides special functions for reading and writing image data from
graphics file formats. To read a graphic file format image use imread; to write
a graphic file format image, use imwrite; to obtain information about the
nature of a graphics file format image, use imfinfo.
This table gives a clearer picture of which MATLAB commands should be used
with which image types.
Procedure
Function(s) to Use
Load or Save a Matrix as a MAT-file
load
save
Load or Save Graphics File Format Image,
e.g. BMP, TIFF
imread
Display Any Image Loaded Into MATLAB
image
imwrite
imagesc
Utilities
imfinfo
ind2rgb
Reading a Graphics Image
The function imread reads an image from any supported graphics image file in
any of the supported bit depths. Most of the images that you will read are 8-bit.
When these are read into memory, MATLAB stores them as class uint8. The
main exception to this rule is that MATLAB supports 16-bit data for PNG and
TIFF images. If you read a 16-bit PNG or TIFF image, it will be stored as class
uint16.
5-15
5
Displaying Bit-Mapped Images
Note For indexed images, imread always reads the colormap into an array of
class double, even though the image array itself may be of class uint8 or
uint16.
For our discussion here we will show one of the most basic syntax uses of
imread. This code reads the image ngc6543a.jpg.
RGB = imread('ngc6543a.jpg');
You can write (save) image data using the imwrite function. The statements
load clown
imwrite(X,map,'clown.bmp')
create a BMP file containing the clown image.
Writing a Graphics Image
When you save an image using imwrite, MATLAB’s default behavior is to
automatically reduce the bit depth to uint8. Many of the images used in
MATLAB are 8-bit, and most graphics file format images do not require
double-precision data. One exception to MATLAB’s rule for saving the image
data as uint8 is that PNG and TIFF images may be saved as uint16. Since
these two formats support 16-bit data, you may override MATLAB’s default
behavior by specifying uint16 as the data type for imwrite. The following
example shows writing a 16-bit PNG file using imwrite.
imwrite(I,'clown.png','BitDepth',16);
Obtaining Information About Graphics Files
The imfinfo function enables you to obtain information about graphics files
that are in any of the standard formats listed above. The information you
obtain depends on the type of file, but it always includes at least the following:
• Name of the file, including the directory path if the file is not in the current
directory
• File format
• Version number of the file format
5-16
Reading, Writing, and Querying Graphics Image Files
• File modification date
• File size in bytes
• Image width in pixels
• Image height in pixels
• Number of bits per pixel
• Image type: RGB (truecolor), intensity (grayscale), or indexed
5-17
5
Displaying Bit-Mapped Images
Displaying Graphics Images
To display a graphics file image, use either image or imagesc. For example,
figure('Position',[100 100 size(RGB,2) size(RGB,1)]);
image(RGB); set(gca,'Position',[0 0 1 1])
(This image was created with support to the Space Telescope Science Institute,
operated by the Association of Universities for research in Astronomy, Inc.,
from NASA contract NAs5-26555, and is reproduced with permission from
AURA/STScI. Digital renditions of images produced by AURA/STScI are
obtainable royalty-free. Credits: J.P. Harrington and K.J. orkowski (University
of Maryland), and NASA.)
5-18
Displaying Graphics Images
Summary of Image Types and Display Methods
This table summarizes display methods for the three types of images.
Image Type
Display Commands
Uses Colormap
Colors
Indexed
image(X); colormap(map)
Yes
Intensity
imagesc(I,[0 1]); colormap(gray)
Yes
RGB
(truecolor)
image(RGB)
No
Controlling Aspect Ratio and Display Size
The image function displays the image in a default-sized figure and axes.
MATLAB stretches or shrinks the image to fit the display area. Sometimes you
want the aspect ratio of the display to match the aspect ratio of the image data
matrix. The easiest way to do this is with the command axis image.
For example, these commands display the earth image in the demos directory
using the default figure and axes positions.
load earth
image(X); colormap(map)
5-19
5
Displaying Bit-Mapped Images
50
100
150
200
250
50
100
150
200
250
The elongated globe results from stretching the image display to fit the axes
position. Use the axis image command to force the aspect ratio to be one-to-one.
axis image
5-20
Displaying Graphics Images
50
100
150
200
250
50
100
150
200
250
The command axis image works by setting the DataAspectRatio property of
the axes object to [1 1 1]. See axis and axes for more information on how to
control the appearance of axes objects.
Sometimes you may want to display an image so that each element in the data
matrix corresponds to a single screen pixel. To display an image with this
one-to-one, matrix-element-to-screen-pixel mapping, you need to resize the
figure and axes. For example, these commands display the earth image so that
one data element corresponds to one screen pixel.
[m,n] = size(X);
figure('Units','pixels','Position',[100 100 n m])
image(X); colormap(map)
set(gca,'Position',[0 0 1 1])
5-21
5
Displaying Bit-Mapped Images
The figure’s Position property is a four-element vector that specifies the
figure's location on the screen as well as its size. The second statement above
positions the figure so that its lower-left corner is at position (100,100) on the
screen and so that its width and height match the image width and height.
Setting the axes position to [0 0 1 1] in normalized units creates an axes that
fills the figure. The resulting picture is shown.
5-22
The Image Object and Its Properties
The Image Object and Its Properties
The commands image and imagesc create image objects. Image objects are
children of axes objects, as are line, patch, surface, and text objects. Like all
Handle Graphics objects, the image object has a number of properties you can
set to fine-tune its appearance on the screen. The most important properties of
the image object with respect to appearance are CData, CDataMapping, XData,
YData, and EraseMode. For detailed information about these and all of the
properties of the image object, please see image.
CData
The CData property of an image object contains the data array. In the
commands below, h is the handle of the image object created by image, and the
matrices X and Y are the same.
h = image(X); colormap(map)
Y = get(h,'CData');
The dimensionality of the CData array controls whether MATLAB displays the
image using colormap colors or as an RGB image. If the CData array is
two-dimensional, then the image is either an indexed image or an intensity
image, and in either case the image is displayed using colormap colors. If, on
the other hand, the CData array is m-by-n-by-3, then MATLAB displays it as a
truecolor image, ignoring the colormap colors.
CDataMapping
The CDataMapping property controls whether an image is indexed or intensity.
An indexed image is displayed by setting the CDataMapping property to
'direct', in which case the values of the CData array are used directly as
indices into the figure’s colormap. When the image command is used with a
single input argument, it sets the value of CDataMapping to 'direct'.
h = image(X); colormap(map)
get(h,'CDataMapping')
ans =
direct
Intensity images are displayed by setting the CDataMapping property to
'scaled'. In this case the CData values are linearly scaled to form colormap
5-23
5
Displaying Bit-Mapped Images
indices. The scale factors are controlled by the axes CLim property. The imagesc
function creates an image object whose CDataMapping property is set to
'scaled', and it also adjusts the CLim property of the parent axes. For
example,
h = imagesc(I,[0 1]); colormap(map)
get(h,'CDataMapping')
ans =
scaled
get(gca,'CLim')
ans =
[0 1]
XData and YData
The XData and YData properties control the coordinate system of the image. For
an m-by-n image, the default XData is [1 n] and the default YData is [1 m].
These settings imply the following:
• The left column of the image has an x-coordinate of 1.
• The right column of the image has an x-coordinate of n.
• The top row of the image has a y-coordinate of 1.
• The bottom row of the image has a y-coordinate of m.
For example, the statements,
X = [1 2 3 4; 5 6 7 8; 9 10 11 12];
h = image(X); colormap(colorcube(12))
xlabel x; ylabel y
produce the picture.
5-24
The Image Object and Its Properties
0.5
1
y
1.5
2
2.5
3
3.5
1
2
3
4
x
The XData and YData properties of the resulting image object have the default
values shown below.
get(h,'XData')
ans =
1
4
get(h,'YData')
ans =
1
3
However, you can override the default settings to specify your own coordinate
system. For example, the statements,
X = [1 2 3 4; 5 6 7 8; 9 10 11 12];
image(X,'XData',[−1 2],'YData',[2 4]); colormap(colorcube(12))
xlabel x; ylabel y
5-25
5
Displaying Bit-Mapped Images
produce the picture.
1.5
2
y
2.5
3
3.5
4
4.5
-1.5
-1
-0.5
0
0.5
x
1
1.5
2
2.5
EraseMode
The EraseMode property controls how MATLAB updates the image on the
screen if the image object’s CData property changes. The default setting of
EraseMode is 'normal'. With this setting, if you change the CData of the image
object using the set command, MATLAB erases the image on the screen before
redrawing the image using the new CData array. The erase step is a problem if
you want to display a series of images quickly and smoothly.
You can achieve fast and visually smooth updates of displayed images as you
change the image CData by setting the image object EraseMode property to
'none'. With this setting, MATLAB does not take the time to erase the
displayed image — it immediately draws the updated image when the CData
changes.
5-26
The Image Object and Its Properties
Suppose, for example, that you have an m-by-n-by-3-by-x array A, containing x
different truecolor images of the same size. You can display them dynamically
with
h = image(A(:,:,:,1),'EraseMode','none');
for i = 2:x
set(h,'CData',A(:,:,:,i))
drawnow
end
Rather than creating a new image object each time through the loop, this code
simply changes the CData of the image object (which was created on the first
line using the image command). The drawnow command causes MATLAB to
update the display with each pass though the loop. Because the image
EraseMode is set to 'none', changes to the CData do not cause the image on the
screen to erase each time through the loop.
5-27
5
Displaying Bit-Mapped Images
Printing Images
When you set the axes Position to [0 0 1 1] so that it fills the entire figure,
the aspect ratio will not be preserved when you print because MATLAB adjusts
the figure size when printing according to the figure’s PaperPosition property.
To preserve the image aspect ratio when printing, set the figure’s
PaperPositionMode to 'auto' from the command line.
set(gcf,'PaperPositionMode','auto')
print
When PaperPositionMode is set to 'auto', the width and height of the printed
figure are determined by the figure’s dimensions on the screen, and the figure
position is adjusted to center the figure on the page. If you want the default
value of PaperPositionMode to be 'auto', enter this line in your startup.m file.
set(0,'DefaultFigurePaperPositionMode','auto')
5-28
Converting the Data or Graphic Type of Images
Converting the Data or Graphic Type of Images
Sometimes you will want to perform operations that are not supported for
uint8 or uint16 arrays. To do this, convert the data to double precision using
the double function. For example,
BW3 = double(BW1) + double(BW2);
Keep in mind that converting between data types changes the way MATLAB
and the toolbox interpret the image data. If you want the resulting array to be
interpreted properly as image data, you need to rescale or offset the data when
you convert it. (See the earlier sections “Image Types” and “8-Bit and 16-Bit
Indexed Images” for more information about offsets.)
For certain operations, it is helpful to convert an image to a different image
type. For example, if you want to filter a color image that is stored as an
indexed image, you should first convert it to RGB format. To do this efficiently,
use the ind2rgb function. (which originated in the Image Processing Toolbox).
When you apply the filter to the RGB image, MATLAB filters the intensity
values in the image, as is appropriate. If you attempt to filter the indexed
image, MATLAB simply applies the filter to the indices in the indexed image
matrix, and the results may not be meaningful.
You can also perform certain conversions just using MATLAB syntax. For
example, if you want to convert a grayscale image to RGB, you can concatenate
three copies of the original matrix along the third dimension.
RGB = cat(3,I,I,I);
The resulting RGB image has identical matrices for the red, green, and blue
planes, so the image displays as shades of gray.
Sometimes you will want to change the graphics format of an image, perhaps
for compatibility with another software product. This process is very
straightforward. For example, to convert an image from a BMP to a PNG, load
the BMP using imread, set the data type to uint8, uint16, or double, and then
save the image using imwrite, with 'PNG' specified as your target format. See
imread and imwrite for the specifics of which bit depths are supported for the
different graphics formats, and for how to specify the format type when writing
an image to file.
5-29
5
Displaying Bit-Mapped Images
5-30
6
Basic Printing and
Exporting
Quick Start
. . . . . . . . . . . . . . . . . . . . 6-3
Overview of Printing and Exporting . . . . . . . . . 6-22
Printing a Figure to a Printer or a File . . . . . . . . 6-26
Exporting a Figure in Graphics Format
. . . . . . . 6-47
Troubleshooting . . . . . . . . . . . . . . . . . . 6-55
6
Basic Printing and Exporting
MATLAB enables you to do basic printing and exporting without having to
understand handle graphics. This section describes some frequently used ways
to print or export a MATLAB figure, and explains the basic printing and
exporting interfaces.
Quick Start
Step-by-step instructions for printing a figure to a printer or to a file, and for
exporting a figure to a graphics-format file or to the clipboard
Overview of Printing and Exporting
Selecting a figure to print or export, what is printed, and information about
default settings
Printing a Figure to a Printer or to a File
Printing a figure directly to a printer from the print menus or from the
command line. You can also print to a file, and print that file to a printer at
some later time.
Exporting a Figure in Graphics Format
Exporting a figure in graphics-format, such as JPEG or, to a file that you can
later import into another application. MATLAB enables you to export to a file
from the print menus or from the command line. You can also export a figure
to the clipboard from the preferences panels, and paste it from there into an
application.
6-2
Quick Start
Quick Start
This section provides step by step instructions for common printing and
exporting tasks. Each printing example tells you how to perform the task from
the print menus and from the command line. Some tasks can only be performed
from the command line.
List of Examples
Printing to a Printer
Print a figure directly to a printer:
• Using the defaults
• At screen size
• Locking the ticks and limits of the axes
• Setting the paper size
• Setting the size of and centering a figure
• To a nondefault printer
• Using Ghostscript
Printing to a File
• Printing a figure to a file. You can later print this file to a printer.
• Appending a figure to an existing PostScript file
Exporting
Export a figure in a graphics-format file that you can later import into an
application:
• Using a specific graphics format
• In EPS color format with a TIFF preview
• To the clipboard (Windows only)
Dialog Box Overview
If you want to print or export a figure using the figure menus, this diagram
illustrates the relationships between the dialog boxes you use most often.
6-3
6
Basic Printing and Exporting
Page Setup dialog box
Print dialog box (Windows version
shown)
Print Preview dialog box
Printing to a Printer Using the Defaults
If you have not changed the default settings, MATLAB prints the current
figure 8-by-6 inches with no window frame. It centers the figure on portrait
format 8.5-by-11 inch paper if available. MATLAB sets the figure background
and the axes background to white, and scales the ticks and limits of your axes
to accommodate the printed size.
This example shows how to print using the defaults:
• From the Windows menus
• From the UNIX menus
• From the command line
6-4
Quick Start
From the Windows Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
2 Choose a printer from the Name scroll list, if the printer you want to use is
not already selected.
3 If desired, set the Number of copies to a value greater than 1.
4 Click OK to print.
From the UNIX Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
6-5
6
Basic Printing and Exporting
2 Set Destination to Printer and choose a printer name from the Printer list
and a driver from the Driver list.
3 Click OK to print.
From the Command Line
This example uses the most basic form of the print command. MATLAB uses
the defaults to print the current figure to your default printer.
print
This example prints Figure No. 2 using default settings.
print -f2
Printing to a Printer at Screen Size
By default, MATLAB prints your figure at 8-by-6 inches. This size includes the
area delimited by the background. This example shows how to print or export
it the same size it is displayed on your screen:
• From the Windows menus
• From the UNIX menus
• From the command line
6-6
Quick Start
From the Windows Menus
1 Resize your figure window to the size you want it to be when printed.
2 Select Page Setup from the figure window’s File menu and select the Size
and Position tab.
3 In the Mode group box, select Use screen size, centered on page.
4 Click OK.
5 Invoke the Print dialog box to print the figure.
From the UNIX Menus
1 Invoke the Print dialog box to print the figure.
2 In the Figure Size on Printed Page group box, select the Same size as
screen option.
3 Click OK.
Note. You can also select screen size from the Size and Position tab in the
Page Setup dialog box.
From the Command Line
Set the PaperPositionMode property to auto before printing the figure.
set(gcf, 'PaperPositionMode', 'auto');
print
If you later want to print the figure at its original size, set PaperPositionMode
back to 'manual'.
Printing to a Printer, Locking the Ticks and Limits of
the Axes
By default, MATLAB scales the ticks and limits of your axes to accommodate
the printed size. This example shows how to lock them so they do not change:
• From the Windows menus
6-7
6
Basic Printing and Exporting
• From the UNIX menus
• From the command line
From the Windows Menus
1 Select Page Setup from the figure window’s File menu and select the Axes
and Figure tab.
2 Select Keep screen limits and ticks in the Axes limits and ticks box.
3 Click OK.
4 Invoke the Print dialog box to print the figure.
From the UNIX Menus
1 Invoke the Print dialog box to print the figure.
2 Select the Same as on screen option in the Axes Limits and Ticks group
box.
3 Click OK.
Note. You can also select screen size from the Axes and Figure tab in the Page
Setup dialog box.
From the Command Line
Set the xtickmode, ytickmode, and ztickmode properties to manual before
printing the figure.
set(gca, 'xtickmode','manual');
set(gca, 'ytickmode','manual');
set(gca, 'ztickmode','manual');
print
Printing to a Printer, Setting the Paper Size
By default, MATLAB uses 8.5-by-11 inch paper. This example shows how to
change the paper size to 8.5-by-14 inches by selecting a paper type (Legal):
6-8
Quick Start
• From the Windows and UNIX menus
• From the command line
From the Windows and UNIX Menus
1 Select Page Setup from the figure window’s File menu.
2 Select the Paper tab.
3 Select the Legal paper type from the list under Paper size. The width and
height fields update to 8.5 and 14, respectively.
4 Make sure that Units is set to Inches.
5 Click OK.
6 Invoke the Print dialog box to print the figure.
From the Command Line
Set the PaperUnits property to inches, and the PaperType property to Legal.
set(gcf, 'PaperUnits', 'inches');
set(gcf, 'PaperType', 'Legal');
Alternatively, you can set the PaperSize property to the size of the paper, in
the specified units.
set(gcf, 'PaperUnits', 'inches');
set(gcf, 'PaperSize', [8.5 14]);
Printing to a Printer, Setting the Size of and
Centering a Figure
This example sets the size of a figure to 5.5-by-3 inches and centers it on the
paper:
• From the Windows and UNIX menus
• From the command line
6-9
6
Basic Printing and Exporting
From the Windows and UNIX Menus
1 Select Page Setup from the figure window’s File menu and select the Size
and Position tab.
2 Make sure that Use screen size, centered on page is unchecked.
3 Enter 5.5 in the Width field and 3 in the Height field. (You can type these
values or click the arrows to select the new size.)
4 Make sure that Units field is set to Inches.
5 Click Center.
6 Click OK.
From the Command Line
1 Start by setting PaperUnits to inches.
set(gcf,'PaperUnits','inches')
2 Use PaperSize to return the size of the current paper.
papersize = get(gcf,'PaperSize')
papersize =
8.5000
11.0000
3 Initialize variables to the desired width and height of the figure.
width = 5.5;
height = 3;
% Initialize a variable for width.
% Initialize a varible for height.
4 Calculate a left margin that centers the figure horizontally on the paper. Use
the first element of PaperSize (width of paper) for the calculation.
left = (PaperSize(1)- width)/2
left =
1.5000
6-10
Quick Start
5 Calculate a bottom margin that centers the figure vertically on the paper.
Use the second element of PaperSize (height of paper) for the calculation.
bottom = (PaperSize(2)- height)/2
bottom =
4
6 Set the figure size and print.
myfiguresize = [left, bottom, width, height];
set(gcf, 'PaperPosition', myfiguresize);
print
Printing to a Nondefault Printer
This example shows you how to select a different printer on a per figure basis:
• From the Windows menus
• From the UNIX menus
• From the command line
Note. To set the default printer for the current MATLAB session, select Print
Setup from the figure window’s File menu. Under Printer, select a printer
from the name list.
From the Windows Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
6-11
6
Basic Printing and Exporting
2 Choose a printer from the Name list, if the printer you want to use is not
already selected.
3 Click OK.
From the UNIX Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
6-12
Quick Start
2 Set Destination to Printer and choose a printer name from the Printer list
and a driver from the Driver list.
3 Click OK.
From the Command Line (UNIX only)
This example sends the output to a black-and-white PostScript printer named
homer.
print -dps -Phomer
Printing to a Printer Using GhostScript
If you are using a non-PostScript printer, you may encounter an
incompatibility that causes the figure to print incorrectly. For example, some
parts of the figure may not print. In some cases, you can get by this problem by
using a GhostScript driver:
• From the UNIX menus
• From the command line
6-13
6
Basic Printing and Exporting
Note See the print reference page for a list of GhostScript drivers. You
cannot specify a printer driver from the Windows menus.
From the UNIX Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
2 Set Destination to Printer and choose a printer name from the Printer list.
3 From the Driver list, select a GhostScript driver that is compatible with
your printer. Click OK to print.
From the Command Line
This example uses a GhostScript driver to send the output to the default
printer, an HP LaserJet III. See the print reference page for a list of
GhostScript drivers.
print -dljet3
Printing a Figure to a File
This example shows you how to print a figure to a file for later printing. By
default, the figure is saved in your current directory.
• From the Windows menus
• From the UNIX menus
• From the command line
From the Windows Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
2 Select a printer, from the Name list, which is of the same type as the one to
which you will later print the figure.
6-14
Quick Start
3 Select the Print to File check box.
4 Click OK. This invokes the Print to File dialog box.
5 Enter a filename, preceding it with a pathname if you do not want the file
saved to the current directory.
6 Click OK to save the file.
From the UNIX Menus
1 Select Print from the figure window’s File menu. This invokes the Print
dialog box.
2 Set Destination to File and enter a filename in the Name field. If you need
to specify a directory other than the current directory, use the Browse
button to navigate to the desired directory.
3 Use the Driver scroll list to select a MATLAB printer driver for the type of
printer to which you will later print the figure.
4 Click OK to save the file.
From the Command Line
This example prints the figure in PostScript format to a file called
myfigure.ps.
print myfigure.ps;
This example uses GhostScript to print the figure to a file named myfigure.jet
that can later be printed to an HP LaserJet III. MATLAB adds the appropriate
file extension.
print -dljet3 myfigure;
Note See the print reference page for a list of printer drivers and their
MATLAB calls.
6-15
6
Basic Printing and Exporting
Appending a Figure to a PostScript File
Use the print command with the -append option to include more that one
PostScript-format figure in a single PostScript file. When you print the
resulting file, each figure appears on a separate page.
This example appends the figure, in PostScript format, to the PostScript file,
myfile.
print -dps -append myfile
This command appends Figure No. 2 to a file named myfigs.ps using level 1
color PostScript format.
print -dpsc -f2 -append myfigs.ps
Note See the print reference page for a list of printer drivers and their
MATLAB calls.
Exporting a Figure to a File in a Specific Graphics
Format
Export a figure to a graphics-format file when you want to import it at a later
time into another application such as a word processor.
• From the Windows or UNIX menus
• From the command line
From the Windows or UNIX Menus
1 Open the figure window’s File menu and select Export. This invokes the
Export dialog box.
6-16
Quick Start
2 Use the Save in field to navigate to a directory in which you want to save
your file.
3 Select a graphics format from the Save as type list.
4 Enter a filename in the File name field. An appropriate file extension, based
on the format you chose, is already shown.
5 Click Save to export the figure.
From the Command Line
From the command line, you must specify the graphics format as an option. See
“Frequently Used Graphics Formats” on page 6-47. See the print reference
page for a complete list of graphics formats and their corresponding option
strings.
This example exports a figure to an EPS color file, myfigure.eps, in your
current directory.
print -depsc myfigure
This example exports Figure No. 2 at a resolution of 300dpi to a 24-bit JPEG
file, myfigure.jpg.
print -djpeg -f2 -r300 myfigure
6-17
6
Basic Printing and Exporting
This example exports a figure at screen size to a 24-bit TIFF file,
myfigure.tif.
set(gcf,'PaperPositionMode','auto')
print -dtiff myfigure
% Use screen size
Exporting a Figure in EPS Format with a TIFF
Preview
Use the print command to export a figure in EPS format with a TIFF preview.
When you import the figure, the application can display the TIFF preview in
the source document. The preview is color if the exported figure is color, and
black-and-white if the exported figure is black-and-white.
This example exports a figure to an EPS color format file, myfigure.eps, and
includes a color TIFF preview.
print -depsc -tiff myfigure
This example exports a figure to an EPS black-and-white format file,
myfigure.eps, and includes a black-and-white TIFF preview.
print -deps -tiff myfigure
Exporting a Figure to the Clipboard
Export a figure to the clipboard in graphics-format when you want to paste it
into another Windows application such as a word processor:
• From the Windows menus
• From the command line
From the Windows Menus
This example exports a figure to the clipboard in Enhanced MetaFile (EMF)
format. Figure settings are chosen that would make the exported figure
suitable for use in a PowerPoint slide. Note that changing the settings modifies
the figure displayed on the screen:
1 Create a figure containing text. You can use the following code.
x = -pi:0.01:pi;
[h] = plot(x,sin(x));
title('Sine Plot');
6-18
Quick Start
2 Select Preferences from the figure window’s File menu. Then select Figure
Copy Template from the Preferences dialog box.
3 In the Figure Copy Template Preferences panel, click the PowerPoint
button. The MATLAB suggested settings for PowerPoint are added to the
template.
The PowerPoint
settings increase the
font size by a
percentage and make
all text bold.
The Text Group Box after the PowerPoint button is clicked
4 In the Lines group box, change the Custom width to 4 points.
5 In the Uicontrols and axes group box, select Keep axes limits and tick
spacing to prevent MATLAB from possibly rescaling ticks and limits when
you export.
6 Click Apply to Figure. The changes appear in the figure window.
If you don’t like the way your figure looks with the new settings, you can
restore it to its original settings by clicking the Restore button.
7 In the left pane of the Preferences dialog box, expand the Figure Copy
Template topic. Select Copy Options.
8 In the Copy Options pane, select Metafile to tell MATLAB to export the
figure in EMF format.
9 Check that Transparent background is selected. This choice makes the
figure background transparent and allows the slide background to frame the
axes part of the figure.
10 Deselect Match figure screen size so that you can use your own figure size
settings.
11 Click OK.
6-19
6
Basic Printing and Exporting
12 Select Page Setup from the figure window’s File menu.
13 In the Size and Position tab, set Width to 10 and Height to 7.5. Make sure
that Units are set to Inches.
14 Click OK.
15 Select Copy Figure from the Edit menu. Your figure is now exported to the
clipboard and can be pasted into another Windows application such as a
PowerPoint slide.
From the Command Line
Use the print command and one of two clipboard formats (-dmeta, -dbitmap)
to export a figure to the clipboard. Do not specify a filename.
6-20
Quick Start
This example exports a figure to the clipboard in Enhanced Metafile (EMF)
format.
print -dmeta
This example exports a figure to the clipboard in Bitmap (BMP) 8-bit color
format.
print -dbitmap
6-21
6
Basic Printing and Exporting
Overview of Printing and Exporting
MATLAB enables you to print a figure from the screen directly to a printer, or
to a file for later printing. It also enables you to export a figure in graphics
format to a file, or to the clipboard, so that you can import, or paste, it into an
application such as a word processor.
Before you print or export the figure, MATLAB enables you to change many
settings that control the look of the figure. For example you can change the size
and position of the figure, the paper type and orientation, as well as line, text
and background attributes.
This section provides general information about:
• What elements of the figure are printed or exported
• How to select the figure to be printed or exported
• Basic ways to print or export a figure
• Default figure settings and how to change them
You can also find more advanced information on selecting the printer driver
most appropriate for your use.
• Specifying a Printer Driver
• Types of Printer Drivers
• Choosing the Right Driver
• Drivers Provided by MATLAB
What Is Printed or Exported
A printed or exported figure includes the area inside the figure window frame.
The figure can include axis labels, uicontrols, and annotations.
Which Figure Is Printed
By default, MATLAB prints the current figure. If you have more than one
figure open, the current figure is the last active figure. Set the current figure:
• By giving the figure focus on your screen
• Using the command
6-22
Overview of Printing and Exporting
print -ffigurehandle
For example, print -f2 sets Figure No. 2 as the current figure. A figure’s
number is usually its handle.
How to Print or Export
This is an overview of the ways you can print or export a figure in MATLAB.
Subsequent sections of this chapter contain more detail.
Action
Ways to Print or Export a Figure
Print a figure to a
printer or to a file.
• Select Print from the figure window’s File
menu.
• Use the print command
Export a figure to a file
in graphics format.
• Select Export from the figure window’s File
menu.
• Use the print command.
Export a figure to the
clipboard in graphics
format.
• Select Copy Figure from the figure window’s
Edit menu.
• Use the print command.
Default Settings and How to Change Them
If you have not changed the default print and export settings, MATLAB prints
or exports the figure:
• 8-by-6 inches with no window frame
• Centered on portrait format 8.5-by-11 inch paper if available
• Using white for the figure and axes background color
• With the ticks and limits of the axes scaled to accommodate the printed size
Changing Settings for a Figure
In general, to change the property settings for a specific figure:
6-23
6
Basic Printing and Exporting
• In Windows, use the Page Setup dialog box, which you invoke by selecting
Page Setup from the figure window’s File menu, and the Document
Properties dialog box which you invoke from the Print dialog box.
• In UNIX, use the Page Setup dialog box, which you invoke by selecting Page
Setup from the figure window’s File menu, and the Options dialog box,
which you invoke from the Print dialog box.
• For exporting to the clipboard, use the Figure Copy Template Preferences
and Copy Options Preferences panels. Invoke these panels from
Preferences on the figure window’s File menu.
• From the command line, use the set command.
The settings you change with the Page Setup, Print, and Options dialog
boxes, and with the set command are saved with the figure and affect each
print of the figure until you change the settings again.
The settings you change with the Figure Copy Template Preferences and
Copy Options Preferences panels alter the figure as it displays on the screen.
The Figure Copy Template Preferences panel enables you to restore the
figure to its original state.
Some settings can also be changed for the current print operation by specifying
options to the print command.
Note After you have changed the settings, preview the print image by
selecting Print Preview from the figure window’s File menu.
See “Changing the Figure’s Settings” on page 6-30 for more information.
Changing Session Defaults
MATLAB enables you to set the session defaults for figure properties. Set the
session default for a property using the syntax
set(0,'DefaultFigurepropertyname','value')
where propertyname is one of the named figure properties. This example sets
the paper orientation for all subsequent print operations in the current
MATLAB session.
6-24
Overview of Printing and Exporting
set(0,'DefaultFigurePaperOrientation','landscape')
The Figure Properties reference page contains a complete list of the properties.
Changing Session-to-Session Defaults
MATLAB enables you to set the session-to-session defaults for figure
properties, the print device, and the print command. The print device can be
either a printer or a graphics format in which figures are exported.
Print Device and Print Command. Set the default print device and the default print
command in your printopt.m file. This file contains instructions for changing
these settings and for displaying the current defaults. Open printopt.m in
your editor by typing the command
edit printopt
Scroll down about 40 lines until you come to this comment line and make your
changes after this line.
%---> Put your own changes to the defaults here (if needed)
Figure Properties. Set the session-to-session default for a property by including
this command in your startup.m file.
set(0,'DefaultFigurepropertyname','value')
where propertyname is one of the named figure properties. For example,
set(0,'DefaultFigureInvertHardcopy','off')
keeps the figure background in the screen color.
This is the same command you use to change a session default, except that it
executes automatically every time MATLAB is invoked. The
Figure Properties reference page contains a complete list of the properties.
Colored Lines and Text. In Windows, you can set the session-to-session default for
how colored lines and text are sent to the printer in the Figure window
printing box on the General Preferences panel. You can override this default
setting for a specific figure from the Lines and Text tab on the figure’s Page
Setup dialog box.
6-25
6
Basic Printing and Exporting
Printing a Figure to a Printer or a File
You can print a figure using the menus, or from the command line. You can
print it directly to a printer, or to a file for later printing.
Note If you print a figure to a file, the file can only be printed and cannot be
imported into another application. If you want to create a figure file that you
can import into an application, see “Exporting a Figure in Graphics Format”
on page 6-47.
This section introduces:
• The dialog boxes you use to print a figure
• The commands you use to print a figure from the command line or from a
program
It also tells you how to:
• Change the settings that control the way a figure looks when you print it.
• Print the figure.
Using Print Dialog Boxes
Invoke the dialog boxes you need to print the figure from the File menu on the
figure window:
1 Use the Page Setup dialog box to make any settings needed for printing,
such as the size of the printed figure.
2 Use the Print Preview dialog box to preview your printed figure.
3 Use the Windows or UNIX Print dialog box to send the figure to the printer.
6-26
Printing a Figure to a Printer or a File
Page Setup dialog box
Print dialog box (Windows version
shown)
Print Preview dialog box
For detailed help on any dialog box element, click the Help button on the
element to see its context-sensitive help.
Note You can invoke the Print, Page Setup, and Print Preview dialog boxes
from a program or from the command line with the printdlg, pagesetupdlg,
and printpreview commands.
From the Command Line
You can print a MATLAB figure from the command line or from a program. Use
the set function to set the properties that control how the printed figure looks.
Use the print command to print it to a printer or to a file.
6-27
6
Basic Printing and Exporting
The set Function
The set function changes the values of properties that control the look of a
printed figure. These properties are stored with the figure. When you change
one of the properties, the new value is saved with the figure and affects each
print of the figure until you change the setting again.
To change the print properties of the current figure, the set command has the
form
set(gcf,'Property1',value1,'Property2',value2,...)
where gcf is a call that gets the handle of the current figure, and each
property-value pair consists of a named property followed by the value to which
the property is set. For example,
set(gcf,'PaperUnits','centimeters','PaperType','A4',...)
sets the units of measure and the paper size. “Changing the Figure’s Settings”
on page 6-30 describes commonly used print properties. The Figure Properties
reference page contains a complete list of the properties.
You can also use the get command to retrieve the value of a specific property.
a = get(gcf,'Property')
Note See “Changing Session Defaults” on page 6-24 and “Changing
Session-to-Session Defaults” on page 6-25 for more information about
managing default property values.
The print Command
The print command sends the figure to a printer, saves it to a file, exports it
to a graphics-format file, or exports it to the clipboard.
The command and function forms of print differ slightly in their syntax.
Although this document uses the command form, you can easily use the
equivalent function form in a program. In both forms, all arguments are
optional and can be placed in any order.
The command form of print is
print -device -options filename
6-28
Printing a Figure to a Printer or a File
The function form of print is
print('-device','-options','filename')
where:
-device
For printing, -device is a printer.
For exporting, -device is the graphics format in which the
figure is exported.
-options
Controls some aspects of the look of the printed figure. It can
also control the action to be taken, or specify the figure to be
printed or exported.
filename
Is the name of the file to which the figure is saved, appended,
or exported.
Note See “Printing the Figure” on page 6-41 for information about specific
-device and -options values.
You control what action the print command takes, depending on the presence
or absence of certain arguments. This table describes what arguments to use.
The table assumes factory defaults.
Action
Print Command Arguments
Print a figure to a printer.
Don’t specify a filename, and specify a
printer.
Print a figure to a file for later
printing.
Specify a filename, and specify a printer.
6-29
6
Basic Printing and Exporting
Action
Print Command Arguments
Export a figure to a graphics
format file that you can later
import into an application.
Specify a filename, and specify a
graphics format.
Export a figure in graphics
format to the clipboard.
Don’t specify a filename, and specify a
graphics format.
Note If you specify no device in the print command, MATLAB uses the
default device for your platform from printop.m. If you have not modified
printop.m, the default device is a printer and MATLAB prints the figure. If
the default driver is modified to be a graphics format, MATLAB exports the
figure.
Changing the Figure’s Settings
This section tells you how to use the Page Setup dialog box or the command
line to change:
• The size of the figure
• The position of the figure on the page
• Units of measure
• The paper size and type
• Color attributes of lines, text, and background
• Axes, tick marks, and uicontrols
• Rendering the figure
Using the Printing Options or Document Properties dialog boxes, or the
command line, you can also control these settings:
• Figure resolution
• Uncropped output
• Use of CMYK color space
6-30
Printing a Figure to a Printer or a File
Note See “Using Print Dialog Boxes” on page 6-26 for an overview of the
dialog boxes, and “From the Command Line” on page 6-27 for information
about the commands and functions you use to change the print settings.
Examples
These examples show you how to change specific settings from the Windows
and the UNIX menus, and from the command line:
• “Printing to a Printer at Screen Size” on page 6-6
• “Printing to a Printer, Locking the Ticks and Limits of the Axes” on page 6-7
• “Printing to a Printer, Setting the Paper Size” on page 6-8
• “Printing to a Printer, Setting the Size of and Centering a Figure” on
page 6-9
Size of the Figure
These properties control the size of the printed figure on the page. In some
cases, they also control the position. See “Position of the Figure on the Page” on
page 6-34 for properties that control position.
Note It is often easier to see what the printed or exported figure will look
like, if you change the size of the screen figure by clicking and dragging its
borders, then printing it at screen size.
6-31
6
Basic Printing and Exporting
Action
Page Setup Dialog Box
Command Line
Print figure at
8-by-6 inches
Size and Position tab. Set the Mode to
Use manual size and position. MATLAB
Set PaperPositionMode
property to 'manual'. This
is the default.
prints the figure at 8-by-6 inches and
centers it on the page (if you have not
changed the default).
Note: You can also make this change from
the UNIX Print dialog box.
Print figure at
screen size
Size and Position tab. Set the Mode to
Use screen size, centered on page.
Set PaperPositionMode
property to 'auto'.
MATLAB prints the figure the same size it
is on the screen. If you select this option,
you cannot change the Top, Left, Width
and Height fields. However, they are
updated to show the position and screen
size of the figure.
Note: You can also make this change from
the UNIX Print dialog box.
Set the height and
width of the figure
Size and Position tab. Set the Width and
Height fields to the desired size of the
figure. MATLAB prints the figure with
these dimensions. The Width and Height
fields are initially set to 8.00 and 6.00
inches respectively.
Set PaperPosition
property to a 4-element
vector [leftmargin,
bottommargin, width,
height].
Mode must be set to Use manual size and
position.
Note Alternatively, you can change the size of the screen figure by
clicking and dragging its borders, then printing it at screen size.
6-32
Printing a Figure to a Printer or a File
Action
Page Setup Dialog Box
Command Line
Size the figure
interactively
Set the size of the printed figure by
dragging the figure boundaries in the
preview image on the right side of the
dialog box. The Width and Height fields
are updated to show the print size of the
figure.
Not available
Mode must be set to Use manual size and
position.
Fill the page
Fix the aspect ratio
Size and Position tab. Click on Fill page.
MATLAB prints the figure to fill the page,
with a margin of 0.25 inches on all four
sides. The Width and Height fields are
updated to show the print size of the figure.
Set PaperPosition
property to a 4-element
vector [leftmargin,
Mode must be set to Use manual size and
position.
Use the value of the
PaperSize property
([width, height]) to
calculate desired figure
size.
Size and Position tab. Click on Fix aspect
ratio. MATLAB resizes the printed figure
Set PaperPosition
property to a 4-element
vector [leftmargin,
to have the same aspect ratio as the screen
figure. The aspect ratio is equal to the
width divided by the height. The Width
and Height fields are updated to show the
new print size of the figure.
Mode must be set to Use manual size and
position.
bottommargin, width,
height].
bottommargin, width,
height].
Get the figure’s Position
property
([leftscreenmargin,
bottomscreenmargin,
width, height]) to
calculate the aspect ratio
of the screen figure
window.
6-33
6
Basic Printing and Exporting
Position of the Figure on the Page
These properties control the position of the printed figure on the page.
Action
Page Setup Dialog Box
Command Line
Set the figure
margins
Size and Position tab. Set the Top and Left
fields to the size of the desired margins.
MATLAB positions the figure using these
margins. The Top and Left fields are initially
set to 2.50 and .25 inches respectively.
Set PaperPosition
property to a 4-element
vector [leftmargin,
Mode must be set to Use manual size and
position.
Note: PaperPosition
sets the bottom margin,
rather than the top
margin.
Size and Position tab. Click on Center.
MATLAB centers the figure horizontally and
vertically on the page.
Set PaperPosition
property to a 4-element
vector [leftmargin,
Center the figure
Mode must be set to Use manual size and
position.
bottommargin, width,
height].
bottommargin, width,
height].
Get the PaperSize
property ([paperwidth,
paperheight]) to
calculate desired
margins.
Position the figure
interactively
Position the printed figure by dragging the
figure in the preview image on the right side
of the dialog box. The Top and Left fields are
updated to show the new margins.
Mode must be set to Use manual size and
position.
6-34
Not available
Printing a Figure to a Printer or a File
Units of Measure
This property controls the units in which all values that describe the size and
position of the printed figure are shown on the dialog boxes or returned on the
command line.
Action
Page Setup Dialog Box
Command Line
Set the units of
measure
Size and Position and Paper tabs. Select the
desired units from the list under Units. The
Top, Left, Width and Height fields in the
Size and Position tab are automatically
converted to the selected units.
Set the PaperUnits
property. Possible values
are 'inches',
'centimeters', 'points',
and 'normalized'. The
default is 'inches'.
Mode must be set to Use manual size and
position.
Inches, centimeters, and points are absolute
units. (One point equals 1/72 of an inch.)
Normalized units are relative to the paper
size, namely, they map the lower-left corner
of the figure to (0,0) and the upper-right
corner to (1.0, 1.0).
This setting applies to all
values you set or get using
the PaperPosition
property.
6-35
6
Basic Printing and Exporting
Paper Size and Type
These properties enable you to select by type or by size, the paper on which the
figure is printed.
Action
Page Setup Dialog Box
Command Line
Set the paper
type
Paper tab. Use the list under Paper size to
select from a list of predefined “paper types.”
The paper Width and Height fields are updated
automatically to reflect the dimensions for your
chosen paper type.
Set the PaperType
property. Some possible
values are 'usletter'
(8.5-by-11 inches),
'uslegal' (11-by-14
inches), 'tabloid'
(11-by-17 inches), 'A4'
(210-by-297 mm).
If you are a Windows user, the list shows the
paper types supported by the current printer. If
you are a UNIX user, the list shows MATLAB’s
built-in paper types. By default, MATLAB
selects portrait format 8.5-by-11.0 inch paper, if
available.
Set the paper
width and height
6-36
Paper tab. Set the Width and Height fields to
the desired paper width and height if you cannot
find a suitable paper type in the Paper size list.
Paper size is automatically updated to show a
paper type of <custom>. When the paper type is
set to <custom>, the paper size is handled by the
printer.
See the Figure
Properties reference
page for a list of paper
types.
Set PaperSize property
to a 2-element vector
[paperwidth,
paperheight].
Printing a Figure to a Printer or a File
Action
Page Setup Dialog Box
Command Line
Set the paper
orientation
Paper tab. Click on one of the Orientation
option buttons:
PaperOrientation
Portrait – Specifies that the longer paper
dimension is oriented vertically with respect to
the figure.
Landscape – Orients the longer paper
dimension horizontally.
Rotated –Equivalent to rotating the paper 180º
from landscape orientation. If Rotated is not
supported by the current printer, the figure
prints with landscape orientation.
Set the
property. Possible values
are 'portrait',
'landscape', and
'rotated'. The default
is 'portrait'.
You can use the orient
function if you want the
figure centered on the
paper.
6-37
6
Basic Printing and Exporting
Attributes of Lines, Text, and Background
By default, MATLAB forces the figure background to white, but retains colors
used in the figure. These properties enable you to override this default
behavior.
Action
Page Setup Dialog Box
Command Line
Force line and text
objects to black and
white
Lines and Text tab. Click on the Black and
white option in the Lines and Text tab. The
Specify the device as a
black-and-white
printer or graphics
format. See the print
reference page for a
list of printers (i.e.,
drivers) and graphics
formats.
Keep the screen
color for lines and
text
Force the figure
background to white
lines and text are printed all black or all white,
depending on the background color. This
setting is recommended for use with black and
white printers because colored lines and text
are dithered to gray that may not be suitable
for thin lines and text characters.
Lines and Text tab. Click on the Color (don’t
convert) option in the Lines and Text tab. The
text and solid colored lines are printed in the
same color as they are on the screen. If you are
using a black and white printer, all of your text
and solid colored lines are converted to shades
of gray.
Axes and Figure tab. Click on the Force
white background option in the Axes and
Figure tab. MATLAB prints the figure with
white axes and figure backgrounds. This
setting is intended to save on toner and may
produce better-looking printed results.
Keep the figure
background in the
screen color
Axes and Figure tab. Click on the Keep
screen background color option in the Axes
and Figure tab. MATLAB prints the figure
using the screen colors for both the axes and
figure backgrounds. If you select this option
and use a black and white printer, the
background colors are dithered to shades of
gray.
6-38
This is the default.
Set the
InvertHardCopy
property to 'on'. This
is the default.
Set the
InvertHardCopy
property to 'off'.
Printing a Figure to a Printer or a File
If you have a black and white printer, you may want to read Getting the Best
Results with Black-and-White Printers.
Axes, Tick Marks, and Uicontrols
By default, MATLAB recomputes the tick marks and the axes limits based on
the size of the printed figure. It also retains uicontrols in the figure. These
properties enable you to override this default behavior.
Action
Page Setup Dialog Box
Command Line
Recompute axes
limits and ticks
Axes and Figure tab. Click on the Recompute
axes limits and ticks option. MATLAB scales the
Set the XTickMode,
YTickMode, and
ZTickMode
number and placement of tick marks and the limit
values of the axes depending on the size of the
printed figure.
Note: You can also make this change in the UNIX
Print dialog box.
Keep screen limits
and ticks
Axes and Figure tab. Click on the Keep screen
limits and ticks option. MATLAB keeps the same
number of ticks and the same limit values in the
printed figure as are in the screen figure.
Note: You can also make this change in the UNIX
Print dialog box.
Keep or suppress
printing of UI
controls
Axes and Figure tab. Deselect Print UIControls
if you do not want uicontrols to appear in the
printed figure. If you leave this check box selected,
any uicontrols in the figure appear in the printout.
Uicontrols include push buttons, listboxes, sliders,
pop-up menus, editable text boxes, and check
boxes that you can add to a figure. See the
uicontrol reference page for a complete list.
properties to
'auto'. This is the
default.
Set the XTickMode,
YTickMode, and
ZTickMode
properties to
'manual'.
Use print -noui
to suppress the
uicontrols. The
default is to keep
the uicontrols.
6-39
6
Basic Printing and Exporting
Rendering the Figure
A renderer is software and/or hardware that draws the figure you see on the
screen in a file, or formats it for a printer. By default, MATLAB chooses a
renderer.
Action
Page Setup Dialog Box
Command Line
Let MATLAB
choose the
renderer
Axes and Figure tab. Select Default (auto mode) in
the Figure renderer list. MATLAB selects a
rendering method based on the complexity of the
figure and the settings of various Handle Graphics
properties. This setting usually produces a
satisfactory printout.
This is the default.
See the Figure Properties reference page for
information about MATLAB’s autoselection criteria.
Select a
specific
renderer
Axes and Figure tab. MATLAB uses the renderer you
select from the Figure renderer list to render the
figure. Select Painter’s if you want to print using
vector graphics. Select Z-buffer or OpenGL if you
want to print using raster (bitmap) graphics.
Set the Renderer
property to
'painters',
'zbuffer', or
'OpenGL'.
Note For printing, the renderer selected using Page Setup takes precedence
over any renderer selection done in the command line. However, when the
renderer is set to Default (auto mode) in Page Setup, you may set your
printing renderer with the command line.
Note The renderer you can use is sometimes limited by the printer driver or
export format. See the table of renderer support.
For more information on setting the rendering method, see
• Comparing Rendering Methods
6-40
Printing a Figure to a Printer or a File
• The Default Renderer for MATLAB
• Reasons for Changing the Renderer
Printing the Figure
After you have changed the settings to make your printed figure look the way
you want, you are ready to print the figure. This section tells you how to print
your figure to a printer or to a file using:
• The Windows Print dialog box
• The UNIX Print dialog box
• The command line
Note Before printing the figure, preview the print image by selecting Print
Preview from the figure window’s File menu. Use the Page Setup dialog box
or the set command to adjust the look of the exported figure. See “Changing
the Figure’s Settings” on page 6-30 for details.
From the Windows Print Dialog Box
MATLAB for Windows uses the standard Windows Print dialog box, which
normally comes with Windows software products. It enables you to:
• Choose the printer to which the figure is printed.
• Specify the number of copies to print.
• Choose to print the figure to a file for later printing.
Select Print from the figure window’s File menu to invoke the Print dialog box.
For examples, see “Printing to a Printer” on page 6-3 and “Printing to a File”
on page 6-3.
6-41
6
Basic Printing and Exporting
Click to invoke the
Windows Document
Properties dialog box.
This enables you to make
changes to
printer-specific settings.
Use the drop-down list
to select a printer.
Lists the type and name
of the currently selected
printer.
Select Print to file to
save to a file that will be
printed later.
This group box does not
affect your printed
output, and cannot be set
to anything other than
All.
If you want to print more
than one copy, type in a
new number or use the
arrows to select a new
number.
Click to begin
printing.
Click to cancel job without
saving any settings.
From the UNIX Print Dialog Box
MATLAB for UNIX has a Print dialog box and an associated Printing Options
dialog box.
Print Dialog Box. The Print dialog box enables you to:
• Choose the printer to which a figure is printed.
• Print the figure to a file for later printing.
• Choose the driver that controls the printed figure’s format.
• Preserve the same axis and tick marks you have in your displayed figure
window. By default, MATLAB scales the number and placement of tick
marks and the axes limits based on the size of the printed figure.
• Print the figure at screen size instead of the default 8-by-6 inches
• Invoke the Printing Options dialog box
6-42
Printing a Figure to a Printer or a File
Select Print from the figure window’s File menu to invoke the Print dialog box.
For examples, see “Printing to a Printer” on page 6-3 and “Printing to a File”
on page 6-3.
Use the drop-down list
to select a printer.
Click to browse to
a directory to save
your file in when
printing to a file.
Select Printer to print now
or select File to save to a
file that can printed later
Type in a name if you are
printing to a file.
Invokes the
Printing Options
dialog box.
Use the drop-down list to
select a printer driver.
Click Same size as screen if
you want the printed plot to
have the same size as it does
on your screen.
Click 8 by 6 inches if you
want the printed output to
have these dimensions.
Click to invoke
help for this
dialog box.
Click Same as on screen to force MATLAB to print
the same number of ticks and the same limit values
for the axes as are used on the screen.
Click Allow MATLAB to select to let MATLAB scale
the limits and ticks of the axes based on the size of
the printed figure.
Click to begin
printing.
Click to cancel job
without saving any
settings made.
Printing Options Dialog Box. The Printing Options dialog box enables you to set
some print settings just before printing, such as the rendering method to use,
or the resolution of the printed figure, in dots per inch. See “Rendering the
Figure” on page 6-40 for information about rendering.
Click the Options button on the Print dialog box to invoke the Printing
Options dialog box.
6-43
6
Basic Printing and Exporting
Check to leave a little space between the
outermost objects in the plot and the edges of
the plot’s background.
Check to produce output in CMYK instead of
RGB. This is for postscript printers and drivers
only.
Click here to
have MATLAB
choose the
renderer.
Check to have MATLAB use the default PostScript
character set. This is useful for early PostScript
printers that do not support the PostScript
operator ISOLatin1Encoding.
Or, click here to
use the
Painter’s
algorithm,
which creates a
metafile.
Check to prevent user interface (UI) controls
(that you added to the plot) from appearing in
the printed plot.
Click here to have MATLAB choose a resolution
that is supported by the chosen printer driver and
makes sense for the type of renderer selected.
Or, click here to
use the
Z-buffer
algorithm,
which creates a
bitmap.
Or, click here to set the resolution for the printout
to the resolution used by the screen.
Or, click here and then enter a resolution value in
the text box. The text box is grayed out if
Specify resolution in dots per inch is not
selected.
Click to apply these
print settings to the
current plot.
Click to dismiss dialog
box without saving any
settings made.
From the Command Line
Use the print command to print the figure to a printer or to a file.
print -device -options filename
where the command arguments are:
-device
A printer, such as a Hewlett-Packard DeskJet 500. Some
commonly used printers and their device specifiers are:
Canon BubbleJet BJ200 color
6-44
-dbj200
Printing a Figure to a Printer or a File
Canon BubbleJet BJ600/4000/70
color
-dbj600
Epson and compatible 9- or 24-pin
dot matrix printers
-depson
HP DeskJet 500
-ddjet500
HP LaserJet III
-dljet3
PostScript Level 2 black and white
-dps2
Postscript Level 2 color
-dpsc2
If you do not specify a printer, MATLAB uses the default device
specified in printop.m for your platform. See the print
reference page for a list of supported printers (i.e., drivers).
-options
Specifies options that control some aspects of the look of the
printed figure. It can also control the action to be taken, or
specify the figure to be printed or exported. Unlike the
properties you set with the set function, these values are not
saved with the figure. You must specify them each time you
print the figure.
Commonly used options are:
-append
Append the figure to an existing PostScript file.
PostScript only.
-fhandle
Handle of the figure to print. For Figure No. 2,
specify -f2. By default MATLAB prints the last
active figure.
-noui
Suppress printing of uicontrols.
-Pprinter
Printer to which the figure is printed. UNIX only.
6-45
6
Basic Printing and Exporting
-rnumber
Resolution in dots per inch.
See the print reference page for a list of supported options.
filename
Specifies the name of the file to which the figure is printed or
appended for later printing. If you do not specify a filename, the
figure is printed to a printer.
If you are printing a figure to a new file and do not specify a file
extension, print appends an extension that is appropriate for
the device.
6-46
Exporting a Figure in Graphics Format
Exporting a Figure in Graphics Format
Export a figure in a graphics format to a file if you want to import it into
another application, such as a word processor. You can also export it to the
Windows clipboard, and paste it from there into an application. Before deciding
on a graphics format, check what formats are supported by your target
application and platform. See the print reference page for a complete list of
supported graphics formats.
Frequently Used Graphics Formats
Format
Description
Command Line -device
Parameter
BMP 8-bit color
bitmab
Export a figure to the clipboard (Windows
only).
-dbitmap
EMF color vector
format
Export a figure to the clipboard (Windows
only).
-dmeta
EPS color and
black-and-white
Export line plots or simple graphs to a file.
-deps (black and white)
Note. An EPS file does not display within
some applications unless you add a TIFF
preview image to it. See the example
“Exporting a Figure in EPS Format with a
TIFF Preview” on page 6-18.
-depsc (color)
JPEG 24-bit
Export plots with surface lighting or
transparency to a file. This format can be
displayed by most Web browsers.
-depsc -tiff
(TIFF preview)
-djpeg
-djpegnumber
where number is the
compression.
TIFF 24-bit bitmap
color
Export plots with surface lighting or
transparency to a file. Widely available. A
good format to choose if you are not sure what
formats your application supports.
-dtiff
6-47
6
Basic Printing and Exporting
Examples
These examples show you how to export a figure to a file using a specific
graphics format, and to the clipboard:
• “Exporting a Figure to a File in a Specific Graphics Format” on page 6-16
• “Exporting a Figure in EPS Format with a TIFF Preview” on page 6-18
• “Exporting a Figure to the Clipboard” on page 6-18
More Information on Exporting
For further information on file formats and how to select the best one for your
application, see
• Details About Selected File Formats
• How to Choose a File Format
• Built-in MATLAB and Ghostscript Formats
• Bitmap and Vector Formats
• Getting the Best Results With Bitmap Formats
• Preserving Colors in Exported Figures
Other topics related to exporting are:
• Using the getframe Command to Export a Graphic
• Importing MATLAB Graphics Into Other Applications
Exporting to a File
You can export a figure to a file in a specific graphics format from the Windows
or UNIX Export dialog box or from the command line.
Note Before you export the figure, preview the image to be exported by
selecting Print Preview from the figure window’s File menu. Use the Page
Setup dialog box or the set command to adjust the look of the exported figure.
See “Changing the Figure’s Settings” on page 6-30 for details.
6-48
Exporting a Figure in Graphics Format
From the Windows or UNIX Export Dialog Box
Use the Export dialog box to select a file format, specify a filename, and
navigate to a directory in which you want to save your file. To invoke the
Export dialog box, select Export from the figure’s File menu.
See “Frequently Used Graphics Formats” on page 6-47.
Select the folder in
which to save the file.
List of folders and files
in selected location
Type the name of the
file to which the figure
will be exported.
Click to save the file.
Click to cancel job
without saving any
settings.
Use the Save as type
drop-down list to select
a graphics format.
From the Command Line
Use the print command to export the figure in graphics format.
print -device -options filename
where the command arguments are:
6-49
6
Basic Printing and Exporting
-device
The graphics format, such as EPS color or JPEG 24-bit, used to
draw the figure in the file. See “Frequently Used Graphics
Formats” on page 6-47. See the print reference page for a
complete list of supported graphics formats.
-options
Specifies options that control some aspects of the look of the
exported figure. You can also specify the figure to be exported.
Unlike the properties you set with the set function, these
values are not saved with the figure. You must specify them
each time you export the figure. Commonly used options are:
-fhandle
Handle of the figure to export. For Figure No. 2,
specify -f2. The default is the current figure.
-noui
Suppress printing of uicontrols.
-rnumber
Resolution in dots per inch.
See the print reference page for a complete list of supported
options.
filename
Specifies the name of the file to which the figure is exported. If
you do not specify a file extension, print appends an extension
that is appropriate for the graphics-format.
Exporting to the Clipboard
You can export a figure in graphics format to the Windows clipboard from the
figure’s Edit menu or from the command line. You can choose one of two
graphics formats for exporting to the clipboard, EMF color vector (-dmeta) or
BMP 8-bit color bitmap (-dbitmap). If you use the menus to export the figure,
you can also elect to let MATLAB choose which of the two formats to use.
By default, the format is chosen based on the rendering method used to display
the figure. If the figure is displayed with the OpenGL or Z-buffer renderer,
Windows Bitmap is the default. If the figure is displayed with the Painter’s
renderer, the EMF format is used.
6-50
Exporting a Figure in Graphics Format
Note Many property settings you make with the Page Setup dialog box or
the set command apply to both printed and exported figures. For exported
figures, the settings that affect the position of the figure on the page, or the
size and orientation of the paper, are ignored. See “Changing the Figure’s
Settings” on page 6-30 if you want to change any of the settings.
From the Edit Menu
To export the current figure to the clipboard, select Copy Figure from the
figure window’s Edit menu.
Before you export the figure, you can use the Figure Copy Template
Preferences panel and the Copy Options Preferences panel to adjust the
figure’s settings. These settings override corresponding settings you made
using the Page Setup dialog box or the set command. Invoke the Preferences
panels from the figure’s File menu.
Figure Copy Template Preferences. This panel enables you to create a template and
apply it to the current figure. When you click Apply to Figure, MATLAB saves
the template and uses it to modify the screen figure. Click Restore Figure to
restore the figure to its original state.
6-51
6
Basic Printing and Exporting
Click Word or PowerPoint to apply
MATLAB-recommended settings.
Click to restore the default
template preference settings.
Check Change font size, then
select to change the size as points
(1 point = 1/72 inch), or a
percentage of the original.
Finally, type in a value.
Check to change text to black
and white.
Check to make text bold.
Check to change the line width
then type the new width.
Check to change the line style,
then select Black and white to
force the lines to black and white,
or B&W styles to also use
different styles to differentiate
the lines.
Check to show uicontrols, uncheck
to suppress them.
Click to save the
template and apply it
to the current figure.
Click to restore the
figure to its original
state.
Click to save the template
and close the preferences
panel.
Click to close the preferences
panel without saving the
template.
Check to keep axes limits and
ticks as they appear on the
screen. Uncheck to allow MATLAB
to scale them based on the size of
the printed figure.
Copy Options Preferences. This panel enables you to adjust the figure’s settings.
These changes override settings you made with the Page Setup dialog box or
the set command. They do not affect the way the figure looks on the screen.
6-52
Exporting a Figure in Graphics Format
Select Metafile to copy the
figure in EMF color vector
format.
Select Preserve information to
allow MATLAB to select the
format. MATLAB uses metafile
format if possible.
Select Bitmap to copy the figure
in BMP 8-bit color bitmap
format.
Select Use figure color to keep
the background color as on the
screen.
Select Force white background
if you want a white background.
Select Transparent
background if, for example,
you want a slide background to
frame the axes part of the
figure.
Click to save the options and
close the preferences panel.
Click to close the preferences panel
without saving the options
Note See “Exporting a Figure to the Clipboard” on page 6-18.
From the Command Line
Use the print command to export the figure to the clipboard in graphics
format. Do not specify a filename.
print -device -options
6-53
6
Basic Printing and Exporting
where the command arguments are:
-device
-options
Graphics format used to draw the figure on the clipboard:
-dmeta
EMF color vector format
-dbitmap
BMP 8-bit color bitmab
Specifies options that control some aspects of the look of the
exported figure. You can also specify the figure to be exported.
Unlike the properties you set with the set function, these
values are not saved with the figure. You must specify them
each time you export the figure. Commonly used options are:
-fhandle
Handle of the figure to export. For Figure No. 2,
specify -f2. By default MATLAB exports the last
active figure.
-noui
Suppress printing of uicontrols.
See the print reference page for a complete list of supported
options.
6-54
Troubleshooting
Troubleshooting
This section lists some common problems you might encounter when printing
or exporting your figure. Refer to the appropriate section listed below.
• Printing Problems
- “Printer Drivers” on page 6-56
- “Default Settings” on page 6-57
- “Printing Lines” on page 6-57
- “Printer” on page 6-58
- “Rotated Text” on page 6-59
- “ResizeFcn Warning” on page 6-59
• Exporting Problems
- “Background Color” on page 6-59
- “Default Settings” on page 6-59
- “Microsoft Word” on page 6-60
- “File Format” on page 6-61
- “Size of Exported File” on page 6-61
- “Making Movies” on page 6-62
- “Extended Operations” on page 6-62
• General Problems
- “Background Color” on page 6-63
- “Default Settings” on page 6-63
- “Dimensions of Output” on page 6-63
- “Axis and Tick Labels” on page 6-64
- “UI Controls” on page 6-64
- “Cropping” on page 6-65
- “Text Object Font” on page 6-65
If you don’t find your problem listed here, try searching the Knowledge Base
maintained by the MathWorks Technical Support Department. Go to http://
www.mathworks.com/support and enter a topic in the search field.
6-55
6
Basic Printing and Exporting
Printing Problems
Printer Drivers
I’m using a Windows printer driver and have been encountering problems such as
segmentation violations, general protection faults, application errors, and unexpected
output.
Try one of the following solutions:
• Check the table of drivers in the print reference page to see if there are other
drivers you can try.
- If your printer is PostScript compatible, try printing with one of
MATLAB’s built-in PostScript drivers.
- If your printer is not PostScript compatible, see if one of MATLAB’s
built-in Ghostscript devices is appropriate for your printer model. These
devices use Ghostscript to convert PostScript files into other formats, such
as HP LaserJet and Canon BubbleJet.
• Contact the printer vendor to obtain a different native printer driver. The
behavior you are experiencing may occur only with certain versions of the
native printer driver. If this doesn’t help and you are using Windows, try
reinstalling the drivers that were shipped with your Windows installation
disk.
• Export the figure to a graphics-format file and then import it into another
application before printing it. For information about exporting figures with
MATLAB, see “Exporting”.
When I use the print command with the -deps switch, I receive this error message.
Encapsulated PostScript files cannot be sent to the printer.
File saved to disk under name 'figure2.eps'
As the error message indicates, your figure was saved to a file. EPS is a
graphics file format and cannot be sent to a printer using a printer driver. To
send your figure directly to a printer, try using one of the PostScript driver
switches. See the table of drivers in the print reference page. To print an EPS
file, you must first import it into a word processor or other software program.
6-56
Troubleshooting
Default Settings
My printer uses a different default paper type than MATLAB’s default type of “letter.” How can
I change the default paper type so that I won’t have to set it for each new figure?
You can set the default value for any property by adding a line to startup.m.
Adding the following line sets the default paper type to A4.
set(0,'DefaultFigurePaperType','A4');
In your call to set, combine the word Default with the name of the object
Figure and the property name PaperType.
I set the paper orientation to landscape, but each time I go to print a new figure, the orientation
setting is portrait again. How can I change the default orientation so that I won’t have to set
it for each new figure?
See the explanation for the question above. Adding the following line to
startup.m sets the default paper orientation to landscape.
set(0, 'DefaultFigurePaperOrient', 'landscape')
Printing Lines
My figure contains lines that use broken line styles. However, these lines print as solid lines.
Microsoft Windows 95 and Windows 98 do not support broken line styles for
lines whose width is greater than 1 pixel. Unfortunately, most printers produce
lines more than 1 pixel thick, so in most cases, Windows 95 and Windows 98
drivers produce solid lines, regardless of the setting of LineStyleOrder.
There are various ways you can work around this problem.
• Change the MATLAB default line width to 1 pixel wide, by adding this line
to the [MATLAB Settings] section of your MATLAB.INI file:
ThinLineStyles=1
This will result in thin lines, but the lines will print with the specified styles.
• Set the figure’s Renderer property to OpenGL:
6-57
6
Basic Printing and Exporting
set(gcf,'Renderer','OpenGL')
The printed output will match the displayed figure. See “Setting the
Rendering Method” for more information about the OpenGL renderer.
• Use a PostScript or Ghostscript printer driver. These drivers bypass the
Windows Print Manager.
I want the lines in my figure to print in black but they keep printing in color.
You must be using a color printer driver. You can specify a black-and-white
driver using the Print dialog box or print command, or you can use the Page
Setup dialog box to force the lines for the current figure to print in black. See
“Specifying Printed Color of Colored Lines and Text” for instructions on either
method.
A white line in my figure keeps coming out black when I print it.
There are two things that can cause this to happen. Most likely, the line is
positioned over a dark background. By default, MATLAB inverts your
background to white when you print, and changes any white lines over the
background to black. To avoid this, retain your background color when you
print. See “Retaining Background Colors”.
The other possibility is that you are using a Windows printer driver and the
printer is sending inaccurate color information to MATLAB. See “Correcting
Color Results with Windows Drivers”.
Printer
I am using a color printer, but my figure keeps printing in black and white.
By default, MATLAB uses a black-and-white printer driver. You need to
specify a color printer driver. For instructions, see “Printer Drivers”. If you are
already using a Windows color driver, the printer may be returning inaccurate
information about its color property. See “Correcting Color Results with
Windows Drivers”.
I have more than one printer connected to my system. How do I specify which one to print my
figure with?
6-58
Troubleshooting
Use the Print dialog box. On UNIX, you can also use the -P switch with the
print command. For instructions using either method, see “Selecting a
Printer”.
Rotated Text
I have some rotated text in my figure. It looks fine on the screen, but when I print it, the
resolution is poor.
You are probably using bitmapped fonts, which don’t rotate well. Try using
TrueType fonts instead.
ResizeFcn Warning
I get a warning about my ResizeFcn being used when I print my figure.
By default, MATLAB resizes your figure when converting it to printer
coordinates. Therefore, MATLAB calls any ResizeFcn you have created for the
figure and issues a warning. You can avoid this warning by setting the figure
to print at screen size.
Exporting Problems
Background Color
I generated a figure with a black background and selected “Use figure color” from the Copy
Options pane of the Preferences dialog box. But when I exported my figure, its background
was changed to white.
You must have exported your figure to a file. The settings in Copy Options
only apply to figures copied to the clipboard.
There are two ways to retain the displayed background color: use the Page
Setup dialog box or set the InvertHardCopy property to off. See “Retaining
Background Colors” for instructions on either method.
Default Settings
I want to export all of my figures using the same size. Is there some way to do this so that I
don’t have to set the size for each individual figure?
6-59
6
Basic Printing and Exporting
You can set the default value for any property by adding a line to startup.m.
Adding the following line sets the default figure size to 4-by-3 inches.
set(0,'DefaultFigurePaperPosition',[0 0 4 3]);
In your call to set, combine the word Default with the name of the object
Figure and the property name PaperPosition.
I use the clipboard to export my figures as metafiles. Is there some way to force all of my copy
operations to use the metafile format?
Use the Copy Options pane of the Preferences dialog box. Any settings made
here, including whether MATLAB copies your figure as a metafile or bitmap,
apply to all copy operations. See “Copy Options Preferences” for instructions.
Microsoft Word
I exported my figure to an EPS file and then tried to import it into my Word document. My
printout has an empty frame with an error message saying that my EPS picture was not saved
with a preview and will only print to a PostScript printer. How do I include a TIFF preview?
Use the print command with the -tiff switch. For example,
print -deps -tiff filename
Note that if you print to a nonPostScript printer with Word, the preview image
is used for printing. This is a low-resolution image that lacks the quality of an
EPS graphic. For more information about preview images and other aspects of
EPS files, see “EPS Files”.
When I try to resize my figure in Word, its quality suffers.
You must have used a bitmap format. Bitmap files generally do not resize well.
If you are going to export using a bitmap format, try to set the figure’s size
while it’s still in MATLAB. See “Size and Position of Printed or Exported
Figures” for instructions.
As an alternative, you can use one of the vector formats, EMF or EPS. Figures
exported in these formats can be resized in Word without affecting quality.
When I copy and paste figures into Word 97 and PowerPoint 97, they display correctly but do
not print under Windows 95. I usually get a blank sheet of paper.
6-60
Troubleshooting
This is a bug that occurs when using the metafile format for clipboard export.
Try using the bitmap clipboard format instead. If you use the graphical user
interface, see “Clipboard Formats”. If you use MATLAB commands, see
“Exporting to the Clipboard Using MATLAB Commands”.
I exported my figure as an EMF to the clipboard. When I paste it into Word, some of the labels
are printed incorrectly.
This problem occurs with some versions of Word and Windows. Try editing the
labels in Word.
File Format
I tried to import my exported figure into a word processing document, but I got an error saying
the file format is unrecognized.
There are two likely causes: you used the print command and forgot to specify
the export format, or your word processing program does not support the export
format. Include a format switch when you use the print command; simply
including the file extension is not sufficient. For instructions, see “Setting the
Export File Format”.
If this does not solve your problem, check what formats the word processor
supports. Also see the table, “Editable Formats in Other Applications”, which
lists some applications and the export formats they support.
I tried to append a figure to an EPS file, and received an error message.
You cannot append figures to an EPS file. The -append option is only valid for
PostScript files, which should not be confused with EPS files. PostScript is a
printer driver; EPS is a graphics file format.
Of the supported export formats, only HDF supports storing multiple figures,
but you must use the imwrite command to append them. For an example, see
the reference page for imwrite.
Size of Exported File
I’ve always used the EPS format to export my figures, but recently it started to generate huge
files. Some of my files are now several megabytes!
Your graphics have probably become complicated enough that MATLAB is
using the OpenGL or Z-buffer renderer instead of the Painter’s renderer. It
6-61
6
Basic Printing and Exporting
does this to improve display time or to handle attributes that Painter’s cannot,
such as lighting. However, using OpenGL or Z-buffer causes a bitmap to be
stored in your EPS file, which sometimes leads to a large file.
There are two ways to fix the problem. You can specify the Painter’s renderer
when you export to EPS, or you can use a bitmap format, such as TIFF. The
best renderer and type of format to use depend upon the figure. See “Bitmap
and Vector Formats” if you need help deciding. For information about the
rendering methods and how to set them, see “Setting the Rendering Method”.
Making Movies
I am processing a large number of frames in MATLAB. I would like these frames to be saved
as individual files for later conversion into a movie. How can I do this?
Use getframe to capture the frames, imwrite to write them to a file, and movie
to create a movie from the files. For more information about using getframe
and imwrite to capture and write the frames, see “Using the getframe
Command to Export a Graphic”. For more information about creating a movie
from the captured frames, see the reference page for movie.
You can also save multiple figures to an AVI file. AVI files can be used for
animated sequences that do not need MATLAB to run. However, they do
require an AVI viewer. For more information, see “Creating an AVI Format
Movie” in “Working Environment for MATLAB.”
Extended Operations
There are some Export operations that cannot be performed using the Export dialog box.
You need to use the print command to do any of the following operations:
• Export to a supported file format not listed in the Export dialog box. The
formats not available from the Export dialog box include HDF, some
variations of BMP and PCX, and the raw data versions of PBM, PGM, and
PPM. The second column of the table, Export Formats and Export-Only
Options, indicates when a format is not available from the Export dialog box.
• Specify a resolution.
• Specify one of the following options: TIFF preview, loose bounding box for
EPS files, compression quality for JPEG files, CMYK output on Windows.
• Perform batch exporting.
6-62
Troubleshooting
General Problems
Background Color
When I output my figure, its background is changed to white. How can I get it to have the
displayed background color?
By default, when you print or export a figure, MATLAB inverts the background
color to white. There are two ways to retain the displayed background color: use
the Page Setup dialog box or set the InvertHardCopy property to off. See
“Retaining Background Colors” for instructions on either method.
If you are exporting your figure to the clipboard, you can also use the Copy
Options pane of the Preferences dialog box. Setting the background here sets
it for all figures copied to the clipboard.
Default Settings
I need to produce diagrams for publications. There is a list of requirements that I must meet
for size of the figure, fonts types, etc. How can I do this easily and consistently?
You can set the default value for any property by adding a line to startup.m.
As an example, the following line sets the default axes label font size to 12.
set(0, 'DefaultAxesFontSize', 12);
In your call to set, combine the word Default with the name of the object Axes
and the property name FontSize.
Dimensions of Output
The dimensions of my output are huge. How can I make it smaller?
Check your settings for figure size and resolution, both of which affect the
output dimensions of your figure.
The default figure size is 8-by-6 inches. You can use the Page Setup dialog box
or the PaperPosition property to set the figure size. See “Size and Position of
Printed or Exported Figures”.
The default resolution depends on the export format or printer driver used. For
example, built-in MATLAB bitmap formats, like TIFF, have a default
resolution of 150 dpi. You can change the resolution by using the print
6-63
6
Basic Printing and Exporting
command and the -r switch. For default resolution values and instructions on
how to change them, see “Setting Resolution”.
I selected “Match Screen Size” from the Page Setup menu, but my output looks a little bigger,
and my font looks different.
You probably output your figure using a higher resolution than your screen
uses. Set your resolution to be the same as the screen’s.
As an alternative, if you are exporting your figure, see if your application
enables you to select a resolution. If so, import the figure at the same resolution
it was exported with. For more information about resolution and how to set it
when exporting, see “Setting Resolution”.
Axis and Tick Labels
When I resize my figure below a certain size, my x-axis label and the bottom half of the x-axis
tick labels are missing from the output.
Your figure size may be too small to accommodate the labels. Labels are
positioned a fixed distance from the x-axis. Since the x-axis itself is positioned
a relative distance away from the window’s edge, the label text may not fit. Try
using a larger figure size or smaller fonts. For instructions on setting the size
of your figure, see “Size and Position of Printed or Exported Figures”. For
information about setting font size, the “Text Properties” reference page.
In my output, the x-axis has fewer ticks than it did on the screen.
MATLAB has rescaled your ticks because the size of your output figure is
different from its displayed size. There are two ways to prevent this: select
Keep Screen Limits and Ticks from the Page Setup dialog box or set the
XTickMode, YTickMode, and ZTickMode properties to manual. See “Locking the
Ticks and Limits of the Axes” for details.
UI Controls
My figure contains UI Controls. How do I prevent them from appearing in my output?
Use the print command with the -noui switch. For details, see “Excluding
User Interface Controls from Output”.
6-64
Troubleshooting
Cropping
I can’t output my figure using the uncropped setting (i.e. a loose BoundingBox).
Only PostScript printer drivers and the EPS export format support uncropped
output. There is a workaround for Windows printer drivers, however. Using
the print command, save your figure to a file that can be printed later. For an
example see, “Printing an Uncropped Figure with a Windows Printer Driver”.
Text Object Font
I have a problem with text objects when printing with a PostScript printer driver or exporting
to EPS. The fonts are correct on the screen, but are changed in the output.
You have probably used a font that is not supported by EPS and PostScript. All
unsupported fonts are converted to Courier. See “PostScript and Ghostscript
Supported Fonts” for the list of the supported fonts.
6-65
6
Basic Printing and Exporting
6-66
7
Handle Graphics Objects
Overview
. . . . . . . . . . . . . . . . . . . . . 7-2
Graphics Object Hierarchy
. . . . . . . . . . . . . 7-3
Types of Graphics Objects . . . . . . . . . . . . . . 7-4
Object Properties . . . . . . . . . . . . . . . . . . 7-9
Graphics Object Creation Functions . . . . . . . . . 7-12
Setting and Querying Property Values . . . . . . . . 7-18
Setting Default Property Values . . . . . . . . . . . 7-23
Accessing Object Handles . . . . . . . . . . . . . . 7-30
Controlling Graphics Output
. . . . . . . . . . . . 7-37
Saving Handles in M-Files . . . . . . . . . . . . . . 7-48
Properties Changed by Built-In Functions . . . . . . 7-49
7
Handle Graphics Objects
Overview
This section discusses Handle Graphics objects and provides an introduction to
programming with MATLAB’s graphics and visualization features. It shows
how to:
• Create objects
• Set and query object properties
• Define default values
• Obtain the handles of existing objects
• Control target window for graphics output
7-2
Graphics Object Hierarchy
Graphics Object Hierarchy
Handle Graphics objects are the basic drawing elements used by MATLAB to
display data and to create graphical user interfaces (GUIs). Each instance of
an object is associated with a unique identifier called a handle. Using this
handle, you can manipulate the characteristics (called object properties) of an
existing graphics object. You can also specify values for properties when you
create a graphics object.
These objects are organized into a tree-structured hierarchy.
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Rectangle
Surface
Text
The hierarchical nature of Handle Graphics is based on the interdependencies
of the various graphics objects. For example, to draw a line object, MATLAB
needs an axes object to orient and provide a frame of reference to the line. The
axes, in turn, needs a figure window to display the line.
7-3
7
Handle Graphics Objects
Types of Graphics Objects
Graphics objects are interdependent so the graphics display typically contains
a variety of objects that, in conjunction, produce a meaningful graph or picture.
The following picture of a figure window contains a number of graphics objects.
Line
Figure
Text
Value of the Sine from Zero to Two Pi
1
0.5
Surface
<−sin(t) = .707
0.5
sin(t)
0
0
<−sin(t) = 0
−0.5
2
2
Axes
(3-D)
1
0
−0.5
0
−2 −2
sin(t) = −.707 −>
−1
−1
0
1
2
3
4
t = 0 to 2pi
5
6
7
50
100
10
Image
150
5
200
0
250
300
−5
−25
−20
−15
−10
−5
0
5
350
100
200
300
Axes
(2-D)
7-4
Patch
10
Types of Graphics Objects
Each type of graphics object has a corresponding creation function that you use
to create an instance of that class of object. Object creation functions have the
same names as the objects they create (e.g., the text function creates text
objects, the figure function creates figure objects, and so on).
Handle Graphics Objects
The following list summarizes the Handle Graphics objects.
The Root
At the top of the hierarchy is the root object. It corresponds to the computer
screen. There is only one root object and all other objects are its descendants.
You do not create the root object; it exists when you start MATLAB. You can,
however, set the values of root properties and thereby affect the graphics
display.
Figure
Figure objects are the individual windows on the root screen where MATLAB
displays graphics. MATLAB places no limits on the number of figure windows
you can create (your computer may, however). All figures are children of the
root and all other graphics objects are descendants of figures.
All functions that draw graphics (e.g., plot and surf) automatically create a
figure if one does not exist. If there are multiple figures within the root, one
figure is always designated as the “current” figure, and is the target for
graphics output.
Uicontrol
Uicontrol objects are user interface controls that execute callback routines
when users activate the object. There are a number of styles of controls such as
pushbuttons, listboxes, and sliders. Each device is designed to accept a certain
type of information from users. For example, listboxes are typically used to
provide a list of filenames from which you select one or more items for action
carried out by the control’s callback routine.
You can use uicontrols in combinations to construct control panels and dialog
boxes. Pop-up menus, editable text boxes, check boxes, pushbuttons, static text,
and frames compose this particular example.
7-5
7
Handle Graphics Objects
.
Pop-up menus provide a choice between
predefined items
Users type numerical values into
these editable text boxes
Check boxes indicate the choice made
by the user
Frames provide logical groupings
for other controls
Static text labels other uicontrols
Pushbuttons indicate an action
Uicontrol objects are children of figures and are therefore independent of axes.
Uimenu
Uimenu objects are pull-down menus that execute callback routines when
users select an individual menu item. MATLAB places uimenus on the figure
window menu bar, to the right of existing menus defined by the system. This
picture shows the top of an MS-Windows figure that has three top-level
uimenus defined (titled Workspace, Figure, and Axes). Two levels of submenus
are visible under Workspace top-level uimenu.
7-6
Types of Graphics Objects
Uimenus are children of figures and are therefore independent of axes.
Axes
Axes objects define a region in a figure window and orient their children within
this region. axes are children of figures and are parents of image, light, line,
patch, surface, and text objects.
All functions that draw graphics (e.g., plot, surf, mesh, and bar) create an axes
object if one does not exist. If there are multiple axes within the figure, one axes
is always designated as the “current” axes, and is the target for display of the
above mentioned graphics objects (uicontrols and uimenus are not children of
axes).
Image
A MATLAB image consists of a data matrix and possibly a colormap. There are
three basic image types that differ in the way that data matrix elements are
interpreted as pixel colors – indexed, intensity, and truecolor. Since images are
strictly 2-D, you can view them only at the default 2-D view.
Light
Light objects define light sources that affect all patch and surface objects
within the axes. You cannot see lights, but you can set properties that control
the style of light source, color, location, and other properties common to all
graphics objects.
Line
Line objects are the basic graphics primitives used to create most 2-D and some
3-D plots. High-level functions plot, plot3, and loglog (and others) create line
objects. The coordinate system of the parent axes positions and orients the line.
7-7
7
Handle Graphics Objects
Patch
Patch objects are filled polygons with edges. A single patch can contain
multiple faces, each colored independently with solid or interpolated colors.
fill, fill3, and contour3 create patch objects. The coordinate system of the
parent axes positions and orients the patch.
Rectangle
Rectangle objects are 2-D filled areas having a shape that can range from a
rectangle to an ellipse. Rectangles are useful for creating flow-chart type
drawings.
Surface
Surface objects are 3-D representations of matrix data created by plotting the
value of each matrix element as a height above the x-y plane. Surface plots are
composed of quadrilaterals whose vertices are specified by the matrix data.
MATLAB can draw surfaces with solid or interpolated colors or with only a
mesh of lines connecting the points. The coordinate system of the parent axes
positions and orients the surface.
The high-level function pcolor and the surf and mesh group of functions create
surface objects.
Text
Text objects are character strings. The coordinate system of the parent axes
positions the text. The high-level functions title, xlabel, ylabel, zlabel, and
gtext create text objects.
7-8
Object Properties
Object Properties
A graphics object’s properties control many aspects of its appearance and
behavior. Properties include general information such as the object’s type, its
parent and children, whether it is visible, as well as information unique to the
particular class of object.
For example, from any given figure object you can obtain the identity of the last
key pressed in the window, the location of the pointer, or the handle of the most
recently selected menu.
MATLAB organizes graphics information into a hierarchy and stores this
information in properties. For example, root properties contain the handle of
the current figure and the current location of the pointer (cursor), figure
properties maintain lists of their descendants and keep track of certain events
that occur within the window, and axes properties contain information about
how each of its child objects uses the figure colormap and the color order used
by the plot function.
Changing Values
You can query the current value of any property and specify most property
values (although some are set by MATLAB and are read only). Property values
apply uniquely to a particular instance of an object; setting a value for one
object does not change this value for other objects of the same type.
Default Values
You can set default values that affect all subsequently created objects.
Whenever you do not define a value for a property, either as a default or when
you create the object, MATLAB uses “factory-defined” values.
The reference entry for each object creation function provides a complete list of
the properties associated with that class of graphics object.
7-9
7
Handle Graphics Objects
Properties Common to All Objects
Some properties are common to all graphics objects, as illustrated in the
following table.
7-10
Property
Information Contained
BusyAction
Controls the way MATLAB handles callback
routine interruption defined for the particular
object
ButtonDownFcn
Callback routine that executes when button press
occurs
Children
Handles of all this object’s children objects
Clipping
Mode that enables or disables clipping (meaningful
only for axes children)
CreateFcn
Callback routine that executes when this type of
object is created
DeleteFcn
Callback routine that executes when you issue a
command that destroys the object
HandleVisibility
Allows you to control the availability of the object’s
handle from the command line and from within
callback routines
Interruptible
Determines whether a callback routine can be
interrupted by a subsequently invoked callback
routine
Parent
The object’s parent
Selected
Indicates whether object is selected
SelectionHighlight
Specifies whether object visually indicates the
selection state
Tag
User-specified object label
Type
The type of object (figure, line, text, etc.)
Object Properties
Property
Information Contained
UserData
Any data you want to associate with the object
Visible
Determines whether or not the object is visible
7-11
7
Handle Graphics Objects
Graphics Object Creation Functions
Each graphics object (except the root object) has a corresponding creation
function, named for the object it creates. This table lists the creation functions.
7-12
Function
Object Description
axes
Rectangular coordinate system that scales and
orients axes children image, light, line, patch,
surface, and text objects.
figure
Window for displaying graphics.
image
2-D picture defined by either colormap indices or
RGB values. The data can be 8-bit or double
precision data.
light
Directional light source located within the axes
and affecting patches and surfaces.
line
Line formed by connecting the coordinate data
with straight line segments, in the sequence
specified.
patch
Polygonal shell created by interpreting each
column in the coordinate matrices as a separate
polygon.
rectangle
2-D filled area having a shape that can range from
a rectangle to an ellipse.
surface
Surface created with rectangular faces defined by
interpreting matrix elements as heights above a
plane.
text
Character string located in the axes coordinate
system.
uicontextmenu
Context menu that you can associate with other
graphics object.
Graphics Object Creation Functions
Function
Object Description
uicontrol
Programmable user-interface device, such as
pushbutton, slider, or listbox.
uimenu
Programmable menu appearing at the top of a
figure window.
All object creation functions have a similar format.
handle = function('propertyname',propertyvalue,...)
You can specify a value for any object property (except those that are read only)
by passing property name/property value pairs as arguments. The function
returns the handle of the object it creates, which you can use to query and
modify properties after creating the object.
Example – Creating Graphics Objects
This code evaluates a mathematical function and creates three graphics objects
using the property values specified as arguments to the figure, axes, and
surface commands. MATLAB uses default values for all other properties.
[x,y] = meshgrid([−2:.4:2]);
Z = x.*exp(−x.^2−y.^2);
fh = figure('Position',[350 275 400 300],'Color','w');
ah = axes('Color',[.8 .8 .8],'XTick',[−2 −1 0 1 2],...
'YTick',[−2 −1 0 1 2]);
sh = surface('XData',x,'YData',y,'ZData',Z,...
'FaceColor',get(ah,'Color')+.1,...
'EdgeColor','k','Marker','o',...
'MarkerFaceColor',[.5 1 .85]);
7-13
7
Handle Graphics Objects
2
1
0
−1
−2
−2
−1
0
1
2
Note that the surface function does not use a 3-D view like the high-level surf
functions. Object creation functions simply add new objects to the current axes
without changing axes properties, except the Children property, which now
includes the new object and the axis limits (XLim, YLim, and ZLim), if necessary.
You can change the view using the camera commands or use the view
command.
view(3)
7-14
Graphics Object Creation Functions
0.5
0
−0.5
2
1
2
1
0
0
−1
−2
−1
−2
Parenting
By default, all statements that create graphics objects do so in the current
figure and the current axes (if the object is an axes child). However, you can
specify the parent of an object when you create it. For example, the statement,
axes('Parent',figure_handle,...)
creates an axes in the figure identified by figure_handle. You can also move
an object from one parent to another by redefining its Parent property.
set(gca,'Parent',figure_handle)
High-Level Versus Low-Level
MATLAB’s high-level graphics routines (e.g., plot or surf) call the appropriate
object creation function to draw graphics objects. However, high-level routines
also clear the axes or create a new figure, depending on the settings of the axes
and figure NextPlot properties.
7-15
7
Handle Graphics Objects
In contrast, object creation functions simply create their respective graphics
objects and place them in the current parent object. They do not respect the
setting of the figure or axes NextPlot property.
For example, if you call the line function,
line('XData',x,'YData',y,'ZData',z,'Color','r')
MATLAB draws a red line in the current axes using the specified data values.
If there is no axes, MATLAB creates one. If there is no figure window in which
to create the axes, MATLAB creates it as well.
If you call the line function a second time, MATLAB draws the second line in
the current axes without erasing the first line. This behavior is different from
high-level functions like plot that delete graphics objects and reset all axes
properties (except Position and Units). You can change the behavior of
high-level functions using the hold command or changing the setting of the
axes NextPlot property.
See the “Controlling Graphics Output” section in this chapter for more
information on this behavior and on using the NextPlot property.
Simplified Calling Syntax
Object creation functions have convenience forms that allow you to use a
simpler syntax. For example,
text(.5,.5,.5,'Hello')
is equivalent to,
text('Position',[.5 .5 .5],'String','Hello')
Note that using the convenience form of an object creation function can cause
subtle differences in behavior when compared to formal property name/
property value syntax.
A Note About Property Names
By convention, MATLAB documentation capitalizes the first letter of each
word that makes up a property name, such as LineStyle or XTickLabelMode.
While this makes property names easier to read, MATLAB does not check for
uppercase letters. In addition, you need use only enough letters to identify the
name uniquely, so you can abbreviate most property names.
7-16
Graphics Object Creation Functions
In M-files, however, using the full property name can prevent problems with
futures releases of MATLAB if a shortened name is no longer unique because
of the addition of new properties.
7-17
7
Handle Graphics Objects
Setting and Querying Property Values
The set and get functions specify and retrieve the value of existing graphics
object properties. They also enable you to list possible values for properties that
have a fixed set of values. (You can also use the Property Editor to set many
property values. See “Using the Property Editor” on page 1-15 for more
information.)
The basic syntax for setting the value of a property on an existing object is
set(object_handle,'PropertyName','NewPropertyValue')
To query the current value of a specific object’s property, use a statement like
returned_value = get(object_handle,'PropertyName');
Property names are always quoted strings. Property values depend on the
particular property.
See the “Accessing Object Handles” section in this chapter and the findobj
command for information on finding the handles of existing object.
Setting Property Values
You can change the properties of an existing object using the set function and
the handle returned by the creating function. For example, this statement
moves the y-axis to the right side of the plot on the current axes.
set(gca,'YAxisLocation','right')
If the handle argument is a vector, MATLAB sets the specified value on all
identified objects.
You can specify property names and property values using structure arrays or
cell arrays. This can be useful if you want to set the same properties on a
number of objects. For example, you can define a structure to set axes
properties appropriately to display a particular graph.
view1.CameraViewAngleMode = 'manual';
view1.DataAspectRatio = [1 1 1];
view1.ProjectionType = 'Perspective';
To set these values on the current axes, type
set(gca,view1)
7-18
Setting and Querying Property Values
Listing Possible Values
You can use set to display the possible values for many properties without
actually assigning a new value. For example, this statement obtains the values
you can specify for line object markers.
set(obj_handle,'Marker')
MATLAB returns a list of values for the Marker property for the type of object
specified by obj_handle. Braces indicate the default value.
[ + | o | * | . | x | square | diamond | v | ^ | > | < | pentagram
| hexagram | {none} ]
To see a list of all settable properties along with possible values of properties
that accept string values, use set with just an object handle.
set(object_handle)
For example, for a surface object, MATLAB returns
CData
CDataScaling: [ {on} | off]
EdgeColor: [ none | {flat} | interp ] ColorSpec.
EraseMode: [ {normal} | background | xor | none ]
FaceColor: [ none | {flat} | interp | texturemap ] ColorSpec.
LineStyle: [ {−} | −− | : | −. | none ]
.
.
.
Visible: [ {on} | off ]
If you assign the output of the set function to a variable, MATLAB returns the
output as a structure array. For example,
a = set(gca);
The field names in a are the object’s property names and the field values are
the possible values for the associated property. For example,
a.GridLineStyle
ans =
'-'
'--'
7-19
7
Handle Graphics Objects
':'
'-.'
'none'
returns the possible value for the axes grid line styles. Note that while property
names are not case sensitive, MATLAB structure field names are. For example,
a.gridlinestyle
??? Reference to non-existent field 'gridlinestyle'.
returns an error.
Querying Property Values
Use get to query the current value of a property or of all the object’s properties.
For example, check the value of the current axes PlotBoxAspectRatio
property.
get(gca,'PlotBoxAspectRatio')
ans =
1
1
1
MATLAB lists the values of all properties, where practical. However, for
properties containing data, MATLAB lists the dimensions only (for example,
CurrentPoint and ColorOrder).
AmbientLightColor = [1 1 1]
Box = off
CameraPosition = [0.5 0.5 2.23205]
CameraPositionMode = auto
CameraTarget = [0.5 0.5 0.5]
CameraTargetMode = auto
CameraUpVector = [0 1 0]
CameraUpVectorMode = auto
CameraViewAngle = [32.2042]
CameraViewAngleMode = auto
CLim: [0 1]
CLimMode: auto
Color: [0 0 0]
CurrentPoint: [ 2x3 double]
ColorOrder: [ 7x3 double]
7-20
Setting and Querying Property Values
.
.
.
Visible = on
Querying Individual Properties
You can obtain the data from the property by getting that property
individually.
get(gca,'ColorOrder')
ans =
0
0
0
0.5000
1.0000
0
0
0.7500
0.7500
0
0.7500
0.7500
0.2500
0.2500
1.0000
0
0
0.7500
0.7500
0
0.2500
Returning a Structure
If you assign the output of get to a variable, MATLAB creates a structure array
whose field names are the object property names and whose field values are the
current values of the named property.
For example, if you plot some data, x and y,
h = plot(x,y);
and get the properties of the line object created by plot,
a = get(h);
you can access the values of the line properties using the field name. This call
to the text command places the string 'x and y data' at the first data point
and colors the text to match the line color.
text(x(1),y(1),'x and y data','Color',a.Color)
If x and y are matrices, plot draws one line per column. To label the plot of the
second column of data, reference that line.
text(x(1,2),y(1,2),'Second set of data','Color',a(2).Color)
7-21
7
Handle Graphics Objects
Querying Groups of Properties
You can define a cell array of property names and conveniently use it to obtain
the values for those properties. For example, suppose you want to query the
values of the axes “camera mode” properties. First define the cell array.
camera_props(1)
camera_props(2)
camera_props(3)
camera_props(4)
=
=
=
=
{'CameraPositionMode'};
{'CameraTargetMode'};
{'CameraUpVectorMode'};
{'CameraViewAngleMode'};
Use this cell array as an argument to obtain the current values of these
properties.
get(gca,camera_props)
ans =
'auto' 'auto' 'auto' 'auto'
Factory-Defined Property Values
MATLAB defines values for all properties, which are used if you do not specify
values as arguments or as defaults. You can obtain a list of all factory-defined
values with the statement.
a = get(0,'Factory');
get returns a structure array whose field names are the object type and
property name concatenated together, and field values are the factory value for
the indicated object and property. For example, this field,
UimenuSelectionHighlight: 'on'
indicates that the factory value for the SelectionHighlight property on
uimenu objects is on.
You can get the factory value of an individual property with,
get(0,'FactoryObjectTypePropertyName')
For example,
get(0,'FactoryTextFontName')
7-22
Setting Default Property Values
Setting Default Property Values
All object properties have “default” values built into MATLAB (i.e.,
factory-defined values). You can also define your own default values at any
point in the object hierarchy.
How MATLAB Searches for Default Values
MATLAB’s search for a default value begins with the current object and
continues through the object’s ancestors until it finds a user-defined default
value or until it reaches the factory-defined value. Therefore, a search for
property values is always satisfied.
The closer to the root of the hierarchy you define the default, the broader its
scope. If you specify a default value for line objects on the root level, MATLAB
uses that value for all lines (since the root is at the top of the hierarchy). If you
specify a default value for line objects on the axes level, then MATLAB uses
that value for line objects drawn only in that axes.
If you define default values on more than one level, the value defined on the
closest ancestor takes precedence since MATLAB terminates the search as
soon as it finds a value.
Note that setting default values affects only those objects created after you set
the default. Existing graphics objects are not affected.
This diagram shows the steps MATLAB follows in determining the value of a
graphics object property.
7-23
7
Handle Graphics Objects
For all properties
Is property
value defined
as argument?
YES
Use property
value specified
as argument
YES
Use Axes-level
default value
YES
Use Figure-level
default value
YES
Use Root-level
default value
NO
Is default
defined on
Axes level?
NO
Is default
defined on
Figure level?
NO
Is default
defined on
Root level?
NO
Use factorydefined default
property value
7-24
Setting Default Property Values
Defining Default Values
To specify default values, create a string beginning with the word Default
followed by the object type and finally the object property. For example, to
specify a default value of 1.5 points for the line LineWidth property at the level
of the current figure, use the statement,
set(gcf,'DefaultLineLineWidth',1.5)
The string, DefaultLineLineWidth identifies the property as a line property.
To specify the figure color, use DefaultFigureColor. Note that it is meaningful
to specify a default figure color only on the root level.
set(0,'DefaultFigureColor','b')
Use get to determine what default values are currently set on any given object
level; for example,
get(gcf,'default')
returns all default values set on the current figure.
Setting Properties to the Default
Specifying a property value of 'default' sets the property to the first
encountered default value defined for that property. For example, these
statements result in a green surface EdgeColor,
set(0,'DefaultSurfaceEdgeColor','k')
h = surface(peaks);
set(gcf,'DefaultSurfaceEdgeColor','g')
set(h,'EdgeColor','default')
Since a default value for surface EdgeColor exists on the figure level, MATLAB
encounters this value first and uses it instead of the default EdgeColor defined
on the root.
Removing Default Values
Specifying a property value of 'remove' gets rid of user-defined default values.
The statement,
set(0,'DefaultSurfaceEdgeColor','remove')
removes the definition of the default Surface EdgeColor from the root.
7-25
7
Handle Graphics Objects
Setting Properties to Factory-Defined Values
Specifying a property value of 'factory' sets the property to its
factory-defined value. (The property descriptions provides access to the factory
settings for properties having predefined sets of values.)
For example, these statements set the EdgeColor of surface h to black (its
factory setting) regardless of what default values you have defined.
set(gcf,'DefaultSurfaceEdgeColor','g')
h = surface(peaks);
set(h,'EdgeColor','factory')
Reserved Words
Setting a property value to default, remove, or factory produces the effect
described in the previous sections. To set a property to one of these words (e.g.,
a text or uicontrol String property set to the word ”Default”), you must
precede the word with the backslash character. For example,
h = uicontrol('Style','edit','String','\Default');
Examples – Setting Default LineStyles
The plot function cycles through the colors defined by the axes ColorOrder
property when displaying multiline plots. If you define more than one value for
the axes LineStyleOrder property, MATLAB increments the linestyle after
each cycle through the colors.
You can set default property values that cause the plot function to produce
graphs using varying linestyles, but not varying colors. This is useful when
working on a monochrome display or printing on a black and white printer.
First Example
This example creates a figure with a white plot (axes) background color, then
sets default values for axes objects on the root level.
whitebg('w') %create a figure with a white color scheme
set(0,'DefaultAxesColorOrder',[0 0 0],...
'DefaultAxesLineStyleOrder','−|−−|:|−.')
Whenever you call plot,
Z = peaks; plot(1:49,Z(4:7,:))
7-26
Setting Default Property Values
it uses one color for all data plotted because the axes ColorOrder contains only
one color, but cycles through the linestyles defined for LineStyleOrder.
0.5
0
−0.5
−1
−1.5
−2
−2.5
−3
−3.5
0
10
20
30
40
50
Second Example
This example sets default values on more than one level in the hierarchy. These
statements create two axes in one figure window, setting default values on the
figure level and the axes level.
t = 0:pi/20:2*pi;
s = sin(t);
c = cos(t);
% Set default value for axes Color property
figh = figure('Position',[30 100 800 350],...
'DefaultAxesColor',[.8 .8 .8]);
axh1 = subplot(1,2,1); grid on
% Set default value for line LineStyle property in first axes
set(axh1,'DefaultLineLineStyle','–.')
line('XData',t,'YData',s)
line('XData',t,'YData',c)
text('Position',[3 .4],'String','Sine')
text('Position',[2 –.3],'String','Cosine',...
7-27
7
Handle Graphics Objects
'HorizontalAlignment','right')
axh2 = subplot(1,2,2); grid on
% Set default value for text Rotation property in second axes
set(axh2,'DefaultTextRotation',90)
line('XData',t,'YData',s)
line('XData',t,'YData',c)
text('Position',[3 .4],'String','Sine')
text('Position',[2 –.3],'String','Cosine',...
'HorizontalAlignment','right')
Issuing the same line and text statements to each subplot region results in a
different display, reflecting different default settings.
1
0.5
Sine
1
0.5
Sine
0
0
−1
Cosine
Cosine
−0.5
−0.5
0
2
4
6
8
−1
0
2
4
6
8
Since the default axes Color property is set on the figure level of the hierarchy,
MATLAB creates both axes with the specified gray background color.
The axes on the left (subplot region 121) defines a dash–dot line style (−.) as
the default, so each call to the line function uses dash–dot lines. The axes on
the right does not define a default linestyle so MATLAB uses solid lines (the
factory setting for lines).
The axes on the right defines a default text Rotation of 90 degrees, which
rotates all text by this amount. MATLAB obtains all other property values
from their factory settings, which results in nonrotated text on the left.
7-28
Setting Default Property Values
To install default values whenever you run MATLAB, specify them in your
startup.m file. Note that MATLAB may install default values for some
appearance properties when started by calling the colordef command.
7-29
7
Handle Graphics Objects
Accessing Object Handles
MATLAB assigns a handle to every graphics object it creates. All object
creation functions optionally return the handle of the created object. If you
want to access the object’s properties (e.g., from an M-file) you should assign its
handle to a variable at creation time to avoid searching for it later. However,
you can always obtain the handle of an existing object with the findobj
function or by listing its parent’s Children property. The “Protecting Figures
and Axes” section in this chapter provides for more information on how object
handles are hidden from normal access.
The root object’s handle is always zero. The handle of a figure is either:
• An integer that, by default, displays in the window title bar
• A floating point number requiring full MATLAB internal precision
The figure IntegerHandle property controls which type of handle the figure
receives.
All other graphics object handles are floating-point numbers. You must
maintain the full precision of these numbers when you reference handles.
Rather than attempting to read handles off the screen and retype them, it is
necessary to store the value in a variable and pass that variable whenever a
handle is required.
The Current Figure, Axes, and Object
An important concept in Handle Graphics is that of being current. The current
figure is the window designated to receive graphics output. Likewise, the
current axes is the target for commands that create axes children. The current
object is the last graphics object created or clicked on by the mouse.
MATLAB stores the three handles corresponding to these objects in the
ancestor’s property list.
7-30
Accessing Object Handles
Root
Current Figure
CurrentFigure
CurrentAxes
CurrentObject
Current Axes
Current Object
These properties enable you to obtain the handles of these key objects.
get(0,'CurrentFigure');
get(gcf,'CurrentAxes');
get(gcf,'CurrentObject');
The following commands are shorthand notation for the get statements.
• gcf – returns the value of the root CurrentFigure property
• gca – returns the value of the current figure’s CurrentAxes property
• gco – returns the value of the current figure’s CurrentObject property
You can use these commands as input arguments to functions that require
object handles. For example, you can click on a line object and then use gco to
specify the handle to the set command,
set(gco,'Marker','square')
or list the values of all current axes properties with
get(gca)
You can get the handles of all the graphic objects in the current axes (except
those with hidden handles),
h = get(gca,'Children');
and then determine the types of the objects.
get(h,'type')
ans =
'text'
'patch'
'surface'
'line'
7-31
7
Handle Graphics Objects
While gcf and gca provide a simple means of obtaining the current figure and
axes handles, they are less useful in M-files. This is particularly true if your
M-file is part of an application layered on MATLAB where you do not
necessarily have knowledge of user actions that can change these values.
See the “Controlling Graphics Output” section in this chapter for information
on how to prevent users from accessing the handles of graphics objects that you
want to protect.
Searching for Objects by Property Values — findobj
The findobj function provides a means to traverse the object hierarchy quickly
and obtain the handles of objects having specific property values. If you do not
specify a starting object, findobj searches from the root object, finding all
occurrences of the property name/property value combination you specify.
Example – Finding Objects
This plot of the sine function contains text objects labeling particular values of
function.
Value of the Sine from Zero to Two Pi
1
←sin(t) = .707 ←sin(t) = .707
sin(t)
0.5
←sin(t) = 0
0
−0.5
sin(t) = −.707 →
−1
0
1
2
3
4
t = 0 to 2pi
5
6
7
Suppose you want to move the text string labeling the value sin(t) = .707 from
its current location at [pi/4,sin(pi/4)] to the point [3*pi/4,sin(3*pi/4)]
7-32
Accessing Object Handles
where the function has the same value (shown grayed out in the picture). To do
this, you need to determine the handle of the text object labeling that point and
change its Position property.
To use findobj, pick a property value that uniquely identifies the object. In
this case, the text String property.
text_handle = findobj('String','\leftarrowsin(t) = .707');
Next move the object to the new position, defining the text Position in axes
units.
set(text_handle,'Position',[3*pi/4,sin(3*pi/4),0])
findobj also lets you restrict the search by specifying a starting point in the
hierarchy, instead of beginning with the root object. This results in faster
searches if there are many objects in the hierarchy. In the previous example,
you know the text object of interest is in the current axes so you can type
text_handle = findobj(gca,'String','\leftarrowsin(t) = .707');
Copying Objects
You can copy objects from one parent to another using the copyobj function.
The new object differs from the original object only in the value of its Parent
property and its handle; it is otherwise a clone of the original. You can copy a
number of objects to a new parent, or one object to a number of new parents as
long as the result maintains the correct parent/child relationship.
When you copy an object having children objects, MATLAB copies all children
as well.
Example – Copying Objects
Suppose you are plotting a variety of data and want to label the point having
the x- and y-coordinates determined by 5π ÷ 4, sin 〈 5π ÷ 4〉 in each plot. The
text function allows you to specify the location of the label in the coordinates
defined by the x- and y-axis limits, simplifying the process of locating the text.
text('String','\{5\pi\div4, sin(5\pi\div4)\}\rightarrow',...
'Position',[5*pi/4,sin(5*pi/4),0],...
'HorizontalAlignment','right')
7-33
7
Handle Graphics Objects
In this statement, the text function:
• Labels the data point with the string { 5π ÷ 4, sin 〈 5π ÷ 4〉 } using TeX
commands to draw a right-facing arrow and mathematical symbols.
• Specifies the Position in terms of the data being plotted.
• Places the data point to the right of the text string by changing the
HorizontalAlignment to right (the default is left).
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
{5π÷4, sin(5π÷4)}→
−0.8
−1
0
1
2
3
4
5
6
7
8
To label the same point with the same string in another plot, copy the text
using copyobj. Since the last statement did not save the handle to the text
object, you can find it using findobj and the 'String' property.
text_handle = findobj('String',...
'\{5\pi\div4,sin(5\pi\div4)\}\rightarrow');
After creating the next plot, add the label by copying it from the first plot.
copyobj(text_handle,gca).
7-34
Accessing Object Handles
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
{5π÷4, sin(5π÷4)}→
−0.8
−1
0
1
2
3
4
5
6
7
8
This particular example takes advantage of the fact that text objects define
their location in the axes’ data space. Therefore the text Position property did
not need to change from one plot to another.
Deleting Objects
You can remove a graphics object with the delete command, using the object’s
handle as an argument. For example, you can delete the current axes (and all
of its descendants) with the statement
delete(gca)
You can use findobj to get the handle of a particular object you want to delete.
For example, to find the handle of the dotted line in this multiline plot,
7-35
7
Handle Graphics Objects
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
use findobj to locate the object whose LineStyle property is ’:’
line_handle = findobj('LineStyle',':');
then use this handle with the delete command.
delete(line_handle)
You can combine these two statements, substituting the findobj statement for
the handle.
delete(findobj('LineStyle',':'))
7-36
Controlling Graphics Output
Controlling Graphics Output
MATLAB allows many figure windows to be open simultaneously during a
session. A MATLAB application may create figures to display graphical user
interfaces as well as plotted data. It is necessary then to protect some figures
from becoming the target for graphics display and to prepare (e.g., reset
properties and clear existing objects from) others before receiving new
graphics.
This section discusses how to control where and how MATLAB displays
graphics output. Topics include:
• Specifying the target for graphics output
• Preparing the figure and axes to accept new objects
• Protecting figures and axes from becoming targets
• Accessing the handles of protected figure and axes
Specifying the Target for Graphics Output
By default, MATLAB functions that create graphics objects display them in the
current figure and current axes (if an axes child). You can direct the output to
another parent by explicitly specifying the Parent property with the creating
function. For example,
plot(1:10,'Parent',axes_handle)
where axes_handle is the handle of the target axes. The uicontrol and uimenu
functions have a convenient syntax that enables you to specify the parent as
the first argument,
uicontrol(Figure_handle,...)
uimenu(parent_menu_handle,...)
or you can set the Parent property.
Preparing Figures and Axes for Graphics
By default, commands that generate graphics output display the graphics
objects in the current figure without clearing or resetting figure properties.
However, if the graphics objects are axes children, MATLAB clears the axes
and resets most axes properties to their default values before displaying the
objects.
7-37
7
Handle Graphics Objects
You can change this behavior by setting the figure and axes NextPlot
properties.
Using NextPlot to Control Output Target
MATLAB high-level graphics functions check the value of the NextPlot
properties to determine whether to add, clear, or clear and reset the figure and
axes before drawing. Low-level object creation functions do not check the
NextPlot properties. They simply add the new graphics objects to the current
figure and axes.
Low-level functions are designed primarily for use in M-files where you can
implement whatever drawing behavior you want. However, when you develop
a MATLAB-based application, controlling MATLAB’s drawing behavior is
essential to creating a program that behaves predictably.
This table summarizes the possible values for the NextPlot property.
NextPlot
Figure
Axes
add
Add new graphics objects without
clearing or resetting the current
figure. (Default setting)
Add new graphics objects without
clearing or resetting the current
axes.
replacechildren
Remove all child objects, but do not
reset figure properties. Equivalent
to clf.
Remove all child objects, but do not
reset axes properties. Equivalent to
cla.
replace
Remove all child objects and reset
figure properties to their defaults.
Equivalent to clf reset.
Remove all child objects and reset
axes properties to their defaults.
Equivalent to cla reset. (Default
setting)
Note that a reset returns all properties, except Position and Units, to their
default values.
The hold command provides convenient access to the NextPlot properties. The
statement
hold on
sets both figure and axes NextPlot to add.
7-38
Controlling Graphics Output
The statement
hold off
sets the axes NextPlot property to replace.
Targeting Graphics Output with newplot
MATLAB provides the newplot function to simplify the process of writing
graphics M-files that conform to the settings of the NextPlot properties.
newplot checks the values of the NextPlot properties and takes the
appropriate action based on these values. You should place newplot at the
beginning of any M-file that calls object creation functions.
When your M-file calls newplot, the following possible actions occur:
1 newplot checks the current figure’s NextPlot property:
- If there are no figures in existence, newplot creates one and makes it the
current figure.
- If the value of NextPlot is add, newplot makes the figure the current
figure.
- If the value of NextPlot is replacechildren, newplot deletes the figure’s
children (axes objects and their descendents) and makes this figure the
current figure.
- If the value of NextPlot is replace, newplot deletes the figure’s children,
resets the figure’s properties to the defaults, and makes this figure the
current figure.
2 newplot checks the current axes’ NextPlot property:
- If there are no axes in existence, newplot creates one and makes it the
current axes.
- If the value of NextPlot is add, newplot makes the axes the current axes.
- If the value of NextPlot is replacechildren, newplot deletes the axes’
children and makes this axes the current axes.
- If the value of NextPlot is replace, newplot deletes the axes’ children,
resets the axes’ properties to the defaults, and makes this axes the current
axes.
7-39
7
Handle Graphics Objects
MATLAB’s Default Behavior
Consider the default situation where the figure NextPlot property is add and
the axes NextPlot property is replace. When you call newplot, it:
1 Checks the value of the current figure’s NextPlot property (which is add)
and determines MATLAB can draw into the current figure with no further
action (if there is no current figure, newplot creates one, but does not
recheck its NextPlot property).
2 Checks the value of the current axes’ NextPlot property (which is replace),
deletes all graphics objects from the axes, reset all axes properties (except
Position and Units) to their defaults, and returns the handle of the current
axes.
Example – Using newplot
To illustrate the use of newplot, this example creates a function that is similar
to the built-in plot function, except it automatically cycles through different
line styles instead of using different colors for multiline plots.
function my_plot(x,y)
cax = newplot; % newplot returns handle of current axes
LSO = ['- ';'--';': ';'-.'];
set(cax,'FontName','Times','FontAngle','italic')
set(get(cax,'Parent'),'MenuBar','none') %
line_handles = line(x,y,'Color','b');
style = 1;
for i = 1:length(line_handles)
if style > length(LSO), style = 1;end
set(line_handles(i),'LineStyle',LSO(style,:))
style = style + 1;
end
grid on
The function my_plot uses the high-level line function syntax to plot the data.
This provides the same flexibility in input argument dimension that the
built-in plot function supports. The line function does not check the value of
the figure or axes NextPlot property. However, because my_plot calls newplot,
it behaves the same way the high-level plot function does – with default values
in place, my_plot clears and resets the axes each time you call it.
7-40
Controlling Graphics Output
my_plot uses the handle returned by newplot to access the target figure and
axes. This example sets axes font properties and disables the figure’s menu bar.
Note how the figure handle is obtained via the axes Parent property.
This picture shows typical output for the my_plot function.
my_plot(1:10,peaks(10))
8
6
4
2
0
−2
−4
−6
−8
1
2
3
4
5
6
7
8
9
10
Basic Plotting M-file Structure
This example illustrates the basic structure of graphics M-files:
• Call newplot early to conform to the NextPlot properties and to obtain the
handle of the target axes.
• Reference the axes handle returned by newplot to set any axes properties or
to obtain the figure’s handle.
• Call object creation functions to draw graphics objects with the desired
characteristics.
7-41
7
Handle Graphics Objects
MATLAB’s default settings for the NextPlot properties facilitate writing
M-files that adhere to MATLAB’s standard behavior: reuse the figure window,
but clear and reset the axes with each new graph. Other values for these
properties allow you to implement different behaviors.
Replacing Only the Children Objects — replacechildren
The replacechildren value for NextPlot causes newplot to remove child
objects from the figure or axes, but does not reset any property values (except
the list of handles contained in the Children property).
This can be useful after setting properties you want to use for subsequent
graphs without having to reset properties. For example, if you type on the
command line
set(gca,'ColorOrder',[0 0 1],'LineStyleOrder','-|--|:|-.',...
'NextPlot','replacechildren')
plot(x,y)
plot produces the same output as the M-file my_plot in the previous section,
but only within the current axes. Calling plot still erases the existing graph
(i.e., deletes the axes children), but it does not reset axes properties. The values
specified for the ColorOrder and LineStyleOrder properties remain in effect.
Testing for Hold State
There are situations in which your M-file should change the visual appearance
of the axes to accommodate new graphics objects. For example, if you want the
M-file my_plot from the previous example to accept 3-D data, it makes sense to
set the view to 3-D when the input data has z-coordinates.
However, to be consistent with the behavior of MATLAB’s high-level routines,
it is a good practice to test if hold is on before changing parent axes or figure
properties. When hold is on, the axes and figure NextPlot properties are both
set to add.
The M-file, my_plot3, accepts 3-D data and also checks the hold state, using
ishold, to determine if it should change the view.
function my_plot3(x,y,z)
cax = newplot;
hold_state = ishold; % ishold tests the current hold state
LSO = ['- ';'--';': ';'-.'];
7-42
Controlling Graphics Output
if nargin == 2
hlines = line(x,y,'Color','k');
if ~hold_state % Change view only if hold is off
view(2)
end
elseif nargin == 3
hlines = line(x,y,z,'Color','k');
if ~hold_state % Change view only if hold is off
view(3)
end
end
ls = 1;
for hindex = 1:length(hlines)
if ls > length(LSO),ls = 1;end
set(hlines(hindex),'LineStyle',LSO(ls,:))
ls = ls + 1;
end
If hold is on when you call my_plot3, it does not change the view. If hold is off,
my_plot3 sets the view to 2-D or 3-D, depending on whether there are two or
three input arguments.
Protecting Figures and Axes
There are situations in which it is important to prevent particular figures or
axes from becoming the target for graphics output (i.e., preventing them from
becoming the gcf or gca). An example is a figure containing the uicontrols that
implement a user interface.
You can prevent MATLAB from drawing into a particular figure or axes by
removing its handle from the list of handles that are visible to the newplot
function, as well as any other functions that either return or implicitly
reference handles (i.e., gca, gcf, gco, cla, clf, close, and findobj). Two
properties control handle hiding: HandleVisibility and ShowHiddenHandles.
HandleVisibility Property
HandleVisibility is a property of all objects. It controls the scope of handle
visibility within three different ranges. Property values can be:
• on – The object’s handle is available to any function executed on the
MATLAB command line or from an M-file. This is the default setting.
7-43
7
Handle Graphics Objects
• callback – The object’s handle is hidden from all functions executing on the
command line, even if it is on the top of the screen stacking order. However,
during callback routine execution (MATLAB statements or functions that
execute in response to user action), the handle is visible to all functions, such
as gca, gcf, gco, findobj, and newplot. This setting enables callback
routines to take advantage of MATLAB’s handle access functions, while
ensuring that users typing at the command line do not inadvertently disturb
a protected object.
• off – The object’s handle is hidden from all functions executing on the
command line and in callback routines. This setting is useful when you want
to protect objects from possibly damaging user commands.
For example, if a GUI accepts user input in the form of text strings, which are
then evaluated (using the eval function) from within the callback routine, a
string such as 'close all' could destroy the GUI. To protect against this
situation, you can temporarily set HandleVisibility to off on key objects.
user_input = get(editbox_handle,'String');
set(gui_handles,'HandleVisibility','off')
eval(user_input)
set(gui_handles,'HandleVisibility','commandline')
Values Returned by gca and gcf. When a protected figure is topmost on the screen,
but has nonprotected figures stacked beneath it, gcf returns the topmost
unprotected figure in the stack. The same is true for gca. If no unprotected
figures or axes exist, calling gcf or gca causes MATLAB to create one in order
to return its handle.
Accessing Protected Objects
The root ShowHiddenHandles property enables and disables handle visibility
control. By default, ShowHiddenHandles is off, which means MATLAB obeys
the setting of the HandleVisibility property. When set to on, all handles are
visible from the command line and within callback routines. This can be useful
when you want access to all graphics objects that exist at a given time,
including the handles of axes text labels, which are normally hidden.
The close function also allows access to nonvisible figures using the hidden
option. For example,
close('hidden')
7-44
Controlling Graphics Output
closes the topmost figure on the screen, even if it is protected. Combining all
and hidden options,
close('all','hidden')
closes all figures.
The Close Request Function
MATLAB executes a callback routine defined by the figure’s CloseRequestFcn
whenever you:
• Issue a close command on a figure.
• Quit MATLAB while there are visible figures. (If a figure’s Visible property
is set to off, MATLAB does not execute its close request function when you
quit MATLAB; the figure is just deleted).
• Close a figure from the windowing system using a close box or a close menu
item.
The close request function enables you to prevent or delay the closing of a
figure or the termination of a MATLAB session. This is useful to perform such
actions as:
• Displaying a dialog box requiring the user to confirm the action.
• Saving data before closing.
• Preventing unintentional command-line deletion of a graphical user
interface built with MATLAB.
The default callback routine for the CloseRequestFcn is an M-file called
closereq. It contains the statements
shh=get(0,'ShowHiddenHandles');
set(0,'ShowHiddenHandles','on');
delete(get(0,'CurrentFigure'));
set(0,'ShowHiddenHandles',shh);
This callback disables HandleVisibility control by setting the root
ShowHiddenHandles property to on, which makes all figure handles visible.
7-45
7
Handle Graphics Objects
Quitting MATLAB
When you quit MATLAB, the current figure’s CloseRequestFcn is called, and
if the figure is deleted, the next figure in the root's list of children (i.e., the root's
Children property) becomes the current figure, and its CloseRequestFcn is in
turn executed, and so on. You can, therefore, use gcf to specify the figure
handle from within the close request function.
If you change a figure's CloseRequestFcn so that it does not delete the figure
(e.g., defining this property as an empty string), then issuing the close
command on that figure does not cause it to be deleted. Furthermore, if you
attempt to quit MATLAB, the quit is aborted because MATLAB does not delete
the figure.
Errors in the Close Request Function
If the CloseRequestFcn generates an error when executed, MATLAB aborts
the close operation. However, errors in the CloseRequestFcn do not abort
attempts to quit MATLAB. If an error occurs in a figure's CloseRequestFcn,
MATLAB closes the figure unconditionally following a quit or exit command.
Overriding the Close Request Function
The delete command always deletes the specified figure, regardless of the
value of its CloseRequestFcn. For example, the statement,
delete(get(0,'Children'))
deletes all figures whose handles are not hidden (i.e., the HandleVisibility
property is set to off). If you want to delete all figures regardless of whether
their handles are hidden, you can set the root ShowHiddenHandles property to
on. The root Children property then contains the handles of all figures. For
example, the statements,
set(0,'ShowHiddenHandles','yes')
delete(get(0,'Children'))
unconditionally delete all figures.
Handle Validity Versus Handle Visibility
All handles remain valid regardless of whether they are visible or not. If you
know an object’s handle, you can set and get its properties. By default, figure
handles are integers that are displayed at the top of the window.
7-46
Controlling Graphics Output
You can provide further protection to figures by setting the IntegerHandle
property to off. MATLAB then uses a floating-point number for figure handles.
7-47
7
Handle Graphics Objects
Saving Handles in M-Files
Graphics M-files frequently use handles to access property values and to direct
graphics output to a particular target. MATLAB provides utility routines that
return the handles to key objects (such as the current figure and axes). In
M-files, however, these utilities may not be the best way to obtain handles
because:
• Querying MATLAB for the handle of an object or other information is less
efficient than storing the handle in a variable and referencing that variable.
• The current figure, axes, or object may change during M-file execution
because of user interaction.
Save Information First
It is a good practice to save relevant information about MATLAB’s state in the
beginning of your M-file. For example, you can begin an M-file with
cax = newplot;
cfig = get(cax,'Parent');
hold_state = ishold;
rather than querying this information each time you need it. Remember that
utility commands like ishold obtain the values they return whenever called.
(The ishold command issues a number of get commands and string compares
(strcmp) to determine the hold state.)
If you are temporarily going to alter the hold state within the M-file, you should
save the current values of the NextPlot properties so you can reset them later.
ax_nextplot = lower(get(cax,'NextPlot'));
fig_nextplot = lower(get(cfig,'NextPlot'));
.
.
.
set(cax,'NextPlot',ax_nextplot)
set(cfig,'NextPlot',fig_nextplot)
7-48
Properties Changed by Built-In Functions
Properties Changed by Built-In Functions
To achieve their intended effect, many built-in functions change axes
properties, which can then affect the workings of your M-file. This table lists
MATLAB’s built-in graphics functions and the properties they change. Note
that these properties change only if hold is off.
Function
Axes Property: Set To
fill
Box: on
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
fill3
CameraPosition: 3-D view
CameraTarget: 3-D view
CameraUpVector: 3-D view
CameraViewAngle: 3-D view
XScale: linear
YScale: linear
ZScale: linear
image (high-level)
Box: on
Layer: top
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
XDir: normal
XLim: [0 size(CData,1)]+0.5
XLimMode: manual
YDir: reverse
YLim: [0 size(CData,2)]+0.5
YLimMode: manual
loglog
Box: on
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
XScale: log
YScale: log
7-49
7
Handle Graphics Objects
7-50
Function
Axes Property: Set To
plot
Box: on
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
plot3
CameraPosition: 3-D view
CameraTarget: 3-D view
CameraUpVector: 3-D view
CameraViewAngle: 3-D view
XScale: linear
YScale: linear
ZScale: linear
semilogx
Box: on
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
XScale: log
YScale: linear
semilogy
Box: on
CameraPosition: 2-D view
CameraTarget: 2-D view
CameraUpVector: 2-D view
CameraViewAngle: 2-D view
XScale: linear
YScale: log
8
Axes Properties
Overview
. . . . . . . . . . . . . . . . . . . . . 8-2
Labeling and Appearance Properties . . . . . . . . . 8-3
Creating Axes with Specific Characteristics . . . . . . . . 8-3
Positioning Axes . . . . . . . . . . . . . . . . . . 8-5
The Position Vector . . . . . . . . . . . . . . . . . . 8-5
Units . . . . . . . . . . . . . . . . . . . . . . . 8-6
Multiple Axes per Figure . . . . . . . . . . . . . . 8-7
Placing Text Outside the Axes . . . . . . . . . . . . . 8-7
Multiple Axes for Different Scaling . . . . . . . . . . . 8-8
Individual Axis Control .
Setting Axis Limits . . . .
Setting Tick Mark Locations
Changing Axis Direction . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 8-10
. 8-11
. 8-12
. 8-13
Using Multiple X and Y Axes . . . . . . . . . . . . . 8-16
Example – Double Axis Graphs . . . . . . . . . . . . . 8-16
Automatic-Mode Properties . . . . . . . . . . . . . 8-19
Colors Controlled by Axes . . . . . . . . . . .
Specifying Axes Colors . . . . . . . . . . . . .
Axes Color Limits – The CLim Property . . . . . .
Example – Simulating Multiple Colormaps in a Figure
Calculating Color Limits . . . . . . . . . . . .
Defining the Color of Lines for Plotting . . . . . . .
Line Styles Used for Plotting – LineStyleOrder . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 8-22
. 8-22
. 8-25
. 8-25
. 8-26
. 8-29
. 8-31
8
Axes Properties
Axes Topics
Axes are the parents of image, light, line, patch, rectangle, surface, and text
graphics objects. These objects are the entities used to draw graphs of
numerical data and pictures of real-world objects, such as airplanes or
automobiles. Axes orient and scale their child objects to produce a particular
effect, such as scaling a plot to accentuate certain information or rotating
objects through various views.
Axes properties control many aspects of how MATLAB displays graphical
information. This section discusses some of the features that are implemented
through axes properties and provides examples of how to uses these features.
The table in the axes reference page listing all axes properties provides an
overview of the characteristics affected by these properties.
The topics covered in this section include:
• Labeling and Appearance Properties – properties that affect general
appearance of the axes.
• Positioning Axes – how axes are positioned within a figure.
• Multiple Axes per Figure – how to uses axes to place text outside the graph
axes and how to use multiple axes within a figure to achieve different views.
• Individual Axis Control and Using Multiple X and Y Axes – properties that
control the x-, y-, and z-axis individually.
• Automatic-Mode Properties – properties that are set automatically with each
graph.
• Colors Controlled by Axes – covers axes colors and using color limits to
control the mapping of data to colormaps.
8-2
Labeling and Appearance Properties
Labeling and Appearance Properties
MATLAB provides a number of properties for labeling and controlling the
appearance of axes. For example, this surface plot shows some of the labeling
possibilities and indicates the controlling property.
Title
Z = f(x,y)
+1
GridLineStyle
ZTickLabels
Z = 0 Plane
Color
−1
2
2
1
YColor
1
0
0
−1
YLabel
Values of Y
FontAngle
−1
−2
−2
Values of X
XLabel
Creating Axes with Specific Characteristics
To create this axes, specify values for the indicated properties.
h = axes('Color',[.9 .9 .9],...
'GridLineStyle','--',...
'ZTickLabels','-1|Z = 0 Plane|+1',...
'FontName','times',...
'FontAngle','italic',...
'FontSize',14,...
'XColor',[0 0 .7],...
'YColor',[0 0 .7],...
'ZColor',[0 0 .7]);
8-3
8
Axes Properties
Axis Labels
The individual axis labels are text objects whose handles are normally hidden
from the command line (their HandleVisibility property is set to callback).
You can use the xlabel, ylabel, zlabel, and title functions to create axis
labels. However, these functions affect only the current axes. If you are labeling
axes other than the current axes by referencing the axes handle, then you must
obtain the text object handle from the corresponding axes property. For
example,
get(axes_handle,'XLabel')
returns the handle of the text object used as the x-axis label. Obtaining the text
handle from the axes is useful in M-files and MATLAB-based applications
where you cannot be sure the intended target is the current axes.
The following statements define the x- and y-axis labels and title for the axes
above.
set(get(axes_handle,'XLabel'),'String','Values of X')
set(get(axes_handle,'YLabel'),'String','Values of Y')
set(get(axes_handle,'Title'),'String','\fontname{times}\itZ =
f(x,y)')
Since the labels are text, you must specify a value for the String property,
which is initially set to the empty string (i.e., there are no labels).
MATLAB overrides many of the other text properties to control positioning and
orientation of these labels. However, you can set the Color, FontAngle,
FontName, FontSize, FontWeight, and String properties.
Note that both axes objects and text objects have font specification properties.
The call to the axes function on the previous page set values for the FontName,
FontAngle, and FontSize properties. If you want to use the same font for the
labels and title, specify these same property values when defining their String
property. For example, the x-axis label statement would be
set(get(h,'XLabel'),'String','Values of X',...
'FontName','times',...
'FontAngle','italic',...
'FontSize',14)
8-4
Positioning Axes
Positioning Axes
The axes Position property controls the size and location of an axes within a
figure. The default axes has the same aspect ratio (ratio of width to height) as
the default figure and fills most of the figure, leaving a border around the
edges. However, you can define the axes position as any rectangle and place it
wherever you want within a figure.
The Position Vector
MATLAB defines the axes Position property as a vector.
[left bottom width height]
left and bottom define a point in the figure that locates the lower-left corner
of the axes rectangle. width and height specify the dimensions the axes
rectangle. Viewing the axes in 2-D (azimuth = 0°, elevation = 90°) orients the
x-axis horizontally and the y-axis vertically. From this angle, the plot box (the
area used for plotting, exclusive of the axis labels) coincides with the axes
rectangle.
width
1
0.9
0.8
0.7
0.6
height
0.5
0.4
0.3
0.2
left
0.1
0
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
bottom
8-5
8
Axes Properties
The default 3-D view is azimuth = -37.5°, elevation = 30°.
width
1
0.8
0.6
height
0.4
0.2
0
1
1
left
0.5
bottom
0.5
0 0
By default, MATLAB draws the plot box to fill the axes rectangle, regardless of
its shape. However, axes properties enable control over the shape and scaling
of the plot box.
Units
The axes Units property determines the units of measurement for the
Position property. Possible values for this property are
set(gca,'Units')
[ inches | centimeters | {normalized} | points | pixels ]
with normalized being the default. Normalized units map the lower-left corner
of the figure to the point (0,0) and the upper-right corner to (1.0,1.0), regardless
of the size of the figure. Normalized units cause axes to resize automatically
whenever you resize the figure. All other units are absolute measurements that
remained fixed as you resize the figure.
8-6
Multiple Axes per Figure
Multiple Axes per Figure
The subplot function creates multiple axes in one figure by computing values
for Position that produce the specified number of axes.
The subplot function is useful for laying out a number of graphs equally
spaced in the figure. However, overlapping axes can create some other useful
effects.
Placing Text Outside the Axes
MATLAB always displays text objects within an axes. If you want to create a
graph and provide a description of the information alongside the graph, you
must create another axes to position the text. If you create an axes that is the
same size as the figure and then create a smaller axes to draw the graph, you
can then display text anywhere independently of the graph.
For example, define two axes.
h = axes('Position',[0 0 1 1],'Visible','off');
axes('Position',[.25 .1 .7 .8])
Since the axes units are normalized to the figure, specifying the Position as
[0 0 1 1] creates an axes that encompasses the entire window.
Now plot some data in the current axes. The last axes created is the current
axes so MATLAB directs graphics output there.
t = 0:900;
plot(t,0.25*exp(-0.005*t))
Define the text and display it in the full-window axes.
str(1) = {'Plot of the function:'};
str(2) = {' y = A{\ite}^{-\alpha{\itt}}'};
str(3) = {'With the values:'};
str(3) = {' A = 0.25'};
str(4) = {' \alpha = .005'};
str(5) = {' t = 0:900'};
set(gcf,'CurrentAxes',h)
text(.025,.6,str,'FontSize',12)
8-7
8
Axes Properties
0.25
0.2
Plot of the function:
−αt
y = Ae
With the values:
A = 0.25
0.15
α = .005
t = 0:900
0.1
0.05
0
0
100
200
300
400
500
600
700
800
900
Multiple Axes for Different Scaling
You can create multiple axes to display graphics objects with different scaling
without changing the data that defines these objects (which would be required
to display them in a single axes).
h(1) = axes('Position',[0 0 1 1]);
sphere
h(2) = axes('Position',[0 0 .4 .6]);
sphere
h(3) = axes('Position',[0 .5 .5 .5]);
sphere
h(4) = axes('Position',[.5 0 .4 .4]);
sphere
h(5) = axes('Position',[.5 .5 .5 .3]);
sphere
set(h,'Visible','off')
8-8
Multiple Axes per Figure
Each sphere is defined by the same data. However, since the parent axes
occupy regions of different size and location, the spheres appear to be different
sizes and shapes.
8-9
8
Axes Properties
Individual Axis Control
MATLAB automatically determines axis limits, tick mark placement, and tick
mark labels whenever you create a graph. However, you can specify these
values manually by setting the appropriate property.
When you specify a value for a property controlled by a mode (e.g., the XLim
property has an associated XLimMode property), MATLAB sets the mode to
manual enabling you to override automatic specification. Since the default
values for these mode properties are automatic, calling high-level functions
such as plot or surf resets these modes to auto.
This section discusses the following properties.
8-10
Property
Purpose
XLim,YLim,ZLim
Sets the axis range.
XLimMode,
YLimMode,
ZLimMode
Specifies whether axis limits are determined
automatically by MATLAB or specified
manually by the user.
XTick,
YTick,
ZTick
Sets the location of the tick marks along the
axis.
XTickMode,
YTickMode,
ZTickMode
Specifies whether tick mark locations are
determined automatically by MATLAB or
specified manually by the user.
XTickLabel,
YTickLabel,
ZTickLabel
Specifies the labels for the axis tick marks.
XTickLabelMode,
YTickLabelMode,
ZTickLabelMode
Specifies whether tick mark labels are
determined automatically by MATLAB or
specified manually by the user.
XDir,YDir,ZDir
Sets the direction of increasing axis values.
Individual Axis Control
Setting Axis Limits
MATLAB determines the limits automatically for each axis based on the range
of the data. You can override the selected limits by specifying the XLim, YLim,
– αt
evaluated
or ZLim property. For example, consider a plot of the function Ae
with A = 0.25, α = 0.05, and t = 0 to 900.
t = 0:900;
plot(t,0.25*exp(−0.05*t))
The plot on the left shows the results. MATLAB selects axis limits that
encompass the range of data in both x and y. However, since the plot contains
little information beyond t = 100, changing the x-axis limits improves the
usefulness of the plot. If the handle of the axes is axes_handle, then following
statement,
set(axes_handle,'XLim',[0 100])
creates the plot on the right.
Before
After
α = 0.05
0.25
0.2
0.2
Amplitude
Amplitude
α = 0.05
0.25
0.15
0.1
0.05
0
0
0.15
0.1
0.05
200
400
600
Time µsec.
800
0
0
20
40
60
Time µsec.
80
100
You can use the axis command to set limits on the current axes only.
8-11
8
Axes Properties
Semiautomatic Limits
You can specify either the minimum or maximum value for an axis limit and
allow the other limit to autorange. Do this by setting an explicit value for the
manual limit and Inf for the automatic limit. For example, the statement,
set(axes_handle,'XLim',[0 Inf])
sets the XLimMode property to auto and allows MATLAB to determine the
maximum value for XLim. Similarly, the statement,
set(axes_handle,'XLim',[−Inf 800])
sets the XLimMode property to auto and allows MATLAB to determine the
minimum value for XLim.
Setting Tick Mark Locations
MATLAB selects the tick mark location based on the data range to produce
equally spaced ticks (for linear graphs). You can specify alternative locations
for the tick marks by setting the XTick, YTick, and ZTick properties.
For example, if the value 0.075 is of interest for the amplitude of the function
– αt
, specify tick marks to include that value.
Ae
set(gca,'YTick',[0 0.05 0.075 0.1 0.15 0.2 0.25])
α = 0.05
0.25
Amplitude
0.2
0.15
0.1
0.075
0.05
0
0
8-12
20
40
60
Time µsec.
80
100
Individual Axis Control
You can change tick labeling from numbers to strings using the XTickLabel,
YTickLabel, and ZTickLabel properties.
For example, to label the y-axis value of 0.075 with the string Cutoff, you can
specify all y-axis labels as a string, separating each label with the “|”
character.
set(gca,'YTickLabel','0|0.05|Cutoff|0.1|0.15|0.2|0.25')
α = 0.05
0.25
Amplitude
0.2
0.15
0.1
Cutoff
0.05
0
0
20
40
60
Time µsec.
80
100
Changing Axis Direction
The XDir, YDir, and ZDir properties control the direction of increasing values
on the respective axis. In the default 2-D view, the x-axis values increase from
left to right and the y-axis values increase from bottom to top. The z-axis points
out of the screen.
You can change the direction of increasing values by setting the associated
property to reverse. For example, setting XDir to reverse,
set(gca,'XDir','reverse')
produces a plot whose x-axis decreases from left to right.
8-13
8
Axes Properties
Frog Road Kills
100
90
Percent of Today’s Rate
80
70
60
50
40
30
20
10
0
200
150
100
Years Ago
50
0
In the 3-D view, the y-axis increases from front to back and the z-axis increases
from bottom to top.
Increasing Values →
Normal Axis Direction
1
0.5
0
1
←
1
Inc
rea 0.5
sin
gV
alu
8-14
es
0 0
Inc
0.5
es →
g Valu
in
s
a
re
Individual Axis Control
Setting the x-, y-, and z-directions to reverse,
set(gca,'XDir','rev','YDir','rev','ZDir','rev')
yields
← Increasing Values
Reverse Axis Direction
0
0.5
1
0
Inc
0
rea
sin 0.5
gV
alu
es
→
1 1
0.5
s
Value
sing
ncrea
←I
8-15
8
Axes Properties
Using Multiple X and Y Axes
The XAxisLocation and YAxisLocation properties specify on which side of the
graph to place the x- and y-axes. You can create graphs with two different
x-axes and y-axes by superimposing two axes objects and using XAxisLocation
and YAxisLocation to position each axis on a different side of the graph. This
technique is useful to plot different sets of data with different scaling in the
same graph.
Example – Double Axis Graphs
This example creates a graph to display two separate sets of data using the
bottom and left sides as the x- and y-axis for one, and the top and right sides as
the x- and y-axis for the other.
Using low-level line and axes routines allows you to superimpose objects
easily. Plot the first data, making the color of the line and the corresponding xand y-axis the same to more easily associate them.
hl1 = line(x1,y1,'Color','r');
ax1 = gca;
set(ax1,'XColor','r','YColor','r')
Next, create another axes at the same location as the first, placing the x-axis
on top and the y-axis on the right. Set the axes Color to none to allow the first
axes to be visible and color code the x- and y-axis to match the data.
ax2 = axes('Position',get(ax1,'Position'),...
'XAxisLocation','top',...
'YAxisLocation','right',...
'Color','none',...
'XColor','k','YColor','k');
Draw the second set of data in the same color as the x- and y-axis.
hl2 = line(x2,y2,'Color','k','Parent',ax2);
8-16
Using Multiple X and Y Axes
Time sec
0
0.05
2
4
6
8
10
2.5
0
2
Amplitude
−0.1
1.5
−0.15
1
−0.2
Amplitude
−0.05
−0.25
0.5
−0.3
−0.35
0
5
10
15
20
25
Time msec
30
35
0
40
Creating Coincident Grids
Since the two axes are completely independent, MATLAB determines tick
mark locations according to the data plotted in each. It is unlikely the gridlines
will coincide. This produces a somewhat confusing looking graph, even though
the two grids are drawn in different colors. However, if you manually specify
tick mark locations, you can make the grids coincide.
The key is to specify the same number of tick marks along corresponding axis
lines (it is also necessary for both axes to be the same size). The following graph
of the same data uses six tick marks per axis, equally spaced within the
original limits. To calculate the tick mark location, obtain the limits of each
axis and calculate an increment.
xlimits = get(ax1,'XLim');
ylimits = get(ax1,'YLim');
xinc = (xlimits(2)−xlimits(1))/5;
yinc = (ylimits(2)−ylimits(1))/5;
8-17
8
Axes Properties
Now set the tick mark locations.
set(ax1,'XTick',[xlimits(1):xinc:xlimits(2)],...
'YTick',[ylimits(1):yinc:ylimits(2)])
The resulting graph is visually simpler, even though the y-axis on the left has
rather odd tick mark values.
Time sec
4
6
8
10
2.5
−0.03
2
−0.11
1.5
−0.19
1
−0.27
0.5
−0.35
0
8-18
2
8
16
24
Time msec
32
0
40
Amplitude
Amplitude
0
Automatic-Mode Properties
Automatic-Mode Properties
While object creation routines that create axes children do not explicitly change
axes properties, some axes properties are under automatic control when their
associated mode property is set to auto (which is the default). The following
table lists the automatic-mode properties.
Mode Properties
What It Controls
CameraPositionMode
Positioning of the viewpoint
CameraTargetMode
Positioning of the camera target in the axes
CameraUpVectorMode
The direction of “up” in 2-D and 3-D views
CameraViewAngleMode
The size of the projected scene and
stretch-to-fit behavior
CLimMode
Mapping of data values to colors
DataAspectRatioMode
Relative scaling of data units along x, y, and z
axes and stretch-to-fit behavior
PlotBoxAspectRatioMode
Relative scaling of plot box along x, y, and z
axes and stretch-to-fit behavior
TickDirMode
Direction of axis tick marks (in for 2-D, out
for 3-D)
XLimMode
YLimMode
ZLimMode
Limits of the respective x, y, and z axes
XTickMode
YTickMode
ZTickMode
Tick mark spacing along the respective x, y,
and z axes
XTickLabelMode
YTickLabelMode
ZTickLabelMode
Tick mark labels along the respective x, y,
and z axes
8-19
8
Axes Properties
For example, if all property values are set to their defaults and you enter these
statements
line(1:10,1:10)
line(1:10,[1:10].^2)
the second line statement causes the YLim property to change from [0 10] to
[0 100].
100
90
80
70
60
50
40
30
20
10
0
1
2
3
4
5
6
7
8
9
10
This is because YLimMode is auto, which always causes MATLAB to recompute
the axis limits.
If you set the value controlled by an automatic-mode property, MATLAB sets
the mode to manual and does not automatically recompute the value.
For example, in the statements
line(1:10,1:10)
set(gca,'XLim',[1 10],'YLim',[1 20])
line(1:10,[1:10].^2)
the set statement sets the x- and y-axis limits and changes the XLimMode and
YLimMode properties to manual. The second line statement now draws a line
that is clipped to the axis limits [1 12] instead of causing the axes to
recompute its limits.
8-20
Automatic-Mode Properties
20
18
16
14
12
10
8
6
4
2
1
2
3
4
5
6
7
8
9
10
8-21
8
Axes Properties
Colors Controlled by Axes
Axes properties specify the color of the axis lines, tick marks, labels, and the
background. Properties also control the color of the lines drawn by plotting
routines and how image, patch, and surface objects obtain colors from the
figure colormap.
The axes properties discussed in this section are listed in the following table.
Property
Characteristic it Controls
Color
Axes background color
XColor, YColor, ZColor
Color of the axis lines, tick marks, gridlines
and labels
Title
Title text object handles
XLabel, YLabel, Zlabel
Axis label text object handles
CLim
Controls mapping of graphic object CData to
the figure colormap
CLimMode
Automatic or manual control of CLim property
ColorOrder
Line color autocycle order
LineStyleOrder
Line styles autocycle order (not a color, but
related to ColorOrder)
Specifying Axes Colors
The default axes background color is set up by the colordef command, which
is called in your startup file. However, you can easily define your own color
scheme.
See InvertHardCopy for information on how MATLAB automatically changes
the color scheme for printing hardcopy.
8-22
Colors Controlled by Axes
Changing the Color Scheme
Suppose you want an axes to use a “black-on-white” color scheme. First, change
the background to white and the axis lines, grid, tick marks, and tick mark
labels to black.
set(gca,'Color','w',...
'XColor','k',...
'YColor','k',...
'ZColor','k')
Next, change the color of the text objects used for the title and axis labels.
set(get(gca,'Title'),'Color','k')
set(get(gca,'XLabel'),'Color','k')
set(get(gca,'YLabel'),'Color','k')
set(get(gca,'ZLabel'),'Color','k')
Changing the figure background color to white completes the new color scheme.
set(gcf,'Color','w')
When you are done, a figure containing a mesh plot looks like the following
figure.
8-23
8
Axes Properties
2
2
Z = Ae−x −y
Values of Z
0.5
0
−0.5
2
2
1
1
0
0
−1
Range In Y
−1
−2
−2
Range In X
You can define default values for the appropriate properties and put these
definitions in your startup.m file. Titles and axis labels are text objects, so you
must set a default color for all text objects, which is a good idea anyway since
the default text color of white is not visible on the white background. Lines
created with the low-level line function (but not the plotting routines) also
have a default color of white, so you should change the default line color as well.
To set default values on the root level, use.
set(0,'DefaultFigureColor','w'
'DefaultAxesColor','w',...
'DefaultAxesXColor','k',...
'DefaultAxesYColor','k',...
'DefaultAxesZColor','k',...
'DefaultTextColor','k',...
'DefaultLineColor','k')
MATLAB colors other axes children (i.e., image, patch, and surface objects)
according to the values of their CData properties and the figure colormap.
8-24
Colors Controlled by Axes
Axes Color Limits – The CLim Property
Many of the 3-D graphics functions produce graphs that use color as another
data dimension. For example, surface plots map surface height to color. The
color limits control the limits of the color dimension in a way analogous to
setting axis limits.
The axes CLim property controls the mapping of image, patch, and surface
CData to the figure colormap. CLim is a two-element vector [cmin cmax]
specifying the CData value to map to the first color in the colormap (cmin) and
the CData value to map the last color in the colormap (cmax). Data values in
between are linearly transformed from the second to the next to last color,
using the expression
colormap_index = fix((CData−cmin)/(cmax−cmin)*cm_length)+1
cm_length is the length of the colormap. When CLimMode is auto, MATLAB sets
CLim to the range of the CData of all graphics objects within the axes. However,
you can set CLim to span any range of values. This allows individual axes within
a single figure to use different portions of the figure’s colormap. You can create
colormaps with different regions, each used by a different axes.
See the caxis command for more information on color limits
Example – Simulating Multiple Colormaps in a
Figure
Suppose you want to display two different surfaces in the same figure and color
each surface with a different colormap. You can produce the effect of two
different colormaps by concatenating two colormaps together and then setting
the CLim property of each axes to map into a different portion of the colormap.
This example creates two surfaces from the same topographic data. One uses
the color scheme of a typical atlas – shades of blue for the ocean and greens for
the land. The other surface is illuminated with a light source to create the
illusion of a three-dimensional picture. Such illumination requires a colormap
that changes monotonically from dark to light.
8-25
8
Axes Properties
Calculating Color Limits
The key to this example is calculating values for CLim that cause each surface
to use the section of the colormap containing the appropriate colors.
To calculate the new values for CLim, you need to know:
• The total length of the colormap (CmLength)
• The beginning colormap slot to use for each axes (BeginSlot)
• The ending colormap slot to use for each axes (EndSlot)
8-26
Colors Controlled by Axes
• The minimum and maximum CData values of the graphic objects contained
in the axes. That is, the values of the axes CLim property determined by
MATLAB when CLimMode is auto (CDmin and CDmax).
First, define subplots regions, and plot the surfaces.
ax1 = subplot(2,1,1);
view([0 80])
surf(topodata)
shading interp
ax2 = subplot(2,1,2),;
view([0 80]);
surfl(topodata,[60 0])
shading interp
Concatenate two colormaps together and install the new colormap.
colormap([Lightingmap;Atlasmap]);
Obtain the data you need to calculate new values for CLim.
CmLength
BeginSlot1
EndSlot1
BeginSlot2
EndSlot2
CLim1
CLim2
=
=
=
=
=
=
=
size(get(gcf,'Colormap'),1);% Colormap length
1;
% Begining slot
size(Lightingmap,1); % Ending slot
EndSlot1+1;
CmLength;
get(ax1,'CLim');% CLim values for each axis
get(ax2,'CLim');
Defining a Function to Calculate CLim Values
Computing new values for CLim involves determining the portion of the
colormap you want each axes to use relative to the total colormap size and
scaling its Clim range accordingly. You can define a MATLAB function to do
this.
function CLim = newclim(BeginSlot,EndSlot,CDmin,CDmax,CmLength)
%
%
PBeginSlot
PEndSlot
PCmRange
%
Convert slot number and range
to percent of colormap
= (BeginSlot − 1) / (CmLength − 1);
= (EndSlot − 1) / (CmLength − 1);
= PEndSlot − PBeginSlot;
Determine range and min and max
8-27
8
Axes Properties
%
DataRange
ClimRange
NewCmin
NewCmax
CLim
=
=
=
=
=
of new CLim values
CDmax − CDmin;
DataRange / PCmRange;
CDmin − (PBeginSlot * ClimRange);
CDmax + (1 − PEndSlot) * ClimRange;
[NewCmin,NewCmax];
The input arguments are identified in the bulleted list above. The M-file first
computes the percentage of the total colormap you want to use for a particular
axes (PCmRange) and then computes the CLim range required to use that portion
of the colormap given the CData range in the axes. Finally, it determines the
minimum and maximum values required for the calculated CLim range and
return these values. These values are the color limits for the given axes.
Using the Function
Use the newclim M-file to set the CLim values of each axes. The statement,
set(ax1,'CLim',newclim(65,120,clim1(1),clim1(2)))
sets the CLim values for the first axes so the surface uses color slots 65 to 120.
The lit surface uses the lower 64 slots. You need to reset its CLim values as well.
set(ax2,'CLim',newclim(1,64,clim1(1),clim1(2)))
How the Function Works
MATLAB enables you to specify any values for the axes CLim property, even if
these values do not correspond to the CData of the graphics objects displayed in
the axes. MATLAB always maps the minimum CLim value to the first color in
the colormap and the maximum CLim value to the last color in the colormap,
whether or not there are really any CData values corresponding to these colors.
Therefore, if you specify values for CLim that extend beyond the object’s actual
CData minimum and maximum, MATLAB colors the object with only a subset
of the colormap.
The newclim M-file computes values for CLim that map the graphics object’s
actual CData values to the beginning and ending colormap slots you specify. It
does this by defining a “virtual” graphics object having the computed CLim
values. The following picture illustrates this concept. It shows a side view of
two surfaces to make it easier to visualize the mapping of color to surface
topography. The virtual surface is on the left and the actual surface on the
right. In the center is the figure’s colormap.
8-28
Colors Controlled by Axes
The real surface has CLim values of [0.4 −0.4]. To color this surface with slots
65 to 120, newclim computed new CLim values of [0.4 −1.4269]. The virtual
surface on the left represents these values.
Virtual surface
mapped to entire
120 slot colormap
Figure Colormap
Real surface using
only color slots 65
to 120
Defining the Color of Lines for Plotting
The axes ColorOrder property determines the color of the individual lines
drawn by the plot and plot3 functions. For multiline graphs, these functions
cycle through the colors defined by ColorOrder, repeating the cycle when
reaching the end of the list.
The colordef command defines various color order schemes for different
background colors. colordef is typically called in the matlabrc file, which is
executed during MATLAB’s startup.
8-29
8
Axes Properties
Defining Your Own ColorOrder
You can redefine ColorOrder to be any m-by-3 matrix of RGB values, where m
is the number of colors. However, high-level functions like plot and plot3
reset most axes properties (including ColorOrder) to the defaults each time you
call them. To use your own ColorOrder definition you must take one of the
following three steps:
• Define a default ColorOrder on the figure or root level, or
• Change the axes NextPlot property to add or replacechildren, or
• Use the informal form of the line function, which obeys the ColorOrder but
does not clear the axes or reset properties
Changing the Default ColorOrder. You can define a new ColorOrder that MATLAB
uses within a particular figure, for all axes within any figures created during
the MATLAB session, or as a user-defined default that MATLAB always uses.
To change the ColorOrder for all plots in the current figure, set a default in
that figure. For example, to set ColorOrder to the colors red, green, and blue,
use the statement,
set(gcf,'DefaultAxesColorOrder',[1 0 0;0 1 0;0 0 1])
To define a new ColorOrder that MATLAB uses for all plotting during your
entire MATLAB session, set a default on the root level so axes created in any
figure use your defaults.
set(0,'DefaultAxesColorOrder',[1 0 0;0 1 0;0 0 1])
To define a new ColorOrder that MATLAB always uses, place the previous
statement in your startup.m file.
Setting the NextPlot Property. The axes NextPlot property determines how
high-level graphics functions draw into an existing axes. You can use this
property to prevent plot and plot3 from resetting the ColorOrder property
each time you call them, but still clear the axes of any existing plots.
By default, NextPlot is set to replace, which is equivalent to a cla reset
command (i.e., delete all axes children and reset all properties, except
Position, to their defaults). If you set NextPlot to replacechildren,
set(gca,'NextPlot','replacechildren')
8-30
Colors Controlled by Axes
MATLAB deletes the axes children, but does not reset axes properties. This is
equivalent to a cla command without the reset.
After setting NextPlot to replacechildren, you can redefine the ColorOrder
property and call plot and plot3 without affecting the ColorOrder.
Setting NextPlot to add is the equivalent of issuing the hold on command. This
setting prevents MATLAB from resetting the ColorOrder property, but it does
not clear the axes children with each call to a plotting function.
Using the line Function. The behavior of the line function depends on its calling
syntax. When you use the informal form (which does not include any explicit
property definitions).
line(x,y,z)
line obeys the ColorOrder property, but does not clear the axes with each
invocation or change the view to 3-D (as plot3 does). However, line can be
useful for creating your own plotting functions where you do not want the
automatic behavior of plot or plot3, but you do want multiline graphs to use
a particular ColorOrder.
Line Styles Used for Plotting – LineStyleOrder
The axes LineStyleOrder property is analogous to the ColorOrder property. It
specifies the line styles to use for multiline plots created with the plot and
plot3 functions. MATLAB increments the line style only after using all of the
colors in the ColorOrder property. It then uses all the colors again with the
second line style, and so on.
For example, define a default ColorOrder of red, green, and blue and a default
LineStyleOrder of solid, dashed, and dotted lines.
set(0,'DefaultAxesColorOrder',[1 0 0;0 1 0;0 0 1],...
'DefaultAxesLineStyleOrder','-|--|:')
Then plot some multiline data.
t = 0:pi/20:2*pi;
a = ones(length(t),9);
for i = 1:9
a(:,i) = sin(t-i/5)';
end
plot(t,a)
8-31
8
Axes Properties
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
MATLAB cycles through all colors for each line style.
8-32
9
Figure Properties
Overview
. . . . . . . . . . . . . . . . . . . . . 9-2
Positioning Figures . . . . . . . . . . . . . . . . . 9-3
The Position Vector . . . . . . . . . . . . . . . . . . 9-3
Example – Specifying Figure Position . . . . . . . . . . 9-5
Controlling How MATLAB Uses Color . .
Indexed Color Displays . . . . . . . . . .
Colormap Colors and Fixed Colors . . . . . .
Using a Large Number of Colors . . . . . .
Nonactive Figures and Shared Colors . . . .
Dithering Truecolor on Indexed Color Systems
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Selecting Drawing Methods
Backing Store . . . . . . .
Double Buffering . . . . . .
Selecting a Renderer . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9-15
. 9-15
. 9-15
. 9-16
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9-7
9-7
9-8
9-9
9-11
9-12
Specifying the Figure Pointer . . . . . . . . . . . . 9-18
Defining Custom Pointers . . . . . . . . . . . . . . . 9-19
Interactive Graphics . . . . . . . . . . . . . . . . 9-23
9
Figure Properties
Figure Topics
Figure graphics objects are the windows in which MATLAB displays graphical
output. Figure properties allow you to control many aspects of these windows,
such as their size and position on the screen, the coloring of graphics objects
displayed within them, and the scaling of printed pictures.
This section discusses some of the features that are implemented through
figure properties and provides examples of how to use these features. The table
in the figure reference page listing all properties provides an overview of the
characteristics affected by figure properties. This section covers the following
topics.
• Positioning Figures – properties used to position figures and how they are
measured.
• Controlling How MATLAB Uses Color – properties that control how
MATLAB uses system color resources.
• Selecting a Drawing Method – how to select rendering method and when to
use double buffering and backing store.
• Specifying the Figure Pointer – describes how to select from predefined
pointers or define customer pointers.
9-2
Positioning Figures
Positioning Figures
The figure Position property controls the size and location of the figure
window on the root screen. At startup, MATLAB determines the size of your
computer screen and defines a default value for Position. This default creates
figures about one-quarter of the screen’s size and places them centered left to
right and in the top half of the screen.
The Position Vector
MATLAB defines the figure Position property as a vector.
[left bottom width height]
left and bottom define the position of the first addressable pixel in the
lower-left corner of the window, specified with respect to the lower-left corner
of the screen. width and height define the size of the interior of the window
(i.e., exclusive of the window border).
Figure No. 1
width
height
left
bottom
9-3
9
Figure Properties
MATLAB does not measure the window border when placing the figure; the
Position property defines only the internal active area of the figure window.
Since figures are windows under the control of your computer’s windowing
system, you can move and resize figures as you would any other windows.
MATLAB automatically updates the Position property to the new values.
Units
The figure’s Units property determines the units of the values used to specify
the position on the screen. Possible values for the Units property are
set(gcf,'Units')
[ inches | centimeters | normalized | points | {pixels} |
characters]
with pixels being the default. These choices allow you to specify the figure size
and location in absolute units (such as inches) if you want the window to
always be a certain size, or in units relative to the screen size (such as pixels).
characters are units that enable you to define the location and size of the
figure in units that are based on the size of the default system font.
Determining Screen Size
Whatever units you use, it is important to know the extent of the screen in
those units. You can obtain this information from the root ScreenSize
property. For example,
get(0,'ScreenSize')
ans =
1 1 1152 900
In this case, the screen is 1152 by 900 pixels. MATLAB returns the ScreenSize
in the units determined by the root Units property. For example,
set(0,'Units','normalized')
normalizes the values returned by ScreenSize.
get(0,'ScreenSize')
ans =
0 0 1 1
9-4
Positioning Figures
Defining the figure Position in terms of the ScreenSize in normalized units
makes the specification independent of variations in screen size. This is useful
if you are writing an M-file that is to be used on different computer systems.
Example – Specifying Figure Position
Suppose you want to define two figure windows that occupy the upper third of
the computer screen (e.g., one for uicontrols and the other to display data). To
position the windows precisely, you must consider the window borders when
calculating the size and offsets to specify for the Position properties.
The figure Position property does not include the window borders, so this
example uses a width of 5 pixels on the sides and bottom and 30 pixels on the
top.
bdwidth = 5;
topbdwidth = 30;
Ensure root units are pixels and get the size of the screen
set(0,'Units','pixels')
scnsize = get(0,'ScreenSize');
Define the size and location of the figures
pos1 = [bdwidth,...
2/3*scnsize(4) + bdwidth,...
scnsize(3)/2 − 2*bdwidth,...
scnsize(4)/3 − (topbdwidth + bdwidth)];
pos2 = [pos1(1) + scnsize(3)/2,...
pos1(2),...
pos1(3),...
pos1(4)];
Create the figures
figure('Position',pos1)
figure('Position',pos2)
9-5
9
Figure Properties
The two figures now occupy the top third of the screen.
9-6
Controlling How MATLAB Uses Color
Controlling How MATLAB Uses Color
Figure properties control the way MATLAB uses your computer’s color
resources. These properties influence both the speed of drawing and the
accuracy of the colors used to display graphics. The properties discussed in this
section include those listed in this table.
Property
Purpose
Colormap
The figure colormap. An n-by-3 array of RGB
values.
FixedColors
Specific colors used by the figure that are not
in the colormap.
MinColormap
The minimum number of system color table
slots MATLAB uses for the figure colormap.
ShareColors
The property that determines whether
MATLAB shares colors with other figure
colormaps in the system color table.
Dithermap
A predefined colormap for displaying truecolor
graphics objects on a pseudocolor system.
DithermapMode
The property that determines whether
MATLAB uses the current dither colormap or
creates one based on the colors specified for
existing graphics objects.
Indexed Color Displays
MATLAB defines a unique colormap as well as fixed colors (which are not part
of the colormap) for each figure object. Your computer system stores these color
definitions in a color lookup table along with colors used for window borders,
backgrounds, and so on.
Indexed color systems associate a color slot (as opposed to a specific color) in
the system color table with each screen pixel. When you activate an application
program, for example, by moving the focus to a MATLAB figure window, the
system loads the colors associated with that program into the color table.
9-7
9
Figure Properties
You can create a number of figures on the screen at once, but only one has focus
at any given time. When you change the focus to a particular figure, the
computer’s operating system loads that figure’s colormap and all its fixed colors
into the system color table.
For example, the color table might be allocated like this.
System
Color
Table
Color slots used by system for window borders,
menu colors, background, etc.
Color slots allocated as MATLAB fixed colors
Color slots available for the figure colormap
Colormap Colors and Fixed Colors
MATLAB maintains two categories of colors for each figure – colors that are
defined in the colormap and colors that are fixed, which do not change when
you change the colormap. These two categories are used in different ways.
Only surface, patch, and image objects use the colormap. MATLAB colors these
objects based on the order the colors appear in the colormap.
Fixed colors are simply definitions of specific colors that MATLAB uses to color
axis lines and labels and values you specify for object colors (i.e., the Color,
ColorOrder, FaceColor, EdgeColor, MarkerFaceColor, and MarkerEdgeColor
properties).
Defining Fixed Colors
When MATLAB creates a figure, it defines three fixed colors.
figure
get(gcf,'FixedColors')
ans =
0.8000
0.8000
0
0
9-8
0.8000
0
Controlling How MATLAB Uses Color
1.0000
1.0000
1.0000
Creating an axes includes the colors defined by the axes ColorOrder property
in the fixed color list, since it is more efficient to predefine these colors.
axes
get(gcf,'FixedColors')
ans =
0.8000
0.8000
0
0
1.0000
1.0000
0
0
0
0.5000
1.0000
0
0
0.7500
0.7500
0
0.7500
0.7500
0.2500
0.2500
0.8000
0
1.0000
1.0000
0
0
0.7500
0.7500
0
0.2500
Any colors you define, for example,
set(surf_handle,'EdgeColor',[.2 .8 .7])
also become part of the fixed color list. You can define as many fixed colors as
you want without affecting the colors in the figure colormap. However, fixed
colors occupy color table slots that MATLAB cannot use for the colormap.
Using a Large Number of Colors
Overview
Set MinColormap to a number equal to the size of your colormap when you do
not want MATLAB to approximate colors. However, this may cause nonactive
windows to display with incorrect colors.
More Details
Problems can arise when you define a large colormap and/or a large number of
fixed colors. If the number of color slots required exceeds the number available
in the system color table, MATLAB specifies all fixed colors first, then linearly
subsamples the colormap to fill the remaining slots.
9-9
9
Figure Properties
For example, if the original colormap contains 128 colors and there are only 64
slots available, then MATLAB adds every other color to the color table.
MATLAB maps each color in the original colormap to the color in the
subsampled colormap that most closely matches the original color.
Specifying the Minimum Colormap Size – MinColormap
The figure MinColormap property specifies the minimum number of slots in the
system color table that MATLAB uses for the figure colormap. This enables you
to use colormaps of any size up to the value of MinColormap and ensure
MATLAB does not subsample the colors.
System
Color
Table
System Color Slots
Fixed colors
Figure colormap
If you specify a value that is greater than the number of available slots,
MATLAB takes over slots used to define system colors (on computers that allow
overwriting of these colors). When this happens, nonactive windows can
display with incorrect colors because MATLAB changed the color of the slot
assigned to their pixels.
MATLAB does not take over color slots allocated to fixed colors. Therefore,
limiting the number of fixed colors maximizes the number of colors allocated to
the colormap. You can limit the number of fixed colors by specifying all
noncolormap object colors (e.g., text, line, and figure colors) as the same color,
and setting the axes ColorOrder property to just one color (the default is seven
colors).
9-10
Controlling How MATLAB Uses Color
Nonactive Figures and Shared Colors
Overview
Set ShareColors to on to conserve resources and to off to allow rapid colormap
change.
More Detail
Since nonactive figures are still visible, it is generally desirable for them to
display correctly colored. However, if a number of figures with different
colormaps exist simultaneously, or have large colormaps, the computer’s color
resources may not be able to display all figures correctly colored. When
ShareColors is on, the figure does not redefine a color in the system color table
if that color already exists.
System
Color
Table
0.5
0
−0.5
25
Two pixels pointing
to the same slot
in the color table
25
20
20
15
15
10
10
5
5
0
0
2
40
1
30
0
20
−1
10
−2
0
0
5
10
15
20
25
30
35
40
While sharing colors is a more efficient use of resources, it prevents MATLAB
from rapidly changing the colormap (for example, as the spinmap function
does). This is because MATLAB cannot change the value of a color slot in the
system color table if other pixels also point to that slot for their color definition.
It must find another slot for the new color. Changing color slot pixel
assignments requires rerendering (i.e., recomputing color values and
9-11
9
Figure Properties
reassigning pixels to these colors) of the figure whose colormap you are
altering.
If you want to change a figure’s colormap rapidly, you should disable color
sharing.
set(fig_handle,'ShareColors','off')
Note that the new colormap must be the same size as the original one to avoid
rerendering the figure. Look at the spinmap M-file for an example of this
technique.
Dithering Truecolor on Indexed Color Systems
Overview
Set DithermapMode to manual to use the current Dithermap or auto to force
MATLAB to create a new Dithermap based on the colors displayed in the figure.
More Detail
MATLAB enables you to take advantage of truecolor systems (24-bit displays)
by specifying CData as RGB triples, instead of values that index into the figure
colormap. Index color systems interpret truecolor specifications by mapping
each color to the closest color in the dithermap, which is assigned to the
Dithermap property. MATLAB uses the Floyd-Steinberg algorithm to perform
the mapping.
9-12
Controlling How MATLAB Uses Color
Direct Color
Specification
B
G
R
Dither
Map
MATLAB maps each direct color to the closest
color in the current dithermap. The algorithm
looks at the colors selected in a six-pixel
region so that, on the average, the color of
that region closely approximates the real
colors.
The dithermap is a colormap that replaces the figure colormap (which is not
used in this case). The default dithermap contains a sampling of colors from the
entire spectrum. This produces reasonably good quality with any object
coloring. However, if the figure contains objects of primarily one color, a
dithermap concentrated in the same color produces better color resolution.
Auto Dither Mode
When you set DithermapMode to auto, MATLAB automatically creates a
dithermap based on the colors in the figure. MATLAB produces an appropriate
dithermap using the minimum variance quantization algorithm; however, the
process is time consuming. Also, MATLAB regenerates the dithermap each
time it re-renders the figure.
To avoid excessive rendering time, you should reset DithermapMode to manual
after MATLAB generates the dithermap. MATLAB then uses this dithermap
without regenerating it until you once again set DithermapMode to auto. You
do not need to regenerate the dithermap unless you change the colors used in
the figure.
9-13
9
Figure Properties
You can save a dithermap by assigning the Dithermap property to a variable
and saving it as a MAT-file.
set(gcf,'DithermapMode','auto')
MATLAB creates a dithermap, which you can then save.
dmap = get(gcf,'Dithermap');
save DitherMaps dmap
Dithermap Size
To obtain the highest color resolution, the default dithermap is as large as the
system allows. This is usually less than 256 colors because a certain number of
slots are reserved for system colors. Also, MATLAB fixed colors are not
overwritten by the dithermap.
Effects of Dithering
Dithering reduces the resolution of the displayed graphics because the colors
are mapped in groups of six pixels. For example, suppose the color of one pixel
is defined as orange, but the dithermap does not have this color. MATLAB
selects combinations of colors from the dithermap that, taken together as a
six-pixel group, approximate the color orange.
9-14
Selecting Drawing Methods
Selecting Drawing Methods
MATLAB enables you to select different techniques for drawing graphics. The
combination of settings you select depends on the type of graphics you are
producing.
There are four figure properties that affect how MATLAB draws graphics:
• BackingStore – allows faster redrawing when obscured figure windows are
exposed.
• DoubleBuffer – produces flash-free rendering for simple animations.
• Renderer and RendererMode – specifies different rendering methods or
allows MATLAB to make the selection.
Backing Store
Overview
Set BackingStore to on to produce fast redraws of previously obscured
windows. Disable BackingStore to use less system memory.
More Details
The term “backing store” refers to an off-screen pixel buffer used to store a copy
of the figure window’s contents. When you move or delete windows on your
display, previously obscured windows can become exposed (even partially),
requiring the computer system to redraw these windows. With backing store
enabled, MATLAB simply copies an exposed figure window’s contents from the
buffer to the screen.
The BackingStore property is on by default as this provides the most desirable
behavior. However, the off-screen pixel buffers required for each figure window
do consume system memory. If memory is limited on your system, set
BackingStore to off to release the memory used by these buffers.
Double Buffering
Overview
Set DoubleBuffer to on when animating lines rendered in painters with
EraseMode set to normal.
9-15
9
Figure Properties
More Details
Double buffering is the process of drawing into an off-screen pixel buffer and
then blitting the buffer contents to the screen once the drawing is complete
(instead of drawing directly to the screen where the process of drawing is
visible as it progresses). Double buffering generally produces flash-free
rendering for simple animations (such as those involving lines, as opposed to
objects containing large numbers of polygons).
The figure DoubleBuffer property accepts the values on and off, with off
being the default. Double buffering works only when the figure Renderer
property is set to painters.
Use double buffering with the animated object’s EraseMode property set to
normal.
Selecting a Renderer
Overview
MATLAB automatically selects the best renderer based on the complexity of
the graphics objects and the options available on your system.
More Details
A renderer is the software that processes graphics data (such as vertex
coordinates) into a form that MATLAB can use to draw into the figure.
MATLAB supports three renderers:
• Painters
• Zbuffer
• OpenGL
Painters
Painters method is faster when the figure contains only simple or small
graphics. It cannot be used with lighting.
Z-Buffer
Z-buffering is the process of determining how to render each pixel by drawing
only the front-most object, as opposed to drawing all objects back to front,
9-16
Selecting Drawing Methods
redrawing objects that obscure those behind. The pixel data is buffered and
then blitted to the screen all at once.
Z-buffering is generally faster for more complex graphics, but may be slower for
very simple graphics. You can set the Renderer property to whatever produces
the fastest drawing (either zbuffer or painters), or let MATLAB decide which
method to use by setting the RendererMode property to auto (the default).
Printing from Z-Buffer. You can select the resolution of the PostScript file
produced by the print command using the −r option. By default, MATLAB
prints Z-buffered figures at a medium resolution of 150 dpi (the default with
Renderer set to painters is 864 dpi).
The size of the file generated from a Z-buffer figure does not depend on its
contents, just the size of the figure. To decrease the file size, make the
PaperPosition property smaller before printing (or set PaperPositionMode to
auto and resize the figure window).
OpenGL
OpenGL is available on many computer systems. It is generally faster than
either painters or zbuffer and in some cases enables MATLAB to uses the
system’s graphics hardware (which results in significant speed increase). See
the figure Renderer property for more information.
Limitations of OpenGL. OpenGL has two limitations when compared to painters
and zbuffer:
• OpenGL does not interpolate colors within the figure colormap; all color
interpolation is performed through the RGB color cube, which may produce
unexpected results.
• OpenGL does not support Phong lighting.
9-17
9
Figure Properties
Specifying the Figure Pointer
MATLAB indicates the position of the pointer (cursor) within the figure
window using a graphical symbol. You can select a pointer from 15 predefined
symbols (see table below) or you can define your own symbol. By convention,
each of the predefined symbols has a purpose associated with it (although
MATLAB enforces no rules for the use of any symbols).
You specify the pointer symbol by setting the value of the figure Pointer
property. For example,
set(gcf,'Pointer','arrow')
The following table shows the predefined symbols, the associated specifier, and
describes typical use.
9-18
Purpose
Specifier
Locate a point on a graphics
object
crosshair
Select a point anywhere in the
figure
arrow
Indicate the system is busy
watch
Resize an object from the top-left
corner
topl
Resize an object from the
top-right corner
topr
Resize an object from the
bottom-left corner
botl
Resize an object from the
bottom-right corner
botr
View the actual hot spot
circle
Locate a point
cross
Use as popular symbol
fleur
Typical Symbol
Specifying the Figure Pointer
Purpose
Specifier
Resize an object from the left side
left
Resize an object from the right
side
right
Resize an object from the top
top
Resize an object from the bottom
bottom
Align a point with other objects
on the display
fullcross
See the next section for
information on defining your own
pointer shape
custom
Typical Symbol
Defining Custom Pointers
When you set the Pointer property to custom, MATLAB displays the pointer
you define using the PointerShapeCData and the PointerShapeHotSpot
properties. Custom pointers are 16-by-16 pixels, where each pixel can be either
black, white, or transparent.
Specify the pointer by creating a 16-by-16 matrix containing elements that are:
• 1s where you want the pixel black
• 2s where you want the pixel white
• NaNs where you want the pixel transparent
Assign the matrix to the figure PointerShapeCData property. MATLAB
displays the defined pointer whenever the pointer is in the figure window.
The PointerShapeHotSpot property specifies the pixel that indicates the
pointer location. MATLAB then stores this location in the root
PointerLocation property. Set the PointerShapeHotSpot property to a
two-element vector specifying the row and column indices in the
PointerShapeCData matrix that corresponds to the pixel specifying the
location. The default value for this property is [1 1], which corresponds to the
upper-left corner of the pointer.
9-19
9
Figure Properties
Example – Two Custom Pointers
One way to create a custom pointer is to assign values to a 16-by-16 matrix by
hand, as illustrated in the following example.
First, initialize the matrix, setting all values to 2. Create a black border 1 pixel
wide. Add alignment marks.
P = ones(16)+1;
P(1,:) = 1; P(16,:) = 1;
P(:,1) = 1; P(:,16) = 1;
P(1:4,8:9) = 1; P(13:16,8:9) = 1;
P(8:9,1:4) = 1; P(8:9,13:16) = 1;
P(5:12,5:12) = NaN; % Create a transparent region in the center
set(gcf,'Pointer','custom','PointerShapeCData',P,...
'PointerShapeHotSpot',[9 9])
The last statement sets the Pointer property to custom, assigns the matrix to
the PointerShapeCData property, and selects the “hot spot” as element (9,9).
MATLAB now uses the custom pointer within the figure window.
2
4
6
8
10
12
14
16
2
4
6
8
10
12
14
16
Creating Pointers from Functions. You can use a mathematical function to define
the PointerShapeCData matrix. For example, evaluating the function,
2
2
2 ( sin ( x + y ) )
g = 0:.2:20;
[X,Y] = meshgrid(g);
9-20
Specifying the Figure Pointer
Z = 2*sin(sqrt(X.^2 + Y.^2));
mesh(Z);
produces an interesting surface.
2
0
−2
20
15
20
10
10
5
0
0
Use the values of Z to create a pointer sampling fewer points so that Z is a
16-by-16 matrix.
g = linspace(0,20,16);
[X,Y] = meshgrid(g);
Z = 2*sin(sqrt(X.^2 + Y.^2));
set(gcf,'Pointer','custom',...
'PointerShapeCData',flipud((Z>0) + 1))
The statement, flipud((Z>0) + 1) sets all values in Z that are greater than
zero to two (in MATLAB, true + 1 = 2), less than zero to one (false + 1 = 1) and
then flips the data around so that element (1,1) is the upper-left corner.
9-21
9
Figure Properties
5
10
15
5
9-22
10
15
Interactive Graphics
Interactive Graphics
Figure objects contain a number of properties designed to facilitate user
interaction with the figure. These properties fall into two categories.
Properties related to callback routine execution:
• BusyAction
• ButtonDownFcn
• CreateFcn
• DeleteFcn
• KeyPressFcn
• Interruptible
• ResizeFcn
• WindowButtonDownFcn, WindowButtonMotionFcn, and WindowButtonUpFcn
Properties that contain information about MATLAB’s state:
• CurrentAxes
• CurrentCharacter
• CurrentMenu
• CurrentObject
• CurrentPoint
• SelectionType
The online manual, Creating Graphical User Interfaces, provides information
on creating programs that incorporate interactive graphics.
9-23
9
Figure Properties
9-24
3-D Visualization
Visualization is the use of graphical representations of information to make
certain characteristics or values more apparent. Visualization conveys
information by employing geometric forms (e.g., surfaces, solids) and colors
that are mapped to data values in particular ways. The geometric forms may
represent real-life objects, such as an airplane or wave guide, or may be
graphical elements that indicate data values, such as streamlines or slice
planes.
This collection of topics introduces visualization techniques and illustrates the
application of these techniques to specific types of data. The following list
summarizes the contents of this collection:
• Creating 3-D Graphs – includes information about 3-D line and surface
graphs.
• Defining the View – discusses how to set the view point and control the
aspect ratio and projection type. This section describes how to compose the
scene you want to display.
• Lighting as a Visualization Tool – illustrates the various lighting effects you
can employ to add realism and improve shape definition in 3-D views.
• Transparency – describes how to make objects translucent.
• Creating 3-D Models with Patches – shows how to use MATLAB patch
objects to define 3-D shell representations of physical shapes. Patches
support x-, y-, and z-coordinates as well as face and vertex data specification.
• Volume Visualization Techniques – employs a variety of MATLAB’s
visualization techniques to display both scalar and vector volume data.
Related Information
The following sections provide information that is useful in understanding the
techniques described in this section:
• Graphics – covers the fundamentals of plotting in MATLAB. It discusses
MATLAB’s standard plotting routines (line plots, pie charts, histograms,
etc.) as well as graph formatting and annotation. In addition, this section
describes the graphics object hierarchy, manipulating object properties, and
the use of important figure and axes properties.
10
Creating 3-D Graphs
Building a 3-D Graph . . . . . . . . . . . . . . . . 10-2
Line Plots of 3-D Data . . . . . . . . . . . . . . . . 10-3
Representing a Matrix As a Surface . .
Mesh and Surface Plots . . . . . . . . .
Visualizing Functions of Two Variables . .
Surface Plots of Nonuniformly Sampled Data
Parametric Surfaces . . . . . . . . . .
Hidden Line Removal . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 10-5
. 10-5
. 10-6
. 10-8
10-10
10-12
Coloring Mesh and Surface Plots . . . . .
Colormaps . . . . . . . . . . . . . . . .
Indexed Colors – Direct and Scaled Colormapping
Example – Mapping Surface Curvature to Color .
Altering Colormaps . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10-13
10-13
10-16
10-17
10-19
Truecolor . . . . . . . . . . . . . . . . . . . . 10-21
Texture Mapping . . . . . . . . . . . . . . . . . 10-24
10
Creating 3-D Graphs
Topics in 3-D Graphing
This section discusses how to plot 3-D vector and 2-D matrix (gridded) data.
• A Typical 3-D Graph – steps followed in creating a typical 3-D graph.
• Line Plots of 3-D Data – lines plots of data having x-, y-, and z-coordinates.
• Representing a Matrix as a Surface – graphs of matrix (2-D gridded) data.
• Coloring Mesh and Surface Plots – describes how MATLAB colors surface
and mesh plots, including colormaps, truecolor, and texture mapping.
10-2
A Typical 3-D Graph
A Typical 3-D Graph
This table illustrates typical steps involved in producing 3-D scenes containing
either data graphs or models of 3-D objects. Example applications include
pseudocolor surfaces illustrating the values of functions over specific regions
and objects drawn with polygons and colored with light sources to produce
realism. Usually, you follow either step 4a or step 4b.
Step
Typical Code
1 Prepare your data
Z = peaks(20);
2 Select window and position
figure(1)
subplot(2,1,2)
plot region within window
3 Call 3-D graphing function
h = surf(Z);
4 Set colormap and shading
colormap hot
shading interp
set(h,'EdgeColor','k')
algorithm
5 Add lighting
light('Position',[-2,2,20])
lighting phong
material([0.4,0.6,0.5,30])
set(h,'FaceColor',[0.7 0.7 0],...
'BackFaceLighting','lit')
6 Set viewpoint
view([30,25])
set(gca,'CameraViewAngleMode','Manual')
7 Set axis limits and tick marks
axis([5 15 5 15 −8 8])
set(gca,'ZTickLabel','Negative||Positive')
8 Set aspect ratio
set(gca,'PlotBoxAspectRatio',[2.5 2.5 1])
9 Annotate the graph with axis
xlabel('X Axis')
ylabel('Y Axis')
zlabel('Function Value')
title('Peaks')
labels, legend, and text
10 Print graph
set(gcf,'PaperPositionMode','auto')
print −dps2
10-3
10
Creating 3-D Graphs
Line Plots of 3-D Data
The 3-D analog of the plot function is plot3. If x, y, and z are three vectors of
the same length,
plot3(x,y,z)
generates a line in 3-D through the points whose coordinates are the elements
of x, y, and z and then produces a 2-D projection of that line on the screen. For
example, these statements produce a helix.
t = 0:pi/50:10*pi;
plot3(sin(t),cos(t),t)
axis square; grid on
40
30
20
10
0
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
Plotting Matrix Data
If the arguments to plot3 are matrices of the same size, MATLAB plots lines
obtained from the columns of X, Y, and Z. For example,
[X,Y] = meshgrid([−2:0.1:2]);
10-4
Line Plots of 3-D Data
Z = X.*exp(−X.^2−Y.^2);
plot3(X,Y,Z)
grid on
Notice how MATLAB cycles through line colors.
0.5
0
−0.5
2
2
1
1
0
0
−1
−1
−2
−2
10-5
10
Creating 3-D Graphs
Representing a Matrix As a Surface
MATLAB defines a surface by the z-coordinates of points above a rectangular
grid in the x-y plane. The plot is formed by joining adjacent points with straight
lines. Surface plots are useful for visualizing matrices that are too large to
display in numerical form and for graphing functions of two variables.
MATLAB can create different forms of surface plots. Mesh plots are wire-frame
surfaces that color only the lines connecting the defining points. Surface plots
display both the connecting lines and the faces of the surface in color. This table
lists the various forms.
Surface Plotting Functions
Function
Used to Create
mesh, surf
Surface plot
meshc, surfc
Surface plot with contour plot beneath it
meshz
Surface plot with curtain plot (reference plane)
pcolor
Flat surface plot (value is proportional only to
color)
surfl
Surface plot illuminated from specified direction
surface
Low-level function (on which high-level functions
are based) for creating surface graphics objects
Mesh and Surface Plots
The mesh and surf commands create 3-D surface plots of matrix data. If Z is a
matrix for which the elements Z(i,j) define the height of a surface over an
underlying (i,j) grid, then
mesh(Z)
generates a colored, wire-frame view of the surface and displays it in a 3-D
view. Similarly,
surf(Z)
10-6
Representing a Matrix As a Surface
generates a colored, faceted view of the surface and displays it in a 3-D view.
Ordinarily, the facets are quadrilaterals, each of which is a constant color,
outlined with black mesh lines, but the shading command allows you to
eliminate the mesh lines (shading flat) or to select interpolated shading
across the facet (shading interp).
Surface object properties provide additional control over the visual appearance
of the surface. You can specify edge line styles, vertex markers, face coloring,
lighting characteristics, and so on.
Visualizing Functions of Two Variables
The first step in displaying a function of two variables, z = f(x,y), is to generate
X and Y matrices consisting of repeated rows and columns, respectively, over
the domain of the function. Then use these matrices to evaluate and graph the
function.
The meshgrid function transforms the domain specified by two vectors, x and
y, into matrices, X and Y. You then use these matrices to evaluate functions of
two variables. The rows of X are copies of the vector x and the columns of Y are
copies of the vector y.
To illustrate the use of meshgrid, consider the sin(r)/r or sinc function. To
evaluate this function between –8 and 8 in both x and y, you need pass only one
vector argument to meshgrid, which is then used in both directions.
[X,Y] = meshgrid(−8:.5:8);
R = sqrt(X.^2 + Y.^2) + eps;
The matrix R contains the distance from the center of the matrix, which is the
origin. Adding eps prevents the divide by zero (in the next step) that produces
Inf values in the data.
Forming the sinc function and plotting Z with mesh results in the 3-D surface.
Z = sin(R)./R;
mesh(Z)
10-7
10
Creating 3-D Graphs
1
0.5
0
−0.5
10
10
5
5
0
0
−5
−5
−10
−10
Emphasizing Surface Shape
MATLAB provides a number of techniques that can enhance the information
content of your graphs. For example, this graph of the sinc function uses the
same data as the previous graph, but employs lighting and view adjustment to
emphasize the shape of the graphed function (daspect, axis, camlight, view).
surf(X,Y,Z,'FaceColor','interp',...
'EdgeColor','none',...
'FaceLighting','phong')
daspect([5 5 1])
axis tight
view(-50,30)
camlight left
10-8
Representing a Matrix As a Surface
See the surf function for more information on surface plots.
Surface Plots of Nonuniformly Sampled Data
You can use meshgrid to create a grid of uniformly sampled data points at
which to evaluate and graph the sinc function. MATLAB then constructs the
surface plot by connecting neighboring matrix elements to form a mesh of
quadrilaterals.
To produce a surface plot from nonuniformly sampled data, first use griddata
to interpolate the values at uniformly spaced points, and then use mesh and
surf in the usual way.
Example– Displaying Nonuniform Data on a Surface
This example evaluates the sinc function at random points within a specific
range and then generates uniformly sampled data for display as a surface plot.
The process involves these steps:
• Use linspace to generate evenly spaced values over the range of your
unevenly sampled data.
10-9
10
Creating 3-D Graphs
• Use meshgrid to generate the plotting grid with the output of linspace.
• Use griddata to interpolate the irregularly sampled data to the regularly
spaced grid returned by meshgrid.
• Use a plotting function to display the data.
1 First, generate unevenly sampled data within the range [−8, 8] and use it to
evaluate the function.
x
y
r
z
=
=
=
=
rand(100,1)*16 − 8;
rand(100,1)*16 − 8;
sqrt(x.^2 + y.^2) + eps;
sin(r)./r;
2 The linspace function provides a convenient way to create uniformly spaced
data with the desired number of elements. The following statements
produce vectors over the range of the random data with the same resolution
as that generated by the −8:.5:8 statement in the previous sinc example.
xlin = linspace(min(x),max(x),33);
ylin = linspace(min(y),max(y),33);
3 Now use these points to generate a uniformly spaced grid.
[X,Y] = meshgrid(xlin,ylin);
4 The key to this process is to use griddata to interpolate the values of the
function at the uniformly spaced points, based on the values of the function
at the original data points (which are random in this example). This
statement uses a triangle-based cubic interpolation to generate the new
data.
Z = griddata(x,y,z,X,Y,'cubic');
5 Plotting the interpolated and the nonuniform data produces
mesh(X,Y,Z) %interpolated
axis tight; hold on
plot3(x,y,z,'.','MarkerSize',15) %nonuniform
10-10
Representing a Matrix As a Surface
0.5
0
5
5
0
0
−5
−5
Parametric Surfaces
The functions that draw surfaces can take two additional vector or matrix
arguments to describe surfaces with specific x and y data. If Z is an m-by-n
matrix, x is an n-vector, and y is an m-vector, then
mesh(x,y,Z,C)
describes a mesh surface with vertices having color C(i,j) and located at the
points
(x(j), y(i), Z(i,j))
where x corresponds to the columns of Z and y to its rows.
More generally, if X, Y, Z, and C are matrices of the same dimensions, then
mesh(X,Y,Z,C)
describes a mesh surface with vertices having color C(i,j) and located at the
points
(X(i,j), Y(i,j), Z(i,j))
10-11
10
Creating 3-D Graphs
This example uses spherical coordinates to draw a sphere and color it with the
pattern of pluses and minuses in a Hadamard matrix, an orthogonal matrix
used in signal processing coding theory. The vectors theta and phi are in the
range –π ≤ theta ≤ π and –π/2 ≤ phi ≤ π/2. Because theta is a row vector and phi
is a column vector, the multiplications that produce the matrices X, Y, and Z are
vector outer products.
k = 5;
n = 2^k–1;
theta = pi*(–n:2:n)/n;
phi = (pi/2)*(–n:2:n)'/n;
X = cos(phi)*cos(theta);
Y = cos(phi)*sin(theta);
Z = sin(phi)*ones(size(theta));
colormap([0 0 0;1 1 1])
C = hadamard(2^k);
surf(X,Y,Z,C)
axis square
1
0.5
0
−0.5
−1
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
10-12
−1
Representing a Matrix As a Surface
Hidden Line Removal
By default, MATLAB removes lines that are hidden from view in mesh plots,
even though the faces of the plot are not colored. You can disable hidden line
removal and allow the faces of a mesh plot to be transparent with the command
hidden off
This is the surface plot with hidden set to off.
1
0.5
0
−0.5
10
5
10
5
0
0
−5
−5
−10
−10
10-13
10
Creating 3-D Graphs
Coloring Mesh and Surface Plots
You can enhance the information content of surface plots by controlling the
way MATLAB applies color to these plots. MATLAB can map particular data
values to colors specified explicitly or can map the entire range of data to a
predefined range of colors called a colormap.
There are two coloring techniques:
• Indexed Color – MATLAB colors the surface plot by assigning each data
point an index into the figure’s colormap. The way MATLAB applies these
colors depends on the type of shading used (faceted, flat, or interpolated).
• Truecolor – MATLAB colors the surface plot using the explicitly specified
colors (i.e., the RGB triplets). The way MATLAB applies these colors depends
on the type of shading used (faceted, flat, or interpolated). To be rendered
accurately, truecolor requires computers with 24-bit displays; however,
MATLAB simulates truecolor on indexed systems. See the shading
command for information on the types of shading.
The type of color data you specify (i.e., single values or RGB triplets)
determines how MATLAB interprets it. When you create a surface plot, you
can:
• Provide no explicit color data, in which case MATLAB generates colormap
indices from the z-data.
• Specify an array of color data that is equal in size to the z- data and is used
for indexed colors.
• Specify an m-by-n-by-3 array of color data that defines an RGB triplet for
each element in the m-by-n z-data array and is used for truecolor.
Colormaps
Each MATLAB figure window has a colormap associated with it. A colormap is
simply a three-column matrix whose length is equal to the number of colors it
defines. Each row of the matrix defines a particular color by specifying three
values in the range 0 to 1. These values define the RGB components (i.e., the
intensities of the red, green, and blue video components).
The colormap function, with no arguments, returns the current figure’s
colormap.
10-14
Coloring Mesh and Surface Plots
For example, MATLAB ’s default colormap contains 64 colors and the 57th
color is red.
cm = colormap;
cm(57,:)
ans =
1 0 0
This table lists some representative RGB color definitions.
Red
Green
Blue
Color
0
0
0
black
1
1
1
white
1
0
0
red
0
1
0
green
0
0
1
blue
1
1
0
yellow
1
0
1
magenta
0
1
1
cyan
0.5
0.5
0.5
gray
0.5
0
0
dark red
1
0.62
0.40
copper
0.49
1
0.83
aquamarine
You can create colormaps with MATLAB ’s array operations or you can use any
of several functions that generate useful maps, including hsv, hot, cool,
summer, and gray. Each function has an optional parameter that specifies the
number of rows in the resulting map.
For example,
hot(m)
10-15
10
Creating 3-D Graphs
creates an m-by-3 matrix whose rows specify the RGB intensities of a map
that varies from black, through shades of red, orange, and yellow, to white.
If you do not specify the colormap length, MATLAB creates a colormap the
same length as the current colormap. The default colormap is jet(64).
If you use long colormaps (> 64 colors) in each of several figures windows, it
may become necessary for the operating system to swap in different color
lookup tables as the active focus is moved among the windows. See “Controlling
How MATLAB Uses Color” in the “Figure Properties” chapter for more
information on how MATLAB manages color.
Displaying Colormaps
The colorbar function displays the current colormap, either vertically or
horizontally, in the figure window along with your graph. For example, the
statements
[x,y] = meshgrid([−2:.2:2]);
Z = x.*exp(−x.^2−y.^2);
surf(x,y,Z,gradient(Z))
colorbar
produce a surface plot and a vertical strip of color corresponding to the
colormap.
10-16
Coloring Mesh and Surface Plots
0.15
0.5
0.1
0
0.05
0
−0.5
2
2
1
1
0
−0.05
0
−1
−1
−2
−2
Note how the colorbar indicates the mapping of data value to color with the axis
labels.
Indexed Colors – Direct and Scaled Colormapping
MATLAB can use two different methods to map indexed color data to the
colormap – direct and scaled.
Direct Mapping
Direct mapping uses the color data directly as indices into the colormap. For
example, a value of 1 points to the first color in the colormap, a value of 2 points
to the second color, and so on. If the color data is noninteger, MATLAB rounds
it towards zero. Values greater than the number of colors in the colormap are
set equal to the last color in the colormap (i.e., the number length(colormap)).
Values less than 1 are set to 1.
Scaled Mapping
Scaled mapping uses a two-element vector [cmin cmax] (specified with the
caxis command) to control the mapping of color data to the figure colormap.
cmin specifies the data value to map to the first color in the colormap and cmax
10-17
10
Creating 3-D Graphs
specifies the data value to map to the last color in the colormap. Data values in
between are linearly transformed from the second to the next-to-last color,
using the expression.
colormap_index = fix((color_data−cmin)/(cmax−cmin)*cm_length)+1
cm_length is the length of the colormap.
By default, MATLAB sets cmin and cmax to span the range of the color data of
all graphics objects within the axes. However, you can set these limits to any
range of values. This enables you to display multiple axes within a single figure
window and use different portions of the figure’s colormap for each one. See the
“Calculating Color Limits” section in the “Axes Properties” chapter for an
example that uses color limits.
By default, MATLAB uses scaled mapping. To use direct mapping, you must
turn off scaling when you create the plot. For example,
surf(Z,C,'CDataMapping','direct')
See surface for more information on specifying color data.
Specifying Indexed Colors
When creating a surface plot with a single matrix argument, surf(Z) for
example, the argument Z specifies both the height and the color of the surface.
MATLAB transforms Z to obtain indices into the current colormap.
With two matrix arguments, the statement
surf(Z,C)
independently specifies the color using the second argument.
Example – Mapping Surface Curvature to Color
The Laplacian of a surface plot is related to its curvature; it is positive for
functions shaped like i^2 + j^2 and negative for functions shaped like –(i^2
+ j^2). The function del2 computes the discrete Laplacian of any matrix. For
example, use del2 to determine the color for the data returned by peaks.
P = peaks(40);
C = del2(P);
surf(P,C)
colormap hot
10-18
Coloring Mesh and Surface Plots
Creating a color array by applying the Laplacian to the data is useful because
it causes regions with similar curvature to be drawn in the same color.
surf(P,del2(P))
10
5
0
−5
−10
40
30
40
30
20
20
10
10
0
0
Compare this surface coloring with that produced by the statements
surf(P)
colormap hot
which use the same colormap, but maps regions with similar z value (height
above the x-y plane) to the same color.
10-19
10
Creating 3-D Graphs
surf(P)
10
5
0
−5
−10
40
30
40
30
20
20
10
10
0
0
Altering Colormaps
Because colormaps are matrices, you can manipulate them like other arrays.
The brighten function takes advantage of this fact to increase or decrease the
intensity of the colors. Plotting the values of the R, G, and B components of a
colormap using rgbplot illustrates the effects of brighten.
brighten(copper,−0.5)
brighten(copper,0.5)
1
1
1
0.9
0.9
0.9
0.8
0.8
0.8
0.7
0.7
0.7
0.6
0.6
0.6
0.5
0.5
0.5
0.4
0.4
0.4
0.3
0.3
0.3
0.2
0.2
0.2
0.1
0.1
0
0
10-20
copper
10
20
30
40
50
60
70
0
0
0.1
10
20
30
40
50
60
70
0
0
10
20
30
40
50
60
70
Coloring Mesh and Surface Plots
NTSC Color Encoding
The brightness component of television signals uses the NTSC color encoding
scheme.
b = .30*red + .59*green + .11*blue
= sum(diag([.30 .59 .11])*map')';
Using the nonlinear grayscale map,
colormap([b b b])
effectively converts a color image to its NTSC black-and-white equivalent.
10-21
10
Creating 3-D Graphs
Truecolor
Computer systems with 24-bit displays are capable of displaying over 16
million (224) colors, as opposed to the 256 colors available on 8-bit displays. You
can take advantage of this capability by defining color data directly as RGB
values and eliminating the step of mapping numerical values to locations in a
colormap.
Specify truecolor using an m-by-n-by-3 array, where the size of Z is m-by-n.
Blue
Green
Red
m-by-n matrix defining
surface plot
Corresponding m-by-n-by-3 matrix
specifying truecolor for the surface plot
For example, the statements
Z = peaks(25);
C(:,:,1) = rand(25);
C(:,:,2) = rand(25);
C(:,:,3) = rand(25);
surf(Z,C)
create a plot of the peaks matrix with random coloring.
10-22
Truecolor
You can set surface properties as with indexed color.
surf(Z,C,'FaceColor','interp','FaceLighting','phong')
camlight right
10-23
10
Creating 3-D Graphs
Rendering Method for Truecolor
MATLAB always uses either OpenGL or the zbuffer render method when
displaying truecolor. If the figure RendererMode property is set to auto,
MATLAB automatically switches the value of the Renderer property to
zbuffer whenever you specify truecolor data.
If you explicitly set Renderer to painters (this sets RendererMode to manual)
and attempt to define an image, patch, or surface object using truecolor,
MATLAB returns a warning and does not render the object.
See the image, patch, and surface functions for information on defining
truecolor for these objects.
Simulating Truecolor – Dithering
You can use truecolor on computers that do not have 24-bit displays. In this
case, MATLAB uses a special colormap designed to produce results that are as
close as possible, given the limited number of colors available. See “Dithering
Truecolor on Indexed Color Systems” in the “Figure Properties” chapter for
more information on the use of a dithermap.
10-24
Texture Mapping
Texture Mapping
Texture mapping is a technique for mapping a 2-D image onto a 3-D surface by
transforming color data so that it conforms to the surface plot. It allows you to
apply a “texture,” such as bumps or wood grain, to a surface without
performing the geometric modeling necessary to create a surface with these
features. The color data can also be any image, such as a scanned photograph.
Texture mapping allows the dimensions of the color data array to be different
from the data defining the surface plot. You can apply an image of arbitrary
size to any surface. MATLAB interpolates texture color data so that it is
mapped to the entire surface.
Example – Texture Mapping a Surface
This example creates a spherical surface using the sphere function and texture
maps it with an image of the earth taken from space. Because the earth image
is a view of earth from one side, this example maps the image to only one side
of the sphere, padding the image data with 1s. In this case, the image data is a
257-by-250 matrix so it is padded equally on each side with two 257-by-125
matrices of 1s by concatenating the three matrices together.
To use texture mapping, set the FaceColor to texturemap and assign the image
to the surface’s CData.
load earth % Load image data, X, and colormap, map
sphere; h = findobj('Type','surface');
hemisphere = [ones(257,125),...
X,...
ones(257,125)];
set(h,'CData',flipud(hemisphere),'FaceColor','texturemap')
colormap(map)
axis equal
view([90 0])
set(gca,'CameraViewAngleMode','manual')
view([65 30])
10-25
10
Creating 3-D Graphs
10-26
11
Defining the View
Setting the Viewpoint . . . . . . . . . . . . . . . . 11-3
Defining Scenes with Camera Graphics
. . . . . . . 11-7
View Control with the Camera Toolbar . . . . . . . . 11-8
Camera Graphics Functions . . . . . . . . . . . . 11-20
Dollying the Camera . . . . . . . . . . . . . . . 11-21
Moving the Camera Through a Scene
. . . . . . . 11-23
Low-Level Camera Properties . . . . . . . . . . . 11-29
View Projection Types
. . . . . . . . . . . . . . 11-35
Understanding Axes Aspect Ratio . . . . . . . . . 11-40
Axes Aspect Ratio Properties
. . . . . . . . . . . 11-45
11
Defining the View
View Definition Topics
The view is the particular orientation you select to display your graph or
graphical scene. The term viewing refers to the process of displaying a
graphical scene from various directions, zooming in or out, changing the
perspective and aspect ratio, flying by, and so on.
This section describes how to define the various viewing parameters to obtain
the view you want. Generally, viewing is applied to 3-D graphs or models,
although you may want to adjust the aspect ratio of 2-D views to achieve
specific proportions or make a graph fit in a particular shape.
MATLAB viewing is composed of two basic areas:
• Positioning the viewpoint to orient the scene
• Setting the aspect ratio and relative axis scaling to control the shape of the
objects being displayed
Positioning the Viewpoint
• Setting the Viewpoint – discusses how to specify the point from which you
view a graph in terms of azimuth and elevation. This is conceptually simple,
but does have limitations.
• Defining Scenes with Camera Graphics, View Control with the Camera
Toolbar, and Camera Graphics Functions – describes how to compose
complex scenes using MATLAB’s camera viewing model.
• Dollying the Camera and Moving the Camera Through a Scene – illustrate
programming techniques for moving the view around and through scenes.
• Low-Level Camera Properties – lists the graphics properties that control the
camera and illustrates the effects they cause.
Setting the Aspect Ratio
• View Projection Types – discusses orthographic and perspective projection
types and illustrates their use.
• Understanding Axes Aspect Ratio and Axes Aspect Ratio Properties –
describes how MATLAB sets the aspect ratio of the axes and how you can
select the most appropriate setting for your graphs.
11-2
View Definition Topics
MATLAB automatically sets the view when you create a graph. The actual
view that MATLAB selects depends on whether you are creating a 2- or 3-D
graph. See the Default Viewpoint Selection and Default Aspect Ratio Selection
sections in this chapter for a description of how MATLAB defines the standard
view.
11-3
11
Defining the View
Setting the Viewpoint
MATLAB enables you to control the orientation of the graphics displayed in an
axes. You can specify the viewpoint, view target, orientation, and extent of the
view displayed in a figure window. These viewing characteristics are controlled
by a set of graphics properties. You can specify values for these properties
directly or use the view command to select a view direction and rely on
MATLAB’s automatic property selection to define a reasonable view.
Specifying Azimuth and Elevation
The view command specifies the viewpoint by defining azimuth and elevation
with respect to the axis origin. Azimuth is a polar angle in the x-y plane, with
positive angles indicating counter-clockwise 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
Elevation
Viewpoint
x
Azimuth
-y
MATLAB automatically selects a viewpoint that is determined by whether the
plot is 2-D or 3-D:
• For 2-D plots, the default is azimuth = 0° and elevation = 90°.
11-4
Setting the Viewpoint
• For 3-D plots, the default is azimuth = −37.5° and elevation = 30°.
For example, these statements create a 3-D surface plot and display it in the
default 3-D view.
[X,Y] = meshgrid([−2:.25:2]);
Z = X.*exp(−X.^2 −Y.^2);
surf(X,Y,Z)
Azimuth = −37.5° Elevation = 30°
z−axis
0.5
0
−0.5
2
1
2
1
0
0
−1
y−axis
−2
−1
−2
x−axis
The statement
view([180 0])
sets the viewpoint so you are looking in the negative y-direction with your eye
at the z = 0 elevation.
11-5
11
Defining the View
Azimuth = 180° Elevation = 0°
z−axis
0.5
0
−0.5
2
1
0
x−axis
−1
−2
You can move the viewpoint to a location below the axis origin using a negative
elevation.
view([−37.5 −30])
Azimuth = −37.5° Elevation = −30°
z−axis
0.5
0
−2
−0.5
−2
−1
−1
0
0
1
1
x−axis
11-6
2
2
y−axis
Setting the Viewpoint
Limitations of Azimuth and Elevation
Specifying the viewpoint in terms of azimuth and elevation is conceptually
simple, but it has limitations. It does not allow you to specify the actual position
of the viewpoint, just its direction, and the z-axis is always pointing up. It does
not allow you to zoom in and out on the scene or perform arbitrary rotations
and translations.
MATLAB’s camera graphics provides greater control than the simple
adjustments allowed with azimuth and elevation. The following sections
discusses how to use camera properties to control the view.
11-7
11
Defining the View
Defining Scenes with Camera Graphics
When you look at the graphics objects displayed in an axes, you are viewing a
scene from a particular location in space that has a particular orientation with
regard to the scene. MATLAB provides functionality, analogous to that of a
camera with a zoom lens, that enables you to control the view of the scene
created by MATLAB.
This picture illustrates how the camera is defined in terms of properties of the
axes.
CameraViewAngle
CameraTarget
Axes plot box
1
Axes position rectangle
0.8
0.6
0.4
0.2
0
1
1
0.5
0.8
0.6
0.4
0.2
0
0
Viewing
Axis
CameraUpVector
projected onto
film plane
CameraPosition
11-8
View Control with the Camera Toolbar
View Control with the Camera Toolbar
The Camera Toolbar enables you to perform a number of viewing operations
interactively. To use the Camera Toolbar:
• Display the toolbar by selecting Camera Toolbar from the figure window’s
View menu.
• Select the type of camera motion control you want to use.
• Position the cursor over the figure window and click, hold down the right
mouse button, then move the cursor in the desired direction.
MATLAB updates the display immediately as you move the mouse.
Camera Toolbar
The toolbar contains the following parts:
Camera Motion Controls
Principal Axis
Selector
Scene Projection Reset and
Light Type
Stop
• Camera Motion Controls – these tools select which camera motion function
to enable. You can also access the camera motion controls from the Tools
menu.
• Principal Axis Selector – some camera controls operate with respect to a
particular axis. These selectors enable you to select the principal axis or to
select non-axis constrained motion. The selectors are grayed out when not
applicable to the currently selected function. You can also access the
principal axis selector from the Tools menu.
• Scene Light – The scene light button toggles a light source on or off in the
scene (one light per axes).
• Projection Type – You can select orthographic or perspective projection
types.
• Reset and Stop – Reset returns the scene to the standard 3-D view. Stop
causes the camera to stop moving (this can be useful if you apply too much
11-9
11
Defining the View
cursor movement). You can also access the an expanded set of reset functions
from the Tools menu.
Principal Axes
The principal axis of a scene defines the direction that is oriented upward on
the screen. For example, a MATLAB surface plot aligns the up direction along
the positive z axis.
Principal axes constrain camera-tool motion along axes that are (on the screen)
parallel and perpendicular to the principal axis that you select. Specifying a
principal axis is useful if your data is define with respect to a specific axis. Z is
the default principal axis, since this matches MATLAB’s default 3-D view.
Three of the camera tools (Orbit, Pan/Tilt, and Walk) allow you to select a
principal axis, as well as axis-free motion. On the screen, the axes of rotation
are determined by a vertical and a horizontal line, both of which pass through
the point defined by the CameraTarget property and are parallel and
perpendicular to the principal axis.
For example, when the principal axis is z, movement occurs about:
• A vertical line that passes through the camera target and is parallel to the z
axis
• A horizontal line that passes through the camera target and is perpendicular
to the z axis
This means the scene (or camera, as the case may be) moves in an arc whose
center is at the camera target. The following picture illustrates the rotation
axes for a z principal axis.
11-10
View Control with the Camera Toolbar
Camera Target
Horizontal cursor motion
results in rotation about the
(blue) vertical axis.
Vertical cursor motion
causes rotation about the
(red) horizontal axis.
Cursor Motion
Z Principal axis
The axes of rotation always pass through the camera target.
Optimizing for 3-D Camera Motion
When you create a plot, MATLAB displays it with an aspect ratio that fits the
figure window. This behavior may not create an optimum situation for the
manipulation of 3-D graphics as it can lead to distortion as you move the
camera around scene. To avoid possible distortion, it is best to switch to a 3-D
visualization mode (enabled from the command line with the command axis
vis3d). When using the camera toolbar, MATLAB automatically switches to
the 3-D visualization mode, but warns you first with the following dialog box.
11-11
11
Defining the View
This dialog box appears only once per MATLAB session.
For more information about the underlying effects of related camera
properties, see the “Understanding Axes Aspect Ratio” section in this chapter.
The next section “Camera Motion Controls” discusses how to use each tool.
Camera Motion Controls
This section discusses the individual camera motion functions selectable from
the toolbar.
Note When interpreting the following diagrams, keep in mind that the
camera always points towards the camera target. See the “Defining Scenes
with Camera Graphics” section in this chapter for an illustration of the
graphics properties involved in camera motion.
Orbit Camera
Orbit Camera rotates the camera about the z-axis (by default). You can select
x-, y-, z-, or free-axis rotation using the Principal Axis Selectors. When using
no principal axis, you can rotate about an arbitrary axis.
11-12
View Control with the Camera Toolbar
Graphics Properties. Orbit camera changes the CameraPosition property while
keeping the CameraTarget fixed.
1
0.8
0.6
0.4
0.2
1
0
1
0.5
0.8
0.6
0.4
0.2
0
0
Cursor Motion
X, Y, or Z Principal
axis
No principal Axis
Orbit Scene Light
The scene light is a light source that is placed with respect to the camera
position. By default, the scene light is positioned to the right of the camera (i.e.,
camlight right). Orbit Scene Light changes the light’s offset from the camera
position. There is only one scene light, however, you can add other lights using
the light command.
Toggle the scene light on and off by clicking on the yellow light bulb icon.
11-13
11
Defining the View
Graphics Properties. Orbit Scene Light moves the scene light by changing the
light’s Position property.
Pan/Tilt Camera
Pan/Tilt Camera moves the point in the scene that the camera points to while
keeping the camera fixed. The movement occurs in an arc about the z-axis by
default. You can select x-, y-, z-, or free-axis rotation using the Principal Axes
Selectors.
Graphics Properties. Pan/Tilt Camera moves the point in the scene that the
camera is pointing to by changing the CameraTarget property.
1
0.8
0.6
0.4
0.2
0
1
1
0.5
0.8
0.6
0.4
0.2
Cursor Motion
X, Y, or Z Principal
axis
No principal Axis
11-14
0
0
View Control with the Camera Toolbar
Move Camera Horizontally/Vertically
Moving the cursor horizontally or vertically (or any combination of the two)
moves the scene in the same direction.
Graphics Properties. The horizontal and vertical movement is achieved by
moving the CameraPosition and the CameraTarget in unison along parallel
lines.
1
0.8
0.6
0.4
0.2
1
0
1
0.5
0.8
0.6
0.4
0.2
0
0
Cursor Motion
Vertical
Horizontal
11-15
11
Defining the View
Move Camera Forward and Backwards
Moving the cursor up or to the right moves the camera towards the scene.
Moving the cursor down or to the left moves the camera away from the scene.
It is possible to move the camera through objects in the scene and to the other
side of the camera target.
Graphics Properties. This function moves the CameraPosition along the line
connecting the camera position and the camera target.
1
0.8
0.6
0.4
0.2
1
0
1
0.5
0.8
0.6
0.4
0.2
Cursor Motion
Closer to
target
Farther
from target
11-16
0
0
View Control with the Camera Toolbar
Zoom Camera
Zoom Camera makes the scene larger as you move the cursor up or to the right
and smaller as you move the cursor down or to the left. Zooming does not move
the camera and therefore cannot move the viewpoint through objects in the
scene.
Graphics Properties. Zoom is implemented by changing the CameraViewAngle.
The larger the angle, the smaller the scene appears, and vice versa.
Camera
View
Angle
1
0.8
0.6
0.4
0.2
0
1
1
0.5
0.8
0.6
0.4
0.2
0
0
Cursor Motion
Larger
angle
Smaller
angle
11-17
11
Defining the View
Camera Roll
Camera Roll rotates the camera about the viewing axis, thereby rotating the
view on the screen.
Graphics Properties. Camera Roll changes the CameraUpVector
1
0.8
0.6
Apparent View Rotation
0.4
0.2
0
1
1
0.5
0.8
0.6
0.4
0.2
0
0
Actual Camera Rotation
Cursor Motion
Counterclockwise
around camera
target
Clockwise around
camera target
11-18
View Control with the Camera Toolbar
Walk Camera
Walk Camera moves the camera in the direction of the camera target and
moves the camera target by the same amount. It also pans the camera from
side to side. Walk Camera enables you to move the camera through the scene,
passing through objects that lie along the viewing axis.
Walk Camera is somewhat analogous to driving a car while keeping your eyes
pointed straight ahead. As you turn to the right, the objects in the scene move
off to the left.
Walk Camera is best used when viewing axis lies in a plane that is
perpendicular to the principle axis. For example, if Z is the principle axis, then
you should position the camera at the same Z value as that of the camera target
(you can do this using Orbit Camera). The toward or away motion then stays
at a constant Z value. You may find it useful to zoom out before using Walk
Camera.
Graphics Properties. Walk Camera modifies both the CameraPosition and the
CameraTarget, preserving the distance between them.
11-19
11
Defining the View
1
0.8
0.6
0.4
0.2
0
1
1
0.5
0.8
0.6
0.4
0.2
0
Cursor Motion
Towards or away
from scene
Pan left or right
11-20
0
Camera Graphics Functions
Camera Graphics Functions
The following table lists MATLAB functions that enable you to perform a
number of useful camera maneuvers. The individual command descriptions
provide information on using each one.
Functions
Purpose
camdolly
Move camera position and target
camlookat
View specific objects
camorbit
Orbit the camera about the camera target
campan
Rotate the camera target about the camera position
campos
Set or get the camera position
camproj
Set or get the projection type (orthographic or
perspective)
camroll
Rotate the camera about the viewing axis
camtarget
Set or get the camera target location
camup
Set or get the value of the camera up vector
camva
Set or get the value of the camera view angle
camzoom
Zoom the camera in or out on the scene
11-21
11
Defining the View
Dollying the Camera
In the camera metaphor, a dolly is a stage that enables movement of the
camera side to side with respect to the scene. The camdolly command
implements similar behavior by moving both the position of the camera and the
position of the camera target in unison (or just the camera position if you so
desire).
This example illustrates how to use camdolly to explore different regions of an
image.
Summary of Techniques
This example:
• Uses ginput to obtain the coordinates of locations on the image
• Uses the camdolly data coordinates option to move the camera and target to
the new position based on coordinates obtained from ginput
• Uses camva to zoom in and to fix the camera view angle, which is otherwise
under automatic control
Implementation
First load the Cape Cod image and zoom in by setting the camera view angle
(using camva).
load cape
image(X)
colormap(map)
axis image
camva(camva/2.5)
Then use ginput to select the x- and y-coordinates of the camera target and
camera position.
while 1
[x,y] = ginput(1);
if ~strcmp(get(gcf,'SelectionType'),'normal')
break
end
ct = camtarget;
dx = x - ct(1);
11-22
Dollying the Camera
dy = y - ct(2);
camdolly(dx,dy,ct(3),'movetarget','data')
drawnow
end
11-23
11
Defining the View
Moving the Camera Through a Scene
A fly-through is an effect created by moving the camera through three
dimensional space, giving the impression that you are flying along with the
camera as if in an aircraft. You can fly-through of regions of a scene that may
be otherwise obscured by objects in the scene or you can fly by a scene by
keeping the camera focused on a particular point.
To accomplish these effects you move the camera along a particular path, the
x axis for example, in a series of steps. To produce a fly-through, move both the
camera position and the camera target at the same time.
The following example makes use of the fly-though effect to view the interior of
an isosurface drawn within a volume defined by a vector field of wind velocities.
This data representing air currents over North America.
See coneplot for a fixed visualization of the same data.
Summary of Techniques
This example employs a number of visualization techniques. It uses:
• Isosurfaces and conplots to illustrate the flow through the volume
• Lighting to illuminate the isosurface and cones in the volume
• Stream lines to define a path for the camera through the volume
• Coordinated motion of the camera position, camera target, and light together
Graphing the Volume Data
The first step is to draw the isosurface and plot the air flow using cone plots.
See isosurface, isonormals, reducepatch, and coneplot for information on
using these commands.
Setting the data aspect ratio (daspect) to [1,1,1] before drawing the cone plot
enables MATLAB to calculate the size of the cones correctly for the final view.
load wind
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
hpatch = patch(isosurface(x,y,z,wind_speed,35));
isonormals(x,y,z,wind_speed,hpatch)
11-24
Moving the Camera Through a Scene
set(hpatch,’FaceColor’,’red’,’EdgeColor’,’none’);
[f vt] = reducepatch(isosurface(x,y,z,wind_speed,45),0.05);
daspect([1,1,1]);
hcone = coneplot(x,y,z,u,v,w,vt(:,1),vt(:,2),vt(:,3),2);
set(hcone,'FaceColor','blue','EdgeColor','none');
Setting Up the View
You need to define viewing parameters to ensure the scene displays correctly.
• Selecting a perspective projection provides the perception of depth as the
camera passes through the interior of the isosurface (camproj).
• Setting the camera view angle to a fixed value prevents MATLAB from
automatically adjusting the angle to encompass the entire scene as well as
zooming in to the desired amount (camva).
camproj perspective
camva(25)
Specifying the Light Source
Positioning the light source at the camera location and modifying the
reflectance characteristics of the isosurface and cones enhances the realism of
the scene.
• Creating a light source at the camera position provides a “headlight” that
moves along with the camera through the isosurface interior (camlight).
• Setting the reflection properties of the isosurface gives the appearance of a
dark interior (AmbientStrength set to 0.1) with highly reflective material
(SpecularStrength and DiffuseStrength set to 1).
• Setting the SpecularStrength of the cones to 1 makes them highly reflective.
hlight = camlight('headlight');
set(hpatch,'AmbientStrength',.1,...
'SpecularStrength',1,...
'DiffuseStrength',1);
set(hcone,'SpecularStrength',1);
set(gcf,'Color','k')
11-25
11
Defining the View
Selecting a Renderer
Because this example uses lighting, MATLAB must use either zbuffer or, if
available, OpenGL renderer settings. The OpenGL renderer is likely to be much
faster displaying the animation; however, you need to use gouraud lighting
with OpenGL, which is not as smooth as phong lighting, which you can use
with the zbuffer renderer. The two choices are
lighting gouraud
set(gcf,'Renderer','OpenGL')
or for zbuffer
lighting phong
set(gcf,'Renderer','zbuffer')
Defining the Camera Path as a Stream Line
Stream lines indicate the direction of flow in the vector field. This example uses
the x, y, and z coordinate data of a single stream line to map a path through the
volume. The camera is then moved along this path. The steps include:
• Create a stream line starting at the point x = 80, y = 30, z = 11
• Get the x, y, and z coordinate data of the stream line.
• Delete the stream line (note that you could also use stream3 to calculated the
stream line data without actually drawing the stream line.
hsline = streamline(x,y,z,u,v,w,80,30,11);
xd = get(hsline,'XData');
yd = get(hsline,'YData');
zd = get(hsline,'ZData');
delete(hsline)
Implementing the Fly-Through
To create a fly-through, move the camera position and camera target along the
same path. In this example, the camera target is placed five elements further
along the x-axis than the camera. Also, a small value is added to the camera
target x position to prevent the position of the camera and target from
becoming the same point if the condition xd(n) = xd(n+5) should occur:
11-26
Moving the Camera Through a Scene
• Update the camera position and camera target so that they both move along
the coordinates of the stream line.
• Move the light along with the camera.
• Call drawnow to display the results of each move.
for i=1:length(xd)-50
campos([xd(i),yd(i),zd(i)])
camtarget([xd(i+5)+min(xd)/100,yd(i),zd(i)])
camlight(hlight,'headlight')
drawnow
end
These snapshots illustrate the view at values of i equal to 10, 110, and 185.
11-27
11
Defining the View
11-28
Moving the Camera Through a Scene
11-29
11
Defining the View
Low-Level Camera Properties
Camera graphics is based on a group of axes properties that control the position
and orientation of the camera. In general, the camera commands make it
unnecessary to access these properties directly.
Property
What It Is
CameraPosition
Specifies the location of the viewpoint in axes units.
CameraPositionMode
In automatic mode, MATLAB determines the position based on the
scene. In manual mode, you specify the viewpoint location.
CameraTarget
Specifies the location in the axes that the camera points to.
Together with the CameraPosition, it defines the viewing axis.
CameraTargetMode
In automatic mode, MATLAB specifies the CameraTarget as the
center of the axes plot box. In manual mode, you specify the
location.
CameraUpVector
The rotation of the camera around the viewing axis is defined by a
vector indicating the direction taken as up.
CameraUpVectorMode
In automatic mode, MATLAB orients the up vector along the
positive y-axis for 2-D views and along the positive z-axis for 3-D
views. In manual mode, you specify the direction.
CameraViewAngle
Specifies the field of view of the “lens.” If you specify a value for
CameraViewAngle, MATLAB overrides stretch-to-fill behavior (see
the “Understanding Axes Aspect Ratio” section of this chapter).
CameraViewAngleMode
In automatic mode, MATLAB adjusts the view angle to the
smallest angle that captures the entire scene. In manual mode, you
specify the angle.
Setting CameraViewAngleMode to manual overrides stretch-to-fill
behavior.
Projection
11-30
Selects either an orthographic or perspective projection.
Low-Level Camera Properties
Default Viewpoint Selection
When all the camera mode properties are set to auto (the default), MATLAB
automatically controls the view, selecting appropriate values based on the
assumption that you want the scene to fill the position rectangle (which is
defined by the width and height components of the axes Position property).
By default, MATLAB:
• Sets the CameraPosition so the orientation of the scene is the standard
MATLAB 2-D or 3-D view (see the view command)
• Sets the CameraTarget to the center of the plot box
• Sets the CameraUpVector so the y-direction is up for 2-D views and the
z-direction is up for 3-D views
• Sets the CameraViewAngle to the minimum angle that makes the scene fill
the position rectangle (the rectangle defined by the axes Position property)
• Uses orthographic projection
This default behavior generally produces desirable results. However, you can
change these properties to produce useful effects.
Moving In and Out on the Scene
You can move the camera anywhere in the 3-D space defined by the axes. The
camera continues to point towards the target regardless of its position. When
the camera moves, MATLAB varies the camera view angle to ensure the scene
fills the position rectangle.
Moving Through a Scene
You can create a fly-by effect by moving the camera through the scene. To do
this, continually change CameraPosition property, moving it toward the
target. Since the camera is moving through space, it turns as it moves past the
camera target. Override MATLAB’s automatic resizing of the scene each time
you move the camera by setting the CameraViewAngleMode to manual.
If you update the CameraPosition and the CameraTarget, the effect is to pass
through the scene while continually facing the direction of movement.
If the Projection is set to perspective, the amount of perspective distortion
increases as the camera gets closer to the target and decreases as it gets farther
away.
11-31
11
Defining the View
Example – Moving Toward or Away from the Target
To move the camera along the viewing axis, you need to calculate new
coordinates for the CameraPosition property. This is accomplished by
subtracting (to move closer to the target) or adding (to move away from the
target) some fraction of the total distance between the camera position and the
camera target.
The function movecamera calculates a new CameraPosition that moves in on
the scene if the argument dist is positive and moves out if dist is negative.
function movecamera(dist) %dist in the range [-1 1]
set(gca,'CameraViewAngleMode','manual')
newcp = cpos − dist * (cpos − ctarg);
set(gca,'CameraPosition',newcp)
function out = cpos
out = get(gca,'CameraPosition');
function out = ctarg
out = get(gca,'CameraTarget');
CameraPosition
0.5
0
−2
CameraTarget
−0.5
2
0
1
0
−1
−2 2
Note that setting the CameraViewAngleMode to manual overrides MATLAB’s
stretch-to-fill behavior and may cause an abrupt change in the aspect ratio. See
11-32
Low-Level Camera Properties
the “Understanding Axes Aspect Ratio” section of this chapter for more
information on stretch-to-fill.
Making the Scene Larger or Smaller
Adjusting the CameraViewAngle property makes the view of the scene larger or
smaller. Larger angles cause the view to encompass a larger area, thereby
making the objects in the scene appear smaller. Similarly, smaller angles make
the objects appear larger.
Changing CameraViewAngle makes the scene larger or smaller without
affecting the position of the camera. This is desirable if you want to zoom in
without moving the viewpoint past objects that will then no longer be in the
scene (as could happen if you changed the camera position). Also, changing the
CameraViewAngle does not affect the amount of perspective applied to the
scene, as changing CameraPosition does when the figure Projection property
is set to perspective.
Revolving Around the Scene
You can use the view command to revolve the viewpoint about the z-axis by
varying the azimuth, and about the azimuth by varying the elevation. This has
the effect of moving the camera around the scene along the surface of a sphere
whose radius is the length of the viewing axis. You could create the same effect
by changing the CameraPosition, but doing so requires you to perform
calculations that MATLAB performs for you when you call view.
For example, the function orbit moves the camera around the scene.
function orbit(deg)
[az el] = view;
rotvec = 0:deg/10:deg;
for i = 1:length(rotvec)
view([az+rotvec(i) el])
drawnow
end
Rotation Without Resizing of Graphics Objects
When CameraViewAngleMode is auto, MATLAB calculates the
CameraViewAngle so that the scene is as large as can fit in the axes position
rectangle. This causes an apparent size change during rotation of the scene. To
11-33
11
Defining the View
prevent resizing during rotation, you need to set the CameraViewAngleMode to
manual (which happens automatically when you specify a value for the
CameraViewAngle property). To do this in the orbit function, add the
statement
set(gca,'CameraViewAngleMode','manual')
Rotation About the Viewing Axis
You can change the orientation of the scene by specifying the direction defined
as up. By default, MATLAB defines up as the y-axis in 2-D views
(the CameraUpVector is [0 1 0]) and the z-axis for 3-D views (the
CameraUpVector is [0 0 1]). However, you can specify up as any arbitrary
direction.
The vector defined by the CameraUpVector property forms one axis of the
camera’s coordinate system. Internally, MATLAB determines the actual
orientation of the camera up vector by projecting the specified vector onto the
plane that is normal to the camera direction (i.e., the viewing axis). This
simplifies the specification of the CameraUpVector property since it need not lie
in this plane.
In many cases, you may find it convenient to visualize the desired up vector in
terms of angles with respect to the axes x-, y-, and z-axes. You can then use
direction cosines to convert from angles to vector components. For a unit vector,
the expression simplifies to
z
γ
β
α
y
x
where the angles α, β, and γ are specified in degrees.
11-34
Low-Level Camera Properties
XComponent = cos(α × (pi ÷ 180));
YComponent = cos(β × (pi ÷ 180));
ZComponent = cos(γ × (pi ÷ 180));
(Consult a mathematics book on vector analysis for a more detailed
explanation of direction cosines.)
Example – Calculating a Camera Up Vector
To specify an up vector that makes an angle of 30° with the z-axis and lies in
the y-z plane, use the expression
upvec = [cos(90*(pi/180)),cos(60*(pi/180)),cos(30*(pi/180))];
and then set the CameraUpVector property.
set(gca,'CameraUpVector',upvec)
Drawing a sphere with this orientation produces
1
Z−Axis
0.5
0
−0.5
−1
1
0.5
0
−0.5
Y−Axis
−1
−1
−0.5
0
0.5
1
X−Axis
11-35
11
Defining the View
View Projection Types
MATLAB supports both orthographic and perspective projection types for
displaying 3-D graphics. The one you select depends on the type of graphics you
are displaying:
• orthographic projects the viewing volume as a rectangular parallelepiped
(i.e., a box whose opposite sides are parallel). Relative distance from the
camera does not affect the size of objects. This projection type is useful when
it is important to maintain the actual size of objects and the angles between
objects.
• perspective projects the viewing volume as the frustrum of a pyramid (a
pyramid whose apex has been cut off parallel to the base). Distance causes
foreshortening; objects further from the camera appear smaller. This
projection type is useful when you want to display realistic views of real
objects.
By default, MATLAB displays objects using orthographic projection. You can
set the projection type using the camproj command.
These pictures show a drawing of a dump truck (created with patch) and a
surface plot of a mathematical function, both using orthographic projection.
0.5
0
−0.5
2
2
1
1
0
0
−1
−1
−2
11-36
−2
View Projection Types
If you measure the width of the front and rear faces of the box enclosing the
dump truck, you’ll see they are the same size. This picture looks unnatural
because it lacks the apparent perspective you see when looking at real objects
with depth. On the other hand, the surface plot accurately indicates the values
of the function within rectangular space.
Now look at the same graphics objects with perspective added. The dump truck
looks more natural because portions of the truck that are farther from the
viewer appear smaller. This projection mimics the way human vision works.
The surface plot, on the other hand, looks distorted.
0.5
0
−0.5
2
1
2
1
0
0
−1
−1
−2
−2
Projection Types and Camera Location
By default, MATLAB adjusts the CameraPosition, CameraTarget, and
CameraViewAngle properties to point the camera at the center of the scene and
to include all graphics objects in the axes. If you position the camera so that
there are graphics objects behind the camera, the scene displayed can be
affected by both the axes Projection property and the figure Renderer
11-37
11
Defining the View
property. This table summarizes the interactions between projection type and
rendering method.
Orthographic
Perspective
Z-buffer
CameraViewAngle determines extent
of scene at CameraTarget
CameraViewAngle determines extent
of scene from CameraPosition to
infinity
Painters
All objects display regardless of
Not recommended if graphics objects
are behind the CameraPosition
CameraPosition
This diagram illustrates what you see (gray area) when using orthographic
projection and Z-buffer. Anything in front of the camera is visible.
Camera
Position
Camera
View
Angle
Camera
Target
To
Infinity
Orthographic projection and Z-buffer renderer
In perspective projection, you see only what is visible in the cone of the camera
view angle.
11-38
View Projection Types
Camera
View
Angle
Camera
Position
Camera
Target
To
Infinity
Perspective projection and Z-buffer renderer
Painters rendering method is less suited to moving the camera in 3-D space
because MATLAB does not clip along the viewing axis. Orthographic projection
in painters method results in all objects contained in the scene being visible
regardless of the camera position.
To
Infinity
Camera
Position
Camera
View
Angle
Camera
Target
To
Infinity
Orthographic projection and painters renderer
Printing 3-D Scenes
The same effects described in the previous section occur in hardcopy output.
However, because of the differences in the process of rendering to the screen
11-39
11
Defining the View
and to a printing format, MATLAB may render in Z-buffer and generate
printed output in painters. You may need to specify Z-buffer printing explicitly
to obtain the results displayed on the screen (use the −zbuffer option with the
print command ).
Additional Information
See the “Basic Printing and Exporting” chapter and the and the “Selecting a
Renderer” section in the “Figure Properties” chapter for information on
printing and rendering methods.
11-40
Understanding Axes Aspect Ratio
Understanding Axes Aspect Ratio
Axes shape graphics objects by setting the scaling and limits of each axis. When
you create a graph, MATLAB automatically determines axis scaling based on
the values or size of the plotted data, and then draws the axes to fit the space
available for display. Axes aspect ratio properties control how MATLAB
performs the scaling required to create a graph.
This section discusses MATLAB’s default behavior as well as techniques for
customizing graphs.
Stretch-to-Fill
By default, the size of the axes MATLAB creates for plotting is normalized to
the size of the figure window (but is slightly smaller to allow for borders). If you
resize the figure, the size and possibly the aspect ratio (the ratio of width to
height) of the axis changes proportionally. This enables the axes to always fill
the available space in the window. MATLAB also sets the x-, y-, and z-axis
limits to provide the greatest resolution in each direction, again optimizing the
use of available space.
This stretch-to-fill behavior is generally desirable; however, you may want to
control this process to produce specific results. For example, images need to be
displayed in correct proportions regardless of the aspect ratio of the figure
window, or you may want graphs always to be a particular size on a printed
page.
Specifying Axis Scaling
The axis command enables you to adjust the scaling of graphs. By default,
MATLAB finds the maxima and minima of the plotted data and chooses
appropriate axes ranges. You can override the defaults by setting axis limits.
axis([xmin xmax ymin ymax zmin zmax])
You can control how MATLAB scales the axes with predefined axis options:
• axis auto returns the axis scaling to its default, automatic mode. v = axis
saves the scaling of the axes of the current plot in vector v. For subsequent
graphics commands to have these same axis limits, follow them with
axis(v).
11-41
11
Defining the View
• axis manual freezes the scaling at the current limits. If you then set hold on,
subsequent plots use the current limits. Specifying values for axis limits also
sets axis scaling to manual.
• axis tight sets the axis limits to the range of the data.
• axis ij places MATLAB into its “matrix” axes mode. The coordinate system
origin is at the upper-left corner. The i-axis is vertical and is numbered from
top to bottom. The j-axis is horizontal and is numbered from left to right.
• axis xy places MATLAB into its default Cartesian axes mode. The
coordinate system origin is at the lower-left corner. The x-axis is horizontal
and is numbered from left to right. The y-axis is vertical and is numbered
from bottom to top.
Specifying Aspect Ratio
The axis command enables you to adjust the aspect ratio of graphs. Normally
MATLAB stretches the axes to fill the window. In many cases, it is more useful
to specify the aspect ratio of the axes based on a particular characteristic such
as the relative length or scaling of each axis. The axis command provides a
number of useful options for adjusting the aspect ratio:
• axis equal changes the current axes scaling so that equal tick mark
increments on the x-, y-, and z-axis are equal in length. This makes the
surface displayed by sphere look like a sphere instead of an ellipsoid. axis
equal overrides stretch-to-fill behavior.
• axis square makes each axis the same length and overrides stretch-to-fill
behavior.
• axis vis3d freezes aspect ratio properties to enable rotation of 3-D objects
and overrides stretch-to-fill. Use this option after other axis options to keep
settings from changing while you rotate the scene.
• axis image makes the aspect ratio of the axes the same as the image.
• axis auto returns the x-, y-, and z-axis limits to automatic selection mode.
• axis normal restores the current axis box to full size and removes any
restrictions on the scaling of the units. It undoes the effects of axis square.
Used in conjunction with axis auto, it undoes the effects of axis equal.
The axis command works by manipulating axes graphics object properties.
11-42
Understanding Axes Aspect Ratio
Example – axis Command Options
The following three pictures illustrate the effects of three axis options on
a cylindrical surface created with the statements
t = 0:pi/6:4*pi;
[x,y,z] = cylinder(4+cos(t),30);
surf(x,y,z)
axis normal is the default behavior. MATLAB automatically sets the axis
limits to span the data range along each axis and stretches the plot to fit
the figure window.
axis normal
1
0.8
0.6
0.4
0.2
0
5
5
0
0
−5
−5
axis square creates an axis that is square regardless of the shape of the
figure window. The cylindrical surface is no longer distorted because it is
not warped to fit the window. However, the size of one data unit is not
equal along all axes (the z-axis spans only one unit while the x- and y-axes
span 10 units each).
11-43
11
Defining the View
axis square
1
0.8
0.6
0.4
0.2
0
5
5
0
0
−5
−5
axis equal makes the length of one data unit equal along each axis while
maintaining a nearly square plot box. It also prevents warping of the axis
to fill the window’s shape.
axis equal
1
0.5
0
4
5
2
0
0
−2
−4
−5
11-44
Understanding Axes Aspect Ratio
Additional Commands for Setting Aspect Ratio
You can control the aspect ratio of your graph in three ways:
• Specifying the relative scales of the x, y, and z axes (data aspect ratio).
• Specifying the shape of the space defined by the axes (plot box aspect ratio).
• Specifying the axis limits.
The following commands enable you to set these values.
Command
Purpose
daspect
Set or query the data aspect ratio
pbaspect
Set or query the plot box aspect ratio
xlim
Set or query x-axis limits
ylim
Set or query y-axis limits
zlim
Set or query z-axis limits
See the “Axes Aspect Ratio Properties” section in this chapter for a list of the
axes properties that control aspect ratio.
11-45
11
Defining the View
Axes Aspect Ratio Properties
The axis command works by setting various axes object properties. You can set
these properties directly to achieve precisely the effect you want.
Property
What It Does
DataAspectRatio
Sets the relative scaling of the individual axis data values. Set
DataAspectRatio to [1 1 1] to display real-world objects in correct
proportions. Specifying a value for DataAspectRatio overrides
stretch-to-fill behavior.
DataAspectRatioMode
In auto, MATLAB selects axis scales that provide the highest
resolution in the space available.
PlotBoxAspectRatio
Sets the proportions of the axes plot box (Set box to on to see the
box). Specifying a value for PlotBoxAspectRatio overrides
stretch-to-fill behavior.
PlotBoxAspectRatioMode
In auto, MATLAB sets the PlotBoxAspectRatio to [1 1 1] unless
you explicitly set the DataAspectRatio and/or the axis limits.
Position
Defines the location and size of the axes with a four-element vector:
[left offset, bottom offset, width, height].
XLim, YLim, ZLim
Sets the minimum and maximum limits of the respective axes.
XLimMode, YLimMode,
ZLimMode
In auto, MATLAB selects the axis limits.
By default, MATLAB automatically determines values for all of these
properties (i.e., all the modes are auto) and then applies stretch-to-fill. You can
override any property’s automatic operation by specifying a value for the
property or setting its mode to manual. The value you select for a particular
property depends primarily on what type of data you want to display.
Much of the data visualized with MATLAB is either:
• Numerical data displayed as line or mesh plots
• Representations of real-world objects (e.g., a dump truck or a section of the
earth’s topography)
11-46
Axes Aspect Ratio Properties
In the first case, it is generally desirable to select axis limits that provide good
resolution in each axis direction and to fill the available space. Real-world
objects, on the other hand, need to be represented accurately in proportion,
regardless of the angle of view.
Default Aspect Ratio Selection
There are two key elements to MATLAB’s default behavior – normalizing the
axes size to the window size and stretch-to-fill.
The axes Position property specifies the location and dimensions of the axes.
The third and fourth elements of the Position vector (width and height)
define a rectangle in which MATLAB draws the axes (indicated by the dotted
line in the following pictures). MATLAB stretches the axes to fill this rectangle.
The default value for the axes Units property is normalized to the parent
figure dimensions. This means the shape of the figure window determines the
shape of the position rectangle. As you change the size of the window, MATLAB
reshapes the position rectangle to fit it.
Axes position
rectangle
1
Axes plot box
(display with
box on command)
0.5
0
−0.5
1
0
−1 −1
−0.5
0
0.5
1
The view is the 2-D projection of the plot box onto the screen.
11-47
11
Defining the View
Resized axes
position rectangle
Resized axes
plot box
1
0.5
0
1
1
0
0
−1 −1
As you can see, reshaping the axes to fit into the figure window can change the
aspect ratio of the graph. MATLAB applies stretch-to-fill so the axes fill the
position rectangle and in the process may distort the shape. This is generally
desirable for graphs of numeric data, but not for displaying objects realistically.
Example – MATLAB Defaults
MATLAB surface plots are well suited for visualizing mathematical functions
of two variables. For example, to display a mesh plot of the function,
2
2
z = xe ( – x – y ) evaluated over the range −2 ≤ x ≤ 2, –4 ≤ y ≤ 4, use the
statements
[X,Y] = meshgrid([–2:.15:2],[–4:.3:4]);
Z = X.∗exp(–X.^2 – Y.^2);
mesh(X,Y,Z)
11-48
Axes Aspect Ratio Properties
Axes position
rectangle
0.5
Axes plot box
0
Surface plot
−0.5
4
2
2
1
0
0
−2
−1
−4
−2
MATLAB ’s default property values are designed to:
• Select axis limits to span the range of the data (XLimMode, YLimMode, and
ZLimMode are set to auto).
• Provide the highest resolution in the available space by setting the scale of
each axis independently (DataAspectRatioMode and the
PlotBoxAspectRatioMode are set to auto).
• Draw axes that fit the position rectangle by adjusting the CameraViewAngle
and then stretch-to-fill the axes if necessary.
Overriding Stretch-to-Fill
To maintain a particular shape, you can specify the size of the axes in absolute
units such as inches, which are independent of the figure window size.
However, this is not a good approach if you are writing an M-file that you want
to work with a figure window of any size. A better approach is to specify the
aspect ratio of the axes and override automatic stretch-to-fill.
In cases where you want a specific aspect ratio, you can override stretching by
specifying a value for these axes properties:
• DataAspectRatio or DataAspectRatioMode
• PlotBoxAspectRatio or PlotBoxAspectRatioMode
• CameraViewAngle or CameraViewAngleMode
11-49
11
Defining the View
The first two sets of properties affect the aspect ratio directly. Setting either of
the mode properties to manual simply disables stretch-to-fill while maintaining
all current property values. In this case, MATLAB enlarges the axes until one
dimension of the position rectangle constrains it.
1
1
0.5
0.5
0
0
−0.5
1
−0.5
1
1
0
0
1
0
0
−1 −1
−1 −1
Setting the CameraViewAngle property disables stretch-to-fill, and also
prevents MATLAB from readjusting the size of the axes if you change the view.
Effects of Setting Aspect Ratio Properties
It is important to understand how properties interact with each other in order
to obtain the results you want. The DataAspectRatio, PlotBoxAspectRatio,
and the x-, y-, and z- axis limits (XLim, YLim, and ZLim properties) all place
constraints on the shape of the axes.
Data Aspect Ratio
The DataAspectRatio property controls the ratio of the axis scales. For a mesh
2
2
plot of the function, z = xe ( – x – y ) evaluated over the range −2 ≤ x ≤ 2, –4 ≤ y
≤4
[X,Y] = meshgrid([–2:.15:2],[–4:.3:4]);
Z = X.∗exp(–X.^2 – Y.^2);
11-50
Axes Aspect Ratio Properties
mesh(X,Y,Z)
the values are
get(gca,'DataAspectRatio')
ans =
4 8 1
This means that four units in length along the x-axis cover the same data
values as eight units in length along the y-axis and one unit in length along the
z-axis. The axes fill the plot box, which has an aspect ratio of [1 1 1] by default.
If you want to view the mesh plot so that the relative magnitudes along each
axis are equal with respect to each other, you can set the DataAspectRatio to
[1 1 1].
set(gca,'DataAspectRatio',[1 1 1])
0.5
0
−0.5
4
3
2
1
0
−1
2
1
−2
0
−3
−1
−4
−2
Setting the value of the DataAspectRatio property also sets the
DataAspectRatioMode to manual and overrides stretch-to-fill so the specified
aspect ratio is achieved.
11-51
11
Defining the View
Plot Box Aspect Ratio
Looking at the value of the PlotBoxAspectRatio for the graph in the previous
section shows that it has now taken on the former value of the
DataAspectRatio.
get(gca,'PlotBoxAspectRatio')
ans =
4 8 1
MATLAB has rescaled the plot box to accommodate the graph using the
specified DataAspectRatio.
The PlotBoxAspectRatio property controls the shape of the axes plot box.
MATLAB sets this property to [1 1 1] by default and adjusts the
DataAspectRatio property so that graphs fill the plot box if stretching is on, or
until reaching a constraint if stretch-to-fill has been overridden.
When you set the value of the DataAspectRatio and thereby prevent it from
changing, MATLAB varies the PlotBoxAspectRatio instead. If you specify
both the DataAspectRatio and the PlotBoxAspectRatio, MATLAB is forced to
changed the axis limits to obey the two constraints you have already defined.
Continuing with the mesh example, if you set both properties,
set(gca,'DataAspectRatio',[1 1 1],...
'PlotBoxAspectRatio',[1 1 1])
MATLAB changes the axis limits to satisfy the two constraints placed on the
axes.
11-52
Axes Aspect Ratio Properties
2
0
−2
2
2
0
0
−2
−2
−4
Adjusting Axis Limits
MATLAB enables you to set the axis limits to whichever values you want.
However, specifying a value for DataAspectRatio, PlotBoxAspectRatio, and
the axis limits, overconstrains the axes definition. For example, it is not
possible for MATLAB to draw the axes if you set these values.
set(gca,'DataAspectRatio',[1 1 1],...
'PlotBoxAspectRatio',[1 1 1],...
'XLim',[−4 4],...
'YLim',[−4 4],...
'ZLim',[−1 1])
In this case, MATLAB ignores the setting of the PlotBoxAspectRatio and
automatically determines its value. These particular values cause the
PlotBoxAspectRatio to return to its calculated value.
get(gca,'PlotBoxAspectRatio')
ans =
4 8 1
MATLAB can now draw the axes using the specified DataAspectRatio and axis
limits.
11-53
11
Defining the View
1
0
−1
4
4
2
2
0
0
−2
−2
−4
−4
Example – Displaying Real Objects
If you want to display an object so that it looks realistic, you need to change
MATLAB’s defaults. For example, this data defines a wedge-shaped patch
object.
vertex_list =
0
0
1
1
0
0
1
1
0
1
1
0
0
1
1
0
0
0
0
0
1
1
4
4
vertex_connection =
1
2
3
2
6
7
4
3
7
1
5
8
1
2
6
5
6
7
4
3
8
4
5
8
patch('Vertices',vertex_list,'Faces',vertex_connection,...
'FaceColor','w','EdgeColor','k')
view(3)
11-54
Axes Aspect Ratio Properties
4
3.5
3
2.5
2
1.5
1
0.5
0
1
1
0.5
0.5
0
0
However, this axes distorts the actual shape of the solid object defined by the
data. To display it in correct proportions, set the DataAspectRatio.
set(gca,'DataAspectRatio',[1 1 1])
The units are now equal in the x-, y-, and z-directions and the axes is not being
stretched to fill the position rectangle, revealing the true shape of the object.
4
3.5
3
2.5
2
1.5
1
0.5
0
1 0.5
0
0
0.5 1
11-55
11
Defining the View
11-56
12
Lighting as a Visualization
Tool
Lighting . . . . . . . . . . . . . . . . . . . . . . 12-2
Lighting Commands
. . . . . . . . . . . . . . . . 12-3
Light Objects . . . . . . . . . . . . . . . . . . . . 12-4
Adding Lights to a Scene
. . . . . . . . . . . . . . 12-5
Properties That Affect Lighting
. . . . . . . . . . . 12-8
Selecting a Lighting Method . . . . . . . . . . . . 12-10
Reflectance Characteristics of Graphics Objects . . . 12-12
12
Lighting as a Visualization Tool
Lighting
Lighting is a technique for adding realism to a graphical scene. It does
this by simulating the highlights and dark areas that occur on objects
under natural lighting (e.g., the directional light that comes from the
sun). To create lighting effects, MATLAB defines a graphics object called
a light.
Lighting Examples
These examples illustrate the use of lighting in a visualization context.
• Tracing a stream line through a volume – sets properties of surfaces,
patches, and lights. See "Example – "Creating a Fly-Through" in the
"Defining the View Chapter".
• Using slice planes and cone plots – sets lighting characteristics of
objects in a scene independently to achieve a desired result. See the
coneplot function.
• Lighting multiple slice planes independently to visualize fluid flow.
See the "Example - Slicing Fluid Flow Data" section in the "Volume
Visualization Techniques" chapter.
• Combining single-color lit surfaces with interpolated coloring. See the
"Example - Visualizing MRI Data" section in the "Volume
Visualization Techniques" chapter.
• Employing lighting to reveal surface shape. The fluid flow isosurface
example and the surface plot of the sinc function examples illustrate
this technique. See the "Example - Isosurfaces in Fluid Flow Data"
section in the "Volume Visualization Techniques" chapter and the
"Visualizing Functions of Two Variables" section in the "Creating 3-D
Graphs" chapter.
12-2
Lighting Commands
Lighting Commands
MATLAB provides commands that enable you to position light sources
and adjust the characteristics of lit objects. These commands include the
following.
Command
Purpose
camlight
Create or move a light with respect to the
camera position
lightangle
Create or position a light in spherical
coordinates
light
Create a light object
lighting
Select a lighting method
material
Set the reflectance properties of lit objects
You may find it useful to set light or lit-object properties directly to
achieve specific results. In addition to the material in this topic area, you
can explore the following lighting examples as an introduction to lighting
for visualization.
12-3
12
Lighting as a Visualization Tool
Light Objects
You create a light object using the light function. Three important light
object properties are:
• Color – the color of the light cast by the light object
• Style – either infinitely far away (the default) or local
• Position – the direction (for infinite light sources) or the location (for
local light sources)
The Color property determines the color of the directional light from the
light source. The color of an object in a scene is determine by the color of
the object and the light source.
The Style property determines whether the light source is a point source
(Style set to local), which radiates from the specified position in all
directions, or a light source placed at infinity (Style set to infinite),
which shines from the direction of the specified position with parallel
rays.
The Position property specifies the location of the light source in axes
data units. In the case of an light source at infinity, Position specifies
the direction to the light source.
Lights affect surface and patch objects that are in the same axes as the
light. These objects have a number of properties that alter the way they
look when illuminated by lights.
12-4
Adding Lights to a Scene
Adding Lights to a Scene
This example displays the membrane surface and illuminates it with a
light source emanating from the direction defined by the position vector
[0 −2 1]. This vector defines a direction from the axes origin passing
through the point with the coordinates 0, −2, 1. The light shines from
this direction towards the axes origin.
membrane
light('Position',[0 −2 1])
Creating a light activates a number of lighting-related properties
controlling characteristics, such as the ambient light and reflectance
properties of objects. It also switches to Z-buffer renderer if not already
in that mode.
Illuminating Mathematical Functions
Lighting can enhance surface graphs of mathematical functions. For
example, use the ezsurf command to evaluate the expression
2
2
2
2
sin ( x + y ) ÷ x + y over the region -6π to 6π.
ezsurf('sin(sqrt(x^2+y^2))/sqrt(x^2+y^2)',[-6*pi,6*pi])
12-5
12
Lighting as a Visualization Tool
Now add lighting using the lightangle command, which accepts the
light position in terms of azimuth and elevation.
view(0,75)
shading interp
lightangle(-45,30)
set(gcf,'Renderer','zbuffer')
set(findobj(gca,'type','surface'),...
'FaceLighting','phong',...
'AmbientStrength',.3,'DiffuseStrength',.8,...
'SpecularStrength',.9,'SpecularExponent',25,...
'BackFaceLighting','unlit')
12-6
Adding Lights to a Scene
After obtaining surface object’s handle using findobj, you can set
properties that affect how the light reflects from the surface. See the
"Properties That Affect Lighting" section of this chapter for more
detailed descriptions of these properties.
12-7
12
Lighting as a Visualization Tool
Properties That Affect Lighting
You cannot see light objects themselves, but you can see their effects on
any patch and surface objects present in the axes containing the light. A
number of functions create these objects, including surf, mesh, pcolor,
fill, and fill3 as well as the surface and patch functions.
You control lighting effects by setting various axes, light, patch, and
surface object properties. All properties have default values that
generally produce desirable results. However, you can achieve the
specific effect you want by adjusting the values of these properties.
12-8
Property
Effect
AmbientLightColor
An axes property that specifies the color of the background light
in the scene, which has no direction and affects all objects
uniformly. Ambient light effects occur only when there is a
visible light object in the axes.
AmbientStrength
A patch and surface property that determines the intensity of
the ambient component of the light reflected from the object.
DiffuseStrength
A patch and surface property that determines the intensity of
the diffuse component of the light reflected from the object.
SpecularStrength
A patch and surface property that determines the intensity of
the specular component of the light reflected from the object.
SpecularExponent
A patch and surface property that determines the size of the
specular highlight.
SpecularColorReflectance
A patch and surface property that determines the degree to
which the specularly reflected light is colored by the object color
or the light source color.
FaceLighting
A patch and surface property that determines the method used
to calculate the effect of the light on the faces of the object.
Choices are either no lighting, or flat, Gouraud, or Phong
lighting algorithms.
Properties That Affect Lighting
Property
Effect
EdgeLighting
A patch and surface property that determines the method used
to calculate the effect of the light on the edges of the object.
Choices are either no lighting, or flat, Gouraud, or Phong
lighting algorithms.
BackFaceLighting
A patch and surface property that determines how faces are lit
when their vertex normals point away from the camera. This
property is useful for discriminating between the internal and
external surfaces of an object.
FaceColor
A patch and surface property that specifies the color of the object
faces.
EdgeColor
A patch and surface property that specifies the color of the object
edges.
VertexNormals
A patch and surface property that contains normal vectors for
each vertex of the object. MATLAB uses vertex normal vectors to
perform lighting calculations. While MATLAB automatically
generates this data, you can also specify your own vertex
normals.
NormalMode
A patch and surface property that determines whether MATLAB
recalculates vertex normals if you change object data (auto) or
uses the current values of the VertexNormals property (manual).
If you specify values for VertexNormals, MATLAB sets this
property to manual.
See a description of all axes, surface, and patch object properties.
12-9
12
Lighting as a Visualization Tool
Selecting a Lighting Method
When you add lights to an axes, MATLAB determines the effects these
lights have on the patch and surface objects that are displayed in that
axes. There are different methods used to calculate the face and edge
coloring of lit objects, and the one you select depends on the results you
want to obtain.
Face and Edge Lighting Methods
MATLAB supports three different algorithms for lighting calculations,
selected by setting the FaceLighting and EdgeLighting properties of
each patch and surface object in the scene. Each algorithm produces
somewhat different results:
• Flat lighting produces uniform color across each of the faces of the
object. Select this method to view faceted objects.
• Gouraud lighting calculates the colors at the vertices and then
interpolates colors across the faces. Select this method to view curved
surfaces.
• Phong lighting interpolates the vertex normals across each face and
calculates 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.
This illustration shows how a red sphere looks using each of the lighting
methods with one white light source.
none
12-10
flat
gouraud
phong
Selecting a Lighting Method
The lighting command (as opposed to the light function) provides a
convenient way to set the lighting method.
12-11
12
Lighting as a Visualization Tool
Reflectance Characteristics of Graphics Objects
You can modify the reflectance characteristics of patch and surface
objects and thereby change the way they look when lights are applied to
the scene. The characteristics discussed in this section include:
• Specular and diffuse reflection
• Ambient light
• Specular exponent
• Specular color reflectance
• Backface lighting
It is likely you will adjust these characteristics in combination to produce
particular results.
Also see the material command for a convenient way to produce certain
lighting effects.
Specular and Diffuse Reflection
You can control the amount of specular and diffuse reflection from the
surface of an object by setting the SpecularStrength and
DiffuseStrength properties. This picture illustrates various settings.
12-12
Reflectance Characteristics of Graphics Objects
DiffuseStrength
1.0
0.5
0.0
0.0
1.0
2.0
SpecularStrength
Ambient Light
Ambient light is a directionless light that shines uniformly on all objects
in the scene. Ambient light is visible only when there are light objects in
the axes. There are two properties that control ambient light –
AmbientLightColor is an axes property that sets the color, and
AmbientStrength is a property of patch and surface objects that
determines the intensity of the ambient light on the particular object.
This illustration shows three different ambient light colors at various
intensities. The sphere is red and there is a white light object present.
12-13
Lighting as a Visualization Tool
AmbientLightColor(RGB)
12
[1 1 1]
[.5 0 1]
[0 1 0]
0.0
0.7
1.0
AmbientStrength
The green [0 1 0] ambient light does not affect the scene because there is
no red component in green light. However, the color defined by the RGB
values [.5 0 1] does have a red component, so it contributes to the light on
the sphere (but less than the white [1 1 1] ambient light).
Specular Exponent
The size of the specular highlight spot depends on the value of the patch
and surface object’s SpecularExponent property. Typical values for this
property range from 1 to 500, with normal objects having values in the
range 5 to 20.
This illustration shows a red sphere illuminated by a white light with
three different values for the SpecularExponent property.
12-14
Reflectance Characteristics of Graphics Objects
15
5
1
SpecularExponent
Specular Color Reflectance
The color of the specularly reflected light can range from a combination
of the color of the object and the color of the light source to the color of the
light source only. The patch and surface SpecularColorReflectance
property controls this color. This illustration shows a red sphere
illuminated by a white light. The values of the
SpecularColorReflectance property range from 0 (object and light
color) to 1 (light color).
0
0.5
1.0
SpecularColorReflectance
Back Face Lighting
Back face lighting is useful for showing the difference between internal
and external faces. These pictures of cut-away cylindrical surfaces
illustrate the effects of back face lighting.
12-15
12
Lighting as a Visualization Tool
BackFaceLighting = reverselit
BackFaceLighting = unlit
The default value for BackFaceLighting is reverselit. This setting
reverses the direction of the vertex normals that face away from the
camera, causing the interior surface to reflect light towards the camera.
Setting BackFaceLighting to unlit disables lighting on faces with
normals that point away from the camera.
You can also use BackFaceLighting to remove edge effects for closed
objects. These effects occur when BackFaceLighting is set to reverselit
and pixels along the edge of a closed object are lit as if their vertex
normals faced the camera. This produces an improperly lit pixel because
the pixel is visible but is really facing away from the camera.
To illustrate this effect, the next picture shows a blowup of the edge of a
lit sphere. Setting BackFaceLighting to lit prevents the improper
lighting of pixels.
12-16
Reflectance Characteristics of Graphics Objects
BackFaceLighting = reverselit
BackFaceLighting = lit
12-17
12
Lighting as a Visualization Tool
Positioning Lights in Data Space
This example creates a sphere and a cube to illustrate the effects of
various properties on lighting. The variables vert and fac define the
cube using the patch function.
vert =
1
1
2
2
1
1
2
2
fac =
1
2
2
1
1
2
2
1
1
1
1
1
2
2
2
2
1
2
4
1
1
5
2
6
3
5
2
6
3
7
7
8
6
7
4
3
8
4
5
8
sphere(36);
h = findobj('Type','surface');
set(h,'FaceLighting','phong',...
'FaceColor','interp',...
'EdgeColor',[.4 .4 .4],...
'BackFaceLighting','lit')
hold on
patch('faces',fac,'vertices',vert,'FaceColor','y');
light('Position',[1 3 2]);
light('Position',[−3 −1 3]);
material shiny
axis vis3d off
hold off
All faces of the cube have FaceColor set to yellow. The sphere function
creates a spherical surface and the handle of this surface is obtained
using findobj to search for the object whose Type property is surface.
The light functions define two, white (the default color) light objects
located at infinity in the direction specified by the Position vectors.
These vectors are defined in axes coordinates [x, y, z].
The patch uses flat FaceLighting (the default) to enhance the visibility
of each side. The surface uses phong FaceLighting because it produces
the smoothest interpolation of lighting effects. The material shiny
12-18
Reflectance Characteristics of Graphics Objects
command affects the reflectance properties of both the cube and sphere
(although its effects are noticeable only on the sphere because of the
cube’s flat shading).
Since the sphere is closed, the BackFaceLighting property is changed
from its default setting, which reverses the direction of vertex normals
that face away from the camera, to normal lighting, which removes
undesirable edge effects.
Examining the code in the lighting and material M-files can help you
understand how various properties affect lighting.
12-19
12
Lighting as a Visualization Tool
12-20
13
Transparency
Overview
. . . . . . . . . . . . . . . . . . . . . 13-2
Making Objects Transparent . . . . . . . . . . . . 13-3
Specifying Transparency . . . . . . . . . . . . . . . 13-4
Specifying a Single Transparency Value for an Object . 13-6
Example – Transparent Isosurface . . . . . . . . . . . 13-6
Mapping Data to Transparency . . . . . .
Size of the Alpha Data Array . . . . . . . . .
Mapping Alpha Data to the Alphamap . . . . .
Example: Mapping Data to Color or Transparency
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13-8
13-9
13-9
13-9
Selecting an Alphamap . . . . . . . . . . . . . . 13-11
Example: Modifying the Alphamap . . . . . . . . . . 13-13
13
Transparency
Transparency Topics
Making graphics objects semi-transparent is a useful technique in 3-D
visualization to make it possible to see an object, while at the same time, see
what information the object would obscure if it was completely opaque. You can
also use transparency as another dimension for displaying data, much the way
color is used in MATLAB.
These sections describe how to use the various transparency properties of
objects to enhance certain types of visualizations.
• Making Objects Transparent – provides an overview of the object properties
that specify transparency.
• Specifying a Single Transparency Value – describes how to specify a
transparency value that applies to all the faces of a graphics object.
• Mapping Data to Transparency – shows how to use transparency as another
dimension for visualizing data.
• Selecting an Alphamap – describes characteristics of various alphamaps and
illustrates the effects they produce.
13-2
Making Objects Transparent
Making Objects Transparent
The transparency of a graphics object determines the degree to which you can
see through the object. You can specify a continuous range of transparency
varying from completely transparent (i.e., invisible) to completely opaque (i.e.,
no transparency).
Objects that support transparency are:
• Image
• Patch
• Surface
The following picture illustrates the effect of transparency. The green
isosurface (patch object) reveals the coneplot that lies in the interior.
Note You must have OpenGL available on your system to use transparency.
MATLAB automatically uses OpenGL if it is available. See the figure
RendererMode property for more information.
13-3
13
Transparency
Specifying Transparency
Transparency values, which range from [0 1], are referred to as alpha values.
An alpha value of 0 means completely transparent (i.e., invisible); an alpha
value of 1 means completely opaque (i.e., no transparency).
MATLAB treats transparency in a way that is analogous to how it treats color
for the respective objects:
• Patches and surfaces can define a single face and edge alpha value or use flat
or interpolated transparency based on values in the figure’s alphamap.
• Images, patches, and surfaces can define alpha data that is used as indices
into the alphamap or directly as alpha values.
• Axes define alpha limits that control the mapping of object data to alpha
values.
• Figures contain alphamaps, which are m-by-1 arrays of alpha values.
See the following sections for more information on color:
• “Specifying Patch Coloring” in the “Creating 3-D Models with Patches”
chapter.
• “Coloring Mesh and Surface Plots” in the “Creating 3-D Graphs” chapter.
Transparency Properties
The following table summarizes the object properties that control
transparency.
13-4
Properties
Purpose
AlphaData
The transparency data for image and
surface objects
AlphaDataMapping
The transparency data mapping method
FaceAlpha
Transparency of the faces (patch and
surface only)
EdgeAlpha
Transparency of the edges (patch and
surface only)
Making Objects Transparent
Properties
Purpose
FaceVertexAlphaData
Patch only alpha data property
ALim
Alpha axis limits
ALimMode
Alpha axis limits mode
Alphamap
Figure alphamap
Transparency Functions
There are three functions that simplify the process of setting alpha properties.
Function
Purpose
alpha
Set or query transparency properties for
objects in current axes
alphamap
Specify the figure alphamap
alim
Set or query the axes alpha limits
13-5
13
Transparency
Specifying a Single Transparency Value
Specifying a single transparency value for graphics objects is useful when you
want to reveal structure that is obscured with opaque objects. For patches and
surfaces, use the FaceAlpha and EdgeAlpha properties to specify the
transparency of faces and edges. The following example illustrates this.
Example – Transparent Isosurface
This example uses the flow function to generate data for the speed profile of a
submerged jet within a infinite tank. One way to visualize this data is by
creating an isosurface illustrating where the rate of flow is equal to a specified
value.
[x y z v] = flow;
p = patch(isosurface(x,y,z,v,-3));
isonormals(x,y,z,v,p);
set(p,'facecolor','red','edgecolor','none');
daspect([1 1 1]);
view(3); axis tight; grid on;
camlight; lighting gouraud;
13-6
Specifying a Single Transparency Value
Adding transparency to the isosurface reveals that there is greater complexity
in the fluid flow than is visible using the opaque surface. The statement
alpha(.5)
sets the FaceAlpha value for the isosurface face to .5.
Setting a Single Transparency Value for Images
For images, the statement
alpha(.5)
sets the AlphaData to .5. When the AlphaDataMapping property is set to none
(the default), setting AlphaData on an image causes the entire image to render
with the specified alpha value.
13-7
13
Transparency
Mapping Data to Transparency
Alpha data is analogous to color data (e.g., the CData property of surfaces).
When you create a surface, MATLAB maps each element in the color data
array to a color in the colormap. Similarly, each element in the alpha data
maps to a transparency value in the alphamap.
Specify surface and image alpha data with the AlphaData property. For patch
objects, use the FaceVertexAlphaData property.
You can control how MATLAB interprets alpha data with the following
properties:
• FaceAlpha and EdgeAlpha – enable you to select flat or interpolated
transparency rendering. If set to a single transparency value, MATLAB
applies this value to all faces or edges and does not use the alpha data.
• AlphaDataMapping and ALim – determine how MATLAB maps the alpha data
to the alphamap. By default, MATLAB scales the alpha data to be within the
range [0 1].
• Alphamap – contains the actual transparency values to which the data is to
be mapped.
Note that there are differences between the default values of equivalent color
and alpha properties because, in contrast to color, transparency is not
displayed by default. The following table highlights these differences.
Color Property
Default
Alpha Property
Default
FaceColor
flat
FaceAlpha
1 (opaque)
CData
equal to ZData
AlphaData and
FaceVertexAlphaData
1 (scalar)
By default, objects have single-valued alpha data. Therefore you cannot specify
flat or interp FaceAlpha or EdgeAlpha without first setting AlphaData to an
array of the appropriate size.
The sections that follow illustrate how to use these properties to display object
data as degrees of transparency.
13-8
Mapping Data to Transparency
Size of the Alpha Data Array
In order to use nonscalar alpha data, you need to specify the alpha data as an
array equal in size to the:
• CData of images and surfaces
• The number of faces (flat) or the number of vertices (interpolated) defined in
the FaceVertexAlphaData property of patches
Once you have specified an alpha data array of the proper size, you can select
the face and edge rendering you want to use. Flat uses one transparency value
per face, while interpolated performs bilinear interpolation of the values at
each vertex.
Mapping Alpha Data to the Alphamap
You can control how MATLAB maps the alpha data to the alphamap using the
AlphaDataMapping property. There are three possible mappings:
• none – Interpret the values in alpha data as transparency values (data
values must be between 0 and 1, or will be clamped to 0 or 1). This is the
default mapping.
• scaled – Transform the alpha data to span the portion of the alphamap
indicated by the axes ALim property, linearly mapping data values to alpha
values. This is the same way color data is mapped to the colormap.
• direct – Use the alpha data directly as indices into the figure alphamap.
By default, objects have scalar alpha data (AlphaData and
FaceVertexAlphaData) set to the value 1.
Example: Mapping Data to Color or Transparency
This example displays a surface plot of a functions of two variables. The color
is mapped to the gradient of the z data.
[x,y] = meshgrid([-2:.2:2]);
z = x.*exp(-x.^2-y.^2);
surf(x,y,z,gradient(z)); axis tight
13-9
13
Transparency
You can map transparency to the gradient of z in a similar way.
surf(x,y,z,'FaceAlpha','flat',...
'AlphaDataMapping','scaled',...
'AlphaData',gradient(z),...
'FaceColor','blue');
axis tight
13-10
Selecting an Alphamap
Selecting an Alphamap
An alphamap is simply an array of values ranging from 0 to 1. The size of the
array can be either m-by-1 or 1-by-m.
The default alphamap contains 64 values ranging linearly from 0 to 1, as you
can see in the following plot.
plot(get(gcf,'Alphamap'))
Default Alphamap
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
0
10
20
30
40
50
60
70
This alphamap displays the lowest alpha data values as completely
transparent and the highest alpha data values as opaque.
The alphamap function creates some useful predefined alphamaps and also
enables you to modify existing maps. For example,
plot(alphamap('vup'))
produces the following alphamap.
13-11
13
Transparency
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
0
10
20
30
40
50
60
70
You can shift the values using the increase or decrease options. For example,
alphamap('increase',.4)
adds the value .4 to all values in the current figure’s alphamap. Replotting the
'vup' alphamap illustrates the change. Note how the values are clamped to the
range [0 1].
plot(get(gcf,'Alphamap'))
13-12
Selecting an Alphamap
1
0.9
0.8
0.7
0.6
0.5
0.4
0
10
20
30
40
50
60
70
Example: Modifying the Alphamap
This example uses slice planes to examine volume data. The slice planes use
the color data for alpha data and employ a rampdown alphamap (the values
range from 1 to 0):
1 Create the volume data by evaluating a function of three variables.
[x,y,z] = meshgrid(-1.25:.1:-.25,-2:.2:2,-2:.1:2);
v = x.*exp(-x.^2-y.^2-z.^2);
2 Create the slice planes, set the alpha data equal to the color data, and
specify interpolated FaceAlpha.
h = slice(x,y,z,v,[-1 -.75 -.5],[],[0]);
alpha('color')
set(h,'EdgeColor','none','FaceColor','interp',...
'FaceAlpha','interp')
3 Install the rampdown alphamap and increase each value in the alphamap
by .1 to achieve the desired degree of transparency. Specify the hsv
colormap.
alphamap('rampdown')
alphamap('increase',.1)
13-13
13
Transparency
colormap(hsv)
This alphamap causes the smallest values of the function (around zero) to
display with the least transparency and the greatest values to display with the
most transparency. This enables you to see through the slice planes, while at
the same time preserving the data around zero.
13-14
14
Creating 3-D Models with
Patches
Introduction to Patch Objects
Defining Patches . . . . . . .
Behavior of the patch Function .
Creating a Single Polygon . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 14-2
. 14-2
. 14-2
. 14-4
Multi-Faceted Patches . . . . . . . . . . . . . . . 14-6
Example – Defining a Cube . . . . . . . . . . . . . . 14-6
Specifying Patch Coloring
. . . . . . . . . . . . 14-11
Face and Edge Coloring . . . . . . . . . . . . . . 14-13
Example – Specifying Flat Edge and Face Coloring . . . . 14-13
Coloring Edges with Shared Vertices . . . . . . . . . 14-14
How MATLAB Interprets Patch Color Data
Indexed Color Data . . . . . . . . . . . .
Truecolor Patches . . . . . . . . . . . .
Interpolating in Indexed Color vs. Truecolor .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
14-16
14-16
14-19
14-19
14
Creating 3-D Models with Patches
Introduction to Patch Objects
A patch graphics object is composed of one or more polygons that may or may
not be connected. Patches are useful for modeling real-world objects such as
airplanes or automobiles, and for drawing 2- or 3-D polygons of arbitrary
shape. In contrast, surface objects are rectangular grids of quadrilaterals and
are better suited for displaying planar topographies such as the values of some
mathematical functions, the contours of data in a rectangular plane, or
parameterized surfaces such as a sphere.
A number of MATLAB functions create patch objects – fill, fill3,
isosurface, isocaps, some of the contour functions, and patch. This section
concentrates on use of the patch function.
Defining Patches
You define a patch by specifying the coordinates of its vertices and some form
of color data. Patches support a variety of coloring options that are useful for
visualizing data superimposed on geometric shapes.
There are two ways to specify a patch:
• By specifying the coordinates of the vertices of each polygon, which MATLAB
connects to form the patch
• By specifying the coordinates of each unique vertex and a matrix that
specifies how to connect these vertices to form the faces
The second technique is preferred for multifaceted patches because it generally
requires less data to define the patch; vertices shared by more than one face
need be defined only once. This topic area provides examples of both
techniques.
Behavior of the patch Function
There are two forms of the patch function – high-level syntax and low-level
syntax. The behavior of the patch function differs somewhat depending on
which syntax you use.
High-Level Syntax
When you use the high-level syntax, MATLAB automatically determines how
to color each face based on the color data you specify. The high-level syntax
14-2
Introduction to Patch Objects
enables you to omit the property names for the x-, y-, and z-coordinates and the
color data, as long as you specify these arguments in the correct order.
patch(x-coordinates,y-coordinates,z-coordinates,colordata)
However, you must specify color data so MATLAB can determine what type of
coloring to use. If you do not specify color data, MATLAB returns an error.
patch(sin(t),cos(t))
??? Error using ==> patch
Not enough input arguments.
Low-Level Syntax
The low-level syntax accepts only property name/property value pairs as
arguments and does not automatically color the faces unless you also change
the value of the FaceColor property. For example, the statement
patch('XData',sin(t),'YData',cos(t)) % Low-level syntax
draws a patch with white face color because the factory default value for the
FaceColor property is the color white.
get(0,'FactoryPatchFaceColor')
ans =
1
1
1
See the list of patch properties in the MATLAB Function Reference and the get
command for information on how to obtain the factory and user default values
for properties.
Interpreting the Color Argument
When you use the informal syntax, MATLAB interprets the third (or fourth if
there are z-coordinates) argument as color data. If you intend to define a patch
with x-, y-, and z-coordinates, but leave out the color, MATLAB interprets the
z-coordinates as color data, and then draws a 2-D patch. For example,
h = patch(sin(t),cos(t),1:length(t))
draws a patch with all vertices at z = 0, colored by interpolating the vertex
colors (since there is one color for each vertex), whereas
h = patch(sin(t),cos(t),1:length(t),'y')
14-3
14
Creating 3-D Models with Patches
draws a patch with vertices at increasing values of z, colored yellow.
The “Specifying Patch Coloring” section in this chapter provides more
information on options for coloring patches.
Creating a Single Polygon
A polygon is simply a patch with one face. To create a polygon, specify the
coordinates of the vertices and color data with a statement of the form.
patch(x-coordinates,y-coordinates,[z-coordinates],colordata)
For example, these statements display a 10-sided polygon with a yellow face
enclosed by a black edge. The axis equal command produces a correctly
proportioned polygon.
t = 0:pi/5:2*pi;
patch(sin(t),cos(t),'y')
axis equal
1
0.5
0
−0.5
−1
−1
−0.5
0
0.5
1
The first and last vertices need not coincide; MATLAB automatically closes
each polygonal face of the patch. In fact, it is generally better to define each
vertex only once, particularly if you are using interpolated face coloring.
14-4
Introduction to Patch Objects
Interpolated Face Colors
You can control many aspects of the patch coloring. For example, instead of
specifying a single color, you can provide a range of numerical values that map
the color at each vertex to a color in the figure colormap.
a = t(1:length(t)−1); %remove redundant vertex definition
patch(sin(a),cos(a),1:length(a),'FaceColor','interp')
colormap cool;
axis equal
MATLAB now interpolates the colors across the face of the patch. You can color
the edges of the patch the same way, by setting the edge colors to be
interpolated. The command is
patch(sin(t),cos(t),1:length(t),'EdgeColor','interp')
The “Specifying Patch Coloring” section in this chapter provides more
information on options for coloring patches.
14-5
14
Creating 3-D Models with Patches
Multi-Faceted Patches
If you specify the x-, y-, and z-coordinate arguments as vectors, MATLAB draws
a single polygon by connecting the points. If the arguments are matrices,
MATLAB draws one polygon per column, producing a single patch with
multiple faces. These faces need not be connected and can be self-intersecting.
Alternatively, you can specify the coordinates of each unique vertex and the
order in which to connect them to form the faces. The examples in this section
illustrate both techniques.
Example – Defining a Cube
A cube is defined by eight vertices that form six sides. This illustration shows
the coordinates of the vertices defining a cube in which the sides are one unit
in length.
1, 1, 1
0, 1, 1
1, 0, 1
0, 0, 1
Face 1
z
1, 1, 0
0, 1, 0
1, 0, 0
y
0, 0, 0
x
Specifying X, Y, and Z Coordinates
Each of the six faces has four vertices. Since you do not need to close each
polygon (i.e., the first and last vertices do not need to be the same), you can
define this cube using a 4-by-6 matrix for each of the x-, y-, and z-coordinates.
14-6
Multi-Faceted Patches
x-coordinates
y-coordinates
z-coordinates
0
1
1
0
0
0
0
0
1
1
0
0
0
0
0
0
0
1
1
1
0
0
1
1
0
1
1
0
0
0
0
0
0
0
0
1
1
1
0
0
1
1
0
1
1
0
1
1
1
1
1
1
0
1
0
1
1
0
0
0
0
0
1
1
1
1
1
1
1
1
0
1
Face 1
Each column of the matrices specifies a different face. Note that while there are
only eight vertices, you must specify 24 vertices to define all six faces. Since
each face shares vertices with four other faces, you can define the patch more
efficiently by defining each vertex only once and then specifying the order in
which to connect these vertices to form each face. The patch Vertices and
Faces properties define patches in just this way.
Specifying Faces and Vertices
These matrices specify the cube using Vertices and Faces.
Vertices
Faces
x
y
z
1st vertex
0
0
0
1
2
6
5
2nd vertex
.
.
.
1
0
0
2
3
7
6
1
1
0
3
4
8
7
0
1
0
4
1
5
8
5th vertex
0
0
1
1
2
3
4
6th vertex
1
0
1
5
6
7
8
1
1
1
This data draws the first face by
connecting vertices 1, 2 ,6, and 5
in that order.
14-7
14
Creating 3-D Models with Patches
Using the vertices/faces technique can save a considerable amount of computer
memory when patches contain a large number of faces. This technique requires
the formal patch function syntax, which entails assigning values to the
Vertices and Faces properties explicitly. For example,
patch('Vertices',vertex_matrix,'Faces',faces_matrix)
Since the formal syntax does not automatically assign face or edge colors, you
must set the appropriate properties to produce patches with colors other than
the default white face color and black edge color.
Flat Face Color
Flat face color is the result of specifying one color per face. For example, using
the vertices/faces technique and the FaceVertexCData property to define color,
this statement specifies one color per face and sets the FaceColor property to
flat.
patch('Vertices',vertex_matrix,'Faces',faces_matrix,...
'FaceVertexCData',hsv(6),'FaceColor','flat')
Since true color specified with the FaceVertexCData property has the same
format as a MATLAB colormap (i.e., an n-by-3 array of RGB values), this
example uses the hsv colormap to generate the six colors required for flat
shading.
14-8
Multi-Faceted Patches
Interpolated Face Color
Interpolated face color means the vertex colors of each face define a transition
of color from one vertex to the next. To interpolate the colors between vertices,
you must specify a color for each vertex and set the FaceColor property to
interp.
patch('Vertices',vertex_matrix,'Faces',faces_matrix,...
'FaceVertexCData',hsv(8),'FaceColor','interp')
Changing to the standard 3-D view and making the axis square,
view(3); axis square
produces a cube with each face colored by interpolating the vertex colors.
To specify the same coloring using the x, y, z, c technique, c must be an
m-by-n-by-3 array, where the dimensions of x, y, and z are m-by-n.
This diagram shows the correspondence between the FaceVertexCData and
CData properties.
14-9
14
Creating 3-D Models with Patches
FaceVertexCData =
CData(:,:,1) =
1.00 0.00 0.00
1.00 1.00 0.50 0.00 1.00 0.00
1.00 0.75 0.00
1.00 0.50 0.00 1.00 1.00 0.00
0.50 1.00 0.00
0.00 0.50 1.00 0.00 0.50 0.50
0.00 1.00 0.25
0.00 0.00 0.50 1.00 0.00 1.00
0.00 1.00 1.00
CData(:,:,2) =
0.00 0.25 1.00
0.00 0.75 1.00 1.00 0.00 1.00
0.50 0.00 1.00
0.75 1.00 1.00 0.00 0.75 0.25
1.00 0.00 0.75
0.25 0.00 0.00 1.00 1.00 0.00
Red Green Blue
1.00 0.25 0.00 0.00 1.00 0.00
CData(:,:,3) =
Red page
Green page
Blue page
0.00 0.00 0.00 0.25 0.00 1.00
0.00 0.00 0.25 0.00 0.00 1.00
1.00 1.00 0.75 1.00 0.00 1.00
1.00 1.00 1.00 0.75 0.25 0.75
See “Specifying Patch Coloring” in this chapter for a discussion of coloring
techniques in more detail.
14-10
Specifying Patch Coloring
Specifying Patch Coloring
Patch objects employ a coloring scheme that is basically different from that
used by surface objects in that patches do not automatically generate color data
based on the value of the z-coordinate at each vertex. You must explicitly
specify patch coloring, or MATLAB uses the default white face color and black
edge color.
Patch coloring methods provide a means to display pictures of real-world
objects with information superimposed on them through the use of color. For
example a picture of an airplane wing can be colored to indicate the air
pressure across its surface.
This table summarizes the patch properties that control color (exclusive of
those used when light sources are present). See the patch property descriptions
in the online MATLAB Function Reference for a complete list of properties.
Property
Purpose
CData
Specify single, per face, or per vertex colors in
conjunction with x, y, and z data
CDataMapping
Specifies whether color data is scaled or used
directly as indices into the figure colormap
FaceVertexCData
Specify single, per face, or per vertex colors in
conjunction with faces and vertices data
EdgeColor
Specifies whether edges are invisible, a single
color, a flat color determined by vertex colors,
or interpolated colors determined by vertex
colors
FaceColor
Specifies whether faces are invisible, a single
color, a flat color determined by vertex colors,
or interpolated colors determined by vertex
colors
MarkerEdgeColor
Specifies the color of the marker, or the edge
color for filled markers
14-11
14
Creating 3-D Models with Patches
14-12
Property
Purpose
MarkerFaceColor
Specifies the fill color for markers that are
closed shapes
Face and Edge Coloring
Face and Edge Coloring
You can specify patch face coloring by defining:
• A single color for all faces
• One color for each face, which is used for flat coloring
• One color for each vertex, which is used for interpolated coloring
Specify the face color using either the CData property, if you are using x-, y-,
and z-coordinates or the FaceVertexCData property, if you are specifying
vertices and faces.
Each patch face has a bounding edge, which you can color as:
• A single color for all edges
• A flat color defined by the color of the vertex that precedes the edge
• Interpolated colors determined by the two vertices that bound the edge
Note that patch edge colors can be flat or interpolated only when you specify a
color for each vertex. For flat edge coloring, MATLAB uses the color of the
vertex preceding the edge to determine the color of the edge. The order in which
you specify the vertices establishes which vertex colors a particular edge.
Example – Specifying Flat Edge and Face Coloring
These statements create a square patch.
v = [0 0 0;1 0 0;1 1 0;0 1 0];
f = [1 2 3 4];
fvc = [1 0 0;0 1 0;1 0 1;1 1 0];
patch('Vertices',v,'Faces',f,'FaceVertexCData',fvc,...
'FaceColor','flat','EdgeColor','flat',...
'Marker','o','MarkerFaceColor','flat')
14-13
14
Creating 3-D Models with Patches
Yellow
Red
Magenta
Green
The Faces property value, [1 2 3 4], determines the order in which MATLAB
connects the vertices. In this case, the order is red, green, magenta, and yellow.
If you change this order, the results can be quite different. For example,
specifying the Faces property as,
f = [4 3 2 1];
changes the order to yellow, magenta, green, and red. Note that changing the
order not only changes the color of the edges, but also the color of the face,
which is the color of the first vertex specified.
Yellow
Red
Magenta
Green
Coloring Edges with Shared Vertices
Each patch face is bound by edges, which are line segments that connect the
vertices. When patches have multiple faces that share vertices, some of the
14-14
Face and Edge Coloring
edges may overlap. In such cases, the edges of the most recently drawn face
overlay previously drawn edges.
For example, this illustration shows a patch with four faces and flat colored
edges (FaceColor set to none, EdgeColor set to flat).
Red
Green
Blue
[1 0 0]
[0 1 0]
[0 0 1]
3
Magenta
4 3rd
[1 0 1]
Yellow
[1 1 0]
4
2
4
3
4th
1
1
3
3
1st
2
4 2nd
1
2
Cyan
[0 1 1]
2
1
Red
Green
Blue
[1 0 0]
[0 1 0]
[0 0 1]
The arrows indicate the order in which each edge is drawn in the first, second,
third, and fourth face. The color at each vertex determines the color of the edge
that follows it. Notice how the second edge in the first face would be green
except that the second face drew its fourth edge from the magenta vertex. You
can see similar effects in all shared edges.
For EdgeColor set to interp, MATLAB interpolates colors between adjacent
vertices. In this case, the order in which you specify the vertices does not affect
the edge color.
14-15
14
Creating 3-D Models with Patches
How MATLAB Interprets Patch Color Data
MATLAB interprets the color data in one of two ways:
• Indexed color data – numerical values that are mapped to colors defined in
the figure colormap
• Truecolor data – RGB triples that define colors explicitly and do not make
use of the figure colormap
The dimensions of the color data (CData or FaceVertexCData) determine how
MATLAB interprets it. If you specify only one numeric value per patch, per
face, or per vertex, then MATLAB interprets the data as indexed. If there are
three numeric values per patch, face, or vertex, then MATLAB interprets the
data as RGB values.
Indexed Color Data
MATLAB interprets indexed color data as either values to scale before
mapping to the colormap, or directly as indices into the colormap. You control
the interpretation by setting the CDataMapping property. The default is to scale
the data.
Scaled Color
By default, MATLAB scales the color data so that the minimum value maps to
the first color in the colormap, the maximum value maps to the last color in the
colormap, and values in between are linearly transformed to span the
colormap. This enables you to use colormaps of different sizes without changing
your data and to use data in any range of values without changing the
colormap.
For example, the following patch has eight triangular faces with a total of 24
(nonunique) vertices. The color data are integers that range from one to 24, but
could be any values.
The variable c contains the color data. It is a 3-by-8 matrix, with each column
specifying the colors for the three vertices of each face.
c =
1
2
3
14-16
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
How MATLAB Interprets Patch Color Data
The color bar (colorbar) on the right side of the patch illustrates the colormap
used and indicates with the vertical axis which color is mapped to the
respective data value.
2
24
1.8
22
20
1.6
CDataMapping = scaled
18
1.4
16
1.2
14
1
12
0.8
10
0.6
8
6
0.4
4
0.2
2
0
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
1.8
2
You can alter the mapping of color data to colormap entry using the caxis
command. This command uses a two-element vector [cmin cmax] to specify
what data values map to the beginning and end of the colormap, thereby
shifting the color mapping.
By default, MATLAB sets cmin to the minimum value and cmax to the
maximum value of the color data of all graphics objects within the axes.
However, you can set these limits to span any range of values and thereby shift
the color mapping. See “Calculating Color Limits” in the “Axes Properties”
chapter for more information.
The color data does not need to be a sequential list of integers; it can be any
matrix with dimensions matching the coordinate data. For example,
patch(x,y,z,rand(size(z)))
14-17
14
Creating 3-D Models with Patches
Direct Color
If you set the patch CDataMapping property to off,
set(patch_handle,'CDataMapping','off')
MATLAB interprets each color data value as a direct index into the colormap.
That is, a value of 1 maps to the first color, a value of 2 maps to the second color,
and so on.
The patch from the previous example would then use only the first 24 colors in
the colormap.
2
60
1.8
1.6
50
CDataMapping = direct
1.4
40
1.2
1
30
0.8
0.6
20
0.4
10
0.2
0
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
1.8
2
This example uses integer color data. However, if the values are not integers,
MATLAB converts them according to these rules:
• If value is < 1, it maps to the first color in the colormap.
• If value is not an integer, it is rounded to the nearest integer towards zero.
• If value > length(colormap), it maps to the last color in the colormap.
Unscaled color data is more commonly used for images where there is typically
a colormap associated with a particular image.
14-18
How MATLAB Interprets Patch Color Data
Truecolor Patches
Truecolor is a means to specify a color explicitly with RGB values rather than
pointing to an entry in the figure colormap. Truecolor generally provides a
greater range of colors than can be defined in a colormap.
Using truecolor eliminates the mapping of data to colormap entries. On the
other hand, you cannot change the coloring of the patch without redefining the
color data (as opposed to just changing the colormap).
You can use truecolor on computers that do not have true color (24-bit)
displays. In this case, MATLAB uses a special colormap designed to produce
results that are as close as possible with the limited number of colors available.
Properties control how MATLAB uses color on pseudocolor machines.
Interpolating in Indexed Color Versus Truecolor
When you specify interpolated face coloring, MATLAB determines the color of
each face by interpolating the vertex colors. The method of interpolation
depends on whether you specified truecolor data or indexed color data.
With truecolor data, MATLAB interpolates the numeric RGB values defined
for the vertices. This generally produces a smooth variation of color across the
face. In contrast, indexed color interpolation uses only colors that are defined
in the colormap. With certain colormaps, the results can be quite different.
To illustrate this difference, these two patches are defined with the same
vertex colors. Circular markers indicate the yellow, red, and blue vertex colors.
14-19
14
Creating 3-D Models with Patches
Indexed Color Data
001
True Color Data
100
110
The patch on the left uses indexed colors obtained from the six-element
colormap shown next to it. The color data maps the vertex colors to the
colormap elements indicated in the picture. With this colormap, interpolating
from the cyan vertex to the blue vertex can include only the colors green, red,
yellow, and magenta, hence the banding.
Interpolation in RGB space makes no use of the colormap. It is simply the
gradual transition from one numeric value to another. For example,
interpolating from the cyan vertex to the blue vertex follows a progression
similar to these values.
0 1 1, 0 0.9 1, 0 0.8 1, ... 0 0.2 1, 0 0.1 1, 0 0 1
In reality each pixel would be a different color so the incremental change would
be much smaller than illustrated here.
14-20
15
Volume Visualization
Techniques
Volume Visualization Topics
. . . . . . . . . . . . 15-2
Overview of Volume Visualization . . . . . . . . . . 15-3
Volume Visualization Functions . . . . . . . . . . . 15-5
Visualizing Scalar Volume Data . . . . . . . . . . . 15-7
Visualizing MRI Data . . . . . . . . . . . . . . . . 15-8
Exploring Volumes with Slice Planes . . . . . . . . 15-14
Connecting Equal Values with Isosurfaces . . . . . 15-19
Isocaps Add Context to Visualizations . . . . . . . 15-21
Visualizing Vector Volume Data . . . . . . . . . . 15-25
Stream Line Plots of Vector Data
. . . . . . . . . 15-30
Displaying Curl with Stream Ribbons
. . . . . . . 15-32
Displaying Divergence with Stream Tubes . . . . . 15-34
Creating Stream Particle Animations
Vector Field Displayed with Cone Plots
. . . . . . . 15-37
. . . . . . 15-40
15
Volume Visualization Techniques
Volume Visualization Topics
This page presents a quick overview of the volume visualization topics
discussed in this section.
• Overview of Volume Visualization – discusses the types of volume data you
can visualize with MATLAB and introduces the techniques available.
• Volume Visualization Functions – provides a list of the functions used for
volume visualization.
• Visualizing Scalar Volume Data – summarizes the techniques available for
visualizing scalar volume data.
• Visualizing MRI Data – shows ways to visualize MRI data using 2- and 3-D
contour slices, isosurfaces, isocaps, and lighting.
• Exploring Volumes with Slice Planes – illustrates the use of slice planes with
scalar volume data.
• Connecting Equal Values with Isosurfaces – shows the use of isosurfaces to
illustrate fluid data.
• Isocaps. Add Context to Visualizations – demonstrates the use of isocaps to
improve the clarity of isosurface plots.
• Visualizing Vector Volume Data – summarizes the techniques available for
visualizing vector volume data, including using scalar techniques,
determining starting points for stream plots, and plotting subregions of
volumes.
• Stream Line Plots of Vector Data – demonstrates the use of stream lines,
slice planes, and contours lines used in conjunction.
• Displaying Curl with Stream Ribbons – illustrates the use of stream ribbon
plots to display the curl of a vector field.
• Displaying Divergence with Stream Tubes – illustrates the use of stream
tube plots to display the divergence of a vector field. Slice planes and contour
lines are used to enhance the visualization.
• Creating Stream Particle Animations – uses a combination of stream lines
and stream particles to create an animation showing wind currents.
• Vector Field Displayed with Cone Plots – applies a combination of cone plots,
isosurfaces, lighting, and camera placement to visualize a vector field.
15-2
Overview of Volume Visualization
Overview of Volume Visualization
Volume visualization is the creation of graphical representations of data sets
that are defined on three-dimensional grids. Volume data sets are
characterized by multidimensional arrays of scalar or vector data. These data
are typically defined on lattice structures representing values sampled in 3-D
space. There are two basic types of volume data:
• Scalar volume data contains single values for each point.
• Vector volume data contains two or three values for each point, defining the
components of a vector.
Examples of Volume Data
An example of scalar volume data is that produced by the flow M-file. The flow
data represents the speed profile of a submerged jet within an infinite tank.
Typing
[x,y,z,v] = flow;
produces four 3-D arrays. The x, y, and z arrays specify the coordinates of the
scalar values in the array v.
The wind data set is an example of vector volume data that represents air
currents over North America. You can load this data in the MATLAB
workspace with the command
load wind
This data set comprises six 3-D arrays: x, y, and z are the coordinate data for
the arrays u, v, and w, which are the vector components for each point in the
volume.
Selecting Visualization Techniques
The techniques you select to visualize volume data depend on what type of data
you have and what you want to learn. In general, scalar data is best viewed
with isosurfaces, slice planes, and contour slices. Vector data represents both
a magnitude and direction at each point, which is best displayed by stream
lines (particles, ribbons, and tubes), cone plots, and arrow plots. Most
visualizations, however, employ a combination of techniques to best reveal the
content of the data.
15-3
15
Volume Visualization Techniques
The material in these sections describe how to apply a variety of techniques to
typical volume data.
Steps to Create a Volume Visualization
Creating an effective visualization requires a number of steps to compose the
final scene. These steps fall into four basic categories:
1 Determine the characteristics of your data. Graphing volume data usually
requires knowledge of the range of both the coordinates and the data values.
2 Select an appropriate plotting routine. The information in this section helps
you select the right methods.
3 Define the view. The information conveyed by a complex three-dimensional
graph can be greatly enhanced through careful composition of the scene.
Viewing techniques include adjusting camera position, specifying aspect
ratio and project type, zooming in or out, and so on.
4 Add lighting and specify coloring. Lighting is an effective means to enhance
the visibility of surface shape and to provide a three-dimensional
perspective to volume graphs. Color can convey data values, both constant
and varying.
15-4
Volume Visualization Functions
Volume Visualization Functions
MATLAB provides functions that enable you to apply a variety of volume
visualization techniques. The following tables group these functions into two
categories based on the type of data (scalar or vector) each is designed to work
with. The reference page for each function provides examples of the intended
use.
Functions Used with Scalar Volume Data
Functions
Purpose
contourslice
Draw contours in volume slice planes
isocaps
Compute isosurface end-cap geometry
isocolors
Compute the colors of isosurface vertices
isonormals
Compute normals of isosurface vertices
isosurface
Extract isosurface data from volume data
patch
Create a patch (multipolygon) graphics object
reducepatch
Reduce the number of patch faces
reducevolume
Reduce the number of elements in a volume data set
shrinkfaces
Reduce the size of each patch face
slice
Draw slice planes in volume
smooth3
Smooth 3-D data
surf2patch
Convert surface data to patch data
subvolume
Extract subset of volume data set
15-5
15
Volume Visualization Techniques
Functions Used with Vector Volume Data
15-6
Functions
Purpose
coneplot
Plot velocity vectors as cones in 3-D vector fields
curl
Compute the curl and angular velocity of a 3-D
vector field
divergence
Compute the divergence of a 3-D vector field
interpstreamspeed
Interpolate streamline vertices from vector-field
magnitudes
streamline
Draw stream lines from 2-D or 3-D vector data
streamparticles
Draw stream particles from vector volume data
streamribbon
Draw stream ribbons from vector volume data
streamslice
Draw well-spaced stream lines from vector volume
data
streamtube
Draw stream tubes from vector volume data
stream2
Compute 2-D stream line data
stream3
Compute 3-D stream line data
volumebounds
Return coordinate and color limits for volume
(scalar and vector)
Visualizing Scalar Volume Data
Visualizing Scalar Volume Data
Typical scalar volume data is composed of a 3-D array of data and three
coordinate arrays of the same dimensions. The coordinate arrays specify the x,
y, and z coordinates for each data point.
The units of the coordinates depend on the type of data. For example, flow data
might have coordinate units of inches and data units of psi.
Techniques for Visualizing Scalar Data
MATLAB supports a number of functions that are useful for visualizing scalar
data.
• Slice planes provide a way to explore the distribution of data values within
the volume by mapping values to colors. You can orient slice planes at
arbitrary angles, as well as use nonplanar slices. (For illustrations of how to
use slice planes, see slice, a volume slicing example, and slice planes used
to show context.) You can specify the data used to color isosurfaces, enabling
you to display different information in color and surface shape (see
isocolors).
• Contour slices are contour plots drawn at specific coordinates within the
volume. Contour plots enable you to see where in a given plane the data
values are equal. See contourslice and MRI data for an example
• Isosurfaces are surfaces constructed by using points of equal value as the
vertices of patch graphics objects.
15-7
15
Volume Visualization Techniques
Visualizing MRI Data
An example of scalar data includes Magnetic Resonance Imaging (MRI) data.
This data typically contains a number of slice planes taken through a volume,
such as the human body. MATLAB includes an MRI data set that contains 27
image slices of a human head. Some useful techniques for visualizing this data
include displaying the data as:
• A series of 2-D images representing slices through the head
• 2-D and 3-D contour slices taken at arbitrary locations within the data
• An isosurface with isocaps showing a cross section of the interior
Changing the Data Format
The MRI data, D, is stored as a 128-by-128-by-1-by-27 array. The third array
dimension is used typically for the image color data. However, since these are
indexed images (a colormap, map, is also loaded) there is no information in the
third dimension, which you can remove using the squeeze command. The
result is a 128-by-128-by-27 array.
The first step is to load the data and transform the data array from 4-D to 3-D.
load mri
D = squeeze(D);
Displaying Images of MRI Data
To display one of the MRI images, use the image command, indexing into the
data array to obtain the eighth image. Then adjust axis scaling, and install the
MRI colormap, which was loaded along with the data.
image_num = 8;
image(D(:,:,image_num))
axis image
colormap(map)
15-8
Visualizing MRI Data
20
40
60
80
100
120
20
40
60
80
100
120
Save the x and y axis limits for use in the next part of the example.
x = xlim;
y = ylim;
Displaying a 2-D Contour Slice
You can treat this MRI data as a volume because it is a collection of slices taken
progressively through the 3-D object. Use contourslice to display a contour
plot of a slice of the volume. To create a contour plot with the same orientation
and size as the image created in the first part of this example, adjust the y-axis
direction (axis), set the limits (xlim, ylim), and set the data aspect ratio
(daspect).
contourslice(D,[],[],image_num)
axis ij
xlim(x)
ylim(y)
daspect([1,1,1])
colormap('default')
This contour plot uses the figure colormap to map color to contour value.
15-9
15
Volume Visualization Techniques
20
40
60
80
100
120
20
40
60
80
100
120
Displaying 3-D Contour Slices
Unlike images, which are 2-D objects, contour slices are 3-D objects that you
can display in any orientation. For example, you can display four contour slices
in a 3-D view. To improve the visibility of the contour line, increase the
LineWidth to 2 points (one point equals 1/72 of an inch).
phandles = contourslice(D,[],[],[1,12,19,27],8);
view(3); axis tight
set(phandles,'LineWidth',2)
15-10
Visualizing MRI Data
Displaying an Isosurface
You can use isosurfaces to display the overall structure of a volume. When
combined with isocaps, this technique can reveal information about data on the
interior of the isosurface.
First, smooth the data with smooth3; then use isosurface to calculate the
isodata. Use patch to display this data as a graphics object.
Ds = smooth3(D);
hiso = patch(isosurface(Ds,5),...
'FaceColor',[1,.75,.65],...
'EdgeColor','none');
Adding an Isocap to Show a Cutaway Surface
Use isocaps to calculate the data for another patch that is displayed at the
same isovalue (5) as the surface. Use the unsmoothed data (D) to show details
of the interior. You can see this as the sliced-away top of the head.
hcap = patch(isocaps(D,5),...
'FaceColor','interp',...
'EdgeColor','none');
colormap(map)
15-11
15
Volume Visualization Techniques
Defining the View
Define the view and set the aspect ratio (view, axis, daspect).
view(45,30)
axis tight
daspect([1,1,.4])
Add Lighting
Add lighting and recalculate the surface normals based on the gradient of the
volume data, which produces smoother lighting (camlight, lighting,
isonormals). Increase the AmbientStrength property of the isocap to brighten
the coloring without affecting the isosurface. Set the
SpecularColorReflectance of the isosurface to make the color of the specular
reflected light closer to the color of the isosurface; then set the
SpecularExponent to reduce the size of the specular spot.
lightangle(45,30);
set(gcf,'Renderer','zbuffer'); lighting phong
isonormals(Ds,hiso)
set(hcap,'AmbientStrength',.6)
set(hiso,'SpecularColorReflectance',0,'SpecularExponent',50)
15-12
Visualizing MRI Data
The isocap uses interpolated face coloring, which means the figure colormap
determines the coloring of the patch. This example uses the colormap supplied
with the data.
To display isocaps at other data values, try changing the isosurface value or use
the subvolume command. See the isocaps and subvolume reference pages for
examples.
15-13
15
Volume Visualization Techniques
Exploring Volumes with Slice Planes
A slice plane (which does not have to be planar) is a surface that takes on
coloring based on the values of the volume data in the region where the slice is
positioned. Slice planes are useful for probing volume data sets to discover
where interesting regions exist, which you can then visualize with other types
of graphs (see the slice example). Slice planes are also useful for adding a
visual context to the bound of the volume when other graphing methods are
also used (see coneplot and the “Streamline Plots of Vector Data” section in
this chapter for examples).
Use the slice command to create slice planes.
Example – Slicing Fluid Flow Data
This example slices through a volume generated by the flow M-file.
1. Investigate the Data
Generate the volume data with the command
[x,y,z,v] = flow;
Determine the range of the volume by finding the minimum and maximum of
the coordinate data.
xmin = min(x(:));
ymin = min(y(:));
zmin = min(z(:));
xmax = max(x(:));
ymax = max(y(:));
zmax = max(z(:));
2. Create a Slice Plane at an Angle to the X-Axes
To create a slice plane that does not lie in an axes plane, first define a surface
and rotate it to the desired orientation. This example uses a surface that has
the same x and y coordinates as the volume.
hslice = surf(linspace(xmin,xmax,100),...
linspace(ymin,ymax,100),...
zeros(100));
15-14
Exploring Volumes with Slice Planes
Rotate the surface by -45 degrees about the x axis and save the surface XData,
YData, and ZData to define the slice plane; then delete the surface.
rotate(hslice,[-1,0,0],-45)
xd = get(hslice,'XData');
yd = get(hslice,'YData');
zd = get(hslice,'ZData');
delete(hslice)
3. Draw the Slice Planes
Draw the rotated slice plane, setting the FaceColor to interp so that it is
colored by the figure colormap and set the EdgeColor to none. Increase the
DiffuseStrength to .8 to make this plane shine more brightly after adding a
light source.
h = slice(x,y,z,v,xd,yd,zd);
set(h,'FaceColor','interp',...
'EdgeColor','none',...
'DiffuseStrength',.8)
Set hold to on and add three more orthogonal slice planes at xmax, ymax, and
zmin to provide a context for the first plane, which slices through the volume at
an angle.
hold on
hx = slice(x,y,z,v,xmax,[],[]);
set(hx,'FaceColor','interp','EdgeColor','none')
hy = slice(x,y,z,v,[],ymax,[]);
set(hy,'FaceColor','interp','EdgeColor','none')
hz = slice(x,y,z,v,[],[],zmin);
set(hz,'FaceColor','interp','EdgeColor','none')
4. Define the View
To display the volume in correct proportions, set the data aspect ratio to
[1,1,1] (daspect). Adjust the axis to fit tightly around the volume (axis) and
turn on the box to provide a sense of a 3-D object. The orientation of the axes
can be selected initially using rotate3d to determine the best view.
15-15
15
Volume Visualization Techniques
Zooming in on the scene provides a larger view of the volume (camzoom).
Selecting a projection type of perspective gives the rectangular solid more
natural proportions than the default orthographic projection (camproj).
daspect([1,1,1])
axis tight
box on
view(-38.5,16)
camzoom(1.4)
camproj perspective
5. Add Lighting and Specify Colors
Adding a light to the scene makes the boundaries between the four slice planes
more obvious since each plane forms a different angle with the light source
(lightangle). Selecting a colormap with only 24 colors (the default is 64)
creates visible gradations that help indicate the variation within the volume.
lightangle(-45,45)
colormap (jet(24))
set(gcf,'Renderer','zbuffer')
15-16
Exploring Volumes with Slice Planes
Modifying the Color Mapping
The current colormap determines the coloring of the slice planes. This enables
you to change the slice plane coloring by:
• Changing the colormap
• Changing the mapping of data value to color
Suppose, for example, you are interested in data values only between -5 and 2.5
and would like to use a colormap that mapped lower values to reds and higher
values to blues (that is, the opposite of the default jet colormap).
Customizing the Colormap
The first step is to flip the colormap (colormap, flipud).
colormap (flipud(jet(24)))
Adjusting the Color Limits
Adjusting the color limits enables you to emphasize any particular data range
of interest. Adjust the color limits to range from -5 to 2.4832 so that any value
lower than the value -5 (the original data ranged from -11.5417 to 2.4832) is
mapped into to same color. (See caxis and the "Axis Color Limits – The CLim
Property" section in the “Axes Properties” chapter for an explanation of color
mapping.)
caxis([-5,2.4832])
Adding a color bar provides a key for the data to color mapping.
colorbar('horiz')
15-17
15
Volume Visualization Techniques
15-18
Connecting Equal Values with Isosurfaces
Connecting Equal Values with Isosurfaces
Isosurfaces are constructed by creating a surface within the volume that has
the same value at each vertex. Isosurface plots are similar to contour plots in
that they both indicate where values are equal.
Isosurfaces are useful to determine where in a volume a certain threshold
value is reached or to observe the spacial distribution of data by selecting
various isovalues at which to generate a plot. The isovalue must lie within the
range of the volume data.
Create isosurfaces with the isosurface and patch commands.
Example – Isosurfaces in Fluid Flow Data
This example creates isosurfaces in a volume generated by the flow M-file.
Generate the volume data with the command,
[x,y,z,v] = flow;
To select the isovalue, determine the range of values in the volume data.
min(v(:))
ans =
-11.5417
max(v(:))
ans =
2.4832
Through exploration, you can select isovalues that reveal useful information
about the data. Once selected, use the isovalue to create the isosurface:
• Use isosurface to generate data that you can pass directly to patch.
• Recalculate the surface normals from the gradient of the volume data to
produce better lighting characteristics (isonormals).
• Set the patch FaceColor to red and the EdgeColor to none to produce a
smoothly lit surface.
• Adjust the view and add lighting (daspect, view, camlight, lighting).
hpatch = patch(isosurface(x,y,z,v,0));
isonormals(x,y,z,v,hpatch)
set(hpatch,'FaceColor','red','EdgeColor','none')
15-19
15
Volume Visualization Techniques
daspect([1,4,4])
view([-65,20])
axis tight
camlight left;
set(gcf,'Renderer','zbuffer'); lighting phong
15-20
Isocaps Add Context to Visualizations
Isocaps Add Context to Visualizations
Isocaps are planes that are fitted to the limits of an isosurface to provide a
visual context for the isosurface. Isocaps show a cross-sectional view of the
interior of the isosurface for which it provides an end cap.
The following two pictures illustrate the use of isocaps. The first is an
isosurface without isocaps.
The second picture shows the effect of adding isocaps to the same isosurface.
15-21
15
Volume Visualization Techniques
Other Isocap Applications
Some additional applications of isocaps are:
• Isocaps used to show the interior of a cut-away volume.
• Isocaps used to cap the end of a volume that would otherwise appear empty.
• Isocaps used to enhance the visibility of the isosurface limits.
Defining Isocaps
Isocaps, like isosurfaces, are created as patch graphics objects. Use the
isocaps command to generate the data to pass to patch. For example,
patch(isocaps(voldata,isoval),...
'FaceColor','interp',...
'EdgeColor','none')
creates isocaps for the scalar volume data voldata at the value isoval. You
should create the isosurface using the same volume data and isovalue to ensure
that the edges of the isocaps fit the isosurface.
15-22
Isocaps Add Context to Visualizations
Setting the patch FaceColor property to interp results in a coloring that maps
the data values spanned by the isocap to colormap entries. You can also set
other patch properties to control the effects of lighting and coloring on the
isocaps.
Example – Adding Isocaps to an Isosurface
This example illustrates how to set coloring and lighting characteristics when
working with isocaps. There are four basic steps:
• Generate and process your volume data.
• Create the isosurface and isocaps and set patch properties to control the
coloring and lighting.
• Specify the view.
• Add lights to the scene.
1. Prepare the Data
This example uses a 3-D array of random (rand) data to define the volume data.
The data is then smoothed (smooth3).
data = rand(12,12,12);
data = smooth3(data,'box',5);
2. Create the Isosurface and Set Properties
Use isosurface and patch to create the isosurface and set coloring and
lighting properties. Reduce the AmbientStrength, SpecularStrength, and
DiffuseStrength of the reflected light to compensate for the brightness of the
two light sources used to provide more uniform lighting.
Recalculate the vertex normals of the isosurface to produce smoother lighting
(isonormals).
isoval = .5;
h = patch(isosurface(data,isoval),...
'FaceColor','blue',...
'EdgeColor','none',...
'AmbientStrength',.2,...
'SpecularStrength',.7,...
'DiffuseStrength',.4);
isonormals(data,h)
15-23
15
Volume Visualization Techniques
3. Create the Isocaps and Set Properties
Define the isocaps using the same data and isovalue as the isosurface. Specify
interpolated coloring and select a colormap that provides better contrasting
colors with the blue isosurface than those in the default colormap (colormap).
patch(isocaps(data,isoval),...
'FaceColor','interp',...
'EdgeColor','none')
colormap hsv
4. Specify the View
Set the data aspect ratio to [1,1,1] so that the displays in correct proportions
(daspect). Eliminate white space within the axis and set the view to 3-D (axis
tight, view).
daspect([1,1,1])
axis tight
view(3)
5. Add Lighting
To add fairly uniform lighting, but still take advantage of the ability of light
sources to make visible subtle variations in shape, this example uses two
lights; one to the left and one to the right of the camera (camlight). Use Phong
lighting to produce the smoothest variation of color (lighting). Phong lighting
requires the zbuffer renderer.
camlight right
camlight left
set(gcf,'Renderer','zbuffer');
lighting phong
15-24
Visualizing Vector Volume Data
Visualizing Vector Volume Data
Vector volume data contains more information than scalar data because each
coordinate point in the data set has three values associated with it. These
values define a vector that represents both a magnitude and a direction. The
velocity of fluid flow is an example of vector data.
MATLAB supports a number of techniques that are useful for visualizing
vector data:
• Stream lines trace the path that a massless particle immersed in the vector
field would follow.
• Stream particles are markers that trace stream lines and are useful for
creating stream line animations.
• Stream ribbons are similar to stream lines, except that the width of the
ribbons enable them to indicate twist. Stream ribbons are useful to indicate
curl angular velocity.
• Stream tubes are similar to stream lines, but you can also control the width
of the tube. Stream tubes are useful for displaying the divergence of a vector
field.
• Cone plots represent the magnitude and direction of the data at each point
by displaying a conical arrowhead or an arrow.
It is typically the case that these functions best elucidate the data when used
in conjunction with other visualization techniques, such as contours, slice
planes, and isosurfaces. The examples in this section illustrate some of these
techniques.
Using Scalar Techniques with Vector Data
Visualization techniques such as contour slices, slice planes, and isosurfaces
require scalar volume data. You can use these techniques with vector data by
taking the magnitude of the vectors. For example, the wind data set returns
three coordinate arrays and three vector component arrays, u, v, w. In this case,
the magnitude of the velocity vectors equals the wind speed at each
corresponding coordinate point in the volume.
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
15-25
15
Volume Visualization Techniques
The array wind_speed contains scalar values for the volume data. The
usefulness of the information produced by this approach, however, depends on
what physical phenomena is represented by the magnitude of your vector data.
Specifying Starting Points for Stream Plots
Stream plots (stream lines, ribbons, tubes, and cones or arrows) illustrate the
flow of a 3-D vector field. The MATLAB stream plotting routines (streamline,
streamribbon, streamtube, coneplot, stream2, stream3) all require you to
specify the point at which you want to begin each stream trace.
Determining the Starting Points
Generally, knowledge of your data’s characteristics help you select the starting
points. Information such as the primary direction of flow and the range of the
data coordinates helps you decide where to evaluate the data.
The streamslice function is useful for exploring your data. For example, these
statements draw a slice through the vector field at a z value midway in the
range.
load wind
zmax = max(z(:)); zmin = min(z):));
streamslice(x,y,z,u,v,w,[],[],(zmax-zmin)/2)
15-26
Visualizing Vector Volume Data
This stream slice plot indicates that the flow is in the positive x direction and
also enables you to select starting points in both x and y. You could create
similar plots that slice the volume in the x-z plane or the y-z plane to gain
further insight into your data’s range and orientation.
Specifying Arrays of Starting-Point Coordinates
To specify the starting point for one stream line, you need the x-, y-, and
z-coordinates of the point. The meshgrid command provides a convenient way
to create arrays of starting points. For example, you could select the following
starting points from the wind data displayed in the previous stream slice.
[sx,sy,sz] = meshgrid(80,20:10:50,0:5:15);
This statement defines the starting points as all lying on x = 80, y ranging from
20 to 50, and z ranging from 0 to 15. You can use plot3 to display the locations.
plot3(sx(:),sy(:),sz(:),'*r');
axis(volumebounds(x,y,z,u,v,w))
grid; box; daspect([2 2 1])
15
10
5
0
130
120
50
110
40
100
90
30
20
80
You do not need to use 3-D arrays, such as those returned by meshgrid, but the
size of each array must be the same, and meshgrid provides a convenient way
to generate arrays when you do not have an equal number of unique values in
15-27
15
Volume Visualization Techniques
each coordinate. You can also define starting-point arrays as column vectors.
For example, meshgrid returns 3-D arrays.
[sx,sy,sz] = meshgrid(80,20:10:50,0:5:15);
whos
Name
Size
Bytes Class
sx
4x1x4
128 double array
sy
4x1x4
128 double array
sz
4x1x4
128 double array
In addition, you could use 16-by-1 column vectors with the corresponding
elements of the three arrays comprising the coordinates of each starting point.
(This is the equivalent of indexing the values returned by meshgrid as sx(:),
sy(:), and sz(:).)
For example, adding the stream lines produces
streamline(x,y,z,u,v,w,sx(:),sy(:),sz(:))
15
10
5
0
130
120
50
110
40
100
90
30
20
80
Accessing Subregions of Volume Data
The subvolume function provides a simple way to access subregions of a volume
data set. subvolume enables you to select regions of interest based on limits
rather than using the colon operator to index into the 3-D arrays that define
15-28
Visualizing Vector Volume Data
volumes. Consider the following two approaches to creating the data for a
subvolume – indexing with the colon operator and using subvolume.
Indexing with the Colon Operator
When you index the arrays, you work with values that specify the elements in
each dimension of the array.
load
xsub
ysub
zsub
usub
vsub
wsub
wind
= x(1:10,20:30,1:7);
= y(1:10,20:30,1:7);
= z(1:10,20:30,1:7);
= u(1:10,20:30,1:7);
= v(1:10,20:30,1:7);
= w(1:10,20:30,1:7);
Using the subvolume Function
subvolume enables you to use coordinate values that you can read from the
axes. For example,
lims = [100.64 116.67 17.25 28.75 -0.02 6.86];
[xsub,ysub,zsub,usub,vsub,wsub] = subvolume(x,y,z,u,v,w,lims);
You can then use the subvolume data as inputs to any function requiring vector
volume data.
15-29
15
Volume Visualization Techniques
Stream Line Plots of Vector Data
MATLAB includes a vector data set called wind that represents air currents
over North America. This example uses a combination of techniques:
• Stream lines to trace the wind velocity
• Slice planes to show cross-sectional views of the data
• Contours on the slice planes to improve the visibility of slice-plane coloring
1. Determine the Range of the Coordinates
Load the data and determine minimum and maximum values to locate the slice
planes and contour plots (load, min, max).
load
xmin
xmax
ymax
zmin
wind
= min(x(:));
= max(x(:));
= max(y(:));
= min(z(:));
2. Add Slice Planes for Visual Context
Calculate the magnitude of the vector field (which represents wind speed) to
generate scalar data for the slice command. Create slice planes along the
x-axis at xmin, 100, and xmax, along the y-axis at ymax, and along the z-axis at
zmin. Specify interpolated face coloring so the slice coloring indicates wind
speed, and do not draw edges (sqrt, slice, FaceColor, EdgeColor).
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
hsurfaces = slice(x,y,z,wind_speed,[xmin,100,xmax],ymax,zmin);
set(hsurfaces,'FaceColor','interp','EdgeColor','none')
3. Add Contour Lines to the Slice Planes
Draw light gray contour lines on the slice planes to help quantify the color
mapping (contourslice, EdgeColor, LineWidth).
hcont = ...
contourslice(x,y,z,wind_speed,[xmin,100,xmax],ymax,zmin);
set(hcont,'EdgeColor',[.7,.7,.7],'LineWidth',.5)
15-30
Stream Line Plots of Vector Data
4. Define the Starting Points for the Stream Lines
In this example, all stream lines start at an x-axis value of 80 and span the
range 20 to 50 in the y direction and 0 to 15 in the z direction. Save the handles
of the stream lines and set the line width and color (meshgrid, streamline,
LineWidth, Color).
[sx,sy,sz] = meshgrid(80,20:10:50,0:5:15);
hlines = streamline(x,y,z,u,v,w,sx,sy,sz);
set(hlines,'LineWidth',2,'Color','r')
5. Define the View
Set up the view, expanding the z-axis to make it easier to read the graph (view,
daspect, axis).
view(3)
daspect([2,2,1])
axis tight
See coneplot for an example of the same data plotted with cones.
15-31
15
Volume Visualization Techniques
Displaying Curl with Stream Ribbons
Stream ribbons illustrate direction of flow, similar to stream lines, but can also
show rotation about the flow axis by twisting the ribbon-shaped flow line. The
streamribbon function enables you to specify a twist angle (in radians) for each
vertex in the stream ribbons.
When used in conjunction with the curl function, streamribbon is useful for
displaying the curl angular velocity of a vector field. The following example
illustrates this technique.
1. Select a Subset of Data to Plot
Load and select a region of interest in the wind data set using subvolume.
Plotting the full data set first can help you select a region of interest.
load wind
lims = [100.64 116.67 17.25 28.75 -0.02 6.86];
[x,y,z,u,v,w] = subvolume(x,y,z,u,v,w,lims);
2. Calculate Curl Angular Velocity and Wind Speed
Calculate the curl angular velocity and the wind speed.
cav = curl(x,y,z,u,v,w);
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
3. Create the Stream Ribbons
• Use meshgrid to create arrays of starting points for the stream ribbons. See
"Starting Points for Stream Plots" in this chapter for information on
specifying the arrays of starting points.
• stream3 calculates the stream line vertices with a step size of .5
• streamribbon scales the width of the ribbon by a factor of 2 to enhance the
visibility of the twisting (which indicates curl angular velocity).
• streamribbon returns the handles of the surface objects it creates, which are
then used to set the color to red (FaceColor), the color of the surface edges to
light gray (EdgeColor), and slightly increase the brightness of the ambient
light reflected when lighting is applied (AmbientStrength).
[sx sy sz] = meshgrid(110,20:5:30,1:5);
verts = stream3(x,y,z,u,v,w,sx,sy,sz,.5);
15-32
Displaying Curl with Stream Ribbons
h = streamribbon(verts,x,y,z,cav,wind_speed,2);
set(h,'FaceColor','r',...
'EdgeColor',[.7 .7 .7],...
'AmbientStrength',.6)
4. Set the View and Add Lighting
• The volumebounds command provides a convenient way to set axis and color
limits.
• Add a grid a set the view for 3-D (streamribbon does not change the current
view).
• camlight creates a light positioned to the right of the view point and
lighting sets the lighting method to Phong (which requires the zbuffer
renderer).
axis(volumebounds(x,y,z,wind_speed))
grid on
view(3)
camlight right;
set(gcf,'Renderer','zbuffer'); lighting phong
15-33
15
Volume Visualization Techniques
Displaying Divergence with Stream Tubes
Stream tubes are similar to stream lines, except the tubes have width,
providing another dimension that you can use to represent information.
By default, MATLAB indicates the divergence of the vector field by the width
of the tube. You can also define widths for each tube vertex and thereby map
other data to width.
This example uses the following techniques:
• Stream tubes indicate flow direction and divergence of the vector field in the
wind data set.
• Slice planes colored to indicate the speed of the wind currents overlaid with
contour line to enhance visibility
Inputs include the coordinates of the volume, vector field components, and
starting location for the stream tubes.
1. Load Data and Calculate Required Values
The first step is to load the data and calculate values needed to make the plots.
These values include:
• The location of the slice planes (maximum x, minimum y, and a value for the
altitude)
• The minimum x value for the start of the stream tubes
• The speed of the wind (magnitude of the vector field)
load wind
xmin = min(x(:));
xmax = max(x(:));
ymin = min(y(:));
alt = 7.356; % z-value for slice and streamtube plane
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
2. Draw the Slice Planes
Draw the slice planes (slice) and set surface properties to create a smoothly
colored slice. Use 16 colors from the hsv colormap.
hslice = slice(x,y,z,wind_speed,xmax,ymin,alt);
set(hslice,'FaceColor','interp','EdgeColor','none')
15-34
Displaying Divergence with Stream Tubes
colormap hsv(16)
3. Add Contour Lines to Slice Planes
Add contour lines (contourslice) to the slice planes. Adjust the contour
interval so the lines match the color boundaries in the slice planes by:
• Calling caxis to get the current color limits
• Setting the interpolation method used by contourslice to linear to match
the default used by slice.
color_lim = caxis;
cont_intervals = linspace(color_lim(1),color_lim(2),17);
hcont = contourslice(x,y,z,wind_speed,xmax,ymin,...
alt,cont_intervals,'linear');
set(hcont,'EdgeColor',[.4 .4 .4],'LineWidth',1)
4. Create the Stream Tubes
Use meshgrid to create arrays for the starting points for the stream tubes,
which begin at the minimum x value, range from 20 to 50 in y, and lie in a
single plane in z (corresponding to one of the slice planes).
The stream tubes (streamtube) are drawn at the specified locations and scaled
to be 1.25 times the default width to emphasize the variation in divergence
(width). The second element in the vector [1.25 30] specifies the number of
points along the circumference of the tube (the default is 20). You may want to
increase this value as the tube size increases to maintain a smooth-looking
tube.
Set the data aspect ratio (daspect) before calling streamtube.
Stream tubes are surface objects therefore you can control their appearance by
setting (surface properties). This example sets surface properties to give a
brightly lit, red surface.
[sx,sy,sz] = meshgrid(xmin,20:3:50,alt);
daspect([1,1,1]) % set DAR before calling streamtube
htubes = streamtube(x,y,z,u,v,w,sx,sy,sz,[1.25 30]);
set(htubes,'EdgeColor','none','FaceColor','r',...
'AmbientStrength',.5)
15-35
15
Volume Visualization Techniques
5. Define the View
The final step is to define the view and add lighting (view, axis volumebounds,
Projection, camlight).
view(-100,30)
axis(volumebounds(x,y,z,wind_speed))
set(gca,'Projection','perspective')
camlight left
15-36
Creating Stream Particle Animations
Creating Stream Particle Animations
A stream particle animation is useful for visualizing the flow direction and
speed of a vector field. The “particles” (represented by any of the line markers)
trace the flow along a particular stream line. The speed of each particle in the
animation is proportional to the magnitude of the vector field at any given
point along the stream line.
1. Specify the Starting Points of the Data Range to Plot
This example determines the region of the volume to plot by specifying the
appropriate starting points. In this case, the stream plots begin a x = 100, y
spans 20 to 50 and in the z = 5 plane. Note that this is not the full volume
bounds.
load wind
[sx sy sz] = meshgrid(100,20:2:50,5);
2. Create Stream Lines to Indicate the Particle Paths
This example uses stream lines (stream3, streamline) to trace the path of the
animated particles. This adds a visual context for the animation. Another
possibility is to set the EraseMode property of the stream particle to none,
which would be useful for a single trace through the volume.
verts = stream3(x,y,z,u,v,w,sx,sy,sz);
sl = streamline(verts);
3. Define the View
While all of the stream lines start in the z = 5 plane, the values of some spiral
down to lower values. The following settings provide a clear view of the
animation:
• The viewpoint (view) selected shows both the plane containing most stream
lines as well as the spiral.
• Selecting a data aspect ratio (daspect) of [2 2 0.125] provides greater
resolution in the z-direction to make the stream particles more easily visible
in the spiral.
• Set the axes limits to match the data limits (axis) and draw the axis box
(box).
15-37
15
Volume Visualization Techniques
view(-10.5,18)
daspect([2 2 0.125])
axis tight; box on
4. Calculate the Stream Particle Vertices
The first step is to determine the vertices along the stream line where a particle
should be drawn. The interpstreamspeed function returns this data based on
the stream line vertices and the speed of the vector data. This example scales
the velocities 0.05 to increase the number of interpolated vertices.
Setting the axes DrawMode property to fast enables the animation to run
faster.
The streamparticles function sets the following properties:
• Animate to 10 to run the animation 10 times
• ParticleAlignment to on to start all particle traces together
• MarkerEdgeColor to none to draw only the face of the circular marker.
Animations usually run faster when marker edges are not drawn.
• MarkerFaceColor to red
• Marker to o, which draws a circular marker. You can use other line markers
as well.
iverts = interpstreamspeed(x,y,z,u,v,w,verts,0.05);
set(gca,'drawmode','fast');
streamparticles(iverts,15,...
'Animate',10,...
'ParticleAlignment','on',...
'MarkerEdgeColor','none',...
'MarkerFaceColor','red',...
'Marker','o');
15-38
Creating Stream Particle Animations
15-39
15
Volume Visualization Techniques
Vector Field Displayed with Cone Plots
This example plots the velocity vector cones for the wind data. The graph
produced employs a number of visualization techniques:
• An isosurface is used to provide visual context for the cone plots and to
provide means to select a specific data value for a set of cones.
• Lighting enables the shape of the isosurface to be clearly visible.
• The use of perspective projection, camera positioning, and view angle
adjustments compose the final view.
1. Create an Isosurface
Displaying an isosurface within the rectangular space of the data provides a
visual context for the cone plot. Creating the isosurface requires a number of
steps:
• Calculate the magnitude of the vector field, which represents the speed of the
wind.
• Use isosurface and patch to draw an isosurface illustrating where in the
rectangular space the wind speed is equal to a particular value. Regions
inside the isosurface have higher wind speeds, regions outside the isosurface
have lower wind speeds.
• Use isonormals to compute vertex normals of the isosurface from the volume
data rather than calculate the normals from the triangles used to render the
isosurface. These normals generally produce more accurate results.
• Set visual properties of the isosurface, making it red and without edges
drawn (FaceColor, EdgeColor).
load wind
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
hiso = patch(isosurface(x,y,z,wind_speed,40));
isonormals(x,y,z,wind_speed,hiso)
set(hiso,'FaceColor','red','EdgeColor','none');
2. Add Isocaps to the Isosurface
Isocaps are similar to slice planes in that they show a cross section of the
volume. They are designed to be the end caps of isosurfaces. Using interpolated
face color on an isocap causes a mapping of data value to color in the current
15-40
Vector Field Displayed with Cone Plots
colormap. To create isocaps for the isosurface, define them at the same isovalue
(isocaps, patch, colormap).
hcap = patch(isocaps(x,y,z,wind_speed,40),...
'FaceColor','interp',...
'EdgeColor','none');
colormap hsv
3. Create First Set of Cones
• Use daspect to set the data aspect ratio of the axes before calling coneplot
so MATLAB can determine the proper size of the cones.
• Determine the points at which to place cones by calculating another
isosurface that has a smaller isovalue (so the cones display outside the first
isosurface) and use reducepatch to reduce number of faces and vertices (so
there are not too many cones on the graph).
• Draw the cones and set the face color to blue and the edge color to none.
daspect([1,1,1]);
[f verts] = reducepatch(isosurface(x,y,z,wind_speed,30),0.07);
h1 = coneplot(x,y,z,u,v,w,verts(:,1),verts(:,2),verts(:,3),3);
set(h1,'FaceColor','blue','EdgeColor','none');
4. Create Second Set of Cones
• Create a second set of points at values that span the data range (linspace,
meshgrid).
• Draw a second set of cones and set the face color to green and the edge color
to none.
xrange = linspace(min(x(:)),max(x(:)),10);
yrange = linspace(min(y(:)),max(y(:)),10);
zrange = 3:4:15;
[cx,cy,cz] = meshgrid(xrange,yrange,zrange);
h2 = coneplot(x,y,z,u,v,w,cx,cy,cz,2);
set(h2,'FaceColor','green','EdgeColor','none');
15-41
15
Volume Visualization Techniques
5. Define the View
• Use the axis command to set the axis limits equal to the minimum and
maximum values of the data and enclose the graph in a box to improve the
sense of a volume (box).
• Set the projection type to perspective to create a more natural view of the
volume. Set the view point and zoom in to make the scene larger (camproj,
camzoom, view).
axis tight
box on
camproj perspective
camzoom(1.25)
view(65,45)
6. Add Lighting
Add a light source and use Phong lighting for the smoothest lighting of the
isosurface (Phong lighting requires the zbuffer renderer). Increase the strength
of the background lighting on the isocaps to make them brighter (camlight,
lighting, AmbientStrength).
camlight(-45,45)
set(gcf,'Renderer','zbuffer');
lighting phong
set(hcap,'AmbientStrength',.6)
15-42
Vector Field Displayed with Cone Plots
15-43
15
Volume Visualization Techniques
15-44
Index
Symbols
3-29
A
alpha values 13-4
ambient light 12-13
AmbientLightColor property 12-8
illustration 12-13
AmbientStrength property 12-8
illustration 12-13
animation 4-51
erase modes for 4-53
movies 4-51
annotating graphs 3-1
adding a legend 3-6
adding a title 3-3
adding labels 3-11
adding plots of data statistics 3-29
adding text 3-15
annotations
adding 1-13, 3-16
area 4-3, 4-12
area graphs 4-3, 4-12
arrays, storing images 5-4
arrow annotations
adding 1-13
arrows
adding to a graph 3-28
aspect ratio 11-41–11-55
for realistic objects 11-54
properties that affect 11-46
specifying 11-50
axes
adding labels 3-11
adding text 3-17
aspect ratio 11-41, 11-46
2-D 2-24
3-D 11-41
properties that affect 11-46
specifying 11-50
automatic modes 8-19
axis control 8-10
axis direction 8-13
camera properties 11-30
CLim property 8-25
color limits 8-25
ColorOrder property 8-30
colors 8-22
controlling the shape of 11-50
default aspect ratio 11-47
functions for 1-8
individual axis control 8-10
labeling 3-13
labels
font properties 8-4
using TeX characters 3-23
limits 11-41
example 11-53
locking position 1-8
making grids coincident 8-17
multi-axis 8-16
multiple 2-26, 8-7
NextPlot property 7-38
overlapping 8-7
plot box 11-8
position rectangle 11-31
positioning 8-5–8-9
preparing to accept graphics 7-37
properties
for labeling 8-3
list 8-2
properties of 1-9
I-1
Index
protecting from output 7-43
scaling 11-41
independent 8-8
setting
limits 8-11
line styles used for plotting 8-31
setting limits 2-19
standard plotting behavior 7-42
stretch-to-fill 11-41
target for graphics 2-28
tick marks 2-21
locating 8-12
units 8-6
unlocking position 1-8
with two x and y axes 8-16
axis 5-2
axis 11-41
auto 11-41
equal 2-24, 11-42
ij 11-42
illustrated examples, 2-D 2-24
illustrated examples, 3-D 11-43
image 5-20, 11-42
manual 11-42
normal 11-42
square 2-24, 11-42
tight 2-25, 11-42
vis3d 11-42
xy 11-42
azimuth of viewpoint 11-4
default 2-D 11-4
default 3-D 11-5
limitations 11-7
B
BackFaceLighting property 12-9
I-2
illustration 12-15
backing store 9-15
bar 4-3, 4-4
bar graphs 4-3–4-12
3-D 4-4
grouped
2-D 4-3
3-D 4-5
horizontal 4-7
labeling 4-5, 4-8
overlaid with plots 4-10
stacked 4-6
bar3 4-3, 4-4
bar3h 4-3
barh 4-3
binary images 5-8
bins, specifying for histogram 4-21
BMP 5-2
brighten 10-20
buttons on toolbar 1-13, 1-14, 3-16, 3-28
C
camdolly 11-21
camera position, moving 11-31
camera properties 11-30
illustration showing 11-8
camera toolbar 11-9
CameraPosition property 11-30
and perspective 11-31
fly-by 11-31
CameraPositionMode property 11-30
CameraTarget property 11-30
CameraTargetMode property 11-30
CameraUpVector property 11-30, 11-34
example 11-35
CameraUpVectorMode property 11-30
Index
CameraViewAngle property 11-30
and perspective 11-33
zooming with 11-33
CameraViewAngleMode property 11-30, 11-33
camlookat property 11-21
camorbit 11-21
campan 11-21
campos 11-21
camproj 11-21
camroll 11-21
camtarget 11-21
camup 11-21
camva 11-21
camzoom 11-21
CData property
images 5-23
patches 14-11
CDataMapping property 10-18
images 5-23
patches 14-11
cla 7-38
clabel 4-38, 4-40
clf 7-38
close 7-45
close request function
default 7-45
closereq.m 7-45
CloseRequestFcn property 7-45
default value 7-45
errors in 7-46
overriding 7-46
closing figures 7-45
closing MATLAB, errors occurring when 7-46
color limits, calculating 8-26
color property of lights 12-4
colorbar 10-16
colordef 2-29
colormap 10-15
colormaps
altering 10-20
brightening 10-20
brightness component of TV signal 10-21
displaying 10-16
for surfaces 10-14
functions that create 10-15
large 9-9
minimum size 9-10
range of RGB values in 10-14
simulating multiple 8-25
size of dithermap 9-14
ColorOrder 8-29
colors
changing color scheme 8-23
colormaps 9-8, 10-14
controlled by axes 8-22
controlled by figure properties 9-7
dithering 9-12, 10-24
effects of dithering 9-14
fixed 9-8
indexed 10-14
direct 10-17
scaled 10-17
indexed and dithering 9-12
interpreted by surfaces 10-14
mapping to data 8-25
NTSC encoding of 10-21
of patches 14-11
of surface plots 10-14
scaling algorithm 10-18
shared 9-11
size of dithermap 9-14
specifying Figure colors 2-28
specifying for surface plot, example 10-18
truecolor 10-14
I-3
Index
on indexed color systems 10-24
specifying 10-22
typical RGB values 10-15
used for plotting 8-29
using a large number 9-9
compass 4-32
compass plots 4-32
complex numbers, plotting 2-15
with feather 4-34
cone plots 15-40
contour 4-38
contour plots 4-38
algorithm 4-43
filled 4-41
in polar coordinates 4-45
labeling 4-40
specifying contour levels 4-42, 4-44
contour3 4-38
contourc 4-38, 4-43
contourf 4-38, 4-41
conv2 5-13
converting the data class of an indexed image
5-11
convn 5-13
coordinate system and viewpoint 11-4
copying
figures 1-11
options 1-11
copying graphics objects 7-33
current
Axes 7-30
Figure 7-30
object 7-30
cursors, see pointers
I-4
D
data statistics
formatting plots of of 3-32
plotting 3-29, 3-32
Data Statistics tool
example 3-30
interface 3-30
overview 1-22
saving to workspace 3-34
data types
8-bit integers 5-4
double-precision 5-4
DataAspectRatio property 11-46
example 11-50
images 5-21
DataAspectRatioMode property 11-46
default
aspect ratio 11-47
azimuth
2-D 11-4
3-D 11-5
CameraPosition 11-31
CameraTarget 11-31
CameraUpVector 11-31
CameraViewAngle 11-31
CloseRequestFcn 7-45
elevation
2-D 11-4
3-D 11-5
factory 7-22
figure color scheme 2-28
Projection 11-31
property values 7-23–??
removing 7-25
search path, diagram 7-23
setting to factory defaults 7-26
view 11-31
Index
default line styles, setting and removing 2-11
del2 10-18
deleting graphics objects 7-35
deselecting objects 1-8
diffuse reflection 12-12
DiffuseStrength property 12-8
illustration 12-12
direct color mapping 10-17
direction cosines 11-34
discrete data graphs 4-23–4-31
stairstep plots 4-30
stem plots 4-23
dithering 9-12
algorithm 9-12
effects of 9-14
Dithermap property 9-12
DithermapMode property 9-12, 9-13
documentation 1-12
double 5-29
double
converting double to uint8 or uint16 5-11
converting image data to double 5-29
double buffering 9-15
double converting double to uint16 5-12
double converting double to uint8 5-12
E
edge effects and lighting 12-16
EdgeColor property 12-9
EdgeLighting property 12-9
edges of patches 14-14
Edit menu
starting Property Editor 1-16
editing plots
interactively 1-6
efficient programming 7-48, 7-49
elevation of viewpoint 11-4
default 2-D 11-4
default 3-D 11-5
limitations 11-7
ending plot edit mode 1-7
erase modes 4-53
and printing 4-55
background 4-55
images 5-26
none 4-53
xor 4-56
errors closing MATLAB 7-46
examples
3-D graph 10-3
animation 4-53
area graphs 4-12
axis 11-43
bar graphs 4-4
changing CameraPosition 11-32
contour plots 4-38
copying graphics objects 7-33
custom pointers 9-20
DataAspectRatio property 11-50
del2 10-18
direction and velocity graphs 4-32
direction cosines 11-34
discrete data graphs 4-23
displaying real objects 11-54
double axis graphs 8-16
finding objects handles 7-32
histograms 4-18
hold 7-43
line 7-40
linspace 10-10
meshgrid 10-4, 10-10
movies 4-52
multiline text 3-25
I-5
Index
newplot 7-40
object creation functions 7-13
of lighting 12-2
overlapping axes 8-7
parametric surfaces 10-12
pie charts 4-15
placing text dynamically 3-21
plot 2-2
complex data 2-15
plot3 10-4
PlotBoxAspectRatio property 11-52
plotting linestyles 8-31
ScreenSize property 9-5
setting default property values 7-26
simulating multiple colormaps 8-25
specifying figure position 9-5
specifying truecolor
surfaces 10-22
stretch-to-fill 11-50
subplot 2-26
text 3-16
texture mapping 10-25
unevenly sampled data 10-9
view 11-33
exporting figures 1-11
extent of computer screen 9-4
F
FaceColor property 12-9
FaceLighting property 12-8
Faces property 14-7
FaceVertexCData property 14-9, 14-11
factory defaults 7-22
feather 4-32, 4-33
feather plots 4-33
fft2 5-13
I-6
fftn 5-13
figure files 1-10
figures
CloseRequestFcn 7-45
closing 7-45
copying 1-11
defining custom pointers 9-19
defining pointers 9-18
defining the color of 2-28
fixed colors 9-8
for plotting 2-26
index color properties 9-7
introduction to 9-2
NextPlot property 7-38
nonactive 9-11
opening 1-10
positioning 9-3
positioning example 9-5
preparing to accept graphics 7-37
protecting from output 7-43
rendering properties 9-15
saving 1-10
specifying pointers 9-18
standard plotting behavior 7-42
units 9-4
visible property 7-45
with multiple axes 2-26
files
exporting 1-11
figure fig 1-10
formats for figures 1-11
opening 1-10
printing 1-11
saving 1-10
fill, properties changed by 7-49
fill3, properties changed by 7-49
findobj 7-32
Index
fixed colors 9-8
FixedColors property 9-8
Floyd-Steinberg dithering algorithm 9-12
fly-by effect 11-31
fonts
axis labels 8-4
formats for figures 1-11
functions
convenience forms 7-16
high-level vs. low-level 7-15
to create graphics objects 7-12
G
gca 7-31
handle visibility 7-44
gcf 7-31
handle visibility 7-44
gco 7-31
get 7-18
getframe 4-51
ginput 4-49
Gouraud lighting algorithm 12-10
gradient 4-36
graphical input 4-49
graphics
M-files, structure of 7-41
graphics file formats
list of formats supported by MATLAB 5-2
graphics images
16-bit
intensity 5-12
8-bit
intensity 5-12
RGB 5-12
converting from one format to another 5-29
converting to RGB 5-29
reading from file 5-15
see also BMP, HDF, JPG, PCX, PNG, TIFF,
XWD 5-16
writing to file 5-16
graphics objects 7-4
accessing handles 7-30
accessing hidden handles 7-44
axes 7-7
controlling where they draw 7-37
copying 7-33
deleting 7-35
editing properties 1-9, 1-17
figures 7-5
functions that create 7-12
convenience forms 7-16
handle validity versus visibility 7-46
HandleVisibility property 7-43
hierarchy 7-3
images 7-7
See also Image chapter
invisible handles 7-43
lights 7-7
line 7-7
patches 7-8
properties 7-9
changed by functions 7-49
changed when created 7-14
common to all objects 7-10
factory defined 7-22
getting current values 7-20
listing possible values 7-19
querying in groups 7-22
search path for default values 7-23
searching for 7-32
setting values 7-18
property names 7-16
rectangle 7-8
I-7
Index
root 7-5
setting parent of 7-15
specifying tag value 1-20
surface 7-8
text 7-8
uicontrol 7-5
uimenu 7-6
graphs
area 4-12–4-14
bar 4-3–4-12
horizontal 4-7
compass plots 4-32
contour plots 4-38–4-47
direction and velocity 4-32–4-37
discrete data 4-23–4-31
feather plots 4-33
histograms 4-18–4-22
labeling 3-1
pie charts 4-15–4-17
quiver plots 4-35
stairstep plots 4-30
steps to create 3-D 10-3
with double axes 8-16
grayscale 5-17
see also intensity images 5-17
Greek characters
see text function
using to annotate 3-14
griddata 10-10
grids, coincident 8-17
H
Hadamard matrix 10-12
Handle Graphics
graphics objects 7-4
hierarchy of graphics objects 7-3
I-8
handles to graphics objects 7-30
finding 7-32
handles, saving in M-files 7-48
HandleVisibility property 7-43
HDF 5-2
help 1-12
hidden 10-13
hidden line removal 10-13
high-level functions 7-15
hist 4-18
histograms 4-18
in polar coordinates 4-20
labeling the bins 4-21
rose plot 4-20
specifying number of bins 4-21
hold 2-7
and NextPlot 7-39
testing state of 7-42
hold state, testing for 7-42
HorizontalAlignment property 3-19
I
image 5-2
image 5-19
properties changed by 7-49
image types
binary 5-8
images
16-bit 5-11
indexed 5-11
8-bit 5-11
indexed 5-11
data types 5-4
erase modes 5-26
indexed 5-6
information about files 5-16
Index
intensity 5-7
numeric classes 5-2
printing 5-28
properties 5-23
CData 5-23
CDataMapping 5-23
XData and YData 5-24
RGB 5-9
see also graphics images 5-12
size and aspect ratio 5-19
storing in MATLAB 5-4
truecolor 5-9
types 5-6
imagesc 5-2
imagesc 5-8
imagesc 5-8
imfinfo 5-3
imfinfo 5-16
imread 5-2
imread 5-15
imwrite 5-3
imwrite 5-16
ind2rgb 5-29
indexed color
displays 9-7
dithering truecolor 9-12
surfaces 10-14
indexed images
converting the data class of 5-11
indirgb 5-3
Infs, avoiding in data 10-7
intensity images
converting the data class of 5-12
interpolated colors
patches 14-9
indexed vs. truecolor 14-19
interpreter property 3-24
ishold 7-42
isosurface
illustrating flow data 15-19
J
JPEG 5-2
L
labeling
axes 3-11
labeling graphs 3-1, 3-11
Laplacian of a matrix 10-18
LaTeX. See TeX
legend
adding to a graph 3-6
editing text labels 3-9
positioning in a graph 3-8
legend 4-26
legends
with data statistics 3-31
light 12-4
lighting 12-2–12-19
algorithms
flat 12-10
Gouraud 12-10
Phong 12-10
ambient light 12-13
backface 12-15
diffuse reflection 12-12
important properties 12-4
properties that affect 12-8
reflectance characteristics 12-12–12-15
specular
color 12-15
exponent 12-14
I-9
Index
reflection 12-12
lighting command 12-11
limits
axes 2-19, 8-11
line styles
used for plotting 2-5
redefining 8-31
lines
adding as annotations 3-28
adding to existing graph 2-7
annotations 1-13
marker types 2-5
properties of 1-9
removing hidden 10-13
styles 2-5
LineStyleOrder property 8-31
linspace 10-9
locking axes position 1-8
loglog, properties changed by 7-49
low-level functions 7-15
M
mapping data to color 8-25
markers used for plotting 2-5
material command 12-12
mathematical functions
visualizing with surface plot 10-7
MATLAB 4 color scheme 2-29
MATLAB, quitting 7-46
matrix
displaying contours 4-39
Hadamard 10-12
plotting 2-13
representing as
area graph 4-12
bar graph 4-4
I-10
histogram 4-19
surface 10-6
storing images 5-4
menus 1-8
mesh 10-6
meshc 4-44
meshgrid 10-7
M-files
basic structure of graphics 7-41
closereq 7-45
to set color mapping 8-28
using newplot 7-39
writing efficient 7-48
min
plotting 3-29
MinColormap property 9-9
movie 4-51, 4-52
movies 4-51
example 4-52
moving
objects 1-8
MRI data, visualizing 15-8
multiaxis axes 8-16
multiline text 3-25
N
navigation bar
in Property Editor 1-18
newplot 7-39
example using 7-40
NextPlot property 7-38
add 7-38
replace 7-38
replacechildren 7-38, 7-42
setting plotting color order 8-30
nonuniform data, plotting 10-9
Index
NormalMode property 12-9
NTSC color encoding 10-21
O
object properties
editing 1-15
online help 1-12
open 1-10, 1-11
OpenGL 9-16, 9-17
opening figures 1-10
options for copying 1-11
organization of Handle Graphics 7-3
orthographic projection 11-36
and Z-buffer 11-38
P
page setup 1-11
painters algorithm 9-16
parametric surfaces 10-11
parent, of graphics object 7-15
patch
behavior of function 14-2
interpreting color 14-3
patches
coloring 14-11
faces and edges 14-13
face coloring
flat 14-8
interpolated 14-9
indexed color 14-16
direct 14-18
scaled 14-16
interpreting color data 14-16
multifaceted 14-6
single polygons 14-4
specifying faces and vertices 14-7
truecolor 14-19
ways to specify 14-2
PCX 5-2
perspective projection 11-36
and Z-buffer 11-38
Phong lighting algorithm 12-10
pie charts 4-15
labeling 4-16
offsetting a slice 4-15
removing a piece 4-17
plot 2-2
properties changed by 7-50
plot box 11-8
plot edit mode, starting and ending 1-7
plot editing mode
overview 1-6
plot3 10-4
properties changed by 7-50
PlotBoxAspectRatio property 11-46
example 11-52
PlotBoxAspectRatioMode property 11-46
plotedit 1-7
plots
editing object in 1-17
plotting
3-D
matrices 10-4
vectors 10-4
adding to existing graph 2-7
annotating graphs 3-1
area graphs 4-12
bar graphs 4-3
compass plots 4-32
complex data 2-15
contour plots 4-38
contours, labeling 4-40
I-11
Index
creating a plot 2-2
data-point markers 2-5
elementary functions for 2-2
feather plots 4-33
interactive 4-49
line colors 8-29
line styles 2-5
matrices 2-13
multiple graphs 2-3
nonuniform data 10-9
overlaying bar graphs 4-10
quiver plots 4-35
specifying line styles 2-4, 8-31
stairstep plots 4-30
stem plots 4-23
surfaces 10-6
to subaxis 2-26
vector data 2-2
windows for 2-26
plotting statistics 3-32
PNG 5-2
writing as 16-bit using imwrite 5-16
Pointer property 9-19
pointers
custom 9-19
example defining 9-20
specifying 9-18
PointerShapeCData property 9-19
PointerShapeHotSpot property 9-19
polar 4-47
polar coordinates
contour plots 4-45
rose plot 4-20
polygons, creating with patch 14-2
pop-up menus 1-8
position of figure 9-3
Position property
I-12
axes 8-5
figure 9-3
position rectangle 11-8
positioning axes 1-8
positioning of axes 8-5
positioning text on a graph 3-17
preferences 1-11
printing
3-D scenes 11-39
images 5-28
Print dialog box 6-26
quick start 6-3
resolution
with painters renderer 9-17
with Z-buffer renderer 9-17
troubleshooting 6-55
Z-buffer 9-17
printing figures 1-11
Projection property 11-30
projection types 11-36–11-40
camera position 11-37
orthographic 11-36
perspective 11-36
rendering method 11-38
properties
automatic axes 8-19
axes 8-2
changed by built-in functions 7-49
changed by object creation functions 7-14
defining in startup.m 7-29
editing 1-9, 1-15
for labeling axes 8-3
naming convention 7-16
See also graphics objects
specifying default values 7-25
Property Editor
closing 1-16
Index
editing multiple objects 1-18
interface 1-15
overview 1-15
searching for objects 1-20
starting 1-16
using the navigation bar 1-18
property values
defaults 7-23
defined by MATLAB 7-22
getting 7-18
resetting to default 7-25
setting 7-18
specifying defaults 7-25
user defined 7-23
pseudocolor displays, see indexed color
resizing
objects 1-8
RGB
color values 10-15
converting to 5-29
images 5-9
converting the data class of 5-12
rgbplot 10-20
right-clicking 1-8
rose 4-18, 4-20
rotating a plot 1-14
rotation
about viewing axis 11-34
without resizing 11-33
Q
S
quiver 4-32, 4-35
saveas 1-10
saving figures 1-10
scaled color mapping 10-17
screen extent, determining 9-4
ScreenSize property 9-4
example 9-5
selecting multiple objects 1-7
selection button 1-7
semilogx, properties changed by 7-50
semilogy, properties changed by 7-50
set 7-18
ShareColors property 9-11
ShowHiddenHandles property 7-44
size of computer screen 9-4
slice planes
colormapping 15-17
slicing a volume 15-14
specular
color 12-15
quiver plots 4-35
2-D 4-35
3-D 4-36
combined with contour plot 4-36
displaying velocity vectors 4-37
quiver3 4-32
R
realism, adding with lighting 12-2
realistic display of objects 11-54
reflection, specular and diffuse 12-12
Renderer property 10-24
and printing 9-17
RendererMode property 10-24
rendering
options 9-15
Z-buffer 9-16
reset 7-38
I-13
Index
exponent 12-14
highlight 12-14
reflection 12-12
SpecularColorReflectance property 12-8
illustration 12-15
SpecularExponent property 12-8
illustration 12-14
curvature mapped to color 10-18
FaceColor, texturemap 10-25
parametric 10-11
plotting 10-6
nonuniformly sampled data 10-9
surfc 4-44
symbols, TeX characters 3-23
SpecularStrength property 12-8
illustration 12-12
sphere 10-25
T
spline 4-49
tag
specifying value of 1-20
TeX
available characters 3-23
creating mathematical symbols 3-23
symbols in text 3-14, 3-24
text
adding to Axes 3-16, 3-23
annotating graphs 3-16
annotations, adding 1-13
editing 1-8, 3-22
for labeling plots 3-16
horizontal and vertical alignment 3-19
multiline 3-25
placing dynamically, example 3-21
placing outside of axes 8-7
positioning 3-19
TeX characters 3-24
using variables in 3-25
texture mapping 10-25
thin line styles 6-57
three-dimensional objects, creating with patch
14-2
tick marks, on axes 2-21, 8-12
TIFF 5-2
title
adding to a graph 3-3
stairs 4-23, 4-30
stairstep plot 4-30
starting plot edit mode 1-7
starting points for stream plots 15-26
statistics
formatting plots of 3-32
plotting 3-29, 3-32
saving to workspace 3-34
stem 4-23
stem plots 4-23
3-D 4-27
overlaid with line plot 4-26
stem3 4-23, 4-27
stream line plots 15-30
stream plots
starting points 15-26
stretch-to-fill 11-41
overriding 11-49
string variable, in text 3-25
style property of lights 12-4
subplot 2-26
sum 5-13
surf 10-6
Surfaces
CData 10-25
coloring 10-14
I-14
Index
toolbar
buttons 1-13, 1-14, 3-16, 3-28
toolbar, camera 11-9
truecolor
dithering on indexed systems 9-12
patches 14-19
rendering method used for 10-24
simulating 10-24
surface plots 10-14, 10-22
U
Uicontrol graphics objects 7-5
Uimenu graphics objects 7-6
uint16 arrays
operations supported on 5-13
storing images 5-5
uint16 arrays
converting uint16 to double 5-11, 5-12
uint8 arrays 5-11
operations supported on 5-13
storing images 5-5
uint8 arrays
converting to double 5-12
converting uint8 to double 5-11
units
axes 8-6
used by figures 9-4
unlocking axes position 1-8
unselecting objects 1-8
V
vectors
determined by direction cosines 11-34
displaying velocity 4-37
velocity vectors displayed with quiver 4-37
vertex normals and back face lighting 12-16
VertexNormals property 12-9
VerticalAlignment property 3-19
Vertices property 14-7
view
azimuth of viewpoint 11-4
camera properties 11-30
coordinate system defining 11-4
definition of 11-2
elevation of viewpoint 11-4
limitation of azimuth and elevation 11-7
MATLAB’s default behavior 11-31
projection types 11-36
rotating 1-14
specifying 11-30
specifying with azimuth and elevation 11-4
view 11-4
example of rotation 11-33
limitations using 11-7
viewing axis 11-8
moving camera along 11-32
viewpoint, controlling 11-4, ??–11-7
visibility of graphics objects 7-46
visualizing
commands for volume data 15-5
mathematical functions 10-7
steps for volume data 15-4
techniques for volume data 15-3
volume data
accessing subregions 15-28
examples of 15-3
MRI 15-8
scalar 15-7
slicing with plane 15-14
steps to visualize 15-4
techniques for visualizing 15-3
vector 15-25
I-15
Index
visualizing 15-3
W
wire frame surface 10-6, 10-13
X
XWD 5-2
Z
Z-buffer 9-16
orthographic projection 11-38
perspective projection 11-38
printing 9-17
rendering truecolor 10-24
zooming by setting camera angle 11-33
I-16
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