Ruby と ImageMagick で顔にモザイクをかける
Google Cloud Vision で顔の位置を特定し、RMagick でその領域を目に見えるピクセルのブロックに置き換えます。以下の Ruby プログラムは、EXIF の向きに従って画素を回転させてから Vision に送信し、その同じ画像を編集して、確認用の PNG として保存します。
顔にモザイクをかける理由は?
モザイク処理は顔の細部を見えにくくしますが、検出器が顔を見落としたり、モザイク処理後も人物を識別できたりする場合があります。出力は確認前の候補として扱ってください。画像の端にいる人物も含め、すべての顔を確認し、共有する前に名前、衣服、映り込みなど、人物の特定につながる要素も検討してください。検出のため、元画像は Google に送信されます。
Ruby と ImageMagick のセットアップ
この手順は、MRI Ruby 4.0、JPEG と PNG に対応した ImageMagick 7、その開発用ヘッダー、C++ コンパイラー、make、pkg-config がインストール済みの Linux シェルを対象とします。動作確認済みのバージョンは Ruby 4.0.7、ImageMagick 7.1.2-31、RMagick 7.2.0、google-cloud-vision 2.2.1 です。Ruby のダウンロードページから、保守対象の Ruby パッチバージョンを使用してください。ディストリビューションに必要なシステムパッケージは、RMagick の前提条件を参照してください。gem はそれらのヘッダーを使用してネイティブ拡張をビルドします。
書き込み可能なディレクトリで、次のブロックを実行してください。新しい face-pixelation ディレクトリを作成し、その中に gem を配置します。同名のディレクトリがすでにある場合は、置き換えずにセットアップを停止します。成功した場合も失敗した場合も、親シェルの作業ディレクトリは元のままです。
(
command -v ruby >/dev/null || exit 1
command -v make >/dev/null || exit 1
command -v g++ >/dev/null || exit 1
command -v pkg-config >/dev/null || exit 1
ruby -e 'abort "Use MRI Ruby 4.0" unless RUBY_ENGINE == "ruby" && RUBY_VERSION.start_with?("4.0.")' || exit 1
pkg-config --exists MagickCore || exit 1
mkdir face-pixelation || exit 1
cd face-pixelation || exit 1
GEM_SPEC_CACHE="$PWD/gem-spec-cache" ruby -S gem install \
--install-dir "$PWD/gems" --no-user-install --no-document \
rmagick:7.2.0 google-cloud-vision:2.2.1
)
インストールに失敗した場合は、コンパイラーの診断情報を保存し、不足している前提条件を満たしてから、作成されたディレクトリ内で gem のインストールコマンドを再実行してください。セットアップを成功させるために mkdir を再実行したり、既存のプロジェクトを削除したりしないでください。この例は bundle exec の外で実行してください。この処理設定は、上位のアプリケーションの Gemfile ではなく、専用の gem ディレクトリを使用します。
Google Cloud Vision API のセットアップ
Google の Vision セットアップガイドに従い、課金と Vision API を有効にしたプロジェクトを用意してください。検出は課金対象のクラウド処理です。バッチ処理の前に、プロジェクトの割り当てと上限を確認してください。この例では実行ごとにローカル画像を一つ送信します。Cloud Storage バケットは不要です。
ローカル開発では、Google Cloud CLI をインストールし、Google の ADC の手順に従ってください。gcloud auth application-default login を実行した後、gcloud auth application-default set-quota-project PROJECT_ID を実行し、PROJECT_ID を課金先プロジェクトに置き換えてください。使用する ID には、そのプロジェクトで serviceusage.services.use が必要です。これらの認証情報は、通常の gcloud のログイン認証情報とは別です。
このプログラムは Application Default Credentials を使用します。既存の環境変数 GOOGLE_APPLICATION_CREDENTIALS はローカルの ADC ファイルより優先されるため、意図した認証情報が選択されることを確認してください。このローカル実行例のためにサービスアカウントキーをダウンロードするのは避けてください。Google Cloud のワークロードでは、そのワークロードに関連付けたサービスアカウントを Google は推奨しています。
Google Cloud Vision API を使った Ruby への顔検出の組み込み
破損のない静止画像で、8 ビットの JPEG または PNG を使用してください。色空間は sRGB またはグレースケールとし、透明部分や埋め込み ICC プロファイルを含めないでください。ほかの色空間の画像や透明部分のある画像は、先に不透明な sRGB 画像として書き出してください。入力の上限は 2 MiB、各辺 4,096 ピクセル、総画素数 4,000,000 ピクセルです。また、Vision に送信する正規化済み PNG の上限は 8 MiB です。圧縮された入力は、デコード後にこの後者の上限を超える場合があります。その場合は画像の寸法を小さくして再試行してください。
Vision の顔検出レスポンスのドキュメントでは、顔が一部しか写っていない場合、ポリゴンの座標が欠けることがあると注意しています。Protobuf の整数フィールドは、値が存在しなくてもゼロとして読み取られる場合があります。その最小値と最大値を使うと、誤った領域を選択しかねません。この例は、画像内で順序どおりに並び、幅と高さが正で、座標軸に平行な長方形を形成する四つの頂点だけを受け付けます。完全な長方形であれば、座標ゼロに接していても構いません。不完全、反転、回転したポリゴンや、その他の曖昧なポリゴンがあると、出力を公開せずに実行全体を停止します。長方形を推測せず、その画像を手動で確認してください。
ImageMagick によるモザイク処理
プログラムは受け付けた長方形ごとに領域を切り出し、各軸で元の約 16 ピクセルを一つのピクセルに縮小してから、再び拡大します。RMagick の
sample メソッドは、平滑化フィルターではなくピクセルのサンプリングを使うため、長方形のブロックができます。信頼度の低いものも含め、返されたすべての検出結果を処理します。検出件数がリクエストした上限に達した場合は、レスポンスが不完全な可能性があるため、処理を拒否します。
Ruby コードの実行手順
次のプログラム全体を face-pixelation/pixelate.rb として保存してください。
require 'google/cloud/vision/v1'
require 'rmagick'
require 'tempfile'
class ReviewRequired < StandardError; end
MAX_INPUT = 2 * 1024 * 1024
MAX_REQUEST_IMAGE = 8 * 1024 * 1024
MAX_FACES = 100
def face_rectangle(face, width, height)
points = face.bounding_poly&.vertices
raise ReviewRequired, 'Ambiguous face polygon; review the original' unless points&.length == 4
a, b, c, d = points
valid = a.x == d.x && b.x == c.x && a.y == b.y && c.y == d.y &&
a.x >= 0 && a.y >= 0 && b.x > a.x && c.y > a.y &&
b.x <= width && c.y <= height
raise ReviewRequired, 'Ambiguous face polygon; review the original' unless valid
[a.x, a.y, b.x - a.x, c.y - a.y]
end
def pixelate_region(image, rectangle)
region = small = blocks = nil
x, y, width, height = rectangle
region = image.crop(x, y, width, height, true)
small = region.sample([(width / 16.0).ceil, 1].max, [(height / 16.0).ceil, 1].max)
blocks = small.sample(width, height)
image.composite!(blocks, x, y, Magick::CopyCompositeOp)
ensure
[region, small, blocks].compact.each(&:destroy!)
end
def run(input, output)
raise ReviewRequired, 'Output must have a .png extension' unless File.extname(output).downcase == '.png'
raise ReviewRequired, 'Destination already exists; choose a new path' if File.exist?(output) || File.symlink?(output)
# Bound native pixel caches; this is not a limit on the Ruby process's total memory.
Magick.limit_resource(:memory, 256 * 1024 * 1024)
Magick.limit_resource(:map, 0)
Magick.limit_resource(:disk, 0)
blob = File.open(input, 'rb') { |file| file.read(MAX_INPUT + 1) || ''.b }
raise ReviewRequired, 'Input must contain 1 byte to 2 MiB' if blob.empty? || blob.bytesize > MAX_INPUT
format = if blob.start_with?("\x89PNG\r\n\x1a\n".b)
'PNG'
elsif blob.start_with?("\xff\xd8\xff".b)
'JPEG'
end
raise ReviewRequired, 'Use a JPEG or PNG' unless format
# Conservative marker refusals also exclude APNG and multi-picture JPEG containers.
raise ReviewRequired, 'Use a static, single-picture image' if blob.include?('acTL') || blob.include?("MPF\0")
headers = images = nil
Tempfile.create(['face-input-', ".#{format.downcase}"]) do |file|
file.binmode
file.write(blob)
file.rewind
headers = Magick::Image.ping(file) { |info| info.format = format }
raise ReviewRequired, 'Use a single-frame image' unless headers.length == 1
header = headers.first
unless header.columns.between?(1, 4096) && header.rows.between?(1, 4096) &&
header.columns * header.rows <= 4_000_000
raise ReviewRequired, 'Input exceeds the dimension or pixel limit; resize it first'
end
end
images = Magick::Image.from_blob(blob) { |info| info.format = format }
raise ReviewRequired, 'Use a single-frame image' unless images.length == 1
image = images.first
unless image.depth <= 8 && !image.alpha? &&
[Magick::SRGBColorspace, Magick::GRAYColorspace].include?(image.colorspace) &&
image.color_profile.to_s.empty?
raise ReviewRequired, 'Use an opaque 8-bit sRGB or grayscale image without an ICC profile'
end
image.auto_orient!
image.strip!
image.format = 'PNG'
upright_png = image.to_blob
raise ReviewRequired, 'Normalized PNG exceeds 8 MiB; resize the input first' if upright_png.bytesize > MAX_REQUEST_IMAGE
client = Google::Cloud::Vision::V1::ImageAnnotator::Client.new do |config|
config.rpcs.batch_annotate_images.timeout = 15
config.rpcs.batch_annotate_images.retry_policy = { retry_codes: [] }
config.channel_args = { 'grpc.enable_retries' => 0 }
config.logger = nil
end
response = client.batch_annotate_images(
{ requests: [{ image: { content: upright_png },
features: [{ type: :FACE_DETECTION, max_results: MAX_FACES }] }] }
)
raise ReviewRequired, 'Unexpected Vision response' unless response.responses.length == 1
result = response.responses.first
raise ReviewRequired, 'Vision returned a detection error; check project access' if result.error && result.error.code != 0
faces = result.face_annotations
raise ReviewRequired, 'No faces detected; review the original' if faces.empty?
raise ReviewRequired, 'Detection limit reached; review the original' if faces.length >= MAX_FACES
rectangles = faces.map { |face| face_rectangle(face, image.columns, image.rows) }
rectangles.each { |rectangle| pixelate_region(image, rectangle) }
# Write completely before publishing; a hard link refuses an existing destination.
Tempfile.create(['face-output-', '.png'], File.dirname(File.expand_path(output))) do |file|
file.binmode
file.write(image.to_blob)
file.flush
File.link(file.path, output)
end
puts "Wrote #{faces.length} pixelated region(s). Review every face before sharing."
ensure
headers&.each(&:destroy!)
images&.each(&:destroy!)
end
begin
raise ReviewRequired, 'Usage: ruby pixelate.rb INPUT OUTPUT.png' unless ARGV.length == 2
unless ARGV.all? { |path| path.dup.force_encoding(Encoding::UTF_8).valid_encoding? }
raise ReviewRequired, 'Use UTF-8 file paths'
end
run(*ARGV)
rescue ReviewRequired => error
warn error.message
exit 1
rescue StandardError
warn 'Processing failed; check the input, project credentials, network, and writable output directory.'
exit 1
end
写真を face-pixelation/input.jpg に配置してください。セットアップ時と同じ親ディレクトリから、次を実行します。
(
cd face-pixelation || exit 1
GEM_HOME="$PWD/gems" GEM_PATH="$PWD/gems" \
ruby pixelate.rb ./input.jpg ./output.png
)
終了ステータスがゼロなら、プログラムは face-pixelation/output.png を書き込み、確認を促すメッセージを表示しています。その PNG を元画像と並べて開き、公開前に、見えているすべての顔を確認してください。次回以降は新しい出力先名を使用してください。プログラムは既存のファイルとシンボリックリンクを拒否し、入力には変更を加えず、一時ファイルを削除します。管理下のディレクトリで、同時に複数実行せず、順番に実行してください。
パフォーマンスの最適化と境界ケースへの対処
Vision RPC のタイムアウトは 15 秒で、SDK の自動再試行は無効です。これは RPC のタイムアウトであり、プログラム全体の実行期限ではありません。依存関係の読み込み、デコード、認証情報の取得、書き込みには、別途時間がかかります。無人運用のサービスでは、このローカルスクリプトをそのままワーカーサービスとして扱わず、プロセス監視と適切な全体の実行期限を追加してください。
顔が検出されないレスポンス、画像ごとのプロバイダーエラー、曖昧なポリゴン、上限いっぱいの 100 件の結果を含むレスポンスでは、ゼロ以外のステータスで終了し、新しい出力は生成しません。通信や認証情報の例外でも、成功メッセージを表示せずに失敗します。何も検出されなかった場合は元画像を確認してください。空のレスポンスは、画像に人物がいないことを意味しません。検出器がほかの顔を正常に検出していても、傾いた顔や一部しか見えない顔には手動編集が必要な場合があります。
ファイルサイズと画素数の制限により、この例の対象は小さな写真に絞られています。ネイティブのピクセルキャッシュを 256 MiB に設定し、ディスクキャッシュを無効にしているため、これらの上限未満でもリソース不足で処理を拒否する場合があります。また、これらの設定はプロセスのすべてのメモリ割り当てを制限するものではありません。ImageMagick は破損画像の一部を復元できるため、デコードの成功は完全性の確認にはなりません。破損のない元画像を使用し、端も含めて出力全体を確認してください。保守的な acTL と MPF のマーカーチェックは、メタデータに該当するバイト列を含む通常のファイルも拒否する場合があります。その場合は静止画像として再度書き出してください。
元画像をクラウドプロバイダーに送信することが適切でない場合は、ローカルの検出器を選び、その検出器の座標と向きの仕様を確認してください。検出 API を変更するには、レスポンスに応じた処理の変更が必要です。ここでの長方形の処理は、受け付ける Vision のポリゴン形状に特化しています。
画像処理で ImageMagick は Ruby とどのように連携する?
RMagick は Ruby から ImageMagick のネイティブ画像操作を呼び出します。この例では EXIF の向きの補正、切り抜き、サンプリング、合成を担当し、Vision が検出結果を提供します。正規化済み PNG は、後で編集するのと同じ RMagick 画像からメモリ上で作成するため、検出とモザイク処理で画像の寸法と向きが一致します。strip! はリクエストと出力の前に、EXIF メタデータを含む入力のプロファイルとプロパティを削除します。ただし、PNG エンコーダーが独自の形式フィールドを追加する場合があります。
プライバシー上の注意点
選択したブロックサイズは視覚効果の設定であり、匿名性を保証するしきい値ではありません。モザイク処理後も顔を識別できる場合があり、メタデータを削除しても、人物の特定につながる画像内容は除去されません。検出を実行する前に、プロバイダーの処理条件と、元画像を送信する権限があるかを確認してください。
確認済みの出力は元画像と分けて保管してください。アップロードのワークフローに組み込む場合は、生成された PNG を公開する前に、明示的な確認判断を必須にしてください。
