ptouch_label/ruby/README.md

libptouch（Ruby gem）

ptouch_label の libptouch を ffi 経由で使うための Gem です。

前提

1. リポジトリルートで共有ライブラリをビルドする（libptouch.so が build/ に生成されます）。

   cmake -S .. -B ../build
   cmake --build ../build
   

2. Ruby 3.0 以上と ffi gem。

インストール（開発時）

cd ruby
bundle install   # または gem install ffi
bundle exec rubocop   # 任意: スタイルチェック（.rubocop.yml）
gem build libptouch.gemspec
gem install ./libptouch-1.0.0.gem

ビルド済みの ../build/libptouch.so を自動で読みに行きます。別のパスにある場合は環境変数で指定できます。

export LIBPTOUCH_LIB=/usr/local/lib/libptouch.so

（cmake --install で共有ライブラリをインストールした場合は、通常は libptouch 名でローダが解決します。）

コマンド ptouch-print-png（PNG のみ）

C の ptouch-print と同様の流れですが、PNG 入力のみ（-w/-H や 1bit ラスターは扱いません）。gem install 後は PATH に ptouch-print-png が入ります。

開発ツリーからそのまま試す例:

bundle exec ruby -I lib exe/ptouch-print-png --help
bundle exec ruby -I lib exe/ptouch-print-png -n -f ../samples/your.png

使用例

require "libptouch"

Libptouch::Context.new.tap do |ctx|
  ctx.open_usb
  p ctx.status_bytes.bytesize # => 32
  p ctx.status_hash[:tape_kind]   # => {:code=>..., :label=>"ラミネートテープ"} など
  p ctx.status_hash[:status_kind] # => 状態（ステータス種類）
ensure
  ctx.dispose
end

生の 32 バイトだけある場合は Libptouch.parse_status(raw) で同じ Hash 形式に展開できます（中身は libptouch_status_fprint と同じ区分）。

PNG からラスターへ:

ctx = Libptouch::Context.new
data, w, h = ctx.png_file_to_raster("/path/to/label.png")
ctx.open_usb
ctx.print_raster(data, width_dots: w, height_dots: h, margin_mm: 0)
ctx.dispose

API の範囲

• 実行ファイル ptouch-print-png … PNG のみ（-f, -t, -n, -S, -V, -h）。ステータスは JSON（status_bytes を parse_status したもの、raw_bytes 除く）
• Libptouch::Context … open_usb / open_usb_vid_pid / close / dispose
• check_raster / print_raster / png_file_to_raster / status_bytes / status_hash
• Libptouch.parse_status(raw) … 32 バイトを Hash に展開（機種・テープ幅・テープ種類・色・状態（status_kind）・エラービット・raw_hex など）
• C の libptouch_status_fprint（FILE *）は FFI からはバインドしていません。テキスト出力の代わりに parse_status / status_hash を使ってください。