Shoot on the Move, Explained

Terms with a dotted underline have definitions — hover them, tap them, or tab to them.

Groundwork · How the pieces fit together

Everything below rests on one distinction, so it's worth nailing down before any maths: a shooting robot aims with two separate mechanisms, and the two halves of the problem map onto them exactly one-to-one.

How motion is described — speed, velocity, acceleration

position  ──d/dt──▶  velocity        ──d/dt──▶  acceleration
   m                    m/s                       m/s²

angle θ   ──d/dt──▶  ang. velocity ω ──d/dt──▶  ang. acceleration α
  rad                  rad/s                     rad/s²

components   v = (vx, vy)      both m/s — neither one is the speed
polar        v = (|v|, θ)      the speed, and a direction as an angle

|v| = √(vx² + vy²)          vx = |v|·cos θ
 θ  = atan2(vy, vx)         vy = |v|·sin θ

The two splits that organise everything below

vx = v · x̂        vy = v · ŷ        axes bolted to the field
v∥ = v · r̂        v⊥ = v · p̂        axes pinned to the goal

vx² + vy²  =  v∥² + v⊥²  =  |v|²

How the two problems connect

Separate problems, but not independent ones. They're chained together, and the chain loops back on itself — which is the single most important thing to understand before reading further.

Part One · Aiming the turret

Job one. Geometry only — and it works out to a formula with exactly two terms.

First — angular velocity, since it's about to be everywhere

There are two completely different kinds of "fast", and every formula below depends on not confusing them.

• Linear velocity — how fast you get somewhere. Metres per second.
• Angular velocity, also called rotational speed, written ω — how fast you turn. Radians per second.

They're independent: a robot spinning on the spot has zero linear velocity and plenty of angular velocity.

The unit zoo

Most of the confusion around angular velocity is really confusion about units. There are three in common use and they all mean the same thing:

Where does 2π come from, if the circumference is 2πr?

A fair objection, and the answer is the key to the whole unit. An angle in radians is a ratio — it is defined as the arc length divided by the radius:

And because it cancels, 2π is the answer for a circle of any size. A coin and a stadium both contain exactly 2π radians in one turn. So 2π and 360 are simply two names for one full revolution — except that 360 is arbitrary (Babylonian, roughly the days in a year, and pleasantly divisible) while 2π falls straight out of the definition.

One revolution = 360° = 2π ≈ 6.28 radians. Radians are the native unit for a specific reason: arc = radius × angle is only true in radians. Work in degrees and you end up sprinkling conversion factors through every equation — which is exactly the derivation coming up in Fig 10.

And second — what a derivative is

You just met one. ω is a derivative — the rate at which heading changes. Since the whole tutorial runs on derivatives, and the word puts people off far more than the idea deserves, here it is plainly.

A derivative is a rate of change: how much the output moves when you nudge the input a little. Three ways of holding the same idea:

• It's the slope of a graph. Steep curve, big derivative. Flat curve, derivative near zero.
• It's the word "per". Miles per hour. Degrees per second. Centimetres of miss per degree of hood error.
• It's the speedometer. Given a formula for where something is, the derivative tells you how fast it's moving.

Is that just algebra, then?

Reasonable thing to assume, and worth heading off, because the answer is no — though for a subtle reason.

Algebra rewrites. Differentiation transforms. Turning 2x + 6 = 10 into x = 2 is a rearrangement: same statement, different clothes, nothing lost, and you can walk it back. Turning y = x² into 2x is not that at all — those two are not equal. It's a brand-new function answering a different question about the original: not "what is its value" but "how steep is it".

And the other half of calculus — integration

Worth meeting now, because both halves are already inside your shooter and it's easier to keep them apart than to untangle them later.

• Differentiate — you have the whole thing, you want the rate. Zoom in. "How fast is this changing right now?"
• Integrate — you have the rate, you want the accumulation. Zoom out. "How much has piled up so far?"

They are inverses of each other, and both work by chopping things into tiny slices. The only difference is what they do with the slice:

differentiate:   Δy ÷ Δt        divide by the slice
integrate:       Σ  y · Δt      multiply by the slice, then add them all up

Start with the easy case. The robot is parked. The target is a fixed point on the field. The turret points at it. Nothing changes, nothing moves, no math required.

Now drive. Two completely separate things start ruining your aim, and it's worth being very clear that they are separate — that's the whole insight behind the formula.

Cause 1: the robot's own rotation

The turret is bolted to the chassis. Its angle is measured relative to the chassis. So if the chassis rotates 40° counterclockwise and the turret motor doesn't move at all, the turret has physically swung 40° counterclockwise in the real world — and lost the target.

The fix is obvious: turn the turret backwards at exactly the rate the robot is turning. If the robot spins at ω radians per second, the turret must spin at −ω. That's the first term, and it's the easy one.

Cause 2: sideways motion, and where the division comes from

This one is less obvious and it's where the / distanceToTargetMeters in your snippet comes from.

First, split the robot's velocity into two pieces relative to the target:

• Radial — the part moving straight toward or straight away from the target. This changes your distance, which matters enormously for the shot solution (Part Two), but it does not change the direction you're pointing. Driving directly at a target never requires turning.
• Tangential (perpendicular) — the part sliding sideways across the target. This is the piece that forces the turret to sweep.

Now, how fast must it sweep? Picture the sideways motion as briefly tracing a tiny arc on a circle centred on the target, of radius d. Arc length equals radius times angle, so angle equals arc length over radius:

sideways distance in time Δt  =  v⊥ · Δt        ← the "arc"
angle swept  =  arc ÷ radius  =  (v⊥ · Δt) ÷ d
divide through by Δt          =   v⊥ ÷ d         ← Δt gone, arc gone

r  = target − robotPose          // vector to the goal
d  = |r|                         // distance
v⊥ = part of the chassis velocity perpendicular to r
FF = -(omega + v⊥ / d)

Put the two together

Add the two effects, flip the sign because the turret has to cancel them rather than follow them, and you have the whole formula:

chassis points  →  ω
turret points   →  ω + θ̇_turret

ω + θ̇_turret  =  φ̇  =  −v⊥/d
      θ̇_turret  =  −( ω + v⊥/d )

That is precisely this line:

double turretFFRadiansPerSecond =
        -(angularVelocityRadiansPerSecond + tangentialVelocityMetersPerSecond / distanceToTargetMeters);

The same idea, phrase by phrase

Stated compactly, the whole approach is one long sentence with six pieces of jargon in it. Every one of them now has a definition, so here it is taken apart:

To compensate for motion, run the turret with a velocity feedforward angular velocity equal and opposite to the rotational speed of the robot plus the tangential velocity of the robot about the target divided by the distance to the target.

Assemble those pieces and you get −( ω + v⊥ ÷ d ) — the formula above, and the line of code shown earlier. Stripped of jargon, the question is simply: "should I spin the turret backwards at exactly the rate the world appears to rotate around it?"

Where the formula actually comes from

Saying the formula is "exact" is a strong claim, so here's the machinery behind it. It's a two-step recipe, and both steps are less intimidating than their names.

Step 1 — write the turret angle as a function of robot pose

Pose is just the three numbers that say where the robot is: x, y, and heading θrobot. "As a function of pose" means writing an equation whose inputs are those three numbers and whose output is the turret angle.

Doing that is pure angle bookkeeping. The turret has to point along the bearing to the target — but turret angles are measured relative to the chassis, not the field, so you subtract the robot's own heading:

Why you subtract the heading — field-centric vs robot-centric

That subtraction is worth dwelling on, because it's a frame conversion, and frames are where most sign bugs live. There are two ways to describe any direction on a field:

• Field-centric (also called field-relative) — measured from the field. "Downfield" points the same way no matter how the robot is turned. Like a top-down video game.
• Robot-centric — measured from the robot. "Forward" means wherever the nose happens to be pointing right now. Like driving a car.

drive encoders  ─┐
steer encoders  ─┼─▶ kinematics ─▶ (vx, vy, ω) robot-relative ─▶ + gyro ─▶ field-relative v
module geometry ─┘

Step 2 — differentiate it

Differentiating means finding the rate of change — the same operation as going from a formula for position-over-time to a formula for speed.

That is exactly the bridge needed here. The feedforward wants a velocity; Step 1 produced a position. Differentiating converts one into the other. Nothing else in this tutorial depends on knowing how to do it by hand, but here's the argument with no calculus at all — over a tiny slice of time Δt, two things happen:

• The chassis rotates by ω·Δt. Since the turret angle is measured from the chassis, that subtracts directly.
• The robot slides sideways by v⊥·Δt, which swings the line of sight by (v⊥·Δt) ÷ d radians — the arc argument from Fig 10. And it swings backwards: move to the left, and the target appears to drift to the right.

So Δθturret = −ω·Δt − (v⊥/d)·Δt. Divide both sides by Δt and you have the rate:

See it move

Drive the robot past the target and watch the two terms trade off. Notice that v_⊥ peaks when the robot is directly abreast of the target and falls to zero at the far ends, where the motion is almost purely radial — and notice how the total demand spikes when d gets small.

A frame-mixing bug worth knowing about

So the formula is right. But a correct formula fed a wrong input is still a wrong turret command, and there is one mistake in computing v_⊥ that is easy to make and hard to spot. It is worth walking through, because it fails quietly rather than obviously. Here is the version with the bug in it:

var targetFrameToRobot = new Translation2d(robotSpeeds.vxMetersPerSecond, robotSpeeds.vyMetersPerSecond)
        .rotateBy(robotToTargetTranslation.getAngle());
double tangentialVelocityMetersPerSecond = targetFrameToRobot.getY();

Here's the idea being attempted. The velocity is in field coordinates — x is downfield, y is to the left. You want to know how much of it is sideways relative to the target. The trick is to rotate your whole coordinate system so the target lies straight ahead on the x-axis; once you've done that, the y component is the sideways part, for free.

To rotate the world so that a direction sitting at angle φ ends up on the x-axis, you rotate by −φ. The code rotates by +φ, which spins it the wrong way and lands the target at 2φ instead of 0.

So is the turret solution robust?

Worth answering carefully, because robust means two different things and they give different answers.

Is the maths sound? Yes — it's exact, as the derivation above shows. There is no fitting, no approximation, and therefore no modelling error to be fragile about.

Is it robust to imperfect inputs? Mostly — but there is one genuine structural hazard, and it's worth knowing before you trust the feedforward everywhere on the field.

Because the formula is exact, every error in its output comes from an error in its three inputs: ω, v_⊥ and d. And d sits in a denominator. Differentiating the second term with respect to distance gives −v⊥/d² — that squared d means sensitivity grows explosively as you close in.

What to do about the close-range problem

Diagnosing it is only half a job. There are real fixes, and the best of them comes straight out of the formula itself.

1 · The turret is not your only actuator

Look again at what's demanded: −(ω + v⊥/d). That's a sum — and ω, the chassis rotation rate, is something you also command. Nothing says the turret has to absorb the whole thing.

So split the work. Ask the drivetrain to rotate as far towards −v⊥/d as it can manage, and hand the turret only what's left over:

omegaChassis = clamp(-vPerp / d,  -OMEGA_MAX,  +OMEGA_MAX);
turretFF     = -(omegaChassis + vPerp / d);      // whatever the chassis couldn't cover

Your available tracking rate becomes turret maximum + chassis maximum rather than the turret's alone. And in the limit where the drivetrain can do the whole job, the turret feedforward falls to zero — the robot simply rotates to follow the goal and the turret sits still relative to the chassis.

2 · Or delete the term altogether

Remember what v⊥ actually is: the tangential part of your velocity. Drive radially — straight towards or away from the goal — and v⊥ = 0, so the entire troublesome term disappears regardless of how close you are.

That isn't a control fix, it's a path-planning constraint: near the goal, approach along the line of sight. It costs nothing to implement and it's completely effective, which makes it the first thing to try.

3 · Cap the damage

• Clamp d to some minimum before dividing. Kills the singularity outright, at the cost of being slightly wrong very close in — where you were going to be wrong anyway.
• Let the aim tolerance grow as you close in. The goal subtends a wider angle up close, so a fixed "within 1° to shoot" threshold is needlessly strict there. Scale the threshold with 1/d and you demand less precision exactly where precision is hardest to get.

4 · Improve the inputs

• Feed forward from commanded chassis velocity, not measured. You know what you asked the drivetrain to do before it does it, so there's no sensor lag — and lag hurts most when rates are high, which is exactly the close-range case.
• One genuine consolation: vision gets better up close. Tags resolve larger, ambiguity drops, so σ_d shrinks as you approach. That partly offsets the 1/d² amplification — it doesn't cancel it, but the close-range case is less dire than the raw formula suggests.

Putting it together — so how far do you actually rotate the turret?

Everything so far has been about the feedforward, which is a rate. But the obvious question is the other one: how far should the turret turn? Both halves exist in this tutorial; here they are assembled.

The first thing to unlearn is the phrasing. You never tell a turret "rotate 12°". You tell it where to point, recompute that fifty times a second, and let a controller close whatever gap remains. The "where" is the angle bookkeeping from Fig 11:

targetAngle = atan2(Ty − y, Tx − x) − robotHeading
              └──── bearing to the goal ────┘   └ chassis ┘

And the complete motor command is those two ideas added together:

// 1 · WHERE to point — a position
double targetAngle = aimPoint.minus(robotPose.getTranslation()).getAngle()
                       .minus(robotPose.getRotation()).getRadians();

// 2 · HOW FAR off we are at this instant
double error = angleWrap(targetAngle - currentTurretAngle);

// 3 · close that gap, AND keep pace with where it is heading
double output = pid.calculate(error) + turretFF;
//              └─ closes the gap ─┘   └ stops it re-opening ┘

One last thing about aimPoint in that snippet: it should be the virtual goal, not the real one — the goal shifted back to compensate for the ball's drift. Which is the subject of the next section, and the one thing this half of the problem cannot supply for itself.

The one thing Part One cannot do

Everything above tracks the goal. But a robot shooting on the move should not point at the goal. The ball leaves the shooter already carrying the robot's velocity, so it drifts sideways during flight. You have to aim at a virtual goal — the real goal offset backwards by however far the ball will drift.

Why the ball drifts at all

Because it inherits the robot's velocity. The ball doesn't leave carrying only the shooter's exit velocity — it leaves carrying exit velocity plus robot velocity. Throw a ball straight up on a moving train and it lands back in your hand, because it kept the train's speed the whole time. The same thing happens here, and there is no way to prevent it.

So at 3 m/s sideways with a flight lasting 0.85 s, the ball drifts 3 × 0.85 = 2.55 m before it arrives. Aim at the goal and you miss by that much.

So aim somewhere else

Offset the aim point by exactly that drift, in the opposite direction, and the drift carries the ball onto the target. One vector subtraction:

exitVel_robot = map(rpm, hoodAngle)          // from the test stand
exitVel_field = exitVel_robot.rotateBy(robotHeading)
                             .plus(robotVelocity)   // ← the robot's motion enters HERE
simulate(exitVel_field)

The offset also depends on your velocity, which is itself changing — so a fully correct feedforward has a third term for how fast the aim point is moving. The two-term formula is the dominant part and correct as far as it goes; it simply isn't the complete picture.

And "how long is the ball in the air?" is a question Part One cannot answer. It has no physics in it. Look back at Fig 3: the turret in box 4 is waiting on a time-of-flight number that only the solver in box 2 can produce. Geometry has taken this as far as geometry goes.

Part Two · Choosing the shot

Job two — box 2 in Fig 3. This is where the clean answers run out, and a genuine design choice appears.

Recall what this box has to produce: given a distance, a hood angle and a flywheel speed as a matched pair, plus the time of flight the turret is waiting on. Not two independent numbers — one pair, because the two are locked to each other.

What you do today, and why it's defensible

The current approach is a lookup table. Park the robot at 3 metres, tune the hood and flywheel by hand until shots go in, write the numbers down. Repeat at 4 m, 5 m, 6 m. At runtime, measure the distance and interpolate between the two nearest rows. A separate table stores time of flight, used to compute the virtual goal offset for moving shots.

Where the table comes from in the first place

There's no clever source. You make it by shooting, on the practice field, by hand:

1. Park the robot at a known distance from the goal.
2. Pick a hood angle, then sweep the flywheel speed until shots go in reliably — several balls in a row, not one lucky one.
3. Write that distance and its matching pair into the table.
4. Move the robot, repeat. Five to ten distances is typical.
5. For the time-of-flight map, film the shots and count frames between launch and arrival.

That's the whole method, and it's genuinely an afternoon's work. It's also why the approach earns so much trust: every row is a shot that actually went in.

That word interpolate is doing quiet work, so here's exactly what it means — the answer is that measuring d is enough because the answers were already measured and written down. You aren't deriving anything, you're blending two rows you already have.

How inaccurate is that blend, really?

Less than you might expect, and it's worth putting a number on it rather than hand-waving — because the table's real weaknesses turn out to be somewhere else entirely.

Linear interpolation draws a straight chord between two points on a curve that actually bows, and the gap between chord and curve is bounded by (h² ÷ 8) × curvature, where h is the row spacing. Taking the very numbers from the example above — 42°, 38°, 35.5° at one-metre spacing — the curvature works out at 1.5 °/m², putting the worst-case interpolation error at 0.19°. Note that it scales with the square of spacing: halve the gaps and you quarter the error. It is the cheapest problem here to fix — you just add rows.

That second row is the important one. Hand-tuning gets you perhaps ±0.5° per entry — you find a band of settings that works and pick somewhere near the middle. And because the chord passes exactly through every measured point, each row's error is preserved permanently. Noise outweighs interpolation error by getting on for three to one, and adding rows only adds more noisy rows.

Three problems that aren't accuracy at all

• The error is biased, not random. On a curve that bends one way, the chord always sits on the same side of the truth. So the error between rows is systematic — it never averages out across many shots the way random error would.
• The slope is a staircase. At every row the derivative jumps discontinuously, and between rows it's constant. A table's slope carries almost no information, which is a second and independent reason robustness can't be extracted from one.
• Beyond the last row there is nothing. Not an inaccurate answer — no answer.

Which reframes the complaint usefully. The table isn't badly inaccurate in the middle; it is noisy (fixable by fitting), incomplete at the edges (fixable by fitting, better by a model), and unusable for slopes (fixable only by a model). Three separate problems at three very different prices, bundled together under the single word "accuracy".

This is popular for an excellent reason: it cannot be wrong about physics, because it contains no physics. Ball compression, roller slip, how much energy the flywheel actually transfers, air drag — none of it is modelled, so none of it can be modelled incorrectly. You measured reality and wrote it down. This is usually called trusting in its "correctness", and that instinct is sound.

Where it runs out

Three limits. It's only valid where you sampled. It can't extrapolate past the ends of the table. And — the one that matters most here — it hands you exactly one answer per distance, with no way to ask whether that answer is a good one.

That third limit is the crux of the entire argument, and it takes two steps to see.

Step one — many different shots all score

At any given distance there isn't one solution — there's an entire family. Shoot high and slow (a lob), shoot low and fast (a line drive), or anything in between. All of them go in. A lookup table picks whichever one you happened to tune that day.

Why any of this matters — the shot is open-loop

Before the next step, the fact that makes it necessary: once the ball leaves the shooter, it is ballistic. Nothing on the robot can touch it. There is no controller downstream, no correction, no second chance.

Everything you can influence happens before release — and that is where all the feedback lives too.

Step two — but they are not equally good

Your hood will never be at exactly the commanded angle. Your flywheel will never be at exactly the commanded RPM. So the right question isn't "does this shot score when everything is perfect" — everything in Fig 19 does. It's "does this shot still score when I'm 2° and 100 RPM off?"

Some members of the family are extremely forgiving. Others fall apart. Same nominal accuracy, wildly different real-world hit rate:

The sensitivity metric is exactly this steepness, measured in both directions at once:

Why the table cannot compute that metric

The metric needs two derivatives. Derivatives are slopes. And here is the difficulty: your table stores where the good shots are, while robustness is entirely about the shape around them.

Every row in the table is a success — it went in. Nothing in it records what happens 2° off, because nobody ever deliberately shot 2° off and measured how far it missed. The table knows the location of the minimum and nothing at all about the terrain surrounding it.

Could you just measure the shape instead?

In principle, yes. In practice the cost is brutal, for a reason that's easy to overlook: you would have to shoot deliberate misses — a grid of perturbed hood and speed settings at every distance — and measure how far each one missed, in centimetres. That is a far harder measurement than "did it go in", because it needs precise landing positions rather than a yes or no.

Five by five perturbations across six distances is already about 150 deliberately-missed shots for the stationary case alone. Add radial velocity as a second input and it runs into the thousands. The alternative is to measure the exit conditions once on a bench and compute the rest.

And no, you don't need calculus to do it

Worth saying plainly, because "derivative" makes this sound like a maths problem when it's really a simulation problem. Robustness is a derivative — "how much does the miss grow per degree of error" is a rate of change, so asking the question is already asking for one. But there are three ways to obtain that number, and only one of them involves calculus:

All three answer the same question; the derivative is the name of the quantity, not the method of getting it. In practice you would use finite differences, estimating the derivatives numerically from the table.

There's also a hard reason symbolic isn't on the table: once drag is in the model there is no closed-form range equation. The tidy v²·sin(2θ)/g above exists only in a vacuum. With air resistance the trajectory has to be integrated step by step, so there is nothing to differentiate symbolically even if you wanted to.

First — what "a model" actually means here

The word model gets thrown around loosely, so let's pin it down, because it's narrower and more boring than it sounds. It does not mean the real robot, a robot simulator, a CAD model, or machine learning.

A model here is a page of equations you run on a laptop. Essentially all of it is this:

whereDoesItLand(exitSpeed, launchAngle, spin):
    x, y   = 0, shooterHeight
    vx, vy = exitSpeed * cos(launchAngle), exitSpeed * sin(launchAngle)

    while y > goalHeight:                              # step forward in tiny slices
        drag   = -DRAG_COEFF   * speed * (vx, vy)                # air resistance
        magnus =  MAGNUS_COEFF * spin  * perpendicular(vx, vy)   # lift from backspin
        vx += (drag.x + magnus.x)        * dt
        vy += (drag.y + magnus.y - 9.81) * dt          # gravity
        x  += vx * dt ;  y += vy * dt

    return x, elapsedTime          # where it landed, and how long it took

Step the ball forward in small time slices and watch where it goes. When people say "simulate" here, they mean running that loop — not boot up a robot simulator. Running it a hundred thousand times with different inputs is the grid sweep in the pipeline below, and it takes seconds.

What exit velocity and spin are each doing in there

They are both handed to the loop, but they enter it in quite different ways.

• Exit velocity is used once, on the line that sets vx, vy. It initialises the integration and is never touched again — it is the constant of integration mentioned earlier.
• Spin is used at every step, inside the Magnus term. It is not an initial condition at all; it is a parameter of one of the forces, acting for the whole flight.

The two constants — and why there are only two

Those two capitalised names are the model's only unknowns. Each bundles several messy physical properties into a single number, so you never have to know them separately:

Three words people use interchangeably, wrongly

Model, simulation and measurement are three different things, and discussions swap between them freely. They're easy to keep straight once separated:

Model is to simulation as a recipe is to cooking. One is the description, the other is the act of running it.

So where does the real robot come in?

Crucially, model and measurement are not rivals — measurement is what makes the model trustworthy. Those two constants don't come from a textbook; they come from your own test stand and stationary shots. The real cycle is: measure a little → calibrate the model → simulate a lot → check against more measurements. The model doesn't replace testing. It multiplies a small amount of testing into answers about a hundred thousand shots you never took.

It's still essential — it just has a different job. The split is deliberate, and it's the cleverest part of the approach.

Where do you actually run that measurement?

Stationary — and it barely matters whether that's a purpose-built stand or the robot itself. Never while driving.

The reason moving is not merely unnecessary but strictly worse: what you are measuring is the robot-frame exit velocity, and that is unaffected by driving. Moving therefore adds a quantity you already know how to compute, and then obliges you to subtract it back out — which requires knowing the robot's velocity precisely at the instant of release, with all the error that carries. Same signal, more noise, no upside.

The only thing that genuinely matters is mechanical identity. This map exists to capture compression, slip and energy transfer — so a stand that squeezes the ball even slightly differently produces numbers that are wrong in a way nothing downstream can detect. If you have a spare identical shooter, use a stand. If not, use the real robot parked. Do not build an approximate stand.

map:  (measured RPM, hood angle)  →  (exit velocity, spin)

What "calibration" actually involves

Two calibrations, done in that order, and they are different kinds of measurement — which is worth being clear about because they get bundled under one word.

180 grid cells  ×  ~200 candidate shots  ×  ~5 perturbations each
   ≈  180,000 shots

Step 1, the map, is measured directly. You point a high-speed camera at the muzzle and see the answer: this RPM and this hood angle produced that speed and that spin. Nothing is inferred.

Step 2, the two constants, are fitted. You cannot photograph a drag coefficient. They are inferred by asking which values would have produced the flights you actually observed:

for each candidate (kd, km):
    total = 0
    for each recorded shot:
        exitVel, spin = map(shot.rpm, shot.hood)      # needs step 1 already done
        predicted     = simulate(exitVel, spin, kd, km)
        total += (predicted - shot.actualLanding)²
    remember total

pick the (kd, km) with the smallest total

Two parameters means a plain 2D grid search is enough — sweep both across a plausible range and take the minimum, no optimiser required. And it makes plain why the map has to come first: the model cannot simulate anything without knowing where the ball started.

How many shots is actually enough?

Worth reframing the question slightly. Statistical significance belongs to hypothesis testing — "is there an effect at all?" — and that is not what is being asked. You are estimating parameters, so the real question is how precise they need to be, and the answer is: precise enough that their error disappears underneath the noise you cannot remove anyway.

Precision improves as the square root of the shot count, which is unforgiving. Taking a shooter with roughly ±20 cm of shot-to-shot scatter:

Twenty is the knee. By then the model's systematic error sits near 4.5 cm, comfortably beneath the ±20 cm of scatter that nothing removes. Pushing on to eighty costs sixty more balls to gain two centimetres which are invisible against that scatter — and the final column shows the price climbing 2 → 5 → 15 → 43 balls per centimetre. That column is the argument for stopping.

The bench measurement is a different problem

There you are not fitting two parameters, you are mapping a function — so what matters is covering the input space rather than statistical power. Two arrangements cost about the same:

• 5 × 5 grid, one ball each — 25 balls, dense coverage, noisier at each point
• 3 × 3 grid, three balls each — 27 balls, coarser, but averaged

Either serves, because you interpolate or fit through the results afterwards, which averages the remaining noise either way. Keep a few measurements out of that fit as well — the same held-back trick as everywhere else in this tutorial, and the thing that tells you whether the shape you chose actually describes your shooter.

What if the constants drift between ball batches?

A fair worry, and it splits into two cases that want different responses.

Random variation within a batch is simply noise. It is already inside the ±20 cm scatter, it averages away across twenty shots, and there is nothing to be done about it.

Systematic drift between batches is the dangerous one — practice balls behaving differently from competition balls. Your constants are then correct for the balls you calibrated on and confidently wrong for the ones you actually compete with.

batch variation in exit velocity   ≈ 3% of 11 m/s   =  0.33 m/s
∂e/∂v at that shot                 ≈ 2.24 m per m/s
                                   ──────────────────────────
cost of the drift                  ≈ 74 cm of miss

How you'd actually record an entry angle

Easier than the exit-velocity measurement, for a reason that is not obvious: angles need no scale calibration. Measuring a velocity requires something of known length in frame to convert pixels into metres. An angle is atan(rise ÷ run), and if both are in pixels the units simply cancel. A phone at 120–240 fps, placed square-on to the shot plane and as far back as practical with the zoom in, is the entire rig.

total += (predictedLanding    - actualLanding)²
       + w * (predictedEntryAngle - actualEntryAngle)²      # w balances metres against degrees

But is it necessary? No.

Worth saying plainly before the case for it, because the degeneracy problem has a cheaper fix that comes first: simply vary your hood angles. That alone breaks most of it, costs nothing and requires no extra measurement at all. Entry angle is the second lever, not the only one.

Do the first two and you have a serviceable calibration. Skip the third and nothing collapses. And keep the proportion in view: the physics model itself isn't necessary either — that is what the drag measurement in Part Three decides. Entry angle is a refinement of a refinement, and if you are still at "get shoot-on-the-move working at all", it is not where the next hour should go.

When it does earn its place

Chiefly when you are already filming for exit velocity, so the marginal cost is close to zero — or when something is wrong and you cannot tell whether the constants are mis-tuned or the model is inadequate. The last item below is the one that matters most.

• It pulls in a different direction. This is not merely more data — it is data of a different kind. Extra landing points from similar shots produce constraints that are nearly parallel in parameter space, so they stack up along the same valley without narrowing it. Entry angle constrains a different direction, because it responds to drag and to spin in quite different proportions than range does.
• Fewer balls for the same confidence. Every shot now yields two numbers rather than one, so twenty shots become forty constraints. Shoot less, or fit better.
• It is the sharpest measurement for spin in particular. Magnus mostly steepens the descent; drag mostly shortens the range. For a light hollow game piece carrying heavy backspin, Magnus is the constant you most need right — and entry angle is the observable that speaks most directly to it.
• It makes the downstream constraint trustworthy. Suggestion 3 in Part Three argues entry angle should be a hard filter on candidate shots. But you can only enforce a constraint you can predict accurately — if the model's entry angles were never checked against reality, that filter is decoration. Measuring it is what earns the right to use it.
• And it is nearly free. No scale calibration, same session, often the same footage.

The one force in there that isn't obvious — Magnus

Gravity needs no explanation and drag is just air resistance. The third term is the one people skip, and skipping it is what makes a shooter model badly wrong rather than slightly wrong.

The Magnus effect is why a spinning ball curves. It's the same physics as a baseball curveball, a topspin tennis shot dipping inside the baseline, or a backspun golf ball floating instead of dropping.

The mechanism is simpler than its reputation. A spinning ball drags a thin layer of air around with it, which makes it fling its wake off to one side. Push air one way, get pushed the other way — Newton's third law, nothing more exotic. Backspin flings air downward, so the ball gets pushed upward.

The proposed pipeline

To compute that slope you need to be able to ask what-if questions — "what if the hood were 1° higher?" A lookup table can't answer that; it only knows the shots you actually took. A physics model can answer it for free. That's the entire reason to want a model.

Step 1 is the clever part of the approach and worth calling out. Instead of trying to model ball compression, roller slip and energy transfer — genuinely hard, and the usual reason physics models fail on real robots — you measure the map from (flywheel RPM, hood angle) to (exit velocity, spin) directly on a test stand. All the messy contact mechanics gets absorbed into a measurement. The physics model then only has to handle a ball flying through air, which is the part physics is actually good at.

How the robustness number is actually computed

The step is usually stated as something like: compute the robustness of every shot using the metric (derivative of distance error with respect to hood angle)² + (derivative of distance error with respect to exit velocity)², estimating the derivatives numerically from the table. Two things are worth untangling before the algorithm.

You can't take a slope from the first because it records only successes. You can from the second because every cell — including all the bad ones — carries a computed miss distance.

Both score perfectly when executed perfectly. Only one of them survives being executed imperfectly, and that is the entire selection rule.

The algorithm, for one distance and radial velocity

# 1 · fill the grid
for θ in 20°..70° step 0.5°:
    for v in 8..20 m/s step 0.1:
        e[θ][v] = simulate(θ, v).landing − goal        # signed miss, in metres

# 2 · central differences on the interior cells
dEdθ = (e[θ+Δθ][v] − e[θ−Δθ][v]) / (2·Δθ)
dEdv = (e[θ][v+Δv] − e[θ][v−Δv]) / (2·Δv)

# 3 · score every cell
S = dEdθ² + dEdv²

# 4 · choose — but ONLY among shots that actually go in
candidates = cells where |e| < tolerance
best       = argmin(S) over candidates

Two refinements worth making

Use central differences, not forward ones. (right − left) / 2Δ has error proportional to Δ², while (next − this) / Δ is only proportional to Δ. Identical cost, noticeably better answer.

Then consider dropping the division entirely. Pick the step size to match the error your hardware actually has — if the hood holds ±1°, use Δθ = 1° — and use the raw difference:

Δe = e(θ + 1°, v) − e(θ, v)      # what a real 1° error costs you, in metres

Two advantages over a true derivative. It answers the question you care about directly, in centimetres of miss rather than metres-per-radian. And near the optimum, where ∂e/∂θ approaches zero and stops discriminating between candidates, a finite perturbation of realistic size still registers the curvature — which is exactly what separates two shots that both look flat to first order.

What that last step means — "fit a polynomial surface"

This phrase gets used a lot without ever being unpacked, so here it is. A lookup table and a polynomial fit do the same job — given a distance, hand back a hood angle. They differ in what they actually store.

• A lookup table stores the measurements themselves. Six rows of numbers. To answer for 3.5 m it finds the two neighbouring rows and splits the difference.
• A polynomial fit stores an equation drawn through those measurements — something like hood = 51.2 − 4.7·d + 0.21·d². Three coefficients replace the entire table, and 3.5 m isn't looked up, it's computed.

So why is it called a surface?

Purely a matter of how many inputs you have.

With one input — distance — the answer graphs as a curve: a line drawn on a flat page, which is exactly Fig 28. That's your current table.

Shooting on the move adds a second input: radial velocity, how fast you're closing on or backing away from the goal. Two inputs graph as a surface — a landscape, where the horizontal position stands for a situation and the height above it is the hood angle for that situation.

But why radial velocity — and why isn't it three inputs?

A fair question, since the robot's velocity has two components and only one of them appears. The answer is that they are consumed by different subsystems, and only one survives as far as the solver.

√(v∥² + v⊥²)  =  |v|     — always, exactly

Strictly an approximation: the virtual goal sits at a slightly different bearing from the real one, so "radial" measured toward it differs a little from "radial" toward the goal itself. Second-order, and normally ignored.

And why split the work that way at all?

The most immediate reason is that each component is fixed by the mechanism that has authority over it. Sideways drift is a direction error, cured by pointing differently. A distance change is an energy error, cured by shooting differently. You cannot fix a sideways drift by shooting harder, nor a distance change by pointing sideways — so the division is dictated by the hardware, not chosen.

Three practical consequences follow from that, and they all point the same way.

So the grid is simply every combination of those two inputs:

Around 180 cells, each one a situation the robot might genuinely be in. Run the optimisation in every cell, keep the winning pair, then fit a surface through the results.

So where does exit velocity sit in all this?

A reasonable thing to lose track of, because it is measured carefully, discussed at length, and then never appears in the finished lookup. It lives inside the offline loop, and only there — but the loop has two levels, and the join between them is where most of the confusion sits.

OFFLINE
  for each situation (d, v_radial):          # the grid axes. Outer loop.
      for each candidate (hood, RPM):        # the inner search
          exitVel, spin = MAP(RPM, hood)     # the map knows only the shooter
          v0      = exitVel + v_radial       # (1) the situation enters here
          landing = SIMULATE(v0, spin)
          error   = landing - d              # (2) and here
          keep the flattest candidate whose error is about zero
      store that (hood, RPM) at cell (d, v_radial)

The map genuinely does not know about distance or radial velocity, and never needs to — it describes the shooter, not the situation. Those two numbers enter the simulation instead, at the points marked above: radial velocity as part of the ball's initial velocity, and distance as the thing the landing point is measured against.

One cell, worked through with real numbers

Take the cell for 4.0 m away, radial velocity zero. First the search — hunting for the RPM that lands on target at one particular hood angle:

try 2600 RPM  →  map says 5.82 m/s  →  lands 3.46 m    short
try 2800 RPM  →  map says 6.27 m/s  →  lands 4.01 m    on target
try 3000 RPM  →  map says 6.72 m/s  →  lands 4.60 m    long

The map was looked up three times — RPM in, exit velocity out. Worth being exact about what that means: the shooting experiment is not being repeated. The map was measured once, on a bench, and what happens here is the computer reading that stored measurement again. At no point did it need to know the target was 4 m away. You knew that; the map only ever answered "what does 2800 RPM give me?"

Repeat across hood angles and you are left with survivors, every one of which lands on target:

All three score. 45° wins, because it barely notices a degree of hood error — so the cell (4.0 m, 0 m/s) stores hood 45°, 2800 RPM. That single pair is what the surface will later be fitted through.

hood = c₀ + c₁·d + c₂·v + c₃·d² + c₄·d·v + c₅·v²
rpm  = k₀ + k₁·d + k₂·v + k₃·d² + k₄·d·v + k₅·v²

bench experiment   →  the map
field shots        →  the two constants      →  SWEEP  →  winners  →  fit  →  THE SURFACE
physics equations  →  the shape of the flight

Why "second-degree" specifically?

Degree is how many bends the equation is allowed to have. Degree 1 is a straight line and cannot bend at all; degree 2 bends once; degree 5 can wiggle four times. So the choice is really "how much freedom do I give this thing", and both extremes fail.

Degree 2 is the lowest degree that can bend at all, and one bend is about as much structure as the underlying physics has across a normal operating range. In two variables it works out to exactly six terms:

hood  =  c₀ + c₁·d + c₂·v + c₃·d² + c₄·d·v + c₅·v²

That d·v cross term is the one worth noticing. It encodes the fact that how much your radial velocity matters depends on how far away you are — an interaction a degree-1 fit cannot express at all, no matter how well you tune it.

Which comes first — the model or the surface?

Worth stating plainly, because it's easy to get backwards: the surface is the last step, not a stepping stone towards the model. The model generates the data; the surface merely compresses the winning answers so the robot can look them up quickly. There is no path from a surface back to a model, and none is needed.

Two separate questions, constantly collapsed into one

It is very easy — and it happens constantly — to hear "lookup table vs. polynomial surface" and "empirical vs. physics model" as the same argument. They are not. They're two independent choices, and you make both.

• Where do the numbers come from? Measured by actually shooting balls, or computed by simulating trajectories.
• How is the answer stored? As rows in a table, or as a fitted equation.

A polynomial surface is only a storage format. It says nothing about where its numbers came from — you can fit one straight through hand-measured shots without a line of physics anywhere. All four combinations exist:

Measured versus modelled — the real tradeoff

Read the right-hand column: every property people actually argue about traces back to the data source, not the storage format. Trust, optimisability, effort, and how it fails are all decided by whether the numbers were measured or simulated. Only smoothness and extrapolation come from choosing a fit over a table — real benefits, but cheap ones, and available without any physics at all.

The obvious synthesis — a physics model with an empirically calibrated correction term — is the right instinct, and the last section sharpens it.

The strongest objection — and how to answer it

There is one objection to all of this that carries real weight, and it goes roughly like this: any approach requiring a physics model gives up the great virtue of the measured table — that you need not understand the physical system very well, and can trust in its correctness regardless.

Put plainly: the table works because you measured it, not because you understand why it works — and a model only works if your understanding is right. This is the most serious argument against the whole approach, and it deserves a real answer rather than enthusiasm.

What "trust in its correctness" really means

The table is correct by construction. It is not a claim about the world that could turn out to be false; it is a record of what happened. You wrote 42° at 3 m because balls went in at 42° at 3 m. There is no physics assertion inside it to be wrong about — which is exactly why "correctness" belongs in quotation marks.

A model inverts that. Its authority rests entirely on your understanding being right. Get the drag coefficient wrong, forget that spin decays during flight, switch to a scuffed ball that grips differently, and the model keeps producing confident numbers everywhere with nothing inside it to signal they are wrong.

So the risk moves rather than shrinking. A table fails by incompleteness — no answer beyond where you sampled — and it fails visibly, at the edges. A model fails by wrongness — an answer everywhere, possibly false — and it fails invisibly, anywhere at all.

Where the objection can be answered

It rests on one assumption: that a model's correctness has to be taken on faith. It doesn't — because you already own measurements, and you can deliberately hold some of them back.

What the whole pipeline is actually for

Before taking it apart phrase by phrase, it is worth having the thesis, because the pipeline reads as a grab-bag of unrelated tasks until you see what they are all in service of.

And the thesis underneath all five: the entire pipeline is scaffolding for a single capability — being able to evaluate a shot you never took. Every component exists to serve that, and the chain from physics down to workshop task is tighter than it first appears. Each step below is forced by the one above it.

The approach, phrase by phrase

Every concept in Part Two is now on the table, so the whole approach can be stated in one pass. Here it is with the technical vocabulary marked:

Use precomputed optimal trajectories rather than a linear interpolation + time of flight map. Compute the optimal trajectory by finding the one whose error given a perturbation in exit velocity or hood angle is least, for every distance / radial velocity pair, then use a second-degree approximation to recover hood angle and shooter velocity. Build the physics model by empirically measuring and mapping shooter velocity and hood angle to the ball's exit velocity, which absorbs ball compression, slip and the rest; measure the backspin with a piece of tape and a high-framerate video. Then construct a second, physical model on top of the empirical one to get the actual flight path.

Unpacking the first clause — where the work happens

"Precomputed rather than linear interpolation + time of flight map" is the densest phrase in the whole approach, and it's really about when and where the thinking gets done.

The deeper change is the one printed at the bottom of the figure. Today, motion is handled as a correction — work out the stationary answer, then patch it up for the fact that you're moving. Precomputing handles motion as an input — radial velocity is one of the axes the answer was worked out over in the first place, so there is nothing left to iterate towards.

That is also exactly why the table grows from one dimension to two. The extra dimension is the thing the loop was compensating for.

One thing worth separating out

The usual complaint about the table-only approach is that it "leaves a lot to be desired in terms of accuracy and robustness". Those sound like one complaint but they're two, with different causes and different fixes:

• Accuracy — does it go in when everything is right? Limited by how much you sampled and how well you can extrapolate. Fixed with better data, or a model.
• Robustness — does it still go in when you're 2° off? Requires optimisation, which requires gradients, which requires a model. No amount of extra data delivers it.

Which exposes the useful thing: the change reads as one big yes-or-no, but it's really three separate questions. Two of them are just the axes of the grid from Fig 35 — the third isn't a square on that grid at all.

Questions 1 and 2 are genuinely independent — you can answer either one without touching the other. Question 3 isn't a storage or source choice at all; it's a goal, and it simply becomes available once question 2 is answered "model". Here are all three drawn on the grid you've already seen:

So the thing everyone actually wants, Q3, is invisible until you've paid for Q2 — which is why the discussion keeps collapsing into a single "is the model worth it?". It also means the sensible order isn't the order it is usually presented in:

1. Now: answer Q1 by fitting a surface to the table you already have. Cheap, reversible, and it commits you to nothing — the surface is a cache, as Fig 34 shows.
2. Next: measure whether drag actually matters for your game piece. That single measurement — suggestion 4 in Part Three — is what decides whether Q2 is worth paying for.
3. Then, only if drag matters: answer Q2, and Q3 comes almost for free with it.

The whole pipeline on one page

Everything above, assembled — and separated by when each part happens and where.

The single most useful thing to hold onto is that this runs in three phases, and they are wildly different in character. One happens in a workshop with a camera and about forty-five balls. One happens on a laptop, once, and never again. One happens on the robot fifty times a second. Confusing them is what makes the approach feel like a tangle.

The order is forced — nothing here can be done out of sequence

1. MEASURE   bench, ~25 balls           →  the map
2. MEASURE   field, ~20 balls           →  landing points
3. FIT ①     tune DRAG and MAGNUS       →  a calibrated model

4. SWEEP
   4a  build the grid    — every (cell, candidate) → its miss distance
   4b  difference it     — neighbouring cells give ∂e/∂θ and ∂e/∂v
   4c  score and select  — best candidate per cell  →  ~180 winners
       ↳ the grid itself is discarded here

5. FIT ②     quadratic through the ~180 winners  →  THE SURFACE
6. SHIP      the coefficients

And the derivatives are for selecting, not for fitting

Worth separating, because "derivative" and "fit" sitting near each other suggests one feeds the other. It does not.

∂e/∂θ , ∂e/∂v   →   decide WHICH ~180 points
the fit        →   draw a curve THROUGH those points

The fit never sees a derivative. It is handed 180 rows of (distance, radial velocity) → (hood, RPM) and performs ordinary least squares. It has no notion that those particular shots were chosen for being forgiving; to the fit they are simply points.

What the derivative decides is which point each cell contributes. Cell (4.0 m, 0) has valid shots at 30°, 45°, 60° and everywhere between — all of them score. The derivative is what breaks that tie, and 45° is the row that goes forward.

Each step is blocked on the one before it. You cannot fit the constants without the map, because the model would have no starting velocity. You cannot sweep without calibrated constants, because you would be simulating the wrong physics a hundred and eighty thousand times. And you cannot fit the surface without the sweep's winners, because there would be nothing to fit through.

The two measurements sit at opposite ends of one flight

Steps 1 and 2 are both labelled "measure", which makes them look like the same activity done twice. They are not — they point cameras at opposite ends of the ball's journey and answer different questions.

What each measurement actually produces — and what Fit ① does with it

Both measurements produce a small table of rows. Here is what is genuinely in them.

So Fit ① walks every landing record through the same three steps:

record #7:   RPM 2800, hood 40°, landed at 4.35 m

  1  look up the MAP with (2800, 40°)                  ← measure ① enters here
        → exit velocity 6.27 m/s, spin 7.5 rev/s

  2  simulate with those, plus a GUESS at the constants
        try kd = 0.010, km = 0.004   →   predicted landing 4.51 m

  3  compare against what actually happened            ← measure ② enters here
        residual = 4.51 − 4.35 = +0.16 m

Repeat for all twenty records, square the residuals and add them up. That gives one score for one guess at the pair (kd, km). Then sweep a grid of guesses and keep whichever scored lowest.

Are drag and Magnus really the only things acting on the ball?

No — but they are the two biggest uncertain ones, and that distinction is exactly why the count is two.

Gravity is modelled but fitted for nothing. So of the three forces actually in the equations, only two carry an unknown — which is where "two constants" comes from.

Part Three · Four refinements worth making

The pipeline as described is sound. These are the four places worth pushing on — the first two make the metric honest, the third stops it optimising something dangerous, and the fourth decides whether to do any of it at all.

1 · Weight the sensitivity metric by real uncertainty

The metric as written adds a term measured in miss-per-degree to a term measured in miss-per-metre-per-second. Those units don't combine — adding them assumes your hood error and flywheel error happen to be numerically comparable, which they aren't. Weight each by how badly you actually control that axis:

σ is your measured closed-loop tracking error on each axis. This turns a heuristic into actual variance propagation — and it's a one-line change.

2 · Handle distance uncertainty — but not by adding a term

On most robots, knowing where you are is a bigger error source than hood or flywheel control. Vision latency, tag ambiguity, odometry drift. So it is tempting to add a σd2(∂e/∂d)2 term alongside the other two — it looks like the obvious way to complete the metric.

None of which makes distance error harmless — it is real, often dominant, and simply cannot be reduced by choosing a different shot. So it does not belong in a metric whose only job is choosing between shots.

3 · Make entry angle a hard constraint, not part of the cost

A ball arriving too shallow bounces off the rim no matter how insensitive the trajectory is. Don't let a low entry angle be traded away against good sensitivity — filter the candidate list by minimum entry angle first, then optimise sensitivity over what survives.

4 · Lead with drag — it's the real justification for the 2D table

This one matters most when making the case for the work at all, because without it the whole project is unnecessary.

With no air drag, shooting while moving is exactly equivalent to shooting at a displaced virtual goal. The iterative "guess the flight time, shift the target, re-solve, repeat" trick is essentially exact, and you don't need a 2D table at all — you need the stationary table plus two iterations.

With meaningful drag on a light game piece, that equivalence breaks. The moving shot isn't a stationary shot at a shifted target; it's a genuinely different trajectory with a different shape and a different entry angle, because drag acts on the ball's total velocity — which now includes the robot's contribution.

Where this leaves you

Don't frame it as model versus empirical. That framing is what gets people stuck, and you do not have to pick.

• Fit the model's free parameters — drag coefficient, Magnus coefficient, effective exit velocity per RPM — to your stationary shot data.
• Keep the leftover residuals as a correction surface layered on top.
• Use the model only for the two things a table fundamentally cannot do: smooth extrapolation, and supplying gradients for the robustness optimisation.

The measured table stays ground truth. The model becomes a well-behaved interpolator with derivatives. That preserves exactly the "you can trust its correctness" property you do not want to give up, while unlocking the optimisation you do — which dissolves the tradeoff instead of picking a side.

Glossary