reproject_adaptive¶
- reproject.reproject_adaptive(input_data, output_projection, shape_out=None, hdu_in=0, center_jacobian=False, despike_jacobian=False, roundtrip_coords=True, conserve_flux=False, kernel='gaussian', kernel_width=1.3, sample_region_width=4, boundary_mode='strict', boundary_fill_value=0, boundary_ignore_threshold=0.5, x_cyclic=False, y_cyclic=False, bad_value_mode='strict', bad_fill_value=0, output_array=None, output_footprint=None, return_footprint=True, block_size=None, parallel=False, return_type=None)[source]¶
Reproject a 2D array from one WCS to another using the DeForest (2004) adaptive, anti-aliased resampling algorithm, with optional flux conservation. This algorithm smoothly transitions between filtered interpolation and spatial averaging, depending on the scaling applied by the transformation at each output location.
- Parameters:
- input_dataobject
The input data to reproject. This can be:
The name of a FITS file as a
str
or apathlib.Path
objectAn
HDUList
objectAn image HDU object such as a
PrimaryHDU
,ImageHDU
, orCompImageHDU
instanceA tuple where the first element is a
ndarray
and the second element is either aBaseLowLevelWCS
,BaseHighLevelWCS
, or aHeader
objectAn
NDData
object from which the.data
and.wcs
attributes will be used as the input data.
If the data array contains more dimensions than are described by the input header or WCS, the extra dimensions (assumed to be the first dimensions) are taken to represent multiple images with the same coordinate information. The coordinate transformation will be computed once and then each image will be reprojected, offering a speedup over reprojecting each image individually.
- output_projection
BaseLowLevelWCS
orBaseHighLevelWCS
orHeader
The output projection, which can be either a
BaseLowLevelWCS
,BaseHighLevelWCS
, or aHeader
instance.- shape_outtuple, optional
If
output_projection
is a WCS instance, the shape of the output data should be specified separately.- hdu_inint or str, optional
If
input_data
is a FITS file or anHDUList
instance, specifies the HDU to use.- center_jacobianbool
A Jacobian matrix is calculated, representing d(input image coordinate) / d(output image coordinate), a local linearization of the coordinate transformation. When this flag is
True
, the Jacobian is calculated at pixel grid points by calculating the transformation at locations offset by half a pixel. This is more accurate but carries the cost of tripling the number of coordinate transforms done by this routine. This is recommended if your coordinate transform varies significantly and non-smoothly between output pixels. WhenFalse
, the Jacobian is calculated using pixel-grid-point transforms, which produces Jacobian values at locations between pixel grid points, and nearby Jacobian values are averaged to produce values at the pixel grid points. This is more efficient, and the loss of accuracy is extremely small for transformations that vary smoothly between pixels. Defaults toFalse
.- despike_jacobianbool
Whether to despike the computed Jacobian values. In some situations (e.g. an all-sky map, with a wrap point in the longitude), extremely large Jacobian values may be computed which are artifacts of the coordinate system definition, rather than reflecting the actual nature of the coordinate transformation. This may result in a band of
nan
pixels in the output image. In these situations, if the actual transformation is approximately constant in the region of these artifacts, this option should be enabled. If enabled, the typical magnitude (distance from the determinant) of the Jacobian matrix,Jmag2 = sum_j sum_i (J_ij**2)
, is computed for each pixel and compared to the 25th percentile of that value in the local 3x3 neighborhood (i.e. the third-lowest value). If it exceeds that percentile value by more than 10 times, the Jacobian matrix is deemed to be “spiking” and it is replaced by the average of the non-spiking values in the 3x3 neighborhood.- roundtrip_coordsbool
Whether to verify that coordinate transformations are defined in both directions.
- conserve_fluxbool
Whether to rescale output pixel values so flux is conserved.
- kernelstr
The averaging kernel to use. Allowed values are ‘Hann’ and ‘Gaussian’. Case-insensitive. The Gaussian kernel produces better photometric accuracy and stronger anti-aliasing at the cost of some blurring (on the scale of a few pixels). If not specified, the Gaussain kernel is used by default.
- kernel_widthdouble
The width of the kernel in pixels, measuring to +/- 1 sigma for the Gaussian window. Does not apply to the Hann window. Reducing this width may introduce photometric errors or leave input pixels under-sampled, while increasing it may improve the degree of anti-aliasing but will increase blurring of the output image. If this width is changed from the default, a proportional change should be made to the value of sample_region_width to maintain an equivalent degree of photometric accuracy.
- sample_region_widthdouble
The width in pixels of the output-image region which, when transformed to the input plane, defines the region to be sampled for each output pixel. Used only for the Gaussian kernel, which otherwise has infinite extent. This value sets a trade-off between accuracy and computation time, with better accuracy at higher values. The default value of 4, with the default kernel width, should limit the most extreme errors to less than one percent. Higher values will offer even more photometric accuracy.
- boundary_modestr
How to handle when the sampling region includes regions outside the bounds of the input image. The default is
strict
. Allowed values are:strict
— Output pixels will be NaN if any input sample falls outside the input image.constant
— Samples outside the input image are replaced by a constant value, set with theboundary_fill_value
argument. Output values become NaN if there are no valid input samples.grid-constant
— Samples outside the input image are replaced by a constant value, set with theboundary_fill_value
argument. Output values will beboundary_fill_value
if there are no valid input samples.ignore
— Samples outside the input image are simply ignored, contributing neither to the output value nor the sum-of-weights normalization.ignore_threshold
— Acts asignore
, unless the total weight of the ignored samples exceeds a set fraction of the total weight across the entire sampling region, set by theboundary_ignore_threshold
argument. In that case, acts asstrict
.nearest
— Samples outside the input image are replaced by the nearest in-bounds input pixel.
- boundary_fill_valuedouble
The constant value used by the
constant
boundary mode.- boundary_ignore_thresholddouble
The threshold used by the
ignore_threshold
boundary mode. Should be a value between 0 and 1, representing a fraction of the total weight across the sampling region.- x_cyclic, y_cyclicbool
Indicates that the x or y axis of the input image should be treated as cyclic or periodic. Overrides the boundary mode for that axis, so that out-of-bounds samples wrap to the other side of the image.
- bad_value_modestr
How to handle values of
nan
andinf
in the input data. The default isstrct
. Allowed values are:strict
— Values ofnan
orinf
in the input data are propagated to every output value which samples them.ignore
— When a sampled input value isnan
orinf
, that input pixel is ignored (affected neither the accumulated sum of weighted samples nor the accumulated sum of weights).constant
— Input values ofnan
andinf
are replaced with a constant value, set via thebad_fill_value
argument.
- bad_fill_valuedouble
The constant value used by the
constant
bad-value mode.- output_arrayNone or
ndarray
An array in which to store the reprojected data. This can be any numpy array including a memory map, which may be helpful when dealing with extremely large files.
- output_footprint
ndarray
, optional An array in which to store the footprint of reprojected data. This can be any numpy array including a memory map, which may be helpful when dealing with extremely large files.
- return_footprintbool
Whether to return the footprint in addition to the output array.
- block_sizetuple or ‘auto’, optional
The size of blocks in terms of output array pixels that each block will handle reprojecting. Extending out from (0,0) coords positively, block sizes are clamped to output space edges when a block would extend past edge. Specifying
'auto'
means that reprojection will be done in blocks with the block size automatically determined. Ifblock_size
is not specified or set toNone
, the reprojection will not be carried out in blocks.- parallelbool or int, optional
If
True
, the reprojection is carried out in parallel, and if a positive integer, this specifies the number of processes to use. The reprojection will be parallelized over output array blocks specified byblock_size
(if the block size is not set, it will be determined automatically).- return_type{‘numpy’, ‘dask’}, optional
Whether to return numpy or dask arrays - defaults to ‘numpy’.
- Returns: