add orientations

content/api/vision/_index.md

@@ -20,6 +20,7 @@ The markers in the list have some useful attributes:
 - `pixel_centre` - returns the location in pixels of the centre of the marker in the captured image.
 - `cartesian` - returns details of the position of the marker in the [Cartesian](coordinates/#cartesian-coordinates) coordinate system.
 - `spherical` - returns details of the position of the marker in a [spherical](coordinates/#spherical-coordinates) coordinate system.
+- `orientation` - returns the [Orientation](orientation) of the marker around its centre.
 - `polar` - *Deprecated*. Use the `spherical` attribute instead.
 
 {{% notice tip %}}

content/api/vision/orientation.md

@@ -0,0 +1,31 @@
+---
+title: Orientation
+---
+
+{{% notice tip %}}
+Orientation was added in version `1.2` of the robot software, see
+[updates](/updates) how to update your robot.
+{{% /notice %}}
+
+Orientation represents the rotation of a marker around the x, y, and z axes.
+These can be accessed as follows:
+
+- `rot_x_radians` / `rot_x_degrees` - the angle of rotation in radians/degrees
+   counter-clockwise about the Cartesian x axis.
+- `rot_y_radians` / `rot_y_degrees` - the angle of rotation in radians/degrees
+   counter-clockwise about the Cartesian y axis.
+- `rot_z_radians` / `rot_z_degrees` - the angle of rotation in radians/degrees
+   counter-clockwise about the Cartesian z axis. (tip: in our use case the z
+   axis always faces the camera, and thus will appear as a clockwise rotation)
+
+Rotations are applied in order of z, y, x.
+
+The following table visually explains what positive and negative
+rotations represent.
+
+|  |  |
+|:-:|:-:|
+| <img src="/img/api/coordinate-orientations/m45x0y0z.png?width=200px" style="margin:0"/> `rot_x_degrees = 45` | <img src="/img/api/coordinate-orientations/m-45x0y0z.png?width=200px" style="margin:0"/>  `rot_x_degrees = -45` |
+| <img src="/img/api/coordinate-orientations/m0x45y0z.png?width=200px" style="margin:0"/> `rot_y_degrees = 45` |  <img src="/img/api/coordinate-orientations/m0x-45y0z.png?width=200px" style="margin:0"/> `rot_y_degrees = -45` |
+| <img src="/img/api/coordinate-orientations/m0x0y45z.png?width=200px" style="margin:0"/> `rot_z_degrees = 45` |  <img src="/img/api/coordinate-orientations/m0x0y-45z.png?width=200px" style="margin:0"/>  `rot_z_degrees= -45` |
+|  <img src="/img/api/coordinate-orientations/m0x0y0z.png?width=200px" style="margin:0"/> `0` in all axes  |