ENH: add decode_as_image() to ContentStreams

[pubpub-zz]

closes #2613

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.14%. Comparing base (3c9f449) to head (604e2b8).
Report is 57 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2615   +/-   ##
=======================================
  Coverage   95.13%   95.14%           
=======================================
  Files          51       51           
  Lines        8538     8547    +9     
  Branches     1702     1703    +1     
=======================================
+ Hits         8123     8132    +9     
  Misses        261      261           
  Partials      154      154           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stefan6419846]

Should we really expect the users to basically call decode_image on every object with arbitrary nesting as there might be a "hidden" image somewhere? This feels rather strange.

Additionally, what happens when it is no image? We log a warning, but is there an exception as well due to invalid image data? If yes, why both?

[pubpub-zz]

Should we really expect the users to basically call decode_image on every object with arbitrary nesting as there might be a "hidden" image somewhere? This feels rather strange.

Why strange. This offers a way to get the image from an stream where images are present but not part of the images (such as the use in pattern as provided in B2.pdf, but also in annotations)

Additionally, what happens when it is no image? We log a warning, but is there an exception as well due to invalid image data? If yes, why both?

I thought about this and my concern is that this may hide some actual issues. I've completed the annotation

[stefan6419846]

I am still not sure whether we can really expect the user to examine every content stream for a possible image. Personally, I would prefer a clean solution, thus I am going to leave this PR open for further discussion.

[pubpub-zz]

I've reviewed quickly the PDF 1.7 spec, and there is many objects not part of the current .images[]. within pages I've found thumbnails, alternate images, and currently patterns, and possibly mask images (as independent images). There is also some images not stores in pages: thumbnaiils within linearized documents and within annotations (such as stamps where images are stores within [/AP][/N][/Resources][/XObjects]).
I may have lost also some elements.

At least providing a function to ease extraction of images for other developers should be an improvements

[stefan6419846]

In this case, could you please fix the merge conflicts and add some basic example to the docs?

[pubpub-zz]

test doc for example in documentation:
test_stamp.pdf