並列処理と Rayon による Rust の画像処理の最適化
Rayon を使い、ワーカーごとにデコード・リサイズ・エンコードのジョブを実行して、個別の画像を並行処理します。このチュートリアルでは、ディレクトリ内の PNG と JPEG 画像を小さい JPEG に変換する Rust CLI を構築します。ワーカー数を指定でき、コマンドはすべてのファイルの失敗を報告してから最終ステータスを返します。
画像と出力の処理方針の選択
この例は、ローカルの静止画像をバッチ処理するもので、次の方針を採用します。
- 拡張子の大文字と小文字を区別せず、
.png、.jpg、.jpegで終わる通常ファイルを選択します。サブディレクトリ、シンボリックリンク、その他の拡張子はスキップします。実行中は入力ディレクトリを変更しないでください。 - 8 ビットの RGB、グレースケール、またはそれらにアルファを加えた形式にデコードされる画像を受け付けます。sRGB の入力を使用してください。プログラムは埋め込みカラープロファイルを変換しません。アニメーションやカラーマネジメントを伴う印刷ワークフローは、この例の対象外です。
- デコーダーが取得した EXIF の向きを適用し、透過部分を白に合成してから、800 × 600 ピクセル以内に収めます。切り抜きや、小さい画像の拡大は行いません。JPEG の品質設定は 85 です。
- 入力ファイル名全体に
.jpgを付加します。photo.pngはphoto.png.jpgに、photo.jpgはphoto.jpg.jpgになります。これにより、拡張子を除く名前が同じ入力も区別できます。 - 出力ディレクトリは新規である必要があります。既存のディレクトリは、空でもエラーになります。別のファイルが失敗しても成功したファイルは残ります。再実行には別の出力ディレクトリが必要です。
エンコーダーに渡すのはピクセルのみなので、元の EXIF、GPS、ICC、テキストメタデータはコピーされません。メタデータを破棄する前に、向きをピクセルに適用します。ここでは、アルファ合成とリサイズを線形光の値ではなく、エンコードされたチャンネル値に対して行います。これはサムネイル向けの意図的な簡略化であり、カラーマネジメントのパイプラインではありません。
Cargo プロジェクトの作成
以下のコマンドは Linux 上の Bash を使用し、Rust と Cargo 1.98.1 で動作確認しています。公式の Rust インストールガイドに従って、現在の安定版ツールチェーンをインストールしてください。既存の Cargo プロジェクトとその .cargo 設定の影響を受けない作業ディレクトリを使用します。以下のシェルブロックは、すべて同じ作業ディレクトリから貼り付けて実行します。
rustc --version && cargo --version
新しいディレクトリを作成します。既存の image-batch は再利用できません。
(mkdir image-batch && mkdir image-batch/src)
次のマニフェスト全体を image-batch/Cargo.toml として保存してください。
[package]
name = "image-batch"
version = "0.1.0"
edition = "2024"
[dependencies]
anyhow = "=1.0.104"
image = { version = "=0.25.10", default-features = false, features = ["jpeg", "png"] }
rayon = "=1.12.0"
[workspace]
有効にするコーデックは PNG と JPEG のみです。バッチの並列処理には Rayon を使用し、image クレートのオプションの Rayon 機能は無効にします。ここで使用する現在のデコードと向きの API は、image のリリースノートに記載されています。
バッチコマンド全体の実装
以下を image-batch/src/main.rs として保存してください。出力ディレクトリを作成する前に、ディレクトリ内のファイルの列挙を完了します。Rust の read_dir は、ディレクトリを開く際にもイテレーターを進める際にも失敗することがあります。そのため、どちらのエラーも伝播させ、黙ってバッチの対象を減らさないようにします。
use std::{env, fs, path::Path, process::ExitCode};
use anyhow::{Context, Result, ensure};
use image::{ColorType, DynamicImage, ImageDecoder, ImageReader, Limits, Rgb, RgbImage};
use image::codecs::jpeg::JpegEncoder;
use image::imageops::FilterType;
use rayon::prelude::*;
fn convert(input: &Path, output_dir: &Path) -> Result<()> {
let mut reader = ImageReader::open(input)?.with_guessed_format()?;
let mut limits = Limits::default();
limits.max_image_width = Some(4096);
limits.max_image_height = Some(4096);
limits.max_alloc = Some(128 * 1024 * 1024);
reader.limits(limits);
let mut decoder = reader.into_decoder().context("Read image header")?;
ensure!(
matches!(decoder.color_type(), ColorType::L8 | ColorType::La8 | ColorType::Rgb8 | ColorType::Rgba8),
"Expected an 8-bit image"
);
let orientation = decoder.orientation()?;
let mut decoded = DynamicImage::from_decoder(decoder).context("Decode pixels")?;
decoded.apply_orientation(orientation);
let rgba = decoded.into_rgba8();
let rgb = RgbImage::from_fn(rgba.width(), rgba.height(), |x, y| {
let pixel = rgba.get_pixel(x, y);
let alpha = u16::from(pixel[3]);
let blend = |channel: u8| {
((u16::from(channel) * alpha + 255 * (255 - alpha) + 127) / 255) as u8
};
Rgb([blend(pixel[0]), blend(pixel[1]), blend(pixel[2])])
});
drop(rgba);
let image = DynamicImage::ImageRgb8(rgb);
let resized = if image.width() > 800 || image.height() > 600 {
image.resize(800, 600, FilterType::Lanczos3)
} else {
image
};
let mut bytes = Vec::new();
JpegEncoder::new_with_quality(&mut bytes, 85).encode_image(&resized)?;
let mut name = input.file_name().context("Missing filename")?.to_os_string();
name.push(".jpg");
let output = output_dir.join(&name);
name.push(".part");
let staging = output_dir.join(name);
fs::write(&staging, bytes).context("Write staged JPEG")?;
fs::rename(&staging, &output).context("Publish JPEG")?;
Ok(())
}
fn run() -> Result<()> {
let args: Vec<_> = env::args_os().skip(1).collect();
ensure!(args.len() == 3, "Usage: image-batch INPUT_DIR NEW_OUTPUT_DIR THREADS");
let threads: usize = args[2].to_str().context("Invalid thread count")?.parse()?;
ensure!((1..=16).contains(&threads), "THREADS must be between 1 and 16");
let input_dir = fs::canonicalize(&args[0]).context("Resolve input directory")?;
let mut inputs = Vec::new();
for entry in fs::read_dir(&input_dir).context("Open input directory")? {
let entry = entry.context("Read directory entry")?;
if !entry.file_type().context("Read entry type")?.is_file() {
continue;
}
let path = entry.path();
let supported = path.extension().is_some_and(|ext| {
ext.eq_ignore_ascii_case("png")
|| ext.eq_ignore_ascii_case("jpg")
|| ext.eq_ignore_ascii_case("jpeg")
});
if supported {
inputs.push(path);
}
}
ensure!(!inputs.is_empty(), "No PNG or JPEG files found");
inputs.sort();
let pool = rayon::ThreadPoolBuilder::new().num_threads(threads).build()?;
let output_dir = Path::new(&args[1]);
fs::create_dir(output_dir).context("Create a new output directory; parent must exist")?;
let failed: usize = pool.install(|| {
inputs.par_iter().map(|input| {
match convert(input, output_dir) {
Ok(()) => 0,
Err(error) => {
eprintln!("FAILED {}: {error:#}", input.display());
1
}
}
}).sum()
});
println!("{} succeeded; {failed} failed", inputs.len() - failed);
ensure!(failed == 0, "Batch incomplete; successful outputs were kept");
Ok(())
}
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(error) => {
eprintln!("{error:#}");
ExitCode::FAILURE
}
}
}
各ジョブは、エンコードを済ませてから .part ファイルに書き込み、そのファイルを最終的な JPEG 名に変更します。名前の変更が完了した場合のみ成功とします。書き込みの失敗や中断によって .part ファイルが残ることがありますが、これは未完了の作業であり、公開済みの画像ではありません。出力ディレクトリは、この実行専用にしてください。この例では、ファイルを永続ストレージに同期する処理や、成功したファイルのロールバックは行いません。
並列イテレーターは、最初のエラーで停止せず、失敗数を合計します。通常のファイル単位のエラーであれば、列挙したすべての画像の処理を試みます。一方、バッチが未完了の場合は、プロセスの終了ステータスを非ゼロに保ちます。エラーメッセージの表示順序は不定です。
ビルド、実行、出力の確認
image-batch/Cargo.lock を一度生成し、プロジェクトと一緒に保持してください。直接依存のバージョンを厳密に固定するだけでは、推移的依存は固定されません。以後のビルドでは、保持したロックファイルを使用します。
(cd image-batch && cargo generate-lockfile)
再現可能な入力を用意するため、ImageMagick をインストールしてください。ここでは 7.1.2-31 で動作確認しています。以下では、左半分が不透明な赤、右半分が透明な 1,600 × 800 の PNG を作成します。この例では、新しいディレクトリ名を使用してください。
(
mkdir input-images &&
magick -size 1600x800 xc:none -fill red -draw 'rectangle 0,0 799,799' \
PNG32:input-images/sample.png
)
リリースモードでビルドし、ワーカーを二つにして実行します。このコマンドは、ビルドが成功した場合にのみ実行ファイルを起動します。
(
cd image-batch &&
cargo build --release --locked &&
./target/release/image-batch ../input-images ../output-images 2
)
この単一の入力に対して、プログラムは 1 succeeded; 0 failed と報告します。別のデコーダーを使って、実際に生成されたファイルを確認してください。
magick ./output-images/sample.png.jpg -format '%m %wx%h\n' info:
JPEG 800x400
その JPEG も開いてください。下端も含め、左半分は赤、右半分は白になっているはずです。resize は指定範囲内でアスペクト比を維持し、この画像を強制的に 800 × 600 にするわけではありません。サイズを明示的に確認することで、小さい入力は元の寸法のまま維持します。リサイズ前に透過部分を合成すると、透明なピクセルに隠れている RGB 値が白い背景ににじむのを防げます。
手元の画像を処理するには、二つのディレクトリ引数を置き換え、出力には新しいディレクトリを指定してください。スペースを含むパスは引用符で囲みます。選択された破損ファイルをデコーダーが拒否した場合は報告され、非対応の拡張子はスキップされます。デコードの成功は整合性の確認にはなりません。このデコーダーでは、途中で切れた JPEG でも、欠落したピクセルが灰色のブロックに置き換わって成功を返す場合があります。キャンバス全体にわたって画像の内容を確認し、原本を保持してください。
メモリ使用量と経過時間に対するワーカー数の測定
num_threads は、このプールのワーカー数を制限します。CLI が受け付けるのは一つから 16 までです。大きな入力では、一つか二つから始めてください。ディレクトリ内のパスを格納した後、実行中のジョブについてのみデコード済みのピクセルを保持します。各ジョブで複数のピクセルバッファが必要になる場合があるため、ワーカー数を倍にするとメモリ使用量が大幅に増えることがあります。
幅と高さそれぞれ 4,096 ピクセルの制限は、向きの適用とリサイズを行う前のソースに適用されます。デコーダーのメモリ割り当て上限 128 MiB はベストエフォートであり、後続の RGBA/RGB バッファ、リサイズ、JPEG エンコード、パス一覧、プロセス全体のメモリは対象外です。これらの制御があっても、このプログラムは信頼できないアップロード向けのサンドボックスにはなりません。
ビルドが成功したら、同じ代表的な複数画像の入力を使い、毎回新しい出力先で比較してください。
time ./image-batch/target/release/image-batch ./input-images ./timed-one 1 &&
time ./image-batch/target/release/image-batch ./input-images ./timed-two 2
Bash の real の経過時間を比較し、新しい出力ディレクトリ名で繰り返し測定してください。ウォーム状態のファイルシステムキャッシュも考慮します。画像一枚のスモークテストでは、バッチの高速化は実証できません。個別のデコードとリサイズで CPU コアを十分に稼働させられる場合、ワーカーを増やすと効果が得られることがあります。ただし、ストレージ、メモリ負荷、スケジューリングのオーバーヘッドによって、その効果が失われる場合もあります。Lanczos3 の結果が画像に適していれば、そのまま使用してください。画質を犠牲にして経過時間を短縮する前に、同じ入力で別のフィルターと比較してください。
