*********************************
Known Issues (Pending Validation)
*********************************

Below is a list of known issues with STIPS that are pending validation. Items will be
removed from this list as they are addressed in future STIPS updates.

* The orientation of the image is non-standard, with east pointing to the right of the
  image. The relative position of sources is not affected.

* There exists a function to place extended sources given a set of Sersic parameters, but
  its validity and functionality have not been tested.

* The flux measurements of sources are only validated in the absence of noise/background.
  As such, the net flux of the image may be inaccurate.

* STIPS interpolates nine PSFs generated by STPSF across the detector to the location of the
  source being placed. However, there is currently a known offset of 20 pixels (in both the
  X and Y directions) between the location at which the PSF is interpolated, and the
  location at which the target is displayed. The header of the output image lists both of these locations:
  'x' and 'y' for the location at which the PSF is interpolated and 'x_input' and 'y_input' for the
  location at which the target is displayed.

  .. note::

    This does not affect the target position or center on the detector. It only means that,
    if a point source is created with a position of (x, y), it will be placed at location
    (x, y) but the interpolated PSF shape will be the shape of the PSF at location (x+20, y+20).
    Because the WFI PSF shape does not vary strongly over this distance, the effect is
    minimal and should not be a concern for most science cases. If ultra-precise PSF models
    are required, the user should generate them directly with STPSF at the desired pixel
    location.

* Bright sources will have large diffraction spikes that are visible beyond 22 pixels away
  from the center of the source. A ``psf_bright_limit`` and ``psf_xbright_limit`` (extra-bright limit)
  magnitude can be specified –– objects brighter than this threshold will be computed out
  to a radius of 44 (bright) and 88 (extra-bright) pixels, respectively. Note that,
  because point source flux is computed for every pixel, bright targets will take
  roughly four times as long (and extra-bright sources 16 times as long) to compute as
  standard sources, so these limits should only be set when it matters.

* The STIPS star generation sub-module (``stips.star_generator``) depends on the ``esutil``
  Python module. This module can currently be installed as part of a Conda environment, but
  can't be installed in a working state from a pip/setup environment. As such, if you are
  installing STIPS without using Conda, *and* you need to use the star generation sub-module,
  you will have to make an additional step. *After* installing STIPS, but before using it,
  install ``esutil`` using pip without using a local cache
  (i.e. run ``pip install esutil --no-cache-dir``).

If you encounter any issues not listed here, please see the :doc:`help <help>` page.