Update the vision docs to match reality

Even before the changes in the Dec 1st kit update these docs were
wildly different to how the vision system actually behaved.
This update brings these to parity with the default behaviour of
the kit (and soon the simulator).

Ideally we would have some diagrams to show how the axes work,
however the diagrams we have are substantially incorrect and will
need replacing. Dropping them clarifies that work is needed before
they can be brought back (though recreating them from scratch
might be easier as we don't seem to have the source files).

Author: PeterJCLaw

images/content/vision/spherical.png

@@ -134,10 +134,10 @@ size
 :   The physical size of the marker, as the vision system expects it.
 
 pixel_centre
-:   A [`Coordinate`](#Coordinate) describing the position of the centre of the marker.
+:   A [`PixelCoordinates`](#PixelCoordinates) describing the position of the centre of the marker.
 
 pixel_corners
-:   A list of 4 [`Coordinate`](#Coordinate) instances, each representing the position of the corners of the marker.
+:   A list of 4 [`PixelCoordinates`](#PixelCoordinates) instances, each representing the position of the corners of the marker.
 
 distance
 :   The distance between the camera and the centre of the marker, in millimetres.
@@ -146,20 +146,33 @@ orientation
 :   An [`Orientation`](#Orientation) instance describing the orientation of the marker.
 
 spherical
-:   A [`Spherical`](#Spherical) instance describing the position relative to the camera.
+:   A [`SphericalCoordinate`](#SphericalCoordinate) instance describing the position relative to the camera.
 
 cartesian
-:   A [`ThreeDCoordinate`](#ThreeDCoordinate) instance describing the absolute position of the marker relative to the camera.
+:   A [`CartesianCoordinates`](#CartesianCoordinates) instance describing the absolute position of the marker relative to the camera.
 
-[`Coordinate`](#Coordinate) {#Coordinate}
+<a id="Coordinate"/>
+
+[`PixelCoordinates`](#PixelCoordinates) {#PixelCoordinates}
 ---------
 
-A `Coordinate` object contains an `x` and `y` attribute. The exact meaning and unit of these attributes depends on its source.
+A named tuple of `x` and `y` coordinates for the point, in pixels relative to the top left of the image.
+
+~~~~~ python
+print(marker.pixel_centre.x, marker.pixel_centre.y)
+~~~~~
 
-[`ThreeDCoordinate`](#ThreeDCoordinate) {#ThreeDCoordinate}
+<a id="ThreeDCoordinate"/>
+
+[`CartesianCoordinates`](#CartesianCoordinates) {#CartesianCoordinates}
 ---------
 
-A `ThreeDCoordinate` object contains an `x`, `y` and `z` attribute. The exact meaning and unit of these attributes depends on its source.
+A named tuple of `x`, `y` and `z` coordinates for the point, in millimeters relative to the camera.
+Increasing values are to the right, below and away from the camera respectively.
+
+~~~~~ python
+print(marker.cartesian.x, marker.cartesian.y, marker.cartesian.z)
+~~~~~
 
 [`Orientation`](#Orientation) {#Orientation}
 ---------------
@@ -171,62 +184,71 @@ One (possibly both) of them may change to resolve this.
 
 An `Orientation` object describes the orientation of a marker.
 
-![A visual representation of how the orientation axes work. Source: SourceBots]({{ site.baseurl }}/images/content/vision/yaw-pitch-roll.png)
-
-pitch
+rot_x
 :   Rotation of the marker about the cartesian x-axis, in radians.
 
-    Leaning a marker away from the camera increases the value of `rot_x`, while
-    leaning it towards the camera decreases it. A value of 0 indicates that the
-    marker is upright.
+    Leaning a marker towards the camera increases the value of `rot_x`, while
+    leaning it away from the camera decreases it. A value of π or -π indicates
+    that the marker is upright.
 
-yaw
+rot_y
 :   Rotation of the marker about the cartesian y-axis, in radians.
 
-    Turning a marker clockwise (as viewed from above) increases the value of
-    `rot_y`, while turning it anticlockwise decreases it. A value of 0 means
+    Turning a marker clockwise (as viewed from above) decreases the value of
+    `rot_y`, while turning it anticlockwise increases it. A value of 0 means
     that the marker is perpendicular to the line of sight of the camera.
 
-roll
+rot_z
 :   Rotation of the marker about the cartesian z-axis, in radians.
 
     Turning a marker anticlockwise (as viewed from the camera) increases the
-    value of `rot_z`, while turning it clockwise decreases it. A value of 0
-    indicates that the marker is upright.
+    value of `rot_z`, while turning it clockwise decreases it. A value of π
+    or -π indicates that the marker is upright.
 
-rot_x
-:   An alias for `pitch`.
+roll
+:   An alias for `rot_x`.
 
-rot_y
-:   An alias for `yaw`.
+pitch
+:   An alias for `rot_y`.
 
-rot_z
-:   An alias for `roll`.
+yaw
+:   An alias for `rot_z`.
 
 rotation_matrix
 :   The rotation matrix represented by this orientation. A list of 3 lists, each with 3 items.
 
 quaternion
 :   The [Quarternion](https://kieranwynn.github.io/pyquaternion/#quaternion-features) instance represented by this orientation.
 
-[`Spherical`](#Spherical) {#Spherical}
+<a id="Spherical"/>
+
+[`SphericalCoordinate`](#SphericalCoordinate) {#SphericalCoordinate}
 ---------------
 
 The spherical coordinates system has three values to specify a specific point in space.
 
-![A visual representation of Spherical coordinates. Source: SourceBots]({{ site.baseurl }}/images/content/vision/spherical.png)
+distance
+:   The radial distance, the distance from the origin to the point, in millimetres.
+
+theta
+:   This is the angle from directly in front of the camera to the vector which
+    points to the location in the horizontal plane. A positive value indicates a
+    counter-clockwise rotation. Zero is at the centre of the image.
+
+phi
+:   The polar angle from the y-axis of the camera "down" to the vector which
+    points to the location, in radians. Zero is directly upward.
 
-- r - The radial distance, the distance from the origin to the point, in millimetres.
-- θ (theta) - The angle from the azimuth to the point, in radians.
-- φ (phi) - The polar angle from the plane of the camera to the point, in radians.
+Also available are two computed angles which express the same location slightly differently:
 
 rot_x
-:   Rotation around the X-axis, in radians, corresponding to `theta` on the diagram.
+:   Approximate rotation around the X-axis, in radians.
+    This is the angle from the camera's horizontal plane to the vector which
+    points to the location. Zero is at the centre of the image. Values increase
+    towards the bottom of the image.
 
 rot_y
-:   Rotation around the Y-axis, in radians, corresponding to `phi` on the diagram.
-
-dist
-:   Distance, in millimetres, corresponding to `r` on the diagram.
+:   Rotation around the Y-axis, in radians. This is similar to `theta`, however
+    values increase towards the right of the image. Zero is at the centre of the image.
 
 The camera is located at the origin, where the coordinates are (0, 0, 0).