API 一覧

BDF の公開 API をパッケージごとにまとめる。引数や細かい挙動は Go のパッケージコメント（go doc）と TypeScript の型定義に書いてある。フォーマットそのものは spec.md、設計の理由は design.md を参照。

使う場所ごとの入口は次のとおり。

Go: 変換（converter）

github.com/shibukawa/bdf/converter は入力形式の登録簿と、形式に共通する変換の入口である。形式ごとの変換器はサブパッケージで、import したものだけが登録される（converter/all は全形式）。

import (
	"github.com/shibukawa/bdf/converter"
	_ "github.com/shibukawa/bdf/converter/all" // 全形式を登録する
)

res, err := converter.ConvertFile("in.xlsx", "", &converter.Options{}) // "" は形式を内容から判定する
if err != nil {
	return err
}
f, _ := os.Create("out.bdf")
defer f.Close()
err = res.Doc.WriteSingle(f) // res.Doc.WriteSplit("out/") なら分割形式

Result は Doc *bdf.Document、Warnings []string（Options.Warn が無いとき）、Summary（1 行の要約）、Protected（パスワードで開いた入力。同じパスワードで bdf.NewPasswordLock して暗号化するとよい）を持つ。

Options の項目（形式ごとに使うものだけを読む）:

形式ごとのパッケージ

直接呼ぶと、converter.Options に無い形式固有の設定も使える。どのパッケージも Convert と ConvertFile を持ち、Options には Title と Warn、テキストをレイアウトする形式ならフォントまわり（FontFS、FontDirs など）と NoTextIndex、画像を持つ形式なら Images がある。ページの選択は converter.Pages 型である。

ページ単位の変換の使い方:

s, err := converter.OpenStream(r, size, "", &converter.Options{})
if err != nil {
	return err
}
outline := s.Outline() // すぐ表示できる: 全ページの大きさ
send(outline)
for i := range s.Pages() { // 読み手が見ているページから順に呼んでよい
	page, err := s.Page(i) // ページ 1 枚と、新しい Part だけ
	if err != nil {
		return err
	}
	send(page)
}
res, err := s.Finish() // Convert と同じ完成した文書

Go: 文書の組み立てと読み込み（bdf）

github.com/shibukawa/bdf はフォーマットそのものを扱う。変換器もこれで文書を作る。

書き出し

描画命令（Object）

NewObject() で作り、メソッドを連ねて命令を足す（どれも Canvas 2D の同名の操作に対応する）。

読み込み

保護モードの配信（segment）

github.com/shibukawa/bdf/segment は、区間を要求ごとに封印して返す net/http のハンドラ（design.md §3.30）。

http.Handle("POST /segments/{name}", &segment.Handler{
	Open:  func(r *http.Request) (*bdf.Reader, error) { … },        // ログインと権利を確かめて文書を返す
	Allow: func(r *http.Request, s bdf.Segment) error { … },         // 区間ごとの規則（立ち読み、読む速さ）
})

その他のパッケージ

Go: サムネイルとページの画像（thumbnail、imagebdf）

github.com/shibukawa/bdf/thumbnail は文書のサムネイルを、github.com/shibukawa/bdf/raster/imagebdf は任意のページや範囲の画像を、ブラウザを使わずに Go で描く（design.md §3.25）。

d, _ := r.ToDocument() // 変換した結果なら res.Doc
th, err := thumbnail.Make(d, &thumbnail.Options{Size: 256, Raster: imagebdf.Options{FontDirs: dirs}})
if err != nil {
	return err
}
err = thumbnail.Encode(w, th.Image, thumbnail.PNG) // JPEG、WebP も

ページ全体は dpi または画素数を指定して描ける。戻り値の *image.RGBA は image.Image として使える。

renderer := imagebdf.New(d, nil)
img, err := renderer.PageDPI(d.Views[0], 0, 144) // 幅 144 pt のページなら 288 px
if err != nil {
	return err
}
return thumbnail.Encode(w, img, thumbnail.PNG)

描けるもの: パス（nonzero・evenodd、アンチエイリアス）、線（端・結合・破線。1 画素より細い線はビューアと同じく 1 画素幅で薄く）、クリップ、単色・線形・放射・扇形のグラデーションとパターン、画像（PNG、JPEG と EXIF の向き、GIF、BMP、WebP、SVG）、埋め込みフォントと名前で参照するフォントのテキスト（advance 補正、揃え、ベースライン、字間、太字・斜体の合成、字ごとのフォールバック、右から左の文字の並べ替え）、グループの透明度とブレンド、ソフトマスク、影（グループを囲む状態の影は、グループ全体の影になる）。描かないもの: AVIF の画像、FILTER、ヒンティング、カーニング、合字、アラビア文字の字形の変化。

Go: 数式（formula、raster/ebitenginebdf）

github.com/shibukawa/bdf/image/formula は LaTeX・MathML の数式を組み、パスだけの Object にする（design.md §3.23）。使い方とサンプルは描画する。

ts, err := formula.New(nil) // 同梱の STIX Two Math
l := ts.Layout(formula.ParseTeX(`x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}`), formula.Style{Size: 24, Display: true})
img, err := imagebdf.Object(l.Object(), 2, nil) // *image.RGBA

github.com/shibukawa/bdf/raster/ebitenginebdf は別モジュール（go get github.com/shibukawa/bdf/raster/ebitenginebdf）で、パスだけの Object を Ebitengine で描く。

コマンド（bdf）

go run ./cmd/bdf <サブコマンド>。暗号化された文書は $BDF_PASSWORD のパスワードで読む。

generate の -thumbnail <file>（-thumbnail-size、-thumbnail-mode、-thumbnail-sheet-dpi）と -text <file>（- で標準出力）は、変換と同時にサムネイルとテキストを書く。サムネイルとテキストは暗号化されないので、暗号化した文書（generate では暗号化して書き出す文書。既定ではパスワード付きの入力のもの）については書かない。-allow-plaintext を付けたときだけ書く（thumbnail・text・render も同じ）。

ブラウザ内変換（cmd/bdfwasm）

cmd/bdfwasm は変換器を GOOS=js GOARCH=wasm でビルドしたもので、Go の wasm_exec.js とともに Worker で動かす（デモサイトは examples/common/convert-worker.ts）。起動すると globalThis.bdfConverter を設定する。-tags pdfonly、officeonly、webonly、imageonly で PDF 用、Office 系用、HTML・Markdown・EPUB 用、画像用に分けてビルドできる。previewonly は変換器を持たず、BDF のサムネイルと検索用テキストと PDF を作るモジュールになる（thumbnail・text・pdf）。formonly は帳票のテンプレート（Word・Excel・PowerPoint）を読んで穴埋めし、PDF にするモジュールになる（fields・fill・pdf）。

options は {format?, password?, fonts?, name?, pages?}。pages は bdf generate -pages と同じ書き方で、変換するページ（スライド、シート）を選ぶ（サムネイルだけなら "1"）。fonts はフォントのディレクトリの URL で、index.json にファイルとフォント走査の範囲（テーブルディレクトリ、name・OS/2・post・cmap）を並べておく（site/build.mjs が作る）。フォールバック探索では cmap に文字があるフォントだけ全体を取得する。失敗した Promise の Error は、パスワードが要る・違う・形式が分からないときに code が "password-required"、"wrong-password"、"unknown-format" になる。返す文書は入力が暗号化されていても暗号化しない。

TypeScript: @bdfkit/core

BDF を読むためのパッケージ（packages/core）。DOM に依存しないので Node でも動く。

文書を開く

BdfDocument のメソッド:

Object とテキスト

TypeScript: @bdfkit/render

ブラウザで描くためのパッケージ（packages/render）。デコードと描画は Worker（@bdfkit/render/worker をバンドルしたもの）で行い、メインスレッドはビットマップとテキスト層を置く。

import { BdfWorkerClient, buildTextLayer, installCopyHandler, TEXT_LAYER_CSS } from "@bdfkit/render";

const client = new BdfWorkerClient(new Worker("./worker.js", { type: "module" })); // @bdfkit/render/worker をバンドルしたもの
const manifest = await client.open({ kind: "single", url: "doc.bdf", range: true });
const view = manifest.views[0];
const zoom = 1;

// ページ 1: Worker が描いたビットマップを canvas に置き、その上にテキスト層を重ねる
const bmp = await client.page(view.id, 0, zoom * devicePixelRatio);
canvas.width = bmp.width;
canvas.height = bmp.height;
canvas.getContext("2d")!.drawImage(bmp, 0, 0);
pageElement.append(buildTextLayer(await client.content(view.id, 0), zoom, { lang: "ja" }));

// テキスト層の CSS と、ページをまたいだコピー
document.head.append(Object.assign(document.createElement("style"), { textContent: TEXT_LAYER_CSS }));
installCopyHandler(container);

BdfWorkerClient

テキスト層

検索バー

ブラウザ自身の検索（Cmd+F、Ctrl+F）は表示範囲の近くのテキスト層しか探せない。ビューアがこのショートカットを受けて View 全体を探すための部品（examples/miniviewer と @bdfkit/viewer が使う）。

同じスレッドで描く

Worker を使わない場合や、自前の Worker に組み込む場合の部品。