Project 16: Vector Geometry and 2D Graphics Toolkit

A self-contained deep-dive from the canonical Math from Foundations to Machine Learning curriculum.

  • Difficulty: Intermediate-Advanced
  • Time: 12-20 hours
  • Language: Python (alternatives: C++, Julia, JavaScript)
  • Prerequisites: Projects 5 and 15
  • Merged from: HS P16; ML-Found P01

What You Will Build

Build a dimension-safe vector library and interactive 2D graphics playground. Begin with a unit-circle checkpoint that converts degrees/radians and visualizes sine/cosine as coordinates. Implement vector addition, subtraction, scalar multiplication, magnitude, normalization, dot product, angle, projection, and parallel/orthogonal decomposition. Then represent polygon vertices as vectors and let the user translate, rotate, scale, and steer shapes. Draw original and transformed vectors, projection components, angles, basis axes, and verification diagnostics so every operation has geometric meaning.

Real World Outcome

The CLI can explain the angle and projection between two vectors and show their decomposition. The graphics window displays a triangle or spaceship that rotates around a chosen pivot, moves along its heading, and scales predictably from keyboard controls. A side panel reports norms, dot products, radians/degrees, and invariant checks such as orthogonal residual near zero and length preservation under rotation.

Core Question

How do coordinates, trigonometry, and dot products turn abstract arrows into measurable geometry and controllable on-screen motion?

Concepts You Must Understand First

  1. Radians and unit circle: (cos θ, sin θ) defines direction; radians connect angle to arc length.
  2. Vectors versus points: both use coordinates, but vectors represent displacement and obey vector operations.
  3. Norm and normalization: magnitude measures length; unit vectors preserve direction only for nonzero inputs.
  4. Dot product: u·v = |u||v|cos θ, connecting algebra to angle and orthogonality. See Orland, Math for Programmers, Chapters 2 and 5.
  5. Projection and rotation: projection extracts the component along a direction; 2D rotation combines sine and cosine. See 3Blue1Brown, Essence of Linear Algebra, Episode 3.

Build Milestones

  1. Build degree/radian conversion and an interactive unit-circle visualization with quadrant tests.
  2. Implement vector arithmetic, norms, normalization, dot products, angles, and dimension checks.
  3. Add projection/decomposition and verify orthogonality and reconstruction invariants.
  4. Render shapes from vertex vectors and support translation, rotation, scaling, and pivot choice.
  5. Add interactive controls, numeric diagnostics, and property tests for geometric identities.

Hints in Layers

  1. Clamp the computed cosine to [-1, 1] before acos to absorb tiny floating-point drift.
  2. Projection of u onto v is (u·v / v·v)v; reject a zero v explicitly.
  3. Apply transformations to immutable model coordinates, then render; repeatedly transforming already-rounded screen points accumulates distortion.

Common Pitfalls and Debugging

  • Symptom: rotations go the wrong way or by the wrong amount. Cause: degrees were passed to radian-based trig or screen y-axis orientation was ignored. Fix: centralize conversion and document coordinates.
  • Symptom: normalization produces NaN. Cause: a zero vector was divided by its magnitude. Fix: return a clear domain error.
  • Symptom: projections do not reconstruct the original vector. Cause: denominator or vector direction is wrong. Fix: assert parallel + orthogonal ≈ original and orthogonal·v ≈ 0.

Definition of Done

  • Unit-circle controls correctly connect angles, radians, sine, and cosine.
  • Vector operations enforce dimensions and handle zero-vector domains.
  • Projection/decomposition pass reconstruction and orthogonality checks.
  • Shapes translate, rotate, and scale around documented pivots.
  • Rotation preserves length within tolerance and deterministic tests cover quadrants.
  • Visuals and numeric diagnostics tell the same geometric story.

Previous: Project 15 · Complete learning path · Next: Project 17