mlreportgen.report.Figure Class
Namespace: mlreportgen.report
Superclasses: mlreportgen.report.Reporter
Figure reporter
Description
Create a figure reporter with a title, figure, and caption.
The mlreportgen.report.Figure
class is a handle
class.
Creation
Description
fig = mlreportgen.report.Figure
creates a
reporter that makes a snapshot of the figure currently open in MATLAB® and adds it to a report. Use the figure properties to add a caption or
change the figure size. The snapshot image is stored in the temporary folder of the
report. When the report is closed, the snapshot image is copied into the report and the
image is deleted from the temporary folder. To prevent the snapshot image files from being
deleted, use the Debug
property of the report. See mlreportgen.report.Report
.
fig = mlreportgen.report.Figure(source)
creates a
reporter that adds the figure specified by source
and sets the
Source
property to source
.
fig = mlreportgen.report.Figure(Name=Value)
sets
properties using name-value pairs. You can specify multiple name-value pair arguments in
any order.
Properties
Source
— Figure source
character vector | string scalar | graphics handle
Figure source, specified as a:
Character vector or string scalar that indicates the path to a valid figure file
Valid graphics handle
Snapshot
— Snapshot reporter
mlreportgen.report.FormalImage
object
Snapshot reporter, specified as an mlreportgen.report.FormalImage
object. Use the properties of the
FormalImage
object to specify the caption for the snapshot image
or to further customize the size of the image.
Note
The reporter initializes the Snapshot
property. Do not reset
this property.
SnapshotFormat
— Snapshot image format
"svg"
(default) | "emf"
| "gif"
| "jpg"
| "pdf"
| "png"
| "tif"
Snapshot image format, specified as "svg"
, "emf"
, "gif"
,
"jpg"
, "pdf"
, "png"
, or
"tif"
. The table lists which image formats are supported for
which report types.
Image Format | File Extension | Supported in HTML | Supported in Word | Supported in PDF |
---|---|---|---|---|
Windows® metafile | .emf | No | Yes | No |
Graphics Interchange Format | .gif | Yes | Yes | Yes |
JPEG image | .jpg | Yes | Yes | Yes |
.pdf | No | No | Yes | |
Portable Network Graphics | .png | Yes | Yes | Yes |
Scalable Vector Graphics | .svg | Yes | Yes | Yes |
TIFF image | .tif | No | Yes | Yes |
Data Types: char
| string
Scaling
— Scaling options for snapshot image
"auto"
(default) | "custom"
| "none"
Scaling options for the snapshot image, specified as "auto"
,
"custom"
, or "none"
. This property controls
the size of the snapshot image in the image file. Supported scaling options are:
"auto"
— For PDF or Word (DOCX) output, use this option to scale the snapshot image to fit the current page layout while maintaining its aspect ratio. First, the reporter scales the snapshot image to the page width. If the image height exceeds the page height, the reporter scales the image down again. This additional scaling ensures that the image fits the current page with an extra one inch spacing. Scaling does not apply to HTML output."custom"
— Use this option to scale the snapshot image based on the values of theHeight
andWidth
properties."none"
— Do not perform scaling
For a PDF image, the size limit is 10000px for width and height. For all other image types, the size limit is the screen size.
Note
The "auto"
and "custom"
options use the MATLAB
print
command to resize the figure. If the figure is too large to fit
in the specified space, the print
command crops the snapshot image. To
avoid cropping, set the Scaling property to "none" and use the reporter specified by the
Snapshot
property to size the image. Because the reporter reduces
the size of the text with the rest of the image, fine details may not be legible unless you
zoom the image. See Resize Figure Snapshot Image.
Note
A java.lang.OutOfMemoryError
can occur when the
Scaling
is set to "custom"
, and
Height
and Width
properties are set to large
values. To avoid or solve this error, use smaller Height
and
Width
property values.
Data Types: char
| string
Height
— Height of snapshot image
"6in"
(default) | character vector | string scalar
Height of the snapshot image, specified as a character vector or string scalar that
consists of a number followed by an abbreviation for a unit of measurement. For example,
"2in"
specifies two inches. The default snapshot is 6 inches.
Valid abbreviations are:
"px"
— pixels"cm"
— centimeters"in"
— inches"mm"
— millimeters"pc"
— picas"pt"
— points
For PDF images, the height limit is 10000 pixels. For all other image types, the height limit is the screen height.
Example: "2in"
Data Types: char
| string
Width
— Width of snapshot image
"6.5in"
(default) | character vector | string scalar
Width of the snapshot image, specified as a character vector or string scalar that
consists of a number followed by an abbreviation for a unit of measurement. For example,
"2in"
specifies two inches. The default snapshot width is 6.5
inches. Valid abbreviations are:
"px"
— pixels"cm"
— centimeters"in"
— inches"mm"
— millimeters"pc"
— picas"pt"
— points
For PDF images, the width limit is 10000 pixels. For all other image types, the width limit is the screen width.
Example: "2in"
Data Types: char
| string
PreserveBackgroundColor
— Whether to preserve background color
false
or 0
(default) | true
or 1
Whether to preserve background color in the snapshot, specified as a numeric or
logical 1 (true
) or 0 (false
). If
PreserveBackgroundColor
is true
, the
background color of the snapshot is the same as the background color of the snapshot
source. If PreserveBackgroundColor
is false
, the
background color of the snapshot is white.
Data Types: logical
TemplateSrc
— Source of template for this reporter
character vector | string scalar | reporter or report | DOM document or document part
Source of the template for this reporter, specified in one of these ways:
Character vector or string scalar that specifies the path of the file that contains the template for this reporter
Reporter or report whose template is used for this reporter or whose template library contains the template for this reporter
Document Object Model (DOM) document or document part whose template is used for this reporter or whose template library contains the template for this reporter
The specified template must be the same type as the report to which you
append this reporter. For example, for a Microsoft® Word report, TemplateSrc
must be a Word reporter template.
If the TemplateSrc
property is empty, this reporter uses the
default reporter template for the output type of the report.
TemplateName
— Name of template for this reporter
character vector | string scalar
Name of the template for this reporter, specified as a character vector or string scalar.
The template for this reporter must be in the template library of the template specified by
the TemplateSrc
property of this reporter.
Data Types: char
| string
LinkTarget
— Hyperlink target for this reporter
[]
(default) | character vector | string scalar | mlreportgen.dom.LinkTarget
object
Hyperlink target for this reporter, specified as a character vector or string scalar
that specifies the link target ID, or an mlreportgen.dom.LinkTarget
object. A character vector or string scalar
value converts to a LinkTarget
object. The link target immediately
precedes the content of this reporter in the output report.
Methods
Public Methods
getSnapshotImage | Get snapshot image path |
mlreportgen.report.Figure.getClassFolder | Figure class definition file location |
mlreportgen.report.Figure.createTemplate | Create figure template |
mlreportgen.report.Figure.customizeReporter | Create custom figure reporter class |
copy | Create copy of reporter object and make deep copies of certain property values |
getImpl | Get implementation of reporter |
Examples
Add a Figure to a Report
Add a figure of a surface plot to a report and set the figure caption and height.
import mlreportgen.report.* surf(peaks); rpt = Report('peaks'); chapter = Chapter(); chapter.Title = 'Figure Example'; add(rpt,chapter); fig = Figure(); fig.Snapshot.Caption = '3-D shaded surface plot'; fig.Snapshot.Height = '5in'; add(rpt,fig); delete(gcf); rptview(rpt);
Add Multiple Figures to a Report Page
Add two figures to a report. To place them next to each other on the page, use a DOM Table object.
import mlreportgen.report.* import mlreportgen.dom.* rpt = Report('peaks'); surf(peaks(20)); figure = Figure(); peaks20 = Image(getSnapshotImage(figure,rpt)); peaks20.Width = '3in'; peaks20.Height = []; delete(gcf); surf(peaks(40)); figure = Figure(); peaks40 = Image(getSnapshotImage(figure,rpt)); peaks40.Width = '3in'; peaks40.Height = []; delete(gcf); t = Table({peaks20,peaks40;'peaks(20)','peaks(40)'}); add(rpt,t); close(rpt); rptview(rpt);
Resize Figure Snapshot Image
This example generates a PDF report that illustrates the difference between resizing a figure snapshot image using the print
command and resizing using the reporter specified by the Snapshot
property of the Figure
reporter.
Create a wide MATLAB® figure. Create three mlreportgen.report.Figure
reporters from the figure and add them to a report.
The first
Figure
reporter does not resize the figure.The second
Figure
reporter uses theprint
command to resize the figure.The third
Figure
reporter uses theSnapshot
reporter to resize the figure.
import mlreportgen.report.* fig = figure(); ax = axes(fig); plot(ax, rand(1,100)); pos = fig.Position; fig.Position = [pos(1) pos(2) 2*pos(3) pos(4)]; rpt = Report('example','pdf'); add(rpt, "Intrinsic figure size"); figReporter0 = Figure(fig); figReporter0.Scaling = 'none'; add(rpt,figReporter0); add(rpt, "Resized by print command"); figReporter1 = Figure(fig); add(rpt,figReporter1); add(rpt, "Resized by snapshot reporter"); figReporter2 = Figure(fig); figReporter2.Scaling = 'none'; figReporter2.Snapshot.ScaleToFit = true; add(rpt,figReporter2);
close(rpt); delete(fig) rptview(rpt);
Here are the figures in the generated report:
Version History
Introduced in R2017bR2024b: Removal of BMP for image output
Report Generator no longer supports BMP (bitmap) as an output image format. This affects
snapshots, images from files, and watermarks in both the Report Explorer and the Report,
DOM, and PPT APIs. See print
for more information.
R2019b: Default value of SnapshotFormat
is 'svg'
for all report types
Starting in R2019b, Scalable Vector Graphics (SVG) images are supported for Word reports. For
all report types (HTML, PDF, and Word), the default value of the
SnapshotFormat
property is 'svg'
and a value of
'auto'
indicates 'svg'
. In previous releases, the
default value of the SnapshotFormat
property was
'auto'
, which indicated 'svg'
for HTML and PDF
reports and 'emf'
or 'png'
for Word reports, depending
on the platform.
Word reports that contain SVG images require Word 2016 or a later version. In MATLAB R2019b or a later release, to generate a report with images that are
compatible with earlier versions of Word, set the SnapshotFormat
property to a value other than 'svg'
. To specify the image format used by
default in earlier releases of MATLAB, set SnapshotFormat
to:
'emf'
for a Windows platform'png'
for a UNIX® or Mac platform
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)