Navigator2Go

User Manual

Installation

Pre-requisites

  • Ubuntu 14.04/16.04 (64-bit/amd64). Ubuntu 18.04 support coming soon. Unfortunately, the Ocean Navigator does not have Windows support at this time. Feel free to contact us regarding this.
  • sudo access (for the initial installation)
  • At least 40GB of free disk space. You can use df -h to check :)
  • Your favourite terminal emulator. I like terminator.

Ready? Set? Go!

We've tried to make the initial installation as painless and automated as possible, however suggestions for improvement are always welcome!

Please note that all required components will be installed to /opt/. For a first-time user, we recommend leaving this unchanged.

  • Download this bash script to some directory. Feel free to skim through it; it is well-documented.
  • Navigate to the above file in your terminal and type: chmod +x Installer_Linux.sh.
  • Type ./Installer_Linux.sh
  • You will eventually be prompted for your sudo password.
  • Depending on your network speed, this installation may take upto 15-20 minutes. We have to download several GB of data.
  • Check the console output regularly for any errors that occour. Again, feel free to !!CONTACT US!! if you have any issues/questions.

All done!

Time to run this thing!

First Run Tutorial

You've now hopefully installed Navigator2Go with complete success! Before we get started, please read through the following notes (the technical ones may be ignored).

Note: We recommend running the Navigator2Go binary from your favourite terminal emulator. This allows you to see potentially important debug information in the scenario something misbehaves. Sending us the output from your terminal will allow for a patch to be released much more quickly.

Technical Note: The Navigator2Go executable is compiled and linked as a static binary, so you can move it from the default installation directory (/opt/Navigator2Go/) to a more convenient place of your choice. Or just create a symlink to it ;)

This tutorial will take you through the process of acquiring data from our public Ocean Navigator server (navigator.oceansdata.ca) and displaying data for the Halifax region on your local installation:

Final result
What we will end up with.

Let's get started!

Starting Up

  • In your favourite terminal emulator: cd /opt/Navigator2Go/.
  • Type: ./Navigator2Go
  • You will see the following dialog pop up:
    First Run Dialog Prompt
    Click OK to continue.
  • Don't worry about what these all represent as they are documented below.
    First Run Settings Dialog
    These default values should be appropriate for most users. If you are already familiar with the ins-and-outs of Navigator2Go, feel free to tweak these settings.
    Click OK to continue.
  • Welcome to your Dashboard!
    Navigator2Go Dashboard

Adding Data

After a fresh install, the Navigator is hungry! Let's give it some data to digest :P

  • Click on the Data Order tab.
  • Leave the Region of Interest unchanged. Read the FAQs on how to change it.
  • Under 2. Remote Datasets, double-click on GIOPS Daily.
  • A new window will appear allowing you to configure the download properties. If you hover over the labels on the left-hand side, you can get some additional information:
    Dataset Properties Tooltip
  • In this new window, scroll to the Variable Selection area.
  • Click on Temperature.
  • Select a date range for the data. Note: There is a limit to the selectable date range according to the Quantum attribute:
    • day: 60 days
    • month: 5 years (or 60 months>
  • Click OK to add this dataset to the download queue and close the window.
  • You will see a new entry in the Download Queue section (right-hand side):
    Download Queue
  • Click the Download Data button to start the download process.

Unfortunately now is when things get slightly more complex...

  • Since we are downloading a new dataset, Navigator2Go doesn't know where to put the downloaded files. If you have lots of storage space available, or only have the 1 drive, the recommended directory for any download is as follows: /opt/thredds_content/data/<dataset_name>. For this example, enter the following: /opt/thredds_content/data/giops_day. Dataset Location
    Click OK.
  • Now another dialog will appear...
    Dataset Time Dimension
    This requires some knowledge of the dataset's internal attributes. You need to enter the name of the time dimension for this dataset. This will be passed along to THREDDS in order to aggregate separate files according to time. The time variable may be called time_counter, time, validity_time, etc. It's usually one of the first two...
    For this example, enter time_counter and click OK.
  • Now our data will download! Data Order Download Progress
  • Sit tight while your stuff downloads. You will be notified when downloads are complete.
  • NOT DONE YET :( You should be thanking me you don't have to manually edit these files and what-not :P
The last step is to make the Navigator itself aware that we have a dataset ready to analyze.
  • Click on the Dashboard tab.
  • Start the THREDDS Server (Apache Tomcat) in the top-left hand box. You should see some output in your console.
  • Click on the Dataset Config Editor tab.
  • Click on Load Default File.
  • Click on Add Dataset.
  • Enter giops_day.
    New Dataset key
  • Double-click on that value in the list to begin editing it's properties.
  • Edit Dataset Properties
    Notice how the URL is already filled in for you.
Remember: You can hover over each label on the left-hand side to reveal more information.
  • Fill in the following values:
    Edit Dataset Properties
  • Now click on Magic Scan. It might take a couple of seconds for the window to pop up. That is normal because querying THREDDS is very slow.
  • This dialog allows you to select which data variables to auto-magically import. You can hover over each row to see the long name of the variable. Magic Scan
    Click on votemper and click OK.
  • There will be a new entry in the Variables table. Doule-click on Name and change it to Temperature. Change Units to Kelvin (no s at the end). Also change Default Min to -5, and Default Max to 30.
    Dataset Variables
  • Save your changes and close with window by click OK in the bottom-right corner.
  • Save your config file to disk by clicking the Save button in the top-right corner of the Dataset Config Editor tab.
  • To start the Ocean Navigator with the "offline" config file we just edited, we must take the Navigator2Go into offline mode as follows:
    • Press CTRL + SHIFT + P to open the Preferences dialog.
      Preferences Dialog
      Look familiar?
    • Click on the Network Online/Offline switch and click OK. Navigator2Go is now offline.
    • A new dialog will popup reminding you to restart the Web Server (GUnicorn) to see your changes.
  • So, let's listen to the program and start the Web Server :P
  • After 5-10 secs, you should see a bunch of output in your console along the lines of [INFO] Booting worker with pid:. The Navigator is now running on your system!
  • Click on the link just below the Web Server (GUnicorn) (http://localhost:5000) label in the Navigator2Go Status box. A new web browser window will open. This should be your result: Ocean Navigator Splash Page
    Click on the OPEN NOW button.
  • After 10-15 secs, your page should look like this: First Page Load
    Note the data around the Halifax region. Feel free to zoom in and make some plots.

Well that was a bit of a doozy now wasn't it?

Note: If you close the Navigator2Go program without stopping both servers, they will continue to run in the background :) But they will not automatically start when you restart your computer.

Uninstallation

To completely uninstall Navigator2Go (including any local THREDDS data), download and run the following script: Uninstall_Linux.sh.

FAQ

Table of Contents

How do I update my installation?

Navigator2Go comes with a built-in update utility that runs every time the program starts. You can manually check for updates by going to: Menu -> Help -> Check for Updates. It checks for updates to Navigator2Go and also to the underlying Ocean Navigator. In general, the Navigator2Go only requires downloading a single tar.gz. The Ocean Navigator is pretty complex so if it needs an update, we will do it automagically for you.

  • If an update to Navigator2Go is available, a dialog box will pop up with a link to the latest release on Github. Download it to your installation directory (default is /opt/Navigator2Go).
  • Remove the old version: rm /opt/Navigator2Go/Navigator2Go.
  • Use tar xvf Navigator2Go.tar.gz -C /opt/Navigator2Go/ to unzip it.

How do I change the Data Order region?

We define the data order region using a bounding box as follows:
Bounding Box
The values you enter will be stored in the program settings, so they will be saved when you close Navigator2Go.
Data Order Region

Where do I find my Navigator2Go version info?

To help with debugging and the update functions, Navigator2Go embeds it's version number and git commit hash in the About dialog. It is accessible via Menu -> Help -> About. It will look like this (the version number and commit hash will change with each release):
About Navigator2Go Dialog Box

Viewing THREDDS log files

Let's be clear: THREDDS is a huge pain (in you know where) to debug if something is wrong. I've added a quick way to browse all of the relevant THREDDS logs to see if something is amiss.

For detailed info: https://www.unidata.ucar.edu/software/thredds/v4.5/tds/tutorial/TomcatAndTDSLogs.html

  • Go to the THREDDS Config Editor.
  • In the bottom right corner, click on Browse Log Files...
  • Use the dropdown menu to cycle through the logs The currently selected one reloads every 30 secs. Here is what each log file captures:
    • cache.log: contains log messages related to THREDDS object and file caching.
    • catalogInit.log: errors and warnings in your catalog configuration files are shown here. Look at this closely every time you change your config catalogs.
    • featureCollectionScan.log: log messages related to THREDDS feature collection scanning.
    • fmrc.log: usually empty...
    • httpout.log:
    • serverStartup.log: contains log messages from the initialization of THREDDS.
    • threddsServlet.log: contains the log messages for all requests handled by THREDDS. The log file rolls over at the top of every hour with old log files named with the "threddsServlet.log." pattern.

What is the My Jobs  box in the Dashboard?

Something cool that is coming soon :)

Feel free to contact us about this.

How do I import my own netCDF file(s)?

Suppose you have a couple of netCDF files lying around on your hard drive you wish to view in the Navigator. Well, you're in luck since Navigator2Go can help! Let's get to it...

To summarize, we will need to do the following: make THREDDS aware of our new dataset, do the actual import operation (which automagically moves your file(s) into the THREDDS directory), then add this dataset to the Navigator config file.

  • Start your engines Navigator2Go.
  • If this is a new dataset you wish to import continue reading. If you wish to "append" to an existing dataset, skip to the third solid bullet.
    • Go to the THREDDS Config Editor.
    • Click on Add Dataset.
    • Enter a concise name describing your dataset. Ensure you follow the note about illegal characters:
      Add THREDDDS Dataset
    • Now enter the directory where you wish your new dataset files to live. Unless your files are very large, we recommend you using the following convention:
      New Dataset Path
      Where my_dataset is the name you entered in the previous dialog box.
    • Now enter the name of the time variable for your dataset. This requires some knowledge of the dataset's internal attributes. This will be passed along to THREDDS in order to aggregate separate files according to time. The time variable may be called time_counter, time, validity_time, etc. It's usually one of the first two...
      New Dataset Time Dimension
  • In the Dashboard, click on the Browse button next to the Import NetCDF File(s) label.
  • This window will appear:
    NetCDF Import Window
  • Click on the Add button and select your *.nc file.
  • In the right-hand column select the dataset you wish to append to (you can import multiple files too).
  • Click OK to begin the import process.
  • Once the process completes, restart Apache Tomcat, and add the new dataset in the Dataset Config Editor.

Contact

For General Inquiries

For Technical Issues/Questions