Move the documentation dection to the top of the page

index.html

@@ -14,9 +14,182 @@
         <p>Interactive simulation of a swerve drive robot with configurable size, speeds, and number of wheels</p>
     </header>
     <main>
+        <section class="documentation">
+            <h2>About This Project</h2>
+            <details>
+                <summary>How To Use</summary>
+                <div class="documentation-content">
+                    <h3>Getting Started</h3>
+                    <p>This interactive visualizer demonstrates how a swerve drive robot moves based on commanded
+                        velocities. Use the controls to experiment with different configurations and movement patterns.
+                    </p>
+
+                    <h3>Drive Controls</h3>
+                    <ul>
+                        <li><strong>Strafe Left/Right:</strong> Controls the robot's velocity in the X direction
+                            (field-relative). Positive values move right, negative values move left.</li>
+                        <li><strong>Move Forward/Backward:</strong> Controls the robot's velocity in the Y direction
+                            (field-relative). Positive values move forward, negative values move backward.</li>
+                        <li><strong>Rotation:</strong> Controls the robot's angular velocity (turn rate) in radians per
+                            second. Positive values rotate counter-clockwise.</li>
+                        <li><strong>Max Module Speed:</strong> Sets the maximum speed limit for any individual swerve
+                            module. If calculated speeds exceed this, all modules are scaled proportionally.</li>
+                        <li><strong>Reset Controls:</strong> Returns all velocity sliders to zero.</li>
+                    </ul>
+
+                    <h3>Preset Configurations</h3>
+                    <p>Choose from 9 pre-built robot configurations ranging from 2 to 16 wheels. Each preset
+                        demonstrates different module arrangements:</p>
+                    <ul>
+                        <li><strong>2-Wheel:</strong> Differential drive arrangement</li>
+                        <li><strong>3-Wheel Triangle:</strong> Three modules in an equilateral triangle</li>
+                        <li><strong>4-Wheel Square:</strong> Classic square configuration</li>
+                        <li><strong>4-Wheel Rectangle:</strong> Rectangular configuration for longer robots</li>
+                        <li><strong>6-Wheel Hexagon:</strong> Hexagonal arrangement</li>
+                        <li><strong>8-Wheel Octagon:</strong> Octagonal arrangement</li>
+                        <li><strong>8-Wheel Square:</strong> Double-layered square with inner and outer modules</li>
+                        <li><strong>12-Wheel Hexagon:</strong> Double-layered hexagonal arrangement</li>
+                        <li><strong>16-Wheel Octagon:</strong> Double-layered octagonal arrangement</li>
+                    </ul>
+
+                    <h3>Custom Configurations</h3>
+                    <p>Create your own robot configuration:</p>
+                    <ol>
+                        <li>Enter the desired number of modules (Minimum of 2)</li>
+                        <li>Click <strong>Generate Position Inputs</strong> to create input fields</li>
+                        <li>For each module, specify:
+                            <ul>
+                                <li><strong>Module Name:</strong> A label for the module</li>
+                                <li><strong>X Position:</strong> Distance from robot center (pixels, positive = right)
+                                </li>
+                                <li><strong>Y Position:</strong> Distance from robot center (pixels, positive = up)</li>
+                            </ul>
+                        </li>
+                        <li>Click <strong>Apply Custom Configuration</strong> to see your design</li>
+                        <li>Use <strong>Remove Position Inputs</strong> to clear the custom fields. This does not reset
+                            the robot, only clears the input box</li>
+                    </ol>
+
+                    <h3>Understanding the Visualization</h3>
+                    <ul>
+                        <li><strong>Robot Frame:</strong> The filled polygon connecting the outer-most module positions
+                        </li>
+                        <li><strong>Modules:</strong> Circular markers at each wheel position</li>
+                        <li><strong>Velocity Arrows:</strong> Red arrows showing the direction and magnitude of each
+                            module's velocity</li>
+                        <li><strong>Grid:</strong> Moves relative to the robot to show field-relative motion</li>
+                        <li><strong>Gyro Heading:</strong> The current rotation angle of the robot in degrees</li>
+                    </ul>
+
+                    <h3>Module States Panel</h3>
+                    <p>Displays real-time information for each module:</p>
+                    <ul>
+                        <li><strong>Angle:</strong> The direction the module is pointing (in degrees)</li>
+                        <li><strong>Speed:</strong> The velocity of the module (in pixels/second)</li>
+                    </ul>
+                </div>
+            </details>
+            <details>
+                <summary>Explanation of Swerve Kinematics</summary>
+                <div class="documentation-content">
+                    <h3>What is Swerve Drive?</h3>
+                    <p>Swerve drive (also called holonomic drive) is a drivetrain design where each wheel module can
+                        independently rotate and drive in any direction. This allows the robot to move in any direction
+                        while simultaneously rotating, providing exceptional maneuverability.</p>
+
+                    <h3>Kinematic Equations</h3>
+                    <p>The simulator calculates each module's state using inverse kinematics. Given a desired robot
+                        velocity (v<sub>x</sub>, v<sub>y</sub>) and rotation rate (ω), we calculate each module's
+                        required velocity.</p>
+
+                    <h4>Field-Relative vs Robot-Relative</h4>
+                    <p>This simulator uses <strong>field-relative control</strong>, meaning the velocity commands are
+                        relative to the field, not the robot's current orientation. The inputs are transformed to
+                        robot-relative coordinates using the current gyro heading:</p>
+                    <pre>
+v<sub>robot_x</sub> = v<sub>field_x</sub> × cos(-θ) - v<sub>field_y</sub> × sin(-θ)
+v<sub>robot_y</sub> = v<sub>field_x</sub> × sin(-θ) + v<sub>field_y</sub> × cos(-θ)
+                    </pre>
+                    <p>Where θ is the robot's heading angle (gyro reading).</p>
+
+                    <h4>Module Velocity Calculation</h4>
+                    <p>For each module at position (x<sub>i</sub>, y<sub>i</sub>) relative to the robot's center of
+                        rotation:</p>
+                    <ol>
+                        <li><strong>Translation component:</strong> The robot's linear velocity (v<sub>robot_x</sub>,
+                            v<sub>robot_y</sub>)</li>
+                        <li><strong>Rotation component:</strong> Perpendicular to the position vector, with magnitude
+                            proportional to distance from center:
+                            <pre>
+v<sub>rot_x</sub> = -y<sub>i</sub> × ω
+v<sub>rot_y</sub> = x<sub>i</sub> × ω
+                            </pre>
+                        </li>
+                        <li><strong>Combined velocity:</strong> Vector sum of translation and rotation:
+                            <pre>
+v<sub>module_x</sub> = v<sub>robot_x</sub> + v<sub>rot_x</sub>
+v<sub>module_y</sub> = v<sub>robot_y</sub> + v<sub>rot_y</sub>
+                            </pre>
+                        </li>
+                    </ol>
+
+                    <h4>Module Angle and Speed</h4>
+                    <p>From the module's velocity vector, we calculate:</p>
+                    <ul>
+                        <li><strong>Speed:</strong> The magnitude of the velocity vector: √(v<sub>x</sub>² +
+                            v<sub>y</sub>²)</li>
+                        <li><strong>Angle:</strong> The direction of the velocity vector: arctan2(v<sub>y</sub>,
+                            v<sub>x</sub>)</li>
+                    </ul>
+
+                    <h4>Speed Normalization</h4>
+                    <p>If any module's calculated speed exceeds the maximum allowed speed, all module velocities are
+                        scaled proportionally. This preserves the movement direction while respecting hardware limits:
+                    </p>
+                    <pre>
+scale = max_speed / max(calculated_speeds)
+if scale &lt; 1:
+    all_module_speeds × scale
+                    </pre>
+
+                    <h3>Gyro Integration</h3>
+                    <p>The robot's heading (gyro angle) is continuously updated by integrating the rotation rate:</p>
+                    <pre>
+θ<sub>new</sub> = θ<sub>old</sub> + ω × Δt
+                    </pre>
+                    <p>Where Δt is the time step. The heading is normalized to stay within the range [-π, π].</p>
+
+                    <h3>Real-World Applications</h3>
+                    <p>Swerve drive systems are commonly used in:</p>
+                    <ul>
+                        <li><strong>FRC (FIRST Robotics Competition):</strong> For competitive robots requiring precise
+                            positioning</li>
+                        <li><strong>Industrial AGVs:</strong> Automated guided vehicles in warehouses</li>
+                        <li><strong>Research Platforms:</strong> Mobile robots requiring omnidirectional movement</li>
+                    </ul>
+
+                    <h3>Key Advantages</h3>
+                    <ul>
+                        <li>True holonomic motion (can move in any direction without rotating)</li>
+                        <li>Can translate and rotate simultaneously</li>
+                        <li>Excellent maneuverability in constrained spaces</li>
+                        <li>No "drift" or unwanted rotation during translation</li>
+                    </ul>
+
+                    <h3>Implementation Considerations</h3>
+                    <ul>
+                        <li><strong>Mechanical Complexity:</strong> Each module requires two motors (drive and steering)
+                        </li>
+                        <li><strong>Control Complexity:</strong> Requires coordinated control of all modules</li>
+                        <li><strong>Sensor Requirements:</strong> Absolute encoders recommended for module angles</li>
+                        <li><strong>Cost:</strong> More expensive than traditional drivetrains</li>
+                    </ul>
+                </div>
+            </details>
+        </section>
         <section class="visualization-canvas">
             <h2>Robot Visualization</h2>
-            <canvas id="swerve-canvas" width="600" height="600"></canvas>
+            <canvas id="swerve-canvas" width="800" height="800"></canvas>
         </section>
 
         <section class="control-panel">
@@ -25,18 +198,18 @@
             <fieldset>
                 <legend>Translation &amp; Rotation</legend>
 
-                <div class="control-group">
-                    <label for="vx-slider">Strafe Left/Right (pixels/s)</label>
-                    <input type="range" id="vx-slider" min="-300" max="300" step="10" value="0">
-                    <output id="vx-value">0</output>
-                </div>
-
                 <div class="control-group">
                     <label for="vy-slider">Move Forward/Backward (pixels/s)</label>
                     <input type="range" id="vy-slider" min="-300" max="300" step="10" value="0">
                     <output id="vy-value">0</output>
                 </div>
 
+                <div class="control-group">
+                    <label for="vx-slider">Strafe Left/Right (pixels/s)</label>
+                    <input type="range" id="vx-slider" min="-300" max="300" step="10" value="0">
+                    <output id="vx-value">0</output>
+                </div>
+
                 <div class="control-group">
                     <label for="omega-slider">Rotation (rad/s)</label>
                     <input type="range" id="omega-slider" min="-3" max="3" step="0.1" value="0">
@@ -51,7 +224,7 @@
 
                 <div class="control-group">
                     <label for="max-speed-slider">Max Module Speed (pixels/s)</label>
-                    <input type="range" id="max-speed-slider" min="1" max="300" step="10" value="150">
+                    <input type="range" id="max-speed-slider" min="200" max="1000" step="10" value="400">
                     <output id="max-speed-value">0</output>
                 </div>
             </fieldset>
@@ -67,6 +240,9 @@
                     <button id="preset-4rect" type="button">4-Wheel Rectangle</button>
                     <button id="preset-6wheel" type="button">6-Wheel Hexagon</button>
                     <button id="preset-8wheel" type="button">8-Wheel Octagon</button>
+                    <button id="preset-8square" type="button">8-Wheel Square</button>
+                    <button id="preset-12hex" type="button">12-Wheel Hexagon</button>
+                    <button id="preset-16oct" type="button">16-Wheel Octogon</button>
                 </div>
             </fieldset>
             <fieldset>
@@ -78,6 +254,7 @@
                 </div>
 
                 <button id="generate-inputs-btn" type="button">Generate Position Inputs</button>
+                <button id="delete-inputs-btn" type="button">Remove Position Inputs</button>
 
                 <div id="module-position-inputs" class="position-inputs">
                     <!-- Dynamically generated position inputs will appear here -->
@@ -91,23 +268,18 @@
             <div id="current-config-info" class="config-info">
                 Current Configuration: <strong id="config-name">4-Wheel Rectangle</strong>
                 (<span id="module-count-display">4</span> modules)
+                <br>
+                Gyro Heading: <strong id="gyro-heading-display">0.0°</strong>
             </div>
             <div class="module-grid" id="module-grid">
                 <!-- Dynamically generated module data will appear here -->
             </div>
         </section>
-        <section class="documentation">
+
-            <h2>About This Project</h2>
-            <details>
-                <summary>How To Use</summary>
-            </details>
-            <details>
-                <summary>Explaination of Swerve Kinematics</summary>
-            </details>
-        </section>
     </main>
 
-    <script src="script.js"></script>
+    <script type="module" src="vendor/lucio/graham-scan.mjs"></script>
+    <script type="module" src="script.js"></script>
 </body>
 
 </html>

script.js

@@ -2,6 +2,8 @@
 * BEGIN CLASS DECLARATIONS
 */
 
+import GrahamScan from "./vendor/lucio/graham-scan.mjs";
+
 // 2D vector class to make some of the math easier
 class Vec2D {
     constructor(x, y) {
@@ -28,19 +30,27 @@ class SwerveModule {
         this.name = name;
     }
 
-    calculateState(velocityX, velocityY, turnSpeed) {
+    calculateState(velocityX, velocityY, turnSpeed, heading = 0) {
         // Take the requested speed and turn rate of the robot and calculate
         // speed and angle of this module to achieve it
 
+        // Transform field-relative velocities to robot-relative velocities
+        // by rotating the velocity vector by the negative of the robot's heading
+        const cosHeading = Math.cos(-heading);
+        const sinHeading = Math.sin(-heading);
+
+        const robotVelX = velocityX * cosHeading - velocityY * sinHeading;
+        const robotVelY = velocityX * sinHeading + velocityY * cosHeading;
+
         // Calculate rotation contribution (perpendicular to position vector)
         const rotX = -this.position.y * turnSpeed;
         const rotY = this.position.x * turnSpeed;
 
-        // Combine translation and rotation
+        // Combine translation and rotation (now in robot frame)
-        this.velocity.x = velocityX + rotX;
+        this.velocity.x = robotVelX + rotX;
-        this.velocity.y = velocityY + rotY;
+        this.velocity.y = robotVelY + rotY;
 
-        // Calculate speed and angle
+        // Calculate speed and angle (in robot frame)
         this.speed = this.velocity.magnitude();
         this.angle = this.velocity.angle();
     }
@@ -48,8 +58,14 @@ class SwerveModule {
 
 // Swerve drive class to represent the robot as a whole
 class SwerveDrive {
-    constructor(modulePositionsAndNames) {
+    constructor(modulePositionsAndNames, robotName) {
         this.setModules(modulePositionsAndNames);
+        this.setName(robotName);
+        this.gyroHeading = 0; // Simulated gyro heading in radians
+    }
+
+    setName(robotName) {
+        this.name = robotName;
     }
 
     setModules(modulePositionsAndNames) {
@@ -59,16 +75,30 @@ class SwerveDrive {
         );
     }
 
-    drive(velocityX, velocityY, turnSpeed, maxModuleSpeed) {
+    updateHeading(turnSpeed, deltaTime = 0.01) {
-        // Take in a requested speeds and update every module
+        // Integrate turn speed to update gyro heading
+        // turnSpeed is in radians/second, deltaTime is the time step
+        this.gyroHeading += turnSpeed * deltaTime;
+
+        // Normalize to -PI to PI range
+        while (this.gyroHeading > Math.PI) this.gyroHeading -= 2 * Math.PI;
+        while (this.gyroHeading < -Math.PI) this.gyroHeading += 2 * Math.PI;
+    }
+
+    drive(velocityX, velocityY, turnSpeed, maxModuleSpeed, deltaTime = 0.01) {
+        // Store the requested turn speed for later calculation of actual turn speed
+        this.requestedTurnSpeed = turnSpeed;
+
+        // Take in a requested speeds and update every module (but don't update heading yet)
         this.modules.forEach(module =>
-            module.calculateState(velocityX, velocityY, turnSpeed)
+            module.calculateState(velocityX, velocityY, turnSpeed, this.gyroHeading)
         );
 
         // If any speeds exceed the max speed, normalize down so we don't effect movement direction
         const maxCalculated = Math.max(...this.modules.map(m => m.speed), 0);
+        let scale = 1.0;
         if (maxCalculated > maxModuleSpeed) {
-            const scale = maxModuleSpeed / maxCalculated;
+            scale = maxModuleSpeed / maxCalculated;
             this.modules.forEach(module => {
                 module.velocity.x *= scale;
                 module.velocity.y *= scale;
@@ -76,6 +106,38 @@ class SwerveDrive {
                 module.angle = module.velocity.angle();
             });
         }
+
+        // Update heading with the actual turn speed (scaled if modules were limited)
+        const actualTurnSpeed = turnSpeed * scale;
+        this.updateHeading(actualTurnSpeed, deltaTime);
+        this.actualTurnSpeed = actualTurnSpeed;
+    }
+
+    getActualVelocity() {
+        // Calculate the actual robot velocity from the average of module velocities
+        // This returns the velocity in robot-relative coordinates
+        if (this.modules.length === 0) return new Vec2D(0, 0);
+
+        let sumX = 0;
+        let sumY = 0;
+
+        // Average the module velocities (they're in robot frame)
+        this.modules.forEach(module => {
+            sumX += module.velocity.x;
+            sumY += module.velocity.y;
+        });
+
+        const avgX = sumX / this.modules.length;
+        const avgY = sumY / this.modules.length;
+
+        // Transform back to field-relative coordinates
+        const cosHeading = Math.cos(this.gyroHeading);
+        const sinHeading = Math.sin(this.gyroHeading);
+
+        const fieldVelX = avgX * cosHeading - avgY * sinHeading;
+        const fieldVelY = avgX * sinHeading + avgY * cosHeading;
+
+        return new Vec2D(fieldVelX, fieldVelY);
     }
 }
 
@@ -130,7 +192,7 @@ const PresetConfigs = {
         return modules;
     },
 
-    eightWheel: (size) => {
+    eightWheelOctogon: (size) => {
         const radius = size / 2;
         const modules = [];
         for (let i = 0; i < 8; i++) {
@@ -142,7 +204,64 @@ const PresetConfigs = {
             });
         }
         return modules;
-    }
+    },
+
+    eightWheelSquare: (size) => {
+        const full = size;
+        const half = size / 2;
+        return [
+            { x: full, y: full, name: "Outer FL" },
+            { x: full, y: -full, name: "Outer FR" },
+            { x: -full, y: full, name: "Outer BL" },
+            { x: -full, y: -full, name: "Outer BR" },
+            { x: half, y: half, name: "Inner FL" },
+            { x: half, y: -half, name: "Inner FR" },
+            { x: -half, y: half, name: "Inner BL" },
+            { x: -half, y: -half, name: "Inner BR" }
+        ];
+    },
+
+    twelveWheelHexagon: (size) => {
+        const outerRadius = size;
+        const innerRadius = size / 2;
+        const modules = [];
+        for (let i = 0; i < 6; i++) {
+            const angle = (Math.PI / 2) + (i * Math.PI / 3);
+            modules.push({
+                x: outerRadius * Math.cos(angle),
+                y: outerRadius * Math.sin(angle),
+                name: `Module ${i + 1}`
+            });
+
+            modules.push({
+                x: innerRadius * Math.cos(angle),
+                y: innerRadius * Math.sin(angle),
+                name: `Module ${i + 7}`
+            });
+        }
+        return modules;
+    },
+
+    sixteenWheelOctogon: (size) => {
+        const outerRadius = size;
+        const innerRadius = size / 2;
+        const modules = [];
+        for (let i = 0; i < 8; i++) {
+            const angle = (Math.PI / 2) + (i * Math.PI / 4);
+            modules.push({
+                x: outerRadius * Math.cos(angle),
+                y: outerRadius * Math.sin(angle),
+                name: `Module ${i + 1}`
+            });
+
+            modules.push({
+                x: innerRadius * Math.cos(angle),
+                y: innerRadius * Math.sin(angle),
+                name: `Module ${i + 9}`
+            });
+        }
+        return modules;
+    },
 };
 
 /*
@@ -166,6 +285,7 @@ const maxSpeedOutput = document.getElementById('max-speed-value');
 // Get button elements
 const resetBtn = document.getElementById('reset-btn');
 const generateInputsBtn = document.getElementById('generate-inputs-btn');
+const clearInputsBtn = document.getElementById('delete-inputs-btn');
 const applyCustomBtn = document.getElementById('apply-custom-btn');
 
 // Preset buttons
@@ -175,32 +295,19 @@ const preset4WheelBtn = document.getElementById('preset-4wheel');
 const preset4RectBtn = document.getElementById('preset-4rect');
 const preset6WheelBtn = document.getElementById('preset-6wheel');
 const preset8WheelBtn = document.getElementById('preset-8wheel');
+const preset8SquareBtn = document.getElementById('preset-8square');
+const preset12HexBtn = document.getElementById('preset-12hex');
+const preset16OctBtn = document.getElementById('preset-16oct');
 
 /*
 * END DOM VARIABLES
 * BEGIN LISTENER CODE
 */
 
-
-vxSlider.addEventListener('input', (e) => {
-    vxOutput.textContent = parseFloat(e.target.value);
-});
-vxOutput.textContent = parseFloat(vxSlider.value);
-
-vySlider.addEventListener('input', (e) => {
-    vyOutput.textContent = parseFloat(e.target.value);
-});
-vyOutput.textContent = parseFloat(vySlider.value);
-
-omegaSlider.addEventListener('input', (e) => {
-    omegaOutput.textContent = parseFloat(e.target.value);
-});
-omegaOutput.textContent = parseFloat(omegaSlider.value);
-
 maxSpeedSlider.addEventListener('input', (e) => {
-    maxSpeedOutput.textContent = parseFloat(e.target.value);
+    maxSpeedOutput.textContent = e.target.value;
 });
-maxSpeedOutput.textContent = parseFloat(maxSpeedSlider.value);
+maxSpeedOutput.textContent = maxSpeedSlider.value;
 
 resetBtn.addEventListener('click', (e) => {
     vxSlider.value = 0;
@@ -216,35 +323,201 @@ resetBtn.addEventListener('click', (e) => {
 preset2WheelBtn.addEventListener('click', () => {
     const positions = PresetConfigs.twoWheel(robotSize);
     robot.setModules(positions);
+    robot.setName("2-Wheel Differential");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 preset3WheelBtn.addEventListener('click', () => {
     const positions = PresetConfigs.threeWheel(robotSize);
     robot.setModules(positions);
+    robot.setName("3-Wheel Triangle");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 preset4WheelBtn.addEventListener('click', () => {
     const positions = PresetConfigs.fourWheelSquare(robotSize);
     robot.setModules(positions);
+    robot.setName("4-Wheel Square");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 preset4RectBtn.addEventListener('click', () => {
     const positions = PresetConfigs.fourWheelRectangle(robotSize);
     robot.setModules(positions);
+    robot.setName("4-Wheel Rectangle");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 preset6WheelBtn.addEventListener('click', () => {
     const positions = PresetConfigs.sixWheel(robotSize);
     robot.setModules(positions);
+    robot.setName("6-Wheel Hexagon");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 preset8WheelBtn.addEventListener('click', () => {
-    const positions = PresetConfigs.eightWheel(robotSize);
+    const positions = PresetConfigs.eightWheelOctogon(robotSize);
     robot.setModules(positions);
+    robot.setName("8-Wheel Octogon");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
+});
+
+preset8SquareBtn.addEventListener('click', () => {
+    const positions = PresetConfigs.eightWheelSquare(robotSize);
+    robot.setModules(positions);
+    robot.setName("8-Wheel Square");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
+});
+
+preset12HexBtn.addEventListener('click', () => {
+    const positions = PresetConfigs.twelveWheelHexagon(robotSize);
+    robot.setModules(positions);
+    robot.setName("12-Wheel Hexagon");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
+});
+
+preset16OctBtn.addEventListener('click', () => {
+    const positions = PresetConfigs.sixteenWheelOctogon(robotSize);
+    robot.setModules(positions);
+    robot.setName("16-Wheel Octogon");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
+});
+
+
+
+generateInputsBtn.addEventListener('click', () => {
+    const count = parseInt(moduleCountInput.value);
+
+    if (isNaN(count) || count < 2) {
+        alert('Please enter a valid number of modules above or equal to 2.');
+        return;
+    }
+    generateModuleInputs(count);
+    applyCustomBtn.style.display = 'block';
+});
+
+clearInputsBtn.addEventListener('click', () => {
+    generateModuleInputs(0);
+    applyCustomBtn.style.display = 'none';
+});
+
+applyCustomBtn.addEventListener('click', () => {
+    const container = document.getElementById('module-position-inputs');
+    const moduleElements = container.childNodes;
+
+    const customModules = [];
+    for (let i = 0; i < moduleElements.length; i++) {
+        const xInput = document.getElementById(`module-${i}-x`);
+        const yInput = document.getElementById(`module-${i}-y`);
+        const nameInput = document.getElementById(`module-${i}-name`);
+
+        const x = parseFloat(xInput.value);
+        const y = parseFloat(yInput.value);
+        const name = nameInput.value.trim();
+
+        customModules.push({ x, y, name });
+    }
+
+    robot.setModules(customModules);
+    robot.setName("Custom Configuration");
+    createModuleDisplays(robot);
+    updateModuleDisplays(robot);
 });
 
 /*
 * END LISTENER CODE
+* BEGIN DYNAMIC DOM FUNCTIONS
+*/
+
+function generateModuleInputs(count) {
+    const container = document.getElementById('module-position-inputs');
+    container.innerHTML = ''; // Clear existing inputs
+
+    for (let i = 0; i < count; i++) {
+        const moduleFieldset = document.createElement('fieldset');
+        moduleFieldset.className = 'module-input-group';
+        moduleFieldset.innerHTML = `
+        <legend>Module ${i + 1}</legend>
+
+        <div class="control-group">
+            <label for="module-${i}-name">Module Name</label>
+            <input type="text" id="module-${i}-name" value="Module ${i + 1}" required>
+        </div>
+        <div class="control-group">
+            <label for="module-${i}-x">X Position (pixels)</label>
+            <input type="number" id="module-${i}-x" step="1" value="0" required>
+        </div>
+        <div class="control-group">
+            <label for="module-${i}-y">Y Position (pixels)</label>
+            <input type="number" id="module-${i}-y" step="0.1" value="0" required>
+        </div>
+        `;
+        container.appendChild(moduleFieldset);
+    }
+}
+
+function createModuleDisplays(robot) {
+    const grid = document.getElementById('module-grid');
+    grid.innerHTML = ''; // Delete any pre-existing elements before creating new ones
+
+    const modules = robot.modules;
+    modules.forEach((module, i) => {
+        const article = document.createElement('article');
+        article.className = 'module-display';
+        const name = module.name;
+
+        article.innerHTML = `
+            <h3>${name}</h3>
+            <div class="readout">
+                <span class="label">Angle:</span>
+                <span id="module-${i}-angle" class="value">0.0°</span>
+            </div>
+            <div class="readout">
+                <span class="label">Speed:</span>
+                <span id="module-${i}-speed" class="value">0.00 pixels/s</span>
+            </div>
+        `;
+        grid.appendChild(article);
+    });
+}
+
+function updateModuleDisplays(robot) {
+    const configName = document.getElementById('config-name');
+    configName.textContent = robot.name;
+    const moduleCount = document.getElementById('module-count-display');
+    moduleCount.textContent = robot.modules.length;
+
+    // Update gyro heading display
+    const gyroHeadingDisplay = document.getElementById('gyro-heading-display');
+    if (gyroHeadingDisplay) {
+        const headingDeg = (robot.gyroHeading * 180 / Math.PI).toFixed(1);
+        gyroHeadingDisplay.textContent = `${headingDeg}°`;
+    }
+
+    const modules = robot.modules;
+    modules.forEach((module, i) => {
+        const angleElement = document.getElementById(`module-${i}-angle`);
+        const speedElement = document.getElementById(`module-${i}-speed`);
+
+        if (angleElement && speedElement) {
+            const angleDeg = (module.angle * 180 / Math.PI).toFixed(1);
+            angleElement.textContent = `${angleDeg}°`;
+            speedElement.textContent = `${module.speed.toFixed(2)} pixels/s`;
+        }
+    });
+}
+
+/*
+* END DYNAMIC DOM FUNCTIONS
 * BEGIN ANIMATION CODE
 */
 
@@ -255,12 +528,9 @@ const ctx = canvas.getContext('2d');
 // Get CSS variables for use in canvas
 const rootStyles = getComputedStyle(document.documentElement);
 
-function drawGrid(ctx, sideLength, gridSquareSize, xOffset, yOffset, rotation) {
+function drawGrid(ctx, sideLength, gridSquareSize, xOffset, yOffset) {
     ctx.save();
 
-    // Apply rotation transform
-    ctx.rotate(-rotation);
-
     ctx.strokeStyle = rootStyles.getPropertyValue('--grid-color');
     ctx.lineWidth = 1;
     const startX = (-sideLength / 2) - xOffset;
@@ -324,35 +594,54 @@ function drawModule(ctx, module) {
     ctx.restore();
 }
 
-function drawRobot(ctx, robot) {
+
+function drawRobot(ctx, robot, heading) {
+    ctx.save(); // Save current state before rotation
+
+    ctx.rotate(heading);
+
     ctx.strokeStyle = rootStyles.getPropertyValue('--robot-frame-color')
     ctx.fillStyle = rootStyles.getPropertyValue('--robot-fill-color');
     ctx.lineWidth = 4;
 
-    const modules = robot.modules.sort((a, b) => Math.atan2(a.position.y, a.position.x) - Math.atan2(b.position.y, b.position.x));
+    let hull = [];
+    // Get the convex hull of the robot if there are more than 3 modules
+    if (robot.modules.length > 3) {
+        const grahamScan = new GrahamScan();
+        grahamScan.setPoints(robot.modules.map((module) => [module.position.x, module.position.y]));
+        hull = grahamScan.getHull();
+    } else {
+        hull = robot.modules.map((module) => [module.position.x, module.position.y]);
+    }
 
+
+    // Draw the convex hull as the robot frame
     ctx.beginPath();
-    ctx.moveTo(modules[0].position.x, modules[0].position.y);
+    ctx.moveTo(hull[0][0], hull[0][1]);
-    for (let i = 1; i < modules.length; i++) {
+    for (let i = 1; i < hull.length; i++) {
-        ctx.lineTo(modules[i].position.x, modules[i].position.y);
+        ctx.lineTo(hull[i][0], hull[i][1]);
     }
     ctx.closePath();
     ctx.fill();
     ctx.stroke();
 
-    modules.forEach(module => drawModule(ctx, module));
+    // Draw all modules (not just hull modules)
+    robot.modules.forEach(module => drawModule(ctx, module, heading));
+
+    ctx.restore(); // Restore to remove rotation
 }
 
 
 // Initialize Variables
 const robotSize = 200;
-const robot = new SwerveDrive(PresetConfigs.fourWheelSquare(robotSize));
+const defaultModulePositions = PresetConfigs.fourWheelSquare(robotSize);
+const robot = new SwerveDrive(defaultModulePositions, "4-Wheel Square");
+createModuleDisplays(robot);
 let xSpeed = 0;
 let ySpeed = 0;
 let turnSpeed = -1;
-let robotRotation = 0; // Track cumulative robot rotation for grid display
 
-let gridSquareSize = 25;
+let gridSquareSize = 50;
 let xGridOffset = 0;
 let yGridOffset = 0;
 robot.drive(xSpeed, ySpeed, 0, 500);
@@ -368,26 +657,31 @@ function animate() {
     ySpeed = -parseFloat(vySlider.value);
     turnSpeed = parseFloat(omegaSlider.value);
 
-    // Animate the grid with robot movement
+    // Update module states before drawing the robot
-    let offsetSpeedDivisor = (100 - gridSquareSize <= 0 ? 1 : 100 - gridSquareSize);
+    // The drive() method will update the gyroHeading internally
-    robotRotation += turnSpeed * 0.01; // Scale factor for reasonable rotation speed
+    robot.drive(xSpeed, ySpeed, turnSpeed, parseFloat(maxSpeedSlider.value));
+    updateModuleDisplays(robot);
 
-    // Convert robot velocities to world velocities for grid movement
+    // Get the actual robot velocity (after scaling to max module speed) for grid animation
-    const cosRot = Math.cos(robotRotation);
+    const actualVelocity = robot.getActualVelocity();
-    const sinRot = Math.sin(robotRotation);
+
-    const worldVx = xSpeed * cosRot - ySpeed * sinRot;
+
-    const worldVy = xSpeed * sinRot + ySpeed * cosRot;
+    // Update control outputs with actual speeds
+    vxOutput.textContent = `Requested: ${vxSlider.value} | Actual: ${actualVelocity.x.toFixed(2)}`;
+    vyOutput.textContent = `Requested: ${vySlider.value} | Actual: ${-actualVelocity.y.toFixed(2)}`;
+    omegaOutput.textContent = `Requested: ${omegaSlider.value} | Actual: ${robot.actualTurnSpeed.toFixed(2)}`;
+
+    // Animate the grid
+    let offsetSpeedDivisor = (100 - gridSquareSize <= 0 ? 1 : 100 - gridSquareSize);
 
     // Update grid offsets based on robot movement
-    xGridOffset = (xGridOffset + (worldVx / offsetSpeedDivisor)) % gridSquareSize;
+    xGridOffset = (xGridOffset + (actualVelocity.x / offsetSpeedDivisor)) % gridSquareSize;
-    yGridOffset = (yGridOffset + (worldVy / offsetSpeedDivisor)) % gridSquareSize;
+    yGridOffset = (yGridOffset + (actualVelocity.y / offsetSpeedDivisor)) % gridSquareSize;
 
     // Draw the robot and it's movement. Grid should be oversized so movement
     // doesn't find the edge of the grid
-    drawGrid(ctx, canvas.width * 2, gridSquareSize, xGridOffset, yGridOffset, robotRotation);
+    drawGrid(ctx, canvas.width * 2, gridSquareSize, xGridOffset, yGridOffset);
-    drawRobot(ctx, robot);
+    drawRobot(ctx, robot, robot.gyroHeading);
-
-    robot.drive(xSpeed, ySpeed, turnSpeed, parseFloat(maxSpeedSlider.value));
 
     // Do it all over again
     ctx.restore();

styles.css

@@ -238,7 +238,7 @@ tr:hover {
 
 .visualization-area {
   grid-column: 1 / 2;
-  grid-row: 1 / 3;
+  grid-row: 2 / 4;
 }
 
 #swerve-canvas {
@@ -252,22 +252,22 @@ tr:hover {
 
 .controls-panel {
   grid-column: 1 / 2;
-  grid-row: 2 / 3;
+  grid-row: 3 / 4;
 }
 
 .config-panel {
   grid-column: 2 / 3;
-  grid-row: 1 / 2;
+  grid-row: 2 / 3;
 }
 
 .module-states {
   grid-column: 2 / 3;
-  grid-row: 2 / 3;
+  grid-row: 3 / 4;
 }
 
 .documentation {
   grid-column: 1 / 3;
-  grid-row: 4 / 5;
+  grid-row: 1 / 2;
 }
 
 fieldset {
@@ -297,3 +297,68 @@ button:hover {
   transform: translateY(-2px);
   box-shadow: var(--shadow);
 }
+
+/* Module States Grid */
+.module-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: var(--spacing-small);
+  margin-top: var(--spacing-small);
+}
+
+.module-card {
+  background-color: var(--background-dark);
+  border: 2px solid var(--border-color);
+  border-radius: var(--border-radius-sm);
+  padding: var(--spacing-small);
+  transition: all 0.3s ease;
+}
+
+.config-info {
+  background-color: var(--background-dark);
+  border: 1px solid var(--border-color);
+  border-radius: var(--border-radius-sm);
+  padding: var(--spacing-small);
+  margin-bottom: var(--spacing-small);
+  color: var(--text-secondary);
+}
+
+.control-group {
+  margin-bottom: var(--spacing-small);
+  display: flex;
+  flex-direction: column;
+}
+
+.position-inputs {
+  max-height: 400px;
+  overflow-y: auto;
+  padding: var(--spacing-small);
+  background-color: var(--background-dark);
+  border-radius: var(--border-radius-sm);
+  margin-top: var(--spacing-small);
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+}
+
+.preset-buttons {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+}
+
+.module-display {
+  background-color: var(--background-dark);
+  border: 2px solid var(--border-color);
+  border-radius: var(--border-radius-sm);
+  padding: var(--spacing-small);
+}
+
+.readout {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: calc(var(--spacing-small) / 2);
+}
+
+.readout .value {
+  color: var(--text-light);
+  font-weight: bold;
+}

vendor/lucio/graham-scan.mjs

@@ -0,0 +1,148 @@
+/*
+This module is not by me, it was found at the following github with MIT license:
+https://github.com/luciopaiva/graham-scan/tree/master
+=========
+Copyright 2020 Lucio Paiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+=========
+*/
+
+
+const X = 0;
+const Y = 1;
+const REMOVED = -1;
+
+export default class GrahamScan {
+
+    constructor() {
+        /** @type {[Number, Number][]} */
+        this.points = [];
+    }
+
+    clear() {
+        this.points = [];
+    }
+
+    getPoints() {
+        return this.points;
+    }
+
+    setPoints(points) {
+        this.points = points.slice();  // copy
+    }
+
+    addPoint(point) {
+        this.points.push(point);
+    }
+
+    /**
+     * Returns the smallest convex hull of a given set of points. Runs in O(n log n).
+     *
+     * @return {[Number, Number][]}
+     */
+    getHull() {
+        const pivot = this.preparePivotPoint();
+
+        let indexes = Array.from(this.points, (point, i) => i);
+        const angles = Array.from(this.points, (point) => this.getAngle(pivot, point));
+        const distances = Array.from(this.points, (point) => this.euclideanDistanceSquared(pivot, point));
+
+        // sort by angle and distance
+        indexes.sort((i, j) => {
+            const angleA = angles[i];
+            const angleB = angles[j];
+            if (angleA === angleB) {
+                const distanceA = distances[i];
+                const distanceB = distances[j];
+                return distanceA - distanceB;
+            }
+            return angleA - angleB;
+        });
+
+        // remove points with repeated angle (but never the pivot, so start from i=1)
+        for (let i = 1; i < indexes.length - 1; i++) {
+            if (angles[indexes[i]] === angles[indexes[i + 1]]) {  // next one has same angle and is farther
+                indexes[i] = REMOVED;  // remove it logically to avoid O(n) operation to physically remove it
+            }
+        }
+
+        const hull = [];
+        for (let i = 0; i < indexes.length; i++) {
+            const index = indexes[i];
+            const point = this.points[index];
+
+            if (index !== REMOVED) {
+                if (hull.length < 3) {
+                    hull.push(point);
+                } else {
+                    while (this.checkOrientation(hull[hull.length - 2], hull[hull.length - 1], point) > 0) {
+                        hull.pop();
+                    }
+                    hull.push(point);
+                }
+            }
+        }
+
+        return hull.length < 3 ? [] : hull;
+    }
+
+    /**
+     * Check the orientation of 3 points in the order given.
+     *
+     * It works by comparing the slope of P1->P2 vs P2->P3. If P1->P2 > P2->P3, orientation is clockwise; if
+     * P1->P2 < P2->P3, counter-clockwise. If P1->P2 == P2->P3, points are co-linear.
+     *
+     * @param {[Number, Number]} p1
+     * @param {[Number, Number]} p2
+     * @param {[Number, Number]} p3
+     * @return {Number} positive if orientation is clockwise, negative if counter-clockwise, 0 if co-linear
+     */
+    checkOrientation(p1, p2, p3) {
+        return (p2[Y] - p1[Y]) * (p3[X] - p2[X]) - (p3[Y] - p2[Y]) * (p2[X] - p1[X]);
+    }
+
+    /**
+     * @private
+     * @param {[Number, Number]} a
+     * @param {[Number, Number]} b
+     * @return Number
+     */
+    getAngle(a, b) {
+        return Math.atan2(b[Y] - a[Y], b[X] - a[X]);
+    }
+
+    /**
+     * @private
+     * @param {[Number, Number]} p1
+     * @param {[Number, Number]} p2
+     * @return {Number}
+     */
+    euclideanDistanceSquared(p1, p2) {
+        const a = p2[X] - p1[X];
+        const b = p2[Y] - p1[Y];
+        return a * a + b * b;
+    }
+
+    /**
+     * @private
+     * @return {[Number, Number]}
+     */
+    preparePivotPoint() {
+        let pivot = this.points[0];
+        let pivotIndex = 0;
+        for (let i = 1; i < this.points.length; i++) {
+            const point = this.points[i];
+            if (point[Y] < pivot[Y] || point[Y] === pivot[Y] && point[X] < pivot[X]) {
+                pivot = point;
+                pivotIndex = i;
+            }
+        }
+        return pivot;
+    }
+}