kzdlib-symbol

工程's (Kouteizu) のシンボルを扱うための .NET Framework 向けクラスライブラリです。シンボルファイル (EMF) の列挙、リサイズを伴う描画、任意の色での描画、シンボル色の取得といった機能を提供します。

NuGet パッケージ WebI.KzdLib.Symbol として配布されます。利用方法の詳細は ユーザーガイド を参照してください。

動作環境

• .NET Framework 4.7.2 以降
• Windows デスクトップ環境 (GDI+ / WPF に依存)
• ビルドは dotnet CLI、Visual Studio 2019 以降、または MSBuild のいずれでも可能です (SDK スタイルの csproj です)

ソリューション構成

NuGet パッケージのメタ情報は (nuspec ではなく) WebI.KzdLib.Symbol.csproj に記載されています。

ビルド方法

SDK スタイルの csproj なので dotnet CLI でビルドできます (Visual Studio / MSBuild でも可)。

dotnet build WebI.KzdLib.Symbol.slnx -c Release

NuGet パッケージを作成する場合は dotnet pack を実行します。パッケージのメタ情報 (PackageId / Version / Authors など) は WebI.KzdLib.Symbol.csproj に記載されているため、新しいバージョンをリリースするときは csproj の Version を更新してください。

dotnet pack WebI.KzdLib.Symbol/WebI.KzdLib.Symbol.csproj -c Release

テスト実行

dotnet test WebI.KzdLib.Symbol.slnx -c Debug

Visual Studio のテスト エクスプローラーからも実行できます。 テストは CenterSymbol.Draw の出力を Tests/Bitmaps/R*.png と 1 ピクセル単位で比較するため、描画ロジックを変更した場合は参照画像の更新も併せて行ってください。

ライブラリの使い方

シンボルファイルの列挙

シンボルフォルダー (既定: C:\Program Files (x86)\WebI\kouteizu\symbol、レジストリ HKLM\Software\WebI\Kouteizu\DIR_SYMBOL で上書き可) から、指定したプレフィクスを持つ EMF ファイルを列挙します。

using WebI.KzdLib.Symbol;

// 中シンボル ("C" プレフィクス)
foreach (var f in SymbolService.GetSymbolFiles(SymbolService.CenterSymbolPrefix))
{
    Console.WriteLine($"{f.Index}: {f.Path}");
}

// 左右シンボル ("LR" プレフィクス)
var lrFiles = SymbolService.GetSymbolFiles(SymbolService.LeftRightSymbolPrefix);

WPF に表示する (BitmapSource)

BitmapSource source = SymbolService.ToBitmapSource(path, width: 64, height: 32);
image.Source = source;

SymbolFile 経由でも同じことができます。

var symbolFile = SymbolService.GetSymbolFiles("C").First();
image.Source = symbolFile.ToBitmapSource(64, 32);

結果は (path, width, height) をキーとしてプロセス内にキャッシュされます。

GDI+ で描画する (Graphics)

using (var bmp = new Bitmap(200, 32))
using (var g = Graphics.FromImage(bmp))
{
    SymbolService.DrawImage(g, path, x: 0, y: 0, width: 200, height: 32);
    bmp.Save("out.png");
}

ISymbol インスタンスは path をキーとしてキャッシュされます。

色を指定して描画する

DrawImage / ToBitmapSource には System.Drawing.Color を受け取るオーバーロードがあります。線(黒)を指定色に置換し、EMF が白で塗った面は白のまま、背景は透明になります。color.A は線部分の不透明度にのみ効きます。

var color = Color.FromArgb(255, 0, 120, 215); // 不透明の青

// GDI+ / WPF いずれも色指定オーバーロードあり
SymbolService.DrawImage(g, path, 0, 0, 64, 64, color);
BitmapSource colored = SymbolService.ToBitmapSource(path, 64, 64, color);

背景が透明なので、他のイメージへ重ねて使えます。色版の BitmapSource は (path, width, height, color) をキーにキャッシュされます。描画例は ユーザーガイド を参照してください。

シンボルの種類について

• 中シンボル (CenterSymbol, "C" プレフィクス) EMF を 32×32 にラスタライズし、上下左右の枠と中央の繰り返しパターンを解析して 9 スライス的に再描画します。任意の幅・高さに対して、枠の太さを保ったまま中央部だけを拡張できます。 縦の高さが BitmapDivider.FIXEDH (= 10) 以下の場合は中央部を縦タイリングせず、垂直中央に配置します。
• 左右シンボル (LeftRightSymbol, "LR" プレフィクス) EMF を指定矩形に引き伸ばして描画します。線で囲まれた閉領域は白で塗ります。

シンボル色の取得

SymbolService.GetSymbolColors() は組み込みの 19 色 (Index 0–18) を返します。 オプションフォルダー (既定: %APPDATA%\WebI\Kouteizu\option、レジストリ DIR_OPTION で上書き可) に TEXT_COLOR.csv がある場合、その内容をマージして返します。同じ Index の行は組み込み色を上書きし、0–18 以外の Index (例: 19–43) の行は追加の色として返されます (Index に上限はありません)。

CSV のフォーマット (1 行 1 色):

<Index>,<未使用>,<R>,<G>,<B>

5 カラム未満の行や数値変換に失敗した行は無視されます。CSV 読み込み中に発生した例外も無視され、組み込み色のみが返ります。返されるリストは Index 昇順で、CSV の色は常に不透明 (A=255) として扱われます。

利用者側のユニットテスト (フォルダーの上書き)

SymbolService.SymbolFolder / SymbolService.OptionFolder に値を設定すると、レジストリ (DIR_SYMBOL / DIR_OPTION) や既定パスより優先してそのフォルダーが使われます。利用者側のユニットテストで、手元のフィクスチャ EMF や TEXT_COLOR.csv を置いたフォルダーを指すために使えます (null を設定すると既定の解決に戻ります)。

// テスト初期化: 手元のフィクスチャを置いたフォルダーを指す
SymbolService.SymbolFolder = @"TestFixtures\Symbols";   // GetSymbolFiles がここを列挙
SymbolService.OptionFolder = @"TestFixtures\Option";    // GetSymbolColors がここの TEXT_COLOR.csv を読む

var files = SymbolService.GetSymbolFiles(SymbolService.CenterSymbolPrefix);
var colors = SymbolService.GetSymbolColors();

// テスト後始末: 上書きを解除して既定の解決に戻す
SymbolService.SymbolFolder = null;
SymbolService.OptionFolder = null;

なお ToBitmapSource / DrawImage / IsLeftRightSymmetric / MakeBitmapFromEmf は EMF のパスを直接受け取るため、フォルダーを上書きしなくても手元のファイルパスを渡してテストできます。上書きが必要になるのは、フォルダー解決に依存する GetSymbolFiles / GetSymbolColors を使う場合です。

解決順序は 上書き → レジストリ → 既定パス です。上書きはプロセス全体の静的な状態なので、テスト間で確実に解除してください (単一スレッド前提)。

設定 (レジストリ)

いずれも HKEY_LOCAL_MACHINE\Software\WebI\Kouteizu (32 ビットビュー) を参照します。

開発上の注意

• SymbolService の静的キャッシュ (dict, symbolDict) は スレッドセーフではありません。UI スレッドからの利用を前提としています。
• CenterSymbol / LeftRightSymbol は IDisposable ですが、SymbolService がキャッシュしたインスタンスは Dispose されません。これを変更する場合はキャッシュ戦略も併せて見直してください。
• BitmapDivider の判定は 0xFF000000 完全一致の黒ピクセルに依存しています。アンチエイリアスが乗った EMF を入力すると分割が崩れます。
• 公開メンバーの XML ドキュメントコメントは日本語で記述するスタイルに揃えてください。
• PresentationCore / WindowsBase に依存しているため、サービスやヘッドレス環境では動作しません。

ライセンス

© Web I Laboratories, Inc.