Add comprehensive image normalization documentation for wandb.Image DOCS-1016

.github/workflows/calibreapp-image-actions.yml

@@ -22,6 +22,6 @@ jobs:
       - name: Compress Images
         uses: calibreapp/image-actions@main
         with:
-          # The `GITHUB_TOKEN` is automatically generated by GitHub and scoped only to the repository that is currently running the action. By default, the action can’t update Pull Requests initiated from forked repositories.
+          # The `GITHUB_TOKEN` is automatically generated by GitHub and scoped only to the repository that is currently running the action. By default, the action can't update Pull Requests initiated from forked repositories.
           # See https://docs.github.com/en/actions/reference/authentication-in-a-workflow and https://help.github.com/en/articles/virtual-environments-for-github-actions#token-permissions
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

content/en/guides/models/track/log/image-normalization.md

@@ -0,0 +1,141 @@
+---
+title: "Image Normalization Guide"
+description: "Learn how wandb.Image handles normalization for different input types and how to control this behavior"
+---
+
+
+When you pass PyTorch tensors or NumPy arrays to `wandb.Image`, the pixel values are automatically normalized to the range [0, 255] unless you set `normalize=False`. This guide explains how image normalization works and how to control it.
+
+## When normalization is applied
+
+| Input Type | Format | Normalization Applied | Notes |
+|------------|--------|----------------------|-------|
+| **PyTorch tensors** | `(channel, height, width)` | ✅ Yes | Automatically normalized to [0, 255] range |
+| **NumPy arrays** | `(height, width, channel)` | ✅ Yes | Automatically normalized to [0, 255] range |
+| **PIL Images** | PIL Image object | ❌ No | Passed as-is without modification |
+| **File paths** | String path to image file | ❌ No | Loaded as-is without modification |
+
+## Normalization algorithm
+
+The normalization algorithm automatically detects the input range and applies the appropriate transformation:
+
+- **If data is in range [0, 1]**: Values are multiplied by 255 and converted to uint8
+  ```python
+  normalized_data = (data * 255).astype(np.uint8)
+  ```
+
+- **If data is in range [-1, 1]**: Values are rescaled to [0, 255] using:
+  ```python
+  normalized_data = (255 * 0.5 * (data + 1)).astype(np.uint8)
+  ```
+
+- **For any other range**: Values are clipped to [0, 255] and converted to uint8
+  ```python
+  normalized_data = data.clip(0, 255).astype(np.uint8)
+  ```
+
+## Examples of normalization effects
+
+### Example 1: [0, 1] range data
+
+```python
+import torch
+import wandb
+
+# Create tensor with values in [0, 1] range
+tensor_0_1 = torch.rand(3, 64, 64)  # Random values between 0 and 1
+
+# This will multiply all values by 255
+image = wandb.Image(tensor_0_1, caption="Normalized from [0,1] range")
+```
+
+### Example 2: [-1, 1] range data
+
+```python
+import torch
+import wandb
+
+# Create tensor with values in [-1, 1] range
+tensor_neg1_1 = torch.rand(3, 64, 64) * 2 - 1  # Random values between -1 and 1
+
+# This will rescale: -1 → 0, 0 → 127.5, 1 → 255
+image = wandb.Image(tensor_neg1_1, caption="Normalized from [-1,1] range")
+```
+
+**Note on visual contrast**: The [-1, 1] normalization creates higher visual contrast compared to [0, 1] normalization. This is because:
+- Negative values (like -0.8) become very dark (around 25)
+- Positive values (like 0.8) become very bright (around 230)
+- Values near 0 become mid-gray (127.5)
+
+This "stretches" the visual range, making differences between pixel values more pronounced. This is particularly useful for highlighting subtle patterns in machine learning data, but if you want less contrast, consider preprocessing your data to a [0, 1] range before logging.
+
+### Example 3: Avoid normalization with PIL Images
+Normalization is not applied to PIL Images.
+
+```python
+import torch
+from PIL import Image as PILImage
+import wandb
+
+# Create tensor with values in [0, 1] range
+tensor_0_1 = torch.rand(3, 64, 64)
+
+# Convert to PIL Image to avoid normalization
+pil_image = PILImage.fromarray((tensor_0_1.permute(1, 2, 0).numpy() * 255).astype('uint8'))
+image = wandb.Image(pil_image, caption="No normalization applied")
+```
+
+### Example 4: Using normalize=False
+To explicitly turn off image normalization without converting the image, set `normalize=False`.
+
+```python
+import torch
+import wandb
+
+# Create tensor with values in [0, 1] range
+tensor_0_1 = torch.rand(3, 64, 64)
+
+# Disable normalization - values will be clipped to [0, 255]
+image = wandb.Image(tensor_0_1, normalize=False, caption="Normalization disabled")
+```
+
+## When to use different approaches
+
+### Use PIL conversion when:
+- You want complete control over pixel values
+- You need custom preprocessing (filters, brightness adjustments, etc.)
+- You want to use PIL's image processing capabilities
+- You're debugging and want to see exact values being logged
+
+### Use normalize=False when:
+- You want to see raw tensor values as they are
+- Your data is already in the correct range (like [0, 255] integers)
+- You're debugging normalization issues
+- Quick testing without additional processing steps
+
+### Use automatic normalization when:
+- You want consistent behavior across different input types
+- Your data is in standard ranges ([0, 1] or [-1, 1])
+- You want W&B to handle the conversion automatically
+
+## Troubleshooting
+
+### Best practices
+
+1. **For consistent results**: Pre-process your data to the expected [0, 255] range before logging
+2. **To avoid normalization**: Convert tensors to PIL Images using `PILImage.fromarray()`
+3. **For debugging**: Use `normalize=False` to see the raw values (they will be clipped to [0, 255])
+4. **For precise control**: Use PIL Images when you need exact pixel values
+5. **For highlighting subtle patterns**: Use [-1, 1] normalization to increase visual contrast
+6. **For natural-looking images**: Use [0, 1] normalization or preprocess to [0, 255] range
+7. **For custom processing**: Use PIL conversion when you need to apply filters or adjustments
+
+### Common issues and solutions
+
+- **Unexpected brightness**: If your tensor values are in [0, 1] range, they will be multiplied by 255, making the image much brighter. **Solution**: Preprocess to [0, 255] range or use PIL conversion.
+- **Data loss**: Values outside the [0, 255] range will be clipped, potentially losing information. **Solution**: Check your data range and preprocess appropriately.
+- **Inconsistent behavior**: Different input types (tensor vs PIL vs file path) may produce different results. **Solution**: Use consistent input types or understand the normalization behavior for each type.
+
+## Testing your code
+
+You can test the normalization behavior using our [Image Normalization Demo Notebook](https://github.com/wandb/wandb/blob/main/wandb_image_normalization_demo.ipynb) which demonstrates all the examples above with visual output. 

content/en/guides/models/track/log/media.md

@@ -58,7 +58,7 @@ with wandb.init(project="image-log-example") as run:
     run.log({"examples": images})
 ```
 
-We assume the image is gray scale if the last dimension is 1, RGB if it's 3, and RGBA if it's 4. If the array contains floats, we convert them to integers between `0` and `255`. If you want to normalize your images differently, you can specify the [`mode`](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#modes) manually or just supply a [`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html), as described in the "Logging PIL Images" tab of this panel.   
+W&B assumes the image is gray scale if the last dimension is 1, RGB if it's 3, and RGBA if it's 4. If the array contains floats, W&B automatically normalizes them to integers between `0` and `255`. For detailed information about normalization with PyTorch tensors and NumPy arrays, see the [Image normalization guide]({{< relref "/guides/models/track/log/image-normalization.md" >}}). To normalize your images differently, you can specify the [`mode`](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#modes) manually or supply a [`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html), as described in the "Logging PIL Images" tab.   
    {{% /tab %}}
    {{% tab header="Logging PIL Images" %}}
 For full control over the conversion of arrays to images, construct the [`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html) yourself and provide it directly.
@@ -97,7 +97,6 @@ with wandb.init(project="") as run:
    {{% /tab %}}
 {{< /tabpane >}}
 
-
 ## Image overlays
 
 

content/en/ref/python/sdk/data-types/Image.md

@@ -9,10 +9,10 @@ data_type_classification: class
 
 
 
-## <kbd>class</kbd> `Image`
+<kbd>class</kbd> `Image`
 A class for logging images to W&B. 
 
-### <kbd>method</kbd> `Image.__init__`
+<kbd>method</kbd> `Image.__init__`
 
 ```python
 __init__(
@@ -103,10 +103,13 @@ with wandb.init() as run:
     run.log({"examples": examples})
 ``` 
 
+Image normalization
+
+When you pass PyTorch tensors or NumPy arrays to `wandb.Image`, the pixel values are automatically normalized to the range [0, 255] unless you set `normalize=False`. For detailed information about normalization behavior, examples, and best practices, see the [Image Normalization Guide]({{< relref "/guides/models/track/log/image-normalization.md" >}}).
 
 ---
 
-### <kbd>property</kbd> Image.image
+<kbd>property</kbd> Image.image
 
 
 

content/ja/guides/integrations/pytorch.md

@@ -49,7 +49,7 @@ for batch_idx, (data, target) in enumerate(train_loader):
 
 ## 画像とメディアのログ
 
-画像データを持つ PyTorch `Tensors` を [`wandb.Image`]({{< relref path="/ref/python/data-types/image.md" lang="ja" >}}) に渡すことができ、[`torchvision`](https://pytorch.org/vision/stable/index.html) のユーティリティが自動的に画像に変換します。
+画像データを持つ PyTorch `Tensors` を [`wandb.Image`]({{< relref "/ref/python/data-types/image.md" >}}) に渡すことができ、[`torchvision`](https://pytorch.org/vision/stable/index.html) のユーティリティが自動的に画像に変換します。
 
 ```python
 images_t = ...  # PyTorch Tensors として画像を生成またはロードする

content/ja/guides/models/track/log/media.md

@@ -52,7 +52,7 @@ images = wandb.Image(image_array, caption="Top: Output, Bottom: Input")
 wandb.log({"examples": images})
 ```
 
-最後の次元が1の場合はグレースケール、3の場合はRGB、4の場合はRGBAと仮定します。配列が浮動小数点数を含む場合、それらを`0`から`255`の整数に変換します。異なる方法で画像を正規化したい場合は、[`mode`](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#modes)を手動で指定するか、`"Logging PIL Images"`タブで説明されているように、単に[`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html)を提供することができます。
+最後の次元が1の場合はグレースケール、3の場合はRGB、4の場合はRGBAと仮定します。配列が浮動小数点数を含む場合、正規化アルゴリズムを使用して自動的に`0`から`255`の整数に変換します。PyTorchテンソルとNumPy配列での正規化の動作についての詳細は、[Imageリファレンスの画像正規化セクション]({{< relref "/ref/python/data-types/image.md#image-normalization" >}})を参照してください。異なる方法で画像を正規화したい場合は、[`mode`](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#modes)を手動で指定するか、`"Logging PIL Images"`タブで説明されているように、単に[`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html)を提供することができます。
    {{% /tab %}}
    {{% tab header="PIL Imagesをログする" %}}
 配列から画像への変換を完全に制御するために、[`PIL.Image`](https://pillow.readthedocs.io/en/stable/reference/Image.html)を自分で構築し、直接提供してください。
@@ -564,7 +564,7 @@ runが終了すると、UIで分子の3D可視化と対話できるようにな
 
 ### PNG 画像
 
-[`wandb.Image`]({{< relref path="/ref/python/data-types/image.md" lang="ja" >}})は`numpy`配列や`PILImage`のインスタンスをデフォルトでPNGに変換します。
+`wandb.Image`は`numpy`配列や`PILImage`のインスタンスをデフォルトでPNGに変換します。
 
 ```python
 wandb.log({"example": wandb.Image(...)})
@@ -584,7 +584,7 @@ wandb.log({"example": wandb.Video("myvideo.mp4")})
 
 ## 分子の2Dビュー
 
-[`wandb.Image`]({{< relref path="/ref/python/data-types/image.md" lang="ja" >}})データ型と[`rdkit`](https://www.rdkit.org/docs/index.html)を使用して分子の2Dビューをログできます:
+[`wandb.Image`]({{< relref "/ref/python/data-types/image.md" >}})データ型と[`rdkit`](https://www.rdkit.org/docs/index.html)を使用して分子の2Dビューをログできます:
 
 ```python
 molecule = rdkit.Chem.MolFromSmiles("CC(=O)O")

content/ja/launch/integration-guides/dagster.md

@@ -181,7 +181,7 @@ def create_dataset():
 W&B は複数のピクルスベースのシリアライズモジュール([pickle](https://docs.python.org/3/library/pickle.html), [dill](https://github.com/uqfoundation/dill), [cloudpickle](https://github.com/cloudpipe/cloudpickle), [joblib](https://github.com/joblib/joblib)) をサポートしています。また、[ONNX](https://onnx.ai/) や [PMML](https://en.wikipedia.org/wiki/Predictive_Model_Markup_Language) といったより高度なシリアライズも利用できます。[Serialization]({{< relref path="#serialization-configuration" lang="ja" >}}) セクションを参照してください。
 {{% /tab %}}
 {{% tab "W&B Object" %}}
-ネイティブ W&B オブジェクト (例: [Table]({{< relref path="/ref/python/data-types/table.md" lang="ja" >}}), [Image]({{< relref path="/ref/python/data-types/image.md" lang="ja" >}}), or [Graph]({{< relref path="/ref/python/data-types/graph.md" lang="ja" >}})) のいずれかが作成された Artifact にインテグレーションによって追加されます。以下は Table を使った例です。
+ネイティブ W&B オブジェクト (例: [Table]({{< relref path="/ref/python/data-types/table.md" lang="ja" >}}), [Image]({{< relref "/ref/python/data-types/image.md" >}}), or [Graph]({{< relref path="/ref/python/data-types/graph.md" lang="ja" >}})) のいずれかが作成された Artifact にインテグレーションによって追加されます。以下は Table を使った例です。
 
 ```python
 import wandb