Jump to: Description Examples CHANGES IN CIAO 4.1 Bugs See Also

AHELP for ChIPS 4.1

add_contour

Context: sl.chips

Syntax

add_contour( [ChipsId,] filename [,attributes]);
add_contour( [ChipsId,] IMAGECrate [,attributes]);
add_contour( [ChipsId,] data-array, x-dim, y-dim [,levels] [, trans]
[,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")
data-array - 1D or 2D regular, non-sparse data array containing the points to be contoured.
x-dim - size of the x dimension of data_array
y-dim - size of the y dimension of data_array
levels - the exact contour levels to display
trans - coordinate transform to be applied to the data
attributes - optional parameters which allow the user to configure properties though a structure, list, or attribute string.

The add_contour command creates a contour whose attributes are specified by user preferences or in an attribute list. The new contour becomes current by default; providing a ChipsId overrides the currency state.

The data-array is a one or two-dimensional array of data points to be contoured. The dimensionality of the input array is ignored and the x-dim and y-dim parameters are used to define the sizes of the x and y dimensions. If a transform is set to be applied, the data in data-array is first contoured and then the transform is applied to the contours.

Customizing the Contour

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

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

The attributes associated with contours are:

Attribute	Description	Options	Default
algorithm	the contouring algorithm to be used	standard, marching	marching
color	contour color	name or hex; see the Color section of "ahelp chipsopt"	default
depth	Depth used for the contour object	see the Depth section of "ahelp chipsopt"	Default
interval	Indicates the delta value from one contour level to the next	Integer	10
levels	When setting, this attribute controls the the contour levels to display when the mode is "arbitrary". When using get_contour() this attribute contains the actual contour levels displayed.	Array or list of numbers	[]
mode	How the contour levels are determined	nice, limits, interval, count, arbitrary	nice
numlevels	number of contour levels when mode is count	positive integer	5
stem	Stem used for contour id	Alphanumeric	ctr
style	Stipple pattern used to draw the line segment	see the Line Style section of "ahelp chipsopt"	solid
thickness	Thickness of the line	0.5 to 10.0; see the Thickness section of "ahelp chipsopt"	1
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.

Example 1

chips> add_contour("img.fits");

Create contours from the file "img.fits". Equally-spaced levels are generated that cover the fullpixel range of the 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> reverse_axes(X_AXIS);
chips> set_yaxis({"tickformat","dec"});

The contour levels are chosen automatically in this case, using the contour.mode preference setting, which defaults to "nice". The actual values used can be found in the levels attribute of the return value of get_contour():

chips> get_contour.mode;
nice
chips> get_contour.levels;
[53.5, 58.5, 63.5, 68.5, 73.5]

Example 2

chips> add_contour("img.fits", [60,68,75]);

Create contours from the file "img.fits". Three contours are drawn, at levels of 60, 68, and 75. The contour mode - i.e. the algotithm used to determine the levels at which to display contours - is set to "arbitrary" in this case.

chips> get_contour.mode;
arbitrary
chips> get_contour.levels;
[60.0, 68.0, 75.0]

Changing the mode setting may change the contours used; below we switch to "nice" and then "interval" modes (in the latter case setting the spacing between levels to 15):

chips> set_contour({"mode", "nice"});
chips> get_contour.levels;
[55.0, 60.0, 65.0, 70.0, 75.0, 80.0]

chips> set_contour({"mode", "interval", "interval", 15});
chips> get_contour.levels;
[60.0, 75.0]

We now change the contouring to use the "count" mode and to use 4 levels; however the requested number of levels is not always possible to create, as in this case which ends up adding three contours.

chips> set_contour({"mode", "count", "numlevels", 4});
chips> get_contour.numlevels;
4
chips> get_contour.levels;
[60.0, 70.0, 80.0]

Finally we go back to the arbitrary mode and end up with the original selection of contour levels:

chips> set_contour({"mode", "arbitrary"});
chips> get_contour.levels;
[60.0, 68.0, 75.0]

For this particular dataset the data range is roughly 50 to 80; the actual range can be found by using get_contour_zrange():

chips> get_contour_zrange;
[51.353700000000003, 80.367400000000004]

Example 3

chips> add_contour("img.fits", {"color", "blue"});
chips> add_contour("img.fits", [0], {"color","green","thickness",2});

Two contours of the same image are created. The first set are drawn in blue, whilst the second one - which is overlain on the first - shows only the zero-level contour using a green contour, with a thickness of 2.

Example 4

chips> add_contour("img.fits", [10,20,30],{ {"wcs","logical"});

Create contours from the file "img.fits" using the specified contour levels. Use the logical coordinate system - namely the pixel numbers - for the axes.

Example 5

chips> img = read_file ("contours.img");
chips> add_contour (img);

Create contours from the file "contours.img" via CRATES.

Example 6

chips> add_contour([1,1,1, 1,3,1, 1,1,1], 3,3);

The 3 by 3 array is contoured with equally-spaced levels.

Example 7

chips> add_contour([1,1,1, 1,3,1, 1,1,1],
3,3,{"color","lime","style","solid"});

Add a contour with line color and style attributes specified.

Example 8

chips> ci = ChipsContour;
chips> ci.color = "lime";
chips> ci.style = "solid";
chips> add_contour([1,1,1, 1,3,1, 1,1,1], 3,3, ci);

Add a contour with line color and style attributes specified via settings in the ChipsContour object.

Example 9

chips> add_contour([1,1,1, 1,3,1, 1,1,1], 3,3, [1.1,1.5,2,2.5]);
chips> set_contour({"color", "lime", "style", "solid"});

Add a contour using user-specified levels, line color, and style attributes.

Example 10

chips> img = [1:12];
chips> add_contour(img, 4, 3, {"color","red"});
chips> get_contour_xrange;
[1.0, 4.0]
chips> get_contour_yrange;
[1.0, 3.0]
chips> add_contour(img, 3, 4, {"color","blue"});
chips> get_contour_xrange;
[1.0, 3.0]
chips> get_contour_yrange;
[1.0, 4.0]
chips> set_axis({"pad",0});
chips> get_plot_xrange;
[1.0, 4.0]
chips> get_plot_yrange;
[1.0, 4.0]

The img variable is a one-dimensional array containing the numbers 1 to 12. The first add_contour call treats this as two-dimensional image with 4 pixels in the X direction and 3 in the Y. The second add_contour call swaps the dimensionality, so that the array is treated as having 3 pixels in the X direction and 4 in the Y direction.

CHANGES IN CIAO 4.1

The default algorithm is now marching

The default contouring algorithm has been changed to be marching squares since it is a faster algorithm than the standard.

Changes to the levels and numlevels attributes

The attribute "levels" which refers to the requested number of levels for a given contour in count mode has been changed to "numlevels." When setting the attribute, "levels" now refers to a list of exact levels the user wants the contour to display (when the mode is set to "arbitrary"). When using get_contour(), the "levels" attribute contains the numeric values of the contour levels.

Bugs

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