レンダリング パイプライン
ドキュメントからページ画像へ
Between OpenDocumentAsync とブラウザに届く PNG の間には、2つの明確な段階があります: viewer resolution (which engine loads the document, decided once per open) と page processing (what happens to each page image on every request). 両方を理解することで、フォーマットがそのようにレンダリングされる理由と、DefaultRender が実際に何を切り替えるかが分かります。
ステージ 1 — フォーマットビューアの解決
ファクトリーは、フォーマットカタログを介してファイル拡張子をビューアにマッピングし、3つの優先レベルがあります:
- カスタムビューアが最初。
DoconutOptions.RegisterViewer(extension, factory, defaultConfig?)で登録したものは、すべての組み込みビューアより優先されます。 - 組み込みファミリービューア。カタログは、各表示可能な拡張子をビューアファミリー(Word、Excel、PowerPoint、Pdf、Cad、Dgn、Image、Tiff、Psd、Email、Visio、Project、Xps、Epub、Txt、Html、Mht、Dcn)にマッピングし、各ファミリーは独自のエンジンアダプタを持ちます。 同じ拡張子に対してライセンス済みプラグインがビューアを提供した場合、プラグインビューアが組み込みビューアを置き換えます。
AddDoconut()は起動時に登録されたプラグイン権利を検証します;ファクトリーが組み込みビューアにフォールバックするのは防御的な実行時ルールです。 - プラグイン専用フォーマット。一部の拡張子には組み込みビューアが全くなく、DICOM(
.dcm)は DICOM プラグインを通じてのみ存在します。必要な機能がない状態で開くと、次の例外がスローされます:
LicenseException: This document type requires the 'Dicom' plugin license.拡張子にビューアが存在しないと、次のエラーが発生します:
FormatNotSupportedException: Document format '<extension>' is not supported.解決後、設定は確定します:渡した場合は明示的な設定オブジェクト、渡さなければカタログからのフォーマットデフォルト設定です。 DocOptions.Password は保護されたドキュメント用の設定にコピーされます。
ステージ 1b — リダイレクトモード (DefaultRender = false)
ほとんどのフォーマット別設定は DefaultRender フラグを公開します。これは、根本的に異なる2つのパスを選択します:
DefaultRender = true— ドキュメントはネイティブにレンダリングされ、直接ページ画像へ出力されます。DefaultRender = false— ドキュメントはまずメモリ内で PDF に変換され、ソースエンジンは解放され、PDF ビューアが引き継ぎます。生成された PDF は実際のテキストを埋め込むため、全文検索はピクセル単位で正確なハイライトが可能です;パイプラインはリダイレクトされた PDF に対してAllowSearchとAllowCopyをオンに強制します。変換はユーザーに見えないためです。
XPS とカタログのデフォルトである MHT はリダイレクトパスを使用します。PDF プロジェクションは HTML や Microsoft Project などのフォーマットに対してネイティブ検索を提供できます。生成された PDF にテキストレイヤーのない画像が含まれる場合、標準ビューアはそれらのピクセルを検索できません。
ドキュメントを開く際に事前変換が必要になる代償として、テキストを保持した PDF プロジェクションが必要な場合はリダイレクトモードを使用してください。
ステージ 2 — ページ画像パイプライン
レンダリングされたページは、リクエストごとに固定シーケンスで処理されます:
raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response- Watermark — ライセンス状態(ライセンス未取得、期限切れの一時またはサブスクリプション、無効なドメイン、バージョン不一致)から適用され、
DocOptions.Watermarkからは独自のカスタムテキストが適用されます。適切にライセンスされたアプリ、または有効な一時ライセンスでカスタム透かしが設定されていない場合、このステップはスキップされます。 - Rotate/flip — ユーザーがウィジェットで設定するページごとの状態(90°/180°/270°、水平/垂直フリップ)はセッションに保存され、以降のそのページのレンダリング時に適用されます。
- Scale — サムネイルとズームレベルは、レンダリングされたページを要求されたターゲットサイズにスケーリングして生成されます;
0は元のサイズで提供することを意味します。 - Annotation burn — 保存されたアノテーションがビットマップ上に描画され、エクスポートやページ画像に反映されます。
- Encoding — 結果はプールされたメモリストリームを使用して PNG にエンコードされ、直接 HTTP 応答に書き込まれます。
ミドルウェア内部のエラーは、HTTP エラーページではなく PNG エラー画像(白地に赤文字)として返されるため、ウィジェットはページ領域にそれらを表示できます。
ページキャッシュ
BaseConfig.CachePages(デフォルトは true)は、ドキュメントセッションの存続期間中、レンダリングされたページ画像をメモリに保持するため、ページを再訪問しても再レンダリングされません。BaseConfig.ImageResolution(25〜300 DPI、0 = フォーマットデフォルト)は主な品質/メモリ調整です;各フォーマットのデフォルトはその設定ページに記載されています。
単一ノードでのレンダリング vs. 複数ノードでのレンダリング
上記はすべて、ドキュメントを開いたセッションに対してオンデマンドで単一ノードがレンダリングすることを説明しています。1つのノードが全アーティファクトセットをレンダリングして公開し、他のノードが共有ストレージからそれらのページを提供するデプロイメントは、別の読み取りパスを使用します — 詳細は Distributed Deployments を参照してください。
Linux 上のフォント
ページはサーバーにインストールされたフォントで描画されます。Linux では、最初のドキュメントを開く前にフォント設定ライブラリをインストールしてください(RHEL と Fedora では fontconfig)。
apt-get update && apt-get install -y libfontconfig1これがないと、ドキュメントを開く際に The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. が発生します。これは Doconut が必要とする唯一のシステムパッケージです;libgdiplus は不要です。
その依存関係により基本的なフォントセット(DejaVu)が提供されるため、ドキュメントはすぐにレンダリングできます。サーバーに存在しないフォント(典型的な Linux イメージでの Calibri、Arial、Times New Roman など)を要求するドキュメントは、代わりに最も近いインストール済みフォントが使用されるため、テキストの幅や改行が Windows と異なる場合があります。Windows に近い出力を得るには、メトリック互換の代替フォント fonts-liberation、fonts-crosextra-carlito、fonts-crosextra-caladea をインストールしてください;他のスクリプト用に fonts-noto-core または fonts-noto-cjk を追加するか、独自の .ttf/.otf ファイルを /usr/share/fonts/ にコピーして fc-cache -f を実行します。
Alpine やその他の musl ベースのディストリビューションはサポートされていません。
どこを調整すべきか
| 目的 | 調整項目 |
|---|---|
| ページをより鮮明に | フォーマット設定で ImageResolution |
| HTML/EPUB/メール/MHT/MPP の正確なテキスト検索 | フォーマット設定で DefaultRender = false |
| 大容量ドキュメントでのメモリ削減 | CachePages = false、セッションを明示的に閉じる |
| 各ページへの独自スタンプ | DocOptions.Watermark |
このページは役に立ちましたか?