Using an External GPS Device with Ladybug Cameras

Supported Products

Ladybug5+

Ladybug6

Overview

The Ladybug library has the ability to interface with a GPS device and insert NMEA sentence data into Ladybug images. The data can then be extracted at a later time and be used to generate HTML data, which can be displayed as a Google Map, or KML data, which can be loaded into Google Earth.

Note: the Ladybug camera has a pulse per second (PPS) feature that allows you to synchronize the timestamps of images with GPS time. For information on working with PPS to synchronize to GPS time, see Using PPS to Synchronize with External GPS.

Working with GPS Data

You can use a GPS receiver in conjunction with a Ladybug camera to record GPS data with stream files, generate Google Map or Google Earth files, and download a GPS data file.

You can record images to stream files when the GPS location changes after a specified distance. This feature is available using the Ladybug API. For more information, see the ladybugSimpleRecording example.

When using a GPS receiver with your Ladybug, keep in mind the following:

• Your GPS receiver should have a serial or USB interface for connecting with your laptop and be able to stream NMEA 0183 data in real time.
• To provide reliable data, your GPS device should show a connection with at least 3 satellites.
• It may take some time between when you first connect the GPS device to your PC and when it is recognized and configured for use with LadybugCapPro.
• The following GPS NMEA data structures are supported: GPGGA, GPGSA, GPGSV, GPRMC, GPZDA, GPVTG and GPGLL.

Using GPS with the LadybugCapPro

Configuring the GPS Receiver

Before capturing GPS data, use the LadybugCapPro Options button on the Main Toolbar to specify some basic settings for communicating with your GPS receiver.

Recording GPS Data and Generating Map Files

Once you have configured your GPS receiver, you are ready to use the GPS toolbar to record GPS data and generate Google Map or Google Earth files.

• Click the  icon to begin receiving positional data from the GPS unit. When used in conjunction with Capturing Stream Files, GPS data is saved with the stream file. This control is not available in recorded stream mode. Click again to stop GPS recording.
• Click the   icon to create a Google Map file from the GPS data that was previously recorded with the stream file. This also allows you the option to load it. An internet connection is required to view the file. Google Maps are saved as .html files in the bin folder of the Ladybug installation directory. This control is not available in image capture mode. 
• Click the  icon to create a Google Earth file from the GPS data recorded with the stream file. This also allows you the option to load it. The Google Earth application and an internet connection are required to view the file. Google Earth files are stored as .kml files in the bin folder of the Ladybug installation directory. This control is not available in image capture mode. 

You can download the data file containing the GPS data for each frame of a recorded stream file. From the GPS menu item, select Generate GPS/frame information. After the file is generated, a dialog box informs you of the location of the file.

Using GPS with the Ladybug API

For a code example, please see the ladybugSimpleGPS example. Examples can be accessed from:
Start Menu -> Point Grey Ladybug SDK-> Examples

Detecting the GPS COM Port

Using the GPS functionality requires the use of a GPS device. The COM port that the GPS device is connected to must be known. To determine the port, perform the following steps:

1. Right click on "My Computer".
2. Click on the Hardware tab and click the "Device Manager" button.
3. Expand the "Ports (COM & LPT)" node and note the COM port that the GPS device is mapped to.

Recording GPS Data and Generating Map Files

The following steps provide a brief overview of how to use the GPS functionality of the Ladybug library:

1. Create a GPS context (LadybugGPSContext) by calling ladybugCreateGPSContext(). This may be done at the same time as the creation of the Ladybug camera context.

2. Register the GPS context with the Ladybug camera context by calling ladybugRegisterGPS(). A single GPS context can be registered with several Ladybug camera contexts.

3. Initialize the device by calling ladybugInitializeGPS().

4. Start the GPS device by calling ladybugStartGPS(). This may be called when ladybugStart() is called. It takes about 5 seconds for the GPS data to become available.

5. Once image grabbing is active, there are several options for image grabbing. The options are:

Getting NMEA data from a GPS device or LadybugImage

The functions ladybugGetGPSNMEAData or ladybugGetGPSNMEADataFromImage can be used to get a single NMEA sentence from a GPS device or LadybugImage. This is usually sufficient if only a small set of values are needed (for example, only latitude and longitude).

If all the sentences are required, calling ladybugGetAllGPSNMEAData or ladybugGetAllGPSNMEADataFromImage will populate a LadybugNMEAGPSData structure with all the supported NMEA sentences (if available).

Each NMEA structure has a boolean value called bValidData. This value is true only if the data contained in that structure is valid.

Getting GPS data from a LadybugImageInfo structure

When grabbing images in JPEG mode, a filled LadybugImageInfo structure is available in each LadybugImage. When the GPS functionality is active, the following values are populated:

• dGPSAltitude
• dGPSLatitude
• dGPSLongitude

If any of these values are equal to LADYBUG_INVALID_GPS_DATA, then they should be considered invalid.

6. Once image grabbing has been completed, call ladybugStopGPS() to stop data acquisition from the GPS device.

7. Unregister the GPS context by calling ladybugUnregisterGPS().

8. Destroy the context by calling ladybugDestroyGPSContext().

9. If a stream context has already been initialized for reading, calling ladybugWriteGPSSummaryDataToFile with the relevant LadybugGPSFileType generates GPS data for the entire stream file.