Merge branch 'main' into patch-1

docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst

@@ -1,28 +1,45 @@
 .. _first field coordinate system:
 
-*FIRST* Tech Challenge Field “Coordinate System" Definition
-===========================================================
+*FIRST* Tech Challenge Field Coordinate System Definition
+=========================================================
+
+.. meta::
+   :description: This document defines the FIRST Tech Challenge Field Coordinate System which can be used to specify position on the playing field.
+
+Summary: The *FIRST* Tech Challenge Field Coordinate System is a Cartesian Coordinate System of three dimensions.
+The X and Y axes will refer to a position on the field and the Z axis a height above the field.
 
 Scope
 -----
-
-This document defines the “standard” Coordinate System (orthogonal axes)
-definition for a *FIRST* Tech Challenge playing field. This definition can be
+  
+This document defines the Field Coordinate System 
+for a *FIRST* Tech Challenge playing field. This definition can be
 used for consistent field-centric navigation, target localization and path
 planning.
 
-Reference frame
+Reference Frame
 ---------------
 
 The reference frame for this definition is the field perimeter wall, adjacent
-to the RED Alliance Station (known here as the: RED WALL).  The definition is
+to the red Alliance Area, known here after as the Red Wall.  The definition is
 from the perspective of a person, standing outside the field, in the center of
-RED WALL, looking towards the center of the field.
-
-Caveat: If the Red Alliance Station is ever adjacent to two perimeter walls,
-the RED WALL will be the one with *most* contact with the Alliance Station. If
-the red Alliance Station is ever adjacent to two perimeter walls EQUALLY, then
-the most clockwise of the two walls will be considered to be the RED WALL.
+Red Wall, looking towards the center of the field.
+
+.. note:: 
+   If the red Alliance Area is ever adjacent to two perimeter walls,
+   the Red Wall will be the one with *most* contact with the Alliance Area. If
+   the red Alliance Area is ever adjacent to two perimeter walls *equally*, then
+   the most clockwise of the two walls will be considered to be the Red Wall.
+
+Coordinate System
+-----------------
+
+The Field Coordinate System is a Cartesian Coordinate System of three dimensions.
+X and Y will refer to a position on the field.
+Z will refer to a height above the field.
+You may use any length measure as long as the same measure is used for all three axes.
+The coordinates are ordered (X, Y, Z).
+Example: coordinate position (10, -10, 0) has X = 10, Y = -10 and Z = 0.
 
 Origin
 ^^^^^^
@@ -35,85 +52,131 @@ mat.
 X Axis
 ^^^^^^
 
-Looking at the origin from the RED WALL, the X axis extends through the origin
-point and runs to the right and left, parallel with the RED WALL. The X axis
+Looking at the origin from the Red Wall, the X axis extends through the origin
+point and runs to the right and left, parallel with the Red Wall. The X axis
 values increase to the right.
 
 Y Axis
 ^^^^^^
 
-Looking at the origin from the RED WALL, the Y axis extends through the origin
-point and runs out and in, perpendicular to the RED WALL.  Increasing Y values
-run out (away) from the RED WALL.
+Looking at the origin from the Red Wall, the Y axis extends through the origin
+point and runs out and in, perpendicular to the Red Wall. Increasing Y values
+run out (away) from the Red Wall.
 
 Z Axis
 ^^^^^^
 
-Looking at the origin from the RED WALL, the Z axis extends through the origin
+Looking at the origin from the Red Wall, the Z axis extends through the origin
 point and runs up and down in a vertical line. Increasing Z values extend
 upwards.
 
-Rotation about Axes
+Rotation About Axes
 ^^^^^^^^^^^^^^^^^^^
 
 When considering rotations about an axis, consider yourself looking down the
-(positive) axis of rotation from the positive towards the origin. Positive
-rotations are then CCW, and negative rotations CW.
-
+axis from the positive end towards the origin. Positive
+rotations are then counterclockwise and negative rotations clockwise.
+   
 .. figure:: images/image1.jpg
-   :width: 35%
-   :align: center
-   :alt: Coordinate Axes
-
-   Figure 1: Coordinate Axes
+   :alt: X, Y and Z coordinate axes.
+
+   Counterclockwise rotations about each axis
+
+   Imagine looking down the positive Z axis towards the origin.
+   This would be like standing in the middle of the field looking down.
+   A positive rotation about the Z axis would be counterclockwise.
 
-An example: consider looking down the positive Z axis towards the origin. This
-would be like standing in the middle of the field, looking down. A positive
-rotation about Z (i.e. a rotation parallel to the X-Y plane) is then CCW, as
-one would normally expect from the usual classic 2D geometry.
+Example: a robot spinning clockwise on the Field is making a negative rotation about the Z axis.
 
-Examples
---------
+Field Configuration Examples
+----------------------------
 
-Below are two examples illustrating this Axes definition.
+Below are two examples illustrating the Field Coordinate System for different
+*FIRST* Tech Challenge field configurations.
 
 .. note::
-   Note that in both cases the Red Alliance members are facing out,
-   along the positive Y axis.
-
-   However, in the “Diamond” field configuration, the X axis is pointing
-   towards the Blue Alliance, but in the “Square” field configuration
-   the Y axis is pointing towards the Blue Alliance.
-
-
-.. figure:: images/image2.jpg
-   :width: 75%
-   :align: center
-   :alt: RES-Q
-
-   Figure 2: FIRST Tech Challenge RES-Q game field orientation
-
-.. figure:: images/image3.jpg
-   :width: 75%
-   :align: center
-   :alt: Cascade Effect
-
-   Figure 3: FIRST Tech Challenge Cascade Effect game field orientation
+   In both field configurations the red Alliance is facing out along the positive Y axis,
+   and the Z axis points up from the center of the field.
+
+Diamond Field
+^^^^^^^^^^^^^
+
+.. figure:: images/first-res-q-field.png
+   :alt: A diamond field with X, Y and Z axes shown.
+
+   The FIRST RES-Q game field
+
+   In a diamond field configuration the two Alliance walls are adjacent.
+   The field is rotated 45 degrees such that both Alliances face the audience.
+   From the audience perspective the field forms a diamond shape.
+   The Red Wall will be on the right as seen from the audience.
+   The Y axis points across the field as seen from the Red Wall. 
+   The X axis points to the Blue Alliance.
+
+Square Field
+^^^^^^^^^^^^
+
+.. figure:: images/into-the-deep-field.png
+   :alt: A square field with X, Y and Z axes shown.
+
+   The Into The Deep game field
+
+   In a square field configuration the two Alliances face each other across the field.
+   The field is oriented such that the Red Wall is on the right as seen from the audience.
+   The Y axis points across the field from the Red Wall towards the Blue Alliance.
+   The X axis points away from the audience to the rear of the field.
+
+Coordinate Position Example
+---------------------------
+
+Let's consider the coordinates (0, -24, 26) in inches on the Into The Deep field, which is a square field.
+Given the order of coordinates then X = 0, Y = -24, and Z = 26. 
+
+The X axis value of 0 is located at the origin in the center of the field.
+The Y axis value of negative 24 would be located closer to the Red Wall, away from the origin by the width of one tile.
+This the center of the wall of the submersible structure on the red side of the field.
+
+The Z axis value of 26 indicates the coordinates refer to the center and top of the Red Alliance "high chamber"
+(which is the higher of the two red crossbars).
 
 Measured Values
 ---------------
 
-The following values have been measured from a 2016 competition field. They are
+The following metric values have been measured from a 2016 competition field. They are
 representative only, and should not be assumed to be exact, or guaranteed.
 
--  Distance between opposite inside faces of panels: 3580 mm
-   (if field assembled well: the straps give some adjustment tolerance)
+-  Distance between opposite inside faces of panels: 3580 mm,
+   (if the field is assembled well: the straps give some adjustment tolerance)
 -  Polycarbonate transparencies have a visible opening height of 255 mm
 -  The top edge of transparencies is 30 mm from the top of the perimeter
 -  Total perimeter height is 313 mm
--  Tiles are 13mm thick
+-  Tiles are 13 mm thick
 
 So, for a diamond field configuration, the corner of the field closest to the
 audience, at a height equal to the top of the perimeter wall, would have a
-coordinate position of: (-1790, 1790, 300).
+coordinate position of: (-1790, 1790, 300) in millimeters.
+
+Additional Information
+----------------------
+
+See this Wikipedia article on `Cartesian coordinate system
+<https://en.wikipedia.org/wiki/Cartesian_coordinate_system#Three_dimensions>`__
+in three dimensions.
+The Field Coordinate System rotation convention comes from the 
+`right hand rule <https://en.wikipedia.org/wiki/Right-hand_rule>`__ 
+of classic geometry.
+
+Robots with a webcam can use :ref:`AprilTags <apriltag/vision_portal/apriltag_intro/apriltag-intro:apriltag introduction>`
+to determine where an :ref:`AprilTag is located 
+<apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values:introduction>` 
+with respect to the robot.
+Since AprilTags are in known locations on the field, you can also determine the
+:ref:`location of the robot <apriltag/vision_portal/apriltag_localization/apriltag-localization:apriltag localization>`
+on the field.
+
+Robots can use an inertial measurement unit (IMU) to measure rotations about axes
+with respect to the robot. See :ref:`IMU axes definition. <programming_resources/imu/imu:axes definition>`
+The yaw value from the IMU, also known the heading, measures rotation about the Z axis
+which points up from the robot. 
+You can use the IMU to determine which direction a robot is facing.
 

docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst

@@ -2,25 +2,51 @@ Playing Field Resources
 =======================
 
 .. figure:: images/CenterStageField.png
+   :alt: Arena with four teams in alliances areas. Four robots are on the field along with CENTERSTAGE game elements.
 
-    Traditional Playing Field ~ CENTERSTAGE presented by RTX, 2023-2024
+   Traditional Playing Field, CENTERSTAGE presented by RTX, 2023-2024
 
 About the Playing Field
-------------------------------------
-There are multiple configurations of the playing field that can be used. For traditional games, the playing field is a part of the Competition Area that includes the 12 ft. x 12 ft. (3.66 m x 3.66 m) field and all
-the elements described in the official field drawings. For remote games, the playing field is a part of the Competition Area that includes the 12 ft. x 8 ft. (3.66 m x 2.44 m) field and all the elements described 
-in the official field drawings. The base field stays the same for all games but the game elements are subject to change as per :ref:`Game Manual Part 2<manuals/game_manuals/game_manuals:game manuals>`.
+-----------------------
 
+There are multiple configurations of the playing field that can be used. For traditional games, the playing field is a part of the Arena that includes the 12 ft. x 12 ft. (3.66 m x 3.66 m) field and all
+the elements described in the official field drawings. For remote games, the playing field is a part of the Arena that includes a 12 ft. x 8 ft. (3.66 m x 2.44 m) field and all the elements described 
+in the official field drawings. The base field stays the same for all games but the game elements are subject to change as per the Competition Manual.
 
-Traditional Field Setup Guide
-------------------------------------
+The Competition Manual contains an Arena section that details the playing field for that years game.
+It includes measurements for key aspects of the field and game elements and scoring elements.
+For example, the height of a basket into which a scoring element can be placed.
+The Competition Manual can be found on the
+`Game and Season Materials page <https://ftc-resources.firstinspires.org/files/ftc/game>`_ on the *FIRST* Website.
 
-This document can be found here: `Traditional Field Setup Guide <https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide>`__
+Field Setup Guide
+-----------------
 
-.. only:: html
+The Field Setup Guide has the official instructions for assembling and setting up a *FIRST* Tech Challenge field.
+Typically there are assembly instructions that build structures that then have setup instructions for placing on the field.
+There are also teardown instructions that indicate how to take apart the field for storage or transport.
 
-   .. raw:: html
+The guide typically has the following sections:
 
-       <iframe id="iframepdf" src="https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide" width="100%" height="700"></iframe>
+- A list of all tools required for assembly and setup, some tools are only for assembly or for setup.
+- Lists all the game elements and scoring elements with the quantity of each.
+- Instructions for setup of the field perimeter and field tiles.
+- Step by step instructions for assembling parts and setting them on the field.
+- Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the Alliances, and sometimes for game areas.
+- Most games have AprilTags placed around the field that can be used for robot navigation.
+- Finally, there are teardown instructions that indicate how to take the field down for storage or transport.
 
-|
+Use the following button link to download a PDF of the Field Setup Guide from the *FIRST* Website:
+
+.. button-link:: https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide
+   :color: primary
+
+   Download PDF, 4.5 MB, will open in a new tab
+
+.. note:: The Field Setup Guide has instructions for assembling an official game set as purchased from AndyMark.
+
+   A purchased game set can be full or partial. A partial game set is less expensive and also suitable for teams who
+   want official game elements but don't have room to setup a full field.
+
+The `Game and Season Materials page (FIRST website) <https://ftc-resources.firstinspires.org/files/ftc/game>`_ also contains downloadable PDFs for the AprilTag images that can be printed and placed on the field.
+There is also a do it yourself (DIY) Resources section that include CAD models of the game and scoring elements and DIY field and perimeter build guides.