WakeKeeper — Live Sailing & Fleet Navigation iOS App

/*
 ===============================================================================
 SAMPLE 01 — DOUGLAS-PEUCKER POLYLINE SIMPLIFICATION
 ===============================================================================
 MODULE:         GPS Track Simplification (Data Layer)
 ARCHITECTURE:   Pure, recursive algorithm hosted inside `UserAccountActor`
                 (a Swift actor that owns the live vessel-location history).
 PURPOSE:        Reduces a dense GPS polyline to its shape-preserving subset
                 using the Ramer–Douglas–Peucker algorithm. Points whose
                 perpendicular distance from the chord between the current
                 anchor points falls below `epsilon` are discarded; otherwise
                 the worst offender becomes a new anchor and both halves are
                 simplified recursively.
 DATA FLOW:      Raw [SendableLocation] stream (1 fix / second)
                   -> fixed-size segments (see sample 02)
                   -> douglasPeucker(points:epsilon:)   // this file
                   -> simplified segment persisted as vessel history
 WHY IT MATTERS: Naïve thinning (every Nth point) destroys curves and turns.
                 Douglas-Peucker keeps exactly the points that define the
                 vessel's actual track, so the map polyline stays faithful
                 while storage and render cost drop by an order of magnitude.
 NOTES:          Epsilon is expressed in degrees of lat/lon
                 (~0.0001° ≈ 11 m at the equator). Perpendicular distance
                 uses a planar approximation, accurate enough for the small
                 deltas typical between consecutive vessel fixes.
 SOURCE:         WakeKeeper/Data/UserAccountActor.swift
 ===============================================================================
 */

import Foundation

// MARK: - Context & Dependencies
// In the app, `SendableLocation` is a Sendable/Codable value-type wrapper
// around CoreLocation's `CLLocation` (see sample 06). Only the fields used
// by the algorithm are reproduced here.
struct SendableLocation {
    let latitude: Double
    let longitude: Double
}

// The actor shell exists only to show where these methods live in the app;
// the algorithm itself is stateless and could just as easily be a free function.
actor UserAccountActor { }

extension UserAccountActor {

    /// Recursively simplifies a polyline, keeping only points that deviate
    /// from the straight line between anchors by more than `epsilon`.
    private func douglasPeucker(points: [SendableLocation], epsilon: Double) -> [SendableLocation] {
        guard points.count > 2 else { return points }
        var maxDistance = 0.0
        var index = 0
        let start = points.first!
        let end = points.last!
        for i in 1..<(points.count - 1) {
            let distance = perpendicularDistance(from: points[i], lineStart: start, lineEnd: end)
            if distance > maxDistance {
                index = i
                maxDistance = distance
            }
        }
        if maxDistance > epsilon {
            let leftBatch = douglasPeucker(points: Array(points[0...index]), epsilon: epsilon)
            let rightBatch = douglasPeucker(points: Array(points[index..<points.count]), epsilon: epsilon)
            return leftBatch.dropLast() + rightBatch   // dropLast: the shared pivot point
        } else {
            return [points.first!, points.last!]
        }
    }

    /// Perpendicular distance from point `p` to the line through `s` and `e`,
    /// using the 2D cross-product magnitude over the chord length.
    private func perpendicularDistance(from p: SendableLocation, lineStart s: SendableLocation, lineEnd e: SendableLocation) -> Double {
        let dx = e.longitude - s.longitude
        let dy = e.latitude - s.latitude
        let mag = sqrt(dx*dx + dy*dy)
        if mag == 0 { return 0 } // Start and end are the same point
        return abs(dy * p.longitude - dx * p.latitude + e.longitude * s.latitude - e.latitude * s.longitude) / mag
    }
}

/*
 ===============================================================================
 SAMPLE 02 — INCREMENTAL GPS TRACK OPTIMIZATION PIPELINE
 ===============================================================================
 MODULE:         Live Vessel History (Data Layer)
 ARCHITECTURE:   Stateful pipeline inside `UserAccountActor`; all state is
                 actor-isolated so the location callbacks (which can arrive
                 off the main run loop) never race.
 PURPOSE:        Textbook Douglas-Peucker (sample 01) only works on a finished
                 polyline. This pipeline applies it *incrementally* to a live
                 GPS stream: locations accumulate into fixed-size "tail"
                 segments, and once 5 un-optimized segments are full, they are
                 flattened, simplified, and replaced by a single level-01
                 segment — while newer locations keep arriving untouched.
 DATA FLOW:      CLLocation (1 Hz)
                   -> appendHistory            (segment bookkeeping)
                   -> startNewActiveTail       (start a new 60-point segment,
                                                carrying the last point across
                                                the boundary for continuity)
                   -> optimizeVesselHistory    (when 5 segments are full:
                                                flatten -> Douglas-Peucker ->
                                                mark .level01)
                   -> get(speedPoints:)        (derive min/max/average speed
                                                gradient stops that color the
                                                simplified polyline by speed)
 STATE MODEL:    [MyVesselState] is a list of segments; each segment is either
                 `.notOptimized` (raw) or `.level01` (simplified). Finalized
                 segments are never revisited — amortized cost stays O(n).
 SOURCE:         WakeKeeper/Data/UserAccountActor.swift
 ===============================================================================
 */

import Foundation

// MARK: - Context & Dependencies
struct SendableLocation {                    // see sample 06
    let latitude: Double
    let longitude: Double
    let speed: Double
}
struct SpeedPoint {                          // one stop of the speed-colored polyline
    let speed: Double
    let progress: Double                     // 0...1 along the segment
}
struct MyVesselState {                       // one 60-point segment of track history
    var activeTail: [SendableLocation]
    var speedPoints: [SpeedPoint]
    var optimizeLevel: OptimizeLevel = .notOptimized
    enum OptimizeLevel { case notOptimized, level01 }
}

actor UserAccountActor {                     // stub shell: real actor carries more state
    private var myVesselHistory: [MyVesselState] = []
    private var itemCounter = 0
    private let itemsPerArray = 60           // points per segment
    private let maxArrays = 5                // un-optimized segments before triggering
    private let currentLocation = SendableLocation(latitude: 0, longitude: 0, speed: 0)

    // Sample 01 — referenced here; full implementation in
    // 01_douglas_peucker_polyline_simplification.swift
    private func douglasPeucker(points: [SendableLocation], epsilon: Double) -> [SendableLocation] { points }

    private func appendHistory(_ location: SendableLocation?, vesselHistory: [MyVesselState]) -> [MyVesselState] {
        guard let location else { return myVesselHistory }
        defer { itemCounter += 1 }
        var myVesselHistory = vesselHistory
        if let newHistoryTail = startNewActiveTail(history: myVesselHistory) {
            myVesselHistory = newHistoryTail
        }

        let i = myVesselHistory.endIndex - 1
        myVesselHistory[i].activeTail.append(location)
        myVesselHistory[i].speedPoints.append(SpeedPoint(speed: location.speed, progress: Double(myVesselHistory.last?.speedPoints.count ?? 0) / Double(itemsPerArray)))
        if let optimizedHistory = optimizeVesselHistory(myVesselHistory: myVesselHistory) {
            return optimizedHistory
        }
        return myVesselHistory
    }

    /// Starts a new 60-point segment when the current tail is full. The last
    /// point of the previous tail seeds the new one, so the simplified
    /// polyline never shows a gap at segment boundaries.
    private func startNewActiveTail(history: [MyVesselState], force: Bool = false) -> [MyVesselState]? {
        var myVesselHistory = history
        let activeTail: [SendableLocation] = {
            if let lastTailSpeed = history.last?.activeTail.last {
                return [lastTailSpeed]
            } else {
                if force,
                   let last = history.last,
                   last.activeTail.isEmpty && history.count >= 2 {
                    let secondFromLast = history[history.count - 2]
                    if let lastLocation = secondFromLast.activeTail.last {
                        return [lastLocation]
                    }
                }
            }
            return []
        }()
        if force || (myVesselHistory.isEmpty || (myVesselHistory.last?.activeTail.count ?? 0) % itemsPerArray == 0) {
            myVesselHistory.append(
                MyVesselState(activeTail: activeTail,
                              speedPoints: [
                    SpeedPoint(speed: myVesselHistory.last?.speedPoints.last?.speed ?? currentLocation.speed, progress: 0)
                ])
            )
            return myVesselHistory
        }
        return nil
    }

    /// Folds 5 full, un-optimized segments into one simplified `.level01`
    /// segment. Epsilon ≈ 0.00005° (~5.5 m).
    private func optimizeVesselHistory(myVesselHistory: [MyVesselState], force: Bool = false) -> [MyVesselState]? {
        let notOptimized = myVesselHistory.filter({ $0.optimizeLevel == .notOptimized })
        if force || (notOptimized.count >= maxArrays && (notOptimized.last?.activeTail.count ?? 0) >= itemsPerArray) {
            // 1. Flatten the unoptimized segments into one sequence
            let tail = notOptimized.flatMap { $0.activeTail.map { $0 } }

            // 2. Extract min, max, start and average speeds for coloring
            let points: [SpeedPoint] = notOptimized.flatMap({ $0.speedPoints.map({ $0 }) })
            let newPoints = get(speedPoints: points, previousSpeed: myVesselHistory.filter({ $0.optimizeLevel == .level01 }).last?.speedPoints.last?.speed)
            // 3. Run the algorithm. Epsilon is in degrees (~0.0001 is roughly 11 meters)
            let optimizedPoints = douglasPeucker(points: tail, epsilon: 0.00005)
            // 4. Create the new optimized state
            var optimizedState = MyVesselState(
                activeTail: optimizedPoints,
                speedPoints: newPoints
            )
            optimizedState.optimizeLevel = .level01
            // 5. Update history: keep finalized history + new optimized segment
            let finalizedHistory = myVesselHistory.dropLast(notOptimized.count)
            return Array(finalizedHistory) + [optimizedState]
        }
        return nil
    }

    /// Derives four ordered gradient stops (start / max / min / average speed)
    /// that the map layer uses to color the polyline by vessel speed. Stops
    /// are nudged away from the edges (`minMaxColorOffset`) so colors remain
    /// visible instead of collapsing to a single point.
    private func get(speedPoints: [SpeedPoint], previousSpeed: Double?) -> [SpeedPoint] {
        let minMaxColorOffset: CGFloat = 0.2
        let previousSpeed = previousSpeed ?? speedPoints.first?.speed ?? 0
        let maxSpeedPoint = speedPoints.max(by: { $0.speed < $1.speed })
        let minSpeedPoint = speedPoints.min(by: { $0.speed < $1.speed })
        let averagesSpeed = speedPoints.map({ $0.speed }).reduce(0, +) / Double(speedPoints.count)
        let maxProgress = maxSpeedPoint?.progress ?? 0.33
        let minProgress = minSpeedPoint?.progress ?? 0.66
        let sortedSpeedPoints =  [
            SpeedPoint(speed: previousSpeed, progress: 0.0),
            SpeedPoint(speed: maxSpeedPoint?.speed ?? 0, progress: maxProgress < minMaxColorOffset ? maxProgress + minMaxColorOffset : maxProgress > 0.9 ? maxProgress - minMaxColorOffset : maxProgress),
            SpeedPoint(speed: minSpeedPoint?.speed ?? 0, progress: minProgress < minMaxColorOffset ? minProgress + minMaxColorOffset : minProgress > 0.9 ? minProgress - minMaxColorOffset : minProgress),
            SpeedPoint(speed: averagesSpeed, progress: 1.0)
        ].sorted(by: { $0.progress < $1.progress })
        return sortedSpeedPoints
    }
}

/*
 ===============================================================================
 SAMPLE 03 — ADAPTIVE CHART TICK CALCULATOR
 ===============================================================================
 MODULE:         Trip Statistics (Data Layer)
 ARCHITECTURE:   Pure function on `UserAccountActor`, called when trip metrics
                 are recalculated.
 PURPOSE:        Swift Charts needs explicit x-axis tick values to achieve a
                 custom look. This picks a "human" tick step (5 s … 1 day) from
                 a tiered ladder based on the total span of the data, then
                 strides ticks aligned to multiples of that step — so labels
                 land on round times regardless of when the trip started.
 DATA FLOW:      [SpeedItem] (time relative to trip start)
                   -> span = last - first
                   -> step  = first ladder tier that covers the span
                   -> stride(from: ceil-aligned start, through: floor-aligned
                      end, by: step)
                   -> smartTicks: [TimeInterval] -> Chart AxisMarks
 TECHNIQUES:     Chained ternary ladder as a compact decision table;
                 ceil/floor alignment of an arithmetic grid via stride.
 SOURCE:         WakeKeeper/Data/UserAccountActor.swift
 ===============================================================================
 */

import Foundation

// MARK: - Context & Dependencies
// `SpeedItem` is one point of the speed-over-time series; `timefromNow` is
// seconds elapsed since the trip started.
struct SpeedItem {
    let speed: Double
    let date: Date
    let timefromNow: TimeInterval
}

extension UserAccountActor {                 // actor declared in sample 01

    /// Returns x-axis tick positions spaced at the coarsest "round" interval
    /// that still subdivides the data span usefully.
    private func calcSmartTimeTicks(result: [SpeedItem]) -> [TimeInterval] {
        let min: TimeInterval = result.first?.timefromNow ?? 0
        let max: TimeInterval = result.last?.timefromNow ?? TimeInterval(result.count)
        let span = max - min
        let step: TimeInterval =
        span <   0     ?      5  :
        span <   30    ?     10  :
        span <   60    ?     15  :
        span <   150   ?     30  :
        span <   300   ?     60  :
        span <   600   ?    120  :
        span <   900   ?    150  :
        span <   1800  ?    300  :
        span <   3600  ?    900  :
        span <   7200  ?   1800  :
        span <  21600  ?   3600  :
        span <  43200  ?   7200  :
        span <  86400  ?  18000  :
        span < 172800  ?  21600  :
        span < 604800  ?  43200  :
        86400
        let start   = ceil(min / step) * step
        let end     = floor(max / step) * step
        return stride(from: start, through: end, by: step).map { $0 }
    }
}

/*
 ===============================================================================
 SAMPLE 04 — WMO WIND BARB GENERATOR (TURTLE GRAPHICS + SWIFTUI CANVAS)
 ===============================================================================
 MODULE:         Weather UI (Presentation Layer)
 ARCHITECTURE:   SwiftUI View; all geometry is computed in a `Canvas` render
                 closure via a Logo-style turtle engine (sample 05).
 PURPOSE:        Renders a standard WMO (World Meteorological Organization)
                 wind barb: a shaft where each "feather" encodes wind speed —
                 triangle = 50 kn, full barb = 10 kn, half barb = 5 kn,
                 ringed dot = calm. `getAllBarbs` greedily decomposes any
                 speed into the correct feather sequence; the render loop
                 walks a turtle down the shaft, stamping feathers as it goes.
 DATA FLOW:      Forecast wind speed (Int, knots)
                   -> getAllBarbs(from:)   // [.fifty, .fifty, .ten, .five] etc.
                   -> Turtle path building (sample 05)
                   -> Canvas strokes/fills
 TECHNIQUES:     Greedy numeric decomposition; turtle-graphics path building;
                 SwiftUI Canvas; trigonometric feather sizing (45° barb angle,
                 hypotenuse = length · √2).
 SOURCE:         WakeKeeper/UserInterface/Views/ForecastArrow.swift
 ===============================================================================
 */

import SwiftUI

// MARK: - Context & Dependencies
// `Turtle` is the Logo-style path engine defined in sample 05
// (05_turtle_graphics_engine.swift): fd/bk move, lt/rt turn,
// pu/pd pen control, home() returns to the start point.
// `ViewModel` is the app-wide @Observable view model (not used in the
// rendered output below, but injected by the environment in the app).

struct ForecastArrow: View {

    @Environment(ViewModel.self) private var globalVM: ViewModel
    private var windSpeedKn     : Int
    private let frame           : CGRect

    init(size: CGFloat, windSpeedKn: Int) {
        self.windSpeedKn = Swift.min(windSpeedKn, 150)
        self.frame = CGRect(x: 0, y: 0, width: size, height: size)

    }

    var body: some View {

        let allBarbs = getAllBarbs(from: windSpeedKn)

        let min: CGFloat = min(frame.width, frame.height)
        let frameY = min * 0.146
        let gray: Color = Color.gray
        let lineWidth   : CGFloat       = min * 0.008

        let lineCap     : CGLineCap     = .square
        let lineJoin    : CGLineJoin    = .miter
        let miterLimit  : CGFloat       = lineWidth
        let dash        : [CGFloat]     = []
        let dashPhase   : CGFloat       = lineWidth

        let style = StrokeStyle(
            lineWidth: lineWidth,
            lineCap: lineCap,
            lineJoin: lineJoin,
            miterLimit: miterLimit,
            dash: dash,
            dashPhase: dashPhase
        )

        Canvas { context, size in

            let bottomCenter = CGPoint(x: size.width / 2, y: size.height)

            // The `fraction` could perhaps be determined by the amount of items in `allBarbs` but for now it will just be a fixed amount of `1/5 of size.height`
            // The `tenFiftyKnotLength` is determined by this fraction of `size.height`.
            let fraction: CGFloat = 0.2

            // The `barbsStartPoint` has to be determined by `fractionOfHeight` which is a distance from `bottomCenter`.
            // This is the distance from `barbsStartPoint` to `bottomCenter` is the same as the `ADJ` or `OPP` angle of the 50/10 barbs.
            // The length of 10 and 50 knot barbs are the same.
            // The length of the `ADJ` and `OPP` sides are `tenFiftyKnotLength`.
            let tenFiftyKnotLength = size.height * fraction

            // The length of the 5 knots barb is half the length of 10/50 knot barbs.
            let fiveKnotLength = tenFiftyKnotLength / 2

            // Define some variables for the size of the head of the shaft and for use in other
            // calculations and adjusting position as needed.
            let aBitLess = size.height * 0.02
            let circleRadius = fiveKnotLength / 2
            let circleDiameter = fiveKnotLength

            // This will be where the first barb will be started
            let barbsStartPoint = CGPoint(x: bottomCenter.x, y: bottomCenter.y - tenFiftyKnotLength - circleRadius)


            // The angle of all barbs are the same.
            // 45° matches the WMO convention for barb feathers.
            let barbAngle: Double = 45


            // The length of the `HYP` for the fifty barb is `sqRoot of tenFiftyKnotLength² * 2`.
            let fiftyHypoteneuse = sqrt((tenFiftyKnotLength * tenFiftyKnotLength) * 2)

            // `aBitLess` will be added to the ten and five barbs to make them look more aligned with the fifty barb.
            let tenHypoteneuse = fiftyHypoteneuse + aBitLess

            // I also need a `fiveKnotHypoteneuse` to draw the 5 knot bard to the correct length.
            let fiveKnotHypoteneuse = sqrt((fiveKnotLength * fiveKnotLength) * 2) + aBitLess

            // If we are going to outline and fill in the shapes then we will need the width and half-width
            // to be a fraction of the  shortest length which is `fiveKnotLength`.
            let allItemsWidth = fiveKnotLength * 0.2

            let allItemsHalfWidth = allItemsWidth * 0.5

            let twoLinesWidth = 2 * lineWidth

            // First the shaft - which is shorter than the full height - needs to be drawn.
            let turtle = Turtle(start: barbsStartPoint)
            let shaftLength = size.height - tenFiftyKnotLength - twoLinesWidth - circleDiameter - circleDiameter
            turtle.fd(shaftLength)

            // Draw a circle at the head of the shaft.
            let turtleCirclePosition = turtle.getPosition()
            let circleCenter = CGPoint(x: turtleCirclePosition.x, y: turtleCirclePosition.y - twoLinesWidth)
            var shaftHead = Path()
            shaftHead.addArc(center: circleCenter, radius: circleRadius, startAngle: .degrees(0), endAngle: .degrees(360), clockwise: true)


            turtle.pu()
            // Move back to the start of the shaft.
            turtle.bk(shaftLength)

            // Now we can start drawing for each barb in `allBarbs`.
            // But first we need a `nextStartPoint` amount that determines how far forward the turtle moves after completing a barb
            // based on the type of barb as below but always shorter in length than `tenFiftyKnotLength`. The standard length
            // below is for 5/10 barbs and will be changed inside the switch for 50-knot barbs.
            let nextStartPoint = tenFiftyKnotLength * 0.35

            // If conditions are still, a `stillCircle` will get stroked.
            var stillCircle = Path()
            var stillCircleCenter = Path()

            // An easy way to get the position to move forward if there is more than one fifty barb is with this variable
            // which is only used for the fifty barb in all cases. Also need to define `nextFiftyLength` to move it
            // forward the correct amount.
            let nextFiftyLength = tenFiftyKnotLength - circleRadius

            // I created a dictionary to easily pass the dimensions around to various methods.
            var dimensionsDictionary: Dictionary<String, CGFloat> = [:]
            dimensionsDictionary["barbAngle"] = barbAngle
            dimensionsDictionary["tenFiftyKnotLength"] = tenFiftyKnotLength
            dimensionsDictionary["fiveKnotLength"] = fiveKnotLength
            dimensionsDictionary["aBitLess"] = aBitLess
            dimensionsDictionary["circleRadius"] = circleRadius
            dimensionsDictionary["circleDiameter"] = circleDiameter
            dimensionsDictionary["fiftyHypoteneuse"] = fiftyHypoteneuse
            dimensionsDictionary["tenHypoteneuse"] = tenHypoteneuse
            dimensionsDictionary["fiveKnotHypoteneuse"] = fiveKnotHypoteneuse
            dimensionsDictionary["allItemsWidth"] = allItemsWidth
            dimensionsDictionary["allItemsHalfWidth"] = allItemsHalfWidth
            dimensionsDictionary["twoLinesWidth"] = twoLinesWidth
            dimensionsDictionary["shaftLength"] = shaftLength
            dimensionsDictionary["nextFiftyLength"] = nextFiftyLength


            for (i, barb) in allBarbs.enumerated() {

                switch barb {
                case .still:
                    // In this case, simply draw a circle at the center of the Canvas with a filled circle at its center.
                    let canvasCenter = CGPoint(x: size.width / 2, y: size.height / 2)
                    // A `reasonableRadius` circle would be...
                    let reasonableRadius = Swift.min(size.width, size.height) / 5
                    let filledCircleRadius = reasonableRadius / 5
                    stillCircle.addArc(center: canvasCenter, radius: reasonableRadius,
                                       startAngle: .degrees(0), endAngle: .degrees(360), clockwise: true)
                    stillCircleCenter.addArc(center: canvasCenter, radius: filledCircleRadius,
                                             startAngle: .degrees(0), endAngle: .degrees(360), clockwise: true)
                    break
                case .calm:
                    break
                case .five:
                    let fiveKnotTurtle = getFiveKnotTurtle(start: turtle.getPosition(), numDict: dimensionsDictionary)
                    context.stroke(fiveKnotTurtle.path, with: .color(gray), style: style)

                    turtle.setPosition(fiveKnotTurtle.getPosition())

                case .ten:
                    let tenKnotTurtle = getTenKnotTurtle(start: turtle.getPosition(), numDict: dimensionsDictionary)
                    context.stroke(tenKnotTurtle.path, with: .color(gray), style: style)

                    turtle.setPosition(tenKnotTurtle.getPosition())

                case .fifty:
                    // If the previous barb was a fifty and this one is a fifty then you need to move the turtle forward by more
                    // than you usually would need to.
                    if i > 0,
                       allBarbs[i - 1] == .fifty && barb == .fifty {
                        turtle.fd(nextFiftyLength)

                    }

                    let fiftyKnotTurtle = getFiftyKnotTurtle(start: turtle.getPosition(), numDict: dimensionsDictionary)
                    context.stroke(fiftyKnotTurtle.path, with: .color(gray), style: style)
                    context.fill(fiftyKnotTurtle.path, with: .color(gray))

                    turtle.setPosition(fiftyKnotTurtle.getPosition())

                }
                turtle.fd(nextStartPoint)

            }

            // Unless wind is `.still`, stroke the turtle otherwise stroke the `.still` circle and the `shaftHead`.
            if allBarbs.contains(.still) {
                context.stroke(stillCircle, with: .color(gray), style: style)
                context.stroke(stillCircleCenter, with: .color(gray), style: style)
                context.fill(stillCircleCenter, with: .color(gray))

            } else {
                context.stroke(turtle.path, with: .color(gray), style: style)
                context.stroke(shaftHead, with: .color(gray), style: style)

            }

        }
        .frame(width: frameY, height: frameY, alignment: .center)

    }

    func getFiveKnotTurtle(start: CGPoint, numDict: Dictionary<String, CGFloat>) -> Turtle {
        let turtle = Turtle(start: start)
        turtle.lt(90 + numDict["barbAngle"]!)
        turtle.pd()
        turtle.fd(numDict["fiveKnotHypoteneuse"]!)
        turtle.pu()
        turtle.home()

        return turtle
    }

    func getTenKnotTurtle(start: CGPoint, numDict: Dictionary<String, CGFloat>) -> Turtle {
        let turtle = Turtle(start: start)
        turtle.lt(90 + numDict["barbAngle"]!)
        turtle.fd(numDict["fiftyHypoteneuse"]!)
        turtle.pu()
        turtle.home()

        return turtle
    }

    func getFiftyKnotTurtle(start: CGPoint, numDict: Dictionary<String, CGFloat>) -> Turtle {
        let turtle = Turtle(start: start)
        turtle.lt(90 + numDict["barbAngle"]!)
        turtle.fd(numDict["fiftyHypoteneuse"]!)
        turtle.lt(90 + numDict["barbAngle"]!)
        turtle.fd(numDict["tenFiftyKnotLength"]!)
        turtle.home()

        return turtle
    }

    /// Greedy decomposition of a wind speed into WMO feathers:
    /// as many 50 kn triangles as fit, then 10 kn barbs, then a 5 kn half-barb.
    /// The `-2` tolerance rounds 48 kn up to a 50 kn triangle, matching how
    /// meteorologists round observations to the nearest 5 knots.
    func getAllBarbs(from windspeed: Int) -> [Barb] {
        if windspeed < 1 { return [.still] }
        else if windspeed < 5 { return [.calm] }
        else {
            var bigResult: [Barb]= []
            var loopingWindSpeed= windspeed
            while loopingWindSpeed - 50 >= -2 {
                bigResult.append(.fifty)
                loopingWindSpeed -= 50
            }
            while loopingWindSpeed - 10 >= -2 {
                bigResult.append(.ten)
                loopingWindSpeed -= 10
            }
            while loopingWindSpeed - 5 >= -2 {
                bigResult.append(.five)
                loopingWindSpeed -= 5
            }

            return bigResult

        }

    }

    private func getWindSpeedRoundedUpToClosestFiveKnots(_ windSpeed: Int) -> Double {
        (Double(windSpeed) / 5).rounded(.up) * 5

    }

    enum Barb: String {
        case still
        case calm
        case five
        case ten
        case fifty
    }

}

// MARK: - Environment Stubs (context only)
// In the app these are injected via SwiftUI's Environment. The one-line stubs
// below ground the references; the view's geometry does not depend on them.
@Observable final class ViewModel { }

/*
 ===============================================================================
 SAMPLE 05 — TURTLE GRAPHICS ENGINE (LOGO-STYLE DSL OVER SWIFTUI PATH)
 ===============================================================================
 MODULE:         Drawing DSL (Presentation Layer)
 ARCHITECTURE:   Reference-type builder (class) that accumulates into a
                 SwiftUI `Path`; consumed by Canvas render closures.
 PURPOSE:        SwiftUI `Path` is a passive value type — you feed it absolute
                 coordinates. For procedural drawing (compass needles, wind
                 barb feathers, dial markers) relative "move and turn"
                 commands are far more natural. This engine ports the classic
                 Logo turtle to SwiftUI: `fd`/`bk` move, `lt`/`rt` turn,
                 `pu`/`pd` lift the pen, `home()` returns to origin.
 DATA FLOW:      Turtle(start:) -> command sequence (fd/lt/pu/...) ->
                 accumulated Path -> context.stroke / context.fill in Canvas.
 TECHNIQUES:     Mutable builder over an immutable value type; trigonometric
                 heading (angle in degrees, -90° = up); pen-state-aware
                 `home()`; backticked `repeat` to reuse the keyword as an API.
 USED BY:        Sample 04 (WMO wind barbs) and the heading-instrument
                 rendering in the app.
 SOURCE:         WakeKeeper/UserInterface/Views/Tutle.swift
 ===============================================================================
 */

import SwiftUI

class Turtle {
    private(set) var path = Path()
    private var start: CGPoint
    private var position: CGPoint
    private var angle: CGFloat = -90  // Degrees; -90° points "up" the canvas
    private var penDown = true

    init(start: CGPoint = .zero) {
        self.start = start
        position = start
        path.move(to: position)
    }

    /// Move forward by `distance` in the current heading, drawing if the pen is down.
    func fd(_ distance: CGFloat) {
        let rad = angle * .pi / 180
        let dx = cos(rad) * distance
        let dy = sin(rad) * distance
        let newPos = CGPoint(x: position.x + dx, y: position.y + dy)
        if penDown {
            path.addLine(to: newPos)
        } else {
            path.move(to: newPos)
        }
        position = newPos
    }
    func bk(_ distance: CGFloat) {
        fd(-distance)
    }
    func rt(_ degrees: CGFloat) {
        angle += degrees
    }
    func lt(_ degrees: CGFloat) {
        angle -= degrees
    }
    func `repeat`(_ times: Int, content: () -> Void) {
        for _ in 0..<times {
            content()
        }
    }
    func pu() {
        penDown= false
    }
    func pd() {
        penDown= true
    }
    /// Return to the start point and heading, preserving pen state so the
    /// caller's stroke/fill intent is respected across the jump.
    func home() {
        let wasDown= penDown
        pu()
        position= start
        if wasDown {
            path.addLine(to: position)
        } else {
            path.move(to: position)
        }
        angle= -90
        if wasDown { pd() }
    }
    func closePath() {
        self.path.closeSubpath()
        self.pd()
    }
    func reset(to point: CGPoint?= nil) {
        position= point ?? start
        angle= 0
        penDown= true
        path= Path()
        path.move(to: position)
    }
    func getPosition() -> CGPoint {
        position
    }
    func setPosition(_ pos: CGPoint) {
        self.position = pos
    }
    func join(_ firstPosition: CGPoint, _ secondPosition: CGPoint) {
        self.path.move(to: firstPosition)
        self.path.addLine(to: secondPosition)
        self.path.move(to: secondPosition)
    }

}