im_patch (image_patch) extracts a rectangular
[Section 1. Programs, DRMS Modules, Shell Scripts]

im_patch extracts a rectangular image from an input series. The patch is tracked across the solar disk from t_start to t_stop times. The patch may be defined by Carrington or Syonyhurst coordinates or in arcsec or pixels. The extracted patch is rectangular in original image pixels. More...

Collaboration diagram for im_patch (image_patch) extracts a rectangular:

region or patch from an input series. The patch is tracked across the solar disk from time t_start to t_stop. The patch size in pixels is defined by either its Carrington rotation, longitude, latitude and size when it crosses central meridian or by its location in arcsec at a reference time. If defined by Carrington coordinates the bounding box size is specified in degrees of longitude and latitude at disk center. Else the box is specified by its reference image time and location in locunits. No reprojection is done, the patch is a simple cutout of the original image.

Synopsis:

   im_patch in=<recordset> out=<series_out>  \
   log=<logfile> \
   t_start=<start time> \
   t_stop=<end time> \
   cadence=<step time> \
   car_rot=<Carrington Rotation> \
   t_ref=<ref_time> \
   locunits=<location units> \
   x=<ew location> \
   y=<ns location> \
   boxunits= <patch spec units> \
   height=<height> \
   width=<width> \
   requestid=<RequestID> \
   [-t] \

Cadence is the desired time between extracted frames. It will be modified to be a multiple of the dataset's step size. The extracted region location may be specified by position at a reference time or by Carrington coordinates. If by position at a reference time, the position may be specified in ipixels, arcsec, or Stonyhurst coordinates. If the car_rot parameter is required if the Carrington location method is used. If the t_ref parameter is present, location is specified by a method given in <locunits>. The location is given in the "x" and "y" arguments where the units of x and y are determined by locunits. The choices for locunits are: "arcsec", "pixels", "stony", "carrlong". For "stony" (Stonyhurst) x is the CM distance in degrees, for "carrlong" x is Carrington longitude. The y value is in degrees of latitude for either "stony" or "carrlong". Arcsec locations are measured from disk center, pixel locations are measured from the lower left corner of the image, with the first pixel labeled (1,1).

The size of the patch, given in the width and height parameters can be expressed in "pixels", "arcsec", or "degrees" as determined by the "boxunits" parameter.

If the logfile parameter is present, a RecordSet query will be written to logfile for each image created containing a query that will return that image.

RequestID, if present, is the ID of an on-requst processing export request.

If neither a limiting recordset specification nor t_start or t_stop are present, those values will be inferred from the on-disk time span for the center of the patch -90 degrees to +90 degrees from CM. If cadence is not specified explicitly on the command line or in the recordset spec, the full cadence of the dataset will be used. This module computes the beginning and ending time for tracking the region identified at time = t_ref, x and y or by the Carrington coordinates of the box center. In the Carrington case the module extracts a rectangular region with user defined size. the height and width of the box are specified in degrees of latitude and longitude with the pixel size of the box is computed from the projection of the box at CM. The pixel size of the rectangular box remains constant during tracking. The box height defaults to the width. The width defaults to 10 degrees.

If the input recordset spec is exactly "[$]" that spec will be discarded and the time limits will be taken from t_start, t_stop, car_rot, and/or t_ref as appropriate. This is to allow exports via jsoc_fetch to not require a bounding recordset to be specified.

If t_start and/or t_stop are specified the referecne time or disk center location need not be included.

If the input is only a seriesname with [$], it must have a prime key of type time.

If the t_ref parameter is specified, there must be a non-missing image within +- 2 hours of t_ref.

The output seriesname defaults to the input seriesname with a suffix of "_mod".

The -t, 'no tracking' flag casues the extracted region to remain fixed with respect to disc center. I.e. the Carrington tracking is disabled. If locunits are "stony" or "carrlong" the patch center must be on the disk.

The -c, 'crop' flag causes the off-limb data to be replaced with MISSING (NaNs for floating types).

The -h "header keywords" flag causes the metadata keywords to be included in all of the output FITS files.

If -r or -R are specified, the images will be sub-pixel registered to the target location. If -r or -R are given along with -t (no tracking) then -r means register to the first frame and -R means register to Sun center.

-f, -F flags and FDS are special rarely used parameters that allow tracking to a location given in a SDO flight dynamics system generated trajectory of e.g. a transitting moon or planet. The -f or -F flags in this case will generate a fake object with value either 0 or datamax. For example, the Venus transit locations are found in sdo.fds[2012.06.05_00:00:00_UTC][SOLAR_TRANSIT][S][2]

If the input series is AIA lev1 or HMI lev1 where the time slots are not fully populated then special code is used to produce the requested cadence. In these cases the DRMS "time@cadence" recordset notation will fail so use the cadence parameter instead.

Flags:

-A Generate output for all segments. -t Disable tracking. -h Include header keywords -r register to first frame -R register to Sun center -f make black fake tracked object -F make light fake tracked object

GEN_FLAGS:

Ubiquitous flags present in every module. DRMS common main program

Parameters:

	in	The input data series.
	out	The output series.

Exit_Status:

Example:

Extracts a rectangular region of size 20 x 10 degrees and tracks it from when the region is just appearing at the E-limb to t_stop.

   im_patch in='hmi.M_45s' locunits=carrlong boxunits=pixels car_rot=2009 x=295 y=5 width=30 height=20

Example:

Bug:

No doubt some bugs.