What is the filetype value should I use in fitz.open()?

[Augus1999]

Assume I have an img.png image file and I want to open it in fitz.

img = fitz.open('img.png') works.

However, if I use

img = fitz.open('img.png', filetype='image/png')

it raises a RuntimeError as following:

mupdf: unrecognized file type
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "D:\Python310\lib\site-packages\fitz\fitz.py", line 3845, in __init__
    _fitz.new_Document(
RuntimeError: unrecognized file type

Using filetype='png' or filetype='img.png' gives the same error.
So I'm wondering what value of filetype should it be?

[JorjMcKie]

Weird - did never encounter this before.
This behaviour seems to be restricted to image files: when using this call pattern with PDF, XPS, etc. everything works fine.
I probably need to adjust documentation, saying that the filetype parameter only works for the registered document handlers - to which the images admittedly do not belong, although they can be treated like documents if they carry a valid image file extension.

Interestingly, doc=fitz.open("png", open("file.png", "rb").read()) does work!

[Augus1999]

I have another weird thing to share.

Assume there is a plain text file namely text.txt. If I just rename it to text.jpg and try to open it in fitz, I expect to receive some handleable errors or warnings from fitz and Python, but the result is

>>> img=fitz.open('text.jpg')
>>> img.convert_to_pdf()
mupdf: unknown image file format

then Python exits without rasing any error.

[JorjMcKie]

Oha! This is a bug in PyMuPDF!
Totally unrelated.
I will look into this.

[JorjMcKie]

Found and fixed the error. Unexpectedly, MuPDF even opens invalid images files without any initial plausibility checks - as long as the file extension is among the good guys.
When my conversion routine catches errors it turns out that among the object to deallocate there was an uninitialized one. Fixing this establishes normal behavior again.

[JorjMcKie]

Update on handling wrong file extensions with fitz.open:

1. For non-image file types only, specify argument filetype.
2. For supported image files a wrong file extension is no problem: they will always be opened and handled correctly.
   • But the extension must still be one of the supported images. E.g. there is no way to make a PNG file work as a document via fitz.open("file.data", filetype="png"). This case can only be solved by putting the image in memory.
3. For files in memory, both open formats are accepted (whether or not image): fitz.open("type", memory) and fitz.open(stream=memory, filetype="type").

The behavior for making Pixmap objects is more relaxed: any filename will be accepted and assumed to be an image, and fitz.Pixmap("file.data") will work for any supported image.

[Augus1999]

Yes, fitz.open(stream=open('img.png', 'rb').read(), filetype='png') works.
Thank you.

[JorjMcKie]

I should also explain a detail difference WRT how MuPDF handles image vs. non-image documents:

• For true document types, MuPDF will check the file for basic conformance. E.g. in case of PDF, the presence of an XREF table is verified. In case of XPS and some other formats, it will confirm that the file structure conforms to ZIP, etc.
• Image formats will not immediately be subject to a file structure verification, but an OS file open will just be done. Only when the app accesses content (like loading a page), the file structure will be investigated ... which means the first dozen or so bytes will be inspected to actually determine the image type. This is why a wrong file extension is not being admonished.
  • This is BTW also the reason for the other error you reported: opening a nonsense image file does work because it just is an OS open. Only when accessing the image as a page (via e.g. trying a PDF conversion), the wrong file format is being detected.

[JorjMcKie]

Just for your info:
Triggered by #1601 I am reworking the behavior around fitz.open():

• Parameter filetype will work the same for all document types - including images.
• Empty and invalid input files will be better intercepted and the problem be reported more clearly.