Skip to content

Allow window ID to be passed to ImageGrab.grab() on macOS #9070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
radarhere merged 11 commits into from
Dec 1, 2025
Merged

Allow window ID to be passed to ImageGrab.grab() on macOS #9070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5ce88db
feat(ImageGrab): enhance grab function to support window-based screen…
yankeguo Jul 7, 2025
1f7e9c3
Apply suggestions from code review
yankeguo Jul 7, 2025
7eaac3f
Updated documentation
radarhere Jul 7, 2025
79914ec
Check for scaling in macOS windows
radarhere Jul 9, 2025
53302c2
Split versionadded info
radarhere Sep 16, 2025
610d564
Merge branch 'main' into main
radarhere Sep 16, 2025
ca3528f
Document that macOS window value is a CGWindowID
radarhere Sep 16, 2025
c680ff0
Merge branch 'main' into main
radarhere Oct 15, 2025
424168b
Merge branch 'main' into main
yankeguo Oct 16, 2025
88247a9
Updated version
radarhere Nov 19, 2025
65c32ec
retina -> Retina
hugovk Nov 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/reference/ImageGrab.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,11 @@ or the clipboard to a PIL image memory.
.. versionadded:: 7.1.0

:param window:
HWND, to capture a single window. Windows only.
Capture a single window. On Windows, this is a HWND. On macOS, this is a
CGWindowID.

.. versionadded:: 11.2.1
.. versionadded:: 11.2.1 Windows support
.. versionadded:: 12.1.0 macOS support
:return: An image

.. py:function:: grabclipboard()
Expand Down
36 changes: 32 additions & 4 deletions src/PIL/ImageGrab.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,17 +43,45 @@ def grab(
fh, filepath = tempfile.mkstemp(".png")
os.close(fh)
args = ["screencapture"]
if bbox:
if window:
args += ["-l", str(window)]
elif bbox:
left, top, right, bottom = bbox
args += ["-R", f"{left},{top},{right-left},{bottom-top}"]
subprocess.call(args + ["-x", filepath])
im = Image.open(filepath)
im.load()
os.unlink(filepath)
if bbox:
im_resized = im.resize((right - left, bottom - top))
im.close()
return im_resized
if window:
# Determine if the window was in Retina mode or not
# by capturing it without the shadow,
# and checking how different the width is
fh, filepath = tempfile.mkstemp(".png")
os.close(fh)
subprocess.call(
["screencapture", "-l", str(window), "-o", "-x", filepath]
Comment on lines 51 to +63
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The subprocess.call() at lines 51, 62-63 don't check the return code. If screencapture fails (e.g., invalid window ID, permission denied), the code will proceed to try opening a potentially non-existent or corrupt file, which could raise an unexpected exception.

Consider checking the return code and raising an appropriate error:

returncode = subprocess.call(args + ["-x", filepath])
if returncode != 0:
    raise OSError(f"screencapture failed with return code {returncode}")

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've created #9321

)
with Image.open(filepath) as im_no_shadow:
retina = im.width - im_no_shadow.width > 100
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The threshold of 100 pixels to detect Retina mode (im.width - im_no_shadow.width > 100) appears arbitrary and could be fragile. This assumes:

  1. The shadow is always more than 100 pixels wider in non-Retina mode
  2. The shadow scaling difference is consistent across different window sizes

Consider documenting why 100 pixels is the appropriate threshold, or using a relative threshold (e.g., percentage difference) instead of an absolute pixel count.

Suggested change
retina = im.width - im_no_shadow.width > 100
# Detect Retina mode by checking if the width difference is >30% of the no-shadow image width
retina = (im.width - im_no_shadow.width) / im_no_shadow.width > 0.3

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current comment is

Determine if the window was in Retina mode or not by capturing it without the shadow, and checking how different the width is

I think it's reasonably apparent that we're using an absolute threshold

os.unlink(filepath)

# Since screencapture's -R does not work with -l,
# crop the image manually
if retina:
left, top, right, bottom = bbox
im_cropped = im.resize(
(right - left, bottom - top),
Comment on lines +57 to +74
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When both window and bbox are provided, the window is captured 3 times:

  1. Line 51: Initial capture with shadow
  2. Line 62-63: Capture without shadow for Retina detection
  3. Implicitly through the subprocess calls

This is inefficient and could impact performance, especially for larger windows. Consider whether the Retina detection step is necessary, or if there's a way to determine Retina mode without an additional capture.

Suggested change
# Determine if the window was in Retina mode or not
# by capturing it without the shadow,
# and checking how different the width is
fh, filepath = tempfile.mkstemp(".png")
os.close(fh)
subprocess.call(
["screencapture", "-l", str(window), "-o", "-x", filepath]
)
with Image.open(filepath) as im_no_shadow:
retina = im.width - im_no_shadow.width > 100
os.unlink(filepath)
# Since screencapture's -R does not work with -l,
# crop the image manually
if retina:
left, top, right, bottom = bbox
im_cropped = im.resize(
(right - left, bottom - top),
# Use the first captured image's dimensions to infer Retina mode.
# If the image width is roughly double the bbox width, it's Retina.
left, top, right, bottom = bbox
bbox_width = right - left
retina = im.width >= bbox_width * 2
# Since screencapture's -R does not work with -l,
# crop the image manually
if retina:
im_cropped = im.resize(
(bbox_width, bottom - top),

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The window is captured twice.

Implicitly through the subprocess calls

This isn't an additional time.

Consider whether the Retina detection step is necessary, or if there's a way to determine Retina mode without an additional capture.

See discussion at #9070 (comment)

box=tuple(coord * 2 for coord in bbox),
)
Comment on lines +73 to +76
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] In Retina mode, the code uses resize() with a box parameter to crop. However, resize() is primarily intended for scaling, not cropping. While this works (the box parameter specifies the region to sample from the source), it's unconventional and potentially confusing.

Consider using a two-step approach for clarity:

if retina:
    left, top, right, bottom = bbox
    im_cropped = im.crop(tuple(coord * 2 for coord in bbox))
    im_cropped = im_cropped.resize((right - left, bottom - top))

Or document why resize() with box is used instead of the more idiomatic crop() + resize() combination.

Suggested change
im_cropped = im.resize(
(right - left, bottom - top),
box=tuple(coord * 2 for coord in bbox),
)
im_cropped = im.crop(tuple(coord * 2 for coord in bbox))
im_cropped = im_cropped.resize((right - left, bottom - top))

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling two methods would not be more efficient, from a performance perspective, than one.

else:
im_cropped = im.crop(bbox)
im.close()
return im_cropped
else:
im_resized = im.resize((right - left, bottom - top))
im.close()
return im_resized
Comment on lines +46 to +84
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new macOS window capture functionality lacks test coverage. While Tests/test_imagegrab.py includes a test_grab_invalid_handle test for Windows window capture, there are no corresponding tests for macOS window capture scenarios.

Consider adding tests for:

  • Basic window capture on macOS (ImageGrab.grab(window=<valid_window_id>))
  • Window capture with bbox on macOS
  • Invalid window IDs on macOS

This is especially important given the complexity of the Retina detection logic introduced in this PR.

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've created #9321

Comment on lines +82 to +84
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The variable name im_cropped is used here, while a similar operation at line 82 uses im_resized. For consistency and accuracy, consider using im_cropped in both places since both operations effectively crop/extract a region from the original image (one uses crop() and one uses resize() with a box parameter, but both achieve cropping).

Suggested change
im_resized = im.resize((right - left, bottom - top))
im.close()
return im_resized
im_cropped = im.resize((right - left, bottom - top))
im.close()
return im_cropped

Copilot uses AI. Check for mistakes.
Copy link
Member

@radarhere radarhere Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a resize operation, not a crop operation.

return im
elif sys.platform == "win32":
if window is not None:
Expand Down
Loading