QGIS » QGIS Application

outline of documentation for GPS Information widget

Steven Mizuno

8/3/2011

Conventions used here: 

	[some text] shows the control label; for buttons with icon faces this is the ToolTip displayed

	Indentation is used to show subordinate controls of another control.

	Generally, a short description of the control follows each label.

The control ordering is left to right and top to bottom. All controls for a page are shown under the page's button.

================

The controls of the GPS Information dock widget:

[Add feature] button to add a feature to a map layer; is labeled with the feature type for the selected map layer and is enabled when a suitable layer is selected and is in editing mode

[Quick status] color indicator for a quick glance at GPS position status - green, yellow, red, gray for good or 3D fix, good 2D fix, no fix, no data/GPS disconnected respectively

[Add track point] button manually adds the current GPS position to the track. Is enabled if [Automatically add track points] is off

[Reset track] button clears the track

[Position] button selects the Position page where GPS data are displayed

	[Latitude] latitude of position fix

	[Longitude] longitude of position fix

	[Altitude] antenna altitude with respect to geoid (mean sea level)

	[Time of fix] time of the position fix

	[Speed] speed over ground

	[Direction] nominally course over ground

	[HDOP] horizontal dilution of precision

	[VDOP] vertical dilution of precision

	[PDOP] position dilution of precision

	[Mode] Automatic or Manual 2D/3D GPS configuration

	[Dimensions] 3D, 2D, No fix

	[Quality] Differential, Non-differential, No position

	[Status] Valid, Invalid position fix

	[Satellites] number of satellites used in the position fix

[Signal] button selects the Signal strength graph page

	bar graph showing satellite signal strength

[Satellites] button selects the Satellites location graph page

	polar graph showing satellite locations in the sky

[Options] button selects the Options page for configuring various settings

	[Connection] group to choose the GPS device connection method

		[Autodetect] automatically detects the GPS device (gpsd localhost or serial) on Connect

		[Serial device] specify a serial device from the list to use

			[Serial device list] drop-down list of detected ports

			[Refresh serial device list] refreshes the list of devices

		[gpsd] specify a gpsd data source to use

			[Host]

			[Port]

			[Device]

	[Digitizing] group for feature and track settings

		[Automatically save added feature] enables saving the map layer after each feature is added

		[Track] group for track settings

			[Automatically add points] enable adding track points on valid GPS position fix

			[Width] spin box to set the track width in pixels

			[Color] button to choose the track color

	[Cursor] enables the GPS cursor to show current position

		[size] slider sets the cursor size

	[Map centering] group to choose when the map is centered

		[Always] centers the map on every position fix

		[when leaving] centers the map when the position moves outside a specified percentage of the map extent

			[ % of map extent] sets the percentage of map extent

		[Never] never center the map

	[Log file] enables logging of GPS data (all NMEA sentences sent by GPS)

		[log file] the name of the file that records the GPS data

		[...] browse for log file to save GPS data to

[Connect]/[Disconnect] button initiates connection to a GPS device as specified in the Connection group of the Options page. Once the GPS device is connected it changes to Disconnect to end the connection to the GPS device.

================

Operation:

Showing or hiding the GPS Information dock widget: on the View menu, Panels choose GPS Information to show/hide it alternately. 

It can also be found on the main window context menu (right-click on a blank are of the menu bar, for example). 

The position and size of the window as well as whether docked or floated are saved when QGIS is closed and restored the next time.

When a GPS device is connected the Connection and Log file groups are disabled to prevent making changes that could be confusing as they don't affect the current connection.

Connection status messages are displayed in the main window's status bar.

	Connecting to GPS device...

	Connected to GPS device.

	Disconnected from GPS device.

	Error opening log file.

The Position page fields are cleared on Connect to give a better indication that a new session has been started. After disconnect the last GPS data are still displayed.

The Quick status indicator is used to show GPS position fix status at a glance:

	green		good or 3D fix 

	yellow		good 2D fix 

	red		no fix or bad fix 

	gray		no data/GPS disconnected

The yellow indication is shown only if 2D information is available.

The Add feature button is used to add a feature based on the current GPS position (point) or track (line, polygon) to a map layer. 

This button has an accelerator key (Alt+A in English) to aid in using the keyboard to add a feature.

The button is labeled with the feature type for the selected map layer and is enabled when a suitable layer is selected and the layer is in editing mode.

If a point feature is being added the track will continue to accumulate points if Automatically add points is on.

If a line or polygon feature is added the track is used and is cleared on adding the feature. 

Track points are not added while the Attributes dialog is displayed.

If the Attributes dialog is cancelled the track is not cleared and resumes accumulating points. 

The Add track point button is used to manually add the current GPS position to the track when the Automatically add track points option is off.

Note that the track object displayed is stored in map CRS coordinates. This may cause incorrect location of the track if the map CRS is changed after a track exists. It is best to set the map CRS before connecting to the GPS device.

The stored points are in WGS 84 coordinates and are transformed to the map layer CRS when the feature is added.

(This is rather technical and the user shouldn't have to think about it.)

The Add feature and Add track point buttons are not disabled if the GPS is not connected or no fix is being reported. This is to allow adding a feature or track point after the GPS is disconnected.

It is up to the user to determine when to add the feature or point.

The Reset track button clears the track.

Something to keep in mind: the track is an object drawn on top of the map. It is not a feature of a map layer until it is added to the layer. Then it is just another feature of the layer, and a new track is started.

The Connect / Disconnect button also has an accelerator key (Alt+C in English) assigned.

Except for the Log file options, all settings on the Options page are saved and then restored the next time QGIS is started.

The Log file must be set before connecting to a GPS device as the file will be opened when the GPS is connected and closed when the GPS is disconnected.

At present the log file capability is very basic, with minimal error handling. 

The browse button must be used to choose a file as the text box where the file name is displayed is not editable due to no name validity checking being done.

Data are appended to the file chosen with a ==== marker placed each time the GPS is connected.

Keyboard use: tab order - initially focus is set to the Position page button, then progresses to buttons to the right up through Connect, then Add feature, Add track point, Reset track. Then all buttons on the currently displayed page. Note that the scroll bar also can be tabbed to.

The Options page is displayed initially. The reason for this is to verify GPS connection and other settings, then usually to select the Position page, then tab to Connect and activate this to establish connection to the GPS device. Then tab to Add feature for convenience. The space bar can be used to activate each button.

(This order seems most logical to me.)

Accelerator keys are assigned to Add feature and Connect buttons for ease of use.

Message boxes are kept to a minimum by enabling and disabling various controls so they are available to use only when conditions are correct. 

Mainly, the message boxes popped have to do with not enough points in the track for adding line (2 necessary) or polygon (3 necessary) features, and a potential for a forward transform error if adding a track point before the GPS reports a valid fix.

Closing QGIS will disconnect the GPS device and close the log file. There is no opportunity given to save the current track.

================

Technical information for advanced users:

There is a setting [as in the Windows registry] 

	gps/dateTimeFormat 

which may be used to set a different date/time format string.

There is currently no place provided to set this in the GPS Information widget.

An example to show thousandths of a second:  ddd MMMM d yyyy hh:mm:ss.zzz

This may be useful if a GPS receiver outputs position fixes two or more times per second.