Outline (TOC) parsing bug

[kybos]

Description of the bug

get_toc() returns inconsistent results for many of my docs (created with MasterPDF Editor).
Some (but not all) outlines are wrongly returned with kind=4 but without nameddest (and also a wrong page number).

Analysis shows that in the pdf source the structure of all outline items is identical. The only difference is that for the wrong items there is a "null" value in the corresponding /XYZ element. When "null" is manually changed to 0 in the pdf source, the get_toc output becomes correct.

How to reproduce the bug

Relevant snippets from the pdf source + get_toc output per line:

6 0 obj
<</A 73 0 R /C[ 0 0 0]/F 0/Title(Page 1)/Parent 74 0 R /Next 22 0 R >>
73 0 obj
<</S/GoTo/Type/Action/D[ 8 0 R /XYZ 0 842 0]>>

[1, 'Page 1', 1, {'color': (0.0, 0.0, 0.0), 'kind': 1, 'page': 0, 'to': Point(0.0, 0.0), 'xref': 6, 'zoom': 0.0}]


22 0 obj
<</A 58 0 R /C[ 0 0 0]/F 0/Title(Page 2)/Parent 74 0 R /Prev 6 0 R /Next 59 0 R >>
58 0 obj
<</S/GoTo/Type/Action/D[ 10 0 R /XYZ 0 null 1]>>

[1, 'Page 2', 3, {'color': (0.0, 0.0, 0.0), 'kind': 1, 'page': 2, 'to': Point(0.0, 841.8), 'xref': 22, 'zoom': 1.0}]


59 0 obj
<</A 68 0 R /C[ 0 0 0]/F 0/Title(Page 3)/Parent 74 0 R /Prev 22 0 R /Next 24 0 R >>
68 0 obj
<</D[ 15 0 R /XYZ 0 null 0]/S/GoTo/Type/Action>>

[1, 'Page 3', 8, {'color': (0.0, 0.0, 0.0), 'kind': 4, 'page': '8', 'xref': 59, 'zoom': 0.0}]


24 0 obj
<</A 60 0 R /C[ 0 0 0]/F 0/Title(Page 4)/Parent 74 0 R /Prev 59 0 R /Next 7 0 R >>
60 0 obj
<</D[ 17 0 R /XYZ 0 null 0]/S/GoTo/Type/Action>>

[1, 'Page 4', 10, {'color': (0.0, 0.0, 0.0), 'kind': 4, 'page': '10', 'xref': 24, 'zoom': 0.0}]


7 0 obj
<</A 71 0 R /C[ 0 0 0]/F 0/Title(Page 5)/Parent 74 0 R /Prev 24 0 R >>
71 0 obj
<</S/GoTo/Type/Action/D[ 19 0 R /XYZ 0 783 0]>>

[1, 'Page 5', 12, {'color': (0.0, 0.0, 0.0), 'kind': 1, 'page': 11, 'to': Point(0.0, 2.4420167), 'xref': 7, 'zoom': 0.0}]

PyMuPDF version

1.28.0

Operating system

Linux

Python version

3.14

[JorjMcKie]

Please let us have an example file showing the problem.

[kybos]

I can't provide the "real" files for privacy reasons, but I created a new test file that shows the issue with kind=4 without nameddest.
Interestingly, there is no "null" in the source this time...

9 0 obj
<</Type/Action/S/GoTo/D[ 4 0 R /FitH 841]>>
endobj
10 0 obj
<</Type/Outlines/First 11 0 R /Last 11 0 R /Count 1>>
endobj
11 0 obj
<</Title(untitled)/F 0/C[ 0 0 0]/A 9 0 R /Parent 10 0 R >>
endobj

[1, 'untitled', 1, {'color': (0.0, 0.0, 0.0), 'kind': 4, 'page': '1', 'view': 'FitH,.89001467', 'xref': 11, 'zoom': 0.0}]

test_mupdf.pdf

[JorjMcKie]

Thanks for providing the file. Error confirmed.

[KetanHegde]

I'd like to investigate this bug and see if I can prepare a fix.

[KetanHegde]

I've been investigating this issue.

From my debugging, the problem appears to be that FitH destinations (for example, /D [4 0 R /FitH 841]) are currently parsed into URIs like #page=1&view=FitH,..., but linkDest only recognizes the existing #page=...&zoom=... format. As a result, these links fall through to the fallback path and are reported as kind=4 instead of LINK_GOTO.

I also confirmed that the destination information is still available (Outline.page, Outline.y, etc.), so it looks like this is a parsing issue rather than missing data.

I'm continuing to investigate the correct handling for FitH destinations and will prepare a fix if my approach looks appropriate.

[kybos]

Yes, that's what I am seeing as well. Even this uri '#page=3&zoom=0,0,nan' leads to the same error (which was the "null" issue I described above).

But all that seem to be just symptoms of a deeper problem. The whole toc handling looks quite broken to me. It ignores the PDF specs that provide many different view modes (Fit FitH FitV XYZ FitR FitB FitBH FitBV), and also the fact that destinations can contain null values. Which means in the end that only documents that have been created by pymupdf itself can be reliably processed (because in set_toc a nested /A/D destination with view mode /XYZ and non-null values for x, y, zoom is hard-coded).

[JorjMcKie]

Thanks a lot @kybos / @KetanHegde for submitting the issue and looking into the details. We are already developing a fix.
It should not only fix this issue reported here, but also extend the support beyond /XYZ to all PDF viewing options /Fit*.
This requires to also change the Document method resolve_names.
The tests have just passed, so the fixe should be available in one of the next versions.

[kybos]

Thanks, that sounds good. I assume the fix is not finalized yet. I tried out the current main branch briefly, I see now there is a new "view" key when view != /XYZ. But still "kind" is set wrongly to 4, and for the /Fit* modes, zoom shouldn't be there.

[JorjMcKie]

Thanks, that sounds good. I assume the fix is not finalized yet. I tried out the current main branch briefly, I see now there is a new "view" key when view != /XYZ. But still "kind" is set wrongly to 4, and for the /Fit* modes, zoom shouldn't be there.

We only publish fixes as part of a new release on PyPI. So bear with us please.