Using an External GPS Device with Ladybug Cameras
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.
|Port Number||The port to which the GPS receiver is connected. To determine the port, expand the Ports node in the Windows Device Manager. LadybugCapPro does not automatically detect this setting upon startup|
|Baud Rate||The signaling event rate at which the GPS receiver communicates with the PC. This rate is limited by what the GPS unit supports. The NMEA 0183 standard supports the default value of 4800.|
|Data Update Interval||The time interval at which positional data is updated from the GPS to the PC. This rate can be set up to the maximum supported by the GPS unit. The default value is 1000 ms.|
|Start GPS when starting LadybugCapPro||When checked, specifies that the GPS unit should transmit positional data as soon as the LadybugCapPro application starts in live camera mode, using the existing settings.|
|Google Map Height /Google Map Width||Specifies the dimensions of the Google Maps that are generated. These dimensions affect the amount of area covered in the maps, rather than their resolution.|
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:
- Right click on "My Computer".
- Click on the Hardware tab and click the "Device Manager" button.
- 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:
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.