Main Content

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

example

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.

example

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

expand all

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

expand all

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

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

Source of the template for this reporter, specified as one of these options:

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

Hyperlink target for this reporter, specified as a character vector or string scalar that specifies the link target ID or as 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

expand all

Examples

collapse all

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

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

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