[Task 2C.2]: Gap Analysis: ImageProcessingService vs Legacy ImageCache

[helgeerbe]

The new ImageProcessingService lacks several features present in the legacy ImageCache class. These should be implemented in the upcoming phases:

Phase 2 (Control Plane & UI) Gaps:

• Matting (adding borders/mats to images)
• Text overlays (adding captions, dates, etc. to images)
• EXIF data extraction and overlay
• Geolocation reverse lookup and overlay

These features need to be implemented in the new architecture to achieve full parity.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[helgeerbe]

Next-gen matting parity update

Code review status:

• Legacy matting is implemented in picframe.mat_image.MatImage and applied from viewer_display.ViewerDisplay.__tex_load().
• The refactored next-gen renderer path does not currently apply matting. ImageRenderer loads a single image or composes an in-memory portrait pair, but never instantiates or calls MatImage.
• Config/schema/UI fields for viewer.mat_images, mat_type, mat colors, borders, texture toggles, and mat_resource_folder already exist, so this is an implementation parity gap rather than a new user-facing setting.
• ImageProcessingService mentions matting in its docstring, but its current processing path only resizes/crops/caches images and handles async metadata extraction.

Architecture decision to track:

• Next-gen matting should be implemented in the playback/render image preparation path, not as playlist behavior.
• Videos are never matted.
• Single images can be matted according to legacy viewer.mat_images semantics.
• Portrait pairs can be matted as a two-image mat, matching legacy behavior where MatImage.mat_image((left, right)) receives both images together.
• Pair-composed or matted images should remain in memory for the first implementation unless performance testing on Raspberry Pi shows a need for managed cache artifacts.
• If persistent artifacts are later introduced, they must live under the managed runtime cache directory and be removable by Clear Image Cache.

Implementation tasks:

• Add matting fields to the next-gen RendererConfig / composition-root config mapping: mat_images, mat_type, outer_mat_color, inner_mat_color, outer_mat_border, inner_mat_border, outer_mat_use_texture, inner_mat_use_texture, and mat_resource_folder.
• Port or reuse legacy ViewerDisplay.__get_mat_image_control_values() semantics so true/yes/on means always mat, false/no/off disables matting, and numeric values mat only when the image/display aspect-ratio difference exceeds the threshold.
• Add a small image-preparation helper/service used by ImageRenderer that can load EXIF-corrected PIL images, decide whether matting applies, and invoke MatImage.
• Apply matting before creating the pi3d texture for single-image render commands.
• Apply matting to portrait-pair render commands by passing both side images to MatImage together; keep videos and placeholders out of the matting path.
• Preserve current fit/crop, Ken Burns, blur-edge, and transition behavior for images where matting is disabled or below threshold.
• Handle missing mat resources gracefully with logging and fallback to the un-matted image rather than breaking playback.
• Add focused unit tests for matting decision logic, config mapping, single-image mat command flow, portrait-pair mat command flow, disabled matting, threshold behavior, and missing-resource fallback.
• Manually validate on Raspberry Pi hardware with real mat resources, including single landscape/portrait images, portrait pairs, videos, and Clear Image Cache behavior.

Public interface notes:

• No new REST or WebSocket API is required.
• Existing Settings fields should become operational in the next-gen renderer.
• No playlist query API changes are needed.

Assumptions:

• Matting is visual rendering parity and does not modify original media files.
• Matting should not create persistent files in the first implementation.
• If performance requires caching later, generated mat artifacts belong to <base_dir>/data/cache and Clear Image Cache should remove them.
• This ticket remains the correct home for next-gen matting parity; no separate matting-only ticket is needed right now.