Skyplanr
Language

Gimbal angle and heading on DJI waypoint missions: why the camera levels out or looks sideways

A waypoint mission sets the gimbal and the nose at every waypoint from the file, not from where you left them by hand. Two pilot questions show what that means and how to check the file before you fly.

By Sander Helgesen · Last checked

In short

  • Gimbal pitch and heading are set per waypoint in the KMZ. If the file says 0°, the gimbal goes level, whatever you tilted it to before the start.
  • To keep -45°, put -45° on every waypoint, then open the KMZ and check every pitch value.
  • The gimbal only tilts; the camera looks where the nose points. A fixed heading east on a route that runs south films sideways the whole way.
  • Follow the route for corridors, face the wall for facades, face the centre for orbits.

Two settings per waypoint: pitch and heading

Every waypoint in a DJI mission file carries a heading (where the nose points) and a gimbal pitch (how far the camera tilts down, 0° level, -90° straight down). They are separate settings, and the drone applies both from the file during the mission.

In the gimbal actions DJI Fly writes, and in the files Skyplanr writes, only pitch is set: gimbal yaw is off and follows the aircraft. So the camera looks where the nose points, and the heading decides what is in the frame left to right.

Why the gimbal went back to 0° before every photo

A Matrice 4E pilot flew a loop round a facade. He tilted the gimbal to -45° by hand, and before every photo it went back to 0°, level. The likely cause is in the file, not the drone: the waypoints carried a pitch of 0°, and the mission was set to use them.

DJI Pilot 2 files have a mission-wide gimbalPitchMode. DJI's WPML reference gives two values. usePointSetting: "Set according to each waypoint", with the pitch transitioning evenly to the next waypoint's pitch on each leg. manual: the pilot controls the pitch between waypoints, and without input the gimbal keeps the pitch it had leaving the waypoint. With usePointSetting and every gimbalPitchAngle at 0, the mission levels the gimbal on every leg, and a hand tilt lasts only until the next one. A gimbalRotate action to 0° at a waypoint does the same in either mode.

The fix is to put the angle in the file rather than in your thumb: -45° on every waypoint. Leaving the mode on manual and tilting by hand works only as long as no waypoint or action sets a pitch, and you get a different angle on every pass.

Heading modes: follow the route, fixed, or toward a point

DJI's WPML reference defines the heading per waypoint (waypointHeadingMode). Three modes cover nearly every job:

Heading modes in a DJI waypoint file and where the camera looks

  • Follow the route

    In the file
    followWayline
    Where the nose and camera point
    Along the leg to the next waypoint
    Use for
    Corridors, mapping lines, flying forward

  • Fixed heading

    In the file
    smoothTransition with the same angle on every waypoint (0 = north, 90 = east)
    Where the nose and camera point
    One compass direction, whichever way the drone flies
    Use for
    Side views, a facade side, a straight dolly shot

  • Toward a point

    In the file
    towardPOI, or smoothTransition with the bearing to the point on each waypoint
    Where the nose and camera point
    At the point of interest
    Use for
    Orbits, push-ins, a house or a mast

Why the river was filmed sideways

A pilot asked for "point the drone east, camera pointing forward" on a river corridor. The river ran south. The plan took "east" literally: a fixed heading of 90° on every waypoint. The drone flew south with its nose east, so the camera filmed the east bank, at a right angle to the river, the whole way.

"Forward" on a line means follow the route: the nose turns with each leg, and the camera looks down the river wherever it bends. A fixed compass heading is for when you want the side view. Flying sideways also means the forward sensors face away from the direction of travel; Skyplanr's checks warn about legs flown sideways or backward without sensing on that side.

Keep a gimbal angle for the whole mission

For a facade loop at -45°, or any mission where every photo needs the same tilt.

  1. Set the pitch on every waypoint

    In the planner, give each waypoint the pitch, -45° here, not only the first one. The gimbal tilts evenly along each leg to the next waypoint's pitch, so one waypoint at 0° levels it on the way there.

  2. Check gimbal actions

    Remove or change any gimbal action that sets another angle at a waypoint. It runs on arrival, before the photo.

  3. Leave pitch mode on the waypoints

    For DJI Pilot 2, keep gimbalPitchMode at usePointSetting, so the file's angle wins over a stray thumb on the tilt wheel.

  4. Check the exported file

    Open the KMZ as below and confirm every pitch value is -45 before you copy it to the controller.

Check heading and gimbal in the KMZ before flying

Five minutes at a computer, on a copy of the file.

  1. Open the KMZ

    A KMZ is a ZIP archive. Copy it, rename the copy to .zip, unpack it and open wpmz/waylines.wpml in a text editor; that is the file the drone flies.

  2. Find the pitch values

    Search for gimbalPitchRotateAngle. It appears in the gimbalRotate action on the first waypoint and in a gimbalEvenlyRotate action on every leg. Each value is the pitch the gimbal reaches at that waypoint; for a -45° mission, all of them read -45.

  3. Ignore the 0/0 block in DJI Fly files

    DJI Fly files also have waypointGimbalPitchAngle 0 and waypointGimbalYawAngle 0 on every waypoint. DJI Fly writes 0 there in its own files too; the pitch lives in the actions. In a DJI Pilot 2 file, also open wpmz/template.kml: gimbalPitchMode should be usePointSetting and each waypoint's gimbalPitchAngle your angle.

  4. Read the heading of each waypoint

    Search for waypointHeadingMode. followWayline follows the route. smoothTransition points the nose at waypointHeadingAngle (0 north, 90 east, -90 west, 180 south): compare it with the direction of the route on the map. towardPOI faces waypointPoiPoint, written latitude first.

  5. Open the mission without editing it

    In DJI Fly, open the mission to check it but don't edit or save it on the controller: DJI Fly then rebuilds it from template.kml, and the waypoints can change. If you did, install the file again. On the first flight, keep the drone in sight and watch the camera view on the first leg.

Which heading for which job

  • Corridors (rivers, roads, shorelines, pipelines): follow the route, one gimbal pitch on every waypoint, -45° for a forward look or -90° for a strip straight down.
  • Facades: a fixed heading per photo, facing the wall, at a constant distance, with the pitch set per photo from the distance and height. Stop at each photo, with a short hover before it.
  • Orbits round a house, tower or mast: toward the centre, the pitch set from the radius and height.
  • Mapping grids: follow the route, so the nose and forward sensors lead every line. Photos alternate 180° between lines, which photogrammetry handles.
  • Side views from a line: a fixed heading, only when you want the camera across the track, and expect less sensing in the direction you fly.

DJI Fly, DJI Pilot 2 and Litchi

Both DJI apps read WPML, but the files differ in where the gimbal is set:

Skyplanr's Pilot 2 files follow DJI's reference and real Pilot 2 exports but have not been flight-tested yet, so fly the first route in sight. Litchi reads a CSV instead: Skyplanr's Litchi CSV carries a heading and a gimbal pitch (gimbal mode interpolate) on every waypoint. The heading mode is a Litchi mission setting the CSV can't carry, so set it to Waypoint Defined (Custom on iOS) in Litchi.

How DJI Fly and DJI Pilot 2 files set gimbal pitch and heading

  • Drones

    DJI Fly
    Consumer drones such as the Mini 4 Pro, Air 3S and Mavic 3 Pro
    DJI Pilot 2
    Enterprise drones such as the Matrice 4E, Matrice 4T and Matrice 30

  • Gimbal pitch

    DJI Fly
    Gimbal actions: one on the first waypoint, one per leg
    DJI Pilot 2
    The same actions, plus a pitch per waypoint in the template

  • Pitch mode

    DJI Fly
    No mission-wide setting in DJI Fly's files
    DJI Pilot 2
    usePointSetting or manual

  • Toward a point

    DJI Fly
    Skyplanr writes the bearing to the point on each waypoint
    DJI Pilot 2
    DJI's native toward-point mode

  • Getting the file in

    DJI Fly
    Replace a placeholder mission's file
    DJI Pilot 2
    Import from a microSD card or USB drive, or through FlightHub 2

Where Skyplanr fits in

Skyplanr sets the gimbal pitch on every waypoint, so the file carries the angle you planned, and keeps the nose along a line such as a river or road unless you ask for a side view: "point east, camera forward" on a line that runs south is flown forward, and the summary says so first. Facade rings face the wall at every photo, and orbits face the centre. You get a KMZ for DJI Fly or DJI Pilot 2, or a Litchi CSV. 3 AI plans a month are free; see pricing.

See the technology

Questions

Why does my gimbal go back to 0° during a DJI waypoint mission?

The mission file sets the pitch at each waypoint, and those waypoints say 0°. With `gimbalPitchMode` `usePointSetting` (DJI Pilot 2), the gimbal tilts to each waypoint's pitch on every leg, so a hand tilt lasts only until the next waypoint. Set the angle on every waypoint and check the exported file.

What is the difference between usePointSetting and manual gimbal pitch?

In DJI's WPML reference, `usePointSetting` takes the pitch from each waypoint and tilts evenly between them. `manual` leaves the pitch to the pilot between waypoints and keeps the last pitch without input. A gimbal action at a waypoint still sets its angle in either mode.

Why did my waypoint mission film sideways?

The heading was fixed to a compass direction while the route ran another way. The camera looks where the nose points, so a fixed heading east on a route south films at a right angle to the route. Use follow the route for a forward view.

How do I check the gimbal angle in a KMZ before flying?

Rename a copy to .zip, open `wpmz/waylines.wpml` and search for `gimbalPitchRotateAngle`: every value should be your angle. The `waypointGimbalPitchAngle` 0 in DJI Fly files is normal; the pitch is in the actions.

Sources

Skyplanr is not affiliated with the third-party guides linked here.

  1. DJI Developer: DJI WPML overview (the KMZ format DJI Fly reads) (developer.dji.com)
  2. DJI Developer: DJI WPML template.kml reference (gimbalPitchMode: usePointSetting or manual) (developer.dji.com)
  3. DJI Developer: DJI WPML common elements (waypointHeadingMode, gimbalEvenlyRotate) (developer.dji.com)
  4. eyelanoesis/drone-mission-planner: reference KMZ files written by DJI Fly itself (github.com)
  5. Litchi Utilities: Litchi CSV format (heading and gimbal pitch per waypoint) (litchiutilities.com)
  6. Litchi: help (Mission Hub Above Ground altitudes, CSV and KML export, one purchase per platform) (flylitchi.com)

This guide describes how DJI Fly behaved when it was last checked; DJI can change the app at any time. It is advice, not a permission: you are the pilot in command, and the site, the geo-zones and the rules are yours to check before takeoff.

Let Skyplanr write the file.

Describe the job, and Skyplanr plans the waypoint mission, checks it and gives you the KMZ for DJI Fly.

Get started freeSee pricing