MSS: accepts to same format as PIL.Image.grab

Mickaël Schoentgen · Mickaël Schoentgen · commit 63fdfaa96fa0 · 2017-08-20T12:35:06.000+02:00
You can give a tuple(left, upper, right, lower) argument and
it will be converted to the appropriate dict.
diff --git a/.pylintrc b/.pylintrc
@@ -1,5 +1,5 @@
 [MESSAGES CONTROL]
-disable = locally-disabled, too-few-public-methods, too-many-instance-attributes
+disable = locally-disabled, too-few-public-methods, too-many-instance-attributes, duplicate-code
 
 [REPORTS]
 output-format = colorized
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -43,6 +43,11 @@ Methods
 
         Retrieve screen pixels for a given monitor.
 
+        .. note::
+
+            ``monitor`` can be a ``tuple`` like ``PIL.Image.grab()`` accepts,
+            it will be converted to the approriate ``dict``.
+
     .. method:: save(mon=1, output='screenshot.png', callback=None) -> generator
 
         :param int mon: the monitor's number.
@@ -59,6 +64,8 @@ Methods
         Helper to save the screenshot of the first monitor, by default.
         You can pass the same arguments as for ``save``.
 
+        .. versionadded:: 3.0.0
+
 .. class:: ScreenShot
 
     Screen shot object.
@@ -86,6 +93,8 @@ Methods
 
         Get the pixel value at the given position.
 
+    .. versionadded:: 3.0.0
+
 .. module:: mss.tools
 
     .. method:: to_png(data, size, output) -> None
@@ -97,6 +106,8 @@ Methods
 
     Dump data to the image file. Pure Python PNG implementation.
 
+    .. versionadded:: 3.0.0
+
 
 Properties
 ==========
@@ -179,6 +190,8 @@ Properties
 
         :type: bytes
 
+    .. versionadded:: 3.0.0
+
 
 Exception
 =========
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -44,6 +44,19 @@ You can capture only a part of the screen:
 .. literalinclude:: examples/part_of_screen.py
     :lines: 9-
 
+.. versionadded:: 3.0.0
+
+Use PIL bbox style and percent values
+-------------------------------------
+
+You can use the same value as you would do with ``PIL.ImageGrab(bbox=tuple(...))``.
+This is an example that uses it, but also using percentage values:
+
+.. literalinclude:: examples/from_pil_tuple.py
+    :lines: 9-
+
+.. versionadded:: 3.1.0
+
 Advanced
 ========
 
@@ -52,6 +65,8 @@ You can handle data using a custom class:
 .. literalinclude:: examples/custom_cls_image.py
     :lines: 9-
 
+.. versionadded:: 3.1.0
+
 PIL
 ===
 
@@ -61,6 +76,8 @@ This is an example using `frombytes() <http://pillow.readthedocs.io/en/latest/re
 .. literalinclude:: examples/pil.py
     :lines: 9-
 
+.. versionadded:: 3.0.0
+
 Playing with pixels
 -------------------
 
@@ -69,6 +86,8 @@ This is an example using `putdata() <https://github.com/python-pillow/Pillow/blo
 .. literalinclude:: examples/pil_pixels.py
     :lines: 9-
 
+.. versionadded:: 3.0.0
+
 OpenCV/Numpy
 ============
 
@@ -79,6 +98,8 @@ And with __no__ lag please.
 .. literalinclude:: examples/opencv_numpy.py
     :lines: 9-
 
+.. versionadded:: 3.0.0
+
 FPS
 ===
 
@@ -89,3 +110,5 @@ Simple naive benchmark to compare with `Reading game frames in Python with OpenC
 
 .. literalinclude:: examples/fps.py
     :lines: 12-
+
+.. versionadded:: 3.0.0
diff --git a/docs/source/examples/from_pil_tuple.py b/docs/source/examples/from_pil_tuple.py
@@ -0,0 +1,30 @@
+# coding: utf-8
+"""
+This is part of the MSS Python's module.
+Source: https://github.com/BoboTiG/python-mss
+
+Use PIL bbox style and percent values.
+"""
+
+import mss
+import mss.tools
+
+
+with mss.mss() as sct:
+    # Use the 1st monitor
+    monitor = sct.monitors[1]
+
+    # Capture a bbox using percent values
+    left = monitor['left'] + monitor['width'] * 5 // 100  # 5% from the left
+    top = monitor['top'] + monitor['height'] * 5 // 100  # 5% from the top
+    right = left + 400  # 400px width
+    lower = top + 400  # 400px height
+    bbox = (left, top, right, lower)
+
+    # Grab the picture
+    # Using PIL would be something like:
+    # im = ImageGrab(bbox=bbox)
+    im = sct.grab(bbox)
+
+    # Save it!
+    mss.tools.to_png(im.rgb, im.size, 'screenshot.png')
diff --git a/mss/base.py b/mss/base.py
@@ -57,6 +57,9 @@ def monitors(self):
             'width':  the width,
             'height': the height
         }
+
+        Note: monitor can be a tuple like PIL.Image.grab() accepts,
+        it must be converted to the approriate dict.
         """
 
         raise NotImplementedError('Subclasses need to implement this!')
diff --git a/mss/darwin.py b/mss/darwin.py
@@ -174,6 +174,15 @@ def grab(self, monitor):
         black pixels.
         """
 
+        # Convert PIL bbox style
+        if isinstance(monitor, tuple):
+            monitor = {
+                'left': monitor[0],
+                'top': monitor[1],
+                'width': monitor[2] - monitor[0],
+                'height': monitor[3] - monitor[1],
+            }
+
         rounded_width = int(math.ceil(monitor['width'] // 16) * 16)
 
         rect = CGRect((monitor['left'], monitor['top']),
diff --git a/mss/linux.py b/mss/linux.py
@@ -273,6 +273,15 @@ def grab(self, monitor):
         # type: (Dict[str, int]) -> ScreenShot
         """ Retrieve all pixels from a monitor. Pixels have to be RGB. """
 
+        # Convert PIL bbox style
+        if isinstance(monitor, tuple):
+            monitor = {
+                'left': monitor[0],
+                'top': monitor[1],
+                'width': monitor[2] - monitor[0],
+                'height': monitor[3] - monitor[1],
+            }
+
         # Fix for XGetImage:
         #     expected LP_Display instance instead of LP_XWindowAttributes
         root = ctypes.cast(self.root, ctypes.POINTER(Display))
diff --git a/mss/windows.py b/mss/windows.py
@@ -162,6 +162,15 @@ def grab(self, monitor):
             Thanks to http://stackoverflow.com/a/3688682
         """
 
+        # Convert PIL bbox style
+        if isinstance(monitor, tuple):
+            monitor = {
+                'left': monitor[0],
+                'top': monitor[1],
+                'width': monitor[2] - monitor[0],
+                'height': monitor[3] - monitor[1],
+            }
+
         srcdc = memdc = bmp = None
         try:
             bmi = BITMAPINFO()
diff --git a/setup.py b/setup.py
@@ -53,7 +53,7 @@
     'classifiers': classifiers,
     'platforms': ['Darwin', 'Linux', 'Windows'],
     'packages': ['mss'],
-    'license': 'MIT'
+    'license': 'MIT',
 }
 
 setup(**config)
diff --git a/tests/test_implementation.py b/tests/test_implementation.py
@@ -8,6 +8,7 @@
 import pytest
 
 import mss
+import mss.tools
 from mss.base import MSSBase
 from mss.exception import ScreenShotError
 from mss.screenshot import ScreenShot
@@ -93,3 +94,46 @@ def raise_():
     with pytest.raises(ScreenShotError):
         mss.mss()
     monkeypatch.undo()
+
+
+def test_grab_with_tuple(sct):
+    left = 100
+    top = 100
+    right = 500
+    lower = 500
+    width = right - left  # 400px width
+    height = lower - top  # 400px height
+
+    # PIL like
+    box = (left, top, right, lower)
+    im = sct.grab(box)
+    assert im.size == (width, height)
+
+    # MSS like
+    box2 = {'left': left, 'top': top, 'width': width, 'height': height}
+    im2 = sct.grab(box2)
+    assert im.size == im2.size
+    assert im.pos == im2.pos
+    assert im.rgb == im2.rgb
+
+
+def test_grab_with_tuple_percents(sct):
+    monitor = sct.monitors[1]
+    left = monitor['left'] + monitor['width'] * 5 // 100  # 5% from the left
+    top = monitor['top'] + monitor['height'] * 5 // 100  # 5% from the top
+    right = left + 500  # 500px
+    lower = top + 500  # 500px
+    width = right - left
+    height = lower - top
+
+    # PIL like
+    box = (left, top, right, lower)
+    im = sct.grab(box)
+    assert im.size == (width, height)
+
+    # MSS like
+    box2 = {'left': left, 'top': top, 'width': width, 'height': height}
+    im2 = sct.grab(box2)
+    assert im.size == im2.size
+    assert im.pos == im2.pos
+    assert im.rgb == im2.rgb

Original file line number	Diff line number	Diff line change
`@@ -57,6 +57,9 @@ def monitors(self):`
`57`	`57`	`'width': the width,`
`58`	`58`	`'height': the height`
`59`	`59`	`}`
	`60`	`+`
	`61`	`+ Note: monitor can be a tuple like PIL.Image.grab() accepts,`
	`62`	`+ it must be converted to the approriate dict.`
`60`	`63`	`"""`
`61`	`64`
`62`	`65`	`raise NotImplementedError('Subclasses need to implement this!')`
Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@`
`53`	`53`	`'classifiers': classifiers,`
`54`	`54`	`'platforms': ['Darwin', 'Linux', 'Windows'],`
`55`	`55`	`'packages': ['mss'],`
`56`		`- 'license': 'MIT'`
	`56`	`+ 'license': 'MIT',`
`57`	`57`	`}`
`58`	`58`
`59`	`59`	`setup(**config)`