flightplan2litchimission

fp2lm is a command-line tool for converting the output generated by the Flight Planner plugin for QGIS to a Litchi mission.

Usage

fp2lm [options] < FlightplannerMission.csv > LitchiMission.csv

Options

• -d <distance>: Sets the interval between projection centres (meters 'm' or feet 'ft'). Example: -d 20m
• -altitude-mode <mode>: Source of altitude data, either asl (absolute) or agl (above ground level). Default: agl
• -pitch <angle>: Gimbal pitch angle (-90 to 0 degrees). Default: -90
• -max-altitude <meters>: Maximum allowed altitude AGL in meters. Default: 120 (to comply with regulations)
• -output <path>: Output file path (if not specified, writes to stdout)

Description

fp2lm reads a stream of waypoints generated by Flight Planner for QGIS and converts them to properly-structured Litchi Mission waypoints. The tool supports both Above Ground Level (AGL) and Above Sea Level (ASL) altitude modes, and provides safeguards to prevent exceeding regulatory altitude limits.

Building from source

Prerequisites

• Go 1.21 or later

Build

git clone https://github.com/pdfinn/flightplan2litchimission.git
cd flightplan2litchimission
make

This will produce a fp2lm binary in the current directory.

Cross-Compile for Multiple Platforms

make cross-compile

This will create binaries for Linux, macOS (Intel and Apple Silicon), and Windows in the dist/ directory.

Create Release Archives

make release

This builds binaries for all platforms and packages them into compressed archives (tar.gz for Linux/macOS, zip for Windows).

Run tests and linters

make check

Installing

Pre-compiled binaries

Pre-compiled binaries for Windows, macOS, and Linux are available from the Releases page. Simply download the appropriate package for your operating system.

• Windows: Download fp2lm_windows_amd64.zip
• macOS (Intel): Download fp2lm_darwin_amd64.tar.gz
• macOS (Apple Silicon): Download fp2lm_darwin_arm64.tar.gz
• Linux (x86_64): Download fp2lm_linux_amd64.tar.gz
• Linux (ARM64): Download fp2lm_linux_arm64.tar.gz

Alternatively, you can build from source by following the instructions below.

Mac OS

Quick Start (using pre-compiled binary)

1. Download the appropriate package for your Mac from the Releases page:

   • For Intel Macs: fp2lm_darwin_amd64.tar.gz
   • For Apple Silicon Macs: fp2lm_darwin_arm64.tar.gz

2. Extract the archive:

   tar -xzf ~/Downloads/fp2lm_darwin_*.tar.gz
   

3. Make the binary executable and run it directly:

   chmod +x ./fp2lm
   ./fp2lm -d 20m < FlightplannerMission.csv > LitchiMission.csv
   

Advanced Setup (adding to PATH)

Open the Terminal, and copy the commands below. Change any bracketed [] portions to reflect your particular environment.

1. Create a folder named bin in your home folder:

mkdir ~/bin

2. Move the fp2lm binary from the download location to the newly-created bin folder:

mv ~/Downloads/fp2lm_darwin_*/fp2lm ~/bin/fp2lm

3. Make the fp2lm programme executable:

chmod u+x ~/bin/fp2lm

4. Open the Terminal and update your PATH to include the bin folder with the following command:

export PATH=/Users/[your home folder]/bin:$PATH

5. To make the update to your PATH permanent, append the updated path to your user profile:

echo "export PATH=/Users/[your home folder]/bin:$PATH" >> ~/.zshrc

6. You may now run fp2lm from the command line as described above at 'Usage:'. For example, assuming you saved your QGIS Flightplanner flight plan as FlightplannerMission.csv on your desktop, and have determined you want twenty-meters between projection centres, you may run the following command:

fp2lm -d 20m < ~/Desktop/FlightplannerMission.csv > ~/Desktop/LitchiMission.csv

Linux

Quick Start (using pre-compiled binary)

1. Download the appropriate package for your system from the Releases page:

   • For x86_64 systems: fp2lm_linux_amd64.tar.gz
   • For ARM64 systems: fp2lm_linux_arm64.tar.gz

2. Extract the archive:

   tar -xzf ~/Downloads/fp2lm_linux_*.tar.gz
   

3. Make the binary executable and run it directly:

   chmod +x ./fp2lm
   ./fp2lm -d 20m < FlightplannerMission.csv > LitchiMission.csv
   

Advanced Setup (adding to PATH)

Open the Terminal, and copy the commands below. Change any bracketed [] portions to reflect your particular environment.

1. Create a folder named bin in your home folder:

mkdir ~/bin

2. Move the fp2lm binary from the download location to the newly-created bin folder:

mv ~/Downloads/fp2lm_linux_*/fp2lm ~/bin/fp2lm

3. Make the fp2lm programme executable:

chmod u+x ~/bin/fp2lm

4. Open the Terminal and update your PATH to include the bin folder with the following command:

export PATH=/home/[your home folder]/bin:$PATH

5. To make the update to your PATH permanent, append the updated path to your user profile:

echo "export PATH=/home/[your home folder]/bin:$PATH" >> ~/.profile

6. You may now run fp2lm from the command line as described above at 'Usage:'. For example, assuming you saved your QGIS Flightplanner flight plan as FlightplannerMission.csv on your desktop, and have determined you want twenty-meters between projection centres, you may run the following command:

fp2lm -d 20m < ~/Desktop/FlightplannerMission.csv > ~/Desktop/LitchiMission.csv

Windows quick-start (no Go required)

1. Grab the latest fp2lm_windows_amd64.zip from
   https://github.com/pdfinn/flightplan2litchimission/releases

2. Un-zip anywhere (e.g. Desktop)

3. Open PowerShell in that folder and run

   .\fp2lm.exe -d 20m < FlightplannerMission.csv > LitchiMission.csv

For more advanced usage, you may want to add the executable to your PATH:

1. Create a Bin Directory

   • Open Windows PowerShell.
   • Create a folder named bin (or name of your choice) in your home directory by executing:

     mkdir $HOME\bin

2. Move the fp2lm Binary

   • Move the fp2lm.exe binary from your download location to the newly-created bin folder. Assuming it is in your Downloads folder, use:

     Move-Item $HOME\Downloads\fp2lm.exe $HOME\bin\fp2lm.exe

3. Update the PATH Environment Variable

   • Add the bin directory to your system's PATH environment variable. This can be done temporarily (just for the current session) by executing:

     $Env:PATH += ";$HOME\bin"

   • For a permanent change, you will need to add $HOME\bin to the PATH environment variable through System Properties or by using the System Environment Variables settings.

Project structure

• cmd/fp2lm/main.go - Entry point for the command-line tool
• cmd/polyorbit/main.go - Experimental polygon flight path utility
• fp2lm/ - Core conversion logic
• missioncsv/ - CSV formatting for Litchi missions
• lenconv/ - Length conversion utilities
• polyorbit/ - Experimental polygon flight path generation
• fp2lm/testdata/ - Test data files
• examples/ - Example input and output files

Steps to produce a Litchi Mission using QGIS

This guide assumes the reader is already familiar with Litchi, but may need help with the workflow in QGIS.

1. Install the flight_planner plugin from QGIS → [Plugins] → [Manage and Install Plugins...] and search for 'Flight Planner'.
2. Load the map layer of your choice. To use Google Earth or OpenStreetMap, select 'XYZ Tiles' in your project's browser and add it as a layer to your project by double-clicking or right-clicking and selecting 'Add Layer to Project'.
3. Scribe your Area of Interest (AoI) by creating a new shapefile layer from [Layer] → [Create Layer] → [New Shapefile Layer]. Select 'Polygon' as the Geometry type. Select the desired points on the map. ℹ️ Depending on the CRS you are using, you may need to change the CRS of the AoI to work with Flight Planner — which requires measurements in meters.
4. Follow the instructions for Flight Planner to plan your flight. ℹ️ If you are using a DJI drone, you will probably need to add your own camera lens. Consult the manufacture's specifications.
5. You will need to create latitude and longitude coordinates for use by Litchi. Fortunately, QGIS makes this easy. With the flight plan generated, select the waypoints layer in the newly-created flight_design layer group. Select [Vector] → [Geometry Tools] → [Add Geometry Attributes]. Select your AoI layer, and calculate the latitude and longitude coordinates using an appropriate CRS (for example, EPSG:4326). Add the new layer to your project. ℹ️ The newly-created layer will have two new fields for latitude and longitude called xcoord and ycoord. You may verify the new values by right-clicking on the layer and selecting Open Attribute Table.
6. Export the new layer with latitude and longitude points added to a CSV file. ℹ️ If the steps were correctly followed, the exported file should have the following header: ️Waypoint Number,X [m],Y [m],Alt. ASL [m],Alt. AGL [m],xcoord,ycoord
7. Measure the distance between projection centers (in the flight_design layer), you will supply this value to fp2lm in the final step.
8. Run fp2lm against the CSV file as described above with the distance between projection centres obtained in the step above set using the -d option.

NOTE: fp2lm expects CSV input in the form of navigation waypoints. The converter automatically inserts a "take photo" action at every waypoint so that images are captured even when the drone is turning, as distance-based intervals alone can miss photos. At the time of this writing, Litchi missions are limited to 99 waypoints. If waypoints are used to trigger additional actions the limit can be quickly consumed, so for this workflow they are primarily reserved for course changes. Photo spacing can still be configured by measuring the distance between projection centres in QGIS, setting that distance in fp2lm with the -d flag, and configuring Litchi to photograph at equal distance intervals. This remains a reliable approach until Litchi supports more waypoints.