.. _draw:

***********************
spacekit.generator.draw
***********************

.. currentmodule:: spacekit.generator.draw

.. autoclass:: DrawMosaics
   :members:
   :undoc-members:
   :show-inheritance:

Generates machine-learning image inputs from drizzled total detection fits files and their associated catalog files. Primarily used for creating a batch of multiple images at once, although it can also be used to draw a single image/single dataset.

Opens fits files from a local directory to generate total detection drizzled images as matplotlib
figures, aligned to WCS with point/segment/gaia catalog overlays. Figures are stripped down to just the pixel values
(no visible axes or legends) and saved to disk as png files. These images can then be used to train an image classification neural network. To draw the images, you need to have at least the ``*_drz/*_drc.fits`` file locally.

To draw the catalog overlay(s), you would also need the .ecsv catalog file(s). The fits and catalog files are generated by running Drizzlepac's Runsinglehap SVM processing script on the raw input files.

Relative Filter Images
^^^^^^^^^^^^^^^^^^^^^^
This script can also be used to generate relative filter images for use in the image similarity
model by passing img_type='filter' (default is "total" for total detection images).

Synthetic (artifically corrupted) datasets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This script also has the capability of drawing images using "corrupt" datasets (see ``spacekit.skopes.hst.svm.corrupt``). Setting ``crpt=1`` or ``c=1`` tells the script how to name the image subfolder for that dataset (so that it doesn't overwrite a regular/non-corrupt dataset with the same name.

   - P: draw point catalog references (0=off, 1=on) default is 0
   - S: draw segment catalog references (0=off, 1=on) default is 0
   - G: draw GAIA catalog references (0=off, 1=on) default is 0

If the above catalog overlays are turned on, the saved images will be saved with the appropriate suffix appended:

    * ``P=1: _point.png``
    * ``S=1: _segment.png``
    * ``P=1, S=1 (both point and segment): _source.png``
    * ``G=1 _gaia.png``

.. note::

   For the SVM Alignment Image Classifier (see spacekit.skopes.hst.svm.prep module), 3 images are produced for each visit:

      * **original** image (no catalog overlay)
      * **source image** (both point and segment catalog overlays)
      * **gaia image** (GAIA catalog overlay)

PNG naming convention is based on fits file unless ``crpt=1``:

``./input_path/dataset/fname.fits``

saves as:

``./img_path/dataset/fname.png``

Normal SVM data
^^^^^^^^^^^^^^^

``dataset=ib1f0a``

``./{input_path}/ib1f0a/hst_11570_0a_wfc3_uvis_total_ib1f0a_drc.fits``

saves as:

``./{imgdir}/hst_11570_0a_wfc3_uvis_total_ib1f0a/hst_11570_0a_wfc3_uvis_total_ib1f0a.png``

Corruption SVM data 
^^^^^^^^^^^^^^^^^^^
``dataset=ia0m04_f110w_all_stat``

``./{input_path}/ia0m04_f110w_all_stoc/hst_11099_04_wfc3_ir_total_ia0m04_drz.fits``

saves as:

``./{imgdir}/hst_f110w_all_stoc_uvis_total_ib1f0a/hst_f110w_all_stoc_uvis_total_ib1f0a.png``

CREDIT: much of the code used for plotting the data from a .fits sci extension (``draw_total_images``) and drawing the catalog overlays (``point_flag_color``, ``segment_flag_color``) is derived from work done by `Matthew Burger <https://github.com/mburger-stsci>`_.