Import sbot's vision docs

Author: RealOrangeOne

docs/api/vision/index.md

@@ -0,0 +1,106 @@
+# Vision
+
+
+![An arena with Fiducial Markers](../../assets/img/api/vision/arena_marker.jpg)
+
+Your robot is able to use a webcam to detect [Fiducial Markers](https://en.wikipedia.org/wiki/Fiducial_marker).
+Specifically it will detect [AprilTags](https://april.eecs.umich.edu/software/apriltag), using the `36H11` marker set.
+
+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. Using this data, it is possible to determine the location of your robot and other objects around it.
+
+## Searching for markers
+
+Assuming you have a webcam connected, you can use `r.camera.see()` to take a picture. The software will process the picture
+and returns a list of the markers it sees.
+
+```python
+markers = r.camera.see()
+```
+
+!!! tip
+    Your camera will be able to process images better if they are not blurred.
+
+## Saving camera output
+
+You can also save a snapshot of what your webcam is currently seeing. This can be useful to debug your code.
+Every marker that your robot can see will have a square annotated around it, with a red dot indicating the bottom right
+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
+r.camera.save("snapshot.jpg")
+```
+
+![An annotated arena with Fiducial Markers.](../../assets/img/api/vision/arena_marker_annotated.jpg){ width="50%" }
+
+## Markers
+
+The marker objects in the list expose data that may be useful to your robot.
+
+### Marker ID
+
+Every marker has a numeric identifier that can be used to determine what object it represents.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+    print(m.id)
+```
+
+### Position
+
+Each marker has a position in 3D space, relative to your webcam.
+
+You can access the position using `m.distance`, `m.cartesian` and `m.spherical`.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+    print(m.distance)  # Distance to the marker from the webcam, in metres
+    print(m.spherical.rot_y)  # Bearing to the marker from the webcam, in radians
+```
+
+!!! note
+    `m.distance` is equivalent to `m.cartesian.z` or `m.spherical.dist`.
+
+For more information on position, including how to use `m.cartesian`, `m.spherical`, and the coordinate systems,
+see [Position](./position.md).
+
+It is also possible to look at the [Orientation](./orientation.md) of the marker.
+
+!!! tip
+    You can use the [`math.degrees`](https://docs.python.org/3/library/math.html#math.degrees) function to convert from radians to degrees.
+
+### Size
+
+Markers can come in different sizes.
+You can access the size of a marker using `m.size`.
+Check the rules to find out how big the different marker types are.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+    print(m.size)
+```
+
+### Pixel Positions
+
+The positions of various points on the marker within the image are exposed over the API. This is useful
+if you would like to perform your own Computer Vision calculations.
+
+The corners are specified in clockwise order, starting from the top left corner of the
+marker. Pixels are counted from the origin of the image, which
+conventionally is in the top left corner of the image.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+    print(m.pixel_corners)  # Pixel positions of the marker corners within the image.
+    print(m.pixel_centre)  # Pixel positions of the centre of the marker within the image.
+```

docs/api/vision/orientation.md

@@ -0,0 +1,47 @@
+# Orientation
+
+![Yaw Pitch and Roll (Image source: Peking University)](../../assets/img/api/vision/yawpitchroll.png)
+
+Orientation represents the rotation of a marker around the x, y, and z axes. These can be accessed as follows:
+
+* `rot_x` / `pitch` - the angle of rotation in radians counter-clockwise about the Cartesian x axis.
+* `rot_y` / `yaw` - the angle of rotation in radians counter-clockwise about the Cartesian y axis.
+* `rot_z` / `roll` - the angle of rotation in radians counter-clockwise about the Cartesian z axis.
+
+Rotations are applied in order of z, y, x.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+   print(m.orientation.rot_x)  # Angle of rotation about x axis.
+   print(m.orientation.rot_y)  # Angle of rotation about y axis.
+   print(m.orientation.rot_z)  # Angle of rotation about z axis.
+```
+
+!!! note
+    In our use case the z axis always faces the camera, and thus will appear as a clockwise rotation
+
+## Examples
+
+The following table visually explains what positive and negative rotations represent.
+
+!!! example
+    0 in all axes:
+
+    ![m0x0y0z]{ width="35%" }
+
+|  | π/4 | -π/4 |
+|---:|:---:|:---:|
+| **`rot_x`** | ![m45x0y0z] | ![m-45x0y0z] |
+| **`rot_y`** | ![m0x45y0z] | ![m0x-45y0z] |
+| **`rot_z`** | ![m0x0y45z] | ![m0x0y-45z] |
+
+[m0x0y0z]: ../../assets/img/api/vision/m0x0y0z.png
+[m-45x0y0z]: ../../assets/img/api/vision/m-45x0y0z.png
+[m0x-45y0z]: ../../assets/img/api/vision/m0x-45y0z.png
+[m0x0y-45z]: ../../assets/img/api/vision/m0x0y-45z.png
+[m0x0y0z]: ../../assets/img/api/vision/m0x0y0z.png
+[m0x0y45z]: ../../assets/img/api/vision/m0x0y45z.png
+[m0x45y0z]: ../../assets/img/api/vision/m0x45y0z.png
+[m45x0y0z]: ../../assets/img/api/vision/m45x0y0z.png

docs/api/vision/position.md

@@ -0,0 +1,56 @@
+# Position
+
+Your robot supports two different coordinates systems for position:
+
+* Cartesian
+* Spherical
+
+The latter is a [Polar Coordinates system](https://en.wikipedia.org/wiki/Polar_coordinate_system).
+
+## Cartesian
+
+![The cartesian coordinates system](../../assets/img/api/vision/cartesian.svg){ width="40%" }
+
+The [cartesian coordinates system](https://en.wikipedia.org/wiki/Cartesian_coordinate_system) has three
+_principal axes_ that are perpendicular to each other.
+
+The value of each coordinate indicates the distance travelled along the axis to the point.
+
+The camera is located at the origin, where the coordinates are ``(0, 0, 0)``.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+    print(m.cartesian.x)  # Displacement from the origin in millimetres, along x axis.
+    print(m.cartesian.y)  # Displacement from the origin in millimetres, along y axis.
+    print(m.cartesian.z)  # Displacement from the origin in millimetres, along z axis.
+```
+
+!!! tip
+    The `y` axis decreases as you go up. This matches convention for computer vision systems.
+
+## Spherical
+
+![The spherical coordinates system](../../assets/img/api/vision/spherical.svg){ width="40%" }
+
+The [spherical coordinates system](https://en.wikipedia.org/wiki/Spherical_coordinate_system) has
+three values to specify a specific point in space.
+
+* `distance` - The _radial distance_, the distance from the origin to the point, in millimetres.
+* `rot_x` -  Rotation around the X-axis, in radians, corresponding to "theta" on the diagram.
+* `rot_y` -  Rotation around the Y-axis, in radians, corresponding to "phi" on the diagram.
+
+The camera is located at the origin, where the coordinates are `(0, 0, 0)`.
+
+```python
+markers = r.camera.see()
+
+for m in markers:
+  print(m.spherical.distance)  # Distance from the origin in millimetres
+  print(m.spherical.rot_x)  # The angle from the azimuth to the point, in radians.
+  print(m.spherical.rot_y)  # The polar angle from the plane of the camera to the point, in radians.
+```
+
+!!! tip
+    You can use the [`math.degrees`](https://docs.python.org/3/library/math.html#math.degrees) function to convert from radians to degrees.