Skip to content

Commit

Permalink
Edits to docs for Imviz (spacetelescope#2674)
Browse files Browse the repository at this point in the history 
* Typo filepath

* Add how to set viewer

* Compact example from API

* Python 3.11 intead of 3.9

* Include images and rearrange the plot option part

* Typo

* More edits to stretch

* Address review

---------

Co-authored-by: Camilla Pacifici <[email protected]>
  • Loading branch information
@camipacifici
camipacifici and Camilla Pacifici authored Feb 2, 2024
1 parent 9373a9e commit db6fbc1
Show file tree
Hide file tree
Showing 4 changed files with 101 additions and 105 deletions.
Binary file added docs/img/imviz_plot_options.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
197 changes: 96 additions & 101 deletions docs/imviz/displayimages.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ allows the user to zoom images in multiple different viewers simultaneously, not
:ref:`imviz_pan_zoom`.

Single-viewer Box Zoom is also available and is used in a similar way as in
other Jdaviz tools. To access this option when there are multiple viewers,
other Jdaviz tools. To access this option when there are multiple viewers,
right-click on the Linked Box Zoom button and left-click on the second option down to select it.

.. _imviz_pan_zoom:
Expand Down Expand Up @@ -281,42 +281,90 @@ To access all of the different display settings for an image viewer, click the
Changing the display settings DOES NOT change the underlying data, only the
visualization of that data.

.. image:: ../img/imviz_plot_options.png
:alt: Imviz Plot Options

If you wish to access plot options via API
(also see `~jdaviz.configs.default.plugins.plot_options.plot_options.PlotOptions`),
you can do the following:
you can use the following generic example. More specific examples are given
later in this Section.

.. code-block:: python
plot_options = imviz.plugins['Plot Options']
plot_options.layer = 'my file'
plot_options.image_colormap = 'Plasma'
plot_options.stretch_function = 'Arcsinh'
plot_options.stretch_vmin = 0.05
plot_options.stretch_vmax = 1.0
Layer
-----

This option allows you to change which layer you are changing the settings for.

Attribute
---------
Show image
----------

This shows which extension of the data is being displayed in the current viewer.
This option selects whether to show or hide the image in the viewer.

Contour
-------
Color mode
----------

This option allows you to choose whether to use a colormap or or a single color to visualize the image.
The colormap can be selected from a dropdown within the Layer tab. In monochromatic mode, the color
can be chosen from a color picker under "Image Color" within the Layer tab.

In monochromatic mode, the option "Assign RGB presets" appears. This will automatically
assign colors spanning from blue to red to the available layers and will adjust opacity and
stretch to produce a composite color image (also known as RGB image). You will then
be able to fine tune all options within each Layer tab.

From the API
^^^^^^^^^^^^

The colormap for just the image being displayed can be set using the Astrowidgets API:

.. code-block:: python
This option selects whether to show or hide contours.
viewer = imviz.default_viewer
viewer.colormap_options
viewer.set_colormap('Viridis')
The :guilabel:`Contours` of a second image can also be plotted over a first image or cube. Add
the second image as data in the data dropdown tab, and select both images. To visualize the contours
of the second image, go to the :guilabel:`Layer` tab, select the layer to be contour-mapped, and
set its :guilabel:`Contour` to be on and its :guilabel:`Bitmap` to be off. The contours of
the second image will appear superimposed on the first image. In the second figure below, we
show the contours of an image generated using the Collapse plugin plotted over the leftmost cube
viewer. If you overplot them on a cube, the contours will remain unchanged as you scrub through
the cube.
Or it can be set using the Plugin API (in this example, the colormap is
being set for all the images at once):

Bitmap
------
.. code-block:: python
This option selects whether to show or hide the bitmap (image) in the viewer.
plot_options = imviz.plugins['Plot Options']
plot_options.select_all()
plot_options.image_colormap = 'Viridis'
.. _imviz_custom_colormap:

Adding Custom Colormap
^^^^^^^^^^^^^^^^^^^^^^

A custom colormap can only be added when Imviz is run in a notebook, not from the
command line. The custom colormap must be added to Glue *before* starting Imviz.
The example below adds a random colormap generated by ``photutils`` into Glue:

.. code-block:: python
from glue.config import colormaps
from photutils.utils import make_random_cmap
randcmap = make_random_cmap(ncolors=256)
randcmap.colors[0] = 0. # To make your background black
colormaps.add('photutils_cmap', randcmap)
Only after the above is done can you start Imviz and use the custom colormap:

.. code-block:: python
imviz = Imviz()
imviz.load_data('myimage.fits')
imviz.default_viewer.set_colormap('photutils_cmap')
Opacity
-------
Expand All @@ -343,25 +391,34 @@ bias values by sliding it left.
Stretch
-------

Change the equation that is used to convert data values between
:guilabel:`min` and :guilabel:`max` to the 0 to 1 scale of pixel saturation on the displayed
image.
The Stretch Function allows you to change the equation that is used to convert data values between
:guilabel:`min` and :guilabel:`max` to the 0 to 1 scale of pixel saturation on the
image. The Percentile can be used to set the :guilabel:`min` and :guilabel:`max`
values based on percentiles of the data.
An interactive histogram is available. It shows vertical lines representing
the ``stretch_vmin`` and ``stretch_vmax`` values, and a colorbar on top.
The stretch "curve" is plotted on the histogram to represent
how pixel values are mapped to the colorbar and can be toggled on and off in the plugin.
The collapsed menu "More stretch options"
includes a toggle to limit the histogram to the current zoom limits (which is not on by default)
and fields to set :guilabel:`min` and :guilabel:`max` manually.

From the API
^^^^^^^^^^^^

To set the stretch function for just the image being displayed.
The acceptable values are as defined by glue backend:
The stretch function for just the image being displayed
(the acceptable values are as defined by glue backend) can be set using
the Astrowidgets API:

.. code-block:: python
viewer = imviz.default_viewer
viewer.stretch_options
viewer.stretch = 'sqrt'
To set the stretch function for all the images at once.
The acceptable values are the same as the GUI menu options
can be accessed with ``plot_options.stretch_function.choices``:
Or it can be set using the Plugin API for a single image or all the images at once
(the acceptable values are the same as the GUI menu options
and can be accessed with ``plot_options.stretch_function.choices``):

.. code-block:: python
Expand All @@ -370,46 +427,24 @@ can be accessed with ``plot_options.stretch_function.choices``:
plot_options.stretch_function = 'Square Root'
A histogram is displayed showing the distribution of pixel values, with
vertical lines representing the ``stretch_vmin`` and ``stretch_vmax``
values, and a colorbar on top. A stretch "curve" can be plotted under the histogram to represent
how pixel values are mapped to the colorbar. This feature can be toggled
on from the API with:
The stretch curve on the histogram can also be toggled using the Plugin API:

.. code-block:: python
plot_options = imviz.plugins['Plot Options']
plot_options.stretch_curve_visible = True
Percentile
----------

Can be used to set the :guilabel:`min` and :guilabel:`max` values based on percentiles of the data.

Min
^^^

If the percentile is "custom", then the data value corresponding to the
minimum of the colormap scale (e.g., black in grayscale) can be set.

Max
^^^
If the percentile is "custom", then the data value corresponding to the
maximum of the colormap scale (e.g., white in grayscale) can be set.

From the API
^^^^^^^^^^^^

To set the percentile for just the image being displayed:
The percentile for just the image being displayed can be set
using the Astrowidgets API:

.. code-block:: python
viewer = imviz.default_viewer
viewer.cuts = '95%' # Preset
viewer.cuts = (0, 1000) # Custom
To set the percentile for all the images at once:
Or it can be set using the Plugin API for one image or all the images at once:

.. code-block:: python
Expand All @@ -424,55 +459,15 @@ To set the percentile for all the images at once:
plot_options.stretch_vmin = 0
plot_options.stretch_vmax = 1000
Colormap
--------

The spectrum of colors used to visualize data can be changed using this drop-down.

From the API
^^^^^^^^^^^^

To set the colormap for just the image being displayed:

.. code-block:: python
viewer = imviz.default_viewer
viewer.colormap_options
viewer.set_colormap('Viridis')
To set the colormap for all the images at once:

.. code-block:: python
plot_options = imviz.plugins['Plot Options']
plot_options.select_all()
plot_options.image_colormap = 'Viridis'
.. _imviz_custom_colormap:

Adding Custom Colormap
^^^^^^^^^^^^^^^^^^^^^^

A custom colormap can only be added when Imviz is run in a notebook, not from the
command line. The custom colormap must be added to Glue *before* starting Imviz.
The example below adds a random colormap generated by ``photutils`` into Glue:

.. code-block:: python
from glue.config import colormaps
from photutils.utils import make_random_cmap
randcmap = make_random_cmap(ncolors=256)
randcmap.colors[0] = 0. # To make your background black
colormaps.add('photutils_cmap', randcmap)
Only after the above is done can you start Imviz and use the custom colormap:

.. code-block:: python
Contour
-------

imviz = Imviz()
imviz.load_data('myimage.fits')
imviz.default_viewer.set_colormap('photutils_cmap')
This option selects whether to show or hide contours. It is off by default and can be
turned on by clicking the eye icon. The :guilabel:`Contours` of a second image can
be plotted over a first image or cube. The contours of the second image will appear
superimposed on the first image. If contours are overplotted on a cube, the contours
will remain unchanged as you scrub through the cube. Please note that this feature is in
development and will be improved in the future.

Adding New Viewers
==================
Expand Down
3 changes: 2 additions & 1 deletion docs/imviz/import_data.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ data entries into the viewer until after the parsing is complete::
imviz = Imviz()
with imviz.batch_load():
for filepath in filepaths:
imviz.load_data(filepaths)
imviz.load_data(filepath)
imviz.show()


Expand All @@ -150,6 +150,7 @@ Loading markers can be done with the following commands:

.. code-block:: python
viewer = imviz.default_viewer
viewer.marker = {'color': 'green', 'alpha': 0.8, 'markersize': 10, 'fill': False}
my_markers = Table.read('my_catalog.ecsv')
coord_i2d = Table({'coord': [SkyCoord(ra=my_catalog['sky_centroid'].ra.degree,
Expand Down
6 changes: 3 additions & 3 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Windows-Specific Dependencies
Some of our dependencies require C++ compilers to install properly. These are usually
included with macOS and most Linux distributions, but are not included by default in
Windows. Microsoft provides these tools as part of their
`Build Tools for Visual Studio <https://visualstudio.microsoft.com/downloads>`_,
`Build Tools for Visual Studio <https://visualstudio.microsoft.com/downloads>`_,
which can be found under "Tools for Visual Studio" towards the bottom of the page.

Create Your Local Environment
Expand All @@ -35,7 +35,7 @@ to avoid version conflicts with other packages you may have installed, for examp

.. code-block:: bash
conda create -n jdaviz-env python=3.9
conda create -n jdaviz-env python=3.11
conda activate jdaviz-env
Pip Install
Expand Down Expand Up @@ -146,4 +146,4 @@ after you restarted the Python kernel):
pip install -e .
Note: It is recommended to install the package without ``-e`` flag initially
to ensure that the template files are copied correctly.
to ensure that the template files are copied correctly.

0 comments on commit db6fbc1

Please sign in to comment.