Merge branch 'DOI-USGS:main' into main

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## Licensing
+This project is mostly composed of free and unencumbered software released into the public domain, and we are unlikely to accept contributions that are not also released into the public domain. Somewhere near the top of each file should have these words:
+
+> This work is free and unencumbered software released into the public domain. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain.
+
+- [ ] I dedicate any and all copyright interest in this software to the public domain. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
+

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: Pull-Request-CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  Build-and-Test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+       os: [ubuntu-latest, macos-latest]
+       python-version: ["3.9", "3.10", "3.11", "3.12"]   
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - name: Setup ENV
+        uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3
+        with:
+          miniforge-version: latest  
+          use-mamba: true  
+          channels: conda-forge  
+          activate-environment: ale  
+          environment-file: environment.yml  
+          auto-activate-base: false  
+          auto-update-conda: true  
+          python-version: ${{ matrix.python-version }}
+      - name: Check build environment
+        run: |
+          conda list
+      - name: Install Python Package
+        run: |
+          python setup.py install
+      - name: Test Python Package
+        run: |
+           pytest -n4

.github/workflows/deploy-docs-aws.yml

@@ -41,6 +41,6 @@ jobs:
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           aws-region: us-west-2
 
-      - name: Upload to S3
-        working-directory: docs
-        run: aws s3 sync --delete public s3://asc-docs/knoten
+      # - name: Upload to S3
+      #   working-directory: docs
+      #   run: aws s3 sync --delete public s3://asc-public-docs/knoten

.gitignore

@@ -115,3 +115,6 @@ venv.bak/
 print.prt
 *.cub
 *.CUB
+
+.DS_Store
+default.profraw

CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All changes that impact users of this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!---
+This document is intended for users of the applications and API. Changes to things
+like tests should not be noted in this document.
+
+When updating this file for a PR, add an entry for your change under Unreleased
+and one of the following headings:
+ - Added - for new features.
+ - Changed - for changes in existing functionality.
+ - Deprecated - for soon-to-be removed features.
+ - Removed - for now removed features.
+ - Fixed - for any bug fixes.
+ - Security - in case of vulnerabilities.
+
+If the heading does not yet exist under Unreleased, then add it as a 3rd heading,
+with three #.
+
+
+When preparing for a public release candidate add a new 2nd heading, with two #, under
+Unreleased with the version number and the release date, in year-month-day
+format. Then, add a link for the new version at the bottom of this document and
+update the Unreleased link so that it compares against the latest release tag.
+
+
+When preparing for a bug fix release create a new 2nd heading above the Fixed
+heading to indicate that only the bug fixes and security fixes are in the bug fix
+release.
+-->
+
+## Unreleased
+
+## [0.4.0] - 2024-05-10
+
+### Added
+- Added the following sensor utility functions: `phase_angle`, `emission_angle`, `slant_distance`, `target_center_distance`, `sub_spacecraft_point`, `local_radius`, `right_ascension_declination`, `line_resolution`, `sample_resolution`, and `pixel_resolution`.
+
+
+## [0.3.0] - 2024-04-14
+
+### Added
+- `create_csm` now dispatches to `_from_isd` and `_from_state` to test whether the sensor model can be instantiated from either and ISD or a state file.
+- `generate_image_coordinate` to `csm.py`. This provides a similar interface to `generate_ground_coordinate` and abstracts away the `csmapi` from the user.
+- A surface class (moved from AutoCNet; credit @jessemapel) with support for Ellipsoid DEMs and basic support for raster DEMs readable by the plio.io.io_gdal.GeoDataset. Support is basic because it uses a single pixel intersection and not an interpolated elevation like ISIS does.
+- A check to `generate_ground_point` when a GeoDataset is used to raise a `ValueError` if the algorithm intersects a no data value in the passed DEM. This ensures that valid heights are used in the intersection computation. Fixes [#120](https://github.com/DOI-USGS/knoten/issues/120)
+
+### Changed
+- Removed all `pyproj` calls from csm.py, abstracting them into the reprojection and pyproj.Transformer code inside utils.py. Updated the transformations to use the new pipeline style syntax to avoid deprecation warnings about old syntax.
+
+### Fixed
+- The init method that searches for the libusgscsm to support searching in the `csmplugins` subdirectory. This approach depends on being able to find `csmapi` in a standard location and then assumes that the `libusgscsm` shared library is in a subdirectoy of that `lib` directory. Fixes [#118](https://github.com/DOI-USGS/knoten/issues/118)
+

README.md

@@ -8,13 +8,13 @@ A library to leverage python wrapped Community Sensor Models (CSMs) for common s
 
 ## References:
 
-- CSM (usgscsm): https://github.com/USGS-Astrogeology/usgscsm
-- Abstraction Layer for Ephemerides (ALE): https://github.com/USGS-Astrogeology/ale
+- CSM (usgscsm): https://github.com/DOI-USGS/usgscsm
+- Abstraction Layer for Ephemerides (ALE): https://github.com/DOI-USGS/ale
 <hr>
 
 ## Overview
 
-We currently use Knoten to help test our supported CSM implementations against well established [ISIS3 camera models](https://github.com/USGS-Astrogeology/ISIS3). In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this [abstract](https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf) and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the [usgscsm](https://github.com/USGS-Astrogeology/usgscsm) library. 
+We currently use Knoten to help test our supported CSM implementations against well established [ISIS3 camera models](https://github.com/DOI-USGS/ISIS3). In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this [abstract](https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf) and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the [usgscsm](https://github.com/DOI-USGS/usgscsm) library. 
 
 A secondary requirement for our CSM implementation requires an ALE-generated Image Support Data (ISD). ISDs contain the [SPICE-derived](https://naif.jpl.nasa.gov/naif/toolkit.html) positional (and when needed velocity) description for each image. You can find several generated JSON-formatted examples [here](examples/data/)
 
@@ -24,40 +24,38 @@ Please see the **status report** below for the current instruments we have imple
 
 ## Installing
 
-You can install the latest build via conda
+You can install the latest build via conda. 
 
 ```
 conda install -c usgs-astrogeology -c conda-forge knoten
 ```
 
-You can also do a local install using the following steps within a clone of the repository
+You can also do a local install using the following steps within a clone of the repository.
 
-1. Install the dependencies
-```
-conda env create -f environment.yml
-```
+1. Install the dependencies.  
+   Note: creating the environment may take around and hour.  If conda is too slow, try using mamba instead.
+    ```
+    conda env create -f environment.yml
+    ```
 
-2. Install the package
-```
-python setup.py install
-```
+1. Install the package
+    ```
+    python setup.py install
+    ```
 
 <hr>
 
-## Status Report - November 2019
-
-For full testing reports and example usage, please see the linked example Jupyter notebooks in the table below. 
+## Building Docs
 
-|       Instrument      |                      Jupyter Notebooks                     |  Production Ready |    Difference CSM -> ISIS (in pixels)   |    Difference ISIS -> CSM (in pixels)   |
-|:---------------------:|:-------------------------------------------------:|:-----------------:|:---------------------------------------:|:---------------------------------------:|
-|       MRO HiRISE      |     [link](examples/mro_hirise_isis_cmp.ipynb)    |     sub-pixel; in testing for production    | sample mean=-2.0e-05; line mean=2.5e-08 | sample mean=-3.0e-08; line mean=1.2e-04 |
-|        MRO CTX        |      [link](examples/mro_ctx_isis_cmp.ipynb)      | nearly sub-pixel; still in research |  gross error in line  |     sample mean=0.0002; line mean=-0.07     |
-|        MEX HRSC       |      [link](examples/mex_hrsc_isis_cmp.ipynb)     |         sub-pixel; in testing for production        |      sample mean=0.000038; line mean=-0.000072      |       sample mean=-0.000038 ; line mean=-7.512e-05       |
-|        LROC NAC       |      [link](examples/lrocnac_isis_cmp.ipynb)      | sub-pixel; in testing for production |      sample mean=-0.003; line mean=-0.0006      |                   sample mean=0.0005	line mean=0.003                   |
-| Kaguya Terrain Camera |     [link](examples/kaguya_tc_isis_cmp.ipynb)     | barely sub-pixel; in testing |     sample mean=0.0001; line mean=0.00003    |      sample mean=0.009; line mean=-1.242      |
-|   Messenger MDIS NAC  | [link](examples/messenger_mdisnac_isis_cmp.ipynb) |  sub-pixel; in testing for production |      sample mean=-0.01; line mean=-0.003     |       sample mean=0.01; line mean=0.003      |
-|  Cassini ISS NAC      |      [link](examples/cassini_isis_nac_cmp.ipynb)      |  sub-pixel; in testing for production  |    sample mean=-0.001; line mean=0.01    |     sample mean=0.001; line mean=-0.01     |
-|  Cassini ISS WAC      |      [link](examples/cassini_isis_wac_cmp.ipynb)      |  sub-pixel; in testing for production  |    sample mean=0.001; line mean=0.004    |     sample mean=-0.001; line mean=-0.004     |
-|  Dawn Framing Camera  |      [link](examples/dawn_fc_isis_cmp.ipynb)      |     sub-pixel; in testing for production    | sample mean=-0.02; line mean=0.003 | sample mean=0.02; line mean=-0.003 |
+To build the docs:
+1. Open the docs directory: `cd docs`
+1. Create (if not existing) and activate the environment (or use the main knoten environment if it is already created).
+   
+   ```sh
+   conda env create -f environment.yml #If it does not exist already
+   conda activate knoten-docs
+   ```
+1. Run `sphinx-build -b html . public` to build the docs in the `docs/public` directory (or change "public" to a subdirectory name of your choosing).
+1. Browse to the `index.html` file in `docs/public` to open the docs.  If needed, run a utility like `http-server` in the `docs/public` directory to serve the docs on localhost.
 
-The Difference column (CSM -> ISIS) represents the mean difference in pixels from running usgscsm's *image2ground* and then back to the camera using ISIS3's *campt* (ground2image). The Difference column (ISIS -> CSM) is simply the reverse starting with ISIS3 first with *campt* (image2ground) and then usgscsm's *ground2image*.
+<hr>

code.json

@@ -44,6 +44,96 @@
       "metadataLastUpdated": "2023-01-25"
     }
   },
+  {
+    "name": "knoten",
+    "organization": "U.S. Geological Survey",
+    "description": "GitHub code repository for the knoten package",
+    "version": "0.4.0",
+    "status": "Production",
+
+    "permissions": {
+      "usageType": "openSource",
+      "licenses": [
+        {
+          "name": "Public Domain, CC0-1.0",
+          "URL": "https://code.usgs.gov/astrogeology/knoten/-/raw/0.4.0/LICENSE.md"
+        }
+      ]
+    },
+
+    "homepageURL": "https://code.usgs.gov/astrogeology/knoten/-/tree/0.4.0",
+    "downloadURL": "https://code.usgs.gov/astrogeology/knoten/-/archive/0.4.0/knoten-0.4.0.zip",
+    "disclaimerURL": "https://code.usgs.gov/astrogeology/knoten/-/raw/0.4.0/DISCLAIMER.md",
+    "repositoryURL": "https://code.usgs.gov/astrogeology/knoten.git",
+    "vcs": "git",
+
+    "laborHours": 300,
+
+    "tags": [
+      "Planetary",
+      "Remote Sensing",
+      "Photogrammetry",
+      "Testing"
+    ],
+
+    "languages": [
+      "Python"
+    ],
+
+    "contact": {
+      "name": "Adam Paquette",
+      "email": "[email protected]"
+    },
+
+    "date": {
+      "metadataLastUpdated": "2024-05-13"
+    }
+  },
+  {
+    "name": "knoten",
+    "organization": "U.S. Geological Survey",
+    "description": "GitHub code repository for the knoten package",
+    "version": "0.3.0",
+    "status": "Production",
+
+    "permissions": {
+      "usageType": "openSource",
+      "licenses": [
+        {
+          "name": "Public Domain, CC0-1.0",
+          "URL": "https://code.usgs.gov/astrogeology/knoten/-/raw/0.3.0/LICENSE.md"
+        }
+      ]
+    },
+
+    "homepageURL": "https://code.usgs.gov/astrogeology/knoten/-/tree/0.3.0",
+    "downloadURL": "https://code.usgs.gov/astrogeology/knoten/-/archive/0.3.0/knoten-0.3.0.zip",
+    "disclaimerURL": "https://code.usgs.gov/astrogeology/knoten/-/raw/0.3.0/DISCLAIMER.md",
+    "repositoryURL": "https://code.usgs.gov/astrogeology/knoten.git",
+    "vcs": "git",
+
+    "laborHours": 300,
+
+    "tags": [
+      "Planetary",
+      "Remote Sensing",
+      "Photogrammetry",
+      "Testing"
+    ],
+
+    "languages": [
+      "Python"
+    ],
+
+    "contact": {
+      "name": "Adam Paquette",
+      "email": "[email protected]"
+    },
+
+    "date": {
+      "metadataLastUpdated": "2023-02-27"
+    }
+  },
   {
     "name": "knoten",
     "organization": "U.S. Geological Survey",