Attaching drawings to an OCG

[syntax-surgeon]

Hi all

I have the following task at hand: I want to optionally display all the drawings (vector graphics and svg-like objects) present in a PDF. For this I would like to attach the drawings on the page to an OCG (Optional Content Group).

I am aware that this is possible when you create a drawing/shape yourself (for example: page.draw_rect(rect, oc=xref). However, to the best of my knowledge, it not possible to manipulate existing drawings in the same way since methods such as document.set_oc require the xref for the object being attached to the OCG. However, the existing drawings do not have an associated xref similar to images.

With this in mind: How can I toggle the visibility of exisiting drawings using an OCG/OCMD? Is it even possible utilizing PyMuPDF or is another approach (perhaps low-level) required?

[JorjMcKie]

Congratulations for a clearly described problem situation. Doesn't happen often ... 😒.

Your analysis is correct. No way to make a drawing OCG-eligible afterwards.
What I can think of:

1. it is possible to find the joined bbox of drawings which overlapping pairwise
2. draw a (white) rectangle over this bbox with an OCG-dependency
3. to turn on/off the underlying graphics visible, turn off/on the white bbox.

The code for finding that bbox is here.

[syntax-surgeon]

Thank you @JorjMcKie for the quick response. This method is a good hack for drawing which are standalone and do not overlap with any text. Unfortunately in my use-case several of these drawings are "on-top" of underlying text and obscure it. Attaching them to an OCG was a way to let me see what's underneath within the PDF viewer (GUI) rather than programatically extracting the text.

Another point of discussion is the following: I can often find these drawings (or more specifically: the drawing commands) as their own separate streams (with the associated xref) via page.get_contents(). Is this possible to manipulate these streams directly and then resave the PDF? Also is it possible to attach a stream to an OCG? (I am thinking NOT!)

Just an observation: I have noticed that these "drawing streams" persist even after cleaning the contents via page.clean_contents(sanitize=True). For example:

page.get_contents() # Output = [16, 17, 18]
page.clean_contents(sanitize=True)
page.get_contents() # Output =[16, 17, 18]

In this specific page, the xref 18 is the stream containing the drawing commands. However, I cannot use doc.set_oc() since xref 18 is neither an image nor a XObject.

[JorjMcKie]

This one of your reported results:

page.get_contents() # Output = [16, 17, 18]
page.clean_contents(sanitize=True)
page.get_contents() # Output =[16, 17, 18]

should not occur. I remember we have had an issue in PyMuPDF several versions ago - so maybe you still are on it.

Otherwise - hacking content streams is of course possible if you are willing to follow the white rabbit ...
Text or vector graphics under OC control are wrapped by PDF commands in some special way. The following PDF
text-oc.pdf
shows text within a rectangle. Both are in separate OCGs which is stored in the page object as follows:

In [4]: print(doc.xref_object(page.xref))
<<
  /Type /Page
  /MediaBox [ 0 0 500 400 ]
  /Rotate 0
  /Resources <<
    /Properties <<  % references to OCGs in the contents:
      /MC0 6 0 R  % this one controls the gray rectangle
      /MC1 4 0 R
      /MC2 5 0 R
    >>
    /Font <<
      /helv 7 0 R
    >>
  >>
  /Parent 2 0 R
  /Contents 8 0 R
>>

This is the start of the contents stream:

In [5]: cont=page.read_contents().decode()
In [6]: len(cont)
Out[6]: 2437
In [7]: print(cont[:500])
q
[3 1] 0 d
/OC /MC0 BDC
45 95 360 260 re
h
.8 .8 .8 rg
0 0 1 RG
B
EMC
Q
q
/OC /MC1 BDC
BT
/helv 12 Tf
1 0 0 1 50 337.1 Tm
[(The false killer whale \(Pseudorca crassidens\) is a species of)] TJ
1 0 0 1 50 319.375 Tm

The rectangle's OCG wraps the drawings command in strings /OC /MC0 BDC and EMC.
It can be seen that the text is wrapped by MC1.
The OCG for the drawing (MC0) looks like this:

In [8]: print(doc.xref_object(6))
<<
  /Type /OCG
  /Name (graphic)
  /Intent [ /View ]
  /Usage <<
    /CreatorInfo <<
      /Creator (PyMuPDF)
      /Subtype /Artwork
    >>
  >>
>>

If you are confident to locate the commands for some vector graphics, you could put similar /OC command strings around them, e.g. b"/OC /mymc BDC"/b"EMC". Then take the page's definition and do doc.xref_set_key(page.xref, "Resources/Properties/mymc", "4711 0 R"), where 4711 is the xref of your (previously defined) OCG.

[JorjMcKie]

We were communicating cross-ways.
Here is how to update page /Contents:
If you know the xref (your case), extract it to a bytes object cont = doc.xref_stream(18). If you want to manually edit cont store it as a text file first, e.g. pathlib.Path("con.txt").write_bytes(cont).
Then edit as desired.
To restore the result in xref 18: cont = pathlib.Path("cont.txt").read_bytes(), then doc.update_stream(18, cont).

If you define an OCG, then it at this point will be an independent object - not connected to a page or whatever. Only the PDF knows about it and has it stored in the PDF catalog.

Whether the page's /Resources already has a sub-dictionary /Properties or not: the above will create the full chain of all dictionaries you are naming. So doc.xref_set_key(page.xref, "Resources/Properties/mymc", "4711 0 R") will create sub-dict Properties and below the dict key /mymc with a value of 4711 0 R.
Of course 4711 must the xref of the previously created OCG - which will now be referenced by the page.

[syntax-surgeon]

It's interesting because I did exactly that but I end with this the following error: RuntimeError: path to 'mymc' has indirects.
The simple script is as follows:

doc = fitz.open("data/whitebox_ocg.pdf")
page = doc[0]

doc.get_ocgs()
# Output: {61: {'name': 'whitebox', 'intent': ['View'], 'on': True, 'usage': 'Artwork'}}

page.get_contents()
# Output: [16, 17, 18]

cont = doc.xref_stream(18)
pathlib.Path("data/cont.txt").write_bytes(cont)

# Here I manually updated the data/cont.txt file by prefixing it with /OC /mymc BDC and suffixing with EMC

updated_cont = pathlib.Path("data/cont.txt").read_bytes()
doc.update_stream(18, updated_cont)
doc.xref_set_key(page.xref, "Resources/Properties/mymc", "61 0 R") # 61 is the xref of the OCG already present in the PDF

Executing this script throws the error: RuntimeError: path to 'mymc' has indirects

[JorjMcKie]

Pesky! But solvable.

res = doc.xref_get_key(page.xref, "Resources")
if res[0] == "dict":  # resources directly defined in the page
    doc.xref_set_key(page.xref, "Resources/Properties/mymc", "61 0 R")
else:
    xref = int(res[1].split()[0])  # extract xref number of /Resources
    doc.xref_set_key(xref, "Properties/mymc", "61 0 R")

In the general case, /Properties may also be an xref inside the resources, and thus the same exception may happen ... but I guess you know now how to handle this.

[JorjMcKie]

Some backgound:
The xref_set_key() cannot update if any of the dictionaries in a chain is an xref. In contrast to this, reading a value from the end of a chain is no problem.

[syntax-surgeon]

Thank you @JorjMcKie . This discussion has taught quite a bit about the PyMuPDF internals and the PDF specification in general. A geniune thanks from a PDF novice!

Edit: By the way, it feels good to have chased the white rabbit! The whitebox-ocg.pdf is finally OCG-eligible.
000-whitebox-OCG.pdf