Running the server:

vis.py can be run in multiple ways.
    
    1. On a publicly accessible port (80 or 443) with or without SSL 
       as both server and web app. 
    2. As a web app on a port that is reverse proxied behind another
       server (nginx or apache) running on 80 or 443. Generally the server  
       provides SSL and the app instance runs plain http.
    3. As a web app running on a non-privileged port that is accessible via
       ssh tunnel. This is generally how a pilot would run their
       own private instances with all of their standard privileges.

Independent of how vis.py is being accessed, it can be run in one of three modes.

    1. private mode - generally intended only for use when running over an
       ssh tunnel. The app runs with the privileges of the invoking
       user and all functionality is exposed and available (chat, ability
       to change control files). App level authentication rules can 
       still be applied. 
    2. pilot mode - intended to provide a piloting interface over a
       web interface. Authentication is provided at the app level
       and additional layers of authentication can be provided at the 
       reverse proxy level. Visually, this adds the status panel,
       comm.log viewer, and control file editor to the main display.
       Chat/log is available. Chat and save buttons can be separately
       disabled for a "public" view that still preserves the pilot
       display panels.
    3. public mode - removes the three pilot panels and chat 
       from the web app. Pilot specific endpoints in the API
       (save, chat) are disabled.   

Any of the instances can be configured using config files (missions.yml, users.yml)
or to operate on just a single mission using the -m command-line flag.

To run in private mode, establish an ssh tunnel when connecting to your basestation:

    desktop# ssh -L 20001:localhost:20001 my.basestation.edu
        ...
    basetation# /opt/basestation/bin/python3 /usr/local/basestation3/vis.py -m sg217:/home/seaglider/sg217 -p 20001

    browser: http://localhost:20001/217

Authentication, enabled fesatures, and permissions are highly configurable via missions.yml. 
Always test a publicly available running instance to make sure that permissions are
appropriate and that features are not being exposed in unintended ways. 

--

The web app:


on desktop, shortcut keys can be used to move through dives and plots in the ribbon: 

    wasd: W up a dive, A down a dive
          S left in the ribbon, D right in the ribbon

    hjkl: (vi key bindings)  
          j down a dive, k up a dive
          h left in the ribbon, l right in the ribbon

    1-5: jumps through the 5 plot "pages" of the ribbon (1 = page 1, etc.)

    scrolling with a scroll wheel inside the ribbon, scrolls horizontally

In chat, markdown for glider, dive, plots and links is available

    @236 = go to glider 236 (link to /236)
    #376 = create link that when clicked will change shown plots to dive 376
    $ts = create link that when clicked will change plot to ts plot

    markdown can be combined: #376$ts = link to change to dive 376 and show ts
                              @234#123$map

    [text](url) = create standard URL link

On mobile:

    landscape: 
        click the three squares to show the ribbon to change the plot
        click the diagonal expander arrow to open the plot full size
        swipe left on the plot to show status - comm.log - cmdfile edit windows
        swipe up down on the left hand side toolbar to show the tool options to change the main display
    
    portrait:
        swipe left and right on the bottom panels to center status or comm.log or cmdfile
        click the expander arrow on the plot to open the plot full size


Not all features are available in all users and/or in all modes.

--

API / URL usage


GET /
    description: "public" index (all missions) page
    parameters : plot (which plot to include in tiles, default=map), mission (comma separated list), glider (comma separated list), status, auth
    returns    : HTML page

GET /<glider:int>
    description: main page for glider
    parameters : mission, plot (starting plot), dive (starting dive), order (plot ribbon order), x,y,z,first,last,step,top,bottom,bin,wholemission|divetimeseries,dives|climbs|both|combine (plot tool values), op (contour,profiles,plot,table,csv), sectionNumber (sort order for section numbers ( normal, reverse)), sectionSort (major sort key for sections (number, name))
    returns    : HTML page

GET /alerts/<glider:int>/<dive:int>
    description: basestation alerts file
    parameters : mission
    returns    : alerts file (with re-written links) from basestation (HTML format)

POST /auth
    description: user authorization
    payload    : (JSON) username, password
    returns    : none on success (sets cookie with authorization token)

GET /baselog/<glider:int>/<timestamp:str>
    description: basestation baselog file
    parameters : mission
    returns    : raw baselog file from basestation (txt)

GET /changes/<glider:int>/<dive:int>/<which:str>/<sort:str>
    description: query database for parameter or control file changes
    args       : dive=-1 returns entire history, which=parms|files, sort=dive|parm|file
    parameters : mission
    returns    : JSON dict of changes [{(dive,parm,oldval,newval}] or [{dive,file,fullname,contents}]

POST /chat/send/<glider:int>
    description: POST a message to chat
    payload    : (form) attachment, message
    parameters : mission
    returns    : JSON dict of chat history

GET /control/<glider:int>/<which:str>
    description: glider control files
    args       : which=cmdfile|targets|science|scicon.sch|tcm2mat.cal|pdoscmds.bat|sg_calib_constants.m
    parameters : mission
    returns    : latest version of glider control file

GET /csv/<glider:int>
    description: get CSV file from glider directory (supports assets type
    parameters : mission, file
    returns    : json array of data

GET /dash
    description: dashboard (engineering diagnostic) view of index (all missions) page
    parameters : plot (which plot to include in tiles, default=diveplot), mission (comma separated list), glider (comma separated list), status, auth
    returns    : HTML page

GET /data/<which:str>/<glider:int>/<dive:int>
    description: download raw data
    parameters : mission
    returns    : netCDF file

GET /db/<glider:int>/<dive:int>
    description: query database for common engineering variables
    args       : dive=-1 returns whole mission
    parameters : mission
    returns    : JSON dict of engineering variables

GET /dbvars/<glider:int>
    description: list of per dive database variables
    parameters : mission
    returns    : JSON list of variable names

GET /deltas/<glider:int>/<dive:int>
    description: list of changes between dives
    parameters : mission
    returns    : JSON formatted dict of control file changes

GET /file/<ext:str>/<glider:int>/<dive:int>
    description: processed glider basestation files
    args       : ext=eng|log|cap
    parameters : mission
    returns    : raw eng, log, or cap file

GET /kml/<glider:int>
    description: get glider KML
    parameters : mission, network, kmz
    returns    : KML

GET /log/<glider:int>/<dive:int>
    description: formatted glider log
    parameters : mission
    returns    : summary version of log file in HTML format

GET /magcal/<glider:int>/<dives:str>
    description: run magcal over multiple dives
    parameters : mission, ballast
    returns    : html of plotly results plot

WEBSOCKET /map/stream

GET /mapdata/<glider:int>
    description: get map configation (also, sa, kml from missions.yml)
    parameters : mission
    returns    : JSON dict with configuration variables

GET /missions/<mask:str>
    description: list of missions
    args       : mask is unused
    returns    : JSON formatted dict of missions and mission config

GET /plot/<fmt:str>/<which:str>/<glider:int>/<dive:int>/<image:str>
    description: get a plot image
    args       : fmt=png|webp|div, which=dv|eng|sg
    parameters : mission
    returns    : image data (webp, png or plotly div)

GET /plots/<glider:int>/<dive:int>
    description: list of plots available for dive
    parameters : mission
    returns    : JSON dict of available plots, sorted by type

WEBSOCKET /pos/stream/<glider:int>
    description: stream real-time position updates
    parameters : mission

POST /post
    description: post version of proxy request handler for map tool
    returns    : contents from requested URL

GET /pro/<glider:int>/<whichVar:str>/<whichProfiles:int>/<first:int>/<last:int>/<stride:int>/<top:int>/<bot:int>/<binSize:int>
    description: extract bin averaged profiles
    args       : whichProfiles=1(dives)|2(climbs)|3(both)|4(combine)
    parameters : mission
    returns    : compressed JSON dict of binned profiles

GET /proxy/<url:path>
    description: proxy requests for map tool
    returns    : contents from requested URL

GET /proxykmz/<url:path>
    description: proxy and unzip network KMZ sources
    returns    : KML from KMZ downloaded from requested URL

GET /query/<glider:int>/<queryVars:str>
    description: query per dive database for arbitrary variables
    args       : queryVars=comma separated list
    parameters : mission, format, limit
    returns    : JSON dict of query results

GET /rafos/<glider:int>

GET /regress/<glider:int>/<dives:str>/<depth1:float>/<depth2:float>/<initBias:float>
    description: run VBD regression over multiple dives
    parameters : mission, ballast
    returns    : html of plotly results plot

POST /save/<glider:int>/<which:str>
    description: save glider control file
    args       : which=cmdfile|targets|science|scicon.sch|tcm2mat.cal|pdoscmds.bat|sg_calib_constants.m
    payload    : (JSON) file, contents
    parameters : mission
    returns    : validator results and/or error message

GET /selftest/<glider:int>
    description: selftest review
    parameters : mission, num
    returns    : HTML format summary of latest selftest results

GET /status/<glider:int>
    description: glider latest dive number and visualization config (mission.dat variables, mission plots)
    parameters : mission
    returns    : JSON formatted dict of configuration

WEBSOCKET /stream/<which:str>/<glider:int>
    description: stream real-time glider information (comm.log, chat, cmdfile changed, glider calling, etc.)
    parameters : mission

GET /summary/<glider:int>
    description: summary status of glider
    parameters : mission
    returns    : JSON formatted dict of glider engineering status variables

GET /tile/asset/<path:str>/<z:int>/<x:int>/<y:int>

GET /time/<glider:int>/<dive:int>/<which:str>
    description: extract timeseries data from netCDF
    parameters : mission
    returns    : compressed JSON dict of timeseries data

GET /timevars/<glider:int>
    description: list of timeseries variables
    parameters : mission
    returns    : JSON list of variable names

POST /upload/<glider:int>
    description: upload files to glider home directory
    parameters : mission
    returns    : 

POST /url
    description: .urls notification handler (used when vis server is different from basestation server)
    parameters : instrument_name, dive, files (), status (), gpsstr ()
    returns    : 'ok' or 'error'

GET /user
    description: checks whether current session user is valid
    returns    : YES is user is valid

WEBSOCKET /watch
    description: stream real-time glider summary state (call status, cmdfile directive)
    parameters : mission, gliders