mlreportgen.report.FormalImage class

Package: mlreportgen.report

Captioned image reporter

Description

Create a reporter for an image with a caption.

Construction

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

string | character array | DOM Image object

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

Properties

Image — Source of image

[] | string | character array | DOM Image object

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

Supported image 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)

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

[] | string | character array | ...

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

• String or character array

• 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 arrays, 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

[] | string | character array

Width of this image, specified as a string or character array. 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. The table shows the valid Units abbreviations.

Units	Units Abbreviation
pixels	px
centimeters	cm
inches	in
millimeters	mm
picas	pc
points	pt
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

[] | string | character array

Height of this image, specified as a string or character array. 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

[] | mlreportgen.dom.ImageMap object

Map of hyperlink areas in this formal image, specified as an mlreportgen.dom.ImageMap object. This property applies only to HTML and PDF reports. Use mlreportgen.dom.ImageArea to define the image areas and then, add them to the map. Image areas are areas in the image that contain hyperlinks to open content in a browser or navigate to another location on the same page.

TemplateSrc — Source of template for this reporter

[] (default) | 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

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

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

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

Methods

createTemplate	Create formal image template
customizeReporter	Create custom formal image reporter class
getCaptionReporter	Get image caption reporter
getClassFolder	Formal image class definition file location
getImageReporter	Get formal image reporter

Inherited Methods

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