feature: accommodate invalid BMP images at default resolution

[PythonShell]

I met ZeroDivisionError when I just try to add one bmp into a Document, code like this:

from docx import *
from docx.shared import *
doc = Document()
doc.add_picture(u"name-that-contains-chinese-and-space.bmp", height=Inches(4.2))

Error raise:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "D:\Python27\lib\site-packages\python_docx-0.8.5-py2.7.egg\docx\document.py", line 79, in add_picture
    return run.add_picture(image_path_or_stream, width, height)
  File "D:\Python27\lib\site-package\python_docx-0.8.5-py2.7.egg\docx\text\run.py", line 62, in add_picture
    inline = self,part.new_pic_inline(image_path_or_stream, width, height)
  File "D:\Python27\lib\site-package\python_docx-0.8.5-py2.7.egg\docx\parts\document.py", line 92, in new_pic_inline
    cx, cy = image.scaled_dimensions(width, height)
  File "D:\Python27\lib\site-package\python_docx-0.8.5-py2.7.egg\docx\image\image.py", line 154, in scaled_dimensions
    scaling_factor = float(height) / float(self.height)
  File "D:\Python27\lib\site-package\python_docx-0.8.5-py2.7.egg\docx\image\image.py", line 134, in height
    return Inches(self.px_height / self.vert_dpi)
ZeroDivisionError: division by zero

Sorry that I cannot post the original bmp file here, I doubt whether a bug exists.
I also tried add other bmp files, and no error raises.
Currently, I only met the error just on the special bmp file.

I wanna to help, and I'm happy if someone can help.

[scanny]

Just off hand I'd be inclined to think that BMP file doesn't include a vertical DPI figure. Have you looked at the file and seen whether it meets the spec?

It's been quite a while, but I don't believe that field is optional. Happy to consider any results from research you turn up.

[PythonShell]

I searched the web, but cannot find a way to read bmp file's properties.
Using GIMP, I see the resolution ratio is 0.0254 x 0.0254 ppi
Is this information useful?
Or can you tell me how to judge whether the bmp meets the spec.
The BMP file is a photo taken by a camera, which I do not know.

[scanny]

You would need to examine the BMP binary header:
https://en.wikipedia.org/wiki/BMP_file_format#Bitmap_file_header

Perhaps using tools like this:
https://www.youtube.com/watch?v=he-CcmkAIb4

You can also try to find a header viewer or write a little code to check bytes at binary offsets in the BMP file using Python.

The resolution ratio looks very odd, being fractional pixels per inch. A typical value would be 72 ppi. In any case, it should be an integer since having a fraction of a pixel per inch doesn't make a lot of sense. I expect that's why .vert_dpi is evaluating to zero, because that's the value of int(0.0254). It's possible the file is not being created properly or the values could be missing and GIMP is showing you an odd default value rather than what is actually present in the file. It's interesting to note that the value is the reciprocal of 100 pixels per 2.54 centimeters (1 inch). 100 ppi would be a common value, but this is upside down and uses centimeters instead of inches. So big programming screw up by the camera folks if that's how the image got that value :)

I can think of a couple ways to work around. If you specify the width as well as the height, that should do the trick. The only reason python-docx needs to know the pixels per inch is to work out the scaling for you. So that's worth a try if you know the width or can calculate it from a known aspect ratio.

The other idea is to convert the file to some other format, like maybe PNG or GIF and see if that one can be added. There are ways to do that from the command line with free open source packages like ImageMagick Convert. You might also try using Pillow from within Python, depending on your running environment. The conversion program may use an appropriate default value if it gets an odd one in the source image.

[PythonShell]

Thanks for the long reply. I already read wikipedia, while youtube is out of my access.
It's my first time to deal with binary files directly. I could not understand the BMP file format immediately.

My picture size is: 1080 x 809

I follow the example in wikipedia, and guess dpi values' offsets are 26h and 2Ah, both have size of 4.
I use sublime read the file, and get code like this(header part):

424d 1eff 2700 0000 0000 3600 0000 2800
0000 3804 0000 2903 0000 0100 1800 0000
0000 e8fe 2700 0100 0000 0100 0000 0000
0000 0000 0000 9bb2 ba9a b1b9 97ae b696

And I guess dpi values are in the third line(counting group 20st - 24th): 0100 0000 0100 0000
Is this right?

In the wikipedia examples, the value is 2835 which equals B13, coding as 13 0B 00 00.

So I guess I should explain code 0100 0000 as 00 00 00 01, which equals 1. and it means 1 pixel/meter.

Am I correct?

[scanny]

I think your location and byte-order are correct:
https://github.com/python-openxml/python-docx/blob/master/docx/image/bmp.py#L26

And doing the math:

dpi = (1 pixel / 1 meter) * (25.4 mm / 1 inch) * (1 meter / 1000 mm)
# => 0.0254 pixels / 1 inch

Which makes for a mighty big pixel :)

You can see in docx.image.bmp.Bmp._dpi() where it's rounding that to zero:
https://github.com/python-openxml/python-docx/blob/master/docx/image/bmp.py#L56

[PythonShell]

wow, it's amazing. the pixel is really really big.
I think setting the dpi value to a default value(like 96 in source) would raise no error.
I suggest that calculate value first then make the equal-zero-judgement:

tmp_dpi = int(round(px_per_meter * 0.0254))
if tmp_dpi==0:
    return 96
else:
    return tmp_dpi

Thanks for your detailed explanation. I've learned how to read binary files like BMP, and how to suppress the ZeroDivisionError. : )