Revamp transforms doc #7859

NicolasHug · 2023-08-21T11:20:22Z

Reorganize API ref in to 2 separate sections: one for V2, one for V1
Document the v2 functional (docstrings still to be done)
Lots of re-writes and additional info
Make v2 the "officially recommended" namespace

Will follow-up with changes to the gallery examples when this is done.

cc @vfdev-5

pytorch-bot · 2023-08-21T11:20:24Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/vision/7859

📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 6 New Failures, 1 Unrelated Failure

As of commit 7f6a39d with merge base 2c44eba ():

NEW FAILURES - The following jobs have failed:

BROKEN TRUNK - The following job failed but were present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

pytorch/vision / wheel-py3_8-cpu-aarch64 (gh)

This comment was automatically generated by Dr. CI and updates every 15 minutes.

NicolasHug · 2023-08-21T11:21:12Z

gallery/v2_transforms/plot_datapoints.py

+# Inplace operations on datapoints like ``obj.add_()`` will preserve the type of
+# ``obj``. However, the **returned** value of inplace operations will be a pure
+# tensor:


This is more of a drive-by. Turns out those inplace operations aren't really exceptions at all.

NicolasHug · 2023-08-21T11:24:18Z

docs/source/transforms.rst

@@ -5,242 +5,449 @@ Transforming and augmenting images

 .. currentmodule:: torchvision.transforms

+Torchvision supports common computer vision transformations in the


All the text below is mostly new. There was very little copy/pasting. Mostly re-writing from scratch. Best to ignore the diff when reviewing.

NicolasHug · 2023-08-21T11:27:14Z

docs/source/transforms.rst

    v2.Resize
    v2.ScaleJitter
    v2.RandomShortestSize
    v2.RandomResize
-    RandomCrop
+
+Functionals


I opted to separate the functionals into [subsubsubsub]sections like that. The alternative is to put e.g. resize just below Resize, but I found that to hurt readability of the rendered docs because it creates tables that are too long, and it becomes hard to figure out which transforms are actually supported.

(I didn't change the way we document the v1 stuff)

docs/source/transforms.rst

vfdev-5 · 2023-08-21T11:58:34Z

@NicolasHug great work rewriting transforms.rst !

vfdev-5

LGTM, thanks a lot !

pmeier

Some minor comments inline. Otherwise, I stumbled over this:

vision/torchvision/transforms/v2/_type_conversion.py

Lines 46 to 47 in 2c44eba

    
           class ToPILImage(Transform): 
        
               """[BETA] Convert a tensor or an ndarray to PIL Image - this does not scale values.

This does not come from this PR, but might be worth fixing here.

For the most common case, i.e. tensor input and omitting the mode parameter, we do in fact scale the values:

vision/torchvision/transforms/functional.py

Lines 289 to 291 in 2c44eba

    
           if isinstance(pic, torch.Tensor): 
        
               if pic.is_floating_point() and mode != "F": 
        
                   pic = pic.mul(255).byte()

Meaning, this transform will fail for users that do ToPILImage(my_float_image_tensor * 255)

Anyway, that is not really important. Thanks Nicolas for the major rewrite!

docs/source/transforms.rst

pmeier · 2023-08-21T22:08:04Z

docs/source/transforms.rst

+Transforms tend to be sensitive to the input strides / memory layout. Some
+transforms will be faster with channels-first images while others prefer
+channels-last. You may want to experiment a bit if you're chasing the very


Since we had user confusion before, should we point out here that we are talking about the memory layout and not the actual shape of the tensor?

addressed in 7f6a39d

docs/source/transforms.rst

pmeier · 2023-08-21T22:09:40Z

docs/source/transforms.rst

+    parametrization. The ``get_params()`` class method of the transforms class
+    can be used to perform parameter sampling when using the functional APIs.


A public get_params is only available for BC for v1 transforms. Should we advertise this here?

It is still the only way to sample parameters, right? I don't think we just added it for BC, we added it for feature completeness.

Co-authored-by: Philip Meier <github.pmeier@posteo.de>

Summary: (Note: this ignores all push blocking failures!) Reviewed By: matteobettini Differential Revision: D48900378 fbshipit-source-id: 2746d77f5c3a01223a98a20ba12f217b89d9652b Co-authored-by: Philip Meier <github.pmeier@posteo.de>

NicolasHug added 6 commits August 18, 2023 15:31

Separate v1 and v2 sections

f0d1e36

Move torchscript note down

0305140

Remove old irrelevant warning

5b67b1d

Some refac

e48314d

Some more

b4d17f4

Merge branch 'main' of github.com:pytorch/vision into transforms_Docs_fi

7d904d5

NicolasHug requested review from vfdev-5 and pmeier August 21, 2023 11:20

NicolasHug commented Aug 21, 2023

View reviewed changes

NicolasHug added module: transforms module: documentation enhancement labels Aug 21, 2023

NicolasHug commented Aug 21, 2023

View reviewed changes

vfdev-5 reviewed Aug 21, 2023

View reviewed changes

docs/source/transforms.rst Show resolved Hide resolved

vfdev-5 approved these changes Aug 21, 2023

View reviewed changes

empty

d20b759

facebook-github-bot added the cla signed label Aug 21, 2023

pmeier approved these changes Aug 21, 2023

View reviewed changes

NicolasHug and others added 3 commits August 22, 2023 09:21

Update docs/source/transforms.rst

7a3df36

Co-authored-by: Philip Meier <github.pmeier@posteo.de>

Update docs/source/transforms.rst

995ab7c

Co-authored-by: Philip Meier <github.pmeier@posteo.de>

clarify layout

7f6a39d

NicolasHug merged commit 37081ee into pytorch:main Aug 22, 2023

NicolasHug mentioned this pull request Aug 22, 2023

clarifying docs for v2.ToPILImage() #7864

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revamp transforms doc #7859

Revamp transforms doc #7859

NicolasHug commented Aug 21, 2023 •

edited

Loading

pytorch-bot bot commented Aug 21, 2023 •

edited

Loading

NicolasHug Aug 21, 2023

NicolasHug Aug 21, 2023 •

edited

Loading

NicolasHug Aug 21, 2023

vfdev-5 commented Aug 21, 2023

vfdev-5 left a comment

pmeier left a comment

pmeier Aug 21, 2023

NicolasHug Aug 22, 2023

pmeier Aug 21, 2023

NicolasHug Aug 22, 2023

		@@ -5,242 +5,449 @@ Transforming and augmenting images

		.. currentmodule:: torchvision.transforms

		Torchvision supports common computer vision transformations in the

	class ToPILImage(Transform):
	"""[BETA] Convert a tensor or an ndarray to PIL Image - this does not scale values.

	if isinstance(pic, torch.Tensor):
	if pic.is_floating_point() and mode != "F":
	pic = pic.mul(255).byte()

		parametrization. The ``get_params()`` class method of the transforms class
		can be used to perform parameter sampling when using the functional APIs.

Revamp transforms doc #7859

Revamp transforms doc #7859

Conversation

NicolasHug commented Aug 21, 2023 • edited Loading

pytorch-bot bot commented Aug 21, 2023 • edited Loading

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/vision/7859

❌ 6 New Failures, 1 Unrelated Failure

NicolasHug Aug 21, 2023

Choose a reason for hiding this comment

NicolasHug Aug 21, 2023 • edited Loading

Choose a reason for hiding this comment

NicolasHug Aug 21, 2023

Choose a reason for hiding this comment

vfdev-5 commented Aug 21, 2023

vfdev-5 left a comment

Choose a reason for hiding this comment

pmeier left a comment

Choose a reason for hiding this comment

pmeier Aug 21, 2023

Choose a reason for hiding this comment

NicolasHug Aug 22, 2023

Choose a reason for hiding this comment

pmeier Aug 21, 2023

Choose a reason for hiding this comment

NicolasHug Aug 22, 2023

Choose a reason for hiding this comment

NicolasHug commented Aug 21, 2023 •

edited

Loading

pytorch-bot bot commented Aug 21, 2023 •

edited

Loading

NicolasHug Aug 21, 2023 •

edited

Loading