MAKESET

Writes Set header information to images

Description:

This routine is used to group images into a Set so that they can be processed together. It is usually used when you have CCD data from a single exposure in multiple files because they were generated from multiple CCDs in a mosaic camera, or from multiple amplifiers in the same CCD, or both. When this program is run on a group of files, header information is written to each one so that other CCDPACK routines will know about the relationship between them.

MAKESET writes the following items of data to the .MORE.CCDPACK.SET extension of each image:

and it will also optionally (if ADDWCS is set true) write:

Normally by just presenting a list of image names to the program the values of these attributes will be taken care of automatically, but various options exist to tune how it is done.

Usage:

makeset in mode

Parameters:

ADDWCS = _LOGICAL (Read)
If ADDWCS is true, then MAKESET will attach a new coordinate system to the WCS component of the image. The new coordinate frame will be a copy of the Current coordinate frame of the image, and will have the Domain name of ’CCD_SET’; CCDPACK tasks concerned with registration know about this name and will use those coordinates on the assumption that they constitute a correct registration of images if they are present. Therefore this parameter should be set true if the images which will form a Set are known to be aligned in their common Current coordinate system.

If MODE=SPLIT, this parameter is ignored and a new CCD_SET coordinate system which is a copy of the Pixel coordinate system will be added in any case. [TRUE]

ASTFILE = LITERAL (Read)
If this parameter is supplied, it gives the name of a file containing Set coordinate information. A new coordinate frame will accordingly be written into the WCS component of each image, with the Domain name ’CCD_SET’; CCDPACK tasks concerned with registration know about this name and will use those coordinates on the assumption that they constitute a correct registration of images if they are present. The newly added coordinate system will become the Current coordinate system of the image.

The file named by this parameter will normally have been written by the ASTEXP program, saving a known correct alignment of images within a Set that corresponds to the one being created by this program. This parameter is ignored if MODE=SPLIT. [!]

FITSINDEX = LITERAL (Read)
The name of the FITS header card whose value will determine the Set Index attribute of each file. The Set Index header value itself is determined from the value of the chosen FITS header card and the value of the INDEXVALS parameter. Only used if MODE=FITS.
FITSNAME = LITERAL (Read)
The name of the FITS header card whose value will determine the Set Name attribute of each file. The Set Name header value is taken directly from the chosen FITS header card. Only used if MODE=FITS.
IN = LITERAL (Read)
A group expression giving a list of images to group into one or more Sets. The order in which they are listed will normally determine their INDEX values (but see the INDICES parameter), so that the Sets should be generated by presenting images in a consistent order; the one from CCD1 first, the one from CCD2 second...
INDEXVALS( ∗ ) = LITERAL (Read)
A list of strings to map the value of the FITS header card indicated by the FITSINDEX parameter to the Set Index value; if the header value matches the Nth element of this list the file will be given a Set Index value of N. This parameter will dynamically default to a sorted list of all the values of the chosen parameter which exist in all the input files presented. This will usually be a suitable value if at least one complete Set is being considered. Note that each value must in general be surrounded by double quotes. Only used if MODE=FITS.
INDICES( ∗ ) = _INTEGER (Read)
This parameter is a list of positive integers with SETSIZE elements (SETSIZE will normally be the same as the number of images accessed by the IN parameter). It indicates, for each image in the list, what value the Set INDEX attribute should take. If set to the null value (!) then INDEX attributes will be assigned in order (1, 2, 3, ...) for the members of each Set. Only used if MODE=LIST. [!]
LOGFILE = FILENAME (Read)
Name of the CCDPACK logfile. If a null (!) value is given for this parameter then no logfile will be written, regardless of the value of the LOGTO parameter.

If the logging system has been initialised using CCDSETUP then the value specified there will be used. Otherwise, the default is "CCDPACK.LOG". [CCDPACK.LOG]

LOGTO = LITERAL (Read)
Every CCDPACK application has the ability to log its output for future reference as well as for display on the terminal. This parameter controls this process, and may be set to any unique abbreviation of the following:

  • TERMINAL – Send output to the terminal only

  • LOGFILE – Send output to the logfile only (see the LOGFILE parameter)

  • BOTH – Send output to both the terminal and the logfile

  • NEITHER – Produce no output at all

If the logging system has been initialised using CCDSETUP then the value specified there will be used. Otherwise, the default is "BOTH". [BOTH]

MODE = LITERAL (Read)
Determines exactly how Set header information should be written to the IN files. It may take one of the following values:

  • LIST

  • CONTAINER

  • FITS

  • SPLIT

When MODE=LIST, new Sets will be formed according to the order in which images are named in the IN list. In the most straightforward case, all the named files will become part of the same new Set, with a Set Name derived from the name of the first file in the list and consecutive Set Index values 1, 2, 3, …The SETSIZE and INDICES parameters can be used to create multiple sets in one invocation and to modify the ordering.

When MODE=CONTAINER, one new Set will be formed for each HDS container file; thus each image will be grouped with the other images in the same container file, being given a Set Name based on the name of the container file and a Set Index based on its position within it. HDS container files suitable for feeding to MAKESET with MODE=CONTAINER are often the result of converting multi-extension FITS files to NDF format.

When MODE=FITS the Set attributes of each image are determined by the value of FITS header cards with keywords given by the FITSINDEX and FITSNAME parameters. The Set Name attribute is given directly by the value of the FITSNAME- chosen header. The Set Index attribute is given by the position of the value of the FITSINDEX-chosen header in the list determined by the INDEXVALS parameter. Note this can only be used if both a Name-like and an Index-like header card is available in the FITS header of each file.

When MODE=SPLIT, a new Set is created for each of the members of the IN list. Each Set will consist of the data from the input image split up into pieces according to the XSTART and YSTART parameters, or the SECTIONS parameter. A new HDS container file will be written for each IN file, with a name given by the OUT parameter. Each split piece of the input file will be written as a separate NDF structure in the container file, with a Set Name given by the name of the original image and a Set Index given by the position in the list of pieces. Unlike the other modes, this does not alter the input file, but creates a new output file to contain the rearranged data. [LIST]

NAME = LITERAL (Read)
The NAME parameter is used to determine the Set NAME attribute which the grouped images will have; all images in the same Set have the same NAME. The value of this parameter should be a group expression containing the same number of elements as the number of Sets being created; if it contains modification elements such as "∗" they are applied to the name of the first image in each Set.

The default value is "∗", which means the Set NAME is the same as the name of the image first entered into each Set (if MODE=LIST) or the name of the HDS container file (if MODE=CONTAINER). If MODE=FITS it is ignored. There is normally no need to use a value other than the default. [∗]

OUT = LITERAL (Read)
If MODE=SPLIT, this parameter gives the names to use for the output HDS container files; one output filename must be specified for each input image. These may be given as a comma-separated list of names, using indirection if required, or as a single modification element (of the input names). A common modification element is ’∗’, meaning the same name as the input file, so out="∗-set" would create output files with the same name as the input files but with "-set" appended.

If MODE is not SPLIT then no new output files are created, so this parameter is ignored.

SECTIONS( ∗ ) = LITERAL (Read)
If MODE=SPLIT, this parameter may be used to give a list of NDF section specifiers from which to form the members of the newly created Set. Each element may optionally be enclosed in parentheses, and should be of the form explained in the "NDF Sections" section of SUN/33; typically it will be of the form "(xmin:xmax,ymin:ymax)". Note that if supplying this parameter on the command line it will be necessary to include each element in quotes and the whole list in square brackets, e.g.: sections=["(17:500,1:1024)","(525:1000,1:1024)"]

When using a Unix shell the whole thing will have to be placed in single quotes as well.

If a null value (!) is given for this parameter the XSTART and YSTART parameters are used instead; if the sections into which the input images are to be split tile the whole of the input image, this is usually more convenient. This parameter is ignored unless MODE=SPLIT. [!]

SETSIZE = _INTEGER (Read)
The number of images in each Set. This will default initially to the number of images in the IN list, but if set to a number less than that, then more than one set will be generated (the first SETSIZE from IN will become the first set, and so on). If INDICES is specified it must have SETSIZE elements, and Set INDEX assignment will wrap round when SETSIZE elements have been processed. SETSIZE must be positive, and must be a divisor of the number of images in the IN list, so that each distinct Set created by one invocation of MAKESET is forced to be the same size. Only used if MODE=LIST. [dynamic]
XSTART( ∗ ) = _INTEGER (Read)
If MODE=SPLIT and SECTIONS is null, this gives a list of the first pixel index in the X direction (first coordinate) of rectangular regions which will become members of a new Set. If there are NX elements given for XSTART and NY for YSTART then each created Set will contain NX∗NY members. The region at position (IX,IY) will be composed of pixels XSTART(IX)..XSTART(IX+1)-1 in the X direction and YSTART(IY)..YSTART(IY+1)-1 in the Y direction, where the last pixel in the input image is implied for the upper bound of the NX’th element of XSTART. The XSTART and YSTART parameters are given for convenience; the same information can be given by specifying an appropriate value for the more flexible SECTIONS parameter.
YSTART( ∗ ) = _INTEGER (Read)
If MODE=SPLIT and SECTIONS is null, this gives a list of the first pixel index in the Y direction (second coordinate) of rectangular sections which will become members of a new Set. If there are NX elements given for XSTART and NY for YSTART then each created Set will contain NX∗NY members. The region at position (IX,IY) will be composed of pixels XSTART(IX)..XSTART(IX+1)-1 in the X direction and YSTART(IY)..YSTART(IY+1)-1 in the Y direction, where the last pixel in the input image is implied for the upper bound of the NY’th element of YSTART. The XSTART and YSTART parameters are given for convenience; the same information can be given by specifying an appropriate value for the more flexible SECTIONS parameter.

Examples:

makeset "data1,data2,data3,data4" addwcs mode=list
This will write Set information into the named images; they will all be given the same Set Name attribute ("data1") and will be given the Set Index attributes 1, 2, 3 and 4 respectively. Additionally, a new attached coordinate system with the Domain "CCD_SET" will be added to the World Coordinate System (WCS) component of each; this will be a copy of each one’s Current attached coordinate system. If not all of them have the same Current coordinate system when the program is run (i.e. they do not all have the same Domain), then a warning will be issued.
makeset ∗ mode=container
In this case, all the images in the current directory are assigned Set header information based on how they are contained within HDS container files.
makeset ∗ mode=list setsize=4
This will add Set information to all the images in the current directory, grouping them into Sets of 4 images each. If MAKESET is to be used in this way however it must be done with care, since it will group the files in the order in which they are presented. This depends on what order the "∗" character is expanded in, which depends on the details of the shell that you are using. Typically shells expand alphabetically, so that if the directory contains files with the names d08.sdf, d09.sdf, d10.sdf, d11.sdf they will be presented in that order, but files with the names d8.sdf, d9.sdf, d10.sdf, d11.sdf would be presented in the order d10.sdf, d11.sdf, d8.sdf, d9.sdf. Unless you are confident of how your shell behaves in this respect, then when using wildcards you should pay careful attention to the log output of MAKESET to check that the order is correct. It is safest to list Set members explicitly as in the previous example.
makeset "d1,d2,d3,e1,e2,e3" name=night1-∗ setsize=3 addwcs=no
This will construct two Sets, which will be given Set Name attributes of "night1-d1" and "night1-e1" respectively. You might want to do this if you are going to use these files along with other Sets generated from files with the names the same as these. No additions are made to the WCS componnent of the images.
makeset "d1,d3" indices=[1,3]
This will construct a Set of the two named images, giving them the Set Index attributes of 1 and 3 respectively. This might be necessary for comparison with 3-member sets if the Index=2 one is absent in this case due to a loss of the data file for some reason.
makeset multi split out=multi-s
sections=["(1:32,1:48)","(1:32,49:96)", "(33:64,1:48)","(33:64,49:96)"] A new HDS container file called multi-s is created which contains the data from the single image multi, split up into four new images. A new coordinate system with the domain CCD_SET will be added which is a copy of the Pixel coordinates, and the Pixel coordinate of each of the new images will be the same as it was in the original.
makeset multi split out=multi-s
sections=["(:32,:48)","(:32,49:)","(33:,:48)","(33:,49:)"] If the input image ‘multi’ has X pixels in the range 1:64 and Y pixels in the range 1:96, this does exactly the same as the previous example, cutting multi into quarters. The abbreviated NDF section specifier syntax allows omission of a pixel bound when it is at the edge of the image.
makeset in=∗ mode=split out=∗-s sections=!
xstart="1,33" ystart="1,49" This does the same as the previous example again, using the somewhat simpler XSTART and YSTART parameters. This time a new Set is created for each of the images in the current directory, and written into a container file with the same name but ’-s’ appended.

See also

“Adding Set headers”, SHOWSET.

Notes:

Behaviour of Parameters

All parameters retain their current value as default. The "current" value is the value assigned on the last run of the application. If the application has not been run then the "intrinsic" defaults, as shown in the parameter help, apply.

Retaining parameter values has the advantage of allowing you to define the default behaviour of the application. The intrinsic default behaviour of the application may be restored by using the RESET keyword on the command line.

Certain parameters (LOGTO and LOGFILE) have global values. These global values will always take precedence, except when an assignment is made on the command line. Global values may be set and reset using the CCDSETUP and CCDCLEAR commands.

Copyright

Copyright (C) 2001 Central Laboratory of the Research Councils