Skip to content
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.

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

Deprecate ICNS (width, height, scale) sizes in favour of load(scale) #8352

Merged
merged 4 commits into from
Sep 10, 2024

Conversation

radarhere
Copy link
Member

@radarhere radarhere commented Sep 6, 2024

Normally, an image size is (width, height). However, the ICNS format allows a third dimension to be added to this, scale, that only exists before loading.

https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#icns

sizes
A list of supported sizes found in this icon file; these are a 3-tuple, (width, height, scale), where scale is 2 for a retina icon and 1 for a standard icon. You are permitted to use this 3-tuple format for the size property if you set it before calling load(); after loading, the size will be reset to a 2-tuple containing pixel dimensions (so, e.g. if you ask for (512, 512, 2), the final value of size will be (1024, 1024)).

This is a brief exception to the rule that image sizes have two dimensions. As such, it complicates type hinting, not just in our implementation, but also conceptually for the user - it would be confusing to explain that images might have three dimensions, but only for one format and only briefly.

This PR suggests that we deprecate this third dimension, and instead take an idea from EPS.

https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#loading

If Ghostscript is available, you can call the load() method with the following parameters to affect how Ghostscript renders the EPS.

scale
Affects the scale of the resultant rasterized image. If the EPS suggests that the image be rendered at 100px x 100px, setting this parameter to 2 will make the Ghostscript render a 200px x 200px image instead.

So instead of

im.size = (16, 16, 2)
im.load()

the user can now

im.size = (16, 16)
im.load(2)

@radarhere radarhere added the Deprecation Feature that will be removed in the future label Sep 6, 2024
@hugovk hugovk merged commit e91aedb into python-pillow:main Sep 10, 2024
48 checks passed
@radarhere radarhere deleted the scale branch September 10, 2024 11:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Deprecation Feature that will be removed in the future
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants