mlreportgen.report.FormalImage Class

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

Captioned image reporter

Description

Create a reporter for an image with a caption.

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

Creation

Description

image = FormalImage creates an empty image reporter. Use the reporter properties to set the image source, caption, height, width, and so on. The reporter uses a template to format and number the caption and position it relative to the image. To customize the format, you can specify a custom template or override the template programmatically, using the properties of this reporter.

image = FormalImage(source) creates an image reporter that adds the image specified by the source to a report. See the Image property.

image = FormalImage(Name=Value) sets properties using name-value arguments. You can specify multiple name-value arguments in any order.

Input Arguments

source — Source of image

character vector | string scalar | DOM Image object

Source of image to add to report, specified as a string or character vector, or as a DOM Image object. See the Image property.

Properties

Image — Source of image

[] (default) | character vector | string scalar | DOM Image object

Source of image to add to report, specified as a character array, string scalar, or a DOM Image object. If you use a string or character array, specify the system path to the image file.

Supported image formats are:

Import Image Format	Supported in HTML	Supported in Word	Supported in PDF	Supported in PDF/A (since R2025a)
Windows® metafile (.emf)	No	Yes	No	No
Graphics Interchange Format (.gif)	Yes	Yes	Yes	Yes
JPEG image (.jpg)	Yes	Yes	Yes	No
PDF (.pdf)	No	No	Yes	No
PDF/A (.pdf)	No	No	Yes	No
Portable Network Graphics (.png)	Yes	Yes	Yes	Yes
Scalable Vector Graphics (.svg)	Yes	Yes	Yes	Yes
TIFF image (.tif)	No	Yes	Yes	Yes

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.

This reporter inserts the specified image in a paragraph whose style is specified by the template of the reporter. The paragraph style determines the alignment and spacing of the image relative to its caption. To customize the alignment and spacing, customize the FormalImage template in the template library for the reporter.

Attributes:

GetAccess	public
SetAccess	public

Caption — Caption of this formal image

[] (default) | character vector | string scalar | ...

Caption of this formal image, specified as one of these values:

• String or character vector

• DOM object

• 1-by-N or N-by-1 array of strings or DOM objects

• 1-by-N or N-by-1 cell array of strings, character vectors, and/or DOM objects

• Hole reporter returned by the getCaptionReporter method

The caption is numbered automatically and positioned under the image.

Inline content is content that a paragraph can contain. If the caption value is inline content, the reporter uses a template stored in its template library to format the caption. The template automatically numbers the caption using a format that depends on whether the image is in a numbered or unnumbered chapter.

• An image in a numbered chapter has a caption text prefix of the form "Figure N.M" where N is the number of the chapter and M is the number of the figure in the chapter. For example, the prefix for the third image in the second chapter of the report is Figure 2.3.

• An image in an unnumbered chapter has a caption text prefix of the form "Figure N" where N is 1 for the first image in the report, 2 for the second image, and so on.

In many non-English locales, the caption prefix is translated to the language and format of the locale. See the Locale property of mlreportgen.report.Report for a list of translated locales.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

Width — Width of this image

[] | character vector | string scalar

Width of this image, specified as character vector or string scalar that contains a number followed by an abbreviation for a unit of measurement. For example, "10px" specifies 10 pixels. Valid abbreviations are:

• px — Pixels

• cm — Centimeters

• in — Inches

• mm — Millimeters

• pc — Picas

• pt — Points

• % — Percent

If you set the image width, but not the height, the height is scaled to preserve the aspect ratio of the image.

Note

This property applies only to a formal image whose source you specify as an image path.

Example: 5in

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

Height — Height of this image

[] | character vector | string scalar

Height of this image, specified as character vector or string scalar that contains a number followed by an abbreviation for a unit of measurement. For example, "10px" specifies 10 pixels. Valid abbreviations are:

• px — Pixels

• cm — Centimeters

• in — Inches

• mm — Millimeters

• pc — Picas

• pt — Points

• % — Percent

If you set the image height, but not the width, the width is scaled to preserve the aspect ratio of the image.

Note

This property applies only to a formal image whose source you specify as an image path.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

ScaleToFit — Scale image

true (default) | false

Whether to scale this formal image, specified as a logical value. This property specifies whether to scale the image to fit between the margins of a Microsoft^® Word or PDF page or a table entry.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

Map — Map of hyperlink areas in image

[] (default) | mlreportgen.dom.ImageMap object

Map of hyperlink areas in this image, specified as an mlreportgen.dom.ImageMap object. The Map property applies to only HTML and PDF reports.

See Create Image Maps.

Attributes:

GetAccess	public
SetAccess	public

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

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.

Attributes:

GetAccess	public
SetAccess	public

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.

Attributes:

GetAccess	public
SetAccess	public

Methods

Public Methods

Method	Purpose
getImageReporter	Get formal image reporter
getCaptionReporter	Get image caption reporter
mlreportgen.report.FormalImage.createTemplate	template = mlreportgen.report.FormalImage.createTemplate(path,type) Create reporter template Input Arguments path, Target path and file name for template file type, Template type, specified as "html", "docx", or "pdf" Return Values template — Path and file name of the template copy, returned as a string scalar. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.createTemplate.
mlreportgen.report.FormalImage.customizeReporter	reporter = mlreportgen.report.FormalImage.customizeReporter(classpath) Create reporter derived from mlreportgen.report.FormalImage class Return Values reporter — Path and file name of the new reporter class, returned as a string scalar. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.customizeReporter.
mlreportgen.report.FormalImage.getClassFolder	path = mlreportgen.report.FormalImage.getClassFolder Get location of folder that contains mlreportgen.report.FormalImage class definition file Return Values path — Class definition file location, returned as a character vector. For more information, see the equivalent method for the Reporter class, mlreportgen.report.Reporter.getClassFolder.
copy	Create copy of reporter object and make deep copies of certain property values
getImpl	Get implementation of reporter

Examples

Add an Image to a Report

Add an empty image reporter to a report and then, set its source, caption, and height.

import mlreportgen.report.*
rpt = mlreportgen.report.Report('output','pdf');
chapter = mlreportgen.report.Chapter();
chapter.Title = 'Formal Image Reporter Example';

image = mlreportgen.report.FormalImage();
image.Image = which('ngc6543a.jpg');
image.Caption = 'Cat''s Eye Nebula or NGC 6543';
image.Height = '5in';

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

Change Image Caption Color

Add an image to a report. Use default formatting, but change the text color of the caption to red.

import mlreportgen.report.*
import mlreportgen.dom.*

rpt = Report('output','pdf');
chapter = Chapter();
chapter.Title = 'Formal Image Reporter Example';

image = FormalImage();
image.Image = which('ngc6543a.jpg');
text = Text('Cat''s Eye Nebula or NGC 6543');
text.Color = 'red';
image.Caption = text;

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

Change Image and Caption Formatting

Add an image to a report and override its alignment, caption font, and margins.

import mlreportgen.report.*
import mlreportgen.dom.*

rpt = Report('output','pdf');
chapter = Chapter();
chapter.Title = 'Formal Image Reporter Example';

image = FormalImage();
image.Image = which('ngc6543a.jpg');
image.Height = '5in';

para = Paragraph('System Design Description');
para.Style = {HAlign('left'),FontFamily('Arial'),...
     FontSize('12pt'),Color('white'),...
     BackgroundColor('blue'), ...
     OuterMargin('0in', '0in','.5in','1in')};
image.Caption = para;

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

Create an Image Map

Create an image map with a defined image area in the upper left and add that image to the report. If you click in the image area, it displays the web page associated with that area.

import mlreportgen.report.*;
rpt = Report('test','pdf');

image = FormalImage(which('ngc6543a.jpg'));
area = mlreportgen.dom.ImageArea('https://www.google.com',...
     'Google',0,0,100,100);
map = mlreportgen.dom.ImageMap;
append(map,area);
image.Map = map;

add(rpt,image);
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.