STScI Logo

qplintran xray.ximages


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · TIME_REQUIREMENTS
BUGS · SEE_ALSO

NAME

qplintran -- apply linear transformation to a qpoe file through filters

USAGE

qplintran input_qpoe region angle eventdef qpoe

DESCRIPTION

qplintran transforms a qpoe file according to the specified parameters. Position X1,Y1 is changed to:


	X2 = Xout + (X1-Xin)*Xmag*cos(Angle) - (Y1-Yin)*Ymag*sin(Angle)
	Y2 = Yout + (Y1-Yin)*Ymag*cos(Angle) + (X1-Xin)*Xmag*sin(Angle)

where Xout,Yout is the new reference point in pixels, Xin,Yin is the input reference point, and Xmag,YMag are the relative plate scales in X and Y (normally 1).

Any type of filtering can be applied to the input qpoe file, including region filtering. In addition, the size of the output event record can be different from the size of the input event record. (Of course, usually one makes the output record equal to or smaller than the input. If the output record size is made greater than the input record, a warning is issued and the "extra" part of the record is undefined.)

PARAMETERS

input_qpoe = "" prompt = input qpoe file name

The input qpoe file name. The extension ".qp" will be added to the file if there is no extension. Qpoe filters can be applied using the bracket notation to filter the input photons.

region = "" prompt = region descriptor

The region descriptor. If null is input, the entire field is copied (subject to the qpoe filters specified with the input file name). Otherwise only those photons are copied which pass the spatial region filter.

qpoe = "" prompt = output qpoe file name

The output qpoe file name. The extension ".qp" will be added to the file if there is no extension. The output file can be the same as the input file.

eventdef = "" prompt = event definition

The event definition of the output QPOE file. If the user enters the empty string, "", the event definition will be copied from the input QPOE file. See help qpoe for information on modifying the event definition.

xrotation = 0. prompt = angle (degrees) through which to rotate

The rotation angle to apply to the data, where positive angles signify counter-clockwise rotation.

(exposure = "NONE") [string]

The PLIO mask containing exposure information for the specified source image. If the null string is input, the name will be the same root as the source image file with a "_exp.pl" extension. If "NONE" is input, no exposure filtering is performed.

(expthresh = 0.) [real]

The percentage of total exposure required for a given source pixel to pass the exposure filter, (if an exposure mask is present). For example, if expthresh is 50.0, then only pixels whose exposure time is >= 50% will be used. An exposure threshold of 0% allows all photons to pass the exposure filter.

(xin = INDEF) [real]

The reference pixel of the original qpoe file. If set to INDEF, the reference pixel from the MWCS header (CRPIX1) will be used. If set to a value different from CRPIX1, this will cause an effective shift in x BEFORE the rotation is applied.

(yin = INDEF) [real]

The reference pixel of the original qpoe file. If set to INDEF, the reference pixel from the MWCS header (CRPIX2) will be used. If set to a value different from CRPIX2, this will cause an effective shift in x AFTER the rotation is applied.

(xout = INDEF) [real]

The reference pixel of the rotated file. If set to INDEF, the reference pixel from the MWCS header (CRPIX1) will be used. If set to a value different from CRPIX1, this will cause an effective shift in y BEFORE the rotation is applied.

(yout = INDEF) [real]

The reference pixel of the rotated file. If set to INDEF, the reference pixel from the MWCS header (CRPIX2) will be used. If set to a value different from CRPIX2, this will cause an effective shift in y AFTER the rotation is applied.

(xmag, ymag = 1.0) [real]

The number of output pixels per input pixel in x and y. The magnifications must always be positive numbers. Numbers less than 1 magnify the image; numbers greater than one reduce the image.

(xdim = INDEF) [integer]

Dimension of output image's x-dimension. If set to INDEF, the dimension of the input image will be used. If the dimension is less than zero, this task will attempt to calculate an appropriate dimension to keep as many photons within the image as possible.

(ydim = INDEF) [integer]

Dimension of output image's y-dimension. If set to INDEF, the dimension of the input image will be used. If the dimension is less than zero, this task will attempt to calculate an appropriate dimension to keep as many photons within the image as possible.

(mwcs = yes) [bool]

Normally, the transformation done to the image, must be reflected in the reference coordinate grid. However, if the transformation is to correct an ERROR in the original grid, then this option should be turned off.

(random = yes) [bool]

Apply a random number fraction to transformation before truncation. Smooths out digitization affects. Turning to no is helpful for debugging.

(clobber = no) [boolean]

Boolean flag specifying whether or not the qpoe file can be overwritten, if it already exists.

(display = 1) [int]

The display level. A display level of 0 generates no display. A display level of 1 generates a display of header information.

(sort = yes) [boolean]

Flag if events are to be sorted. If true, the type of sort is determined by the sorttype parameter.

(sorttype = "position") [string]

The type of sort to perform. This string consists of a list of event element names that specifies the order in which to sort the event record. For example, "y x time" will sort on the "y" element as the primary key, the "x" element as the secondary key, and "time" as the tertiary key. If sorting is not to be performed, this parameter can be used as a string that will go into the x_sort qpoe param to indicate the type of sorting of the events. For example, if the events are already sorted by time, and are not to be resorted, one can set sort to false and sorttype to "time", and the qpoe file will be indistinguishable from one whose events were sorted by time.

(sortsize = 1000000) [int]

The number of bytes that are to be sorted at a time. This allows users to tailor the task to the amount of available memory. If there is a lot of memory available, sortsize should be set large enough so that the task will do an in-core sort. (This requires knowing the approximate number of events and the byte size of each event.) If only a small amount of memory is available, use a smaller number. In this case, several core loads will be sorted and written to temp files, which are then merged.

(qp_internals = yes) [boolean]

Boolean flag controlling whether the internal qpoe parameters (see below) are prompted for, or whether they are defaulted to internally hardwired values. This parameter is not usually changed by the user. (Prompting is normally turned off during stand-alone debugging only.)

(qp_pagesize = 1024) [int]

Page size for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_bucketlen = 2048) [int]

Bucket length for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_blockfact = 1) [int]

The default block factor for IMIO. This parameter is internal to qpoe and should not normally be changed.

(qp_mkindex = yes) [boolean]

Boolean flag that an index should be made for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_key = "") [string]

Key on which to make the qpoe index. This parameter is internal to qpoe and should not normally be changed.

(qp_debug = 0) [int]

Debug level for qpoe internals. This parameter is internal to qpoe and should not normally be changed.

EXAMPLES

1. Shift the x-axis by 3.2 pixels and the y-axis by -1.65 pixels. Make the resulting qpoe file of size small. Note that

 		7681.0 + 3.2 = 7684.2
		7681.0 - 1.65 = 7679.35


	cl> imhead xdata$rp110590.qp long+ | match CRPIX
	    CRPIX1  =                7681.
	    CRPIX2  =                7681.


	cl> qplintran xdata$rp110590.qp "" "rp_shift.qp" "small" 0.0 
	 display=1 xout=7684.2 yout=7679.35

	xdata$rp110590.qp (; no exp.) -> rp_shift.qp (xin=7681.00 
	 yin=7681.00 xrot=0.00 yrot=0.00 xout=7684.20 yout=7679.35)
	QPEX Warning: bad attribute name `time'
	Creating QPOE output file: rp_shift.qp

2. Rotate the field 27.2 degrees conter-clockwise. Make the resulting qpoe file of size medium. (The 'invalid event's come from photons in the corners of the input image which were rotated out of the field.)

	cl> qplintran xdata$rp110590.qp "" "rp_rot.qp" "medium" 27.2 
	 display=1

	** WARNING ** invalid event: 7851 -824 - discarded
	** WARNING ** invalid event: 7986 -747 - discarded
	** WARNING ** invalid event: 8374 -536 - discarded
	   .
	   .
	   .
	** WARNING ** invalid event: 6102 15400 - discarded
	** WARNING ** invalid event: 6083 15413 - discarded
	** WARNING ** invalid event: 6097 15459 - discarded

	xdata$rp110590.qp (; no exp.) -> rp_rot.qp (xin=7681.00 yin=7681.00
	 xrot=27.20 yrot=27.20 xout=7681.00 yout=7681.00)
	Creating QPOE output file: rp_rot.qp

TIME REQUIREMENTS

BUGS

For large QPOE files (> 25MBytes) it will be necessary to optimize the QPOE internal parameters.

SEE ALSO

The task GEOMAP can be used to determine correction factors to align to distorted images.

Documentation on region filtering (help regions ) for a description of the spatial filter user interface.

Documentation on qpoe filtering (help qpoe ) for a description of the qpoe filter user interface.

Documentation on file extensions (help extensions ) for a description of PROS file extensions.

Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Search Form · STSDAS