Waypoint Plotter Control
Updated December 27, 2008
Download Waypoint.ocx Visual Studio Control

The NMEA Sage Waypoint Plotter ActiveX Control will accept many thousands of waypoints and plot them onto a fully resizable viewport. It will handle any ocean, and the viewport may span any distance from a few hundred feet up to 12,000 miles or so. Distances may be calculated in Nautical Miles, Standard (Imperial) Miles, or Kilometers. Thus one may plot way points from San Diego to Hawaii, for example, and down to islands in the South Pacific, and they will all be plotted on the viewport.

The control's internal waypoint symbols table conforms to Garmin's standards (see table below).

Features that are controllable by the end user are also exposed to the programmer; this allows the programmer to "turn off" the control's built-in user interface (the button bar on the right of the control) and provide an entirely different user interface to the user if the programmer wishes.

Using the computer mouse's right button, one may "drag" a rectangle on the view port to resize and recenter the viewport within a collection of waypoints. Start at one corner, push and hold down the mouse's right button, move the mouse cursor to the diagonally opposide corner, then let go of the mouse button: the latitude and longitude distance within that rectangle will be displayed in the bottom left corner, and then the viewport will be redrawn to fit that rectangle.

The control calculates a "best fit" based upon the dimentions of the viewport.

The computer's left mouse button may be used to show direction and distance from any point on the viewport to any other point. The directions are True or Magnetic; the distances are selectable between Nautical Miles, Standard Miles, and Kilometers.

When the mouse's cursor is moved around the viewport without any button being held down, the latitude and longitude for where the pointer is located will show in the bottom left corner of the control.

Three different Latutude and Longitude formats may be specified.

NOTE: all Longitudes and Latitudes entered into the control must be in decimal notation only [DD.DDDDDD]. "Degrees and minutes" [DD M.MMMM] or "degrees minutes seconds" [DD:MM:SS] will be rejected.

The bottom caption area may be hidden via the "C" button, or programatically via the ShowCaptions Property.

Note that there is no button to hide the Button Bar. The Button Bar may only be hidden programatically via the ShowButtons Property.

The "I" button displays an Information dialog window that gives viewport data.
The "S" button allows the user to configure parts of the control via the Settings dialog box.

The Zoom increment is used to "zoom in" and "zoom out" via the ">" and "<" buttons. This value is also used to pan north, south, east, and west via the tiny arrows in the corner of the viewport.

If there is boat position data, a symbol of a boat may be drawn on the viewport. That boat may also be kept in the center so that when boat position data is updated, waypoints scroll past the boat symbol while the boat symbol stays in the center of the viewport. If the Boat Centering feature is turned off, the boat will be allowed to "steam" off the edge of the viewport.

The "T" button toggles between displaying waypoint symbols and waypoint Identification labels. A waypoint may be given an ID of from 1 to 256 characters. The AddWaypoint Property is used to add a waypoint to the control.

   With WaypointPlotter1
      .AddWaypoint ID, Lat, Lon, SymbolNumber, Alarm, WPColor
   End With
.Alarm and .WPColor are optional.

NOTE: North latitudes must be positive; South latitudes must be negative; East longitudes must be positive; West longitides must be negative. Therefore, for example, San Diego California will be entered via:

   With WaypointPlotter1
      .AddWaypoint "SANDIE", 32.73, -117.17, 1, 1.25
   End With
The "Alarm" value is a single-precision number that specifies how many Nautical Miles, Standard Miles, or Kilometers the boat must come to a waypoint for the ArrivalAtWaypoint Event to occur. The event will be raised every time the boat's position is updated while the boat is within that distance to the waypoint: to silence the alarm (i.e., shut off the event), the SilenceAlarm Method is used:
   Private Sub WaypointPlotter1_ArrivalAtWaypoint(Wayp....)
      '   play alarm.wav or some other code
      WaypointPlotter1.SilenceAlarm WaypointNumber
   End Sub
If the WaypointSymbol number equals -1, you may also specify a color for that waypoint; the waypoint will be drawn as a dot in that color.
    Dim ID As String, Lat As Single, Lon As Single, MyValue As Integer
    Open "C:\temp\springs.txt" For Input As #1
    Do
        If EOF(1) Then Exit Do
        Input #1, ID, Lat, Lon
        WaypointPlotter1.AddWaypoint ID, Lat, Lon, -1, , vbBlue
    Loop
    Close
The "W" button displays a list of waypoints.
The settings dialog box has an option to show the "center hairs" or hide them. If the boat's position is used as the center, the cross hairs will not be shown.
If the control is told where the boat is (via the BoatLat and BoatLon Properties and/or via the BoatPosition Method) the boat's position may be used as the center of the viewport. The "B" button toggles this feature on and off: when the feature is off, a "B" is displayed; when the feature is on, a "b" is displayed.
    WaypointPlotter1.BoatPosition 35.514189, -116.368779
With "Boat Centering" turned on, subsequent updates of the boat's position will cause the waypoints around the boat, if any, to move while the boat stays in the center of the viewport. With "Boat Centering" off, the waypoints stay where they are and the boat moves.
The control must be told where the boat is before it can center the viewport on the boat.

NOTE: you do not need to tell the control where the boat, if any, is. The control will work without any boat information.

NOTE: If no boat information is entered, the control will USE THE FIRST WAYPOINT to center on, or the control may be told the latitude and longitude to center on via either the CenterLat and CenterLon Properties or the CenterViewport Method.

The programmer may pan the viewport simply by moving the viewport's center latitude and center longitude around.

The control reports how many waypoints are within the viewport and how many waypoints are outside the viewport.

The "A" button will scale the viewport into a "best fit" that will place all waypoints into view. This excludes the boat symbol when "Boat Centering" is turned off; if "Boat Centering" is turned own, the boat is placed in the center of the viewport and all waypoints are collected around it and placed within view.

The programmer may use the ShowAllWaypoints Method to use this feature. Note that if there is track data outside the bounds of the waypoints, that track data will not be included in the "best fit."

The Twilight and Night Properties set the same color scheme used in all other NMEA Sage controls. These color schemes are to help the end user see the displays without being blinded by the glare from the computer screen at twilight and nighttime.
The ShowButtons Property may be set to False to remove the Button Bar from the control. If the programmer uses this feature, she will have to provide a custom user interface.
The ShowButtons Property may be used with the ShowCaption Property to remove both, resulting in just the viewport being displayed on the control. This means the programmer must provide the user interface.
The bottom button on the Button Bar toggles "on"and "off" (shows and hides) the four Pan Arrows (one in each corner of the viewport).
If "Boat Centering" is turned on, one may not pan the viewport using the Pan Arrows.
The AddTrack Method is used to add from 1 to 15 tracks to the plotter control. The Method returns True (-1) if the track element was added successfully, and False (0) if the add attempt failed. The Method accepts four properties: the track's latitude, longitude, color, and line width. The color and line width are optional, and defaults to black and 1 respectively.
   RetVal = WaypointPlotter1.AddTrack(1, Lat, Lon, vbBlue, 2)
   WaypointPlotter1.RefreshViewport
Since the programmer or end user may wish to add a long series of track elements (which is often the case--- spanning many hundreds of track elements), the control does not automatically refresh after a track element is successfully added: one must issue the RefreshViewport Method to have the track data drawn after it is added.
    Open "track-data.txt" For Input As #1
    Do
        If EOF(1) Then Exit Do
        Input #1, Lat, Lon
        RetVal = WaypointPlotter1.AddTrack(2, Lat, Lon, vbRed, 2)
    Loop
    Close
    WaypointPlotter1.RefreshViewport
If the track's color is the same as the plotter's background color, the track color defaults to black: if the plotter's background color is black and the track's color is black, the track's color will change to white.
This image shows how the control is "sizable." The waypoint IDs have three alignments: here the "Center" alignment, via the Settings dialog window, was selected.

The blue dash lines show the Equator and the 180 degree meridian.

Here we see the boat on its way from Hilo Hawaii to the Palmyra Atoll. American Samoa and Pitcairn Island, as well as San Diego California at the top of the viewport, are also included.

The Longitude and Latitude format setting has been set to Degrees Minutes Seconds, as one can see in the bottom left corner of the control.

The same ocean span in the image above is shown here with the control at its smallest size. Note that South latitude is a negative number (and North is a positive number), as shown in the lower left corner.
The more waypoints one plugs into the control, the longer the control takes to draw itself. Here is an image of over 4,600 waypoints within San Bernardino County, California.
Here is the state of California, plotting 24,723 waypoints. There are over 100,000 Topographic Map waypoints for California but I only loaded a portion: this many waypoints takes a long time for the Waypoint Plotter control to redraw: several minutes.
Nevada.
Waypoint Symbols
0 Marina 39 Toilet 62 Truck Stop 97 Civil
1 School 40 Shower 67 TrackBack Point 98 Crossing
6 Bank 41 Drinking Water 68 Golf Course 99 Ghost Town
7 Fishing Area 42 Telephone 69 Small City 100 Levee
8 Fule Dock 43 Medical Facility 70 Medium City 101 Military
10 Residence 44 Information 71 Large City 102 Oil Field
11 Restaurant 45 Parking Area 76 Car Repair 103 Tunnel
13 Drinking Bar 46 Park 77 Fast Food 104 Beach
14 Danger Area 47 Picnic Area 78 Fitness Center 105 Forest
18 Waypoint 48 Scenic Area 79 Movie Theater 106 Summit
19 Shipwreak 49 Skiing Area 83 Post Office 107 Airport
20 Man Overboard 50 Swimming Area 84 RV Park 108 Heliport
22 Amber NavAid 51 Dam 89 Convienence Store 109 Private Air Field
25 Green NavAid 55 Ball Park 90 Playhouse Theater 110 Soft Field
29 Red NavAid 56 Car 91 Scales 111 Tall Tower
33 White NavAid 57 Hunting Area 92 Toll Booth 112 Short Tower
35 White-Red NavAid 58 Shopping Area 93 Bridge 113 Glider Area
37 Boat Ramp 59 Hotel 94 Building 114 Ultralight Area
37 Radio Beacon 60 Mine 95 Cemetary 115 Parachute Area
38 Campground 61 Trail Head 96 Cult 116 Seaplane Base
Events:

DistanceCalculated (Via Update 27Dec2008)
WaypointError
ArrivalAtWaypoint
Click
DblClick
ViewportDblClick(Latitude, Longitude)

Methods:

ShowAllWaypoints
AddWaypoint
AddTrack
RefreshViewport
BoatPosition
CenterViewport
RemoveWaypointByID
RemoveWaypointByNumber
Cls
SilenceAlarm
ResetControl
PanUp (Via Update 23Dec2008)
PanDown (Via Update 23Dec2008)
PanLeft (Via Update 23Dec2008)
PanRight (Via Update 23Dec2008)
ZoomIn (Via Update 23Dec2008)
ZoomOut (Via Update 23Dec2008)
The Cls Method erases all waypoints and tracks; the ResetControl erases all information and sets the control to it's new instancing defaults.

Properties:

BoatLat
BoatLon
CenterLat
CenterLon
CompassUnit
DisplayFormat
ShowWPText
ShowButtons
ShowCenter
BackColor
ForeColor
CenterOnBoat
BorderStyle
ShowCaptions
ShowBoat
ShowPanArrows
MagneticVariation
Night
Twilight
ErrorNumber
ErrorDescription
WaypointCount
ZoomInc (Via Update 23Dec2008)
DistanceUnits (Via Update 27Dec2008)

Error Codes

0 - No Current Error
1 - Waypoint must have an ID.
2 - Waypoint ID must have no more than 256 characters.
3 - Waypoint sumbol number must be from -1 to 116.
4 - Boat Latitude must be from -90 to 90
5 - Boat Longitude must be from -180 to 180
6 - Center Latitude must be from -90 to 90
7 - Center Longitude must be from -180 to 180
8 - There are no waypoints: remove request has been ignored.
9 - Waypoint number specified exceeds the number of waypoints.
10 - Waypoint [ID] was not found.
11 - There is no ocean data: cannot center viewport on boat.
12 - There is no boat location data: cannot center viewport on boat.
13 - Waypoint [NUMBER] has already been removed.
14 - Waypoint [NUMBER] does not exist and therefore cannot be silenced.
15 - Track number must be from 1 to 15.
16 - Track Latitude must be from -90 to 90.
17 - Track Longitude must be from -179.99999 to 179.99999.
18 - Track width must be from 1 to 6.
NMEA Sage Home Page

The Banded Compass Control
The Compass Control
The North Biased Compass Control
The Goto Control
Course and Speed (Ground)
The Position Control
Engine RPM Control
The Rudder Control
The GPS Satellite Health Control
The GPS Satellite Elevation Control
Set and Drift Control
The NMEA Talker Control
Depth and Water Temperature Control
The Wind Control
The Cross Track Alarm Control
The Pilot Control
Waypoint Plotter Control
Radar Control
Goto Simple Control