vision orientation page

Author: 8BitJosh

programming/vision/index.md

@@ -3,8 +3,7 @@ layout: page
 title: Vision
 ---
 
-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.
@@ -17,8 +16,8 @@ Using the marker poses and their locations, we can either calculate the location
 
 For information on markers, see the [markers page](./markers).
 
-[Camera](#camera) {#camera}
-===========================
+
+## Camera
 
 The interface to the vision system is through the camera, accessible through `R.camera`.
 
@@ -69,8 +68,8 @@ frame = robot.camera.capture()
 flipped = cv2.flip(frame, 0)
 ~~~~~
 
-[Frame argument](#frame_args) {#frame_args}
--------------------------------------------
+
+### Frame argument
 
 The slowest part of vision is capturing the image.
 You can use a frame with the other vision commands to avoid recapturing.
@@ -92,8 +91,8 @@ robot.camera.save("photo.jpg", frame=frame)
 # Do some other vision algorithm with the OpenCV frame here
 ~~~~~
 
-[Field of View](#fov) {#fov}
-----------------------------
+
+### Field of View
 
 The Logitech C500 has a [field of view][fov] of 72° and the C270 has a field of view of 60°.
 
@@ -104,8 +103,8 @@ 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](#marker) {#marker}
-===========================
+
+## Marker
 
 A `Marker` object contains information about a *detected* marker.
 It has the following attributes:
@@ -117,10 +116,10 @@ size
 :   The physical size of the marker, 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`](#pixelcoordinates) 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`](#pixelcoordinates) instances, each representing the position of a corner of the marker in the image.
 
 position
 :   A `Position` instance describing the position of the marker.
@@ -161,10 +160,7 @@ orientation
         Zero values have the marker facing the camera square-on.
 
 
-<a id="Coordinate"/>
-
-[`PixelCoordinates`](#PixelCoordinates) {#PixelCoordinates}
----------
+### PixelCoordinates
 
 A named tuple of `x` and `y` coordinates for the point, in pixels relative to the top left of the image.
 

programming/vision/orientation.md

@@ -3,20 +3,48 @@ layout: page
 title: Orientation
 ---
 
-Orientation
-===========
+# Orientation
 
-TODO
+Orientation represents the rotation of a marker around its center.
+The axis and rotations follow the [aircraft principal axis](https://en.wikipedia.org/wiki/Aircraft_principal_axes) as shown in the diagram below.
 
+![Yaw Pitch Roll axis](https://upload.wikimedia.org/wikipedia/commons/c/c1/Yaw_Axis_Corrected.svg "Yaw Pitch Roll axis")
 
-# Examples
+These properties can be accessed as follows:
 
-The following table visually explains what positive and negative rotations represent.
-The red arrow is not normally present on the marker but is used in these examples to indicate which way is up.
+yaw
+:   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
+:   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
+:   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.
+
+~~~~~ python
+markers = robot.camera.see()
 
-Zero on all axis:
+for marker in markers:
+   print(marker.orientation.yaw)
+   print(marker.orientation.pitch)
+   print(marker.orientation.roll)
+~~~~~
+
+
+## Examples
+
+The following images visually explains what positive and negative rotations represent.
+The red arrow is not normally present on the marker but is used in these examples to indicate which way is up.
 
-![Orientation zero all axis]({{ site.baseurl }}/images/content/vision/orientation/all0.png "All axis zero")
+|Zero on all axis|
+|---|
+|![Orientation zero all axis]({{ site.baseurl }}/images/content/vision/orientation/all0.png "All axis zero")|
 
 |       |π/4 |-π/4|
 |-------|-------|-------|