Add optional SDK image asset export for rendered and embedded PDF images

[VooDisss]

Fixes: #173

Summary

This PR builds on the branch changes introduced in PR #171:

• Add printed page number metadata to SDK JSON output #171

Add optional SDK-owned image asset export for PP-DocLayoutV3 image regions.

This change introduces:

• imgs_rendered/ as the canonical rendered image asset directory
• optional imgs_embedded/ extraction for geometrically matched embedded PDF images
• configurable Markdown preference between embedded and rendered
• stable image block metadata describing selected and available image assets

Behavior

Rendered-only mode

When enable_image_asset_export=false:

• image regions are still exported to imgs_rendered/
• no embedded extraction is attempted
• image blocks expose:
  • image_path
  • rendered_image_path
  • embedded_image_path: null
  • image_asset_source: "rendered"

Embedded-enabled mode

When enable_image_asset_export=true:

• rendered image assets are still created
• the SDK inspects embedded PDF images via PyMuPDF
• matched embedded assets are saved to imgs_embedded/
• image_path follows markdown_image_preference
• embedded_image_path is populated only when a match exists

Matching

Embedded matching is based on:

• same-page filtering
• bbox geometry
• IoU threshold
• containment threshold
• aspect-ratio plausibility
• one-to-one assignment

It deliberately avoids center-distance-only matching.

Output contract

Image blocks now expose:

{
  "image_path": "...",
  "rendered_image_path": "...",
  "embedded_image_path": null,
  "image_asset_source": "rendered"
}

or, when an embedded match exists and embedded is selected:

{
  "image_path": "imgs_embedded/...",
  "rendered_image_path": "imgs_rendered/...",
  "embedded_image_path": "imgs_embedded/...",
  "image_asset_source": "embedded"
}

Failure behavior

The implementation explicitly avoids stale asset advertisement:

• no nonexistent rendered asset should remain in image_path
• no nonexistent rendered asset should remain in rendered_image_path
• stale markdown image references are removed when no asset survives
• if a valid embedded asset survives recovery, it remains the selected asset

Validation

• focused regression tests cover:

  • rendered-only default behavior
  • embedded match preference
  • rendered preference
  • preservation-mode recovery
  • missing rendered-key recovery
  • no-render-pages behavior
  • crop-failure behavior
  • rendered-origin stale markdown cleanup
  • embedded-origin stale markdown cleanup
  • nested asset persistence in saved output

• real validation confirmed:

  • imgs_rendered/ created in rendered-only mode
  • imgs_rendered/ + imgs_embedded/ created in embedded-enabled mode
  • markdown prefers embedded assets when configured and matched