BUG: invalid cm/tm in visitor functions

[pubpub-zz]

closes #2200
closes #2075
reworks and is still valid to close #2059

[codecov]

Codecov Report

Attention: 3 lines in your changes are missing coverage. Please review.

Comparison is base (4b090ba) 94.40% compared to head (8a6a0e5) 94.44%.
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2206      +/-   ##
==========================================
+ Coverage   94.40%   94.44%   +0.04%     
==========================================
  Files          43       43              
  Lines        7599     7621      +22     
  Branches     1501     1502       +1     
==========================================
+ Hits         7174     7198      +24     
+ Misses        262      261       -1     
+ Partials      163      162       -1     

Files	Coverage Δ
pypdf/__init__.py	87.50% <100.00%> (ø)
pypdf/_text_extraction/__init__.py	93.70% <100.00%> (+0.36%)	⬆️
pypdf/_page.py	94.67% <88.00%> (+0.31%)	⬆️

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

[pubpub-zz]

@troethe,
From my analysis, the change you've proposed was not suffcient as the prev position may be overriden during the process.
I've created a PR where I've storing the cm/tm matrices when resetting the text variable (this normally occurs when meeting the Td which will occurs/set the position before restarting a new line
Can you have a review of my change?

[troethe]

Looks good! I think this approach is currently the best way to handle #2075. The two comments I added are minutiae and not necessarily important.

[troethe]

This doesn't look quite right. I think this line can however be safely removed, because cm_prev doesn't get accessed until it is being assigned to again at the end of this function (i.e. this is currently a noop).

[pubpub-zz]

agree.
Good point to have noticed it . Actually I've forgot to pass the multiplied cm_matrix to the visitor

[troethe]

I think the old comment was more correct, right? This change was probably a side effect of the revert.

[pubpub-zz]

Correct we store inhere only tm_matrix

[pubpub-zz]

@troethe
I've taken into account your comments

@srogmann
I would like to have your opinion too:
I've also completed the PR passing the product of cm_matrix . tm_matrix as the users may not have an easy access to mult() function and because cm_matrix alone has no mean (for me)
also for me it is better to recommand to work on the cm_matrix as it will take into account all transformations()
finally looking at the code I currently see no difference between using visitor_operand_before() and visitor_operand_after().
Shouldn't we await from visitor_operand_before() to return the tuple operator,operands to allow the user to modify/cancel the processing of some operations ?

[srogmann]

@pubpub-zz I also have no example of cm_matrix without tm_matrix at hand. PDF-reference, "5.3.3 Text Space Details", uses the product of cm_matrix and tm_matrix you mentioned.

An argument to stay at cm_matrix instead of the product might be the performance if the product is computed but not used. In that case the publish of a mult()-function might be useful.

In text-extraction-test 3 of tests/test_page.py I used visitor_operand_after to verify the Td-operation (see visitor_td).

The return of the operator by visit_operand_before() can support patches or studies like the one in #1389 (comment). Can or should the operand-list be modified inside visit_operand_before() by using append(...), clear(...), ...? Otherwise it would be better to return the tuple (operator, operands).

[pubpub-zz]

@pubpub-zz I also have no example of cm_matrix without tm_matrix at hand. PDF-reference, "5.3.3 Text Space Details", uses the product of cm_matrix and tm_matrix you mentioned.

An argument to stay at cm_matrix instead of the product might be the performance if the product is computed but not used. In that case the publish of a mult()-function might be useful.

In text-extraction-test 3 of tests/test_page.py I used visitor_operand_after to verify the Td-operation (see visitor_td).

The return of the operator by visit_operand_before() can support patches or studies like the one in #1389 (comment). Can or should the operand-list be modified inside visit_operand_before() by using append(...), clear(...), ...? Otherwise it would be better to return the tuple (operator, operands).

@MartinThoma
your opinion?

[MartinThoma]

I don't have an opinion on this topic. To be honest, I haven't read the specs so I need to trust you on those changes.

If two of you agree that this PR is good (and CI is green), then I would merge :-)

[pubpub-zz]

@MartinThoma / @srogmann
the PR for me is mature.
I left the change of cm_matrix which now reflects the position/orientation/scale of the text in the page user space :
this may be considered as a change in the interface but I don't think many people are using the existing matrix and the change makes things easier to handle (the matrix description was very obscure)
I did not implement the new feature to use visit_operand_before to modify the operations. I will do this in an independant PR for traceability.

[pubpub-zz]

Plus stdby

[MartinThoma]

Plus stdby

I take this as "please standby", so I should not merge?

[pubpub-zz]

Plus stdby

I take this as "please standby", so I should not merge?

Correct interpretation
@jianfan2012 used the visitor in an interesting (cf #2163 (reply in thread)) way where the multiplication of cm.tm is preventing the use
we need to keep then separate. I'm reverting my change update the documentation

[pubpub-zz]

@MartinThoma
All should be good now.

[MartinThoma]

The cm/tm parts of the visitor functions are really hard to get right. Thank you for taking care of it @pubpub-zz 🙏