add documentation for static preview script

.gitattributes

@@ -0,0 +1 @@
+**.png filter=lfs diff=lfs merge=lfs -text

.readthedocs.yaml

@@ -20,6 +20,22 @@ build:
   os: ubuntu-22.04
   tools:
     python: mambaforge-4.10
+  jobs:
+    post_checkout:
+      # Download and uncompress the binary
+      # https://git-lfs.github.com/
+      - wget https://github.com/git-lfs/git-lfs/releases/download/v3.1.4/git-lfs-linux-amd64-v3.1.4.tar.gz
+      - tar xvfz git-lfs-linux-amd64-v3.1.4.tar.gz
+      # Modify LFS config paths to point where git-lfs binary was downloaded
+      - git config filter.lfs.process "`pwd`/git-lfs filter-process"
+      - git config filter.lfs.smudge  "`pwd`/git-lfs smudge -- %f"
+      - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f"
+      # Make LFS available in current repository
+      - ./git-lfs install
+      # Download content from remote
+      - ./git-lfs fetch
+      # Make local files to have the real content on them
+      - ./git-lfs checkout
 
 conda:
   environment: docs/rtd_environment.yaml

CHANGES.rst

@@ -6,6 +6,11 @@ jump detection
 
 - Added uneven ramp-jump detection docs. [#1035]
 
+documentation
+-------------
+
+- added user documentation for ``roman_static_preview`` script [#1046]
+
 0.13.0 (2023-11-28)
 ===================
 

docs/index.rst

@@ -42,3 +42,5 @@ The Roman Space Telescope Calibration Pipeline
 .. toctree::
    :caption: Additional Information
    :maxdepth: 1
+
+   roman/pipeline_static_preview.rst

docs/roman/pipeline_static_preview.rst

@@ -0,0 +1,112 @@
+Generating Static Previews
+==========================
+
+Roman archiving requires static preview images for viewing and selecting images, with the
+following requirements for each ``ImageModel``:
+
+- 1080p x 1080p preview image
+- 300p x 300p thumbnail image
+- output as PNG files
+- 90th percentile linear histogram stretch
+- using ``afmhot`` colormap
+- overlay indicating orientation
+
+The ``roman_static_preview`` script creates downsampled images from ASDF files containing
+an ``ImageModel``, with an optional compass rose overlayed onto the image indicating orientation.
+
+Installation
+------------
+
+The requirements for this script are not installed by default as part of ``romancal``; install with
+the ``sdp`` extra to include them.
+
+.. code-block:: shell
+
+	pip install "romancal[sdp]"
+
+Usage
+-----
+
+``roman_static_preview`` includes two convenience commands, ``preview`` and ``thumbnail``, that set
+default options to the static preview requirements.
+
+.. code-block:: shell
+
+	❯ roman_static_preview preview --help
+	Usage: roman_static_preview preview [OPTIONS] INPUT [OUTPUT] [SHAPE]...
+
+	  create a preview image with a north arrow overlay indicating orientation
+
+	Arguments:
+	  INPUT       path to ASDF file with 2D image data  [required]
+	  [OUTPUT]    path to output image file
+	  [SHAPE]...  desired pixel resolution of output image  [default: 1080, 1080]
+
+	Options:
+	  --compass / --no-compass  whether to draw a north arrow on the image
+	                            [default: compass]
+	  --help                    Show this message and exit.
+
+.. code-block:: shell
+
+	❯ roman_static_preview thumbnail --help
+	Usage: roman_static_preview thumbnail [OPTIONS] INPUT [OUTPUT] [SHAPE]...
+
+	Arguments:
+	  INPUT       path to ASDF file with 2D image data  [required]
+	  [OUTPUT]    path to output image file
+	  [SHAPE]...  desired pixel resolution of output image  [default: 300, 300]
+
+	Options:
+	  --compass / --no-compass  whether to draw a north arrow on the image
+	                            [default: no-compass]
+	  --help                    Show this message and exit.
+
+Examples
+--------
+
+.. code-block:: shell
+
+	roman_static_preview preview /grp/roman/TEST_DATA/23Q4_B11/aligntest/r0000501001001001001_01101_0001_WFI01_cal.asdf
+
+.. image:: ../images/r0000501001001001001_01101_0001_WFI01_cal.png
+   :alt: preview of simulated Roman imagery, with compass rose showing orientation
+
+.. code-block:: shell
+
+	roman_static_preview thumbnail /grp/roman/TEST_DATA/23Q4_B11/aligntest/r0000501001001001001_01101_0001_WFI01_cal.asdf
+
+.. image:: ../images/r0000501001001001001_01101_0001_WFI01_cal_thumb.png
+   :alt: thumbnail of simulated Roman imagery
+
+using ``stpreview`` directly
+----------------------------
+
+The ``roman_static_preview`` script is merely a wrapper over ``stpreview to``, which
+offers more options for fine-grained control of the output image.
+
+
+.. code-block:: shell
+
+	❯ stpreview to --help
+	Usage: stpreview to [OPTIONS] INPUT OUTPUT SHAPE... [OBSERVATORY]
+
+	  downsample the given ASDF image to the desired shape
+
+	  the output image may be smaller than the desired shape, if no even factor
+	  exists
+
+	Arguments:
+	  INPUT          path to ASDF file with 2D image data  [required]
+	  OUTPUT         path to output image file  [required]
+	  SHAPE...       desired pixel resolution of output image  [required]
+	  [OBSERVATORY]  observatory, one of ['roman', 'jwst']
+
+	Options:
+	  --compass / --no-compass  whether to draw a north arrow on the image
+	                            [default: no-compass]
+	  --help                    Show this message and exit.
+
+Refer to
+`the ``stpreview`` documentation <https://github.com/spacetelescope/stpreview#usage>`_
+for usage instructions.