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 pairs. You can specify multiple name-value pair 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:

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

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.

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.

Width — Width of this image

[] | character vector | string scalar

Width of this image, specified as a character vector or string scalar. This property applies only to a formal image whose source you specify as an image path.

The Width format is valueUnits, where Units is an abbreviation for the width units and value is the number of units. 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.

Example: 5in

Height — Height of this image

[] | character vector | string scalar

Height of this image, specified as a character vector or string scalar. This property applies only to a formal image whose source you specify as an image path.

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

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

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.

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.

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

mlreportgen.report.FormalImage.createTemplate	Create formal image template
mlreportgen.report.FormalImage.customizeReporter	Create custom formal image reporter class
mlreportgen.report.FormalImage.getClassFolder	Formal image class definition file location
getCaptionReporter	Get image caption reporter
getImageReporter	Get formal image reporter
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.