Write test utility to search a 3D cloud of points for the nearest neighbor to a specified (lat, lon, elev) location

[JohnHalleyGotway]

Describe the New Feature

This issue to create a new development utility in the internal/test_util/libcode/vx_grid directory named something like search_3d_kdtree.

This test utility would:

1. Read an input set of points, each defined by latitude, longitude, and elevation (in kilometers). Recommend using the geomagnetic grid locations provided in a sample file from NRL.
2. Likely use the Atlas::PointXYZ class to create a KDTree object (see UnstructuredGrid::build_tree() for existing implementation with the PointLonLat class.
3. Let the user define on the command line a location of interest by its latitude, longitude, and elevation.
4. Use the KDTree to search for the nearest point to the requested location. Print it out along with the distance to the location of interest.

Usage would look something roughly like this:

search_3d_kdtree -kdtree_points <path to input file> -search <latitude> <longitude> <elevation>

Arguments were modified

search_3d_kdtree <path to input file> <latitude> <longitude> <elevation_meters> \
   <lat_var_name> <lon_var_name> <elv_var_name>
   - <path to input file>: /d1/personal/dadriaan/projects/NRL/PyIRI/pyiri_f4_2020.nc
   - <xxx_var_name> are optional, default are glat,glon,zalt

The purpose of this test utility is to demonstrate that MET can be enhanced to search a 3D cloud for the point closest to a requested location. While the PointXYZ class looks promising, please consider other more classes provided by Atlas and ecKit that may be more appropriate.

If this utility proves useful, consider reimplementing the existing unstructured_grid.h/.cc source code to switch from 2D lat/lon support to 3D lat/lon/elev support. And when processing lat/lon only points, just define the elevation as a constant value.

The real challenge here is figuring out the "units" of the coordinate system. We need to clearly define the 3D distance metric. If possible, consider mapping all 3 dimensions into a coordinate system defined in meters (or kilometers) where distances in the horizontal and vertical are well-defined and comparable.

Acceptance Testing

List input data types and sources.
Describe tests required for new functionality.

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the new feature down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

Do not charge 7730022 after 12/30.

Funding Source

7730022 NRL METplus

Define the Metadata

Assignee

• Select engineer(s) or no engineer required: @hsoh-u to do the development
• Select scientist(s) or no scientist required: @willmayfield to test and advise

Labels

• Review default alert labels
• Select component(s)
• Select priority
• Select requestor(s)

Milestone and Projects

• Select Milestone as a MET-X.Y.Z version, Consider for Next Release, or Backlog of Development Ideas
• For a MET-X.Y.Z version, select the MET-X.Y.Z Development project

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdataio, METviewer, METexpress, METcalcpy, METplotpy
  No impacts for this test utility.

New Feature Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s) and Development issue
  Select: Milestone as the next official version
  Select: MET-X.Y.Z Development project for development toward the next official release
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.