/ chips4.11 / ahelp / add_image.html

Jump to: Description · Examples · Image Preferences and Attributes · Supported World Coordinate Systems · Bugs · See Also

AHELP for CIAO 4.11 ChIPS v1

add_image

Context: images

Synopsis

Adds an image to the current window.

Syntax

add_image([id,] filename [,attributes])
add_image([id,] IMAGECrate [,attributes])

add_image([id,] numpy array [,transform] [,attributes])
add_image([id,] array, nx, ny [,transform] [,attributes])

add_image([id,] red_image, green_image, blue_image [,alpha_image]
[,transform] [,attributes])

Description

The function arguments.

Argument	Description
id	A ChipsId structure identifying the item.
filename	The name of the file containing an image to display. This can include CIAO DataModel filters, such as "evt2.fits[energy=500:7000][bin sky=8]", to automatically filter and bin a table before displaying it.
IMAGECrate	An image crate, returned either by a read_file call or a call to the IMAGECrate constructor (see "ahelp crate").
numpy array	A one- or two-dimensional NumPy array.
array, nx, ny	A Python list or NumPy array. The nx and ny arguments must be given to determine the display size.
red_image, green_image, blue_image	The images to use for the red, green, and blue channels when using three-color images. The arguments can either be file names or NumPy arrays. To ignore a channel set its value to None.
alpha_image	The optional opacity image (0 is fully transparent and 1 is fully opaque) for three-color images. The argument can either be a file name or a NumPy array.
transform	A pytransform object that determines the mapping between the logical coordinate system, where (1,1) refers to the center of the bottom-left pixel, and the display system. At present this should either be a LINEAR2DTransform or WCSTransform object that contains a tangent-plane projection.
attributes	Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The add_image command loads an image from file or Crate to the current ChIPS window whose attributes are specified by user preferences or in an attribute list. The new image becomes current by default; providing a ChipsId overrides the currency state.

Creating an image plot

You can add images in several ways:

as a filename, including any Data Model filters;
the return value of Crates' read_file() command (when called on an image);
as a one- or two- dimensional array (data-array) - the width (nx) and height (ny) are required if data-array is not a one or two-dimensional numpy array.

For example:

chips> add_image('img.fits')

chips> ivals = np.arange(12).reshape(3,4)
chips> add_image(ivals)

and

chips> add_image([1,2,3,4,5,6,7,8,9], 3, 3)

will each add an image to the current ChIPS window (or create the window, if necessary).

Coordinates

Unless explicitly set by the "wcs" attribute, images are displayed using the "most specific" coordinate system supported by ChIPS; that is the WCS system, if specified and in the tangent-plane format, otherwise physical or, if not given, logical.

True Color Images

True color images are composed of multiple, co-aligned images, where each image specifies a red, green, blue, or alpha channel of the combined images. Not all image channels need to be specified; those that are left empty will be treated as zero. The components of a true color image must have the same WCS, otherwise the images will not line up correctly.

Customizing the Image

There are several attributes that control the image characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_image command, or values from the user's preference file.

The attributes may also be modified with the set_image command at any time; see "ahelp set_image" and "ahelp setget" for more information.

Please see the "Image Preferences and Attributes" section below the examples for a list of the image preferences.

Examples

Example 1

chips> add_image("img.fits")

Display the contents of the file "img.fits" as an image. If the image contains WCS information, then it will be used for the X and Y axes; in this case you may wish to change the tick label format to use sexagesimal notation by saying:

chips> set_xaxis(["tickformat", "ra"])
chips> set_yaxis(["tickformat", "dec"])

Example 2

chips> add_image("img.fits", ["wcs", "physical"])

Here the image is displayed using the physical coordinate system; for Chandra data this is the SKY system.

Example 3

chips> img = np.arange(150).reshape(10, 15)
chips> add_image(img)
chips> set_plot_aspect_ratio('fit')
chips> set_image(['colormap', 'hsv', 'depth', 50])

This example displays a 15 pixel (X) by 10 pixel (Y) image, changing the plot so that it matches the aspect ratio of the data. The depth of the image is changed to 50 so that the pixels do not cover the tick marks of the axes. An alternative would be to change the minor and major tick marks so that they are drawn outside of the plot area with a call like

chips> set_axis(['*.tickstyle', 'outside'])

Example 4

chips> add_image("img.fits", ["interpolation", "bilinear"])
chips> set_image(["threshold", [10,20], "invert_colormap", True])

The image is displayed and the interpolation method changed from its default value (nearest-neighbor) to a bilinear scheme. Then the display limits are changed to the range 10 to 20, inclusive, and the colormap is inverted.

Example 5

chips> add_image('img.fits[bin x=3900:4200:2,y=3900:4200:2]')

Add an image to using a DM filter which crops and rebins the original image.

Example 6

chips> add_image("dss.fits")
chips> add_contour("acis.fits", ["thickness", 2])
chips> set_xaxis(["tickformat", "%ra1"])
chips> set_yaxis(["tickformat", "%dec1"])

Here we overlay contours from an ACIS observation onto the image from the Digital Sky Survey. The axes are labelled using sexagesimal notation, where the components are separated by ":" characters.

Example 7

chips> add_image("dss.fits")
chips> add_image("acis.fits", ["alpha", [0.7,0.7]])
chips> set_image(["colormap", "blue", "threshold", [0,10]])

Here we overlay the ACIS image on top of the Digital Sky Survey image; the Chandra data is made slightly opaque so that the DSS data can still be seen. In this example all pixels of the ACIS image have the same opacity of 0.7, but you can also change it to scale linearly between the minimum and maximum values - e.g. by saying

chips> set_image(["alpha", [0, 0.7]])

Note that the alpha setting is ignored - and set to 1 - when creating PS or EPS outputs using print_window().

Example 8

chips> r = "img_red.fits"
chips> g = "img_green.fits"
chips> b = "img_blue.fits"
chips> add_image(r,g,b)

Creates a composite, RGB color image from three separate images.

Example 9

chips> r = "radio.fits"
chips> g = None
chips> b = "chandra.fits"
chips> add_image(r,g,b)

Here the green channel is ignored. Note that the two images must have the same image size and WCS information; use remap from WCSTools, the Montage package, or equivalent to perform the necessary alignment and rebinning before using add_image. The only WCS projection system supported by ChIPS is the tangent-plane system.

Example 10

chips> add_image("img.fits", ["colormap", "hsv"])
chips> add_colorbar(0.5, 1.05)

The image is displayed using the "hsv" colormap (the default colormap is "grayscale"), and a color bar is added above the plot.

Example 11

chips> add_image("img.fits", ["wcs","logical"])

Use the logical coordinate system - namely the pixel numbers - for the axes.

Example 12

chips> j, i = np.mgrid[-10:10:0.5, 20:50:0.5]
chips> r2 = (i-34)**2 + (j-2)**2
chips> r = np.sqrt(r2)
chips> add_image(r, ['invert_colormap', True, 'depth', 50])
chips> add_contour(r, [2, 5, 10, 15])
chips> set_plot_aspect_ratio('fit')

The NumPy mgrid routine is used to create two 2D arrays (i and j) which contain the X and Y coordinates respectively for a grid ranging over x=20 to 50 and y=-10 to 10 with a grid size of 0.5 in both dimensions. Note that the upper bounds (ie x=20 and y=10) are not included in these grids.

The i and j arrays are used to create an image r2, where each pixel is the square of the distance of that pixel from x=34, y=2. The final display is of the square root of this distance, with contours overlaid showing those pixels whose distance is 2, 5, 10, and 15 units from the center.

Although the image is calculated with an X axis of 20 to 49.5 and Y axis of -10 to 9.5, the image is displayed in logical coordinates; so the X axis covers 0 to 60 and Y axis 0 to 40, as

chips> print(r.shape)
(40, 60)

The actual plot range chosen will depend on the window size, the chosen plot area, and whether the aspect ratio is set. Here we use the set_plot_aspect_ratio command to resize the plot so that it fits the data.

Displaying the axis coordinates

The transform library can be used to create the necessary LINEAR2DTransform object, or we can take advantage of the imexent routine from the crates_contrib.images module:

chips> from crates_contrib.images import imextent
chips> tr = imextent(r, 20, 49.5, -10, 9.5)
chips> add_window()
chips> add_image(r, tr, ['invert_colormap', True, 'depth', 50])
chips> add_contour(r, [2, 5, 10, 15], tr)
chips> set_plot_aspect_ratio('fit')

Example 13

chips> img = read_file("images.img")
chips> add_image(img)

Read in an image from a file into a crate and then use it to create the image display. This will include any coordinate transform defined in the input file.

Example 14

chips> crate = read_file("img.fits")
chips> ivals = copy_piximgvals(crate)
chips> ivals = np.log10(ivals)
Warning: divide by zero encountered in log10
chips> add_image(ivals)

Read in an image from a file into a crate and convert the crate into an array. Since the array may be operated on, it is possible to change the scaling of the image, in this case, plotted on a logarithmic scale. However, the image is now plotted in logical, pixel coordinates instead of WCS.

To preserve the image scaling and retain the original WCS information from the image file, the following example continues using the loaded IMAGEcrate and array:

Example 15

chips> crate.get_image().values = ivals
chips> add_window(8, 8, "inches")
chips> add_image(crate)
chips> set_xaxis(["tickformat", "%ra"])
chips> set_yaxis(["tickformat", "%dec"])

the scaled array is copied into the original IMAGECrate, so retaining the WCS coordinatate information of the original image.

Image Preferences and Attributes

The attributes associated with images are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_image() command. To change the image preference settings prepend "image." to the attribute name.

Attribute	Description	Options	Default	Set?
alpha	A two-element array of the minimum and maximum values to use for the alpha channel.	The values are normalized to the data range, so should be in the range 0 to 1, inclusive. A setting of [1,1] is fully opaque whereas [0.5,0.5] makes every pixel 50 per cent transparent, and [0,1] makes the minimum value fully transparent and the maximum value fully opaque.	[-1, -1]	Yes
colormap	the color map used to display the image	red\|green\|blue\|grayscale\| rainbow\|hsv\|heat\|cool\| usercmap1\|usercmap2\|usercmap3; see the colormap section of "ahelp chipsopt"	grayscale	Yes
colormap_interpolate	should the colormap be interpolated over the size of the colormap	see the Booleans section of "ahelp chipsopt"	true	Yes
colormap_size	number of entries to use from the color map		256	Yes
depth	Value indicating the depth of the image	see the Depth section of "ahelp chipsopt"	default	Yes
interpolation	the interpolation method used to display the image pixels	neighbor\|bilinear\|bicubic	neighbor	Yes
invert_colormap	should the colormap be inverted?	see the Booleans section of "ahelp chipsopt"	false	Yes
scale_channels	when displaying true-color images, should each channel (other than alpha) be normalized to its own range (true) or the range of all the channels (false).	see the Booleans section of "ahelp chipsopt"	true	Yes
stem	stem to use for image ids	An alpha-numeric character sequence that does not contain a space	image	No
threshold	A two-element array of the minimum and maximum values to use for thresholding the image.	The values are normalized to the data range, so should be in the range 0 to 1, inclusive. A setting of [0,1] means use the whole pixel range whilst [0.05,0.95] would only use the central 90% of the pixel range.	[-1, -1]	Yes
wcs	The name of the coordinate system to use	"logical", "physical", "world". You can also use the names of the transforms, such as "sky" and "EQPOS".	"world", if available and supported (WCS-TAN).	No

Supported World Coordinate Systems

WCS-TAN support

At present the only supported World Coordinate System for displaying data in ChIPS is the tangent-plane projection; namely WCS-TAN. Using an unsupported system will result in a warning message and the data will be displayed using the physical or - if it does not exist, logical - system.

Bugs

Transparency support and PostScript formats

The Postscript (PS and EPS) output formats do not support the alpha settings of images or the opacity settings of region or histograms. The attribute values are treated as 1 when the object are displayed in these formats.

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.