Pillow: PIL.Image.crop() documentation is lacking clarity

[Zooce]

This is just a suggestion to update any documentation mentioning a pixel coordinate to have a reference to the coordinate system documentation. For example, the documentation for PIL.Image.crop() is misleading if you don't fully understand the Pillow coordinate system.

From https://pillow.readthedocs.io/en/4.2.x/reference/Image.html:

Returns a rectangular region from this image. The box is a 4-tuple defining the left, upper, right, and lower pixel coordinate.

See the following example.

from PIL import Image

img = Image.open( 'my_image.png' )  # size: 184 x 184

# I want the top left corner of the image with dimensions 46 x 46
# I'm expecting the rows to go from index 0 to 45 (that's 46 pixels tall) and the
# columns to go from index 0 to 45 (that's 46 pixels wide)
left, top, right, bottom = 0, 0, 45, 45
cropped = img.crop( ( left, top, right, bottom ) )  # size: 45, 45

# I don't know that the coordinate system marks pixels at their top left corner...
cropped.getpixel( ( 45, 45 ) )  # IndexError: image index out of range

[hugovk]

Here's what https://pillow.readthedocs.io/en/4.2.x/handbook/concepts.html#coordinate-system says:

Coordinate System

The Python Imaging Library uses a Cartesian pixel coordinate system, with (0,0) in the upper left corner. Note that the coordinates refer to the implied pixel corners; the centre of a pixel addressed as (0, 0) actually lies at (0.5, 0.5).

Coordinates are usually passed to the library as 2-tuples (x, y). Rectangles are represented as 4-tuples, with the upper left corner given first. For example, a rectangle covering all of an 800x600 pixel image is written as (0, 0, 800, 600).

So, as you've discovered, if you want 46x46, use (0, 0, 46, 46).

Pull requests are welcome, docs are generally under https://github.com/python-pillow/Pillow/tree/master/docs and the bit you quoted is from the docstring at https://github.com/python-pillow/Pillow/blob/master/PIL/Image.py#L1043-L1051

[aclark4life]

@Zooce How about a PR for this one? Thanks

[Zooce]

@aclark4life I'm currently quite busy with my master's program and my job, so it's unlikely I'll have time to do this now. I can try to fit this in at the end of the semester, but it may be faster if someone with more time to tackle this now.

[pptr3]

The syntax is the following:
cropped = img.crop( ( x, y, x + width , y + height ) )

x and yare the top left coordinate on image;
x + width and y + height are the width and height respectively of the region that you want to crop starting at x and ypoint.
Note: x + width and y + height are the bottom right coordinate of the cropped region.

[viji-123]

I want to crop a part of an image, say for instance draw a rectangle at a desired angle over a small portion in a large image and then crop that part.
Can you please suggest how i can crop it. I have the center point of the rectangle , height , width and angle at which it is tilted

[aclark4life]

@viji-123 You might check SO e.g. https://stackoverflow.com/questions/9983263/crop-the-image-using-pil-in-python …

[viji-123]

Thanks for the reply. I tried implementing what is suggested there. But am able to achieve like the below only. What i want is to crop an area in that image - like a rectangle portion tilted at an angle

[radarhere]

from PIL import Image
im = Image.open('plane.png')
im = im.rotate(70, Image.BICUBIC)
im = im.crop((166, 335, 248, 388))
im.save('out.png')

[viji-123]

Thanks for the code. But its not cropping at the desired angle inside the image. Its rotating the entire image at the angle 70

[aclark4life]

"If only there was some system we could use to ask technical questions and get answers from the community … " (i.e. maybe let's move this discussion to SO 😈 )

[ankitcsr]

im.crop((x_min,y_min,x_max,y_max))