matlab-generate-report

MATLAB レポート生成

MATLAB のデータや Simulink モデルから、構造化されたプロフェッショナルなレポート（PDF、Word、HTML）を生成します。

使用する場面

• MATLAB のデータから PDF、Word、HTML レポートを作成する
• 章、タイトルページ、目次を含むレポートを作成する
• 文書に自動採番される図や表を追加する
• 複数ページの HTML レポート（ナビゲーション付きの個別 HTML ファイル）を作成する
• ブロック線図、I/O テーブル、実行順序を含めて Simulink モデルを文書化する
• レポートテンプレート（スタイル、色、フォント、ヘッダー、フッター）をカスタマイズする
• テンプレートの差し込み箇所と動的コンテンツを備えたカスタムレポータークラスを作成する
• 共通の企業スタイルを適用した複数レポーターのパッケージを作成する
• ヘッダーの色が異なるテーブルバリアントレポーターを作成する
• レポートに HTML コンテンツを含める

使用しない場面

• シンプルなファイルエクスポート（CSV、Excel）— writetable、writematrix を使用します
• レポートとしてのライブスクリプト — MATLAB Live Editor のエクスポートを使用します
• 対話的なレポート作成 — Report Explorer GUI を使用します
• Simulink モデルの Web ビュー — slreportgen.webview.* を直接使用します

API の選択

基盤として常に Report API（mlreportgen.report.*）を使用してください。レポートのコンテナである Report と、レポーター（Figure、BaseTable、FormalImage、Chapter、TitlePage など）が提供され、自動採番、キャプション、文書構造を処理します。

両方の API を併用します。 Report API でレポートを作成し、対応するレポーターがあるコンテンツを追加します。スタイル付き段落、カスタムテーブル、インライン書式、HTML の取り込み、キャプションのない画像には DOM API（mlreportgen.dom.*）を使用します。DOM オブジェクトは、レポーターと並べて Report、Chapter、または Section に直接追加できます。

重要なルール： Report API のレポーター（Figure、BaseTable、FormalImage）を追加できるのは、Report、Chapter、または Section オブジェクトのみです。TableEntry のような DOM オブジェクトには追加できません。TableEntry の内部では DOM オブジェクトを使用してください。

Simulink レポート： SystemIO、ExecutionOrder、その他の Simulink レポーターに必要なモデルコンパイルのサポートが拡張された、slreportgen.report.Report（mlreportgen.report.Report ではありません）を使用します。

複数ページの HTML： "html-multipage" タイプと HTMLPage オブジェクトを組み合わせて、mlreportgen.dom.Document を使用します。DOM の Document を Report API の Report の代わりに使用するのは、この場合のみです。

基本的なワークフロー：標準レポート

TitlePage、TableOfContents、ListOfFigures、ListOfTables は任意です。必要な場合にのみ含めてください。最小限のレポートは、Report とコンテンツ、そして close だけで構成されます。

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

rpt = Report("MyReport","pdf");
append(rpt,TitlePage(Title="Report Title",Author="Team"));  % optional
append(rpt,TableOfContents());   % optional
append(rpt,ListOfFigures());     % optional
append(rpt,ListOfTables());      % optional

ch = Chapter("Results");
append(ch,Paragraph("Analysis complete."));

% Auto-numbered table
data = FormalTable(["ID","Value"],[1 10; 2 20]);
bt = BaseTable(data);
bt.Title = "Measured values";
append(ch,bt);

% Auto-numbered figure
fig = figure("Visible","off");
plot([1 2],[10 20]);
rptFig = Figure(fig);
rptFig.Snapshot.Caption = "Value trend";
append(ch,rptFig);
close(fig);

append(rpt,ch);
close(rpt);
rptview(rpt);

基本的なワークフロー：Simulink レポート

load_system(modelName);

% MUST use slreportgen.report.Report for Simulink content
rpt = slreportgen.report.Report(outputPath,"pdf");
append(rpt,mlreportgen.report.TitlePage("Title","Model Report"));
append(rpt,mlreportgen.report.TableOfContents());

ch = mlreportgen.report.Chapter("Diagrams");

% Root diagram — direct reporter
rootDiag = slreportgen.report.Diagram(modelName);
rootDiag.Snapshot.ScaleToFit = true;
append(ch,rootDiag);

% Subsystems — finder pattern (iterator for memory efficiency)
finder = slreportgen.finder.SystemDiagramFinder(modelName);
finder.IncludeRoot = false;
finder.SortType = "alphabetical";

while finder.hasNext()
    result = finder.next();
    sec = mlreportgen.report.Section("Title",result.Name);
    append(sec,result);
    append(ch,sec);
end

append(rpt,ch);
close(rpt);
rptview(rpt);

組み込みレポーターとカスタムレポーターの選択

コードを書く前に、要件を組み込みレポーターの機能と照らし合わせて分析します。

1. コンテンツと書式の要件をすべて列挙します — タイトルページのフィールド、ページ枠、ヘッダー／フッター、ブランドに合わせたスタイル
2. 組み込みレポーターを確認します。 組み込みの TitlePage には、Title、Subtitle、Author、Publisher、PubDate、Image があります。組み込みの Chapter／Section には、見出し、自動番号付け、Content ホールがあります。
3. 組み込みレポーターがすべての要件を満たす場合は、そのまま使用します
4. 満たされない要件がある場合は、カスタムレポーターを作成します。
   • カスタムレポーターが 1 つの場合 — references/custom-reporters.md を参照してください
   • ビジュアルアイデンティティを共有する複数のレポーターの場合 — references/report-package.md を参照してください

カスタムレポーターが必要となる一般的なケース：

• タイトルページに標準セット以外のフィールド（プロジェクト名、施設、契約番号）が必要
• ページ枠、透かし、カスタムのページレイアウトが必要
• 動的コンテンツ（章ごとの画像、ティッカー）を含むページヘッダー／フッターが必要
• ヘッダーの色が異なるブランド仕様のテーブルを複数用意する必要がある
• MATLAB でロゴを生成する（plot/patch で幾何学図形を描画し、exportgraphics で出力する）

要件を組み込みプロパティに無理に当てはめないでください（例：フィールドを連結して Subtitle に入れる）。代わりにカスタムレポーターを作成してください。

カスタムのタイトルページを、生の DOM 要素で作成しないでください（Paragraph や Image を Chapter に追加するなど）。テンプレートベースのレイアウトとフォーマット間の移植性を確保するため、常に customizeReporter を使用してください。

判断ツリー：参照するドキュメント

必要な作業	参照先
章、図、テーブル、検証を含む標準レポートの作成	references/report-api-patterns.md
DOM テーブル、HTML の挿入、複数ページの HTML、Number/NumberFormat の使用	references/dom-api-patterns.md
テンプレートのファイル形式の理解、テンプレートの検索／確認	references/template-system.md
組み込みテンプレートのホール、スタイル、ページレイアウトの参照（事前計算済み）	references/template-reference.md
カスタムレポータークラスの作成（customizeReporter、ホール、ヘッダー）	references/custom-reporters.md
スタイルを共有する複数レポーターのパッケージと buildTemplates の作成	references/report-package.md
Simulink モデルレポートの生成（ファインダー、向き、中央揃え）	references/simulink-report.md
すべての Simulink ファインダーとレポーターの参照	references/finders-and-reporters.md
構造体配列を反復処理してカスタムレポーターで章を作成	references/data-driven-report-pattern.md
テンプレートのスタイル（色、フォント、ヘッダー、フッター、TOC）の編集	references/template-system.md

主な機能

クラス	用途	パッケージ
Report	最上位のレポートコンテナー	mlreportgen.report
TitlePage	タイトル、サブタイトル、作成者を含むタイトルページ	mlreportgen.report
TableOfContents	自動生成される目次	mlreportgen.report
Chapter / Section	ドキュメントの構成	mlreportgen.report
Figure	MATLAB の図から自動採番される図	mlreportgen.report
FormalImage	キャプション付きのファイルから自動採番される画像	mlreportgen.report
BaseTable	自動採番される表のラッパー（FormalTable を渡します）	mlreportgen.report
FormalTable	セル配列から作成するヘッダー、本文、フッター付きの表	mlreportgen.dom
Template（3 引数）	テンプレートを編集します：Template(out,fmt,src)	mlreportgen.dom
HTMLFile / HTML	任意の出力形式に HTML コンテンツを含めます	mlreportgen.dom
HTMLPage	複数ページの HTML ドキュメント内のページ（R2024a 以降）	mlreportgen.dom
Number	数値の DOM オブジェクト（NumberFormat と併用します）	mlreportgen.dom
TemplateHole	レポート生成時に値が挿入されるプレースホルダー	mlreportgen.dom
Page / NumPages	ページ番号／総ページ数	mlreportgen.dom
*.customizeReporter	カスタムレポーターとテンプレートをひな形から作成します	mlreportgen.report
getStyle / replaceStyle	テンプレートのスタイルを変更します	mlreportgen.dom
slreportgen.report.Report	Simulink コンテンツ用のレポートコンテナー	slreportgen.report
slreportgen.report.Diagram	システムの図のスナップショット	slreportgen.report
slreportgen.finder.SystemDiagramFinder	システム／サブシステムの図を検索します	slreportgen.finder
slreportgen.report.SystemIO	入出力をレポートします（コンパイルが必要です）	slreportgen.report
slreportgen.report.ExecutionOrder	ブロックの実行順序をレポートします	slreportgen.report
slreportgen.report.LookupTable	ルックアップテーブルのデータとプロットをレポートします	slreportgen.report
rptview	レポートを表示します（DOCX フィールドを更新します）	関数
docview	Word ドキュメントを処理します（フィールドの更新、変換）	関数

よくある間違い

間違い	正しい方法
mlreportgen.dom.Document をレポートコンテナーとして使用する	mlreportgen.report.Report を使用します。例外：複数ページの HTML には、"html-multipage" を指定した Document が必要です
Simulink のコンテンツに mlreportgen.report.Report を使用する	モデルのコンパイルに必要な slreportgen.report.Report を使用します
複数ページの出力に "html" を指定して Report を使用する	"html-multipage" を指定した mlreportgen.dom.Document と HTMLPage オブジェクトを使用します
レポーターを DOM オブジェクト（Paragraph、TableEntry）に追加する	レポーターを追加できるのは Report、Chapter、Section のみです。TableEntry 内では DOM オブジェクトを使用します
FormalTable のセルに生の double 値を入れる	Style で Number と NumberFormat を使用します：n = Number(42); n.Style = {NumberFormat("%.0f")}。n をセル配列に直接入れます。references/dom-api-patterns.md § Number and NumberFormat を参照してください
NumberFormat("$%.0f") または NumberFormat("%,.0f")	標準的な sprintf 指定子のみ使用できます（$、%,、%d は使用できません）。通貨や単位を表示するには、Number を Paragraph で囲み、前後に Text を追加します
「default」／「even」のページヘッダーのみをカスタマイズする	すべてのページタイプ（「first」、「default」、「even」）をカスタマイズします。ただし、内容はそれぞれ変えます（下記参照）
先頭ページのヘッダーに StyleRef（章タイトル）を入れる	先頭ページには章見出しがすでに表示されるため、「first」ヘッダーでは StyleRef を省略します。道案内として「default」／「even」でのみ使用します
winopen／open／start で DOCX を開く	rptview(rpt) または docview(file,"updatefields") を使用します。フィールドの更新が実行されます
幅に ColSpec／ColSpecGroup を使用する	Style で Width を指定した TableColSpecGroup と TableColSpec を使用します
ResizeToFitContents(false) を指定せずに幅を設定する	テーブルの Style に ResizeToFitContents(false) を追加し、絶対値の ft.Width（"100%" ではありません）を設定します
TemplateParagraphStyle.Formats = {Bold(true)}	配列を使用します：Formats = [Bold(true),FontSize("12pt")]
既存のテンプレートを編集するために Template(path,"pdf") を使用する	引数 2 つでは空のテンプレートが作成されます。引数 3 つの形式 Template(out,"pdf",src) を使用します
Template コンストラクターでソースと出力に同じパスを指定する	OPC は同時に読み書きできません。異なるパスを使用し、その後 movefile を実行します
rotate() を呼び出さずに PDFPageLayout.PageSize.Orientation を設定する	rotate(pl) を呼び出します。Width／Height が入れ替わり、Orientation も設定されます
Height と Width を明示せずに DOCXPageLayout を使用する	DOCX では自動で入れ替わらないため、両方を明示的に設定します
PDFPageLayout の後にページ番号がリセットされる	番号を継続するには、pl.FirstPageNumber = ''（空文字列）を設定します
レポーターを Paragraph で囲んで中央揃えにする	Template API を使用して、レポーターのテンプレートスタイルをカスタマイズします
PDF の HTML に RawText(html) を使用する	HTMLFile(path) または HTML(string) を使用します。どの形式でも機能します
Table のセル配列で Group を使用する	入れ子のセル配列を使用します：Table({{img,caption},desc})
MATLAB の table() を BaseTable に渡す	FormalTable(headers,body) を渡します。MATLABTable ラッパーを回避できます
e.Style = {BackgroundColor("yellow")}（既存のスタイルを上書きする）	追記します：e.Style = [e.Style, {BackgroundColor("yellow")}]。継承したスタイルを保持できます
フィールドを無理に TitlePage.Subtitle に入れる	customizeReporter を使用して、カスタムのタイトルページレポーターを作成します
カスタムレポータークラスを一から作成する	customizeReporter を使用してひな型を生成します。必要なバイナリテンプレートが作成されます
customizeReporter を実行する前に classdef を記述する	ひな型の生成で classdef ファイルが上書きされます。先にひな型を生成し、その後編集します
パッケージ内で修飾なしの TitlePage.getClassFolder() を使用する	完全修飾名を使用します：mypkg.TitlePage.getClassFolder()
PDF／HTML で getStyle(ss,name,type) を使用する	type 引数を指定すると [] が返されます。type を指定せず getStyle(ss,name) を使用します
垂直方向の間隔に OuterMargin("12pt","6pt","0","0") を使用する	引数は (left,right,top,bottom) の順です。CSS の順序ではありません。上下の間隔には OuterMargin("0","0","12pt","6pt") を使用します
TemplateCharacterStyle を使用する	これは存在しません。PDF／HTML の文字スタイル／インラインスタイルには TemplateTextStyle を使用します
.pdftx／.htmtx／.dotx を解凍し、fileread／regexprep で編集する	必ず DOM Template API を使用します。Template(out,fmt,src) + open + オブジェクトの変更 + close の順に実行します。生の編集ではフレームワークの検証を回避してしまいます
検出に find_system + DiagramFinder を使用する	フィルタープロパティを指定して SystemDiagramFinder を使用します
ChartDiagramFinder の結果に対して Diagram(result.Path) を使用する	getReporter(result) を使用します。チャートのパスは Diagram コンストラクターでは無効です
find() と for ループをファインダーに使用する	必ずイテレーターを使用します：while finder.hasNext() / result = finder.next()
BlockFinder に SearchDepth=inf を指定して、参照先モデルも検索されることを期待する	BlockFinder は Model References をたどりません。SystemDiagramFinder（IncludeReferencedModels=true）と、システムごとの BlockFinder（SearchDepth=1）を使用します
仮想サブシステムに ExecutionOrder を使用する	まず get_param(obj,'IsSubsystemVirtual') を確認します
Simulink Functions に ExecutionOrder／SystemIO を使用する	slreportgen.utils.isSimulinkFunction(result.Object) で条件を確認します

規約

• すべての内容を追加した後、必ず close(rpt) を実行します — 出力ファイルが生成されます
• DOCX を開くときは、必ず rptview または docview を使います — winopen や open は使いません
• レポートに出力するプロットには figure("Visible","off") を使います
• 図をファイルに保存するときは、print ではなく exportgraphics を使います
• 1 章につき番号付けの範囲は 1 つです — 図と表には「章番号-連番」の形式で番号を付けます（例：「図 2-1」）
• BaseTable は FormalTable をラップします — MATLAB の table() ではなく、FormalTable(headers,body) を渡します
• セル単位のスタイル設定：構築時ではなく、構築後に entry(t,row,col) を使います
• テンプレートのスタイルには [] 配列を使い、インラインの .Style プロパティには {} を使います
• レポーターは @ClassName ディレクトリに配置します — それぞれに独自の resources/templates/ が必要です
• いずれかを編集する前に、すべてのレポーターのスキャフォールドを生成します — customizeReporter はバイナリテンプレートを作成し、classdef を上書きします
• スキャフォールドの生成後、修飾されていないクラス名を修正します — パッケージ修飾名を使います
• すべての出力形式をカスタマイズします — PDF／Word／HTML のテンプレートはそれぞれ独立しています
• Simulink：必ず slreportgen.report.Report を使い、必ず Diagram.Snapshot.ScaleToFit = true を設定します
• Simulink ファインダー：get_param にはパス文字列ではなく .Object ハンドルを使い、タイトルには result.Name を使います
• 複数レポーターのパッケージでは、唯一の信頼できる情報源として JSON を使います — スタイル値をハードコードしないでください

レポートの表示と処理

rptview(rpt);                           % Open in system viewer (updates DOCX fields)
rptview("MyReport.docx","pdf");         % Convert DOCX to PDF via Word
docview("Report.docx","updatefields","closedoc","closeapp");  % Update without display

検証： エラーなく実行できても、正しいことの確認にはなりません。close(rpt) の後に、次を行います：

• isfile(rpt.OutputPath) および dir(rpt.OutputPath).bytes > 1000 を確認します
• PDF の場合：open(rpt) を呼び出し、内容を追加する前に rpt.Document.RetainFO = true を設定してから、*_FO/*.fo ファイルを検索します
• DOCX の場合：解凍して word/document.xml を検索します
• 期待されるタイトル、見出し、キャプションが出力に表示されることをアサートします

検証パターンの詳細については、references/report-api-patterns.md を参照してください。

必要なツールボックス

MATLAB Report Generator（mcp__matlab__detect_matlab_toolboxes で確認してください）。Simulink モデルのレポートには Simulink Report Generator も必要です。

---

Copyright 2026 The MathWorks, Inc.

---