docs: Update coordinate systems and orientation documentation

- Move coordinates.rst from tutorials/ to reference/ for better discoverability in the sidebar.
- Add the coordinates page to the Language Reference toctree.
- Update the global coordinate system section to clarify Euler angle composition and intrinsic rotation order.
- Revise the local coordinate system section to generalize parentOrientation behavior:
  - Most specifiers allow an optional parentOrientation override at level 3.
  - The :specifier: specifier sets parentOrientation automatically at level 2.
  - Added a note on tuple syntax ((3, 3, 3)) and linked to the specifiers page for more details.
- Update the Orientation entry in the Data Types Reference to include a link to the coordinates page.

Author: lola831

docs/language_reference.rst

@@ -16,6 +16,7 @@ For details on the syntax for functions, loops, etc. inherited from Python, see
 
     reference/general
     reference/data
+    reference/coordinates
     reference/region_types
     reference/distributions
     reference/statements
@@ -33,4 +34,4 @@ The pages above describe the semantics of each of Scenic's constructs individual
     :maxdepth: 1
 
     reference/scene_generation
-    reference/dynamic_scenarios
+    reference/dynamic_scenarios

docs/tutorials/coordinates.rst docs/reference/coordinates.rstdocs/tutorials/coordinates.rst renamed to docs/reference/coordinates.rst

@@ -10,8 +10,8 @@ Global Coordinate System
 All objects in Scenic have an :prop:`orientation` property, which is their orientation in global coordinates.
 Scenic represents orientations internally using quaternions, though for convenience they can be created using Euler angles. Scenic follows the right hand rule with the Z,X,Y order of rotations. In other words, Euler angles are given as (Yaw, Pitch, Roll), in radians, and applied in that order.
 
-:prop:`orientation` is derived from the values of 4 other properties, :prop:`parentOrientation`, :prop:`yaw`, :prop:`pitch`, and :prop:`roll`. 
-The :prop:`parentOrientation` property defines the parent orientation of the object, which is the orientation with respect to which the intrinsic Euler angles :prop:`yaw`, :prop:`pitch`, and :prop:`roll` are interpreted. 
+:prop:`orientation` is derived from the values of 4 other properties, :prop:`parentOrientation`, :prop:`yaw`, :prop:`pitch`, and :prop:`roll`.
+The :prop:`parentOrientation` property defines the parent orientation of the object, which is the orientation with respect to which the intrinsic Euler angles :prop:`yaw`, :prop:`pitch`, and :prop:`roll` are interpreted.
 Specifically, :prop:`orientation` is obtained as follows:
 
   1. start from :prop:`parentOrientation`;
@@ -26,26 +26,33 @@ Below is an illustration of the global coordinate system
 
 By default, :prop:`parentOrientation` is aligned with the global coordinate system, so that :prop:`yaw` for example is just the angle by which to rotate the object around the Z axis.
 
-This corresponds to the :prop:`heading` property in older versions of Scenic. :prop:`heading` represents yaw in the global XY plane. Scenic represents headings in radians, measured anticlockwise from North, so that a heading of 0 is due North and a heading of π/2 is due West. 
+This corresponds to the :prop:`heading` property in older versions of Scenic. :prop:`heading` represents yaw in the global XY plane. Scenic represents headings in radians, measured anticlockwise from North, so that a heading of 0 is due North and a heading of π/2 is due West.
 
 For more information on orientations and heading please consult:
 
     * Tutorial on Orientations :ref:`orientations_tutorial`
     * Reference on Orientations: :ref:`Orientation`.
     * Reference on Heading: :ref:`Heading`
 
+.. note::
+    When manually composing rotations in Scenic, remember that if rotation **A** is applied first, followed by rotation **B**, the resulting orientation is computed as **A * B**. This multiplication order is reversed relative to the typical extrinsic rotation convention, reflecting Scenic’s use of intrinsic Euler angles.
+
 Local Coordinate System
 -----------------------
-If you want to specify an objects coordinate system relative to other objects, there are specifiers for the :prop:`orientation` to do so. 
+When specifying an object's coordinate system relative to other objects, several position specifiers can influence its :prop:`parentOrientation`.
+
+- Most position specifiers—such as the :specifier:`ahead of` specifier and the general operator :scenic:`{X} relative to {Y}`—allow you to optionally override the default :prop:`parentOrientation` at level 3 by appending a clause like :specifier:`with parentOrientation {value}`.
+
+- In contrast, the :specifier:`on {region}` specifier automatically sets :prop:`parentOrientation` (at level 2) whenever the region in question has a preferred orientation. The region's associated vector field defines an orientation at each point, which is then used as the default for the object.
+
+.. note::
+    When using tuple syntax (e.g. ``(3, 3, 3)``) to specify positions, be aware that these tuples are interpreted as Vectors, which can sometimes yield unintuitive results. For more details, see the :ref:`specifiers` page.
+
+- Additionally, the `OrientedPoint` class encapsulates a position along with an orientation (and its associated properties, including :prop:`parentOrientation`, :prop:`yaw`, etc.), thereby defining a complete local coordinate system.
 
-    1. The :specifier:`on {region}` specifier specifies :prop:`parentOrientation` whenever the region in question has a :term:`preferred orientation`: a `vector field` (another primitive Scenic type) which defines an orientation at each point in the region.
-    2. The :specifier:`ahead of` specifier only specifies :prop:`parentOrientation` *optionally*, giving it a new default value: if you want a different value, you can override that default by explicitly writing :specifier:`with parentOrientation {value}`.
-    3. The general operator :scenic:`{X} relative to {Y}` can interpret vectors and orientations as being in a variety of local coordinate systems
-    4. The `OrientedPoint` class adds :prop:`position` and :prop:`orientation` (plus :prop:`parentOrientation`, :prop:`yaw`, etc.) to define a local coordinate sytem.
 
 For more information on defining a local coordinate system, please consult:
 
     * Tutorial on :scenic:`relative to`: :ref:`dependencies_and_modifying_specifiers`
     * Reference on :scenic:`relative to` for headings: :ref:`operators`
     * Reference on `OrientedPoint`: :ref:`OrientedPoint`
-

docs/reference/data.rst

@@ -63,8 +63,11 @@ Scenic rejects such expressions as being ambiguous: more explicit syntax like :s
 
 Orientation
 ===========
-Orientations represent orientations in 3D space.
-Scenic represents orientations internally using quaternions, though for convenience they can be created using Euler angles. Scenic follows the right hand rule with the Z,X,Y order of rotations. In other words, Euler angles are given as (Yaw, Pitch, Roll), in radians, and applied in that order. To help visualize, one can consider their right hand with fingers extended orthogonally. The index finger points along positive X, the middle finger bends left along positive Y, and the thumb ends up pointing along positive Z. For rotations, align your right thumb with a positive axis and the way your fingers curl is a positive rotation.
+Orientations represent rotations in 3D space. Scenic represents orientations internally using quaternions, though for convenience they can be created using Euler angles. Scenic follows the right hand rule with the Z,X,Y order of rotations. In other words, Euler angles are given as (Yaw, Pitch, Roll), in radians, and applied in that order.
+
+For a more detailed explanation of coordinate systems and rotation composition in Scenic, see the :ref:`coordinates` page.
+
+To help visualize an orientation, consider your right hand with fingers extended orthogonally. The index finger points along the positive X axis, the middle finger along the positive Y axis, and the thumb along the positive Z axis. When you align your right thumb with a positive axis, the way your fingers curl indicates a positive rotation.
 
 .. versionadded:: 3.0
 
@@ -135,4 +138,3 @@ When creating a `MeshShape`, if no dimensions are provided then dimensions will
 .. autoclass:: scenic.core.shapes.SpheroidShape
     :noindex:
     :no-show-inheritance:
-