文書形式：画像、表、動画

#リソース

画像、SVG、表、動画は本文中には書きません。これらはリソースとして一度だけ宣言し（Sandboxのリソースパネルで管理します。このパネルでは、画像とSVGのアップロード、対話式の表エディター、YouTube・Vimeo・アップロードした動画、キャプションと配置の編集を扱います）、IDで本文と結び付けます。リソースは参照するだけで組み込まれます。インラインの:ref{id="…"}で一度言及すれば、エンジンが図や表をその参照の後にある最初の空き位置へフロートとして配置します。言及した段の下端、次の段の上端、次のページの帯など、印刷の組版者と同じやり方です。2度目に配置する必要はありません。

以下の2つの形式はどちらもCommonMarkと衝突しない新しい構文なので、これらを使った文書もほかのMarkdownビューアーではプレーンテキストとして読めます。

#インライン参照（基本の形）

本文中からリソースを参照するには:ref{id="…"}を使います。最初の参照はリソースを組み込み（ページ上に配置されるようにし）、同時に算出された番号を表示します。番号の前には、既定で種類の短いラベルが付きます。

As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.

表示は「As shown in Fig. 1.7, the lantern room sits above the gallery.」となります。図そのものはその文の後にある最も近い空き位置（この段の下端、次の段の上端、または次のページの帯）へフロートとして配置され、この文とそれに続くテキストは途切れずに流れます。

参照の位置で本文が途切れることはありません。リソースが置かれる場所（最初の空き位置か、上端または下端の位置だけか、1段の中か全幅にわたるか）は、その配置（後述の配置を参照）と、言及した場所によって決まります。探索は参照の直後から始まります。

#ブロック埋め込み（任意、本文中への明示的な配置）

リソースをフロートさせず、流れの中の決まった位置に置きたい場合もあります。フロートをやめるには、リソースにplacement.position: "here"を指定し、::resource{id="…"}を単独の行に書いて埋め込みます。

Here is the floor plan we discussed.
 
::resource{id="lighthouse-diagram"}
 
The keeper's quarters occupy the eastern wing.

フロートするリソースには::resourceディレクティブは不要です。:refがすでに配置しており、同じIDに対する余分な::resourceは2つ目の複製ではなく、もう1つの参照として扱われます。::resourceがリソースを本文中に描画するのは、解決された配置が"here"の場合だけです。インラインのリソースは、フロートと同じく上に1行分のアキ（フロートのアキ）を取ります。ただし、直前のブロックがそれより大きなアキを求める場合はそちらに従います。本文中では下にも同じアキを取り、その後のテキストはベースライングリッドに戻ります。このとき、さらに最大1行分のアキが加わることがあります。直後に見出し、リスト、囲み、または別のインラインのリソースが続く場合、そのアキは後続の要素自身の上のアキと共有され、両方ではなく大きいほうが適用されます。（postext 1.4までは、下のアキはグリッドへのスナップで残る分だけで、0から1行まで幅がありました。layout.inlineResourceGap: 'above'でその規則を保てます。1.5より前に保存された本はこの設定で読み込まれます。）囲み（:::callout）の中でもリソースは同じアキを保ち、上には囲み自体のテキストの1行分、'around'の場合は下にも同じだけ取ります。囲みの上端または下端では、代わりにパディングがリソースを離します。（postext 1.4までは、リソースは囲みのテキストに密着していました。layout.inlineResourceGapInBoxes: falseでその動作を保てます。リソースを埋め込んだ囲みを含む、1.5より前に保存された本はこの設定で読み込まれます。）

段が複数ある版面では、配置にさらにspan: 'page'を指定したインラインのリソース（placement: { position: 'here', span: 'page' }）は、ページ幅の囲みと同じく、ディレクティブの位置でページ幅いっぱいに組まれます。上の段は高さをそろえて閉じ（段の均等化を行い、そろえられない場合はリソースが次ページの頭へ送られます）、リソースは版面の幅いっぱいに上下に同じアキを取って組まれ、本文はその下のすべての段で続きます。1段のページでは、これまでどおり段幅いっぱいに組まれます。columnsを指定したspan: 'column'のリソースは、インラインで埋め込むと自分の段にとどまります。段数はフロートにだけ効きます。postext 1.19から。

idはリソースパネルで定義したリソースと一致している必要があります。エンジンはリソース（ビットマップ、SVG、表）を描画し、その下に図や表の脚書きとしてキャプションを組みます。キャプションのテキストは、リソースの種類のcaptionPrefix、算出された番号、リソース自身のキャプションから組み立てられます。たとえば「Figure 1.7. The original lighthouse plan.」のようになります。キャプションの文字組みは設定 › キャプションスタイルで決まります。ラベルと説明文は書体とサイズを共有し、ラベルだけは太字・イタリック・色を個別に設定できます。キャプションの上のアキの既定値は0.75em、そろえの既定値は左です。キャプションはリソースの上に置くこともでき（captionStyle.position: 'above'。全体またはリソースの種類ごとに指定）、色付きの帯の上に組むこともできます。リソースにはnote（注記）を付けることもできます。出典やクレジットを示す短い行で、キャプションと同じインラインの書式と:refの記号が使えます。注記はリソースの下に小さめの文字で組まれ（キャプションが下にあるときはキャプションの下、上にあるときは本体の下）、スタイルはcaptionStyle.noteで設定します。

キャプションと注記の改行。キャプションや注記はそれぞれ、その位置の行長で組まれる1つの段落で、中で入力した改行はスペースになります。新しい行を始めるには、タイトルで使う強制改行の\\を書くか、Markdownのハード改行として行末をバックスラッシュで終えます。¹ Measured at 20 °C. \\ ² Mean of three runs.と書けば、幅の広い表の脚注がそれぞれ1行に組まれます。改行の前の行は自然な幅のままで、行長いっぱいに伸ばされることはありません。改行を2つ続けても空行はできません（間にノーブレークスペースを入れると空行になります）。表のセルの中では、\\は改行と同じく新しい段落を始めます。その次の行の字下げは保たれるので、先頭の2つのスペースでリスト項目を入れ子にできます。本文中では2つのバックスラッシュは常に改行になり、エスケープの方法はありません。そのまま印字するには、バックスラッシュが書いたとおりに印字されるインラインコードの中に入れます。リンク先の中ではURLの一部、ディレクティブの属性（:refのtext）の中では値の一部のままです。1行に組まれるチップの中では、改行はスペースになります。（postext 1.4までは、バックスラッシュがそのまま印字され、キャプションや注記は行長が尽きたところでしか改行されませんでした。）

表のリソースは独自の罫線を描画し、そのスタイルは設定 › 表スタイルで設定します。本文セルとヘッダーセルの文字組みは完全に独立しています。ヘッダーの背景の既定値は#f0f0f0、罫線は0.75pt、cellPaddingは0.375emで、未設定の項目は本文テキストから継承されます。列幅は表そのものに含まれます。TableModel.columnWidthsは列ごとに1つの相対的な比率を持ち（[2, 1, 1]なら第1列が幅の半分を占めます）、未設定なら列は幅を均等に分けます。表は名前付きのバリエーションで組むこともできます。table.styleIdは文書のtableStylesの1つを選び（設定 › 名前付きの表スタイルを参照）、その未設定の項目はtableStyleを継承します。不明なIDやIDがない場合はtableStyleのままです。

セルの内容の置き方は、TableCell.align（left、center、right。リスト項目は左そろえのまま）とTableCell.verticalAlign（既定値のtop、middle、bottom）で決めます。縦方向のそろえは、内容より背の高いセル、つまり隣の長いセルに引き伸ばされた行や、rowSpanがまたがる行の中で、セルの内容全体（画像とその下のテキストを1つのまとまりとして）を動かします。これはすべての出力（canvas、HTML、PDF）、回転した表、ページをまたいで分割された表の各部分に適用されます。どちらもSandboxの表エディターのツールバーにあるそろえのボタンでセルごとに設定します。

表のセルには画像を入れることもできます。TableCell.imageはビットマップまたはSVGのリソースをIDで指定します（{ "resourceId": "fig-arm", "width": 0.7 }）。画像はセルの中に描画され（番号、フロート、キャプションは付きません）、縦横比を保ったままセルの内側の幅（またはwidthで指定したその割合。既定値は1）に合わせられ、セルのテキストと同じようにそろえられます。セルのテキストはその下に続きます。行は画像が収まるように高くなります。Sandboxの表エディターでは、ツールバーの画像ボタンで選択中のセルのリソースを選び、幅の欄で割合を設定します。どの画像リソースとも一致しないIDの場合、セルはテキストだけになります。

セルには独自の塗りを持たせることもできます。TableCell.backgroundは色の値（{ "hex": "#c1dfd6", "model": "hex" }。paletteIdで文書のパレットの項目にリンクすることもできます）で、スタイルのヘッダーや本文の背景の代わりに塗られます。互換性の一覧表では、この方法でセルを緑、赤、黄色に塗り分けます。Sandboxの表エディターでは、ツールバーの塗りのコントロールで設定します。こうした塗りの凡例のために、キャプション、注記、あらゆるテキストブロックでインラインのカラースウォッチが使えます。:swatch{color="#c1dfd6"}（hex値、またはパレット項目のID。:swatch{color="table-compatible"}）は、ベースライン上にフォントサイズの4分の3の小さな正方形を置き、その色で塗ってテキストの色で輪郭を描きます。これで注記を:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatibleのように書けます。何にも解決されない色の場合は、空の輪郭だけが描かれます。hex値にはアルファチャンネル（#rrggbbaa、#rgba）も使え、rgb() / rgba()の色も使えるので、半透明のセルの塗りには半透明の凡例を合わせられます（設定 › 透明度を参照）。

SVGのリソースは、さらにdiagramStyle.singleInk（既定値はfalse）で、1色の特色印刷向けに色を変えられます。有効にすると、SVGのダイアグラムのすべての色が、輝度に応じたdiagramStyle.inkColor（既定値はパレットのメインカラー#295AA3）の濃淡に置き換えられます。白は紙の色に、黒はインキのベタになるので、文書を1色の特色で印刷しても図が忠実に再現されます。設定 › ダイアグラムスタイルを参照してください。

不正な埋め込み（idがない、または空、idが引用符で囲まれていないか一重引用符で囲まれている、余分な属性がある）はリソースのブロックとして扱われず、通常の段落として解析されて出力にそのまま表示されます。正しい形式の埋め込み行でも、段落の行の直下に空行なしで続けて書くと同じで、その段落の一部として読まれます。どちらもmalformedEmbed警告となり、Sandboxの検査パネルにテキストとして組まれた埋め込みの項目として表示されます。

インライン参照は、段落、見出し、引用ブロック、リスト項目など、あらゆるテキストブロックの中で認識され、太字、イタリック、インラインコード、インライン数式と並べて使えます。

参照のオプション

:refディレクティブは3つの省略可能な属性を任意の順序で受け付けます。styleは算出されたラベルの表示方法を選びます。style="number"は番号だけ（1.7）、style="full"は種類の正式名と番号（Figure 1.7）を表示し、styleが未設定のときは種類のshortLabelと番号（Fig. 1.7）を使います。caseはラベル部分の大文字・小文字だけを変え（lower、upper、capitalize）、番号には触れません。textは書いたとおりに使われる上書きで、算出されたラベルを置き換え、styleとcaseの両方より優先されます。表示のオプションを並べると次のとおりです。

:ref（または::resource）が一致するリソースのないIDを指定すると、ラベルは?になり（text=のラベルがある場合はそれが表示されますが、番号もリンクも付きません）、Sandboxは不明なリソースの警告を出します。エンジンはこれを文書のcontentWarningsにunknownResourceIdの項目として、参照のソース範囲とページとともに記録します。本文が使うリソースのキャプション、注記、表のセルの中にある:refも同様です。

#初出順の番号付け

リソースの番号は、読む順序で最初に言及されたときに割り当てられます。最初の言及が::resourceのブロック埋め込みでもインラインの:refでも同じです。以降、同じIDへの参照はすべて同じ番号を表示します。

つまり番号は、パネルでリソースを作成した順ではなく、読者が出会う順に付きます。

• 序論で図を:refで参照し、2ページ後で初めて（::resourceで）埋め込んだ場合も、その図には序論の時点の番号が付きます。参照のほうが先だからです。
• 文書の前のほうに新しい参照を挿入すると、それ以降はすべて自動的に番号が振り直されます。手作業で番号を合わせる必要はありません。

番号はリソースの種類ごとに付けられ、種類ごとのリセット範囲とカウンターの書式に従います。テンプレートのトークン（{h1}、{n}）、resetOn、counterFormatについては設定 › リソースの種類を参照してください。

数えられるのは本文が参照するものだけです。デザインだけが描くリソース（たとえば章扉の画像要素）には番号が付かず、カウンターも変わりません。また{h1}は、スタイルがnumbered: falseでないすべてのレベル1見出しを数えます。numberingTemplateが空の見出しも含むため、唯一のH1がタイトルである記事では、図の番号は既定で1.1、1.2…となります。設定 › 番号が付くものに、この2つの規則と、図1、図2…と番号を付けるための設定があります。

#配置

各リソースには、フロートの置き場所を決める配置があります。配置はリソースごとに、まずリソース自身のplacement、次にその種類のdefaultPlacement、最後に組み込みの既定値auto / columnの順に解決されます。

フロートは、読む順序で最初の参照の後にある最初の空き位置に置かれます。順に、参照がある段の下端、同じページで次に空いている段の上端と下端、そして流れが開く次のページの帯です（ページ幅のフロートは、すべての段にまだ収まる余地があればページの下端を取り、そうでなければ次のページの帯を取ります）。インラインの図や表が開くページも対象になります。そのページを待っているフロートは、両方が収まる場合、図や表の上にあるページの先頭を取ります。収まらない場合は図や表がそのページを使い、フロートは次のページを待ちます。postext 1.4までは、そのようなページは飛ばされ、両方が収まる場合でもフロートはその次のページを待っていました。フロートは、shrinkで置き場所の空きまでの縮小を許していない限り元の大きさで組まれ（上の表を参照）、参照より前に置かれることもありません。同じ番号の系列のフロートは参照の順に現れます。あるページのどこにも収まらない図は、後ろの図を待たせます（待っている表が図を待たせることも、その逆もありません）。そのため図12が図11より前に現れることはありません。待つことになる表は、代わりに分割されます。空いた段の先頭が提供されると、収まる行だけを取り、ヘッダー行を繰り返して次の位置（隣の段か次のページ）に続きます（tableStyle.overflowを参照）。citingPageをオンにしたtopまたはautoのフロートは、代わりに参照行のあるページ（または段）の先頭に置かれることがあり、参照より前の本文はその下に送られます。このときフロートは同じページで参照より上に描かれますが、それより前のページに置かれることはなく、タグ付き PDF と HTML では参照の後に読まれます。エンジンは数回の追加パスでこれを決め、参照行がそのページに残る場合にだけ保持します。

フロートが章の外に出ることはありません。章扉（breakBeforeまたはspan: 'page'を持つ見出しレベル）、:::part、floatBarrier: trueを指定した囲みスタイル（章末の「要点」の囲み）、文書の末尾では、保留中のフロートがすべて先に配置されます。置かれるのは、そのページの空き位置か、境界より前に開いたページです。章扉自体が最初に参照するフロート（自分の図を挙げる章タイトル）や、:::partの後の最初のブロックが最初に参照するフロートは新しい章に属し、ほかのフロートと同じくその行の後に置かれます。ページの先頭を求めた図や表は、専用のページではなく、章の最後のページの、段末をそろえた段の下にある下端を取ることがあります。:::pagebreakは、保留中のフロートをその後のページに送るだけです。

2段以上の本文の上に組んだページ幅の章扉の下では、章扉のある段にまだ章扉の後の内容がないあいだ、その段の先頭は空いているものとして扱われます。章扉の直後に置いたフロートの囲みや、そこに::resourceで埋め込んだリソースは、章扉の下で第1段の先頭に入り、ほかの段の先頭とそろいます（columnsがあれば第1段から数段にまたがります）。その段の本文はその下から始まります。本文中で参照されるフロートは、これまでどおり参照する行の後に置かれます。postext 1.24までは第1段のこの位置は使われず、フロートは第2段から置かれていました。layout.floatsUnderOpener: falseでその動作を保てます（設定 › レイアウトを参照）。

サイド段の囲み（span="side"）も章の外には出ません。そのページのサイド段に収まらない囲みは、次のページのサイド段に置かれます。その前に章または文書が終わると、待っている囲みはそれぞれ、フェンスの順に本文の後に開いたページのサイド段に置かれ、その後で参照されたサイド段の図はそれらの後ろに置かれます。そのページには本文がないので、ビルドはそこにある囲みと図をすべて知らせます（afterText）。空のサイド段より高い囲みもそのまま置かれて知らされ（calloutOverflow）、それでもページが見つからないものも、捨てられずに知らされます（unplaced）。postext 1.24までは、そうしたページは最初の1ページしか開かれず、残りの囲みは警告なしに失われていました。

フロートの帯はベースライングリッドに合わせて補正され、周囲のテキストはページ全体の縦のリズムを保ちます。上端の帯は下側の余白を次のグリッド線まで広げるので、フロートの下のテキストは隣の段や向かいのページとそろったままになります。下端のフロートは、キャプションの最終行がほかの段の最終行とベースラインを共有するように固定されます（キャプションのない内容は下端を最後のグリッド位置にそろえます）。そのため満杯のページは、段をまたいでも見開きをまたいでも同じ高さで終わります。

章の最後のページ（および文書の最後のページ）では、テキストの最後の帯の下に組まれたページ幅の図や表の後には何も続きません。そのため、それらはテキストの下にフロートのアキ1つ分だけ空けて、順に積み重ねて上に移動し、テキストとページ下端の図の間に空白を残しません。position: 'bottom'のフロートも同じです。ほかのページと同じく下端に置いたままにするには、layout.hugClosingFloats: falseを設定します（設定 › レイアウトを参照）。サイド段のあるページでは移動しません。

canvasのプレビュー、HTMLビューアー、PDF出力の3つのバックエンドすべてがリソースを描画します。HTMLバックエンドでは画像データが本体とは別に保持されるため、ホストがresourceImageUrl(fileId)リゾルバーオプションで渡します。リゾルバーがない場合（またはファイルに対して何も返さない場合）、リソースは中立的なプレースホルダーの枠として描画され、レイアウトは崩れません。動画のファイル自体も、同じようにresourceVideoUrl(fileId)で渡します（動画を参照）。

フロートが置かれる場所

「参照より前には置かない」は、フロートを参照する行から数えます。フロートはその行が組まれるまで待ち、読む順序でその後にある最初の空き位置を取ります。その行が組まれるページの先頭は、行より前にあたります。サイドフロート（span: 'side'。1段半レイアウトのフロート専用のサイド段に置くもの）は例外で、参照するテキストの横のサイド段に積み重ねられ、参照行よりページの上のほうに置かれることもあります。5ページで参照される図の場合は次のとおりです。

• 章扉のページにも同じ規則が適用されます。章扉の最初の段落で参照されたページ幅のautoまたはbottomのフロートは、そのページの下端の帯（テキストの下）を取れます。topのフロートは次のページの先頭に置かれます。参照するページに画像を置くには、autoかbottomを使うか、章扉のデザインの画像要素として描きます。
• 同じ段落で参照された2つの段のフロートは、続く2つの位置を取ります。通常、1つ目は参照する段の下端、2つ目は次の空いた段の先頭に置かれ、ページ上で横に並びます。
• 1段組みのレイアウトではページ幅のフロートは段のフロートと同じで、同じ規則が適用されます。あるページで参照されたtopのフロートは、次のページの先頭に置かれます。
• ページをまたぐ段落も、参照行から数えます。段落が5ページの下端で始まり、参照が6ページにある場合（あるいは、5ページの下端に収まる行が足りず段落全体が6ページに移る場合）、参照は6ページにあることになります。topのフロートは7ページの先頭に置かれ、autoのフロートは余地があれば6ページの下端を取ります。同じページの段の間や、ページをまたいで分割された囲みでも同様で、囲みの2つ目の部分が参照する図はその部分を待ちます。
• postext 1.5での変更。postext 1.4までは、フロートを参照する段落にレイアウトが達した時点でフロートが待ち行列に入っていたため、そのような段落が続く（または移る）ページの先頭、参照を含む行より上にフロートが置かれることがありました。現在そのような図は1ページ後に置かれるか、autoを求める場合はそのページの下端に置かれます。その結果、ページ数が変わることがあります。

#回り込み

段より狭い図版、表、ボックスは、雑誌や会報のように段の片側に置き、本文をその横に組めます。配置にwrapの側と、必要ならwidthを指定します。

{ "id": "bed", "typeId": "figure", "kind": "svg", "caption": "新しい花壇。",
  "placement": { "position": "here", "wrap": "right", "width": 0.4 } }

• 本文中（"here"）。 リソースは段のその側に置かれ、上端は::resource行の次の行の上端にそろいます。続く段落、引用、箇条書きの項目は残りの行長でその横に組まれ、下では全幅に戻ります。横で始まり下で終わる段落は 1 つの段落のままで、途中で切れず、図版の下に余分な空きも入りません。すべての行がベースライングリッドに乗り、図版の下の空きは間隔を行送りの整数倍に切り上げたものです。
• 段のフロート。 1 段幅のspan: "column"フロートを段頭（"top"、または段頭の"auto"）か段末（"bottom"、"auto"）に置くと、ほかのフロートと同じく帯に置かれ、段の最初または最後の行がその横に組まれます。2 段組では、フロートは自分の段に属し、もう一方の段は全幅のままです。
• ボックス。 :::calloutは同じ設定を属性で受け取ります。:::callout{wrap="right" width=0.4}は現れた位置に引用や囲み記事を置き、続く本文を横に組みます。placement="top"または"bottom"とwrapを併せると段頭か段末に浮かせます。回り込むボックスはまとめて組まれ、分割されません。
• 下に回るもの。 見出し、別行立ての数式、図や表、ボックス、詩は回り込む対象の横に組まれず、その下に回ります。その上の横の余白は空いたままです。段を離れると（段末、:::columnbreak、改ページ）そこで回り込みは終わり、対象は自分の段に属します。本文中のリソースの直後のブロックが横に組めないときは、wrapがない場合と同じくリソースが帯を占めます。
• 間隔と限度。 wrapGap（なければlayout.wrap.gap、それもなければ本文 1 行分）が、キャプションを含む対象と横および下の本文とを隔てます。横の本文がlayout.wrap.minTextWidth（本文の 12 em）より狭くなる場合や、対象がlayout.wrap.minLinesBeside行（2）より低い場合は、全幅を占め、textWrap警告が出ます。段の残りに収まらない本文中の対象は、アンカーとともに次の段へ移り、同じ警告が出ます。
• 左右。 leftとrightはalignと同じく本文の流れの側です。右から左の本ではleftは紙面の右です。startとendは同じ側を指します。
• 出力。 キャンバス、HTMLビューアー、PDF、固定レイアウトEPUBはレイアウトどおりに行を組みます。タグ付きPDFは、図版やボックスを横に組まれた段落より先に読みます。リフロー型EPUBはCSSで同じ幅の割合のまま片側に浮かせます。
• 未対応。 図版の両側に本文を組むこと、輪郭に沿った回り込み、ボックスの中身の中での回り込み、縦組みでの回り込み（対象は帯のままで警告が出ます）。回り込む対象のある段は段のそろえから外れます。

#ビットマップのサイズ

ビットマップは自分のピクセル数を宣言します。bitmap.widthとbitmap.heightはファイルのピクセル数で、印刷サイズではありません。1インチに何ピクセルを割り当てるかで、置き場所による上限がかかる前の画像の大きさが決まります。サイズの決め方は3つあります。

• ページのdpiでのピクセル数（既定）。解像度がなければ、画像の1ピクセルはレイアウトの1ピクセルです（page.dpi。指定しなければ300）。2400 pxの写真は、300 dpiのページでは幅8インチ（203.2 mm）、150 dpiのページではその2倍になります。
• 解像度。bitmap.resolutionは原寸で印刷したときの画像のppiなので、原寸の幅はページのdpiにかかわらずwidth × page.dpi / resolutionです。resolution: 300の2400 pxは、150 dpiで組んだページでも300 dpiで組んだページでも幅203.2 mmです。layout.bitmapResolutionは、自身の解像度を持たないすべてのビットマップに解像度を与えます。値は数値（300）か、ファイルに記載された解像度を使う'file'です（bitmap.fileResolution。PNGのpHYs、JPEGのJFIFまたはEXIFの密度、WebPのEXIF。Wordから読み込んだ画像では、Wordで印刷されるサイズ）。カメラ、スクリーンショット、Web向けの書き出しは、印刷サイズを何も知らないまま72や96 ppiと記載することが多いため、'file'ではこの2つを記載なしとして扱い、画像はページのdpiでのピクセル数のままになります。リソース自体に宣言した72は、書かれたとおりに使われます。既定の'document'は1つ目の方法です。
• 段に対する割合。placement.widthはフロートやインラインの埋め込みを段（またはページ）の幅の一定の割合まで狭めます。その幅より大きい画像は、ピクセル数にかかわらずその幅まで縮小されます（配置を参照）。

どの場合も、画像は縦横比を保ったまま置き場所を上限とし、それより小さい画像が拡大されることはありません。表のセルの画像や、サイズが'auto'のデザインのimage要素にも、同じ原寸が使われます。PDFはファイルをそのまま、配置したサイズで埋め込みます。各画像が印刷される解像度はプリフライトで検査され、Sandboxのリソースパネルには画像ごとに表示されます。postext 1.24から。

{ "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.",
  "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } }

bitmapInfo(bytes)（postextとpostext/bundleがエクスポート）は、ファイルのピクセル数と、ファイルに記載された解像度を{ width, height, resolution?: { x, y, source } }として読み取ります。'file'で開いたバンドルはこれでfileResolutionを埋め、Sandboxはアップロードしたすべての画像についてこの値を保存します。

#セーフエリア

ビットマップやSVGのリソースにはセーフエリアを指定できます。画像の中で重要なもの（人物とその背後の風景の一部、グラフのプロット部分など）を含み、常に表示される長方形です。これはリソースのsafeAreaで、画像の固有サイズに対する4つの割合（0〜1）を左上の角から測ります。xとwidthは幅に対する割合、yとheightは高さに対する割合です。この名前は残すべきものを表します。トリミングの枠なら、どこを切るかを表すことになります。

const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // the boats and the quay: 18–68 % of the width, 25–85 % of the height
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};

トリミングされるのはセーフエリアのある画像だけです。その場合エンジンは、画像全体からセーフエリアまでの間の任意の縦横比で画像を表示できます。左右を切り落として画像本来の比率より縦長にする場合はセーフエリアの幅まで、天地を切り落として横長にする場合はセーフエリアの高さまでです。図の幅は変わらず、変わるのは高さだけです。セーフエリアの外側は、その両側の余白に比例して切り落とされるので、中央より左にある被写体は中央より左に残ります。上の港の画像を幅60mmで組むと、全体を表示したときの高さは40mmで、24mm（天地を高さの60%まで切り落とす）から80mm（左右を幅の半分まで切り落とす）までの任意の高さで表示できます。画像の端を超える値は端に収められます。数値でない値を含む範囲、辺が画像の2%未満の範囲、画像全体を覆う範囲は無視され、表に指定した場合も無視されます。セーフエリアがなければ、画像はこれまでどおり常に全体が表示されます。

エンジンはこの余裕を4つの場面で使います。

• 段に残った余地。インラインの画像（position: 'here'）が段に残った余地に対して少し高すぎる場合（キャプションがページの下端を超えてしまう場合も含む）、次の段やページに移ってこの段を短く残す代わりに、セーフエリアの範囲でトリミングしてその段にとどまります。
• 図より短いページ。layout.fitFiguresToPageを指定すると、ページに対して高すぎる画像はまず幅を保ったままセーフエリアの範囲でトリミングされ、それでも高すぎる場合にだけ縮小されます（設定 › レイアウトを参照）。
• 図より短い帯。placement.shrinkで置き場所の空きまで縮小するフロートは、まず幅を保ったままセーフエリアの内側でトリミングし、それでも足りないときに縮小します。下のflexFigureのレバーがその空きを超えて伸ばすことはありません。
• 段末そろえ。短い段にインラインで組まれた画像や、その段だけにかかるように段の先頭か下端にフロートとして置かれた画像のうち、セーフエリアのあるものは、段の空いた行を埋めるようにベースライングリッドの行単位で高くなります。画像が高くなっても目に見える穴は残らないので、この調整手段flexFigureは、段を閉じる囲みの調整の直後、見出しの上やリストの後にアキを加えるより前に試されます。章の最後のページや閉じの帯で段の先頭に置かれたフロートは高くなりません。それらの段の先頭は高さをそろえたままにするためです（設定 › 段末そろえを参照）。

VDTはトリミングをリソースのブロックに記録します。bodySourceはbodyRectに表示される画像の部分で、同じ割合で表します（画像全体が収まる場合はありません）。bodyFlexは、本体がまだ縮められる量と伸ばせる量、および調整手段がすでに変えた量をpxで示します（{ shrink, grow, delta }）。canvasのプレビューとPDFは本体でクリップし、トリミングしない大きさで画像全体を描きます。HTMLビューアーと固定レイアウトのEPUBは、object-fit: coverとそれに合わせたobject-positionで画像を組みます。埋めるべきページのないリフロー型のEPUBでは、画像全体を表示します。画像を自前で描くホストは、postextがエクスポートするヘルパーを使えます。resourceSafeAreaとnormalizeSafeArea（エンジンが読み取るセーフエリア、またはundefined）、safeAreaHeightRange（ある幅での本体の最小と最大の高さ）、safeAreaSource（ある高さで表示される部分）、uncroppedPictureBox（クリップの前に画像全体を描く位置）、そして型ResourceSafeAreaです。Sandboxでは、リソースパネルの画像にあるセーフエリアの項目で設定します。

レシピ集のNo. 116「短い段を埋めるように伸びる写真」は、2段組みの雑誌特集をセーフエリアなしとセーフエリアありの2回組むので、ページを並べて比べられます。

#話者のアンカーと回避エリア

漫画のコマの絵になる画像は、写植のために、人物がどこにいるかも示せます（漫画を参照）。anchorsは話し手ごとに1つの点を、avoidはどの吹き出しも覆わない範囲を並べ、どちらもセーフエリアと同じく画像に対する割合で表します。

const radio: Resource = {
  id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 },
  safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 },
  anchors: [
    // 灯台守：口、頭（思考の吹き出し用）、顔
    { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } },
  ],
  avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // 無線機
};

アンカーのidは台本の話し手のキー（tomas: …）か、コマの描き文字を集める点を表すsfxです。xとyはセリフの吹き出しのしっぽが指す口、headは思考の吹き出しの泡が指す点（未設定なら口）、faceはどの吹き出しも覆わない長方形です。エンジンはすべての点をコマのトリミングと反転を通して写すので、コマがどんな形になってもしっぽは話し手から外れません。セーフエリアの外にあるアンカーは、トリミングで切られるおそれがあるのでcomicAnchorOutsideSafeAreaを出します。3つ目の一覧facesには、話さない人物の顔をavoidと同じ長方形で書きます。吹き出しはこの顔を覆いません。回避エリアのほうは、コマにほかの場所がないときには覆われます。アンカーは画像に属し、その漫画のどの翻訳にも使えます。アンカーを読むのは漫画のコマだけで、図は無視します。Sandboxでは、リソースパネルのセーフエリアと写植のダイアログで指定します。

#動画

動画リソース（kind: 'video'）は、YouTubeまたはVimeoの動画、あるいは自前の動画です。自前の動画は、本の中に持つファイル（MP4、WebM）でも、Webのアドレスにあるもの、つまりサーバー上のファイルやHLSストリーム（.m3u8のプレイリスト）でもかまいません。画像と同じように配置、キャプション付け、フロート、参照ができ、独自の系列で番号が付きます。組み込みのvideoの種類は、Figure 1.1やTable 1.1と並んでVideo 1.1、Video 1.2…と表示します（設定 › リソースの種類を参照）。各出力は、それぞれ可能な形で動画を表示します。

const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};

本文は図と同じように動画を参照します。:ref{id="keeper-talk"}はVideo 1.1と表示し、参照の後にある最初の空き位置へポスター画像をフロートとして配置します。placement.position: 'here'を指定して::resource{id="keeper-talk"}を書くと、本文中に組まれます。Resource.video（ResourceVideo）の項目は次のとおりです。

ポスター画像。その位置の行長（またはそのplacement.widthの割合）で、ピクセルサイズにかかわらず自身の縦横比で組まれます。画面サイズのフレームは、小さく印刷されるのではなく拡大されます。ビットマップと同じくセーフエリアを持つことができ、placement.alignに従います。ポスター画像のない動画は、動画の縦横比（指定がなければ16:9）の暗い枠をオーバーレイ付きで印刷し、videoWithoutPosterの内容の警告を出します。Sandboxでは、YouTubeやVimeoの動画のポスター画像はアドレスを入力したときにプラットフォームから取得され、ファイルの場合は動画の中から選んだフレームになります。

アドレス。QRコードとPDFのリンクは、動画のページhttps://youtu.be/<id>またはhttps://vimeo.com/<id>をstartの位置から開きます。ファイルにはページがないので、公開先のアドレスを開きます。ファイルを持たない動画（サーバー上のMP4、HLSストリーム）も、このアドレスから再生されます。それがない場合、印刷物にはQRコードもリンクも付かず（videoWithoutUrl）、ファイルを含まないHTMLやEPUBの出力はポスター画像を表示します。YouTubeやVimeoのアドレスがそのプラットフォームの動画を指していない場合はvideoUrlInvalidが出て、プレーヤーの代わりにポスター画像が表示されます。

プレーヤー。プレーヤーのオプション（コントロール、ダウンロードボタン、全画面表示、速度メニュー、ピクチャーインピクチャー、キャスト、自動再生、ミュートでの開始、ループ、プリロード、プライバシー強化モードの埋め込み）は、本全体にはvideoStyle.playerで、1つの動画にはvideo.playerで設定します。各プレーヤーは対応できる範囲でこれに従います（設定 › 動画スタイルを参照）。HTMLバックエンドは、画像をresourceImageUrlで受け取るのと同じように、ファイルの再生可能なURLをresourceVideoUrl(fileId)オプションで受け取り、なければ公開先のアドレスを使います。そのvideos: { files, streams, hls }オプションは、videoStyle.htmlに優先して、再生元ごとにプレーヤーかポスター画像かを選びます（hlsはHLSのアドレスから再生する動画のためのもので、指定しなければfilesに従います）。EPUBライターもこれを使います。HLSのアドレスを再生する<video>にはdata-pt-hlsが付くので、HLSにネイティブ対応していないブラウザーでは、ホストがプレーヤーを付けられます（Safariと最近のChromeはそのまま再生します）。右から左の本では、QRコードが読めるように、プレーヤーとポスター画像のオーバーレイは画像と同じく向きが元に戻されます。

VDTでの表現。動画のリソースのブロックはkind: 'video'、ポスター画像としてのfileId / format（ビットマップと同じように描画されます）、そしてvideo（VDTResourceVideo）を持ちます。その中身は、読者を送るlink、プレーヤーオプションを適用したYouTubeまたはVimeoのembedUrl、ファイルのfileId、自前の動画のmimeType（ファイルのもの、またはアドレスだけの場合はアドレスのもの。HLSならapplication/vnd.apple.mpegurl）、start / endの範囲、解決済みのplayer、linkPoster、html、そしてオーバーレイのplayMarkとqr（QRのモジュールを'0' / '1'の行として表したもの）で、矩形は本体の左上の角からの相対位置です。動画を自前で描くホストは、postextがエクスポートするヘルパーparseVideoUrl、videoWatchUrl、resourceVideoLink、videoEmbedUrl、videoEmbedAllow、videoElementAttributes、mediaFragment、videoMimeType、videoFormatOfUrl、resourceVideoFormat、isHlsMimeType、HLS_MIME_TYPE、youtubePosterUrls、encodeQr、layoutVideo、playMarkTriangle、qrModuleRunsを使えます。

バンドルでの表現。.postextは動画ファイル（resources/<id>.mp4）とポスター画像（resources/<id>.poster.jpg）を含みます。マニフェストの項目はfileとposterでそれらを指定し、width / heightでポスター画像のサイズを示し、残りはファイルIDを除いてvideoに保持します。bundleVideoUrl(bundle)は、バンドルのファイルを対象とするresourceVideoUrlリゾルバーです。アドレスだけから再生する動画はファイルを持たないので、その項目にはポスター画像しかありません。多言語のバンドルでは、言語ごとにlocalized[…].resourcesで動画に独自のposterとvideo（別の編集版を、それ自身のアドレスで）を与えられます。

Folioのページで再生する動画

3Dの本では、自前の動画は、それが印刷されているページの上で再生されます。ポスター画像をクリックすると、ポインターが本に対して何をするモード（ページをめくる、視点を回す、テキストを選択する）であっても、その場で再生が始まります。ページのシェーダーがポスター画像の上に動画のフレームを描くので、丁をめくると映像も紙と一緒にしなって丸まり、めくっている間も再生は続きます。再生中の動画をクリックすると一時停止し、一時停止中の動画をクリックすると再開します。SpaceキーかEnterキーは、開いている見開きの最初の動画に同じことをします。別の動画を再生すると、再生中の動画は止まってポスター画像に戻ります。動画は、本がその動画の見えない見開きで静止したとき、またはendに達したときにも止まります。再生できる動画の上ではポインターが手の形になります。動画の上から始めたドラッグでも、ページはめくれ、視点は回ります。ひとりでに再生するよう設定した動画（video.player.autoplay）は、本が初めてその見開きで静止したときに、本の状態が落ち着くのを待って（レイアウトを段階的に進めるホストの場合も含めて）ひとりでに再生を始めます。そのビューアーで2度目に自動再生されることはありません。

ほかの動画と同時に再生する動画（video.player.exclusive: false、postext 1.18以降）では、この2つの決まりが変わります。再生を始めても止まるのは排他的な動画だけなので、こうした動画は何本でも同時に再生されます。排他的な動画を再生すると、こちらも止まります。autoplayを付けると、本がその見開きで止まるたびに無音で始まり、見開きがめくられると止まります。ページ上の無音のループ（loop）は、読者がそのページを開くたびにいっしょに流れます。

• 再生されるもの。ファイル（ホストがvideoUrlオプションでそのfileIdをURLに変えます。SandboxではオブジェクトURLです）、ファイルがなければそのアドレスで、MP4、WebM、HLSストリームのいずれかです。HLSストリームは、ブラウザーにMedia Source Extensionsがあればどこでもhls.jsを通して再生されます（最初の再生時に読み込まれます。postext-folioの省略可能なピア依存関係です）。画面上の映像の大きさに最も近いバリアントまでに抑えるので、高さ数百ピクセルの映像のために4Kのバリアントを読み込むことはありません。ブラウザー自身のHLSは、その代わりの手段として使われます。そのリクエストには専用のpt-corsクエリーが付くので、ほかのプレーヤーがCORSなしで取得したコピーをブラウザーのキャッシュが返すことはありません。YouTubeとVimeoはiframeの中で再生され、iframeはWebGLでは描けないので、そのポスター画像をクリックしても、ほかの場所と同じくページがめくれるだけです。
• クロスオリジンの読み込み。WebGLが動画を描けるのは、動画のサーバーが読み込みを許可している場合（CORS、Access-Control-Allow-Origin）だけです。読み込めない動画はポスター画像のままで、onVideoはerrorを受け取ります。
• 音声。クリックによって、動画は音声付きで再生できるようになります。それでもブラウザーが拒んだ場合は、ミュートで再生されます。ひとりでに再生を始める動画は、読者がページ上でクリックかキー入力をした後なら（そのページまでめくったことも数えます）音声付きで再生されます。それより前はミュートで始まり、動画をクリックすると、まずミュートが解除され、次のクリックで一時停止します。video.player.mutedはミュートで再生を始め、loopは繰り返し再生し、start / endは再生する部分を決めます。
• どのページでも。映像はレイアウトが置いた場所に、ポスター画像と同じように描かれます。回転したリソースでは回転し、縦組みのページでは正立し、右から左の本では左右反転されません。セーフエリアの範囲内で切り抜かれたポスター画像は、動画も同じように切り抜きます。
• WebGL2がない場合、または動きを減らす設定の場合は、ページの上に重ねたHTMLの<video>で再生されます。

const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();

videos: falseでこの機能をオフにします。toggleVideoAt({ page, x, y })はその位置をクリックしたときと同じ動作をし、pageVideoSpots(page, doc)はページ上の各動画の位置を一覧にします。独自のコントロールを描くホストのためのものです。

レシピ集の2つのレシピが動画を組んでいます。No. 131「ポスター画像にQRコードを刷った映画クラブのプログラム」は、映画ごとに再生マークとQRコードの付いたタイトルカードを刷ります。No. 132「画面とEPUBで動画が再生される実験シート」は、HTML版のプレーヤーオプションを設定し、自前の動画を固定レイアウトのEPUBに同梱します。