slreportgen.report.Diagram Class

Namespace: slreportgen.report
Superclasses: slreportgen.report.Reporter

Create diagram reporter

Description

Create a diagram reporter, including a diagram snapshot and caption, for a Simulink^® or Stateflow^® diagram.

Note

To use a Diagram reporter in a report, you must create the report using the slreportgen.report.Report class.

The slreportgen.report.Diagram class is a handle class.

Creation

Description

diagram = Diagram() creates an empty diagram reporter. Set its properties to capture a Simulink or Stateflow diagram.

diagram = Diagram(source) creates a diagram reporter for the Simulink or Stateflow diagram specified by source. Adding this reporter to a report creates a snapshot of the diagram. Then, the snapshot displays in the report as an image with a caption. 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 then, the image is deleted from the temporary folder. To prevent the snapshot image file from being deleted, use the Debug property of the report. See slreportgen.report.Report

diagram = Diagram(Name=Value) sets properties using name-value pairs. You can specify multiple name-value pair arguments in any order.

Input Arguments

source — Diagram snapshot image source

string | character vector

See the Source property.

Properties

Source — Diagram snapshot image source

string scalar | character vector | handle | slreportgen.finder.DiagramResult | ...

Diagram snapshot image source, specified as one of these values.

• Name of an open or loaded Simulink model

• Path of a Simulink subsystem block that contains the Simulink diagram or Stateflow chart

• slreportgen.finder.DiagramResult object

• Handle to a subsystem block containing a Simulink diagram or Stateflow chart

• Stateflow.Chart or Stateflow subchart object. Subcharts are graphical objects that can contain the same objects as a top-level chart, including other subcharts. Subcharts are commonly specified by a Stateflow.State, Stateflow.Function, or Stateflow.Box object.

Attributes:

NonCopyable

true

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.

SnapshotArea — Diagram area to capture in snapshot

[] (default) | 1-by-4 array of doubles

Diagram area to capture in the snapshot, specified as a 1-by-4 array of doubles. The first two values of the array are the x and y coordinates, in pixels, of the top left corner of the diagram area in the Simulink Editor coordinate space. The last two values are the width and height, in pixels. An empty array specifies the entire diagram.

You can set up the view that you want to capture in the Simulink Editor and then set the SnapshotArea property to the output of the slreportgen.utils.getCurrentEditorView function. For an example, see Take Snapshot of Part of a Diagram.

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

HyperlinkDiagram — Hyperlinks of diagram elements

true (default) | false

Choice to include a hyperlink of each diagram element, specified as a logical. If this property is true, each element becomes a hyperlink to an object in the report that describes it. This property applies only to PDF and HTML reports. Hyperlinks allow you to navigate the report using Simulink and Stateflow charts.

The Diagram, SimulinkObjectProperties, and StateflowObjectProperties reporters work together to enable navigation using hyperlinks. Each reporter prefaces the report object it creates with a hyperlink target. The ID of that target is based on the path of the reported element in the model. The Diagram reporter also overlays elements of a diagram snapshot with hyperlinks to the corresponding element-based target ID. The report object to which a diagram element links depends on the element type.

• A diagram-based block (subsystem, chart, model) links to the diagram of the block.

• Other blocks link to textual block descriptions, typically block property tables.

• Masked subsystem blocks that have mask parameters link to the textual description of the block, such as the mask parameter tables. This linking to the textual descriptions is true only if the MaskedSystemLinkPolicy property of the Diagram reporter is set to 'block' or 'default'. Otherwise, the masked system block links to its diagram.

• Masked subsystem blocks that do not have mask parameters link to the diagram of the block.

To customize diagram-based navigation, create custom link targets based on target IDs generated by the slreportgen.utils.getObjectID utility function.

MaskedSystemLinkPolicy — Policy for masked system blocks hyperlinks targets

character vector | string

Policy to determine the targets for the hyperlinks of masked system blocks, specified as one of these values.

• 'default' — Masked system blocks that have parameters link to textual descriptions, such as mask parameter tables. Masked system blocks that do not have parameters link to the corresponding block diagram in the report.

• 'system' — Masked system blocks link to their block diagram in the report.

• 'block' — Masked system blocks link to their textual description, such as a table of masked parameters or subsystem parameters.

Scaling — Scaling options for snapshot image

"auto" (default) | "custom" | "zoom"

Scaling options for the snapshot image, specified as "auto", "custom", or "zoom". 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.

• "zoom" — Enlarges or reduces the element image size to the percent value specified by the Zoom property. To specify the maximum image height and maximum image width, use the MaxHeight and MaxWidth properties, respectively.

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 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 — 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

Zoom — Amount to zoom snapshot image

"100%" (default) | character vector | string scalar

Amount to zoom the snapshot image, specified as a string. The Zoom format is "value%", where value is the percentage by which the snapshot image is enlarged or reduced.

Example: "100%"

Data Types: char | string

MaxHeight — Maximum height for zoom scaling

character vector | string scalar

Maximum height for zoom scaling, specified as a string. This property applies only if Scaling is set to "zoom".

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

Example: "5in"

Data Types: char | string

MaxWidth — Maximum width for zoom scaling

character vector | string scalar

Maximum width for zoom scaling, specified as a string. This property applies only if Scaling is set to "zoom".

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

Example: "5in"

Data Types: char | string

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

slreportgen.report.Diagram.createTemplate	Create diagram template
slreportgen.report.Diagram.customizeReporter	Create custom diagram reporter class
slreportgen.report.Diagram.getClassFolder	Diagram class definition file location
getSnapshotImage	Diagram snapshot image file location
copy	Create copy of a Simulink reporter object and make deep copies of certain property values
getImpl	Get implementation of reporter

Examples

Add Top Level of Model Diagram

Add a snapshot of the top level of the vdp model to a report.

load_system("vdp")
import slreportgen.report.*
import mlreportgen.report.*
rpt = slreportgen.report.Report("output","pdf");
 
chapter = Chapter();
chapter.Title = "Diagram Reporter Example";
 
diagram = Diagram("vdp");
diagram.Snapshot.Caption = "The van der Pol Equation";
diagram.SnapshotFormat = "svg";
diagram.Snapshot.Height = "4in";

add(chapter,diagram);
add(rpt,chapter);
rptview(rpt);

Add Hyperlinked Diagram to a Report

Create a PDF report and add diagram snapshots of the root system and a subsystem from the sf_car model to it. Add a hyperlink to the transmission subsystem and add a paragraph as the target for that link.

import mlreportgen.report.*
import slreportgen.report.*
import slreportgen.utils.*
import mlreportgen.dom.*
rpt = slreportgen.report.Report("output","pdf");
chapter = Chapter("sf_car");

load_system("sf_car");
diag1 = Diagram("sf_car");
diag1.Snapshot.Caption = "Root System: sf_car";
add(chapter,diag1);
add(chapter,PageBreak);

diag2 = Diagram("sf_car/Engine");
diag2.Snapshot.Caption = "Subsystem: sf_car/Engine";
add(chapter,diag2);
add(chapter, PageBreak);

para = Paragraph("Custom target for sf_car/transmission");
id = getObjectID("sf_car/transmission");
append(para,mlreportgen.dom.LinkTarget(id));
add(chapter,para);
add(chapter,PageBreak);

add(rpt,chapter);
close(rpt);
rptview(rpt);

Take Snapshot of Part of a Diagram

Use the SnapshotArea property to specify the area of the diagram to capture in the snapshot. This example sets up the view in the Simulink Editor and then sets the SnapshotArea property to that view by calling slreportgen.utils.getCurrentEditorView.

Open the model.

openExample('f14')

In the Simulink Editor, display the part of the diagram that you want to capture in the snapshot. Get the current Simulink Editor view area by calling slreportgen.utils.getCurrentEditorView.

editorViewArea = getCurrentEditorView();

Create the report and diagram reporter. Set the diagram snapshot area to the current editor viewing area. Add the diagram reporter to the report.

import slreportgen.report.*
import Slreportgen.utils.*
rpt = Report('output','pdf');

diag = Diagram('f14');
diag.SnapshotArea = editorViewArea;
add(rpt, diag);

close(rpt);
rptview(rpt);

Version History

Introduced in R2017b

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