Scala と ImageMagick による動的な画像処理
Scala から ImageMagick を実行して、コマンドラインで指定した画像をリサイズし、透かしを追加します。以下のプログラムは、新しいディレクトリに入力ごとに PNG を書き込み、元の画像を保持します。いずれかの画像の処理に失敗すると、ゼロ以外のステータスを返します。バッチ内で失敗が発生しても、処理に成功したほかの画像は利用できます。
このチュートリアルでは、Scala のプロセス連携とバッチ処理のエラー処理を中心に説明します。Web サイト向けに複数の幅の画像と代替形式を生成する場合は、別のレスポンシブ画像の処理例を参照してください。
小規模な Scala プロジェクトのセットアップ
Linux、Bash、cURL、JDK 21 のインストール環境、および JPEG、PNG、FreeType をサポートする
ImageMagick 7.1.2-31を使用します。この例は OpenJDK 21.0.12.1、Scala 2.13.18、ImageMagick 7.1.2-31 Q16-HDRI でテスト済みです。Scala 2.13.18 は Scala 2.13 系の現行リリースで、JDK 21 をサポートしています。ImageMagick 6 の convert エントリーポイントと
Windows ネイティブのシェルは、このチュートリアルの対象外です。
読み取り可能な TrueType フォントも必要です。実行コマンドでは
/usr/share/fonts/liberation/LiberationSans-Regular.ttf を使用します。ディストリビューションによってインストール先が異なる場合は、フォントのフルパスに置き換えてください。シェルのコードブロックは、Bash の errexit を無効にしてから貼り付けてください。これにより、コマンドが失敗するとプロンプトに戻ります。各ブロックは、呼び出し元のディレクトリとシェルオプションを変更せずに終了します。
java -version && magick -version && magick -list format
形式一覧で JPEG と PNG が読み書きをサポートしていることを確認してください。書き込み可能な作業ディレクトリから始めます。このブロックは新しい scala-images プロジェクトを作成し、バージョンを固定した Scala の jar を三つ Maven Central からダウンロードします。同名のプロジェクトディレクトリがすでにある場合は処理を拒否するため、別の作業ディレクトリを選んでください。
(
mkdir scala-images || exit 1
cd scala-images || exit 1
mkdir lib classes inputs || exit 1
for artifact in scala-library scala-reflect scala-compiler; do
curl -fsSLo "lib/$artifact-2.13.18.jar" \
"https://repo.maven.apache.org/maven2/org/scala-lang/$artifact/2.13.18/$artifact-2.13.18.jar" || exit 1
done
java -cp 'lib/*' scala.tools.nsc.Main -version
)
これらは Scala 2.13.18のコンパイラー、ランタイムライブラリ、リフレクションライブラリです。このプロジェクトは sbt ビルドもサードパーティーの Scala 依存関係も使用しません。クラスパスを明示しているため、既存の sbt プロジェクト内でも、親プロジェクトのビルド設定を読み込んだり依存関係を追加したりせずに動作します。
バッチ処理プログラム全体の保存
以下を scala-images/ImageBatch.scala として保存してください。引数は、新しい出力ディレクトリ、フォントのパス、透かしのラベル、一つ以上のローカルの静止 JPEG または PNG のパスです。ラベルには最大 40 文字の ASCII の英字、数字、スペース、ピリオド、アンダースコア、ハイフンを使用でき、先頭は英字または数字にする必要があります。この制限により、ImageMagick のテキストエスケープやファイル読み取り構文がラベルに含まれるのを防ぎます。
出力名には入力ファイル名全体が含まれます。photo.jpg は photo.jpg.png になります。ベース名が同じ入力が二つある場合、出力ディレクトリの作成前に拒否されます。入力は引数の順に処理され、大文字と小文字が混在する .jpg、.jpeg、.png 拡張子にも対応します。
import java.io.IOException
import java.nio.file.{Files, Path, Paths}
import java.util.Locale
import scala.sys.process.{Process, ProcessLogger}
import scala.util.control.NonFatal
object ImageBatch {
private def command(arguments: Seq[String], directory: Path): String = {
val output = new StringBuilder
val errors = new StringBuilder
val status = Process(arguments, directory.toFile).!(ProcessLogger(
line => { output.append(line).append('\n'); () },
line => { errors.append(line).append('\n'); () }
))
if (status != 0 || errors.nonEmpty) {
throw new IOException(s"ImageMagick status $status: ${errors.toString.trim}")
}
output.toString
}
private def processImage(input: Path, output: Path, font: Path, label: String): Boolean = {
try {
val name = input.getFileName.toString.toLowerCase(Locale.ROOT)
if (!Seq(".jpg", ".jpeg", ".png").exists(name.endsWith)) {
throw new IOException("Expected a .jpg, .jpeg, or .png filename")
}
if (!Files.isRegularFile(input) || !Files.isReadable(input)) {
throw new IOException("Not a readable regular file")
}
val stage = Files.createTempDirectory(output, ".work-")
try {
// Ordinary private names prevent ImageMagick from interpreting the reader's paths.
Files.copy(input, stage.resolve("source"))
Files.copy(font, stage.resolve("font.ttf"))
val formats = command(Seq("magick", "identify", "-regard-warnings",
"-limit", "thread", "1", "-format", "%m\n", "source"), stage)
.linesIterator.toVector
if (formats != Vector("JPEG") && formats != Vector("PNG")) {
throw new IOException("Expected one still JPEG or PNG image")
}
command(Seq(
"magick", "-regard-warnings", "-limit", "thread", "1", "source",
"-auto-orient", "-colorspace", "sRGB", "-resize", "800x600>",
"-background", "white", "-alpha", "remove", "-alpha", "off",
"-font", "font.ttf", "-pointsize", "24", "-gravity", "southeast",
"-fill", "white", "-stroke", "black", "-strokewidth", "1",
"-annotate", "+12+12", label, "-strip", "PNG24:result.png"
), stage)
Files.move(stage.resolve("result.png"), output.resolve(input.getFileName.toString + ".png"))
} finally {
val children = Files.list(stage)
try children.forEach(path => { Files.delete(path); () })
finally children.close()
Files.delete(stage)
}
println(s"OK $input")
true
} catch {
case NonFatal(error) =>
Console.err.println(s"FAILED $input: ${error.getMessage}")
false
}
}
private def run(arguments: Array[String]): Int = {
if (arguments.length < 4) {
Console.err.println("Usage: ImageBatch NEW_OUTPUT_DIR FONT.ttf LABEL INPUT [INPUT ...]")
return 2
}
val output = Paths.get(arguments(0)).toAbsolutePath
val font = Paths.get(arguments(1)).toAbsolutePath
val label = arguments(2)
val inputs = arguments.drop(3).map(value => Paths.get(value).toAbsolutePath).toVector
require(Files.isRegularFile(font) && Files.isReadable(font), "Font must be readable")
require(label.matches("[A-Za-z0-9][A-Za-z0-9 ._-]{0,39}"), "Invalid watermark label")
require(inputs.map(_.getFileName.toString).distinct.size == inputs.size,
"Input basenames must be distinct")
// Creating a new directory reserves this batch; an existing directory is never reused.
Files.createDirectory(output)
var succeeded = 0
var failed = 0
for (input <- inputs) {
if (processImage(input, output, font, label)) succeeded += 1
else failed += 1
}
println(s"Batch: $succeeded succeeded, $failed failed")
if (failed == 0) 0 else 1
}
def main(arguments: Array[String]): Unit = {
val status = try run(arguments) catch {
case NonFatal(error) =>
Console.err.println(s"Cannot start batch: ${error.getMessage}")
2
}
sys.exit(status)
}
}
Process(Seq(...), directory)は、実行ファイルに個別の引数を渡します。パスにスペースが含まれていても、シェルコマンドを組み立てる必要はありません。ただし、ImageMagick にはフレームセレクターや出力パターンなど、独自のファイル名の解釈規則があります。Java のファイル操作で各ソースを source にコピーし、その専用ディレクトリで ImageMagick を実行してから、result.png を指定どおりの出力名に移動します。これにより、ファイル名に含まれる角括弧、パーセント記号、先頭のハイフンも文字どおりに扱われます。
リサイズとメタデータの削除に先立って、画像の向きを適用します。リサイズでは、切り抜きや引き伸ばし、小さい入力の拡大を行わずに 800×600 以内に収めます。透明ピクセルは白の背景に合成され、PNG24: が不透明な 8 ビット RGB PNG を書き込みます。黒い縁取りのある白いラベルを右下に配置します。小さい画像では、収まるように短いラベルを使用してください。
sRGB 変換は汎用的なものです。プロファイルに敏感な素材や広色域の素材、特に CMYK 写真で正確に色を合わせるには、適切な ICC プロファイルのワークフローが必要です。元の画像は保持してください。PNG は静止画像を使用してください。PNG デコーダーは APNG の最初のフレームだけを読み取るため、形式チェックではすべてのアニメーションを検出できません。このプログラムはアニメーションを保持しません。
実際の例のビルドと実行
サンプル画像を二つ作成します。これらのコマンドは元の作業ディレクトリから実行し、いずれかのサンプルがすでに存在する場合は上書きを拒否します。
(
cd scala-images &&
test ! -e inputs/landscape.jpg && test ! -L inputs/landscape.jpg &&
test ! -e 'inputs/portrait photo.png' && test ! -L 'inputs/portrait photo.png' &&
magick -size 1600x900 xc:steelblue inputs/landscape.jpg &&
magick -size 600x1200 xc:seagreen 'inputs/portrait photo.png'
)
保存したプログラムをコンパイルし、Java でメインクラスを呼び出します。&& により、ビルドに失敗した場合に古いクラスファイルが起動されるのを防ぎます。出力ディレクトリの親は存在する必要がありますが、output 自体は存在してはいけません。
(
cd scala-images &&
java -cp 'lib/*' scala.tools.nsc.Main -usejavacp -d classes ImageBatch.scala &&
java -cp 'classes:lib/scala-library-2.13.18.jar' ImageBatch \
output /usr/share/fonts/liberation/LiberationSans-Regular.ttf 'Scala batch' \
inputs/landscape.jpg 'inputs/portrait photo.png'
)
実行に成功すると、入力ごとに OK の行と
Batch: 2 succeeded, 0 failed が出力され、終了ステータスはゼロになります。指定した名前の出力ファイルを確認してください。
(
cd scala-images &&
magick identify -format '%f: %m %wx%h\n' \
output/landscape.jpg.png 'output/portrait photo.png.png'
)
横長の画像は 800×450 の PNG、縦長の画像は 300×600 の PNG になります。両方のファイルを画像ビューアーで開き、右下の Scala batch ラベルを確認してください。独自のバッチ処理では、二つの入力引数を引用符で囲んだパスに置き換え、新しい出力ディレクトリを選びます。Java は ImageBatch より後の引数をすべてプログラムに渡します。- で始まるファイル名も含まれます。
バッチ処理のリソース制限
Scala のループは画像を一つずつ処理します。ImageMagick の各呼び出しには
-limit thread 1 を指定しています。これは ImageMagick の処理スレッドを制限するもので、メモリの総量や外部デリゲートを制限するものではありません。大きなソースのデコードでは、リサイズで小さくなる前に、インストール環境のリソースポリシーを超える場合があります。このサンプルを実行するためだけにグローバルポリシーを変更しないでください。制限についてはリソースポリシーのドキュメントを参照してください。
各処理では、入力、フォント、出力を一つずつ一時配置し、その後に一時ディレクトリを削除します。処理に成功した PNG はバッチディレクトリに蓄積されます。この例には、処理ごとの期限や中断時のクリーンアップはありません。JVM を停止すると .work-* ディレクトリが残る場合があります。プロセスの停止後に、内容を確認して削除できます。アップロードサービスではなく、信頼できるファイル向けのローカルなバッチユーティリティとして使用してください。
バッチ処理の失敗の診断
終了ステータス 1 は、選択した画像のうち少なくとも一つの処理に失敗したことを示します。FAILED の行に該当する入力が表示されます。後続の画像の処理に成功した場合も、最後の集計にはすべての入力が含まれます。空のファイル、存在しないファイル、読み取れないファイル、認識できないファイルは失敗となりますが、残りの処理は停止しません。変換に失敗した場合は一時配置された出力を削除し、処理に成功したほかの画像は出力ディレクトリに残します。
終了ステータス 2 は、バッチ処理を開始できなかったことを示します。たとえば、フォントを読み取れない、透かしのラベルが無効、入力のベース名が重複している、出力ディレクトリがすでに存在するといった場合です。再実行時には既存のディレクトリを拒否し、その中のファイルを保持します。問題を修正してから、新しい出力先を選んでください。処理中は入力とフォントを変更せず、このプログラムがバッチディレクトリを使用している間は、ほかのプロセスに編集させないでください。
-regard-warningsは、デコーダーの一部の警告をエラーに昇格させます。また、プログラムは、終了ステータスがゼロでも診断メッセージを出力するコマンドを拒否します。これは画像の完全性チェックではありません。デコーダーは、破損したデータを通知せずに復旧する場合があります。破損の可能性がある場合は、ソースと出力の全体を確認してください。ヘッダーが有効であること、寸法が期待どおりであること、プロセスが正常終了したことだけでは、ピクセルが破損していないとは判断できません。
ローカルの ImageMagick 環境ではなく、マネージドな処理が必要なアプリケーションについては、Transloadit の画像処理 APIを参照してください。
