img: add ImagePart.default_cx, cy

Steve Canny · Steve Canny · commit 8a0d89361432 · 2013-12-29T22:41:57.000-08:00
Along the way:

* transplanted _BaseLength and Inches, Emu, etc. from python-pptx
* renamed width and height to cx, cy in a couple related spots
diff --git a/docx/oxml/shape.py b/docx/oxml/shape.py
@@ -85,7 +85,7 @@ def graphic(self):
         return self.find(qn('a:graphic'))
 
     @classmethod
-    def new(cls, width, height, shape_id, pic):
+    def new(cls, cx, cy, shape_id, pic):
         """
         Return a new ``<wp:inline>`` element populated with the values passed
         as parameters.
@@ -94,7 +94,7 @@ def new(cls, width, height, shape_id, pic):
         uri = nsmap['pic']
 
         inline = OxmlElement('wp:inline', nsmap=nspfxmap('wp', 'r'))
-        inline.append(CT_PositiveSize2D.new('wp:extent', width, height))
+        inline.append(CT_PositiveSize2D.new('wp:extent', cx, cy))
         inline.append(CT_NonVisualDrawingProps.new(
             'wp:docPr', shape_id, name
         ))
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -153,12 +153,12 @@ def new_picture(cls, r, image_part, rId, shape_id):
         placement of *image_part* appended to run *r* and uniquely identified
         by *shape_id*.
         """
-        width, height, filename = (
-            image_part.width, image_part.height, image_part.filename
+        cx, cy, filename = (
+            image_part.default_cx, image_part.default_cy, image_part.filename
         )
         pic_id = 0
-        pic = CT_Picture.new(pic_id, filename, rId, width, height)
-        inline = CT_Inline.new(width, height, shape_id, pic)
+        pic = CT_Picture.new(pic_id, filename, rId, cx, cy)
+        inline = CT_Inline.new(cx, cy, shape_id, pic)
         r.add_drawing(inline)
         return cls(inline)
 
diff --git a/docx/parts/image.py b/docx/parts/image.py
@@ -4,7 +4,9 @@
 The proxy class for an image part, and related objects.
 """
 
-from __future__ import absolute_import, print_function, unicode_literals
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
 
 import hashlib
 import os
@@ -16,7 +18,7 @@
 
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.package import Part
-from docx.shared import lazyproperty
+from docx.shared import Emu, Inches, lazyproperty
 
 
 class Image(object):
@@ -200,6 +202,28 @@ def __init__(self, partname, content_type, blob, image=None):
         super(ImagePart, self).__init__(partname, content_type, blob)
         self._image = image
 
+    @property
+    def default_cx(self):
+        """
+        Native width of this image, calculated from its width in pixels and
+        horizontal dots per inch (dpi).
+        """
+        px_width = self._image.px_width
+        horz_dpi = self._image.horz_dpi
+        width_in_inches = px_width / horz_dpi
+        return Inches(width_in_inches)
+
+    @property
+    def default_cy(self):
+        """
+        Native height of this image, calculated from its height in pixels and
+        vertical dots per inch (dpi).
+        """
+        px_height = self._image.px_height
+        horz_dpi = self._image.horz_dpi
+        height_in_emu = 914400 * px_height / horz_dpi
+        return Emu(height_in_emu)
+
     @property
     def filename(self):
         """
@@ -219,16 +243,6 @@ def from_image(cls, image, partname):
         """
         return ImagePart(partname, image.content_type, image.blob, image)
 
-    @property
-    def height(self):
-        """
-        Native height of this image, calculated from its height in pixels and
-        vertical dots per inch (dpi) when available. Default values are
-        silently substituted when specific values cannot be parsed from the
-        binary image byte stream.
-        """
-        raise NotImplementedError
-
     @classmethod
     def load(cls, partname, content_type, blob, package):
         """
@@ -244,13 +258,3 @@ def sha1(self):
         SHA1 hash digest of the blob of this image part.
         """
         raise NotImplementedError
-
-    @property
-    def width(self):
-        """
-        Native width of this image, calculated from its width in pixels and
-        horizontal dots per inch (dpi) when available. Default values are
-        silently substituted when specific values cannot be parsed from the
-        binary image byte stream.
-        """
-        raise NotImplementedError
diff --git a/docx/shared.py b/docx/shared.py
@@ -7,6 +7,84 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 
+class _BaseLength(int):
+    """
+    Base class for length classes Inches, Cm, Mm, Px, and Emu
+    """
+    _EMUS_PER_INCH = 914400
+    _EMUS_PER_CM = 360000
+    _EMUS_PER_MM = 36000
+    _EMUS_PER_PX = 12700
+
+    def __new__(cls, emu):
+        return int.__new__(cls, emu)
+
+    @property
+    def inches(self):
+        return self / float(self._EMUS_PER_INCH)
+
+    @property
+    def cm(self):
+        return self / float(self._EMUS_PER_CM)
+
+    @property
+    def mm(self):
+        return self / float(self._EMUS_PER_MM)
+
+    @property
+    def px(self):
+        # round can somtimes return values like x.999999 which are truncated
+        # to x by int(); adding the 0.1 prevents this
+        return int(round(self / float(self._EMUS_PER_PX)) + 0.1)
+
+    @property
+    def emu(self):
+        return self
+
+
+class Inches(_BaseLength):
+    """Convenience constructor for length in inches."""
+    def __new__(cls, inches):
+        emu = int(inches * _BaseLength._EMUS_PER_INCH)
+        return _BaseLength.__new__(cls, emu)
+
+
+class Cm(_BaseLength):
+    """Convenience constructor for length in centimeters."""
+    def __new__(cls, cm):
+        emu = int(cm * _BaseLength._EMUS_PER_CM)
+        return _BaseLength.__new__(cls, emu)
+
+
+class Emu(_BaseLength):
+    """Convenience constructor for length in english metric units."""
+    def __new__(cls, emu):
+        return _BaseLength.__new__(cls, int(emu))
+
+
+class Mm(_BaseLength):
+    """Convenience constructor for length in millimeters."""
+    def __new__(cls, mm):
+        emu = int(mm * _BaseLength._EMUS_PER_MM)
+        return _BaseLength.__new__(cls, emu)
+
+
+class Pt(int):
+    """Convenience class for setting font sizes in points"""
+    _UNITS_PER_POINT = 100
+
+    def __new__(cls, pts):
+        units = int(pts * Pt._UNITS_PER_POINT)
+        return int.__new__(cls, units)
+
+
+class Px(_BaseLength):
+    """Convenience constructor for length in pixels."""
+    def __new__(cls, px):
+        emu = int(px * _BaseLength._EMUS_PER_PX)
+        return _BaseLength.__new__(cls, emu)
+
+
 def lazyproperty(f):
     """
     @lazyprop decorator. Decorated method will be called only on first access
diff --git a/tests/parts/test_document.py b/tests/parts/test_document.py
@@ -422,8 +422,8 @@ def image_params(self):
     def image_part_(self, request, image_params):
         filename, rId, cx, cy = image_params
         image_part_ = instance_mock(request, ImagePart)
-        image_part_.width = str(cx)
-        image_part_.height = str(cy)
+        image_part_.default_cx = cx
+        image_part_.default_cy = cy
         image_part_.filename = filename
         return image_part_
 
diff --git a/tests/parts/test_image.py b/tests/parts/test_image.py
@@ -107,12 +107,27 @@ def it_can_construct_from_an_Image_instance(self, from_image_fixture):
         )
         assert isinstance(image_part, ImagePart)
 
+    def it_knows_its_default_dimensions_in_EMU(self, dimensions_fixture):
+        image_part, cx, cy = dimensions_fixture
+        assert image_part.default_cx == cx
+        assert image_part.default_cy == cy
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture
     def blob_(self, request):
         return instance_mock(request, str)
 
+    # param for one known from test_files at 72 dpi and created with from_image
+    # param for one loaded by PartFactory with no Image instance
+    @pytest.fixture
+    def dimensions_fixture(self):
+        image_file_path = test_file('monty-truth.png')
+        image = Image.load(image_file_path)
+        image_part = ImagePart.from_image(image, None)
+        cx, cy = 1905000, 2717800
+        return image_part, cx, cy
+
     @pytest.fixture
     def from_image_fixture(self, image_, partname_, ImagePart__init__):
         return image_, partname_, ImagePart__init__
