From 5798bdc5bd8f7c7dc2894dce792f065ad85c8c37 Mon Sep 17 00:00:00 2001 From: Mike Date: Tue, 12 Nov 2024 15:05:28 -0800 Subject: [PATCH 1/4] add image descriptions and other readability fixes --- .../field-coordinate-system.rst | 92 ++++++++++++------- 1 file changed, 57 insertions(+), 35 deletions(-) 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 a080c4a0..be14aa66 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,15 +1,21 @@ -*FIRST* Tech Challenge Field “Coordinate System" Definition -=========================================================== +Field Coordinate System Definition +================================== 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 +The Field Coordinate System is a +`three-dimensional Cartesian coordinate system +`__ +which means that the three axes are at right angles to each other. +The X and Y axes will refer to a position on the field and Z axis a height above the field. + +Reference Frame --------------- The reference frame for this definition is the field perimeter wall, adjacent @@ -51,52 +57,68 @@ 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. +This rotation convention comes from the `right hand rule `__ of classic geometry. .. figure:: images/image1.jpg :width: 35% :align: center - :alt: Coordinate Axes - - Figure 1: Coordinate Axes - -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. - -Examples --------- - -Below are two examples illustrating this Axes definition. - -.. 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. - + :class: no-scaled-link + :alt: illustration + + showing the counterclockwise rotations about each axis. + +A rotation example: consider looking down the positive Z axis towards the origin. +This would be like standing in the middle of the field +looking down at the intersection of the tiles in the very center of the field. +A positive rotation about the Z axis is then counterclockwise. +Example: a robot spinning clockwise on the field is making a negative rotation about the Z axis. + +Field Configuration Examples +---------------------------- + +Below are two examples illustrating the Field Coordinate System for different +*FIRST* Tech Challenge field configurations. + +In a diamond field configuration the two alliance walls are adjacent. +The field is rotated 45 degrees such that both alliances face the audience. +The red alliance will be on the right as seen from the audience. +The Y axis points across the field from the RED WALL and the X axis points to +the Blue Alliance on the right side of the field. .. figure:: images/image2.jpg :width: 75% :align: center - :alt: RES-Q + :class: no-scaled-link + :alt: a diamond field + + from the FIRST RES-Q game - Figure 2: FIRST Tech Challenge RES-Q game field orientation +In a square field configuration the two alliances face each other across the field. +The field is oriented such that the red alliance is on the right as seen from the audience. +The Y axis points across the field to the Blue Alliance and the X axis points +to the right side of the field, away from the audience. .. figure:: images/image3.jpg :width: 75% :align: center - :alt: Cascade Effect + :class: no-scaled-link + :alt: a square field + + from the Cascade Effect game - Figure 3: FIRST Tech Challenge Cascade Effect game field orientation +.. note:: + In both field configurations the Red Alliance team members are facing out along the positive Y axis + and the Z axis points up from the center of the field. + + 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. Measured Values --------------- @@ -109,7 +131,7 @@ representative only, and should not be assumed to be exact, or guaranteed. - 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 From b63b782f5fbc46e7d34d88e0fd4975bb7e075b3c Mon Sep 17 00:00:00 2001 From: Mike Date: Fri, 15 Nov 2024 14:11:37 -0800 Subject: [PATCH 2/4] fix text descriptions of one image, add Glossary, adjust capitalized words, fix tile dimensions when read out loud --- .../field-coordinate-system.rst | 112 +++++++++++------- 1 file changed, 69 insertions(+), 43 deletions(-) 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 be14aa66..17de4f1d 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 @@ -4,8 +4,9 @@ Field Coordinate System Definition Scope ----- + This document defines the Field Coordinate System -for a *FIRST* Tech Challenge playing field. This definition can be +for a *FIRST* Tech Challenge playing Field. This definition can be used for consistent field-centric navigation, target localization and path planning. @@ -13,47 +14,48 @@ The Field Coordinate System is a `three-dimensional Cartesian coordinate system `__ which means that the three axes are at right angles to each other. -The X and Y axes will refer to a position on the field and Z axis a height above the field. +The X and Y axes will refer to a position on the Field and Z axis a height above the Field. 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 -from the perspective of a person, standing outside the field, in the center of -RED WALL, looking towards the center of the field. +The reference frame for this definition is the Field perimeter wall, adjacent +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. +.. 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. Origin ^^^^^^ The 0,0,0 origin of the *FIRST* Tech Challenge coordinate system is the point -in the center of the field, equidistant from all 4 perimeter walls (where the +in the center of the Field, equidistant from all 4 perimeter walls (where the four center tiles meet). The origin point rests on the top surface of the floor 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. @@ -63,7 +65,8 @@ Rotation About Axes When considering rotations about an axis, consider yourself looking down the axis from the positive end towards the origin. Positive rotations are then counterclockwise and negative rotations clockwise. -This rotation convention comes from the `right hand rule `__ of classic geometry. +This rotation convention comes from the +`right hand rule `__ of classic geometry. .. figure:: images/image1.jpg :width: 35% @@ -74,66 +77,89 @@ This rotation convention comes from the `right hand rule Date: Sat, 23 Nov 2024 07:39:35 -0800 Subject: [PATCH 3/4] more changes and I think a better approach to long descriptions --- .../field-coordinate-system.rst | 166 ++++++++++++------ 1 file changed, 112 insertions(+), 54 deletions(-) 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 17de4f1d..1584610e 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,21 +1,26 @@ -Field Coordinate System Definition -================================== +*FIRST* Tech Challenge Field Coordinate System Definition +========================================================= + +.. meta:: + :description: This document defines the 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. + +.. contents:: In This Article: + :local: + :depth: 1 + :backlinks: none Scope ----- - 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. -The Field Coordinate System is a -`three-dimensional Cartesian coordinate system -`__ -which means that the three axes are at right angles to each other. -The X and Y axes will refer to a position on the Field and Z axis a height above the Field. - Reference Frame --------------- @@ -24,11 +29,21 @@ 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. -.. note:: +.. 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 ^^^^^^ @@ -65,22 +80,18 @@ Rotation About Axes When considering rotations about an axis, consider yourself looking down the axis from the positive end towards the origin. Positive rotations are then counterclockwise and negative rotations clockwise. -This rotation convention comes from the -`right hand rule `__ of classic geometry. - -.. figure:: images/image1.jpg - :width: 35% - :align: center - :class: no-scaled-link - :alt: illustration - showing the counterclockwise rotations about each axis. +.. figure:: images/image1.jpg + :alt: -A rotation example: consider looking down the positive Z axis towards the origin. -This would be like standing in the middle of the Field -looking down at the intersection of the tiles in the very center of the Field. -A positive rotation about the Z axis is then counterclockwise. -Example: a robot spinning clockwise on the Field is making a negative rotation about the Z axis. + 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 at the intersection of the tiles in the very center of the Field. + A positive rotation about the Z axis is then counterclockwise. + +Example: a robot spinning clockwise on the Field is making a negative rotation about the Z axis. Field Configuration Examples ---------------------------- @@ -88,35 +99,35 @@ Field Configuration Examples Below are two examples illustrating the Field Coordinate System for different *FIRST* Tech Challenge Field configurations. -In a diamond Field configuration the two Alliance walls are adjacent. -The Field is rotated 45 degrees such that both Alliance Areas 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, -and the blue wall will be on the left. -The Y axis points across the Field as seen from the Red Wall. -The X axis points to the blue wall. +Diamond Field +^^^^^^^^^^^^^ .. figure:: images/image2.jpg - :width: 75% - :align: center - :class: no-scaled-link - :alt: a diamond Field + :alt: - from the *FIRST* RES-Q game - -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, -and the blue wall will be on the left. -The Y axis points across the Field from the Red Wall to the blue wall. -The X axis points away from the audience to the rear of the Field. + The *FIRST* RES-Q game Field with X, Y and Z axes shown. + + 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, + and the blue wall will be on the left. + The Y axis points across the Field as seen from the Red Wall. + The X axis points to the blue wall. + +Square Field +^^^^^^^^^^^^ .. figure:: images/image3.jpg - :width: 75% - :align: center - :class: no-scaled-link - :alt: a square Field + :alt: - from the Cascade Effect game + The Cascade Effect game Field with X, Y and Z axes shown. + + 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, and the blue wall will be on the left. + The Y axis points across the Field from the Red Wall to the blue wall. + The X axis points away from the audience to the rear of the Field. .. note:: In both Field configurations the red Alliance is facing out along the positive Y axis, @@ -126,10 +137,24 @@ The X axis points away from the audience to the rear of the Field. towards the blue Alliance. In the square Field configuration the Y axis is pointing towards the blue Alliance. +Coordinate Position Example +--------------------------- + +Let's consider a robot on the Cascade Effect Field at coordinates +(60, -60, 10) in inches. So X = 60, y = -60, and Z = 10. +Measured in inches, the walls would be about 72 inches from the origin. +Cascade Effect was a Sqaure Field configuration, so +the X axis value of positive 60 would be located close to the rear field wall, away from the audience. +The Y axis value of negative 60 would be located close to the Red Wall, away from the origin. +Together the X and Y values (60, -60) indicate a position in the corner of the Field. +That corner is adjacent to the Red Wall and furthest from the audience. +The Z axis value of 10 places the robot on top of the red +ramp that is in that corner in the Cascade Effect game. + 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, @@ -141,7 +166,31 @@ representative only, and should not be assumed to be exact, or guaranteed. 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. Glossary -------- @@ -154,12 +203,21 @@ Glossary and an Alliance in the blue Alliance Area is known as the blue Alliance. Alliance Area - A 120 inch (~304.8 cm) wide by 42 inch (~106.7 cm) deep by infinitely tall volume formed - by placing Alliance colored tape onto the flooring surface outside of the Field. - The Alliance Area includes the taped lines. + A 120 inch wide by 42 inch deep (304.8 cm by 106.7 cm) by infinitely tall volume + formed by placing Alliance colored tape onto the flooring surface outside of the Field. The red Alliance Area will have red tape, the blue Alliance Area will have blue tape. + The Alliance Area includes the taped lines. + + Cartesian Coordinate System + A Cartesian coordinate system for three-dimensional space consists of an ordered triplet of lines + (the axes) that go through a common point (the origin). The axes are pair-wise perpendicular + (at right-angles to each other). A single unit of measure applies to all three axes. + A point P in space can then be referenced by three numbers which correspond to the three axes. + The Cartesian coordinates of P are those three numbers, in the chosen order. Field - An approximately 12 foot (3.66m) by 12 foot (3.66m) Area bounded by the + A square area with walls approximately 12 feet (3.66 meters) long bounded by the outside edge of the extrusion that frames the walls of the Field perimeter. - The flooring surface of the Field is made of 36 (nominal size) 24 inch by 24 inch by 5/8 inch interlocking soft foam tiles. + The flooring surface of the Field is made of 36 interlocking soft foam tiles. + The nominal size of a tile is 24 inches by 24 inches by 5/8 of an inch. + From 5f58c350a3eb83b59d78a0f9ec332f1c97373e79 Mon Sep 17 00:00:00 2001 From: Mike Date: Sat, 23 Nov 2024 07:42:18 -0800 Subject: [PATCH 4/4] fix spelling mistake --- .../field_coordinate_system/field-coordinate-system.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 1584610e..2eded43a 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 @@ -143,7 +143,7 @@ Coordinate Position Example Let's consider a robot on the Cascade Effect Field at coordinates (60, -60, 10) in inches. So X = 60, y = -60, and Z = 10. Measured in inches, the walls would be about 72 inches from the origin. -Cascade Effect was a Sqaure Field configuration, so +Cascade Effect was a Square Field configuration, so the X axis value of positive 60 would be located close to the rear field wall, away from the audience. The Y axis value of negative 60 would be located close to the Red Wall, away from the origin. Together the X and Y values (60, -60) indicate a position in the corner of the Field.