Functions to write cutouts to a ZIP (#167)

* function to write cutouts to zip

* style fixes, changelog

* Test fix

Additional test coverage

Fix error message

* Adding types

* Applying copilot feedback

* Refactor _make_cutout_filename into cutout.py, fix floating point precision

Doctest fix

* Comments, reworking inheritance of method

* More descriptive changelog

Fix indentation on changelog

Sync changelog

* Update docstrings for new zip filename format

Author: snbianco

CHANGES.rst

@@ -1,11 +1,35 @@
 Unreleased
 ----------
 
-- Added support in `ra_dec_crossmatch` for a cutout size of zero, enabling single-point matching to FFIs that contain
+- Added support in ``ra_dec_crossmatch`` for a cutout size of zero, enabling single-point matching to FFIs that contain
   the specified coordinates. [#166]
+- Added ``write_as_zip`` method to ``ASDFCutout``, ``FITSCutout``, ``TessCubeCutout``, and ``TessFootprintCutout`` classes to facilitate 
+  writing multiple cutouts into a single ZIP archive. [#167]
 - Added ``get_tess_sectors`` function to return TESS sector information for sectors whose footprints overlap with 
   the given sky coordinates and cutout size. [#168]
 
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+- Cube cutout filenames now use a hyphen between dimensions (e.g., ``10-x-10`` instead of ``10x10``). They also include unit suffixes when 
+  users request sizes as an ``astropy.units.Quantity`` object (e.g., ``5arcmin-x-4arcmin`` or ``30arcsec-x-20arcsec``). RA/Dec formatting within
+  filenames now uses 7 decimal places (``{:.7f}``) for consistency across classes. These changes may break code that parses filenames or relies on
+  old glob patterns. [#167]
+
+  Migration:
+
+  - Update glob patterns from ``*_<ra>_<dec>_<ny>x<nx>_astrocut.fits`` to ``*_<ra>_<dec>_*-x-*_astrocut.fits``.
+  - If parsing filenames, switch to flexible regex patterns:
+
+    - RA/Dec: ``_(?P<ra>[-+]?\\d+(?:\\.\\d+)?)_(?P<dec>[-+]?\\d+(?:\\.\\d+)?)_``
+    - Dimensions (with optional units): ``(?P<ny>\\d+(?:\\.\\d+)?)(?P<ny_unit>arcsec|arcmin|deg|pixel|pix)?-x-(?P<nx>\\d+(?:\\.\\d+)?)(?P<nx_unit>arcsec|arcmin|deg|pixel|pix)?``
+  - Prefer reading RA/Dec, dimensions, and scales from file metadata (FITS headers/WCS) instead of relying on filenames.
+  - Example transition:
+
+    - Old: ``..._83.406310_-62.489771_64x64_astrocut.fits``
+    - New (no unit - pixels assumed): ``..._83.4063100_-62.4897710_64-x-64_astrocut.fits``
+    - New (with units): ``..._83.4063100_-62.4897710_5arcmin-x-4arcmin_astrocut.fits``
+
 
 1.1.0 (2025-09-15)
 ------------------

astrocut/asdf_cutout.py

@@ -419,6 +419,33 @@ def cutout(self) -> Union[str, List[str], List[fits.HDUList]]:
         log.debug('Total time: %.2f sec', monotonic() - start_time)
 
         return self.cutouts
+    
+    def _make_cutout_filename(self, file: Union[str, Path], output_format: str) -> str:
+        """
+        Generate a standardized filename for the cutout.
+
+        Overrides the superclass method to include the '_lite' tag if applicable and the output format.
+
+        Parameters
+        ----------
+        file : str | Path
+            The input file name.
+        output_format : str
+            The output format to write the cutout to. Options are '.fits' and '.asdf'.
+
+        Returns
+        -------
+        filename : str
+            The generated filename for the cutout.
+        """
+        return '{}_{:.7f}_{:.7f}_{}-x-{}{}_astrocut{}'.format(
+            Path(file).stem,
+            self._coordinates.ra.value,
+            self._coordinates.dec.value,
+            str(self._cutout_size[0]).replace(' ', ''), 
+            str(self._cutout_size[1]).replace(' ', ''),
+            '_lite' if self._lite else '',
+            output_format)
 
     def _write_as_format(self, output_format: str, output_dir: Union[str, Path] = '.') -> List[str]:
         """
@@ -440,14 +467,7 @@ def _write_as_format(self, output_format: str, output_dir: Union[str, Path] = '.
         cutout_paths = []  # List to store paths to cutout files
         for i, file in enumerate(self.cutouts_by_file):
             # Determine the output path
-            filename = '{}_{:.7f}_{:.7f}_{}-x-{}{}_astrocut{}'.format(
-                Path(file).stem,
-                self._coordinates.ra.value,
-                self._coordinates.dec.value,
-                str(self._cutout_size[0]).replace(' ', ''), 
-                str(self._cutout_size[1]).replace(' ', ''),
-                '_lite' if self._lite else '',
-                output_format)
+            filename = self._make_cutout_filename(file, output_format)
             cutout_path = Path(output_dir, filename)
 
             if output_format == '.fits':
@@ -496,6 +516,42 @@ def write_as_asdf(self, output_dir: Union[str, Path] = '.') -> List[str]:
             A list of paths to the cutout ASDF files.
         """
         return self._write_as_format(output_format='.asdf', output_dir=output_dir)
+
+    def write_as_zip(self, output_dir: Union[str, Path] = '.', filename: Union[str, Path, None] = None,
+                     *, output_format: str = '.asdf') -> str:
+        """
+        Package the ASDF or FITS cutouts into a zip archive without writing intermediates.
+
+        Parameters
+        ----------
+        output_dir : str | Path, optional
+            Directory where the zip will be created. Default '.'.
+        filename : str | Path | None, optional
+            Name (or path) of the output zip file. If not provided, defaults to
+            'astrocut_{ra}_{dec}_{size}.zip'. If provided without a '.zip' suffix,
+            the suffix is added automatically.
+        output_format : str, optional
+            Either '.asdf' (default) or '.fits'. Determines which in-memory representation is zipped.
+
+        Returns
+        -------
+        str
+            Path to the created zip file.
+        """
+        fmt = output_format.lower().strip()
+        fmt = '.' + fmt if not fmt.startswith('.') else fmt
+        if fmt not in ('.asdf', '.fits'):
+            raise InvalidInputError("File format must be either '.asdf' or '.fits'")
+
+        def build_entries():
+            use_fits = fmt == '.fits'
+            objs = self.fits_cutouts if use_fits else self.asdf_cutouts
+
+            for i, file in enumerate(self.cutouts_by_file):
+                arcname = self._make_cutout_filename(file, fmt)
+                yield arcname, objs[i]
+
+        return self._write_cutouts_to_zip(output_dir=output_dir, filename=filename, build_entries=build_entries)
 
 
 def get_center_pixel(gwcsobj: gwcs.wcs.WCS, ra: float, dec: float) -> Tuple[Tuple[int, int], WCS]:

astrocut/cutout.py

@@ -1,13 +1,17 @@
+import warnings
+import io
+import zipfile
 from abc import abstractmethod, ABC
 from pathlib import Path
-from typing import List, Union, Tuple
-import warnings
+from typing import List, Union, Tuple, Iterable, Callable, Any, Optional
 
-from astropy import wcs
+import asdf
 import astropy.units as u
+import numpy as np
+from astropy import wcs
+from astropy.io import fits
 from s3path import S3Path
 from astropy.coordinates import SkyCoord
-import numpy as np
 
 from astrocut.exceptions import InputWarning, InvalidInputError, InvalidQueryError
 
@@ -148,6 +152,107 @@ def cutout(self):
         This method is abstract and should be defined in subclasses.
         """
         raise NotImplementedError('Subclasses must implement this method.')
+    
+    def _make_cutout_filename(self, file_stem: str) -> str:
+        """
+        Create a cutout filename based on a file stem, coordinates, and cutout size.
+
+        Parameters
+        ----------
+        file_stem : str
+            The stem of the input file to use in the cutout filename.
+
+        Returns
+        -------
+        filename : str
+            The generated cutout filename.
+        """
+        return '{}_{:.7f}_{:.7f}_{}-x-{}_astrocut.fits'.format(
+            file_stem,
+            self._coordinates.ra.value,
+            self._coordinates.dec.value,
+            str(self._cutout_size[0]).replace(' ', ''),
+            str(self._cutout_size[1]).replace(' ', ''))
+    
+    def _obj_to_bytes(self, obj: Union[fits.HDUList, asdf.AsdfFile]) -> bytes:
+        """
+        Convert a supported object into bytes for writing into a zip stream.
+
+        Parameters
+        ----------
+        obj : `astropy.io.fits.HDUList` | `asdf.AsdfFile`
+            The object to convert to bytes.
+
+        Returns
+        -------
+        bytes
+            The byte representation of the object.
+        """
+        # HDUList to bytes
+        if isinstance(obj, fits.HDUList):
+            buf = io.BytesIO()
+            with warnings.catch_warnings():
+                warnings.simplefilter('ignore', fits.verify.VerifyWarning)
+                obj.writeto(buf, overwrite=True, checksum=True)
+        # `AsdfFile` to bytes
+        elif isinstance(obj, asdf.AsdfFile):
+            buf = io.BytesIO()
+            obj.write_to(buf)
+        else:
+            raise TypeError(
+                'Unsupported payload type for zip entry. Expected `HDUList` or `AsdfFile`.'
+            )
+        
+        return buf.getvalue()
+
+    def _write_cutouts_to_zip(
+        self,
+        output_dir: Union[str, Path] = ".",
+        filename: Optional[Union[str, Path]] = None,
+        build_entries: Optional[Callable[[], Iterable[Tuple[str, Any]]]] = None
+    ) -> str:
+        """
+        Create a zip archive containing all cutout files without writing intermediate files.
+
+        Parameters
+        ----------
+        output_dir : str | Path, optional
+            Directory where the zip will be created. Default '.'
+        filename : str | Path | None, optional
+            Name (or path) of the output zip file. If not provided, defaults to
+            'astrocut_{ra}_{dec}_{size}.zip'. If provided without a '.zip' suffix,
+            the suffix is added automatically.
+        build_entries : callable -> iterable of (arcname, payload), optional
+            Function that yields entries lazily. Useful to build streams on demand.
+
+        Returns
+        -------
+        str
+            Path to the created zip file.
+        """
+        # Resolve zip path and ensure directory exists
+        if filename is None:
+            filename = 'astrocut_{:.7f}_{:.7f}_{}-x-{}.zip'.format(
+                self._coordinates.ra.value,
+                self._coordinates.dec.value,
+                str(self._cutout_size[0]).replace(' ', ''),
+                str(self._cutout_size[1]).replace(' ', ''))
+        filename = Path(filename)
+        if filename.suffix.lower() != '.zip':
+            filename = filename.with_suffix('.zip')
+
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        zip_path = filename if filename.is_absolute() else output_dir / filename
+
+        # Stream entries directly into the zip
+        with zipfile.ZipFile(zip_path, mode='w', compression=zipfile.ZIP_DEFLATED) as zf:
+            for arcname, payload in build_entries():
+                data = self._obj_to_bytes(payload)
+                zf.writestr(arcname, data)
+
+        return zip_path.as_posix()
 
     @staticmethod
     def parse_size_input(cutout_size, *, allow_zero: bool = False) -> np.ndarray:

astrocut/fits_cutout.py

@@ -405,12 +405,7 @@ def write_as_fits(self, output_dir: Union[str, Path] = '.', cutout_prefix: str =
             log.debug('Returning cutout as a single FITS file.')
 
             cutout_fits = self.fits_cutouts[0]
-            filename = '{}_{:.7f}_{:.7f}_{}-x-{}_astrocut.fits'.format(
-                cutout_prefix,
-                self._coordinates.ra.value,
-                self._coordinates.dec.value,
-                str(self._cutout_size[0]).replace(' ', ''),
-                str(self._cutout_size[1]).replace(' ', ''))
+            filename = self._make_cutout_filename(cutout_prefix)
             cutout_path = Path(output_dir, filename)
             with warnings.catch_warnings():
                 warnings.simplefilter('ignore') 
@@ -424,12 +419,7 @@ def write_as_fits(self, output_dir: Union[str, Path] = '.', cutout_prefix: str =
             cutout_paths = []
             for i, file in enumerate(self.hdu_cutouts_by_file):
                 cutout_fits = self.fits_cutouts[i]
-                filename = '{}_{:.7f}_{:.7f}_{}-x-{}_astrocut.fits'.format(
-                    Path(file).stem,
-                    self._coordinates.ra.value,
-                    self._coordinates.dec.value,
-                    str(self._cutout_size[0]).replace(' ', ''), 
-                    str(self._cutout_size[1]).replace(' ', ''))
+                filename = self._make_cutout_filename(Path(file).stem)
                 cutout_path = Path(output_dir, filename)
                 with warnings.catch_warnings():
                     warnings.simplefilter('ignore')
@@ -439,6 +429,39 @@ def write_as_fits(self, output_dir: Union[str, Path] = '.', cutout_prefix: str =
 
             log.debug('Cutout filepaths: {}'.format(cutout_paths))
             return cutout_paths
+
+    def write_as_zip(self, output_dir: Union[str, Path] = '.', filename: Union[str, Path, None] = None) -> str:
+        """
+        Package the FITS cutouts into a zip archive without writing intermediate files.
+
+        Parameters
+        ----------
+        output_dir : str | Path, optional
+            Directory where the zip will be created. Default '.'.
+        filename : str | Path | None, optional
+            Name (or path) of the output zip file. If not provided, defaults to
+            'astrocut_{ra}_{dec}_{size}.zip'. If provided without a '.zip' suffix,
+            the suffix is added automatically.
+
+        Returns
+        -------
+        str
+            Path to the created zip file.
+        """
+        def build_entries():
+            if self._single_outfile:
+                # Mirror the single-file naming used by write_as_fits
+                arcname = self._make_cutout_filename('cutout')
+                hdu = self.fits_cutouts[0]
+                yield arcname, hdu
+            else:
+                # One file per input; mirror write_as_fits naming
+                for i, file in enumerate(self.hdu_cutouts_by_file):
+                    arcname = self._make_cutout_filename(Path(file).stem)
+                    hdu = self.fits_cutouts[i]
+                    yield arcname, hdu
+
+        return self._write_cutouts_to_zip(output_dir=output_dir, filename=filename, build_entries=build_entries)
 
     class CutoutInstance:
         """

astrocut/tess_cube_cutout.py

@@ -487,15 +487,7 @@ def write_as_tpf(self, output_dir: Union[str, Path] = '.', output_file: str = No
         for file, cutout in self.cutouts_by_file.items():
             # Determine file name
             if not output_file or len(self._input_files) > 1:
-                cutout_lims = cutout.cutout_lims
-                width = cutout_lims[0, 1] - cutout_lims[0, 0]
-                height = cutout_lims[1, 1] - cutout_lims[1, 0]
-                filename = '{}_{:7f}_{:7f}_{}x{}_astrocut.fits'.format(
-                    Path(file).stem.rstrip('-cube'),
-                    self._coordinates.ra.value,
-                    self._coordinates.dec.value,
-                    width,
-                    height)
+                filename = self._make_cutout_filename(Path(file).stem.rstrip('-cube'))
             else:
                 filename = output_file
 
@@ -517,6 +509,31 @@ def write_as_tpf(self, output_dir: Union[str, Path] = '.', output_file: str = No
 
         log.debug('Write time: %.2f sec', (monotonic() - write_time))
         return cutout_paths
+
+    def write_as_zip(self, output_dir: Union[str, Path] = '.', filename: Union[str, Path, None] = None) -> str:
+        """
+        Package the cutout TPF files into a zip archive without writing intermediate files.
+
+        Parameters
+        ----------
+        output_dir : str | Path, optional
+            Directory where the zip will be created. Default '.'.
+        filename : str | Path | None, optional
+            Name (or path) of the output zip file. If not provided, defaults to
+            'astrocut_{ra}_{dec}_{size}.zip'. If provided without a '.zip' suffix,
+            the suffix is added automatically.
+
+        Returns
+        -------
+        str
+            Path to the created zip file.
+        """
+        def build_entries():
+            for file, tpf in self.tpf_cutouts_by_file.items():
+                arcname = self._make_cutout_filename(Path(file).stem.rstrip('-cube'))
+                yield arcname, tpf
+
+        return self._write_cutouts_to_zip(output_dir=output_dir, filename=filename, build_entries=build_entries)
 
     class CubeCutoutInstance(CubeCutout.CubeCutoutInstance):
         """