ImageViewerLogic#

class astro_image_display_api.image_viewer_logic.ImageViewerLogic(_center: tuple[Real, Real] = (0.0, 0.0))[source]#

Bases: object

This viewer does not do anything except making changes to its internal state to simulate the behavior of a real viewer.

Attributes Summary

`catalog_labels`	Names of the loaded catalogs.
`image_labels`	Labels of the loaded images.

Methods Summary

`get_catalog`([x_colname, y_colname, ...])	Get the marker positions.
`get_catalog_style`([catalog_label])	Get the style of the catalog markers.
`get_colormap`([image_label])	Get the current colormap for the image.
`get_cuts`([image_label])	Get the current cuts for the image.
`get_image`([image_label])	Get the data of a loaded image.
`get_stretch`([image_label])	Get the current stretch for the image.
`get_viewport`([sky_or_pixel, image_label])	Get the current viewport of the image.
`load_catalog`(table[, x_colname, y_colname, ...])	Add catalog entries to the viewer at positions given by the catalog.
`load_image`(data[, image_label])	Load a FITS file, 2D array or `NDData` object into the viewer and display it.
`remove_catalog`([catalog_label])	Remove markers from the image.
`save`(filename[, overwrite])	Save the current view to a file.
`set_catalog_style`([catalog_label, shape, ...])	Set the style of the catalog markers.
`set_colormap`(map_name[, image_label])	Set the colormap for the image specified by image_label.
`set_cuts`(cuts[, image_label])	Set the cuts for the image.
`set_stretch`(stretch[, image_label])	Set the stretch for the image.
`set_viewport`([center, fov, image_label])	Set the viewport of the image, which defines the center and field of view.

Attributes Documentation

catalog_labels#

Names of the loaded catalogs.

Returns:

tuple of str: The names of the loaded catalogs.

Notes

This has no effect on the displayed image.

image_labels#

Labels of the loaded images.

Returns:

image_labels: tuple of str: The labels of the loaded images.

Methods Documentation

get_catalog(x_colname: str = 'x', y_colname: str = 'y', skycoord_colname: str = 'coord', catalog_label: str | None = None, **kwargs) → Table[source]#

Get the marker positions.

Parameters:

x_colnamestr, optional: The name of the column containing the x positions. Default is 'x'.
y_colnamestr, optional: The name of the column containing the y positions. Default is 'y'.
skycoord_colnamestr, optional: The name of the column containing the sky coordinates. Default is 'coord'.
catalog_labelstr, optional: The name of the catalog set to get.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

tableastropy.table.Table: The table containing the marker positions. If no catalogs are loaded and no catalog_label is given, an empty table is returned.

Raises:

ValueError: If the catalog_label is not provided when there are multiple catalogs loaded, or if the catalog_label does not correspond to a loaded catalog.

Notes

This has no effect on the displayed image.

get_catalog_style(catalog_label=None, **kwargs) → dict[str, Any][source]#

Get the style of the catalog markers.

Parameters:

catalog_labelstr, optional: The name of the catalog. If not given and there is only one catalog loaded, the style for that catalog is returned. If there are multiple catalogs and no label is provided, an error is raised. If no label is given and no catalogs are loaded, the default style is returned.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

dict: The style of the markers. The dictionary always contains at least the keys shape, color and size, and a catalog_label key whose value is the label of the catalog the style belongs to. When the default style is returned because no catalogs are loaded, the value of the catalog_label key is None.

Raises:

ValueError: If there are multiple catalog labels defined and the user has not specified a catalog_label for which to get the style, or if the catalog_label does not correspond to a loaded catalog.

Notes

This has no effect on the displayed image.

get_colormap(image_label: str | None = None, **kwargs) → str | None[source]#

Get the current colormap for the image.

Parameters:

image_labelstr, optional: The label of the image to get the colormap for. If not given and there is only one image loaded, the colormap for that image is returned. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

map_namestr or None: The name of the current colormap, or None if no colormap has been set for the image. A return of None means the backend is using whatever default colormap it chooses; a backend may instead return the name of that default.

Raises:

ValueError: If the image_label is not provided when there are multiple images loaded or if the image_label does not correspond to a loaded image.

Notes

This has no effect on the displayed image.

get_cuts(image_label: str | None = None, **kwargs) → BaseInterval[source]#

Get the current cuts for the image.

Parameters:

image_labeloptional: The label of the image to get the cuts for. If not given and there is only one image loaded, the cuts for that image are returned. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

cutsastropy.visualization.BaseInterval: The Astropy interval object representing the current cuts.

Raises:

ValueError: If the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image.

Notes

This has no effect on the displayed image.

get_image(image_label: str | None = None, **kwargs) → ArrayLike | NDData | CCDData[source]#

Get the data of a loaded image.

Parameters:

image_labeloptional: The label of the image to get. If not given and there is only one image loaded, that image is returned.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

image_dataAny: The data that was loaded for the image with the given label. The returned object must either be array-like or expose the array of image values through a data attribute, as NDData and its subclasses do. It is expected that the returned data can be re-loaded into the viewer using load_image.

Raises:

ValueError: If the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image.

get_stretch(image_label: str | None = None, **kwargs) → BaseStretch[source]#

Get the current stretch for the image.

Parameters:

image_labelstr, optional: The label of the image to get the stretch for. If not given and there is only one image loaded, the stretch for that image is returned. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

stretchBaseStretch: The Astropy stretch object representing the current stretch.

Raises:

ValueError: If the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image.

Notes

This has no effect on the displayed image.

get_viewport(sky_or_pixel: str | None = None, image_label: str | None = None, **kwargs) → dict[str, Any][source]#

Get the current viewport of the image.

Parameters:

sky_or_pixelstr, optional: If ‘sky’, the center will be returned as a SkyCoord object. If ‘pixel’, the center will be returned as a tuple of pixel coordinates. If None, the default behavior is to return the center as a SkyCoord if possible, or as a tuple of floats if the image is in pixel coordinates and has no WCS information.
image_labelstr, optional: The label of the image to get the viewport for. If not given and there is only one image loaded, the viewport for that image is returned. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Returns:

dict: A dictionary containing the current viewport settings. The keys are ‘center’, ‘fov’, and ‘image_label’. - ‘center’ is an SkyCoord object or a tuple of floats. - ‘fov’ is an Quantity object or a float. - ‘image_label’ is a string representing the label of the image (the default label if the image was loaded without one).

Raises:

ValueError: If the sky_or_pixel parameter is not one of ‘sky’, ‘pixel’, or None, or if the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image. Also raised if a conversion between pixel and sky coordinates is needed to satisfy the requested sky_or_pixel but the image has no WCS; the error message contains “WCS is not set”.

Notes

This has no effect on the displayed image.

load_catalog(table: Table, x_colname: str = 'x', y_colname: str = 'y', skycoord_colname: str = 'coord', use_skycoord: bool = False, catalog_label: str | None = None, catalog_style: dict | None = None, **kwargs) → None[source]#

Add catalog entries to the viewer at positions given by the catalog.

Loading a catalog using a catalog_label that already exists will overwrite the existing catalog with the new one.

Parameters:

tableastropy.table.Table: The table containing the marker positions.
x_colnamestr, optional: The name of the column containing the x positions. Default is 'x'.
y_colnamestr, optional: The name of the column containing the y positions. Default is 'y'.
skycoord_colnamestr, optional: The name of the column containing the sky coordinates, as SkyCoord objects. The column is only used for marker positions when use_skycoord is True. Default is 'coord'.
use_skycoordbool, optional: Whether marker positions come from sky or pixel coordinates. If True, positions are taken from the skycoord_colname column, or computed from the pixel position columns and the image’s WCS if the table has no sky-coordinate column. If False (the default), positions are taken from the x_colname/y_colname columns, or computed from the sky-coordinate column and the image’s WCS if the table has no pixel position columns. An error is raised when the requested mode is impossible with the available columns and WCS.
catalog_labelstr, optional: The name to use for the catalog. If not given, a single shared default label is used, so loading a catalog without a label repeatedly replaces the previously loaded unlabeled catalog.
catalog_styledict, optional: A dictionary that specifies the style of the markers used to represent the catalog. See set_catalog_style for details.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

ValueError: If pixel positions are requested (use_skycoord=False) but the table has no pixel position columns and they cannot be computed (error message starts with “Cannot use pixel coordinates without pixel columns”), or if sky positions are requested (use_skycoord=True) but the table has no sky-coordinate column and there is no WCS to compute one (error message starts with “Cannot use sky coordinates without”). Also raised if a pixel/sky conversion is required but the backend cannot determine which image’s WCS to use (e.g. because several images are loaded).

Notes

This should display the markers on the image in addition to storing the marker positions in the viewer.

load_image(data: str | PathLike | ArrayLike | NDData, image_label: str | None = None, **kwargs) → None[source]#

Load a FITS file, 2D array or NDData object into the viewer and display it.

Parameters:

datastr, os.PathLike, array-like or NDData: The data to load. A string or path is interpreted as the name of a FITS file (or of an ASDF file when it ends in .asdf).
image_labelstr, optional: The label for the image. If not given, a single shared default label is used, so loading an image without a label repeatedly replaces the previously loaded unlabeled image.
**kwargs: Additional keyword arguments that may be used by the viewer.

Notes

Loading an image sets an appropriate viewport for that image and makes it the displayed image, replacing the image that was displayed before.

Loading data under an image_label that already exists replaces that label’s data but keeps the cuts, stretch and colormap that were set for the label; the viewport is reset to fit the new data. An image loaded under a new label starts from the default settings.

remove_catalog(catalog_label: str | None = None, **kwargs) → None[source]#

Remove markers from the image.

Parameters:

catalog_labelstr, optional: The name of the catalog to remove. The value '*' can be used to remove all catalogs. If not given and there is only one catalog loaded, that catalog is removed.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

ValueError: If the catalog_label is not provided when there are multiple catalogs loaded, or if the catalog_label does not correspond to a loaded catalog.
TypeError: If the catalog_label is a list. Only a single catalog label or '*' may be given.

save(filename: str | PathLike, overwrite: bool = False, **kwargs) → None[source]#

Save the current view to a file.

Parameters:

filenamestr or os.PathLike: The file to save to. The format is determined by the extension.
overwritebool, optional: If True, overwrite the file if it exists. Default is False.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

FileExistsError: If the file already exists and overwrite is False.

Notes

This has no effect on the displayed image.

set_catalog_style(catalog_label: str | None = None, shape: str = 'circle', color: str = 'red', size: float = 5, **kwargs) → None[source]#

Set the style of the catalog markers.

Parameters:

catalog_labelstr, optional: The label of the catalog whose style is being set. If not given and there is only one catalog loaded, the style for that catalog is set. If there are multiple catalogs and no label is provided, an error is raised.
shapestr, optional: The shape of the markers. Default is 'circle'. The set of supported shapes is listed below in the Note section below.
colorstr, optional: The color of the markers. Default is 'red'. Permitted colors are any CSS4 color name. CSS4 also permits hex RGB or RGBA colors.
sizefloat, optional: The size of the markers. Default is 5.0.
**kwargs: Additional keyword arguments to pass to the marker style.

Raises:

ValueError: If there are multiple catalog styles set and the user has not specified a catalog_label for which to set the style, or if an style is set for a catalog that does not exist.

Notes

The following shapes are supported: “circle”, “square”, “crosshair”, “plus”, “diamond”.

Changing the style of the markers should update the display of the markers in the image.

set_colormap(map_name: str, image_label: str | None = None, **kwargs) → None[source]#

Set the colormap for the image specified by image_label.

Parameters:

map_name: The name of the colormap to set. This should be a valid colormap name from Matplotlib. Not all backends support all colormaps; a backend must raise a ValueError for a colormap name it does not support.
image_labeloptional: The label of the image to set the colormap for. If not given and there is only one image loaded, the colormap for that image is set. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

ValueError: If the map_name is not a colormap name the backend supports, if the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image.

Notes

This should update the display of the image to reflect the new colormap.

set_cuts(cuts: tuple[Real, Real] | BaseInterval, image_label: str | None = None, **kwargs) → None[source]#

Set the cuts for the image.

Parameters:

cuts: any interval from `astropy.visualization`: The cuts to set. If a tuple, it should be of the form (min, max) and will be interpreted as a ManualInterval.
image_labeloptional: The label of the image to set the cuts for. If not given and there is only one image loaded, the cuts for that image are set.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

TypeError: If the cuts parameter is not a tuple or an astropy.visualization.BaseInterval object.
ValueError: If the image_label is not provided when there are multiple images loaded, or if the image_label does not correspond to a loaded image.

Notes

Setting cuts should update the display of the image to reflect the new cuts.

set_stretch(stretch: BaseStretch, image_label: str | None = None, **kwargs) → None[source]#

Set the stretch for the image.

Parameters:

stretchAny stretch from visualization: The stretch to set. This can be any subclass of BaseStretch.
image_label: The label of the image to set the stretch for. If not given and there is only one image loaded, the stretch for that image are set.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

TypeError: If the stretch is not a valid BaseStretch object.
ValueError: If the image_label is not provided when there are multiple images loaded or if the image_label does not correspond to a loaded image.

Notes

Setting the stretch should update the display of the image to reflect the new stretch.

Set the viewport of the image, which defines the center and field of view.

Parameters:

centerastropy.coordinates.SkyCoord or tuple of float, optional: The center of the viewport. If not given, the current center is used.
fovastropy.units.Quantity or float, optional: The field of view (FOV) of the viewport. If not given, the current FOV is used. If a float is given, it is interpreted as a size in pixels. For viewers that are not square, the FOV is interpreted as the size of the shorter side of the viewer such that the FOV is guaranteed to be entirely visible regardless of the aspect ratio of the viewer.
image_labelstr, optional: The label of the image to set the viewport for. If not given and there is only one image loaded, the viewport for that image is set. If there are multiple images and no label is provided, an error is raised.
**kwargs: Additional keyword arguments that may be used by the viewer.

Raises:

TypeError: If the center is not a SkyCoord object or a tuple of floats (error message starts with “Invalid value for center”), or if the fov is not an angular Quantity or a float (error message starts with “Invalid value for fov”). Also raised if the image has no WCS and a sky value is given where the stored viewport is in pixels, or vice versa, so that no conversion is possible; those error messages start with “Center must be a tuple”, “Center must be a SkyCoord” or “FOV must be a float”.
ValueError: If image_label is not provided when there are multiple images loaded.
astropy.units.UnitTypeError: If the fov is a Quantity but does not have an angular unit (error message starts with “Incorrect unit for fov”).

Notes

Setting the viewport should update the display of the image to reflect the new viewport.