Jump to: Description · Examples · Image Preferences and Attributes · Changes in CIAO 4.5 · Bugs · See Also

AHELP for CIAO 4.5 ChIPS v1

add_image

Context: images

Syntax

add_image([ChipsId,] file name [,attributes])
add_image([ChipsId,] IMAGECrate [,attributes])

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

add_image([ChipsId,] [red_image] [,green_image] [,blue_image]
[,alpha_image], [,attributes])

Description

ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
IMAGECrate/filename - input data, specified as a filename or an IMAGECrate ("ahelp crates")
red_image - image to provide the red channel of a true color image (e.g. soft x-ray band image).
green_image - image to provide the green channel of a true color image (e.g. medium x-ray band image).
blue_image - image to provide the blue channel of a true color image (e.g. hard x-ray band image).
alpha_image - image for the alpha channel of a true color image which provides the opacity of the various channels across the true color image.
nx - size of the x dimension of data_array; this is only needed if data-array is not a one- or two-dimensional numpy array.
ny - size of the y dimension of data_array; this is only needed if data-array is not a one- or two-dimensional numpy array.
transform - a pytransform object determining the mapping between logical coordinates, where (1,1) refers to the center of the bottom-left pixel, and the coordinate system to be displayed (see "ahelp transform" for more information).
attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

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).

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 section "Image Preferences and Attributes" below the examples for a list of the image preferences.

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> 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 4

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 5

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 6

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 7

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, produced from three separate bands.

Example 8

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 9

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

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

Example 10

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 (see ahelp aspectratio) 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 11

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 12

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 13

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

Changes in CIAO 4.5

Support for 1D NumPy arrays

One NumPy dimensional arrays can now be displayed without having to give nx and ny values (the Y dimension is assumed to have a length of 1).

chips> clear()
chips> add_image(np.arange(12))

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.