Update vision pages

Author: 8BitJosh

_data/sidebar_tree.yaml

@@ -109,6 +109,8 @@ tree:
     tree:
     - url: /competitor_resources/microgames
       title: Microgames
+    - url: /competitor_resources/markers
+      title: Game markers
   - url: /team_admin/
     title: Team Admin
     tree:

competitor_resources/markers.md

@@ -0,0 +1,7 @@
+---
+layout: page
+title: Game markers
+---
+
+# Game markers
+

images/content/vision/marker-0.png

@@ -5,24 +5,23 @@ title: Vision
 
 # Vision
 
-Your robot is able to use a webcam to detect [fiducial markers](https://en.wikipedia.org/wiki/Fiducial_marker).
-Specifically it can detect [AprilTags](https://april.eecs.umich.edu/software/apriltag), using the `36H11` marker set.
+Your robot is able to use a webcam to detect [fiducial markers](https://en.wikipedia.org/wiki/Fiducial_marker) and return their locations relative to the robot.
 
-Each marker is unique and encodes a number in a machine-readable way, which means that robots can identify these objects.
+Specifically it can detect [AprilTags](https://april.eecs.umich.edu/software/apriltag), using the `36H11` marker set.
+Each of these markers acts like a QR-code, encoding a number in a machine-readable way so the robot can identify them.
 
 Using [Pose Estimation](https://en.wikipedia.org/wiki/3D_pose_estimation), it can calculate the orientation and position of the marker relative to the webcam.
 Markers are attached to various items in the Student Robotics arena, in known locations.
-Using the marker poses and their locations, we can either calculate the location of object relative to the robot or the position of the robot relative to the arena.
+Using the marker's poses and their locations, we can either calculate the location of object relative to the robot or the position of the robot relative to the arena.
 
 For information on markers, see the [markers page](./markers).
 
-
 ## Camera
 
-The interface to the vision system is through the camera, accessible through `R.camera`.
+The interface to the vision system is through the camera, accessible through `robot.camera`, there are three functions available on the camera object:
 
 see
-:   Take a photo through the webcam, and return a list of [`Marker`](#marker) instances, each of which describes one of the markers that were found in the image.
+:   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.
 
 Here's an example that will repeatedly print out the distance, in meters, to each marker that the robot can see:
 
@@ -44,7 +43,7 @@ Try pausing movement while taking an image.
 </div>
 
 save
-:   Take a photo through the webcam, and save it to the provided location.
+:   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 *
@@ -55,7 +54,7 @@ robot.camera.save(robot.usbkey / "initial-view.png")
 ~~~~~
 
 capture
-:   Take a photo through the webcam, and return the image data as an OpenCV array.
+:   Take a photo using the webcam, and return the image data as an OpenCV array.
 
 ~~~~~ python
 import cv2
@@ -64,15 +63,14 @@ robot = Robot()
 
 frame = robot.camera.capture()
 
-# Flip the image with OpenCV
-flipped = cv2.flip(frame, 0)
+# Do some other vision algorithm with the OpenCV frame here
 ~~~~~
 
 
 ### Frame argument
 
 The slowest part of vision is capturing the image.
-You can use a frame with the other vision commands to avoid recapturing.
+You can use the output of the `capture` method with the other vision commands to avoid recapturing.
 This may be useful if you wish to use both your own vision algorithms and our marker detection on the same frames.
 
 ~~~~~ python
@@ -86,81 +84,67 @@ frame = robot.camera.capture()
 markers = robot.camera.see(frame=frame)
 
 # Save the frame with marker annotation
-robot.camera.save("photo.jpg", frame=frame)
+robot.camera.save(robot.usbkey / "photo.jpg", frame=frame)
 
 # Do some other vision algorithm with the OpenCV frame here
 ~~~~~
 
 
-### Field of View
-
-The Logitech C500 has a [field of view][fov] of 72&deg; and the C270 has a field of view of 60&deg;.
-
-[fov]: https://en.wikipedia.org/wiki/Field_of_view
-
-<div class="info">
-Note that the axes are all defined relative to the camera.
-Since we have no way to know how you've mounted your camera, you may need to account for that in your usage of the vision system's data.
-</div>
-
-
 ## Marker
 
-A `Marker` object contains information about a *detected* marker.
+A `Marker` object contains information about a detected marker.
 It has the following attributes:
 
 id
 :   The id of the marker.
 
 size
-:   The physical size of the marker, as the vision system expects it.
+:   The physical size of the marker in millimetres, as the vision system expects it.
 
 pixel_centre
-:   A [`PixelCoordinates`](#pixelcoordinates) describing the position of the centre of the marker in the image.
+:   A [`PixelCoordinates`](#pixel-coordinates) object describing the position of the centre of the marker in the image.
 
 pixel_corners
-:   A list of 4 [`PixelCoordinates`](#pixelcoordinates) instances, each representing the position of a corner of the marker in the image.
+:   A list of 4 [`PixelCoordinates`](#pixel-coordinates) objects, each representing the position of a corner of the marker in the image.
 
 position
-:   A `Position` instance describing the position of the marker.
+:   A `Position` object describing the position of the marker.
     See the [Position page](./position) for detailed definitions and diagrams.
 
     distance
     :   The distance between the camera and the centre of the marker, in millimetres.
 
     horizontal_angle
-    :   Horizontal angle from the camera to the marker, in radians.
+    :   Horizontal angle from the centre of the camera's view to the marker, in radians.
         Ranges -&pi; to &pi;.
-        Positive to the right.
-        Directly in front is 0.
+        Directly in front is zero, positive to the right.
 
     vertical_angle
-    :   Vertical angle from the camera to the marker, in radians.
+    :   Vertical angle from the centre of the camera's view to the marker, in radians.
         Ranges -&pi; to &pi;.
-        Positive values upwards.
-        Directly in front is 0.
+        Directly in front is zero, positive values upwards.
 
 orientation
 :   An `Orientation` instance describing the orientation of the marker.
     See the [Orientation page](./orientation) for detailed definitions and diagrams.
 
     yaw
-    :   The Yaw of the marker, a rotation about the vertical axis, in radians.
+    :   The yaw of the marker, a rotation about the vertical axis, in radians.
         Positive values indicate a rotation clockwise from the perspective of the marker.
         Zero values have the marker facing the camera square-on.
 
     pitch
-    :   The Pitch of the marker, a rotation about the transverse axis, in radians.
+    :   The pitch of the marker, a rotation about the transverse axis, in radians.
         Positive values indicate a rotation upwards from the perspective of the marker.
         Zero values have the marker facing the camera square-on.
 
     roll
-    :   The Roll of the marker, a rotation about the longitudinal axis, in radians.
+    :   The roll of the marker, a rotation about the longitudinal axis, in radians.
         Positive values indicate a rotation clockwise from the perspective of the marker.
         Zero values have the marker facing the camera square-on.
 
 
-### PixelCoordinates
+### Pixel Coordinates
 
 A named tuple of `x` and `y` coordinates for the point, in pixels relative to the top left of the image.