From 302118243242eeffbc98411cffdf1f06f6aa63c2 Mon Sep 17 00:00:00 2001
From: WillB97 <will@rudi.org.uk>
Date: Sun, 1 Sep 2024 18:26:36 +0100
Subject: [PATCH 1/2] Update camera docs for new API

---
 programming/vision/index.md | 38 +++++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/programming/vision/index.md b/programming/vision/index.md
index a3a4666b..5dcedb86 100644
--- a/programming/vision/index.md
+++ b/programming/vision/index.md
@@ -20,7 +20,7 @@ For information on markers, see the [markers page](./markers).
 
 ## Camera
 
-The interface to the vision system is through the camera, accessible through `robot.camera`, there are three functions available on the camera object:
+The interface to the vision system is through the camera, accessible through `robot.camera`, there are two functions available on the camera object:
 
 see
 :   Take a photo using the webcam, and return a list of [`Marker`](#marker) instances, each of which describes one of the markers that were found in the image.
@@ -47,17 +47,6 @@ Taking images while moving will cause them to be blurry, which will cause marker
 Try pausing movement while taking an image.
 </div>
 
-save
-:   Take a photo using the webcam, draw a box around the detected markers and save it to the provided location.
-
-~~~~~ python
-from sr.robot3 import *
-robot = Robot()
-
-# `robot.usbkey` is the path to your USB drive
-robot.camera.save(robot.usbkey / "initial-view.jpg")
-~~~~~
-
 capture
 :   Take a photo using the webcam, and return the image data as an OpenCV array.
 
@@ -95,6 +84,31 @@ robot.camera.save(robot.usbkey / "photo.jpg", frame=frame)
 ~~~~~
 
 
+### Saving camera output
+
+You can also save a snapshot of what your webcam is currently seeing. This can be useful to debug your code.
+
+This is done by adding the `save` parameter to the `see` or `capture` functions.
+The parameter should be the filename to where you want to save the image.
+
+If used with the `see` function, every marker that your robot can see will have a square annotated around it, with a red dot indicating the top left corner of the marker.
+The ID of every marker is also written next to it.
+
+Snapshots are saved to your USB drive, and can be viewed on another computer.
+
+```python
+from sr.robot3 import *
+
+robot = Robot()
+
+# Save a snapshot of what the camera is currently seeing
+frame =  robot.camera.capture(save="snapshot.jpg")
+
+# Save a snapshot of what the camera is currently seeing with markers annotated
+markers = robot.camera.see(save="annotated-snapshot.jpg")
+```
+
+
 ## Marker
 
 A `Marker` object contains information about a detected marker.

From 8cd2faf44a5bdca25df4efbbb1f3fc9d3491fb3e Mon Sep 17 00:00:00 2001
From: WillB97 <will@rudi.org.uk>
Date: Mon, 2 Sep 2024 21:02:19 +0100
Subject: [PATCH 2/2] Warn that images are overwritten

---
 programming/vision/index.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/programming/vision/index.md b/programming/vision/index.md
index 5dcedb86..ec15b5a7 100644
--- a/programming/vision/index.md
+++ b/programming/vision/index.md
@@ -96,6 +96,10 @@ The ID of every marker is also written next to it.
 
 Snapshots are saved to your USB drive, and can be viewed on another computer.
 
+<div class="warning">
+    When saving images, make sure to use a unique filename each time, otherwise the previous image will be overwritten.
+</div>
+
 ```python
 from sr.robot3 import *