Update docs to include more info about tangent plane units (#179)

spacetelescope · Apr 14, 2023 · 62d4cdc · 62d4cdc
1 parent b9d0076
commit 62d4cdc
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 4 deletions.
diff --git a/tweakwcs/correctors.py b/tweakwcs/correctors.py
@@ -271,7 +271,8 @@ def bounding_box(self):
 
 class FITSWCSCorrector(WCSCorrector):
  """ A class for holding ``FITS`` ``WCS`` information and for managing
- tangent-plane corrections.
+ tangent-plane corrections. The units of the tangent plane of this
+ corrector are same as detector coordinates.
 
  .. note::
  Currently only WCS objects that have ``CPDIS``, ``DET2IM``, and ``SIP``
@@ -557,7 +558,9 @@ def _get_submodel(model, name):
 
 class JWSTWCSCorrector(WCSCorrector):
  """ A class for holding ``JWST`` ``gWCS`` information and for managing
- tangent-plane corrections.
+ tangent-plane corrections. The units of the tangent plane of this
+ corrector are ``arcsec`` and the axes are not along parallel to the
+ axes of the detector's coordinate system.
 
  """
  units = 'arcsec'

diff --git a/tweakwcs/imalign.py b/tweakwcs/imalign.py
@@ -166,7 +166,7 @@ def fit_wcs(refcat, imcat, corrector, ref_tpwcs=None, fitgeom='general',
  object. ``'fit_info'`` is a dictionary with the following items:
 
  * **'shift'**: A ``numpy.ndarray`` with two components of the
- computed shift.
+ computed shift. Note: shift is in units of the *tangent plane*.
 
  * **'matrix'**: A ``2x2`` ``numpy.ndarray`` with the computed
  generalized rotation matrix.

diff --git a/tweakwcs/wcsimage.py b/tweakwcs/wcsimage.py
@@ -1196,7 +1196,8 @@ def align_to_ref(self, refcat, ref_tpwcs=None, match=None, minobj=None,
  * **'fitgeom'**: the value of the ``fitgeom`` argument
  * **'eff_minobj'**: effective value of the ``minobj`` parameter
  * **'matrix'**: computed rotation matrix
- * **'shift'**: shift (offset) along X- and Y-axis
+ * **'shift'**: shift (offset) along X- and Y-axis in units of the
+ *tangent plane* coordinates.
  * **'rot'**: A tuple of ``(rotx, roty)`` - the rotation angles with
  regard to the ``X`` and ``Y`` axes.
  * **'<rot>'**: *Arithmetic mean* of the angles of rotation around
@@ -1251,6 +1252,12 @@ def align_to_ref(self, refcat, ref_tpwcs=None, match=None, minobj=None,
  errors. Use other fields to evaluate alignment: fit ``RMSE``
  and ``MAE`` values, number of matched sources, etc.
 
+ .. note::
+ Many quantities in ``fit_info`` are in units of the *tangent plane*
+ coordinates, e.g., ``shift``, ``rmse``, ``std``, ``mae``. See
+ specific ``WCSCorrector`` in `~tweakwcs.correctors` for the units
+ of the tangent plane.
+
  Parameters
  ----------
  refcat: RefCatalog