Skip to content

Latest commit

 

History

History
265 lines (210 loc) · 6.61 KB

GoTutorials.md

File metadata and controls

265 lines (210 loc) · 6.61 KB
Raw

Nautical GO Tutorials

The document contains the tutorials/examples for the GO package.

Note: If you are familiar with the python package, please be advised that the go package is structured differently because of the required imports.

Table Of Contents

Buoys

The following section provides examples in the buoy package.

If you know the ID of the buoy station you may use CreateBuoy as a shortcut to create a buoy struct.


buoy, err := CreateBuoy("44099")
if err != nil {
    // error occurred
} else if buoy.Valid {
    // Buoy contains valid data
}

The result will be a buoy filled with all of the data that was pulled online. The user should always check the validity of the buoy after the function call(s) to ensure that the data can be trusted.

If the user already has a buoy struct and wants to get the most up-to-date information, use te FillBuoy function.


// Buoy was created previously

err := buoy.FillBuoy()
if err != nil {
    // error occurred
}

Sources

The following section provides examples in the buoy package.

NOAA provides a KML document containing all sources and the buoys that are grouped together by that source. The document also provides minimal information about buoys in the event that they cannot be retrieved online.

Note: The TAO and Tsunami sources are not available in any regard.

If the user wishes to make a record for ALL sources and their buoys use the default settings when calling the GetBuoySources.


sources, err := GetBuoySources()
if err != nil {
    // error occurred
} else {
    for _, source := range sources {
        // do something with each source
    }
}

Location

The following sections are provided as examples in the location package.

In area

The user is provided with convenience functions for location Points. If the user wants to determine if a point (possibly the location of a buoy) is contained within a specific area they can use the `in_area_ function.


geometry := []Point{
    Point{}, Point{}, Point{}, Point{}
}

pointToCheck := Point{
    Latitude: latitude, 
    Longitude: longitude
}

inArea, err := InArea(geometry, pointToCheck)
if err != nil {
    return err
}

if inArea {
    // do something 
} else {
    // do something else
}

Similarly, the user can pass the location of a buoy to determine if it is in the area.


geometry := []Point{
    Point{}, Point{}, Point{}, Point{}
}
buoy := Buoy{
    Station: "test", 
    Description: "this is a test", 
    Location: Point{
        Latitude:latitude, 
        Longitude: longitude
    }
}

inArea, err := InArea(geometry, buoy.Location)
if err != nil {
    return err
}

if inArea {
    // do something 
} else {
    // do something else
}

In Range

The user can determine if two points are within a range of each other using the InRange function of the Point.


geometry := []Point{
    Point{}, Point{}, Point{}, Point{}
}

pointOne := Point{
    Latitude: latitude, 
    Longitude: longitude
}

pointTwo := Point{
    Latitude: latitude, 
    Longitude: longitude
}

// Only Meters distance is supported -> 1 km
inRange, err := pointOne.InRange(pointTwo, 1000.0)
if err != nil {
    return nil
}

if inRange {
    // do something
} else {
    // do something else
}


**Note**: _Currently, the Go package only supports meters as a distance for InRange()_.

Cache

The following sections are provided as examples in the cache package.

Dump data to file

Start by loading the data. There are several methods of doing so, but this example will manually create data.

buoys := []noaa.Buoy{
		noaa.Buoy{
			Station: "FakeStation",
			Present: &noaa.BuoyData{
				Time:  &nt.NauticalTime{Minutes: 30, Hours: 8, Format: nt.HOUR_24},
				Year:  2000,
				Month: 5,
				Day:   14,
			},
		},
		noaa.Buoy{
			Station: "FakeStation2",
			Present: &noaa.BuoyData{
				Time:  &nt.NauticalTime{Minutes: 30, Hours: 9, Format: nt.HOUR_24},
				Year:  2000,
				Month: 5,
				Day:   16,
			},
		},
		noaa.Buoy{
			Station: "FakeStation3",
			Present: &noaa.BuoyData{
				Time:  &nt.NauticalTime{Minutes: 30, Hours: 10, Format: nt.HOUR_24},
				Year:  2000,
				Month: 5,
				Day:   15,
			},
		},
	}

sources := []noaa.Source{
		noaa.Source{
			Name:        "Sample Source",
			Description: "Sample Source",
			Buoys: map[uint64]*noaa.Buoy{
				1234: &noaa.Buoy{Station: "FakeStation"},
				1235: &noaa.Buoy{Station: "FakeStation2"},
				1236: &noaa.Buoy{Station: "FakeStation3"},
			},
		},
	}

	cacheData := NauticalCacheData{
        Filename: "example.json",
        CacheData: &NauticalCache{
            Buoys: buoys,
            Sources: sources,
            Time: time.Now().UTC().Add(-(time.Minute * time.Duration(minutesOffset))).Format(TimeLayout)
        }
    }

    if err := nauticalCache.Dump(); err != nil {
		// some error occurred
	}

Load data from file

Loading the cached data will supply the user/caller with a NauticalCacheData struct when no error exists.

myCache := err, cacheData := Load(filename)
if err == nil {
    // Cached Data contains data to view manipulate.
}

Copying file contents

The user/caller has access to CopyCurrentCache and CopyCurrentCacheWithTimestamp. These functions will copy the current contents of the cached file (if exists) to a new filename. The name of the file where the data was copied is returned by both functions.

The CopyCurrentCache function provides a bit more flexibility with the name as any data provided is appended to the name of nautical_cache.json.

For instance, the following snippet would set the filename to nautical_cacheEXAMPLE.json.

myCache := NauticalCacheData{
    Filename: "nautical_cache.json"
}

err := myCache.CopyCurrentCache("EXAMPLE")