Part 2 · From a real drone's spec sheet to a testable task2편 · 실제 드론 스펙에서 검증 가능한 과제로第 2 篇 · 从真实无人机的规格表到可检验的任务

Part 1 ended with a fast simulator. Fast isn’t the same as believable, and believable isn’t the same as testable. Before training anything, I wanted three things fixed: which parts of a real drone the simulation copies, what exactly a policy sees and outputs, and how a flight is scored. If those move later, every result moves with them.

1. A spec sheet, filtered by scale

I took the spec sheet of a real consumer drone, the DJI Mavic 4 Pro, and went through it item by item. The simulated airframe is a Bitcraze Crazyflie 2.x: the physics parameters in gym-pybullet-drones (mass, inertia, thrust, drag) come from that real product.

A 40x difference in mass means absolute numbers such as “25 m/s” can’t transfer. So every spec item went into one of three bins:

2. The camera: a gimbal, tilted down

In Part 1 the camera was bolted to the body and looked straight ahead. That has two problems. Half of every frame was sky, and when the drone pitches forward to accelerate, the whole image tilts with it. The Mavic carries its camera on a 3-axis gimbal, which keeps the image level. So the simulated camera now does the same, tilted 20° down, with the Mavic’s 72° (diagonal) field of view.

Tilting 20° down also moves the pixels from sky to floor and targets, which fixes Part 1’s “half the frame is sky” finding. The targets became 1.2 m pillars so they stay in view all the way to the stopping point. At the start, each target fills 1.5–4.5% of the frame; at the stopping point, the named one fills 36–43%.

3. Position noise, chosen against the expert

A real drone doesn’t know exactly where it is. Its position estimate drifts slowly. I added a noise process to the position the controller sees. The camera still renders from the true position, because it is physically on the drone. The size, 3 cm horizontally and 1 cm vertically, is a choice. It keeps the Mavic’s 3:1 ratio, scaled down to fit a small room.

The timing of the noise took more work. My first version was jumpy, and the scripted expert (a controller that knows the true positions) began to fail: it couldn’t hold still after stopping, because the controller chased the jumping estimate as if it were real motion.

This choice was tuned on one set of seeds, so those 20/20 don’t count as evidence. On 40 held-out episodes that I never looked at while choosing, the expert succeeded in all 40.

Wind and a tilt limit exist as well. The dataset in Part 3 uses noise and the tilt limit but keeps wind off; the details are in the appendix.

4. The contract every policy must satisfy

This is the most important picture in the series. Every policy, from the tiny one in Part 4 to SmolVLA later, has to fit into it.

Two details matter:

• The action is a velocity request, not motor speeds. The policy says “go 0.4 m/s forward, 0.1 m/s left”. A PID controller underneath turns that into motor commands 12 times per decision. So the policy only has to learn where to fly.
• One adapter enforces the limits, for everyone. The expert, the learned policies and later the C++ runtime all go through the same function (full code):

def adapt(raw, limits=ActionLimits(), planar=True):
    """Validate and cap one raw policy action. Never raises on bad numbers -- it reports."""
    raw = np.asarray(raw, dtype=np.float64).reshape(-1)
    if raw.shape != (5,):
        return AdaptedAction(..., rejected=f"wrong shape {raw.shape}, expected (5,)")
    if not np.all(np.isfinite(raw)):
        return AdaptedAction(..., rejected="non-finite value in action")

    vx, vy, vz, yaw_rate, stop_logit = raw
    speed = math.hypot(vx, vy)
    if speed > limits.horizontal_mps:            # 0.5 m/s, capped as a vector, not per axis
        vx, vy = vx * limits.horizontal_mps / speed, vy * limits.horizontal_mps / speed
    ...                                          # same for vz (0.3 m/s) and yaw rate (0.5 rad/s)
    return AdaptedAction(applied=np.array([vx, vy, vz, yaw_rate]),
                         stop_positive=bool(stop_logit > 0.0), flags=flags)

The adapter records which limit engaged in flags, so “the policy asked for too much” is always visible in the logs instead of silently corrected.

5. The task, and how a flight is scored

The scene. An 8 x 8 x 3 m room. The drone starts on one side at 1 m altitude. Two pillars with different colours stand on the other side. Each has a hover point 0.75 m in front of it, where the drone should stop.

One episode. The drone gets one sentence, such as “Go to the red box and stop.”, and flies. To stop, the policy must signal Stop three decisions in a row (0.6 s). The drone then holds position for one second while the evaluator watches.

Success means all of these, judged on the true simulator state:

• within 0.4 m of the named hover point,
• slower than 0.1 m/s for the whole second after Stop,
• no collision, and within 30 s.

Everything else is a named failure, because “failed” alone teaches nothing:

Pair success is the metric the series is built around. Each layout is flown twice from the identical start, once per sentence. A pair counts only if both flights succeed. A policy that ignores the words and always picks one pillar can still score 50% on single episodes, but its pair success is zero.

Testing the scorer itself. An evaluator with a bug produces believable wrong numbers. So each outcome has a test that causes it on purpose: fly to the wrong pillar, ram a target, signal Stop while still moving, and so on. The evaluator must name every one correctly. The same test suite (79 tests at the commit below) also covers the action contract, the environment API and pair determinism: both flights of a pair get byte-identical first images.

What this part does not show

• This is not a Mavic. It is a 27 g quadrotor with a Mavic-like camera and noise profile.
• The 3 cm noise size is a choice, not a measurement. The 72° field of view assumes DJI quotes it diagonally, their usual convention.
• Everything is simulation.

Next

The task and scorer are fixed. Part 3 builds the dataset: 120 pairs of flights where the same image comes with two different sentences.

Appendix

python -m pytest tests -q                    # includes one fixture per outcome
python scripts/try_env.py --headless         # same start, two instructions, two outcomes
python scripts/playground.py --headless      # camera mount, noise, wind: change and re-run
python scripts/figures/blog02_04.py          # every figure in parts 2-4

References: what I took from each

• DJI Mavic 4 Pro specs give the camera, gimbal, tilt and hover-accuracy numbers. → I copied only the items whose meaning doesn’t depend on size.
• Bitcraze Crazyflie 2.1 is the real airframe behind the simulated one. → Its mass and motor model are why the absolute speeds stay small.
• Gymnasium: create a custom environment defines reset/step, terminated vs truncated. → A timeout is a truncation, not a failure state, which is why timeout is scored separately.

Summary (STAR)