mlreportgen.report.Figure class

Package: 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

example

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.

Note

The figure must remain open until the Figure reporter is added to a 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. Enclose each property name in single or double quotes.

Properties

expand all

Figure image, specified as an object of the mlreportgen.report.FormalImage reporter class. The reporter uses gcf to obtain the current MATLAB figure. It uses the formal image reporter to insert the figure into a report. To specify the size of the snapshot or the caption, use the properties of the FormalImage object.

Note

The figure reporter initializes the Snapshot property. Do not reset this property.

Figure source, specified as a:

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

  • Valid graphics handle

Snapshot image format, specified as a character vector or string scalar. Supported formats are:

  • 'bmp' — Bitmap image.

  • 'gif' — Graphics Interchange format.

  • 'jpg' — JPEG image.

  • 'png' — PNG image.

  • 'emf' — Enhanced metafile, supported only in DOCX output on Windows® platforms.

  • 'svg' — Scalable Vector Graphics.

  • 'tif' — Tag Image File format, not supported in HTML output.

  • 'pdf' — PDF image (supported only in PDF output).

See Compatibility Considerations.

Scaling options for the figure snapshot image, specified as a character vector or string scalar. Scaling controls the size of the figure snapshot image in the image file. Supported scaling options are:

  • 'auto' — For PDF or Word (DOCX) output, scales the figure snapshot image to fit the current page layout while maintaining its aspect ratio. First, the figure snapshot image is scaled to the page width. If the image height exceeds the page height, the image is scaled 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' — Scales the figure snapshot image based on the values of the Height and Width properties.

    When you set Scaling to custom and have large values for the Height and Width properties, a java.lang.OutOfMemoryError can occur during PDF generation. To avoid this error and ensure that the figure fits on the page, use smaller Height and Width values.

  • 'none' — No sizing is performed

Note

The 'auto' and 'custom' options use the MATLAB print command to resize the figure. If the figure is too large to fit legibly in the specified space, the print command crops the snapshot image. To avoid cropping, you can specify 'none' as the value of the Scaling option and use the reporter specified by the Snapshot property to size the figure image. This reporter reduces the size of the text with the rest of the image and a user might need to zoom the image in a viewer to discern fine detail. See Resize Figure Snapshot Image.

Height of 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. Valid abbreviations are:

  • px — pixels (default)

  • cm — centimeters

  • in — inches

  • mm — millimeters

  • pc — picas

  • pt — points

Example: '2in'

Width of 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. Valid abbreviations are:

  • px — pixels (default)

  • cm — centimeters

  • in — inches

  • mm — millimeters

  • pc — picas

  • pt — points

Example: '3in'

Preserve the figure background color in the snapshot, specified as true or false. If PreserveBackgroundColor is true, the background color of the snapshot is the same as the background color of the figure. If PreserveBackgroundColor is false, the background color of the snapshot is white.

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

  • 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 this reporter is appended. 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.

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 source (TemplateSrc) for this reporter.

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 is converted to a LinkTarget object. The link target immediately precedes the content of this reporter in the output report.

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:

Compatibility Considerations

expand all

Behavior changed in R2019b

See Also

| | | |

Topics

Introduced in R2017b

MATLAB Report Generator Documentation

Support