OCG / Layer renaming

[dchritton]

I'm hoping to use PyMuPDF for a script to run through a file with 100+ layers and rename each one depending on a set of criteria or delete that layer.

I've read through the docs and can't find the functionality to rename or delete layers. Is this something PyMuPDF can do?

[JorjMcKie]

Let's check. We will make it work if it does not already 😎 OC is new functionality in PyMuPDF, so I am ready to fill any gaps ...

In PDF there are configuration layers, representing ON / OFF states of the various OCGs. Used to switch between different such states, without having to do this for each single OCG. Any such switching is temporary only, i.e. the standard configuration is active again on the next open.
There is however the option to declare such a non-standard configuration permanent. In that case it replaces the stanard config, and all other configs are deleted.
The PyMuPDF method doing this is doc.set_layer_config(config, as_default=False). config is the optional config number (0-based).
doc.layer_configs() shows a list of existing ones (excluding the standard one).

When some configuration is active, there is also a way, to set single OCGs on or off temporarily.

In addition, for each configuration (including the standard one), you can permanently change the ON / OFF state of OCGs via doc.set_oc_states(config, on=None, off=None, basestate=None, rbgroups=None). The config is the layer number, use -1 for the standard one.
The keys correspond to on => /ON, off => /OFF and rbgroups => /RBGroups in PDF. On and off are lists of xref numbers of OCGs, rbgroups is a list of lists of xref numbers. "RBGroups" indicates that sublists of xref numbers should behave like radio buttons, where switching one on automatically switches the others off.

Then you can combine multiple existing OCGs into logical expressions, so-called OCMDs, OC membership dictionaries. A viewer will evaluate the expression of an OCMD, interpeting false as OFF and true as ON.
Otherwise, OCMDs can be used like OCGs when attaching an OC state to supporting objects (annotations, images, form xobjects, drawings and text).
All this is supported by PyMuPDF.

Hope I haven't forgotten something important ...

[JorjMcKie]

I am aware that desireable functionality is still missing in PyMuPDF:

• while it is possible to add OCGs via doc.add_ocg(name, config=- 1, on=True, intent='View', usage='Artwork'), there is no way yet to update an existing OCG. Especially the OCG name might be interesting, because it is used in viewers as an identifier. Its other properties probably are less interesting (except maybe intent).
• there is currently no way to influence the /Order entry of a layer. This entry decides if and how OCGs are to be presented by viewers. What I am doing now is simply appending any new OCG to that array, so it will appear in a viewer.

[JustSaX]

Are there any updates on renaming or deleting layers or OCGs? I use pymupdf to highlight words in PDFs and save the highlights in different layers. I would like to be able to delete the layers in case I don't need them anymore. Or is there a way that to inactivate the layer so that viewers don't show it anymore?

[JorjMcKie]

@JustSaX - I have not worked on this in the meantime, so no status change.

But I am not sure what you want to achieve:
If you want to show an annotation unconditionally (not subject to any OC), just remove its oc property.
If you never want to show an annotation, you can either of course delete it altogether, or assign an oc property which always evaluates to OFF.

[JustSaX]

@JorjMcKie Thanks for replying.

I use pymupdf to highlight words in scientific papers so that I can quicker read through the paper. As I do want the highlights to be permanently I put them in an OCG layer and name it. This gives me the possibility to toggle visibility of the highlighted words in a PDF viewer. Overtime I end up having several layers in PDFs. Some of those layers I would like to remove so I don't have unnecessary layers shown in my PDF viewer. I don't mind if the layers are in the PDF but it would be nice if they are not shown by PDF viewers.

So I could programmatically remove all the highlights/annotations in a layer but that still would leave me with an empty layer that will be part of the list of layers that my PDF viewer shows, or?

[JorjMcKie]

empty layer that will be part of the list of layers that my PDF viewer shows

Correct, and that has not been addressed as yet. On the other hand, the structure of the relevant OCProperties object is not overly complex. So there is a way to achieve the desired using pure Python code, if the low-level interface is employed also:
Alternate layers are contained in sub-object /Configs - an array. By string manipulation via doc.xref_set_key() you could remove obsolete layers from there - they are probably referenced indirectly via their xref.
Otherwise, each config in that array is represented by a string that is enclosed in <<...>>.

[JorjMcKie]

Can you please let me have an example file which you would like to be cleaned up?
Maybe I can find a simple way to do this.

[JustSaX]

Hi @JorjMcKie thanks for looking into this. Example file is attached.

OCG_layer_example.pdf

[JorjMcKie]

Looked at your file - thanks for providing it.
We are not talking about layers in this case! You just created 3 OCGs and you assigned names like "Layer1" to them. There is only the standard configuration. So the PDF catalog looks like this:

doc=fitz.open("OCG_layer_example.pdf")
print(doc.xref_object(doc.pdf_catalog()))
<<
  /Type /Catalog
  /Pages 1 0 R
  /OCProperties <<
    /OCGs [ 18 0 R 23 0 R 28 0 R ]
    /D <<
      /ON [ 18 0 R 23 0 R 28 0 R ]
      /OFF [ ]
      /Order [ 18 0 R 23 0 R 28 0 R ]
      /RBGroups [ ]
    >>
  >>
>>
pprint(doc.get_ocgs())
{18: {'intent': ['View'], 'name': 'Layer1', 'on': True, 'usage': 'Artwork'},
 23: {'intent': ['View'], 'name': 'Layer2', 'on': True, 'usage': 'Artwork'},
 28: {'intent': ['View'], 'name': 'Layer3', 'on': True, 'usage': 'Artwork'}}

Each of the 3 OCGs is used by annotations which highlight some text - apparently using a specific color each.
To set for example Layer3 to be permanently invisible, you can do simply this:

doc.set_layer(-1, on=[18, 23], off=[28])
# this will change the catalog like this:
print(doc.xref_object(doc.pdf_catalog()))
<<
  /Type /Catalog
  /Pages 1 0 R
  /OCProperties <<
    /OCGs [ 18 0 R 23 0 R 28 0 R ]
    /D <<
      /RBGroups [ ]
      /ON [ 18 0 R 23 0 R ]
      /Order [ 18 0 R 23 0 R 28 0 R ]
      /OFF [ 28 0 R ]
    >>
  >>
>>

In Adobe and other viewers, Layer3 is still there but set to OFF.
The feature gap we actually have is, that "28 0 R" still appears in the catalog. Here comes in what I referred to alluding to "low-level code":
As a hacky, intermediate solution, you could remove string "28 0 R" from the OCProperties subdictionary in the catalog:

# after open the file in original state:
occp = doc.xref_get_key(doc.pdf_catalog(), "OCProperties")
print(occp)
('dict', '<</OCGs[18 0 R 23 0 R 28 0 R]/D<</ON[18 0 R 23 0 R 28 0 R]/OFF[]/Order[18 0 R 23 0 R 28 0 R]/RBGroups[]>>>>')
# remove ref to xref 28 and replace the occp
new_occp = occp[1].replace("28 0 R", "")
doc.xref_set_key(doc.pdf_catalog(), "OCProperties", new_occp)
# done

[JorjMcKie]

If you do the previous, the layer disappears, and all annotations referring to it will be shown. Their oc property will simply be ignored after the change.

[JustSaX]

This works, Thanks!

If I want to delete the annotations as well and not only the layer, is there another way to iterate over every annotation on every page and remove the annotation?

[JorjMcKie]

Sure:

# deletes all annots on all pages
for page in doc:
    annot = page.first_annot
    while annot:
        annot = page.delete_annot(annot)  # deletes annot and returns next one (or None)

Or if you want to delete specific annotations e.g. referring to some OCG:

annots = [a for a in page.annots() if a.get_oc() == 28]
for a in annots:
    page.delete_annot(a)

[JustSaX]

Thanks @JorjMcKie for your help and time! Very appreciated.

[occludedpixel]

Is the following still the way to go about delete an OCG?

In Adobe and other viewers, Layer3 is still there but set to OFF. The feature gap we actually have is, that "28 0 R" still appears in the catalog. Here comes in what I referred to alluding to "low-level code": As a hacky, intermediate solution, you could remove string "28 0 R" from the OCProperties subdictionary in the catalog:

# after open the file in original state:
occp = doc.xref_get_key(doc.pdf_catalog(), "OCProperties")
print(occp)
('dict', '<</OCGs[18 0 R 23 0 R 28 0 R]/D<</ON[18 0 R 23 0 R 28 0 R]/OFF[]/Order[18 0 R 23 0 R 28 0 R]/RBGroups[]>>>>')
# remove ref to xref 28 and replace the occp
new_occp = occp[1].replace("28 0 R", "")
doc.xref_set_key(doc.pdf_catalog(), "OCProperties", new_occp)
# done

[JorjMcKie]

We currently have no plans to do something here and we also see no convincing reason to add this functionality.

1. Doing this properly can be quite complex and is error-prone.
2. You can easily set an OCG to a desired state and then include it in the "locked" list to prevent future changes.
3. File size implications of an OCG being present or not are very small.