review(p6-3): 회차 1 지적 반영

- 새 모듈 `crates/kebab-parse-image/src/image_prep.rs` — OCR + caption
  + 향후 PDF/video 가 공유할 단일 다운스케일 헬퍼 (`downscale_to_png`)
  추출. 기존 ocr.rs / caption.rs 의 거의 동일 알고리즘 두 벌을 한
  곳으로 통합. 1px 후행 클램프 / PNG passthrough hot path / 에러
  메시지 패턴이 한 곳에서 관리됨.
- src/ocr.rs: `downscale_to_long_edge` 제거 → `image_prep::downscale_to_png`
  호출. `image::ImageReader / ImageFormat / Cursor` import 도 정리.
- src/caption.rs:
  • `caption_image` / `apply_caption` 의 disabled 처리 비대칭 해소.
    `caption_image` 는 raw 연산 (gate 없음), `apply_caption` 만
    `cfg.image.caption.enabled` 게이트 검사. 호출자가 같은 함수에서
    같은 의미를 얻음.
  • `apply_caption` 의 caption.model / model_version `String::clone`
    2회 → 0회. caption move 전에 ProvenanceEvent.note 를 먼저 빌드.
  • 다운스케일 로직 통째로 image_prep 위임.
  • `MIN_CAPTION_LONG_EDGE` / `MAX_CAPTION_LONG_EDGE` 를 `pub const`
    로 노출 (P6-2 의 `MAX_DECODE_DIM` 가시성 컨벤션과 일관).
- tests/caption.rs:
  • `caption_image_errors_when_feature_disabled` 를
    `caption_image_runs_regardless_of_enabled_flag` 로 교체 — 새
    책임 분리 의미 검증.
  • `caption_image_clamps_oversized_max_pixels` 가 literal 1536 대신
    `kebab_parse_image::caption::MAX_CAPTION_LONG_EDGE` 상수 참조.
- tasks/HOTFIXES.md: `model_version` 형태 deviation 한 단락 추가
  (spec literal `provider` → `<provider>/<prompt_template_version>`
  확장 + 사유).

cargo test -p kebab-parse-image — 42 pass + 2 ignored
  (13 unit + 12 P6-1 + 8 P6-2 + 9 P6-3).
cargo clippy --workspace --all-targets -- -D warnings — pass.
This commit is contained in:
2026-05-02 06:11:56 +00:00
parent cd2213e48d
commit 9c644245fb
6 changed files with 131 additions and 157 deletions

View File

@@ -0,0 +1,83 @@
//! Shared image preparation for OCR / caption / future vision pipelines.
//!
//! Both P6-2 OCR and P6-3 caption need the same pre-LM step: clamp the
//! long edge to a configured max, re-encode as PNG (Ollama's vision
//! channel format), pass through the source bytes when they already
//! satisfy both constraints. Centralising this here keeps the
//! 1px-rounding fix, the PNG passthrough hot path, and the error
//! messages in one place — future modules (PDF page thumbnails,
//! video keyframes, …) plug in without re-deriving the algorithm.
use std::io::Cursor;
use anyhow::{Context, Result};
use image::{ImageFormat, ImageReader};
/// Decode `bytes`, downscale so the long edge is at most `max_long_edge`,
/// and re-encode as PNG. Returns `(png_bytes, final_w, final_h)` so
/// callers that care about the final dimensions (e.g. OCR's
/// `SourceSpan::Region`) get them without re-decoding.
///
/// PNG sources that already fit the cap pass through (zero decodes,
/// just a `Vec` clone). Every other path decodes the image exactly
/// once: a cheap header sniff peeks at the format / dimensions before
/// committing to a decode, so non-PNG passthrough and downscale share
/// the same `decode → optionally resize → re-encode` tail.
pub(crate) fn downscale_to_png(
bytes: &[u8],
max_long_edge: u32,
) -> Result<(Vec<u8>, u32, u32)> {
let reader = ImageReader::new(Cursor::new(bytes))
.with_guessed_format()
.context("reading image header")?;
let format = reader.format();
let (w, h) = reader
.into_dimensions()
.context("reading image dimensions")?;
let long = w.max(h);
// Hot path — PNG within budget already matches the wire format we
// send to vision models, so we ship the bytes verbatim without
// paying for a decode + re-encode round-trip.
if long <= max_long_edge && format == Some(ImageFormat::Png) {
return Ok((bytes.to_vec(), w, h));
}
// Every remaining branch needs the pixels — either to re-encode as
// PNG (non-PNG within budget) or to resize first (over budget).
// One decode covers both.
let img = ImageReader::new(Cursor::new(bytes))
.with_guessed_format()
.context("re-reading image for decode")?
.decode()
.context("decoding image")?;
let (final_w, final_h, final_img) = if long <= max_long_edge {
(w, h, img)
} else {
let scale = max_long_edge as f32 / long as f32;
let mut new_w = ((w as f32) * scale).round().max(1.0) as u32;
let mut new_h = ((h as f32) * scale).round().max(1.0) as u32;
// Independent rounding of the two axes can let `f32`'s
// round-to-nearest push the long axis one pixel past
// `max_long_edge` for irrational scales (e.g. `max=1601,
// long=4001`). Pin the long axis to exactly `max_long_edge`
// so the doc-comment's "long edge is at most max_long_edge"
// stays a strict bound.
if w >= h {
new_w = new_w.min(max_long_edge);
} else {
new_h = new_h.min(max_long_edge);
}
let resized =
img.resize_exact(new_w, new_h, image::imageops::FilterType::Triangle);
(new_w, new_h, resized)
};
let mut out = Cursor::new(Vec::new());
final_img
.write_to(&mut out, ImageFormat::Png)
.context("encoding image as PNG")?;
Ok((out.into_inner(), final_w, final_h))
}