mlreportgen.report.Figure Class

Namespace: mlreportgen.report
Superclasses: mlreportgen.report.Reporter

Figure reporter

expand all in page

Description

Create a figure reporter with a title, figure, and caption.

The mlreportgen.report.Figure class is a handle class.

Class Attributes

HandleCompatible
true

For information on class attributes, see Class Attributes.

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.

example

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 arguments. You can specify multiple name-value arguments in any order.

Properties

expand all

Figure source, specified as a:

  • Character vector or string scalar that indicates the path to a valid figure file

  • Valid graphics handle

Attributes:

GetAccess
public
SetAccess
public

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.

Attributes:

GetAccess
public
SetAccess
public

Snapshot image format, specified as one of these formats:

Import Image FormatSupported in HTMLSupported in WordSupported in PDF

Supported in PDF/A (since R2025a)

Windows® metafile (.emf)NoYesNoNo
Graphics Interchange Format (.gif)YesYesYesYes
JPEG image (.jpg)YesYesYesNo
PDF (.pdf)NoNoYesNo
PDF/A (.pdf)NoNoYesNo
Portable Network Graphics (.png)YesYesYesYes
Scalable Vector Graphics (.svg)YesYesYesYes
TIFF image (.tif)NoYesYesYes

Note

Unlike the PDF report output format, the PDF/A format does not support including PDF or PDF/A images. Use one of the image formats listed in the table to include an image in a PDF/A report.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

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 the Height and Width properties.

  • "none" — Do not perform scaling

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 either of these combinations of property settings occur:

  • Scaling set to "zoom", and Zoom, MaxHeight, and MaxWidth properties set to large values

  • Scaling set to "custom", and Height and Width properties set to large values

To avoid this error, for zoom Scaling, use smaller Zoom, MaxHeight, and MaxWidth property values. For Scaling is set to "custom", use smaller Height and Width property values.

Data Types: char | string

Height of the snapshot image, specified as a character vector or string scalar that contains 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

Note

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.

Example: "2in"

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

Width of the snapshot image, specified as a character vector or string scalar that contains 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

Note

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.

Example: "2in"

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

Whether to preserve background color in the snapshot, specified as a numeric or logical 1 (true) or 0 (false).

  • true — the background color of the snapshot is the same as the background color of the snapshot source and the Theme property is ignored.

  • false — the background color of the snapshot follows the settings of the Theme property.

Attributes:

GetAccess
public
SetAccess
public

Data Types: logical

Since R2025a

Graphics theme to use when printing the snapshot, specified as:

  • "light" — prints the figure with a white background and dark-colored graph lines and text.

  • "dark" — prints the figure with a dark-colored background and light-colored graph lines and text.

If you manually set any graphics colors, the snapshot preserves those colors, with the exception of the figure and axes background colors, regardless of theme setting. When PreserveBackgroundColor is true, this property is ignored.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

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 this reporter uses or whose template library contains the template for this reporter

  • Document Object Model (DOM) document or document part whose template this reporter uses 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.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

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.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

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.

Attributes:

GetAccess
public
SetAccess
public

Methods

expand all

Examples

collapse all

Open Live Script

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);
Open Live Script

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);
Open Live Script

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 the print command to resize the figure.

  • The third Figure reporter uses the Snapshot 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:

Limitations

  • The Figure reporter cannot take snapshots when you generate the report on a server that does not have a monitor.

Tips

  • A report generator calculates the width and height of a figure snapshot based on the value of the Scaling property. Legends are floating elements that are not tightly bound to axes or figure content. When you adjust the dimensions of a figure by using the Scaling value, the position of the legend in the report may shift compared to the position in the figure window.

Version History

Introduced in R2017b

expand all

See Also

| | | |

Topics