set_image

Context: images

Synopsis

Modifies the attributes of an existing image.

Syntax

set_image(attributes)
set_image(id, attributes)

Description

The function arguments.

Argument	Description
id	A ChipsId structure identifying the item, or a string containing the name of the object.
attributes	Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The set_image command sets the specified attributes to the provided values. The modified image becomes current. Multiple images may be modified with a single command by setting the currency to "all".

Customizing the Image

There are several attributes that control the characteristics of images. The set_image command may be used to modify the attribute values of an existing image at any time during a ChIPS session. See "ahelp attributes" and "ahelp setget" for more general information.

If multiple attributes are being set simultaneously and one of them fails, the entire command will fail and the image will not be modified.

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

Advanced Functions

The module of advanced ChIPS functions contains other commands for setting attribute values (refer to "ahelp chips" for information on loading the module):

set_image_alpha
set_image_colormap
set_image_colormap_interpolate
set_image_colormap_size
set_image_depth
set_image_interpolation
set_image_invert_colormap
set_image_scale_channels
set_image_threshold

Examples

Example 1

chips> clear()
chips> add_image(np.arange(100), 10, 10)
chips> set_image(["interpolation", "bilinear"])
chips> set_image(["interpolation", "bicubic"])
chips> set_image(["interpolation", "neighbor"])

Here we create a simple image to display (a 10 by 10 array with values 0 to 99). The default interpolation scheme is "neighbor", and we use the set_image() call to change between the three allowed options. For this image there is very-little difference between the linear and cubic systems.

Example 2

chips> set_image(["colormap", "heat"])

Using attribute/value pairs, set the current image to display using the "heat" colormap.

Example 3

chips> set_image(["colormap", "cool", "threshold", [20,75]])

Set the current image to display using the "cool" colormap, where 20 is mapped to the minimum color and 75 the maximum color.

A color bar can be added to help show the pixel value mapping, for example:

chips> add_colorbar(0.5, 1.05)

See "ahelp add_colorbar" for more information.

Example 4

chips> set_image({"colormap": "cool", "threshold": [20,75]})

Repeat the previous example but this time using a dictionary to send in the attribute values.

Example 5

chips> set_image(["invert_colormap", True])

The color mapping is inverted.

Example 6

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

The transparency of the image is changed; the valid range is 0 to 1 with 1 being fully opaque and 0 fully transparent. Note that transparency is only supported on screen and in the bitmap outputs (PNG and JPEG); for the postscript and PDF outputs the alpha value is fixed to 1.

We can add an image behind the current one to better show how the transparency works. We start by creating a grid of x and y values for the coordinates, using the numpy mgrid routine, then display it on top (where it hides the original image) before moving it behind the partially opaque image:

chips> y,x = np.mgrid[1:11,1:11]
chips> i2 = np.sin(x-6) + np.cos(y-8)
chips> add_image(i2, 10, 10, ["colormap", "red"])
chips> set_image(["interpolation", "bicubic"])
chips> set_image(["depth", 50])

If the alpha setting had been "[0.3,0.7]" then the image transparency would be scaled from 0.3 for the lowest displayed values to 0.7 for those pixels set to the largest displayed value (e.g. as set by the "threshold" attribute)"

chips> set_image("image1", ["alpha", [0.3,0.7]])

Example 7

chips> s = ChipsImage()
chips> s.colormap = "red"
chips> s.invert_colormap = True
chips> set_image("image1", s)

Populate the "s" structure with attribute values, then use it to set the image with an id of "image1" to use an inverted, red colormap.

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

Bugs

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