画像をMZ-700のキャラグラに変換する「MZ-700 Gaphic Converter」

概要

画像をMZ-700のキャラグラに変換するプログラムです。GUIとCLIの両方を利用できます。

• 絵心はないけど、MZ-700でキャラグラの絵を表示してみたい。
• 昔、キャラグラを書いたのだけど、編集可能な CGE7形式のファイルをなくしてしまい、画像だけ残っている。
• キャラグラエディタ CGE7で書いたキャラグラをバイナリとしてマシン語プログラムに組み込みたい。
• MZ-700にキャラグラで動画再生させたい。
• CGE7 や Magic.MapEditor との間でコピペして編集した後に他の形式で保存したい。

そんな用途に使えます。
たぶん。

ダウンロード

1. 起動と動作環境

Windows 11 と.NET 10 Desktop Runtimeが必要です。ソースからビルドする場合は.NET 10 SDKを使用します。

現在のRelease版は、リポジトリのルートから次のコマンドで起動できます。エクスプローラーから実行ファイルを開いても起動できます。

.\publish\MZ700GraphicConverter.exe

引数なしで起動するとGUI、引数を付けるとCLIになります。

フォントデータの準備（必須）

フォントデータは配布物に同梱していません。利用者自身で作成・用意してください。 次の少なくとも一方を実行ファイルと同じフォルダーに置きます。

日本語版のデータ作成は、AKDさんの「MZ-700WIN フォントデータの作成」を参考にしてください。欧州版を使用する場合も、自身で用意したデータを上記の名前で配置してください。 各ファイルには512文字×8バイトの4096バイト以上のデータが必要です。

• 両方ある場合はGUIのFONT欄でJP／EUを選択できます。初期値はJPです。
• 片方だけある場合は、そのフォントを自動的に使用し、FONT欄は選択できなくなります。保存済み設定がもう一方のフォントを指定していても、利用可能な方を使います。
• 両方ない場合でもGUIは起動しますが、変換・画面表示にはフォントが必要です。画面下部と読み込み時のメッセージで準備方法を案内します。配置後に画像を読み込むと再検出します。
• CLIも、-JP／-EUで指定したフォントがなく、もう一方がある場合は利用可能な方を使用します。指定省略時も同じです。両方ない場合は標準エラーに案内を出し、終了コード1で終了します。--helpはフォントなしでも利用できます。

GUIは終了時のウィンドウ位置・サイズ・最大化状態、3つの表示領域の配置・分割位置と、「変換方法」のチェック状態をUI設定として保存し、次回起動時に復元します。全方式OFFも保存・復元します。UI設定の保存に「設定を保存」を押す必要はありません。 最小化したまま終了した場合は最小化状態を保存せず、その前の通常表示または最大化状態で開きます。 モニター構成が変わって保存位置が画面外になった場合は、現在の画面の作業領域内に調整します。 設定はユーザーごとの %LOCALAPPDATA%\MZ700GraphicConverter\window-placement.json に保存します。 初期位置・サイズへ戻す場合は、アプリを終了した状態でこの設定ファイルを削除してください。登録したパラメータ設定も削除されるため、必要なら先にこのファイルをバックアップしてください。

ソースからGUIを起動する場合:

dotnet run --project .\MZ700GraphicConverterCs\MZ700GraphicConverterCs.csproj

別ディレクトリ・別PCへの配置

現在のRelease版は.NETランタイムを含まない配布形式です。 別ディレクトリに配置する場合は、次のフォルダーから以下の8ファイル（実行用6ファイルとライセンス表示2ファイル）をコピーし、すべて同じディレクトリに置いてください。フォントデータはこの一覧に含まれず、利用者自身で別途用意する必要があります。

コピー元: リポジトリのルートにある publish フォルダー

MZ700GraphicConverter.exe
MZ700GraphicConverter.dll
MZ700GraphicConverter.deps.json
MZ700GraphicConverter.runtimeconfig.json
CG_VIEWER.mzt
PhotoSauce.MagicScaler.dll
MagicScaler-LICENSE.txt
MagicScaler-NOTICES.txt

コピー先の MZ700GraphicConverter.exe を起動します。実行ファイルだけをコピーしても動作しません。

• MZ700GraphicConverter.pdb はデバッグ用なので、通常の実行には不要です。
• CG_VIEWER.mzt はビューアー付きMZT保存に使用します。この機能を使わなければ省略でき、実行用は5ファイルです（ライセンス表示2ファイルは同梱してください）。これとは別に、フォントデータが少なくとも1ファイル必要です。
• dotnet publish はフォントデータをコピーしません。配布するときも MZ700FON.DAT と MZ700FON_EU.DAT は含めないでください。過去の出力先に残っている場合は配布物から取り除いてください。
• PhotoSauce.MagicScaler.dll はLanczos3・面積平均・Catmull-Romの処理に使用します。既存の配置先へもコピーしてください。
• 移動先のPCには .NET 10 Desktop Runtime（x64） が必要です。SDKは不要です。通常の.NET Runtimeだけではなく、Windows Formsを含むDesktop Runtimeを使用してください。
• ソースコード、テストプロジェクト、obj フォルダーは実行時に不要です。
• ウィンドウ位置などの設定は %LOCALAPPDATA%\MZ700GraphicConverter に保存します。インストール先にコピーする必要はありません。

2. GUIの基本操作

最初の変換

1. ファイルをウィンドウにドラッグ&ドロップして読み込みます。クリップボードの画像・対応テキストはCtrl+Vで貼り付けます。
2. 初回は4方式すべてにチェックが入り、以降は前回終了時のチェック状態を復元します。画像読込時にONの方式を変換します。保存・コピー対象の初期値は「単純パターンマッチ(改)」です（OFFならONの先頭方式が対象になります）。
3. 必要に応じて範囲、出力サイズ、閾値、彩度、自動レベル補正を調整します。変更は選択中の全方式に反映されます。 数値を直接入力した場合は、別の入力欄やウィンドウ内の空白・ラベル部分をクリックすると確定し、変換結果に反映されます。
4. 比較したい変換方式にチェックを入れます。
5. 保存したい結果画像、または結果上部の方式名をクリックして選択します。
6. 「PNG保存」などの保存ボタンを押し、出力先を指定します。

画像入力はBMP、PNG、JPEG、GIFに対応します。CGE7の .txt、M7Rの .m7r、本ツールのビューアー付き .mzt も読み込めます。 これらの画面データは画像から再変換せず、その内容を表示します。範囲指定や画像補正を行うには元の画像を読み込んでください。

CLI引数の表示と設定の保存

画面上部に、現在の設定をCLI引数形式で表示します。数値の直接入力は確定時に反映されます。 「引数をコピー」で、この引数を通常のテキストとしてクリップボードへコピーできます。 入力・出力ファイル名や保存形式は含まないため、CLIで実行する場合は追加してください。

.\publish\MZ700GraphicConverter.exe -JP -c pmm -tr 127 -tg 127 -tb 127 -resize_mode 0 -resize_filter bicubic -screen_size 40 25 -saturation 100 -z 1 -o png -O output.png input.png

• 表示・コピーする -c は、右側で保存・コピー対象として選んだ1方式です。GUIで4方式をチェックしていても、CLIは指定された1方式だけを変換します。
• 有効な補正だけを引数に含めます。無効な補正の強度・中間調なども、プリセットには保存します。
• 範囲指定と回転・反転も含みます。GUIの範囲は加工後の座標ですが、CLI用には元画像の座標へ戻して出力するため、同じ元画像に適用できます。
• 「設定を保存」で名前（最大80文字）を入力すると、最大10件まで登録できます。同名なら確認後に上書きします。10件登録済みでも同名の上書きは可能です。
• 上部のプルダウンで名前を選ぶと、保存したパラメータ・保存対象方式・PNG倍率・回転／反転・選択範囲を読み込み、一括で反映します。「変換方法」のチェック状態はプリセットの保存対象ではなく、現在のUIの状態を維持します。
• 読み込み時、保存対象の方式（CLI引数の -c に相当）が現在OFFなら、その方式だけを追加でONにします。他の方式のチェック状態は変えません。旧版のプリセットにチェック状態が含まれていても無視します。CLIの変換は従来どおり -c の1方式のみです。
• 別の大きさの画像へ適用する場合、選択範囲は画像内に収まるよう調整します。画像を読み込む前に設定を選んだ場合は、次に読み込む画像へ回転／反転と範囲を適用します。
• 「設定を削除」で、選択した登録設定を確認後に削除できます。現在のパラメータ自体は変更しません。

保存先はウィンドウ位置と共通の %LOCALAPPDATA%\MZ700GraphicConverter\window-placement.json です。 画像ファイルそのものやパス、表示領域の配置はプリセットに登録しません。配置は別途UI設定として同じファイルに保存します。以前の位置・サイズだけの設定ファイルもそのまま読み込めます。 起動時は従来の初期パラメータを使用し、保存済み設定を自動では読み込みません。

変換対象の範囲

「画像加工」の枠内で範囲を指定します。座標は画面に表示している元画像のピクセル座標で、左上が X=0, Y=0 です。

• 元画像上をドラッグすると、変換対象の矩形を指定できます。
• 選択範囲の内側からドラッグすると、幅・高さを変えずに位置だけを移動します。画像の端では移動が止まります。
• 範囲の外側からドラッグすると、新しい範囲を指定できます。
• 「範囲 X」「範囲 Y」「範囲 幅」「範囲 高さ」から数値で指定することもできます。値は画像内に収まるように調整されます。
• 「全範囲」で画像全体に戻し、選択枠の角度も0度にします。この状態では画像内のどこからでも新しい範囲を作れます。
• ファイルを読み直す場合は、同じファイルをもう一度ドラッグ&ドロップします。全範囲に戻り、変換方式のチェックと補正設定は維持します。

変換は、指定した範囲を切り出してから行います。選択範囲を移動した結果は、ドラッグ終了時に反映されます。

選択枠の角度

「画像加工」の「角度 °」で、選択枠の中心を軸に 0～360度を1度単位で指定できます。時計回りが正方向で、360度は0度と同じです。 元画像自体を回す操作ではなく、選択枠だけを傾け、傾いた範囲をまっすぐな四角へ切り出します。「文字変換直前」で結果を確認できます。

選択枠の青い辺につながる青い丸をドラッグして回転することもできます。ドラッグ中は枠・角度欄・CLI引数表示を更新し、マウスを離した時に「文字変換直前」と変換結果へ反映します。重い変換処理はドラッグ中には繰り返しません。 画像外の余白にある丸も操作できます。回転した枠が表示領域からはみ出す場合も、丸は操作できる位置に表示します。

• 青い辺が、切り出した画像の上辺になります。例えば30度と210度は同じ場所を選びますが、結果は上下逆になります。
• 中心は X + 幅 / 2, Y + 高さ / 2 です。X・Y・幅・高さは傾ける前の矩形を表し、回転しても切り出す画像の幅・高さは変わりません。
• 傾けた枠の内側をドラッグすると、サイズと角度を保って移動します。外側のドラッグでは新しい矩形を作り、角度は維持します。
• 基準の矩形は画像内に収めますが、回転した角が画像の外へ出ることは許可します。外側は黒で補います。
• 「全範囲」と新しい画像の読み込みで角度を0度に戻します。プリセットを画像より先に読み込んだ場合は、保存した範囲と角度を次の画像へ適用します。
• 「パラメータリセット」では範囲と角度を変更しません。プリセットには角度も保存します。CLI引数表示・コピーにも反映します。

回転した範囲を切り出す際の補間は、「最近傍法」なら最近傍、「バイリニア」なら高品質バイリニア、それ以外はGDI+の高品質バイキュービックを使います。Lanczos3・面積平均・Catmull-Romは、その後の拡大・縮小に適用します。角度0度・360度では回転用の補間をしません。

回転と反転

「画像加工」のボタンで、変換前画像全体に次の操作を適用できます。

回転・反転に合わせて選択範囲も移動し、同じ画像部分を選択した状態を維持します。90度回転では画像と選択範囲の幅・高さが入れ替わります。 加工後の画像に合わせて範囲の数値を更新し、チェック中の全方式で再変換します。補正・彩度の設定は維持します。 加工は内部の画像に適用するため、元の画像ファイルは変更しません。ファイルをもう一度ドラッグ&ドロップするか、元画像をCtrl+Vで貼り付け直すと、加工前の状態から読み込み直せます。 回転・反転は画像入力時に使用できます。CGE7・M7R・MZTなどの画面データには適用しません。

パラメータ

出力サイズはピクセル数ではなく文字数です。 1文字は8×8ピクセルなので、40×25文字で320×200ピクセルになります。

左側上部の「MZ-700変換」枠内はR閾値／FONT、G閾値、B閾値、リサイズ、補間方式、出力幅／出力高さの順です。 PNG倍率は保存操作の設定として「PNG保存」のすぐ上に配置しています。 「画像加工」は、範囲X／Y、幅／高さ、角度／全範囲、左右90度回転、上下／左右反転の順に幾何操作を配置し、その下に自動調整、淡色補正、自動レベル補正、彩度をまとめています。「全範囲」と「自動調整」は別の行です。自動レベル補正と彩度も別々の行に配置しています。 淡色補正の強度と補正方式は、その従属パラメータとして右側に揃えています。

補間方式、淡色補正とその強度・補正方式、自動レベル補正とその強度・中間調、彩度は、マウスを約0.5秒置くと説明が表示されます。 項目名や入力欄の上でも表示します。補間方式と淡色補正方式の説明は現在選択中の方式に合わせて切り替わります。

「画像加工」の最下段にある「パラメータリセット」は、自動レベル補正・淡色補正をOFF、両補正の強度を100%、レベル補正の中間調を50%、淡色補正方式をRGB、彩度を100%に戻し、チェック中の方式で再変換します。 選択範囲・角度と範囲の入力値はリセットしません。範囲を画像全体・角度0度へ戻す場合は「全範囲」を使ってください。 RGB閾値、FONT、リサイズ、補間方式、出力幅・高さ、変換方法のチェック、PNG倍率は変更しません。 回転・反転済みの画像自体は元に戻しません。画像を加工前に戻す場合は、元ファイルを読み込み直すか、元画像を貼り付け直してください。 画面データのみ読み込んでいる場合は設定だけをリセットし、表示中の画面データは維持します。

閾値が小さいほど、その色がONになりやすくなります。メッシュ変換ではRGB閾値を使用せず、8×8ピクセルの平均色を固定の境界値で変換します。

自動レベル補正の右側に専用の「強度 %」、その下に「中間調 %」があります。淡色補正側の強度とは独立しています。 強度100%、中間調50%が従来の動作です。補正が強すぎる場合は強度50%程度から、明るすぎる場合は中間調40%程度から調整してください。 GUIでは数値変更だけで自動レベル補正をONにしません。適用するにはチェックを入れます。 黒側・白側のクリップ率は各1%のままです。中間調はRGB共通ヒストグラムの中央値を基準にガンマを決める目標値で、過剰補正を避けるためガンマは0.7～1.4に制限します。 階調幅が小さい一様な画像では補正を行わず、中央値が極端な画像ではガンマ補正を省略します。目標値どおりの明るさになる保証はありません。

明るいイラストや淡い色が白くつぶれる画像には、「画像加工」の「淡色補正」を試してください。 選択範囲のヒストグラムを均等化して、明るい部分に集中した階調を広げます。 淡色補正の右に「強度 %」、その下の右側に方式の選択欄があります。強度は0～100%で、補正前後を混ぜて調整します。 「RGB」は従来のRGB共通ヒストグラム方式です。「明暗のみ」は輝度から補正曲線を作り、RGB間の差を増幅しません。 明暗のみでも白黒にはせず、元の色の差を維持します。ただし黒・白付近でRGBの範囲を超える場合は色の差を縮めます。 白に近い背景が紫になる画像では、まず「明暗のみ」、強度50%程度から試してください。 自動レベル補正とは独立して使用でき、両方を選択した場合は自動レベル補正の後に適用します。 元画像ファイルは変更しません。色や明暗の印象が強く変わることがあるため、初期状態ではOFFです。 補正済み画像は内部で保持し、変換方法を追加しただけでは補正をやり直しません。 8色・文字パターンの制約があるため、細い輪郭や元画像のすべての淡色を再現できるわけではありません。

自動調整

「画像加工」の「自動調整」を押すと、現在の選択範囲を分析し、補正設定を選んで再変換します。 GUIでは保存・コピー対象として選択中の変換方法、現在のRGB閾値・彩度を使って判断します。 レベル補正ON/OFFと、淡色補正なし／明暗のみ25・50・75・100%を縮小画像で比較します。 レベル補正の候補には現在指定されている強度・中間調を使い、自動調整後もこの2つの値を維持します。 8色化（メッシュは段階的な色分け）で失われる明暗・色の差、黒潰れ・白飛び・色の変化を評価し、改善が小さい場合は補正なしを選びます。 白い領域が多いことだけを理由に補正を強めることはありません。

選ばれた設定はチェックボックス・強度・補正方式に反映し、下部に表示します。その後は通常どおり手動で変更できます。 GUIはボタンを押した時点での一回限りの分析です。別画像の読み込み、範囲・閾値変更後に再判断したい場合は、もう一度押してください。 範囲、出力サイズ、閾値、彩度、変換方法のチェックは自動調整で変更しません。元ファイルも変更しません。 判定は縮小画像の画素による近似評価で、文字パターンの全候補を試すものではありません。最適な見た目を保証するものではないため、結果を確認して微調整してください。

横いっぱい・縦いっぱいでは左上に配置し、出力枠を超える部分は切り捨て、余る部分は黒で埋めます。 そのままサイズでは幅・高さをそれぞれ8ピクセル単位に切り上げ、端の余りを黒で埋めます。

補間方式

元画像を変換用のサイズへ拡大・縮小する際のアルゴリズムを、「MZ-700変換」の「補間方式」で選択します。 「リサイズ」は縦横比・配置を決める設定、「補間方式」は画素の計算方法を決める独立した設定です。

縮小だけでなく拡大にも適用します。同じサイズの場合はリサイズせず、「そのままサイズ」では元の画素を維持します。 範囲指定・回転・反転・レベル補正・淡色補正の後に適用し、彩度調整の前に実行します。 選択方式は自動調整の縮小分析にも使用します。方式変更時は内部の準備画像を更新しますが、変換方法を追加するだけでは縮小し直しません。 右側のプレビュー表示やPNG保存倍率の拡大方式は変更しません。PNG倍率は従来どおり最近傍法です。 Lanczos3・面積平均・Catmull-Romには PhotoSauce.MagicScaler を使用し、自動シャープ化と中間サイズへの簡易縮小は無効にしています。RGB値のまま補間する設定で、追加の明るさ補正は行いません。

変換方式の比較

初期配置では右側の変換結果の上に「文字変換直前」の画像を表示します。 範囲指定・回転／反転・レベル補正・淡色補正・選択した補間方式による拡大縮小・彩度調整を適用した、文字パターン判定とRGB閾値での8色化より前の画像です。 320×200ピクセル以下は原寸で、それより大きい場合は表示枠に合わせて表示します。見出しに実際のピクセル寸法を表示します。 他の表示領域と上下に並んでいる場合は、画像サイズと表示幅に合わせてこの領域の高さを自動調整し、残りの高さを隣の領域に割り当てます。配置変更・画像サイズ変更・ウィンドウサイズ変更にも追従します。 変換方式をすべてOFFにしても加工後の画像を確認できます。RGB閾値やFONTだけを変えても、この画像自体は変わりません。 内部の準備画像を共有し、方式を追加しただけでは画像加工や表示用コピーをやり直しません。 TXT・M7R・MZTやクリップボードの画面データは元画像がないため、この欄を表示しません。 保存・コピーの対象は従来どおり、選択したMZ-700変換結果です。「文字変換直前」の画像をクリックしても保存対象は切り替わりません。

表示領域のレイアウト

「元画像」「文字変換直前」「MZ-700変換結果」の各領域の見出しをドラッグして、配置と並び順を変更できます。

• 移動先の領域の左・右・上・下の端にドロップすると、その側に配置します。
• 移動先の中央にドロップすると、2つの領域の位置を交換します。
• ドラッグ中の青い領域が配置先の目印です。
• 領域間の境界線をドラッグすると、それぞれの幅・高さを調整できます。
• 見出しを右クリックし「レイアウトを初期化」を選ぶと、元画像が左、文字変換直前と変換結果が右の初期配置に戻します。

移動やサイズ調整で再変換は行わず、画像・範囲指定・保存対象を維持します。画像の読み込みは、各表示領域へのファイルのドラッグ&ドロップでも利用できます。 レイアウトの配置・分割位置は終了時にUI設定として保存し、次回起動時に復元します。画像をまだ読み込んでおらず「文字変換直前」が非表示の場合も、配置情報は保持します。 「文字変換直前」は移動直後も画像と見出しに必要な高さへ調整します。320×200以下は原寸表示できる高さにし、元画像の上に移動しても余分な縦幅を取らないようにします。画面が狭い場合は領域の最小サイズが優先されます。 「レイアウトを初期化」で戻した配置も終了時に保存されます。保存先は他のUI設定と同じ %LOCALAPPDATA%\MZ700GraphicConverter\window-placement.json です。 元画像のない画面データを読み込んでいる間は、文字変換直前の領域を折りたたみます。

「変換方法」の枠内で、チェックを入れた方式の結果を表示します。4方式すべてにチェックを入れると4枚を比較できます。 チェックOFFの方式の表示枠は空けず、ONの結果だけを方式順に詰めて表示します。結果欄の横幅に合わせて1～4列で左から右、次の行の順に並び、必要な行数だけを使用します。 GUIはUI設定がない初回だけ4方式すべてONで、以降は前回終了時のチェック状態を復元します。CLIではGUIのチェック状態に関係なく、-cで指定した1方式のみ変換します。省略時はpmmのみで、他方式の比較処理は行いません。 すべてのチェックを外すと、変換結果と保存・コピー対象がなくなります。

起動時は結果欄を1列分の幅にして、元画像の表示領域を広く確保します。 元画像と結果欄の境界をドラッグして結果欄を広げると、横幅に収まる枚数に応じて列数が増えます。「MZ-700変換結果」を上や下に配置した場合も同じで、横4枚分の余裕があれば4方式を1行に並べます。横2枚分の場合は次の2行2列になります。

チェックを外した方式の位置は空欄になります。結果欄に収まらない部分はスクロールできます。横3枚分なら1行目にpm → pmm → semi、2行目に mesh を表示します。横1枚分なら `pm` → `pmm` → `semi` → `mesh` の1列4段になります。 チェックを外した方式の分は詰めて表示します。結果欄に収まらない部分はスクロールできます。

320×200ピクセル以下の結果は縮小せず原寸で表示し、大きい結果は表示枠に合わせます。 ウィンドウを横に広げると、その分だけ元画像の表示領域が広がります。元画像と結果の境界はドラッグして調整できます。

保存とクリップボード

結果上部の選択印が付いた画像が、保存・コピーの対象です。切り替えるには結果画像か方式名をクリックします。

画像ファイルは読み込み時に内部へ複製し、元ファイルをロックし続けません。PNG保存時に元画像と同じファイル名を選び、上書きを確認した場合も保存できます。 上書き後もGUIの元画像表示と再変換には読み込み済みの元画像を使います。保存したファイルを元画像として使う場合は読み込み直してください。 PNGは一時ファイルへの書き込みを完了してから保存先を置き換えます。他アプリのロック・読み取り専用などで置き換えに失敗した場合は、既存の保存先を残します。 保存失敗時は、保存先と確認事項（他アプリの使用、書き込み権限、空き容量など）を日本語で表示します。元画像を残したい場合は別の名前で保存してください。 CLIの-o png -Oでも入力画像と同じパスを指定できます。CLIには上書き確認ダイアログはありません。

コピーのボタン名は1行表示です。幅に収まらない場合は「で」、さらに必要なら「形式」を省略します（例：テキスト形式コピー／テキストコピー）。マウスを置くと省略前の名前を確認できます。

クリップボード画像は元画像として読み込み、現在チェックしている方式で変換します。 PrintScreen／Alt+PrintScreenなどのWindows標準ビットマップと、PNG形式（PNGまたはimage/png）の画像データに対応します。 .NET 10の型付きAPIで取得し、画像を内部へ複製してから変換するため、クリップボードの内容や提供元の画像・ストリームは変更しません。 クリップボード用テキストは、文字コードと色属性をそのまま復元します。対応テキストと画像が両方ある場合はテキストを優先し、無関係なテキストと画像がある場合は画像を読み込みます。

クリップボード用テキストは、CGE7保存で作るCSVとは異なります。形式は以下のとおりです。

1. 先頭行に10進数で 幅 高さ。
2. 文字コードの下位8ビットを各2桁の16進数で並べます。
3. 続いて属性バイトを各2桁の16進数で並べます。文字コードの上位ビットは属性のビット7に入ります。
4. 文字コード・属性の各領域は、16バイトごとに改行します。

例（2×1文字）:

2 1
FF 00
F7 21

クリップボード用テキストにはJP/EUの種別が含まれません。コピー時と同じFONTを選択して読み込んでください。

3. CLIの基本操作

以下の実行例は、実行ファイルがあるフォルダーで操作する場合の書き方です。パスに空白がある場合は引用符で囲んでください。

.\MZ700GraphicConverter.exe [options] input-file

CLIでは1回につき1方式を指定します。方式を比較する場合は、-c と出力ファイル名を変えて複数回実行します。

初期値はJP（EUのみ配置されている場合はEU）、pmm、40×25文字、RGB閾値127、彩度100%、縦横比無視リサイズ、自動レベル補正なし、PNG倍率1、出力形式 txt です。

全パラメータ

-o（小文字）は形式、-O（大文字）はファイル名なので区別してください。出力ファイルを指定すると、-OD より -O が優先されます。

-bgc の色番号は、0:黒、1:青、2:赤、3:マゼンタ、4:緑、5:シアン、6:黄、7:白です。 mesh ではRGB閾値と -bgc を使用しません。

-crop のX/Yは0以上、幅・高さは正の値で、範囲全体が画像内に収まる必要があります。 回転・反転はコマンドラインに指定した順で適用します。-crop は加工前の元画像の座標で指定し、回転・反転後も同じ画像部分を切り出します。-crop 自体を引数のどこに置いても、この座標の意味は変わりません。 -crop_angle は画像全体の回転・反転が終わった後の選択枠の角度です。引数の位置には依存しません。-crop を省略した場合は画像全体の中心を軸に枠を傾け、画像外は黒で補います。 -resize_mode 3 では、切り出し範囲から出力文字数を自動で決めるため、-screen_size の値は使いません。 画像以外の入力（.txt、.m7r、.mzt）では、画像用の回転・反転・範囲指定・補正・変換方式は適用しません。

出力先に同名ファイルがある場合は上書きします。入力と出力の拡張子が同じ場合は、-O または -OD で出力先を分けてください。

CLI起動時は呼び出し元のコンソールに接続し、進捗・ヘルプは標準出力、エラーは標準エラー出力に表示します。 ファイルやパイプへのリダイレクトも保持し、UTF-8で出力します。コンソールのない場所から引数付きで起動した場合は、CLI用コンソールを作成します。 引数なしのGUI起動ではコンソールを表示しません。 cmd.exeではGUI形式のEXEを起動した直後にプロンプトへ戻る場合があります。完了まで待つ場合は start /wait "" MZ700GraphicConverter.exe ... を使用してください。 同じフォルダーのDLLを dotnet から実行する方法も利用できます。

dotnet .\MZ700GraphicConverter.dll --help

実行例

淡色補正を明暗のみ・強度50%で使用し、指定した1方式だけでPNGを保存:

.\MZ700GraphicConverter.exe -c pmm -pale_mode luminance -pale_strength 50 -o png -O result.png photo.png

-pale_modeまたは-pale_strengthを指定すれば、-pale_correctionの併記は不要です。 従来の補正を再現する場合は-pale_mode rgb -pale_strength 100を指定します。

補正設定を自動で選ぶ場合:

.\MZ700GraphicConverter.exe -auto_adjust -c pmm -o png -O result.png photo.png
.\MZ700GraphicConverter.exe -F -auto_adjust -threads 4 -o png -OD .\output images.txt

-auto_adjustは-cで指定した1方式だけを対象とし、他方式の変換は行いません。-Fでは画像ごとに独立して判断します。 -cropと回転・反転を指定した場合は、加工後の選択範囲を分析します。画面データ入力（TXT/M7R/MZT）は再変換せず、この指定も適用しません。 自動判断は-auto_levels、-pale_correction、-pale_strength、-pale_modeの手動指定より優先します（引数の順序によらず）。 ただし-levels_strengthと-levels_midtoneの値は自動判断でも使用し、上書きしません。自動判断によりレベル補正がOFFに選ばれた場合は適用しません。 閾値・彩度・サイズなどは指定した値を維持します。手動補正を使う場合は-auto_adjustを省略してください。 一括処理の進捗は従来どおり完了枚数(n/m)のみです。

レベル補正を控えめ・暗めに調整する場合:

.\MZ700GraphicConverter.exe -levels_strength 50 -levels_midtone 40 -o png -O result.png photo.jpg

どちらかのパラメータを指定すれば-auto_levelsの併記は不要です。-Fでも同じ値を各画像に適用します。

Lanczos3で変換する場合:

.\MZ700GraphicConverter.exe -resize_filter lanczos -c pmm -o png -O result.png photo.jpg
.\MZ700GraphicConverter.exe -resize_filter catmullrom -c pmm -o png -O result.png illustration.png
.\MZ700GraphicConverter.exe -F -resize_filter area -o png -OD .\output images.txt

省略時は従来のバイキュービックで、指定した変換方式だけを処理します。画面データ入力（TXT/M7R/MZT）には補間方式を適用しません。 明暗のみでも8色への変換時に一部の色が強く出ることがあり、色の変化が完全になくなるわけではありません。

標準の pmm でCGE7テキストに変換:

.\MZ700GraphicConverter.exe -o txt -O result.txt photo.jpg

範囲を指定して自動補正し、2倍のPNGに保存（出力は640×400ピクセル）:

.\MZ700GraphicConverter.exe -crop 100 50 640 400 -auto_levels -o png -z 2 -O result.png photo.jpg

メッシュ変換でMZTに保存:

.\MZ700GraphicConverter.exe -c mesh -o mzt -O result.mzt photo.jpg

右へ90度回転してから左右反転し、自動補正してPNGに保存:

.\MZ700GraphicConverter.exe -rotate right -flip horizontal -auto_levels -o png -O rotated.png photo.jpg

左回転は -rotate left、上下反転は -flip vertical です。 -rotate right -flip horizontal と -flip horizontal -rotate right は加工順が違うため、結果も異なります。

EUフォント、横いっぱいリサイズ、閾値・彩度の指定:

.\MZ700GraphicConverter.exe -EU -c pm -resize_mode 1 -screen_size 40 25 -tb 110 -tr 130 -tg 120 -saturation 130 -o m7r -O result.m7r photo.jpg

リサイズせず、指定範囲を変換:

.\MZ700GraphicConverter.exe -crop 0 0 160 80 -resize_mode 3 -o png -O crop.png photo.jpg

選択枠を中心の周りに30度傾けて変換:

.\MZ700GraphicConverter.exe -crop 100 50 640 400 -crop_angle 30 -o png -O tilted.png photo.jpg

この例では20×10文字、160×80ピクセルの結果になります。

M7Rの内容をPNGに出力:

.\MZ700GraphicConverter.exe -o png -O restored.png screen.m7r

一括変換

-Fでは複数画像を並列に変換します。-threads 4で同時処理数を最大4に制限し、-threads 1でリスト順の逐次処理になります。 省略時は4ワーカーで、CPUの論理コア数が4未満の場合はその数が上限です。画像枚数より多くのワーカーは使いません。 -threadsを明示した場合は4より大きな値も指定できます。単一ファイル指定では常に1画像だけを処理します。 大きな画像でメモリ使用量が多い場合は、-threads 2などに減らしてください。

進捗は同じ行に (完了枚数/総枚数) だけを上書き表示し、画像ごとには改行しません。 最初に (0/総枚数) を表示し、保存が完了するたびに完了数を増やします。最後にだけ改行します。 Processing／Completedや画像名の行は表示しません。並列処理でも完了数は順に増えます。 空行・空白だけの行は件数に含めません。通常の単一ファイル変換にはこの進捗表示を追加しません。

(12/20)

標準出力をファイルやパイプへ送る場合も、同じ改行しない進捗を出力します（上書き用の復帰文字 \r を含みます）。 出力先の重複による逐次処理への切り替え通知やエラーは標準エラー出力へ送ります。

並列変換の例:

.\MZ700GraphicConverter.exe -F -threads 4 -c pmm -o png -OD .\output images.txt

各ワーカーの変換器と画像ごとの設定は独立しています。GUIの4方式比較は実行せず、-cで指定した1方式だけを変換します。 出力パスが重複する場合（同じ -O、同名画像を同じ -ODへ出力する場合など）や、出力先が一覧内の入力と重なる場合は、自動で1ワーカーに切り替えます。 この場合はリスト順に処理し、最後の画像の結果が残る従来の上書き動作を維持します。 失敗した場合は対象ファイル名を表示してエラー終了します。既に出力したファイルは残り、実行中のほかの処理が完了する場合があります。

Shift-JISのテキストファイルに、入力ファイルのパスを1行ずつ書きます。相対パスは一覧ファイルのあるフォルダーを基準に解決します。 空行は無視します。パスの前後に引用符は付けず、コメント行も入れないでください。

images.txt の例:

photo1.jpg
pictures\photo2.png
E:\Images\photo3.bmp

.\MZ700GraphicConverter.exe -F -auto_levels -o png -OD .\output images.txt

同じ設定で各画像を変換し、output に入力と同じベース名のPNGを作ります。 一括変換で -O を指定すると全入力が同じファイルに上書きされるため、通常は -OD を使用します。 入力のベース名が同じ場合も出力名が重複します。-crop を使う場合は、その範囲が一覧の全画像に収まるように指定してください。

4. 自動補正と処理の順序

画像の処理順は、選択枠の角度を反映した範囲の切り出し → 自動レベル補正 → 淡色補正 → リサイズ → 彩度調整 → MZ-700変換です。 CLIで回転・反転を指定した場合は、切り出し前に画像全体へ指定順で適用し、範囲の座標も画像に合わせて移動します。

自動レベル補正では、選択範囲のRGB値の下位・上位1%を基準に明暗を広げ、中間調を穏やかに調整します。 RGB共通の階調カーブを使い、明暗差が小さい画像は補正を省略します。

GUIは補正・リサイズ済み画像と方式別の結果を内部に保持します。方式を追加すると追加方式だけを変換し、再チェックでは保持済み結果を再利用します。 閾値・フォントの変更では変換結果を、画像・範囲・出力サイズ・リサイズ・彩度・補正設定の変更では前処理から作り直します。 並びの切り替えや保存対象の選択では再変換しません。

5. 開発・検証

リポジトリのルートからビルド:

dotnet build .\MZ700GraphicConverterCs\MZ700GraphicConverterCs.csproj

Release版の作成（リポジトリ直下の固定の publish フォルダーに出力）:

dotnet publish .\MZ700GraphicConverterCs\MZ700GraphicConverterCs.csproj -c Release -r win-x64 --self-contained false

PublishDirはプロジェクトで固定しています。更新時も同じ publish フォルダーを上書きし、publish-XXXX のようなフォルダーは増やしません。 上書き対象の実行ファイルを起動している場合は、アプリを終了してから発行してください。

bin\Release\net10.0-windows\win-x64 はコンパイル時の出力で、publish は配布・インストール用に必要なファイルをまとめる出力です。 dotnet publish は先にビルドしてから配布用のファイルを集めるため、通常は両方に実行ファイル群ができます。 別の場所へインストールする場合は publish のファイルを使用し、両方のフォルダーをコピーする必要はありません。

機能の検証:

dotnet run --project .\MZ700GraphicConverterCs.Tests\MZ700GraphicConverterCs.Tests.csproj

一括変換の逐次・4ワーカーの時間比較（結果の一致も検証）:

dotnet run --project .\MZ700GraphicConverterCs.Tests\MZ700GraphicConverterCs.Tests.csproj -c Release -- --benchmark-batch

自動レベル補正の旧処理との速度比較:

dotnet run --project .\MZ700GraphicConverterCs.Tests\MZ700GraphicConverterCs.Tests.csproj -c Release -- --benchmark