docs: enhance wandb.Image docstrings for better normalization documentation#10380
docs: enhance wandb.Image docstrings for better normalization documentation#10380mdlinville wants to merge 19 commits intomainfrom
Conversation
- Add detailed docstring for _guess_and_rescale_to_0_255 function explaining normalization algorithm - Enhance Image.__init__ docstring with normalization behavior details - Add examples showing different normalization scenarios - Clarify when normalization is applied vs when it's not - Provide guidance on how to avoid unwanted normalization Addresses DOCS-1016
|
Update: Companion PR in |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
| @@ -59,17 +59,34 @@ def _warn_on_invalid_data_range( | |||
| def _guess_and_rescale_to_0_255(data: "np.ndarray") -> "np.ndarray": | |||
There was a problem hiding this comment.
This function is private and shouldn't appear in our documentation; why update its docstring here? I prefer the original for conciseness and developer context. The new version is too verbose and adds irrelevant context about PyTorch, PIL and the normalize parameter to the wandb.Image constructor.
There was a problem hiding this comment.
I'm a little confused about this feedback:
- I am not sure why the _guess_and_rescale_to_0_255 function is showing up. @ngrayluna can you take a look? Is there some magic that prevents things starting with an underscore from showing up? Though, I think that this function doesn't show up in the docs, so maybe this is fine. https://docs.wandb.ai/ref/python/sdk/data-types/image/ is the currently published reference, without the changes in this PR.
- Preferring more verbose: Is this about lines 66-72 vs lines 60-64 ? Would you like me to revert the change here?
| tensor_0_1 = torch.rand(3, 64, 64) # Random values between 0 and 1 | ||
| image1 = wandb.Image(tensor_0_1, caption="Normalized from [0,1] range") | ||
|
|
||
| # Example 2: [-1, 1] range tensor - values will be rescaled |
There was a problem hiding this comment.
Not necessarily. If the values all happen to be nonnegative, this will be rescaled using the [0, 1] rules.
| If the values are not in the range [0, 255] or all values are in the range [0, 1], | ||
| the image pixel values will be normalized to the range [0, 255] | ||
| unless `normalize` is set to False. |
There was a problem hiding this comment.
Should this still be here?
There was a problem hiding this comment.
I'm not sure what you are specifically referring to. It looks to me like this is missing the -1-1 range case. Do you mean that since we have lines 62-64, the detail in 161-3 should be removed?
…explanations, keep concise examples
…e PIL vs normalize=False
…sual contrast effects
|
@timoffex PTAL, I think that your feedback in this PR is addressed, but let me know if there is more to do. Note that there is a related Docs PR and a related Examples PR to add a demo notebook. |
|
@mdlinville is this still relevant or we can close? |
3 participants
Summary
This PR addresses DOCS-1016 and the related GitHub issue wandb/wandb#7377 by enhancing the docstrings in the
wandb.Imageimplementation to provide better auto-generated documentation for image normalization behavior.This is part of a three-part project. The other two PRs are:
Changes Made
Enhanced Docstrings (
wandb/sdk/data_types/image.py)_guess_and_rescale_to_0_255function:Image.__init__method:normalizeparameterProblem Solved
The original issue was that users found the existing documentation about image normalization to be "cryptic" and unclear. Users were wasting computation time due to misunderstandings about:
These enhanced docstrings will improve the auto-generated API documentation and provide clearer guidance to users.
Related PRs
wandb/docsrepository: wandb/docs#1559JIRA Reference