mlreportgen.report.Figure class

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

Class Attributes

HandleCompatible
true

For information on class attributes, see Class Attributes (MATLAB).

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.

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 1" spacing. Scaling does not apply to HTML output.

  • 'custom' — Scales the figure snapshot image based on the values of the Height and Width properties.

Note

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.

Height of snapshot image for custom scaling, specified as a character vector or string scalar. This property applies only if Scaling is set to 'custom'.

The Height format is valueUnits, where Units is an abbreviation for the height units and value is the number of units. The table shows the valid Units abbreviations.

UnitsUnits Abbreviation
pixelspx
centimeterscm
inchesin
millimetersmm
picaspc
pointspt

Example: '3in'

Width of snapshot image for custom scaling, specified as a character vector or string scalar. This property applies only if Scaling is set to custom.

The Width format is valueUnits, where Units is an abbreviation for the units of the width and value is the number of units. See the Height property for a table of valid Units abbreviations.

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 is in the template library of the template source (TemplateSrc) for this reporter.

Hyperlink target for this reporter, specified as a string or character array that specifies the link target ID, or an mlreportgen.dom.LinkTarget object. A string or character array value is converted to a LinkTarget object. The link target object immediately precedes the content of this reporter in the output report.

Methods

expand all

Examples

collapse all

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 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);

Compatibility Considerations

expand all

Behavior changed in R2019b

Introduced in R2017b