Image Cutouts¶
The image cutout interfaces in astroquery.mast provide a convenient way to retrieve
small, spatially localized subsets of large imaging datasets hosted at MAST. Instead of
downloading full-frame images, users can request cutouts centered on a sky position or target
of interest, reducing data volume and simplifying exploratory analysis.
Cutout services support several major MAST imaging products, including TESS full-frame images, Hubble Advanced Products (HAP), and selected deep-field surveys. These interfaces are designed for common science workflows such as quick-look visualization, time-series extraction, and focused analysis around known sources.
The sections below describe the available cutout classes and typical usage patterns, with examples demonstrating how to request cutout products.
TESSCut¶
TESSCut is a MAST service that provides image cutouts from the full-frame images (FFIs) taken by the Transiting Exoplanet Survey Satellite (TESS). This service enables users to extract small, localized regions of TESS data around targets of interest without downloading entire FFI files, which are quite large. TESSCut is particularly useful for time-series analysis, quick-look visualization, and focused studies of specific objects.
The TesscutClass provides programmatic access to the
MAST TESScut API,
enabling TESSCut queries directly from Python scripts and applications. It has three main capabilities:
Sector Discovery: Identify which TESS sectors, cameras, and CCDs cover a given sky position or object.
In-memory Cutouts: Retrieve cutouts as
HDUListobjects for immediate analysis without writing files to disk.Downloaded Cutouts: Download cutout target pixel files (TPFs) to local storage.
TESSCut supports cutout requests centered on fixed sky coordinates, resolved object names (including TIC IDs), and moving targets such as asteroids and comets. Requests may return multiple cutouts when a target appears in more than one sector or overlaps multiple cameras or CCDs. For fixed targets, cutouts may be requested by sky coordinates or object name. For moving targets, ephemerides from the JPL Horizons system are used to determine target positions on a per-sector basis. All cutouts are generated from Science Processing Operations Center (SPOC) FFI products and are returned in the standard TESS target pixel file format.
As of August 2025, the option to generate cutouts from TESS Image Calibration (TICA) full frame images has been discontinued. Individual TICA FFIs remain available from the MAST TICA homepage. Cutouts generated from SPOC FFIs continue to be supported through TESSCut.
Note: TESSCut limits each user to a maximum of 10 simultaneous requests. If this limit
is exceeded, the service will respond with a 503 Service Temporarily Unavailable Error.
If you use TESSCut for your work, please cite Brasseur et al. 2019.
Sector Discovery¶
Before requesting cutouts, it is often useful to determine which TESS sectors contain data for a given target. TESS observes the sky in discrete observing campaigns called sectors, and cutouts can only be generated for sectors in which the target falls on an active camera and CCD.
The get_sectors method identifies the TESS sectors whose
footprints intersect a given target or region of the sky. Targets may be specified using sky
coordinates, a resolved object name (including TIC IDs), or a moving target name.
The result is returned as an Table containing the sector number along with
the corresponding camera and CCD information. This table can be used to:
Verify whether a target was observed by TESS
Identify all available sectors before requesting cutouts
Select a specific sector, camera, or CCD for downstream analysis
If no sectors overlap the requested location, a warning is issued and an empty result is returned.
For moving targets, sector discovery accounts for the target’s motion across the sky. When a sector is not explicitly specified in later cutout requests, this information is used internally to generate cutouts for each applicable sector.
The following example demonstrates how to use the get_sectors method with sky coordinates.
>>> from astroquery.mast import Tesscut
>>> from astropy.coordinates import SkyCoord
...
>>> coord = SkyCoord(135.1408, -5.1915, unit="deg")
>>> sector_table = Tesscut.get_sectors(coordinates=coord)
>>> print(sector_table)
sectorName sector camera ccd
-------------- ------ ------ ---
tess-s0008-1-1 8 1 1
tess-s0034-1-2 34 1 2
tess-s0061-1-2 61 1 2
tess-s0088-1-2 88 1 2
You can also use the objectname parameter to specify a target by name or TIC ID.
>>> sector_table = Tesscut.get_sectors(objectname="TIC 32449963")
>>> print(sector_table)
sectorName sector camera ccd
-------------- ------ ------ ---
tess-s0010-1-4 10 1 4
To find sectors for a moving target, set the moving_target parameter to True.
>>> sector_table = Tesscut.get_sectors(objectname="Ceres", moving_target=True)
>>> print(sector_table)
sectorName sector camera ccd
-------------- ------ ------ ---
tess-s0029-1-4 29 1 4
tess-s0043-3-3 43 3 3
tess-s0044-2-4 44 2 4
tess-s0092-4-3 92 4 3
tess-s0097-1-4 97 1 4
Cutouts in Memory¶
For interactive analysis or workflows that do not require writing files to disk,
get_cutouts can be used to load TESS cutouts directly
into memory. This method returns cutout data as a list of
HDUList objects, allowing immediate inspection and analysis.
Targets may be specified by sky coordinates, resolved object names (including TIC IDs), or moving targets. The cutout size may be given in pixels or as an angular quantity; if not specified, a default size of 5 pixels is used.
The optional sector parameter controls which TESS observing sector is used when generating
cutouts. When sector is provided, cutouts are generated only from data in that specific
sector. This is useful when focusing on a particular observing window, comparing results
across sectors, or avoiding unnecessary data retrieval.
If sector is not specified, get_cutouts will return cutouts for all available
sectors in which the target appears. In this case, a separate target pixel file is returned
for each sector, and potentially for each camera or CCD overlapped by the cutout region. The returned cutout
list may therefore contain multiple cutouts, depending on the number of sectors, cameras, and CCDs involved.
This behavior ensures that all available data covering the target is returned.
The following example demonstrates how to request a TESS cutout using sky coordinates and a specified sector.
>>> from astroquery.mast import Tesscut
>>> from astropy.coordinates import SkyCoord
...
>>> cutout_coord = SkyCoord(107.18696, -70.50919, unit="deg")
>>> hdulist = Tesscut.get_cutouts(coordinates=cutout_coord, sector=33)
>>> hdulist[0].info()
Filename: <class '_io.BytesIO'>
No. Name Ver Type Cards Dimensions Format
0 PRIMARY 1 PrimaryHDU 57 ()
1 PIXELS 1 BinTableHDU 281 3495R x 12C [D, E, J, 25J, 25E, 25E, 25E, 25E, J, E, E, 38A]
2 APERTURE 1 ImageHDU 82 (5, 5) int32
You may also request cutouts of a moving target by inputting a valid moving target as the objectname and setting
the moving_target parameter to True.
>>> hdulist = Tesscut.get_cutouts(objectname="Eleonora",
... moving_target=True,
... sector=6)
>>> hdulist[0].info()
Filename: <class '_io.BytesIO'>
No. Name Ver Type Cards Dimensions Format
0 PRIMARY 1 PrimaryHDU 54 ()
1 PIXELS 1 BinTableHDU 150 355R x 16C [D, E, J, 25J, 25E, 25E, 25E, 25E, J, E, E, 38A, D, D, D, D]
2 APERTURE 1 ImageHDU 97 (2136, 2078) int32
Download Cutouts¶
For workflows that require persistent files on disk, such as batch processing or repeated
analysis, download_cutouts can be used to download TESS cutout
target pixel files to local storage.
This method accepts the same target specifications and cutout sizing options as
get_cutouts, but instead of returning in-memory FITS objects, it writes the resulting
cutout files to disk and returns an Table listing the local file paths.
By default, cutouts are downloaded as a compressed archive and automatically extracted into
the specified directory. The temporary archive is removed after extraction. To retain the
compressed archive without extracting its contents, set inflate=False.
As with in-memory cutouts, multiple files may be produced when a target appears in more than one TESS sector or overlaps multiple cameras or CCDs. For moving targets, if no sector is specified, cutouts are downloaded separately for each applicable sector to reduce load on the service.
>>> from astroquery.mast import Tesscut
>>> from astropy.coordinates import SkyCoord
>>> import astropy.units as u
...
>>> cutout_coord = SkyCoord(107.18696, -70.50919, unit="deg")
>>> manifest = Tesscut.download_cutouts(coordinates=cutout_coord,
... size=[5, 5]*u.arcmin,
... sector=9)
Downloading URL https://mast.stsci.edu/tesscut/api/v0.1/astrocut?ra=107.18696&dec=-70.50919&y=0.08333333333333333&x=0.11666666666666667&units=d§or=9 to ./tesscut_20210716150026.zip ... [Done]
>>> print(manifest)
Local Path
----------------------------------------------------------
./tess-s0009-4-1_107.186960_-70.509190_15x15_astrocut.fits
The returned table contains the paths to the downloaded target pixel files, which follow the standard TESS pipeline format and can be opened using Astropy or other FITS-compatible tools.
Downloaded cutouts are recommended when working with large numbers of targets, performing offline analysis, or integrating TESS cutouts into automated pipelines.
Zcut¶
ZCut is a MAST service that provides image cutouts from large, deep-field imaging surveys hosted at MAST. Unlike mission-specific cutout services, ZCut enables positional cutouts from a variety of wide-area and deep-field datasets through a single interface, making it useful for exploratory imaging analysis and multi-survey comparisons.
The ZcutClass provides programmatic access to the MAST ZCut API,
allowing users to generate cutouts centered on a sky position without downloading full-frame images.
Cutouts may be returned either as in-memory FITS objects for interactive analysis or as files
written to disk in FITS or common image formats.
ZCut supports workflows for discovering which deep-field surveys cover a given sky position, as well as requesting cutouts from one or more of those surveys. Optional image-scaling and stretching parameters are available when requesting image-format cutouts, enabling quick-look visualization directly from the service.
The sections below describe how to identify available surveys at a given position and how to retrieve cutouts using both in-memory and downloaded workflows.
Survey Discovery¶
Before requesting cutouts, users may wish to determine which deep-field surveys cover a given position on the sky. ZCut provides a survey discovery step that identifies all available imaging surveys whose footprints intersect a specified target location.
The get_surveys method returns a list of deep-field surveys
available at a given sky position. The target location may be specified using sky coordinates
or a resolvable target name. An optional search radius may be provided to expand the region
used for survey matching.
The result is returned as a list of survey identifiers, which can be used to:
Verify whether a position is covered by one or more deep-field surveys
Select a specific survey for subsequent cutout requests
Inspect and compare coverage across multiple surveys
If no surveys overlap the requested location, a warning is issued and an empty result is returned.
>>> from astroquery.mast import Zcut
>>> from astropy.coordinates import SkyCoord
...
>>> coord = SkyCoord(189.49206, 62.20615, unit="deg")
>>> survey_list = Zcut.get_surveys(coordinates=coord)
>>> print(survey_list)
['candels_gn_60mas', 'candels_gn_30mas', 'goods_north', '3dhst_goods-n']
Cutouts in Memory¶
For interactive analysis or exploratory workflows, ZCut supports retrieving cutouts directly
into memory without writing files to disk. The
get_cutouts method returns cutout data as a list of
HDUList objects, which can be inspected and analyzed immediately.
Cutouts are requested by sky position and may optionally be restricted to a specific survey with the survey parameter.
The cutout size may be specified in pixels or as an angular quantity; if not provided, a
default size of 5 pixels is used.
When no survey is specified, cutouts are returned for all surveys that cover the requested position. If a survey is provided, only cutouts from that survey are returned. This allows users to compare coverage across multiple datasets or to focus on a single deep-field survey of interest. The returned list may contain multiple cutouts, depending on the number of surveys that overlap the requested location.
The following example demonstrates how to request a ZCut cutout using sky coordinates and a specified survey.
>>> from astroquery.mast import Zcut
>>> from astropy.coordinates import SkyCoord
...
>>> cutout_coord = SkyCoord(189.49206, 62.20615, unit="deg")
>>> hdulist = Zcut.get_cutouts(coordinates=cutout_coord, survey='3dhst_goods-n')
>>> hdulist[0].info()
Filename: <class '_io.BytesIO'>
No. Name Ver Type Cards Dimensions Format
0 PRIMARY 1 PrimaryHDU 11 ()
1 CUTOUT 1 ImageHDU 177 (5, 5) float32
2 CUTOUT 1 ImageHDU 177 (5, 5) float32
3 CUTOUT 1 ImageHDU 177 (5, 5) float32
Download Cutouts¶
For workflows that require cutout files to be saved locally, such as batch processing or
offline analysis, download_cutouts can be used to download ZCut
image cutouts to disk.
This method accepts the same target, size, and survey parameters as get_cutouts, but
writes the resulting cutout files to the specified directory instead of returning in-memory
objects. The method returns an Table containing the local file paths of the
downloaded cutouts.
By default, cutouts are returned from the service as a compressed archive and are
automatically extracted into the output directory. The temporary archive is removed after
extraction. To retain the archive without extracting its contents, set inflate=False.
Cutouts may be saved in FITS format or in common image formats (jpg or png). When requesting image-format cutouts, optional image-scaling parameters may be supplied to control stretching, scaling, and inversion for quick-look visualization.
If no survey is specified, cutouts are downloaded for all surveys that cover the requested position. Restricting the request to a single survey can help reduce the number of returned files.
The following example demonstrates how to download ZCut cutouts using sky coordinates and a specified survey.
>>> from astroquery.mast import Zcut
>>> from astropy.coordinates import SkyCoord
...
>>> cutout_coord = SkyCoord(189.49206, 62.20615, unit="deg")
>>> manifest = Zcut.download_cutouts(coordinates=cutout_coord,
... size=[5, 10],
... units="px",
... survey="3dhst_goods-n")
Downloading URL https://mast.stsci.edu/zcut/api/v0.1/astrocut?ra=189.49206&dec=62.20615&y=200&x=300&units=px&format=fits to ./zcut_20210125155545.zip ... [Done]
Inflating...
...
>>> print(manifest)
Local Path
-------------------------------------------------------------------------
./candels_gn_30mas_189.492060_62.206150_300.0pix-x-200.0pix_astrocut.fits
You can also request cutouts in image formats such as jpg by setting the cutout_format parameter.
>>> manifest = Zcut.download_cutouts(coordinates=cutout_coord,
... size=[5, 10],
... units="px",
... survey="3dhst_goods-n",
... cutout_format="jpg")
Downloading URL https://mast.stsci.edu/zcut/api/v0.1/astrocut?ra=189.49206&dec=62.20615&y=200&x=300&units=px&format=jpg to ./zcut_20201202132453.zip ... [Done]
...
>>> print(manifest)
Local Path
-------------------------------------------------------------------------------------------------------
./hlsp_3dhst_spitzer_irac_goods-n_irac1_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_spitzer_irac_goods-n-s2_irac3_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_spitzer_irac_goods-n-s1_irac4_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_spitzer_irac_goods-n_irac2_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_mayall_mosaic_goods-n_u_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_subaru_suprimecam_goods-n_rc_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_subaru_suprimecam_goods-n_v_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_subaru_suprimecam_goods-n_ic_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_subaru_suprimecam_goods-n_zp_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
./hlsp_3dhst_subaru_suprimecam_goods-n_b_v4.0_sc_189.492060_62.206150_10.0pix-x-5.0pix_astrocut_0.jpg
HAPCut¶
HAPCut is a MAST service that provides image cutouts from Hubble Advanced Products (HAP), which are high-level, science-ready data products derived from Hubble Space Telescope observations. These products combine and reprocess individual exposures to produce well-aligned, calibrated images suitable for direct scientific analysis.
The HapcutClass provides programmatic access to the MAST HAPCut API,
allowing users to generate image cutouts centered on a sky position without downloading full
HAP mosaics or images. This interface is designed for simple, position-based cutout requests
and supports both in-memory and file-based workflows.
HAPCut cutouts are returned as FITS images and are well suited for quick-look visualization, photometric measurements, and targeted analysis of small regions within larger Hubble datasets. Unlike other cutout services, HAPCut does not require survey or sector selection; all available HAP imaging that overlaps the requested position is returned.
The sections below describe how to retrieve HAP cutouts directly into memory or download them to disk for further analysis.
Cutouts in Memory¶
For interactive analysis or exploratory workflows, HAPCut supports retrieving image cutouts
directly into memory without writing files to disk. The
get_cutouts method returns cutout data as a list of
HDUList objects, allowing immediate inspection and analysis.
Cutouts are requested by sky position and cutout size. The target may be specified using sky coordinates or a resolvable object name, and the cutout size may be given in pixels or as an angular quantity. If not specified, a default size of 5 pixels is used.
When multiple HAP images overlap the requested position, a separate cutout is returned for each matching image. This ensures that all available Hubble Advanced Products covering the target are included in the result.
>>> from astroquery.mast import Hapcut
>>> from astropy.coordinates import SkyCoord
...
>>> cutout_coord = SkyCoord(351.347812, 28.497808, unit="deg")
>>> hdulist = Hapcut.get_cutouts(coordinates=cutout_coord, size=5)
>>> hdulist[0].info()
Filename: <class '_io.BytesIO'>
No. Name Ver Type Cards Dimensions Format
0 PRIMARY 1 PrimaryHDU 754 ()
1 SCI 1 ImageHDU 102 (5, 5) float32
2 WHT 1 ImageHDU 56 (5, 5) float32
Each element in the returned list is a FITS image provided as an in-memory object. In-memory cutouts are best suited for visualization, exploratory analysis, and notebook-based workflows where temporary files are unnecessary.
Download Cutouts¶
For workflows that require cutout files to be saved locally, such as batch processing or
offline analysis, download_cutouts can be used to download HAP
image cutouts to disk.
This method accepts the same target and size parameters as get_cutouts,
but writes the resulting cutout files to the specified directory instead of returning in-memory FITS
objects. The method returns an Table listing the local paths of the
downloaded cutouts.
By default, cutouts are returned from the service as a compressed archive and are
automatically extracted into the output directory. The temporary archive is removed after
extraction. To retain the archive without extracting its contents, set inflate=False.
If multiple HAP images overlap the requested position, a separate cutout file is produced for each image. This behavior ensures that all available Hubble Advanced Products covering the target location are included in the downloaded results.
>>> from astroquery.mast import Hapcut
>>> from astropy.coordinates import SkyCoord
...
>>> cutout_coord = SkyCoord(351.347812, 28.497808, unit="deg")
>>> manifest = Hapcut.download_cutouts(coordinates=cutout_coord, size=[50, 100])
Downloading URL https://mast.stsci.edu/hapcut/api/v0.1/astrocut?ra=351.347812&dec=28.497808&x=100&y=50&units=px to ./hapcut_20221130112710.zip ... [Done]
Inflating...
...
>>> print(manifest)
Local Path
---------------------------------------------------------------------------------
./hst_cutout_skycell-p2007x09y05-ra351d3478-decn28d4978_wfc3_ir_f160w_coarse.fits
./hst_cutout_skycell-p2007x09y05-ra351d3478-decn28d4978_wfc3_ir_f160w.fits
./hst_cutout_skycell-p2007x09y05-ra351d3478-decn28d4978_wfc3_uvis_f606w.fits
./hst_cutout_skycell-p2007x09y05-ra351d3478-decn28d4978_wfc3_uvis_f814w.fits
The returned table contains the paths to the downloaded FITS cutout files, which can be opened using standard FITS-compatible tools for further analysis.