diff --git a/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst b/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst index 36b175a2..1b38be2c 100644 --- a/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst +++ b/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 +`__ +in three dimensions. +The Field Coordinate System rotation convention comes from the +`right hand rule `__ +of classic geometry. + +Robots with a webcam can use :ref:`AprilTags ` +to determine where an :ref:`AprilTag is located +` +with respect to the robot. +Since AprilTags are in known locations on the field, you can also determine the +:ref:`location of the robot ` +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. ` +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. diff --git a/docs/source/game_specific_resources/field_coordinate_system/images/first-res-q-field.png b/docs/source/game_specific_resources/field_coordinate_system/images/first-res-q-field.png new file mode 100644 index 00000000..b72719c6 Binary files /dev/null and b/docs/source/game_specific_resources/field_coordinate_system/images/first-res-q-field.png differ diff --git a/docs/source/game_specific_resources/field_coordinate_system/images/image2.jpg b/docs/source/game_specific_resources/field_coordinate_system/images/image2.jpg deleted file mode 100644 index 58729f90..00000000 Binary files a/docs/source/game_specific_resources/field_coordinate_system/images/image2.jpg and /dev/null differ diff --git a/docs/source/game_specific_resources/field_coordinate_system/images/image3.jpg b/docs/source/game_specific_resources/field_coordinate_system/images/image3.jpg deleted file mode 100644 index 2519ea32..00000000 Binary files a/docs/source/game_specific_resources/field_coordinate_system/images/image3.jpg and /dev/null differ diff --git a/docs/source/game_specific_resources/field_coordinate_system/images/into-the-deep-field.png b/docs/source/game_specific_resources/field_coordinate_system/images/into-the-deep-field.png new file mode 100644 index 00000000..84169d51 Binary files /dev/null and b/docs/source/game_specific_resources/field_coordinate_system/images/into-the-deep-field.png differ