From 9916b6121c3c5f7a864893b88dd1a12734331001 Mon Sep 17 00:00:00 2001
From: Dave Berenbaum <dave@iterative.ai>
Date: Wed, 5 Jul 2023 16:24:53 -0400
Subject: [PATCH] dvclive: cache_images (#4675)

* dvclive: cache_images

* dvclive: mention gitignore in cache_images
---
 content/docs/dvclive/how-it-works.md   |  4 ++++
 content/docs/dvclive/live/index.md     |  3 +++
 content/docs/dvclive/live/log_image.md | 17 ++++++++++++-----
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/content/docs/dvclive/how-it-works.md b/content/docs/dvclive/how-it-works.md
index 17bf0eaf2a..5a2bf339fd 100644
--- a/content/docs/dvclive/how-it-works.md
+++ b/content/docs/dvclive/how-it-works.md
@@ -95,6 +95,10 @@ the corresponding `dvc.yaml`. Passing `type="model"` will mark it as a `model`
 for DVC and will also show it in
 [Studio Model Registry](/doc/studio/user-guide/model-registry/what-is-a-model-registry).
 
+Using `Live.log_image()` to log multiple images may also grow too large to track
+with Git, in which case you can use
+[`Live(cache_images=True)`](/doc/dvclive/live#parameters) to cache them.
+
 ### Run with DVC
 
 Experimenting in Python interactively (like in notebooks) is great for
diff --git a/content/docs/dvclive/live/index.md b/content/docs/dvclive/live/index.md
index 675067bf93..8deac73673 100644
--- a/content/docs/dvclive/live/index.md
+++ b/content/docs/dvclive/live/index.md
@@ -93,6 +93,9 @@ You can use `Live()` as a context manager. When exiting the context manager,
 
   </admon>
 
+- `cache_images` - If `True`, DVCLive will <abbr>cache</abbr> any images logged
+  with `Live.log_image()` as part of `Live.end()`. Defaults to `False`.
+
 - `exp_message` - If not `None`, and `save_dvc_exp` is `True`, the provided
   string will be passed to
   [`dvc exp save --message`](/doc/command-reference/exp/save#--message).
diff --git a/content/docs/dvclive/live/log_image.md b/content/docs/dvclive/live/log_image.md
index b0b6a7a12f..789cf437c6 100644
--- a/content/docs/dvclive/live/log_image.md
+++ b/content/docs/dvclive/live/log_image.md
@@ -11,7 +11,7 @@ def log_image(name: str, val):
 ```py
 from dvclive import Live
 
-with Live() as live:
+with Live(cache_images=True) as live:
     # 1. Log an image from a numpy array:
     import numpy as np
     img_numpy = np.ones((500, 500), np.uint8) * 255
@@ -39,14 +39,21 @@ Supported values for `val` are:
   should be in a format that is readable by
   [`PIL.Image.open()`](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.open)
 
-The images will be saved in `{Live.plots_dir}/images/{name}`:
+The images will be saved in `{Live.plots_dir}/images/{name}`. When using
+[`Live(cache_images=True)`](/doc/dvclive/live#parameters), the images directory
+will also be <abbr>cached</abbr> as part of `Live.end()`. In that case, a `.dvc`
+file will be saved to [track](/doc/dvclive/how-it-works#track-the-results) it,
+and the directory will be added to a `.gitignore` file to prevent Git tracking:
 
 ```
 dvclive
 └── plots
-    └── images
-        ├── numpy.png
-        └── pil.png
+    ├── .gitignore
+    ├── images
+    │   ├── numpy.png
+    │   ├── pil.png
+    │   └── sample.png
+    └── images.dvc
 ```
 
 <admon type="tip">