From 8e1d9f44b2b2bc4031693855478f7201a7681053 Mon Sep 17 00:00:00 2001 From: Ben Burwell Date: Thu, 6 Feb 2020 15:04:34 -0500 Subject: improve docs --- README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ cmd/metar.go | 17 ++++-------- doc/wx.1.scd | 62 +++++++++++++++++++++++++++++++++++++++-- 3 files changed, 156 insertions(+), 14 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5a5a8e7 --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# `wx` - a command line interface for aviation weather + +`wx` fetches weather data from the NOAA Aviation Weather Center's Text Data +Server (TDS). + +## Installation from source + +1. Clone the repository +2. Run `sudo make install` + +## Usage + +Currently, we support fetching METARs in a variety of methods. When fetching +METARs, a time constraint must be supplied. A time constraint can either be in +the form "past x" or "between x and y". + + $ wx metar --past 3h + $ wx metar --since 2020-01-01T00:00:00 --until 2020-01-02T00:00:00 + +The `--past` argument defaults to `1h`, so if none of `--past`, `--since`, or +`--until` are specified, METARs from the past hour will be fetched. + +Note that the TDS only stores METARs from the past three days, so the `wx` +command cannot effectively be used to pull historical data. + +### For a set of stations + +You can fetch METARs from a set of stations by their full or partial ICAO IDs: + + $ wx metar kbos + $ wx metar kbos ksea + $ wx metar kb + +### For stations in a region + +You can fetch METARs from all stations within a rectangular or radial region. +Rectangular regions are specified by a `minLat,minLon,maxLat,maxLon` tuple: + + $ wx metar --rect 39,-70,40,-71 + +Radial regions are specified as a radius in statute miles around a center point +as a `dist,lat,lon` tuple: + + $ wx metar --radial 5.5,40,-70 + +### For stations along a flight path + +You can fetch weather for all stations with a distance of a specified flight +path. A flight path is specified by a series of `--waypoint` arguments, where +each waypoint can be an ICAO identifier or a `lon,lat` tuple. Waypoints must be +specified in order from origin to destination. + + $ wx metar --path-dist 10 --waypoint ksea --waypoint kbos + +### Controlling density + +When running a query which will return METARs from many stations, it may be +helpful to reduce the density of the results. This can be done with the +`--min-dist` argument which specifies a minimum distance (in degrees of latitude +or longitude) between stations to display. Providing a higher value for +`--min-dist` will result in fewer stations being returned. + + $ wx metar \ + --path-dist 10 --waypoint ksea --waypoint kbos \ + --min-dist 5 \ + +### Filtering recency + +There are two mechanisms for filtering results by recency. First, you can +request the single most recent METAR from all the stations being fetched: + + $ wx metar --past 6h kbos ksea --most-recent + +Even though we've specified two stations, KBOS and KSEA, we'll only get a single +METAR back from whichever of the two stations most recently made an observation. + +The second filtering mechanism is `--most-recent-by-station`. This argument can +take several values: + +* `constraint` (default): request the most recent for each METAR station in the + fastest fashion. +* `postfilter`: filter results after applying all other constraints. +* `false`: don't filter results to only the most recent for each station. + +## Contributing + +Email patches to . + +## License + +MIT diff --git a/cmd/metar.go b/cmd/metar.go index 6355105..ea72f70 100644 --- a/cmd/metar.go +++ b/cmd/metar.go @@ -124,7 +124,7 @@ conjunction with --until`) `Ending time for METARs (e.g. "2020-01-01T01:31:00" or "3h"), used in conjunction with --since`) metarCmd.Flags().DurationVar( - &past, "past", 0, + &past, "past", time.Hour, `Duration to retrieve METARs since (e.g. "3h")`) // location constraints @@ -154,8 +154,8 @@ reported. A higher value results in less dense results.`) &mostRecentByStation, "most-recent-by-station", "constraint", `Method for fetching most recent for each station ("constraint", "postfilter", "false")`) - metarCmd.Flags().BoolVarP( - &mostRecent, "one", "1", false, + metarCmd.Flags().BoolVar( + &mostRecent, "most-recent", false, `Only fetch the single most recently-issued METAR of all the selected stations`) } @@ -173,19 +173,14 @@ var metarCmd = &cobra.Command{ if !since.t.IsZero() || !until.t.IsZero() { reqArgs = append(reqArgs, metar.TimeRange(since.t, until.t)) - } - - dur, _ := cmd.Flags().GetDuration("past") - if dur > 0 { + } else if dur, _ := cmd.Flags().GetDuration("past"); dur > 0 { reqArgs = append(reqArgs, metar.HoursBeforeNow(dur.Hours())) } - if mostRecentByStation != "" { - reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation)) - } - if mostRecent { reqArgs = append(reqArgs, metar.MostRecent(true)) + } else if mostRecentByStation != "" { + reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation)) } if !rect.IsZero() { diff --git a/doc/wx.1.scd b/doc/wx.1.scd index 1b452d8..a11f65c 100644 --- a/doc/wx.1.scd +++ b/doc/wx.1.scd @@ -2,7 +2,7 @@ wx(1) # NAME -wx - a front-end CLI for NOAA Aviation Weather Center data +wx - a command line interface for aviation weather # SYNOPSIS @@ -10,5 +10,61 @@ wx _command_ # COMMANDS -*metar* - fetch METAR data +*metar* [_station_ ...] + fetch METAR data for _station_ + +# METAR + +When fetching METARs, a time constraint must be supplied. A time constraint can +either be in the form "past x" or "between x and y". + +Options: + +*--past* _duration_ + fetch METARs from the past _duration_, formatted as a Go duration string + (e.g. _3h_). + + *Default:* 1h + +*--since* _time_ + fetch METARs since _time_, formatted as YYYY-MM-DDTHH:MM:SS + +*--until* _time_ + fetch METARs until _time_, formatted as YYYY-MM-DDTHH:MM:SS + +*--rect* _minLat_,_minLon_,_maxLat_,_maxLon_ + fetch METARs within the specified rectangle + +*--radial* _dist_,_lat_,_lon_ + fetch METARs within _dist_ statute miles of the specified point + +*--path-dist* _dist_ + when used with *--waypoint*, specify a maximum distance around the flight + path in which to fetch METARs. + +*--waypoint* _point_ + fetch METARs along a flight path specified by multiple *--waypoint* arguments + in order from origin to destination. The _point_ may be either an ICAO + identifier or a lon,lat pair. + +*--min-dist* _dist_ + when fetching METARs from multiple sources, enforce a minimum distance of + _dist_ degrees of latitude or longitude between stations to reduce the + density. + +*--most-recent* + fetch only the single most recent METAR that matches the station filters. + +*--most-recent-by-station* _type_ + fetch the most recent METAR for each station that matches using _type_ as the + filter type, which can be one of constraint, postfilter, or false. + + See _https://www.aviationweather.gov/dataserver/example?datatype=metar_ for + information about these options. + + *Default:* constraint + +# AUTHORS + +Ben Burwell . For more information, see +_https://git.sr.ht/~benburwell/wxcli_. -- cgit v1.2.3