---
name: "mSubimage"
section: "1"
platform: "linux"
package: "montage"
version: "6.1+dfsg-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mSubimage"
---

# mSubimage(1)

Create a "cutout" of a FITS image

## NAME

mSubimage - Create a "cutout" of a FITS image

## SYNOPSIS

mSubimage \[-d\] \[-a\] \[-h *hdu*\] \[-s *statusfile*\] in.fits out.fits ra dec xsize \[ysize\]

mSubimage -p \[-d\] \[-h *hdu*\] \[-s *statusfile*\] in.fits out.fits xstartpix ystartpix xpixsize \[ypixsize\]

## DESCRIPTION

Creates a subimage (or "cutout") of a FITS file.  Note that in "normal" mode, all the parameters (location and size) are in degrees; in pixel (-p) mode, all of them are in pixels

## OPTIONS

- \-d

  Turns on debugging.

- \-a

  All pixels - Force retrieval of whole image (useful to extract an entire HDU)

- \-h *hdu*

  Operate on the specified FITS header extension (HDU)

- \-s *statusfile*

  Output and errors are sent to *statusfile* instead of to stdout

- \-p

  Pixel mode - create subimage using pixel locations, instead of a location on the sky

## ARGUMENTS

- in.fits

  Input FITS file.

- out.fits

  Path to output FITS file.

- ra

  In normal mode, RA of center of output image.

- dec

  In normal mode, declination of center of output image.

- xstartpix

  In pixel mode, pixel along the x-axis where the cutout image will begin

- ystartpix

  In pixel mode, pixel along the y-axis where the cutout image will begin

- xsize

  In normal mode, width of output image in degrees.

- ysize

  In normal mode, height of output image in degrees (default is equal to *xsize*.

- xpixsize

  In pixel mode, width of output image in pixels

- ypixsize

  In pixel mode, height of output image in pixels (default is equal to *xpixsize*

## RESULT

**\[struct stat="OK", content="***blank, flat or normal***"\]**

*The content keyword indicates whether all pixels where NaN (blank), all pixels were the same value (flat), or the image appears to be normal.*

## MESSAGES

- *OK*

  *\[struct stat="OK", content="blank, flat or normal"\]*

- *ERROR*

  *HDU value (hdu) must be a non-negative integer*

- *ERROR*

  *Cannot open status file: statusfile*

- *ERROR*

  *Center RA string (string) cannot be interpreted as a real number*

- *ERROR*

  *Center Dec string (string) cannot be interpreted as a real number*

- *ERROR*

  *X size string (string) cannot be interpreted as a real number*

- *ERROR*

  *Y size string (string) cannot be interpreted as a real number*

- *ERROR*

  *Invalid 'x' size*

- *ERROR*

  *Invalid 'y' size*

- *ERROR*

  *Image file filename missing or invalid FITS*

- *ERROR*

  *Cannot find HDU hdu*

- *ERROR*

  *Output wcsinit() failed.*

- *ERROR*

  *Location is off image*

- *ERROR*

  *Region outside image*

- *ERROR*

  *No pixels match area.*

- *ERROR*

  *Can't create output file: out.fits*

- *ERROR*

  *FITS library error*

## EXAMPLES

- *$ mSubimage image1.fits subimage.fits 307.9 37.29 .01 .01*

  *\[struct stat="OK", content="normal"\]*

## BUGS

*The drizzle algorithm has been implemented but has not been tested* *in this release.*

*If a header template contains carriage returns (i.e., created/modified* *on a Windows machine), the cfitsio library will be unable to read it* *properly, resulting in the error: \[struct stat="ERROR", status=207,* *msg="illegal character in keyword"\]*

*It is best for the background correction algorithms if the area* *described in the header template completely encloses all of the input* *images in their entirety. If parts of input images are "chopped off"* *by the header template, the background correction will be affected. We* *recommend you use an expanded header for the reprojection and* *background modeling steps, returning to the originally desired header* *size for the final coaddition. The default background matching assumes* *that there are no non-linear background variations in the individual* *images (and therefore in the overlap differences). If there is any* *uncertainty in this regard, it is safer to turn on the "level only"* *background matching (the "-l" flag in mBgModel.*

## COPYRIGHT

*2001-2015 California Institute of Technology, Pasadena, California*

*If your research uses Montage, please include the following* *acknowledgement: "This research made use of Montage. It is funded by* *the National Science Foundation under Grant Number ACI-1440620, and* *was previously funded by the National Aeronautics and Space* *Administration's Earth Science Technology Office, Computation* *Technologies Project, under Cooperative Agreement Number NCC5-626* *between NASA and the California Institute of Technology."*

*The Montage distribution includes an adaptation of the MOPEX algorithm* *developed at the Spitzer Science Center.*