Cannot show optional content group: AttributeError: module 'fitz.mupdf' has no attribute 'pdf_array_push_drop'

[stefaneidelloth]

Description of the bug

I tried to set the visibility of an optional content group with

doc.set_layer(config=-1, on=[first_id])

and got

AttributeError: module 'fitz.mupdf' has no attribute 'pdf_array_push_drop'

=> How to correctly show/hide optional content groups?

How to reproduce the bug

Full example:

import fitz  # PyMuPDF

doc = fitz.open()
page = doc.new_page()

# Define the items for the combo box
combo_items = ['first', 'second', 'third']

# Create a combo box field
combo_box = fitz.Widget()  # create a new widget
combo_box.field_type = fitz.PDF_WIDGET_TYPE_COMBOBOX
combo_box.field_name = "myComboBox"
combo_box.field_value = combo_items[0]
combo_box.choice_values = combo_items
combo_box.rect = fitz.Rect(50, 50, 200, 75)  # position of the combo box
combo_box.script_change = """
var value = event.value;
app.alert('You selected: ' + value);

//todo: show selected image/optional content group/layer

"""

# Insert the combo box into the page
# https://pymupdf.readthedocs.io/en/latest/page.html#Page.add_widget
page.add_widget(combo_box)

# Create optional content groups
# https://github.com/pymupdf/PyMuPDF-Utilities/blob/master/jupyter-notebooks/optional-content.ipynb


# Load images and create OCGs for each
optional_content_group_ids = {}
for i, item in enumerate(combo_items):
    optional_content_group_id = doc.add_ocg(item, on=False)
    optional_content_group_ids[item] = optional_content_group_id
    rect = fitz.Rect(50, 100, 250, 300)
    image_file_name = f'{item}.png'
    # xref = page.insert_image(
    #    rect,
    #    filename=image_file_name,
    #    oc=optional_content_group_id,
    # )


first_id = optional_content_group_ids['first']
second_id = optional_content_group_ids['second']
third_id = optional_content_group_ids['third']

# https://pymupdf.readthedocs.io/en/latest/document.html#Document.set_layer


doc.set_layer(-1, basestate="OFF")
layers = doc.get_layer()
doc.set_layer(config=-1, on=[first_id])

# https://pymupdf.readthedocs.io/en/latest/document.html#Document.set_layer_ui_config
# configs = doc.layer_ui_configs()
# doc.set_layer_ui_config(0, fitz.PDF_OC_ON)
# doc.set_layer_ui_config('third', action=2)

# Save the PDF
doc.save("output.pdf")
doc.close()

Example images first.png, second.png, third.png

PyMuPDF version

1.23.23

Operating system

Windows

Python version

3.11

[julian-smith-artifex-com]

Thanks for reporting this. I have a fix in my tree.

[stefaneidelloth]

Thank you. I think this does not make the ocm visible, yet.

I would expect something like

doc.show_ocgs([first_id])

or

doc.set_ocg(first_id, on=True)

But there are no such methods.

=> How to programmatically show a previously hidden ocg (or layer)?

[JorjMcKie]

@stefaneidelloth Please have a look at layer_ui_configs() and set_layer_ui_config(number, action=0).
They get / set the temporary visibility - like a supporting PDF viewer would via its UI.

Close by in that part of the documentation, you will also find ways to make permanent changes.

[stefaneidelloth]

Thanks. As you see in the comments /end of the example, I already tried that. What would be a modified version of the example that works? (I also attached example image files just now.)

[julian-smith-artifex-com]

The pdf_array_push_drop bug is fixed in 1.23.24. I'll leave this issue open though until the other questions are understood/answered.

[julian-smith-artifex-com]

[I've converted this into a discussion, as that seems more appropriate.]

[stefaneidelloth]

Is there some working example that shows how to show optional content groups?

In the doc for set_layer_ui_config it says

number (int,str) – either the sequence number of the item in list Document.layer_configs() or the “text” of one of these items.

Should that be Document.layer_ui_configs() instead of Document.layer_configs() ? Or is the method Document.layer_configs() still missing?

[jamie-lemon]

I think this blog post might have some helpful OCG code examples: https://artifex.com/blog/optional-content-discovering-the-pdf-layers-pymupdf-python

[stefaneidelloth]

Thank you. The suggested command
doc.set_layer(off=[oc_en, oc_gr], on=[])
results in
TypeError: Document.set_layer() missing 1 required positional argument: 'config'

If I use

doc.set_layer(config=-1, off=[oc_en, oc_gr], on=[])

oc_gr is still visible when save the document and open it with Acrobat Reader:

What is the correct argument for config?

# making sure we have required packages installed
# pip install pymupdf
# pip install ipyplot


import fitz  # import PyMuPDF


def show_image(pix):
    """Display a pixmap.

    Just to display images - ignore the man behind the curtain.
    """
    import ipyplot, numpy as np

    img = np.ndarray([pix.h, pix.w, 3], dtype=np.uint8, buffer=pix.samples)
    _ = ipyplot.plot_images([img], labels=[""], custom_texts=[""], img_width=500)


# This is the rectangle we want to draw as text background
rect = fitz.Rect(50, 50, 400, 300)


doc = fitz.open()  # make a new PDF
# also give it a page - a bit larger than the rectangle
page = doc.new_page(height=400, width=500)


# This is the English, respectively German text we want to show:
text_en = (
    "The false killer whale (Pseudorca crassidens) is a species of oceanic"
    " dolphin that is the only extant representative of the genus Pseudorca."
    " It is found in oceans worldwide but mainly in tropical regions."
    " It was first described in 1846 as a species of porpoise based on a skull,"
    " which was revised when the first carcasses were observed in 1861."
    " The name 'false killer whale' comes from having a skull similar to the"
    " orca (Orcinus orca), or killer whale."
    "\nThe false killer whale reaches a maximum length of 6 m (20 ft), though"
    " size can vary around the world. It is highly sociable, known to form"
    " pods of up to 50 members, and can also form pods with other dolphin"
    " species, such as the common bottlenose dolphin (Tursiops truncatus)."
)
text_de = (
    "Der Kleine Schwertwal (Pseudorca crassidens), auch bekannt als Unechter"
    " oder Schwarzer Schwertwal, ist eine Art der Delfine (Delphinidae) und"
    " der einzige rezente Vertreter der Gattung Pseudorca. Er ähnelt dem"
    " Orca in Form und Proportionen, ist aber einfarbig schwarz und mit"
    " einer Maximallänge von etwa sechs Metern deutlich kleiner. Kleine"
    " Schwertwale bilden Schulen von durchschnittlich zehn bis fünfzig"
    " Tieren, wobei sie sich auch mit anderen Delfinen vergesellschaften und"
    " sich meistens abseits der Küsten aufhalten. Sie sind in allen Ozeanen"
    " gemäßigter, subtropischer und tropischer Breiten beheimatet, sind"
    " jedoch vor allem in wärmeren Jahreszeiten auch bis in die gemäßigte"
    " bis subpolare Zone südlich der Südspitze Südamerikas, vor Nordeuropa"
    " und bis vor Kanada anzutreffen."
)


oc_gr = doc.add_ocg("graphics")
oc_en = doc.add_ocg("english")
oc_de = doc.set_ocmd(ocgs=[oc_en], policy="AllOff")

# Draw rectangle as background for the text
page.draw_rect(
    rect + (-5, -5, 5, 5),  # enlarge by 5 pt for nicer text appearance
    fill=fitz.pdfcolor["gray80"],  # fill color some gray
    color=fitz.pdfcolor["blue"],  # border color blue
    oc=oc_gr,  # give it OCG "graphics"
    dashes="[3 1]",  # dashed border: 3 points followed by 1 point gap
)


# Write the text into the rectangle.
page.insert_textbox(
    rect,  # the "box"
    text_en,  # English text
    fontsize=12,  # font size
    oc=oc_en,  # give it the "english" OCG
)


page.insert_textbox(
    rect,  # the "box"
    text_de,  # German text
    fontsize=12,  # font size
    oc=oc_de,  # give it the non-"english" OCMD
)

doc.set_layer(config=-1, off=[oc_en, oc_gr], on=[])

doc.save("output2.pdf")
doc.close()

[fhg-isi]

Are the optional content groups expected to work with mypdf viewer only or also with Acrobat Reader?

[JorjMcKie]

They will work with any PDF viewer that supports layers.

[stefaneidelloth]

Thank you for clarification.

[stefaneidelloth]

Got it working with version 1.23.26. (Don't know what the exact issue has been.)

import fitz  # PyMuPDF

doc = fitz.open()
page = doc.new_page()

# Define the items for the combo box
combo_items = ['first', 'second', 'third']

# Create a combo box field
combo_box = fitz.Widget()  # create a new widget
combo_box.field_type = fitz.PDF_WIDGET_TYPE_COMBOBOX
combo_box.field_name = "myComboBox"
combo_box.field_value = combo_items[0]
combo_box.choice_values = combo_items
combo_box.rect = fitz.Rect(50, 50, 200, 75)  # position of the combo box
combo_box.script_stroke = """
var value = event.value;
var optionalContentGroups = this.getOCGs();
for(var id in optionalContentGroups) {
    var ocg = optionalContentGroups[id];    
    if(ocg.name==value) {
        ocg.state = true;       
    } else {
        ocg.state = false;  
    }  
}
"""

# Insert the combo box into the page
# https://pymupdf.readthedocs.io/en/latest/page.html#Page.add_widget
page.add_widget(combo_box)

# Create optional content groups
# https://github.com/pymupdf/PyMuPDF-Utilities/blob/master/jupyter-notebooks/optional-content.ipynb


# Load images and create OCGs for each
optional_content_group_ids = {}

for index, item in enumerate(combo_items):
    optional_content_group_id = doc.add_ocg(item)

    optional_content_group_ids[item] = optional_content_group_id
    rect = fitz.Rect(50, 100, 250, 300)
    #image_file_name = f'../../images/{item}.png'
    #xref = page.insert_image(
    #    rect,
    #    filename=image_file_name,
    #    oc=optional_content_group_id,
    #)
    page.insert_textbox(
        rect,
        item + "_content",
        fontsize=12,
        oc=optional_content_group_id,
    )


first_id = optional_content_group_ids['first']
second_id = optional_content_group_ids['second']
third_id = optional_content_group_ids['third']

# https://pymupdf.readthedocs.io/en/latest/document.html#Document.set_layer
doc.set_layer(config=-1, off=[second_id, third_id])

doc.save("output.pdf")
doc.close()