Coordinate System in movementEngineMk2

This document explains the coordinate system and transformation mathematics used in the movementEngineMk2 package.

Overview

The movementEngineMk2 uses an arbitrary coordinate system that can be dynamically reconfigured. This allows for complex movement patterns and relative positioning within different contexts.

Basic Coordinate System

At its core, the coordinate system defines three axes with a fixed orientation:

• X-axis: Forward/backward direction (positive = forward)
• Y-axis: Up/down direction (positive = up)
• Z-axis: Right/left direction (positive = right)

When the engine is initialized:

• X = 0, Y = 0, Z = 0 represents the starting position
• The coordinate system's orientation is fixed at initialization
• Important: Movement coordinates are always interpreted relative to the fixed coordinate system's orientation, not the turtle's current physical facing direction. The turtle's facing (angle) does not affect how movement coordinates are interpreted.

Transformation Matrices

The engine uses 2×2 transformation matrices to handle coordinate rotations based on the turtle's current facing angle:

Where angle is the current facing angle (0-359 degrees).

How Transformations Work

1. Rotation: When the turtle turns, the matrix is updated to reflect the new orientation
2. Movement: Movement vectors (x, z) are multiplied by the matrix to transform them into the current physical facing direction
3. Position Tracking: The engine tracks absolute position in world coordinates while providing relative movement in the current coordinate system

Note: The transformation matrix converts movement coordinates from the fixed coordinate system to the turtle's current physical facing direction.

Matrix Multiplication Example

For a turtle facing 90 degrees (right) with a fixed coordinate system:

• Matrix: { {0, -1}, {1, 0} }
• Movement vector: {5, 0} (forward 5 in fixed coordinate system)
• Transformed: {0*5 + (-1)*0, 1*5 + 0*0} = {0, 5} (actual movement is right 5 in world coordinates)

Nested Coordinate Systems

The setCenter() and popCenter() functions enable nested coordinate systems:

setCenter(x, y, z, angle)

1. Saves current state: Pushes current position and angle onto the position stack
2. Creates new reference frame:
   • New origin at (x, y, z)
   • Creates a local coordinate system with X-axis aligned with specified angle
   • Position is recalculated relative to new origin
3. Updates matrix: Creates new transformation matrix based on angle difference

Important: This creates a local coordinate system that is independent of the turtle's current physical facing. The local coordinate system's orientation is defined by the angle parameter.

popCenter()

1. Retrieves previous state: Pops position and angle from the stack
2. Restores coordinate system:
   • Recalculates position in previous coordinate system
   • Updates transformation matrix
   • Restores previous facing angle

Example: Nested Coordinate System

Coordinate System Stack

The positionStack maintains a stack of coordinate systems:

Each time setCenter() is called, a new entry is pushed onto the stack. Each popCenter() removes the top entry and restores the previous coordinate system.

Mathematical Foundations

Angle Normalization

Angles are normalized to the range [0, 360) degrees using modulo arithmetic:

Matrix Creation

The transformation matrix is created based on the current angle:

Matrix-Vector Multiplication

Movement vectors are transformed using matrix multiplication:

Practical Implications

Why Use Nested Coordinate Systems?

1. Relative Movement: Perform operations relative to specific locations
2. Pattern Repetition: Create reusable movement patterns at different locations
3. Local Coordinates: Work in local coordinates while tracking global position
4. Complex Paths: Build complex paths by combining multiple coordinate systems

Example Use Case: Mining Pattern

Example Use Case: Construction

Common Pitfalls

1. Forgetting to popCenter(): Always balance setCenter() and popCenter() calls
2. Angle Confusion: Remember that the angle parameter in setCenter() defines the new local X-axis direction, not the turtle's physical facing
3. Position Tracking: The engine tracks absolute position in world coordinates, but movement coordinates are interpreted relative to the current coordinate system (which may be a local coordinate system with its own orientation)
4. Negative Values: Negative movement values reverse direction along the specified axis

Visualizing Coordinate Systems

Imagine the turtle's world as multiple layers of graph paper:

• Bottom layer: World coordinates (fixed origin)
• Top layer(s): Current coordinate system(s) (moving origin(s))
• Movement: Always relative to top layer
• Transformations: When you change coordinate systems, the graph paper shifts and rotates

The setCenter() function is like placing a new piece of graph paper on top, with its own origin and local orientation (defined by the angle parameter). This local orientation is independent of the turtle's physical facing direction. The popCenter() function removes that top layer, revealing the previous one below.