`PILToTensor` input shape description is wrong/confusing

[nicolasdumitru]

📚 The doc issue

The PILToTensor documentation pages (for both torchvision.transforms.v2.PILToTensor and torchvision.transforms.PILToTensor) state:

Converts a PIL Image (H x W x C) to a Tensor of shape (C x H x W).

This is confusing, because img.size returns the dimensions of a PIL.Image (img, in this case) in (width, height) format.

Suggest a potential alternative/fix

Change the quoted statement to the following:

Converts a PIL Image (W x H x C) to a Tensor of shape (C x H x W).

[AntoineSimoulin]

Hey @nicolasdumitru, Thanks for posting this issue! I understand the confusion regarding image shape conventions.

A PIL (Pillow) Image object does not directly expose a shape attribute, but rather a size attribute as a tuple (W, H). This differs from NumPy, where an image array typically has the shape (H, W, C), and from TorchVision, where a tensor image has the shape (C, H, W).

The class torchvision.transforms.v2.PILToTensor ultimately calls the function pil_to_tensor, which converts the input PIL Image to an intermediate NumPy array of shape (H, W, C), and then to a tensor of shape (C, H, W). So in this case, the shape attributes refer to the NumPy array conversion from the input image.

While this may not be immediately clear, it is consistent with other parts of the codebase. For example, the ToTensor class can accept either a PIL Image or a NumPy array of shape (H, W, C) as input.

Since some objects accept both PIL Images and NumPy arrays as input, the documentation describes the input shape based on the NumPy array conversion.

Does it make sense? Maybe we can modify this specific docstring to convey this message?

[nicolasdumitru]

Yes, this totally makes sense in the case of converting from NumPy arrays. I just took another look at the source linked in the doc page and I saw that the function raises an error if the input is not a PIL Image, so we should also make this clear. Certainly, consistency with other parts of the codebase is important and should be preserved. However, since the function does not support converting from NumPy arrays, it is just as important to clarify the differences between the conventions of the actual input and output types. I think modifying the docstring to convey this kind of message is the right thing to do. The message could include something like the following for clarity about the shapes and sizes:

Converts a PIL Image with size (W, H) to a Tensor of shape (C x H x W).

Adding a link to the Pillow documentation for Image.size, as above would also be great.