Add more examples

- doc: add an example about capturing part of the monitor 2
- doc: add an example about computing BGRA values to RGB

Author: BoboTiG

CHANGELOG

@@ -3,72 +3,75 @@ History:
 <see Git checking messages for history>
 
 dev     2018/xx/xx
-      - add PNG compression level control
+      - removed support for Python 3.4
       - MSS: add the Screenshot.bgra attribute
       - MSS: speed-up grabbing on the 3 platforms
+      - tools: add PNG compression level control to to_png()
       - tests: add leaks.py and benchmarks.py for manual testing
+      - doc: add an example about capturing part of the monitor 2
+      - doc: add an example about computing BGRA values to RGB
 
 3.1.2   2018/01/05
       - removed support for Python 3.3
-      - CI: build the documentation
-      - doc: improvements and fixes (fix #37)
       - MSS: possibility to get the whole PNG raw bytes
       - Windows: capture all visible windows
+      - doc: improvements and fixes (fix #37)
+      - CI: build the documentation
 
 3.1.1   2017/11/27
       - MSS: add the 'mss' entry point
 
 3.1.0   2017/11/16
       - new contributor: Karan Lyons
-      - add the 'Say Thanks' button
-      - doc: several fixes (fix #22)
-      - tests: a lot of tests added for better coverage
       - MSS: add more way of customization to the output argument of save()
       - MSS: possibility to use custom class to handle screen shot data
       - Mac: properly support all display scaling and resolutions (fix #14, #19, #21, #23)
       - Mac: fix memory leaks (fix #24)
       - Linux: handle bad display value
       - Windows: take into account zoom factor for high-DPI displays (fix #20)
+      - doc: several fixes (fix #22)
+      - tests: a lot of tests added for better coverage
+      - add the 'Say Thanks' button
 
 3.0.1   2017/07/06
       - fix examples links
 
 3.0.0   2017/07/06
       - big refactor, introducing the ScreenShot class
-      - add Numpy array interface support
-      - examples: add OpenCV/Numpy, PIL pixels, FPS
+      - MSS: add Numpy array interface support to the Screenshot class
+      - docs: add OpenCV/Numpy, PIL pixels, FPS
 
 2.0.22  2017/04/29
       - new contributors: David Becker, redodo
-      - add an example to capture only a part of the screen
-      - better use of exception mechanism
+      - MSS: better use of exception mechanism
       - Linux: use of hasattr to prevent Exception on early exit
       - Mac: take into account extra black pixels added when screen with is not divisible by 16 (fix #14)
+      - docs: add an example to capture only a part of the screen
 
 2.0.18  2016/12/03
       - change license to MIT
       - new contributor: Jochen 'cycomanic' Schroeder
-      - add type hints
-      - add documentation (fix #10)
-      - add tests and use Travis CI (fix #9)
-      - remove unused code (reported by Vulture)
+      - MSS: add type hints
+      - MSS: remove unused code (reported by Vulture)
       - Linux: remove MSS library
       - Linux: insanely fast using only ctypes
       - Linux: skip unused monitors
       - Linux: use errcheck instead of deprecated restype with callable (fix #11)
       - Linux: fix security issue (reported by Bandit)
+      - docs: add documentation (fix #10)
+      - tests: add tests and use Travis CI (fix #9)
 
 2.0.0   2016/06/04
       - split the module into several files
-      - add issue and pull request templates
-      - a lot of code refactor and optimizations
+      - MSS: a lot of code refactor and optimizations
       - MSS: rename save_img() to to_png()
       - MSS: save(): replace 'screen' argument by 'mon'
       - Mac: get rid of the PyObjc module, 100% ctypes
       - Linux: prevent segfault when DISPLAY is set but no X server started
       - Linux: prevent segfault when Xrandr is not loaded
       - Linux: get_pixels() insanely fast, use of MSS library (C code)
       - Windows: fix #6, screen shot not correct on Windows 8
+      - add issue and pull request templates
 
 1.0.2   2016/04/22
       - MSS: fix non existent alias
@@ -78,28 +81,28 @@ dev     2018/xx/xx
 
 1.0.0   2015/04/16
       - Python 2.6 to 3.5 ready
-      - code purgation and review, no more debug informations
-      - delete --debug argument
+      - MSS: code purgation and review, no more debug informations
       - MSS: fix #5, add a shortcut to take automatically use the proper MSS class
       - MSS: few optimizations into save_img()
       - Darwin: remove rotation from informations returned by enum_display_monitors()
       - Linux: fix object has no attribute 'display' into __del__
       - Linux: use of XDestroyImage() instead of XFree()
       - Linux: optimizations of get_pixels()
       - Windows: huge optimization of get_pixels()
+      - CLI: delete --debug argument
 
 0.1.1   2015/04/10
-      - little code review
-      - add doc/TESTING
-      - remove Bonus section from README.rst
-      - tests: remove test-linux binary
+      - MSS: little code review
       - Linux: fix monitor count
+      - tests: remove test-linux binary
+      - docs: add doc/TESTING
+      - docs: remove Bonus section from README.rst
 
 0.1.0   2015/04/10
-      - fix code with YAPF tool
-      - better tests and examples
+      - MSS: fix code with YAPF tool
       - Linux: fully functional using Xrandr library
       - Linux: code purgation (no more XML files to parse)
+      - docs: better tests and examples
 
 0.0.8   2015/02/04
       - new contributors: sergey-vin, Alexander 'thehesiod' Mohr
@@ -113,16 +116,16 @@ dev     2018/xx/xx
 
 0.0.6   2014/03/19
       - new contributor: Sam from sametmax.com
-      - PEP8 compliant
       - Python 3.4 ready
-      - review module structure to fit the "Code Like a Pythonista: Idiomatic Python"
-      - refactoring of all enum_display_monitors() methods
-      - fix misspellings using 'codespell' tool
-      - possibility to append '--debug' to the command line
-      - better way to manage output filenames (callback)
-      - several fixes here and there, code refactoring
+      - PEP8 compliant
+      - MSS: review module structure to fit the "Code Like a Pythonista: Idiomatic Python"
+      - MSS: refactoring of all enum_display_monitors() methods
+      - MSS: fix misspellings using 'codespell' tool
+      - MSS: better way to manage output filenames (callback)
+      - MSS: several fixes here and there, code refactoring
       - MSS: moved into a MSS:save_img() method
       - Linux: add XFCE4 support
+      - CLI: possibility to append '--debug' to the command line
 
 0.0.5   2013/11/01
       - MSS: code simplified

docs/source/examples.rst

@@ -45,6 +45,18 @@ You can capture only a part of the screen:
 
 .. versionadded:: 3.0.0
 
+
+Part of the screen of the 2nd monitor
+-------------------------------------
+
+This is an example of capturing some part of the screen of the monitor 2:
+
+.. literalinclude:: examples/part_of_screen_monitor_2.py
+    :lines: 9-
+
+.. versionadded:: 3.0.0
+
+
 Use PIL bbox style and percent values
 -------------------------------------
 
@@ -120,3 +132,37 @@ Simple naive benchmark to compare with `Reading game frames in Python with OpenC
     :lines: 12-
 
 .. versionadded:: 3.0.0
+
+
+BGRA to RGB
+===========
+
+Differents possiblities to convert raw BGRA values to RGB::
+
+    def mss_rgb(im):
+        """ Better than Numpy versions, but slower than Pillow. """
+        return im.rgb
+
+
+    def numpy_flip(im):
+        """ Most efficient Numpy version as of now. """
+        frame = numpy.array(im, dtype=numpy.uint8)
+        return numpy.flip(frame[:, :, :3], 2).tobytes()
+
+
+    def numpy_slice(im):
+        """ Slow Numpy version. """
+        return numpy.array(im, dtype=numpy.uint8)[..., [2, 1, 0]].tobytes()
+
+
+    def pil_frombytes(im):
+        """ Efficient Pillow version. """
+        return Image.frombytes('RGB', im.size, im.bgra, 'raw', 'BGRX').tobytes()
+
+
+    with mss.mss() as sct:
+        im = sct.grab(sct.monitors[1])
+        rgb = pil_frombytes(im)
+        ...
+
+.. versionadded:: 3.2.0

docs/source/examples/part_of_screen_monitor_2.py

@@ -0,0 +1,33 @@
+# coding: utf-8
+"""
+This is part of the MSS Python's module.
+Source: https://github.com/BoboTiG/python-mss
+
+Example to capture part of the screen of the monitor 2.
+"""
+
+import mss
+import mss.tools
+
+
+with mss.mss() as sct:
+    # Get information of monitor 2
+    monitor_number = 2
+    mon = sct.monitors[monitor_number]
+
+    # The screen part to capture
+    monitor = {
+        'top': mon['top'] + 100,  # 100px from the top
+        'left': mon['left'] + 100,  # 100px from the left
+        'width': 160,
+        'height': 135,
+        'mon': monitor_number,
+    }
+    output = 'sct-mon{mon}_{top}x{left}_{width}x{height}.png'.format(**monitor)
+
+    # Grab the data
+    sct_img = sct.grab(monitor)
+
+    # Save to the picture file
+    mss.tools.to_png(sct_img.rgb, sct_img.size, output=output)
+    print(output)

docs/source/examples/pil.py

@@ -17,7 +17,9 @@
         sct_img = sct.grab(monitor)
 
         # Create the Image
-        img = Image.frombytes('RGB', sct_img.size, sct_img.rgb)
+        img = Image.frombytes('RGB', sct_img.size, sct_img.bgra, 'raw', 'BGRX')
+        # The same, but less efficient:
+        # img = Image.frombytes('RGB', sct_img.size, sct_img.rgb)
 
         # And save it!
         output = 'monitor-{0}.png'.format(num)

docs/source/support.rst

@@ -24,7 +24,9 @@ Abandoned
 =========
 
 - Python 2.6 (2016-10-08)
-- Python 3.0, 3.1, and 3.2 (2016-10-08)
+- Python 3.0 (2016-10-08)
+- Python 3.1 (2016-10-08)
+- Python 3.2 (2016-10-08)
 - Python 3.3 (2017-12-05)
 - Python 3.4 (2018-03-19)
 

tests/bench_bgra2rgb.py

@@ -0,0 +1,68 @@
+# coding: utf-8
+"""
+2018-03-19.
+
+Maximum screenshots in 1 second by computing BGRA raw values to RGB.
+
+
+GNU/Linux
+  pil_frombytes 595
+  mss_rgb       437
+  numpy_flip    183
+  numpy_slice   156
+
+macOS
+  pil_frombytes 115
+  mss_rgb       108
+  numpy_flip     67
+  numpy_slice    65
+
+Windows
+  pil_frombytes 294
+  mss_rgb       261
+  numpy_flip    124
+  numpy_slice   115
+"""
+
+import time
+
+import numpy
+from PIL import Image
+
+import mss
+
+
+def mss_rgb(im):
+    return im.rgb
+
+
+def numpy_flip(im):
+    frame = numpy.array(im, dtype=numpy.uint8)
+    return numpy.flip(frame[:, :, :3], 2).tobytes()
+
+
+def numpy_slice(im):
+    return numpy.array(im, dtype=numpy.uint8)[..., [2, 1, 0]].tobytes()
+
+
+def pil_frombytes(im):
+    return Image.frombytes('RGB', im.size, im.bgra, 'raw', 'BGRX').tobytes()
+
+
+def benchmark(func):
+    with mss.mss() as sct:
+        m = {'top': 0, 'left': 0, 'width': 640, 'height': 480}
+        count = 0
+        start = time.time()
+
+        while (time.time() - start) <= 1:
+            frame = func(sct.grab(m))  # noqa
+            count += 1
+
+        print(func.__name__, count)
+
+
+benchmark(pil_frombytes)
+benchmark(mss_rgb)
+benchmark(numpy_flip)
+benchmark(numpy_slice)

tests/benchmarks.py renamed to tests/bench_general.py

@@ -1,3 +1,29 @@
+# coding: utf-8
+"""
+2018-03-19.
+
+Original means MSS 3.1.2.
+Patched  means MSS 3.2.0.
+
+
+GNU/Linux    Original Patched   Gain %
+  grab           2618    2738    +4.58
+  access_rgb     1083    1128    +4.15
+  output          324     322   ------
+  save            320     319   ------
+
+macOS
+  grab            524     526   ------
+  access_rgb      396     406    +2.52
+  output          194     195   ------
+  save            193     194   ------
+
+Windows
+  grab           1280    2498   +95.16
+  access_rgb      574     712   +24.04
+  output          139     188   +35.25
+"""
+
 from time import time
 import mss
 import mss.tools

tests/test_third_party.py

@@ -54,10 +54,17 @@ def test_pil_bgra(sct):
     box = {'top': 0, 'left': 0, 'width': width, 'height': height}
     sct_img = sct.grab(box)
 
-    img = Image.frombytes('RGBX', sct_img.size, sct_img.bgra)
-    assert img.mode == 'RGBX'
+    img = Image.frombytes('RGB', sct_img.size, sct_img.bgra, 'raw', 'BGRX')
+    assert img.mode == 'RGB'
     assert img.size == sct_img.size
 
+    for x in range(width):
+        for y in range(height):
+            assert img.getpixel((x, y)) == sct_img.pixel(x, y)
+
+    img.save('box-bgra.png')
+    assert os.path.isfile('box-bgra.png')
+
 
 @pytest.mark.skipif(
     Image is None,