このドキュメントでは、CommonMark Markdown パーサーの高性能 Java 実装である flexmark-java の包括的な概要を説明します。速度、拡張性、詳細なソース位置追跡などの機能の詳細と、クイック スタート、利用可能な拡張機能、ペグダウンからの移行の手順が説明されています。この文書では、進行中の開発と貢献のガイドラインについても説明します。
フレックスマーク-Java
flexmark-java は、CommonMark (仕様 0.28) パーサーの Java 実装です。
最初にブロック、Markdown 解析アーキテクチャの後にインライン。
その強みは、速度、柔軟性、Markdown ソース要素ベースの AST であり、
要素を構成する語彙素の個々の文字までのソース位置と
拡張性。
API を使用すると、解析プロセスをきめ細かく制御でき、大規模な解析に最適化されています。
インストールされている拡張機能の数。パーサーと拡張機能には、パーサー用の豊富なオプションが付属しています
動作と HTML レンダリングのバリエーション。最終的な目標は、パーサーとレンダラーができるようにすることです。
他のパーサーを非常に正確に模倣します。これで部分的に完了しました。
Markdown プロセッサ エミュレーションの実装
このプロジェクトの動機は、Markdown Navigator のペグダウン パーサーを置き換える必要があったことでした。
JetBrains IDE 用のプラグイン。ペグダウンには優れた機能セットがありますが、一般に速度が遅くなります。
理想よりも、病的な入力の場合は、解析中にハングするか、実質的にハングします。
️バージョン 0.60.0 には、再編成、名前変更、クリーンアップ、および
実装クラスの最適化。変更点の詳細は、
バージョン-0.60.0-変更点。
最新
要件
バージョン 0.62.2 以下、Java 8 以降、Java 9 以降と互換性があります。バージョン0.64.0以降の場合
Java 11 以降。
プロジェクトは Maven 上にあります: com.vladsch.flexmark
このコアには org.jetbrains:annotations:24.0.1 以外の依存関係はありません。拡張機能については、を参照してください。
以下の拡張子の説明。
API は、新しい拡張機能や機能に対応するために進化し続けています。
クイックスタート
Maven の場合、コアとすべてのモジュールを含む flexmark-all を依存関係として追加します。
次のサンプル:
ソース:
BasicSample.java
Gradle経由でビルドする
Android Studio を使用したビルド
ファイルの重複による追加設定:
詳細については、次のドキュメントを参照してください。
Wiki ホームの使用例
拡張機能の詳細
拡張機能の作成
ペグダウン移行ヘルパー
PegdownOptionsAdapter クラスは、pegdown Extensions.* フラグをフレックスマーク オプションに変換し、
拡張機能のリスト。 Pegdown Extensions.java は利便性のために含まれていますが、新しいオプションは見つかりません
ペグダウン 1.6.0 では。これらは flexmark-profile-pegdown モジュールにありますが、
このリポジトリ: PegdownOptionsAdapter.java、Extensions.java からソースを取得し、独自のものを作成します
プロジェクトのニーズに合わせて変更されたバージョン。
拡張フラグを静的な PegdownOptionsAdapter.flexmarkOptions(int) に渡すことも、
PegdownOptionsAdapter をインスタンス化し、便利なメソッドを使用して設定、追加、削除できます
拡張フラグ。 PegdownOptionsAdapter.getFlexmarkOptions() は、次の新しいコピーを返します。
DataHolder は毎回、ペグダウン拡張フラグを反映するオプションを使用します。
デフォルトの flexmark-java ペグダウン エミュレーションは、厳密性の低い HTML ブロック解析を使用するため、
空白行の HTML ブロック。ペグダウンは、すべてのタグが含まれている場合にのみ、空白行の HTML ブロックを中断します。
HTML ブロックは閉じられています。
元のペグダウン HTML ブロックの解析動作に近づけるには、次のメソッドを使用します。
ブール値の strictHtml 引数:
カスタム リンク リゾルバーを使用したサンプルも利用できます。これには、
オーバーライドする必要がある場合は、リンクの URL または属性、およびカスタム ノード レンダラーを変更します。
生成されたリンク HTML。
flexmark-java には、flexmark-java よりも多くの拡張機能と構成オプションがあります。
pegdown 1.6.0 で利用可能な拡張機能に加えて、pegdown。
PegdownOptionsAdapter 経由で利用可能な拡張機能
最新の追加と変更
バージョン 0.60.0 での実装の大規模な再編成とコードのクリーンアップ。「」を参照してください。
バージョン-0.60.0-による素晴らしい作業のおかげで変更されました
Alex Karezin モジュールの依存関係の概要を取得できます
パッケージとクラスにドリルダウンする機能を備えています。
複数のマークダウンドキュメントを 1 つにマージするマージ API
書類。
Docx レンダラー拡張機能:
制限された属性ノードの処理
拡張可能な HTML to Markdown コンバーター モジュール:
フレックスマーク-html2md-コンバーター。サンプル:
HtmlToMarkdownCustomizedSample.java
Java9+モジュールの互換性
複合列挙参照
列挙型参照を作成するための拡張機能
要素と見出しの法的な番号付け。
任意のマークダウン コンテンツを可能にするマクロ拡張機能
ブロック要素またはインライン要素として挿入され、インラインのみでブロック要素を使用できるようになります。
要素は構文によって許可されます。
解析および解析のための GitLab フレーバード マークダウン
GitLab マークダウン拡張機能のレンダリング。
OSGi モジュールの提供: Dan Klco (GitHub @klcodanr)
メディア タグ メディア リンク トランス拡張機能の提供
Cornelia Schultz (GitHub @CorneliaXaos) がリンクを変換します
Audio、Embed、Picture、Video HTML5 タグにカスタム プレフィックスを使用します。
翻訳マークダウンを作成するための翻訳ヘルパー API
書類をより簡単に。
アドバイス ブロックスタイルのサイドコンテンツを作成すること。のために
完全なドキュメントは、Admonition Extension、MkDocs の資料を参照してください。
ドキュメント。
列挙型を作成するための列挙型参照
図、表、その他のマークダウン要素のリファレンス。
{name name=value name='value' name="value" #id .class-name} 属性の形式の属性を解析するための属性。
YouTube 埋め込みリンク トランスフォーマー
Vyacheslav N. Boyko (GitHub @bvn13) のおかげで、YouTube ビデオへの単純なリンクが次のように変換されます。
埋め込みビデオ iframe HTML。
docx4j ライブラリを使用する Docx コンバータ。使用方法:
DocxConverter サンプル、カスタマイズ方法:
Docx レンダリングのカスタマイズ
このモジュールの開発は次のスポンサーによって行われました。
ジョナー研究所 GmbH。
CommonMark (仕様 0.28) に準拠するようにライブラリを更新し、追加
ParserEmulationProfile.COMMONMARK027 および ParserEmulationProfile.COMMONMARK028 を許可する
特定の仕様バージョンのオプションを選択します。
オーバーライドされたノードの標準レンダリングを呼び出す機能を備えたカスタム ノード レンダリング API。
特殊なケースのみを処理し、残りを次のようにレンダリングするカスタム ノード レンダリングを許可します。
いつもの。カスタムリンクリゾルバー
Gfm の問題と
解析およびレンダリング用の Gfm-Users 拡張機能 #123 および
それぞれ @user-name です。
他のタグの後に続く生のテキストタグをより適切に処理するためのディープ HTML ブロック解析オプション
ペグダウン HTML ブロック解析の互換性のため。
コア、すべての拡張機能、フォーマッタ、JIRA、YouTrack を含む flexmark-all モジュール
コンバータ、ペグダウン プロファイル モジュール、HTML から Markdown への変換。
PDF出力モジュール
Open HTML To PDF を使用した PDF 出力
タイポグラフィックの実装
XWiki マクロ拡張機能
ジキル Tags
HTMLからマークダウンへ
Maven Markdown ページ生成プラグイン
ASTをマークダウンとして出力するMarkdown Formatterモジュール
書式設定オプション。
Markdown Formatter のテーブル
マークダウンテーブルの列幅と配置:
リリース、バグ修正、機能強化、サポート
JetBrains IDE の Markdown Navigator プラグインのパーサーとして flexmark-java を使用しています。私はそうする傾向があります
バグを修正したり改善を得るには、最新の未リリースバージョンを使用してください。したがって、バグを見つけた場合は、
あなたのプロジェクトのショーストッパー、またはあなたのプロジェクトに影響を与えている次のリリースで修正済みとマークされている Github の問題ページのバグを確認したら、私に知らせてください。すぐに対応できるかもしれません。
問題に対処するために新しいリリースを作成します。それ以外の場合は、バグ修正と機能拡張をさせていただきます
すでに修正されたものには誰も影響されないと考えて蓄積します。
API の拡張ポイントは非常に多くあります
API には、用途に応じた拡張オプションが多数あります。優れたソフトスタートとは、
要求された簡単なサンプルを含む flexmark-java-samples モジュール
拡張子。次に最適な場所は、同様の構文を持つ既存の拡張機能のソースです。
追加したいものに。
拡張機能が適切な API と一致している場合、タスクは通常非常に短くて簡単です。もしあなたの
拡張機能が意図しない方法で API を使用するか、予期されたハウスキーピングに従わない
プロトコルを使用すると、if/else 条件の処理とネズミの巣との困難な戦いに気づくかもしれません。
1 つのバグを修正すると、別のバグが作成されるだけです。
一般に、単純な拡張機能を追加するのに数十行以上かかる場合は、
やり方が間違っているか、API に拡張ポイントがありません。全部見てみると、
実装された拡張機能は、ほとんどが定型文以外の数行のコードであることがわかります。
API によって指示されます。それがこのライブラリの目標です。つまり、次のような拡張可能なコアを提供することです。
拡張機能を簡単に作成できます。
より大きな拡張機能は、flexmark-ext-tables と flexmark-ext-spec-example です。
どちらも約 200 行のコードです。サイズを見積もるためのガイドポストとして使用できます。
拡大。
私自身の拡張機能追加の経験から、新しいタイプの拡張機能が最適な場合があることがわかりました。
API の機能拡張により実装をシームレスにするか、バグを修正することで対処できます。
拡張機能が適切な方法で API を強調するまでは表示されませんでした。あなたの意図した
拡張機能はまさにそのようなアプローチを必要とするものかもしれません。
答えが見つからない場合は、ためらわずに問題を開いてください
重要なのは、拡張機能や機能を実装したい場合は、ためらわずに行ってください。
問題を開いていただければ、それに対処するための最善の方法についてアドバイスさせていただきます。それはあなたを大いに節約するかもしれません
多くの機能を追加する前に、拡張機能のニーズに対応するために API を改善させていただくことで、時間を節約できます。
それに対する無駄な努力。
私がこのプロジェクトの主任料理人でありボトル洗浄者であることを理解していただきたいのですが、
ヴァルカン・マインド・メルディング・スキルのイオタ。何を実装したいのか説明してください
あなたの心が読めないから。ソース周りの偵察バックグラウンド作業を行ってください。
コードとドキュメントは、あなたの意志がなければ、私が知っていることをあなたに伝えることができないためです。
努力。
コンサルティングが可能です
商用アプリケーションをお持ちで、拡張機能を自分で作成したくない場合、または拡張機能を作成したくない場合
拡張機能の実装と flexmark-java の統合にかかる時間と労力を軽減するには、
ご自由にご連絡ください。コンサルティング/契約ベースで対応させていただきます。
マークダウンプロセッサエミュレーション
その名前にもかかわらず、commonmark は他のマークダウン フレーバーのスーパーセットでもサブセットでもありません。
むしろ、元の「コア」の標準的で明確な構文仕様を提案します。
Markdown により、さらに別のフレーバーが効果的に導入されます。フレックスマークはデフォルトで
commonmark に準拠しているため、そのパーサーはさまざまな方法で調整できます。必要な一連の調整
最も一般的に使用されるマークダウン パーサーをエミュレートします。これらは flexmark で次のように利用できます。
パーサーエミュレーションプロファイル。
ParserEmulationProfile という名前が示すように、パーサーのみが
特定のマークダウンフレーバー。プロファイルを適用しても、で利用可能な機能を超える機能は追加されません。
共通のマーク。 flexmark を使用して別のマークダウン プロセッサの動作を完全にエミュレートしたい場合は、
パーサーを調整し、追加の機能を提供するフレックスマーク拡張機能を構成する必要があります。
エミュレートするパーサーで利用可能な機能。
他のマークダウンプロセッサのエミュレーションをより適切に制御するためにリストパーサーを書き換えました。
Markdown プロセッサのエミュレーションが完了しました。の追加
これらのパーサーの特定のマークダウン処理動作をエミュレートするプロセッサ プリセットは、
短いToDoリスト。
一部のエミュレーション ファミリは、他のエミュレーション ファミリよりもターゲットをより適切にエミュレートします。ほとんどの
この取り組みは、これらのプロセッサが標準のマークダウンとリストを解析する方法をエミュレートすることに向けられました。
特に関連する解析。オリジナルの Markdown を拡張するプロセッサの場合は、以下を追加する必要があります。
すでに flexmark-java で Parser/Renderer ビルダーに実装されている拡張機能
オプション。
拡張機能は、特定のプロセッサ エミュレーション用の独自のプリセットを含めるように変更されます。
そのプロセッサには同等の拡張機能が実装されています。
矛盾を見つけた場合は、問題を解決できるように問題を開いてください。
主要なプロセッサ ファミリが実装されており、一部のファミリ メンバーも次のとおりです。
プロファイル内のバリアントの構成詳細をカプセル化します。
ファミリは 0.11.0 で追加されました。
歴史と動機
flexmark-java は commonmark-java プロジェクトのフォークであり、AST を生成するように変更されています。
元のソース内のすべての要素を反映し、すべての要素の完全なソース位置追跡
AST とより簡単な JetBrains Open API PsiTree の生成。
API は、解析プロセスをより詳細に制御できるように変更され、最適化されました。
インストールされている多数の拡張機能を解析します。パーサーと拡張機能には多くの機能が付属しています
パーサーの動作と HTML レンダリングのバリエーションのオプションを調整します。最終目標は、
パーサーとレンダラーは、他のパーサーを非常に正確に模倣できます。
この動機は、Markdown Navigator プラグインのペグダウン パーサーを置き換える必要性からでした。
ペグダウンには優れた機能セットがありますが、一般にその速度は理想的とは言えません。
病的な入力は、解析中にハングするか、実質的にハングします。
commonmark-java は、理解しやすく拡張しやすい優れた解析アーキテクチャを備えています。
目標は、AST にソース位置追跡を追加しても容易さが変わらないことを確認することでした。
必要以上に AST を解析して生成すること。
commonmark-java をパーサーとして選択する理由は、速度、理解のしやすさ、使いやすさです。
伸びとスピード。コアを作り直し、いくつかの拡張機能を追加したので、非常に満足しています
私の選択に満足しています。
もう 1 つの目標は、パーサーの動作を変更する拡張機能の機能を向上させて、あらゆるパーサーの動作を変更できるようにすることでした。
マークダウンの方言は拡張メカニズムを通じて実装できます。拡張可能なオプション
すべてのオプションを 1 か所で設定できるようにする API が追加されました。パーサー、レンダラー、拡張機能の使用
これらの構成オプションには、一部のコア ブロック パーサーの無効化も含まれます。
これは進行中の作業であり、API に多くの変更が加えられています。過去の API を保持する試みは行われません
元のプロジェクトとの互換性があり、機能セットがほぼ完成するまでは、
このプロジェクトの以前のバージョン。
機能の比較
(1)
flexmark-java 100,000 の病理学的入力 [ 68 ミリ秒で解析、100,000 ] 57 ミリ秒、100,000
ネストされた [ ] は 55 ミリ秒で解析されます
(2)
commonmark-java 100,000 の病理学的入力 [ 30 ミリ秒で解析、100,000 ] 30 ミリ秒、100,000
ネストされた [ ] は 43 ミリ秒で解析されます
(3)
ペグダウンの病理学的入力は 650 ミリ秒で 17 [ 解析、1300 ミリ秒で 18 [
進捗
私自身のパーサーを commonmark-java ベースのパーサーに切り替える決定に非常に満足しています。
プロジェクト。完全な音源位置を確保するために内部に大規模な手術をしなければならなかったにもかかわらず
ソース要素と一致するトラッキングと AST を使用すると、作業が楽しくなり、今では
拡張する喜び。ソースレベル要素ASTまたは残りのflexmark-javaが必要ない場合
追加され、CommonMark がターゲットのマークダウン パーサーである場合は、使用することをお勧めします
commonmark-java はニーズに合った優れた選択肢であり、パフォーマンスはそれほど高くありません。
使用しない機能のオーバーヘッドが発生する可能性があります。
ベンチマーク
最新、2017 年 1 月 28 日 flexmark-java 0.13.1、CE EAP 2017 の intellij-markdown、commonmark-java
0.8.0:
上記の比率:
これら 2 つのファイルはペグダウンの病理学的入力を表すため、これらを次のように実行することはなくなりました。
結果の偏りを防ぐためのベンチマークの一部です。結果は後世のためにここにあります。
上記の比率:
貢献する
プルリクエスト、問題、コメントは大歓迎です?プルリクエストの場合:
ライセンス
著作権 (c) 2015-2016 Atlassian およびその他。
著作権 (c) 2016-2023、ウラジミール シュナイダー、
BSD (2 条項) ライセンス付き。LICENSE.txt ファイルを参照してください。
例:
ミツバレンダラー3
ドキュメント | チュートリアルビデオ | Linux | MacOS | 窓 | PyPI |
---|---|---|---|---|---|
️
警告
️
現在、文書化されていない不安定な作業が大量に行われています。
master
ブランチ。ぜひご利用ください。
最新リリース
追って通知があるまで。
今後の変更をすでに試してみたい場合は、こちらをご覧ください。
この移植ガイド。
今後の新機能と重大な変更のほとんどがカバーされているはずです。
導入
ミツバ 3 は、順光と逆光の研究指向のレンダリング システムです。
スイスのEPFLで開発された輸送シミュレーション。
コア ライブラリと機能を実装するプラグインのセットで構成されます。
マテリアルや光源から完全なレンダリング アルゴリズムに至るまで。
ミツバ 3 は再ターゲット可能です。これは、基礎となる実装と
データ構造は、さまざまな異なるタスクを実行するために変換できます。のために
たとえば、同じコードで両方のスカラー (一度に 1 レイずつの古典的な) RGB トランスポートをシミュレートできます。
または GPU 上の差分スペクトル転送。これはすべてに基づいています
Dr.Jit は、このプロジェクトのために特別に開発された特殊なジャストインタイム(JIT) コンパイラーです。
主な特長
クロスプラットフォーム:Mitsuba 3 は Linux ( x86_64
)、macOS でテストされています
( aarch64
、 x8664
)、および Windows ( x8664
)。
高いパフォーマンス: 基盤となる Dr.Jit コンパイラーがレンダリング コードを融合します
を使用して最先端のパフォーマンスを実現するカーネルに組み込まれます。
CPU をターゲットとする LLVM バックエンドと CUDA/OptiX バックエンド
レイ トレーシング ハードウェア アクセラレーションを備えた NVIDIA GPU をターゲットとしています。
Python ファースト: ミツバ 3 は Python と深く統合されています。材料、
テクスチャ、さらには完全なレンダリング アルゴリズムさえも Python で開発できます。
これは、システムによってオンザフライで JIT コンパイル (およびオプションで微分) されます。
これにより、コンピュータ グラフィックスの研究に必要な実験が可能になり、
他の分野。
微分: ミツバ 3 は微分可能なレンダラーです。
入力に関するシミュレーション全体の導関数を計算できます
カメラのポーズ、ジオメトリ、BSDF、テクスチャ、ボリュームなどのパラメータ。それ
EPFL で開発された最近の微分可能レンダリング アルゴリズムを実装します。
スペクトルと偏光:Mitsuba 3 は単色として使用可能
レンダラー、RGB ベースのレンダラー、またはスペクトル レンダラー。各バリアントでは、
必要に応じて、分極の影響をオプションで考慮します。
チュートリアルビデオ、ドキュメント
優しい紹介を提供する YouTube ビデオをいくつか録画しました。
ミツバ3とドクタージット。さらに、完全な Juypter ノートブックを見つけることができます。
さまざまなアプリケーション、ハウツー ガイド、リファレンス ドキュメントを網羅
readthedocs で。
インストール
PyPI 経由でコンパイル済みのバイナリ ホイールを提供します。この方法でのMitsubaのインストールは、実行するのと同じくらい簡単です
pip インストールミツバ
コマンドラインで。 Python パッケージにはデフォルトで 13 のバリアントが含まれています。
scalar_rgb
scalar_spectral
scalarspectralpolarized
llvmadrgb
llvmadmono
llvmadmono_polarized
llvmadspectral
llvmadspectral_polarized
cudaadrgb
cudaadmono
cudaadmono_polarized
cudaadspectral
cudaadspectral_polarized
最初の 2 つは、RGB のいずれかを使用して、一度に 1 レイずつの古典的なシミュレーションを実行します。
またはスペクトル色表現、後者の 2 つは逆変換に使用できます。
CPU または GPU でのレンダリング。追加のバリアントにアクセスするには、次のことを行う必要があります。
CMake を使用して Dr.Jit のカスタム バージョンをコンパイルします。をご覧ください。
ドキュメント
詳細については。
要件
Python >= 3.8
(オプション) GPU での計算の場合: Nvidia driver >= 495.89
(オプション) CPU でのベクトル化/並列計算の場合: LLVM >= 11.1
使用法
これは、レンダリングがいかに簡単であるかを示す単純な「Hello World」の例です。
PythonからMitsuba 3を使用したシーン:
# エイリアス "mi" を使用してライブラリをインポートしますimport tsuba as mi# renderer のバリアントを設定しますmi.setvariant('scalarrgb')# シーンをロードしますscene = mi.loaddict(mi.cornellbox())# シーンをレンダリングしますimg = mi。 render(scene)# レンダリングされたイメージを EXR ファイルに書き込みますmi.Bitmap(img).write('cbox.exr')
さまざまなアプリケーションをカバーするチュートリアルとノートブックの例が見つかります。
ドキュメントにあります。
について
このプロジェクトは Wenzel Jakob によって作成されました。
コードの重要な機能や改善は、次の寄稿者によって行われました。
セバスチャン・シュパイラー
ニコラ・ルーセル
マーリン・ニミエ=デイヴィッド
デリオ・ヴィチーニ
ティツィアン・ツェルトナー
バティスト・ニコレット
ミゲル・クレスポ
ヴァンサン・リロイと
チャン・ツィイー。
学術プロジェクトでMitsuba 3を使用する場合は、以下を引用してください。
@software{Mitsuba3,title = {Mitsuba 3 renderer},author = {Wenzel Jakob、Sébastien Speierer、Nicolas Roussel、Merlin Nimier-David、Delio Vicini、Tizian Zeltner、Baptiste Nicolet、Miguel Crespo、Vincent Leroy、Ziyi Zhang},note = {https://tsuba-renderer.org}、バージョン = {3.1.1}、年 = 2022}