Coverage for python/lsst/obs/base/_fitsRawFormatterBase.py: 39%
139 statements
« prev ^ index » next coverage.py v7.3.1, created at 2023-09-29 17:03 +0000
« prev ^ index » next coverage.py v7.3.1, created at 2023-09-29 17:03 +0000
1# This file is part of obs_base.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (https://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This program is free software: you can redistribute it and/or modify
10# it under the terms of the GNU General Public License as published by
11# the Free Software Foundation, either version 3 of the License, or
12# (at your option) any later version.
13#
14# This program is distributed in the hope that it will be useful,
15# but WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17# GNU General Public License for more details.
18#
19# You should have received a copy of the GNU General Public License
20# along with this program. If not, see <http://www.gnu.org/licenses/>.
22__all__ = ("FitsRawFormatterBase",)
24import logging
25from abc import abstractmethod
27import lsst.afw.fits
28import lsst.afw.geom
29import lsst.afw.image
30from astro_metadata_translator import ObservationInfo, fix_header
31from lsst.daf.butler import FileDescriptor
32from lsst.utils.classes import cached_getter
34from .formatters.fitsExposure import FitsImageFormatterBase, standardizeAmplifierParameters
35from .makeRawVisitInfoViaObsInfo import MakeRawVisitInfoViaObsInfo
36from .utils import InitialSkyWcsError, createInitialSkyWcsFromBoresight
38log = logging.getLogger(__name__)
41class FitsRawFormatterBase(FitsImageFormatterBase):
42 """Abstract base class for reading and writing raw data to and from
43 FITS files.
44 """
46 # This has to be explicit until we fix camera geometry in DM-20746
47 wcsFlipX = False
48 """Control whether the WCS is flipped in the X-direction (`bool`)"""
50 def __init__(self, *args, **kwargs):
51 super().__init__(*args, **kwargs)
52 self._metadata = None
53 self._observationInfo = None
55 @classmethod
56 def fromMetadata(cls, metadata, obsInfo=None, storageClass=None, location=None):
57 """Construct a possibly-limited formatter from known metadata.
59 Parameters
60 ----------
61 metadata : `lsst.daf.base.PropertyList`
62 Raw header metadata, with any fixes (see
63 `astro_metadata_translator.fix_header`) applied but nothing
64 stripped.
65 obsInfo : `astro_metadata_translator.ObservationInfo`, optional
66 Structured information already extracted from ``metadata``.
67 If not provided, will be read from ``metadata`` on first use.
68 storageClass : `lsst.daf.butler.StorageClass`, optional
69 StorageClass for this file. If not provided, the formatter will
70 only support `makeWcs`, `makeVisitInfo`, `makeFilter`, and other
71 operations that operate purely on metadata and not the actual file.
72 location : `lsst.daf.butler.Location`, optional.
73 Location of the file. If not provided, the formatter will only
74 support `makeWcs`, `makeVisitInfo`, `makeFilter`, and other
75 operations that operate purely on metadata and not the actual file.
77 Returns
78 -------
79 formatter : `FitsRawFormatterBase`
80 An instance of ``cls``.
81 """
82 self = cls(FileDescriptor(location, storageClass))
83 self._metadata = metadata
84 self._observationInfo = obsInfo
85 return self
87 @property
88 @abstractmethod
89 def translatorClass(self):
90 """`~astro_metadata_translator.MetadataTranslator` to translate
91 metadata header to `~astro_metadata_translator.ObservationInfo`.
92 """
93 return None
95 @property
96 @abstractmethod
97 def filterDefinitions(self):
98 """`~lsst.obs.base.FilterDefinitions`, defining the filters for this
99 instrument.
100 """
101 return None
103 @property
104 @cached_getter
105 def checked_parameters(self):
106 # Docstring inherited.
107 parameters = super().checked_parameters
108 if "bbox" in parameters:
109 raise TypeError(
110 "Raw formatters do not support reading arbitrary subimages, as some "
111 "implementations may be assembled on-the-fly."
112 )
113 return parameters
115 def readImage(self):
116 """Read just the image component of the Exposure.
118 Returns
119 -------
120 image : `~lsst.afw.image.Image`
121 In-memory image component.
122 """
123 return lsst.afw.image.ImageU(self.fileDescriptor.location.path)
125 def isOnSky(self):
126 """Boolean to determine if the exposure is thought to be on the sky.
128 Returns
129 -------
130 onSky : `bool`
131 Returns `True` if the observation looks like it was taken on the
132 sky. Returns `False` if this observation looks like a calibration
133 observation.
135 Notes
136 -----
137 If there is tracking RA/Dec information associated with the
138 observation it is assumed that the observation is on sky.
139 Currently the observation type is not checked.
140 """
141 if self.observationInfo.tracking_radec is None:
142 return False
143 return True
145 @property
146 def metadata(self):
147 """The metadata read from this file. It will be stripped as
148 components are extracted from it
149 (`lsst.daf.base.PropertyList`).
150 """
151 if self._metadata is None:
152 self._metadata = self.readMetadata()
153 return self._metadata
155 def readMetadata(self):
156 """Read all header metadata directly into a PropertyList.
158 Returns
159 -------
160 metadata : `~lsst.daf.base.PropertyList`
161 Header metadata.
162 """
163 md = lsst.afw.fits.readMetadata(self.fileDescriptor.location.path)
164 fix_header(md, translator_class=self.translatorClass)
165 return md
167 def stripMetadata(self):
168 """Remove metadata entries that are parsed into components."""
169 try:
170 lsst.afw.geom.stripWcsMetadata(self.metadata)
171 except TypeError as e:
172 log.debug("Error caught and ignored while stripping metadata: %s", e.args[0])
174 def makeVisitInfo(self):
175 """Construct a VisitInfo from metadata.
177 Returns
178 -------
179 visitInfo : `~lsst.afw.image.VisitInfo`
180 Structured metadata about the observation.
181 """
182 return MakeRawVisitInfoViaObsInfo.observationInfo2visitInfo(self.observationInfo)
184 @abstractmethod
185 def getDetector(self, id):
186 """Return the detector that acquired this raw exposure.
188 Parameters
189 ----------
190 id : `int`
191 The identifying number of the detector to get.
193 Returns
194 -------
195 detector : `~lsst.afw.cameraGeom.Detector`
196 The detector associated with that ``id``.
197 """
198 raise NotImplementedError("Must be implemented by subclasses.")
200 def makeWcs(self, visitInfo, detector):
201 """Create a SkyWcs from information about the exposure.
203 If VisitInfo is not None, use it and the detector to create a SkyWcs,
204 otherwise return the metadata-based SkyWcs (always created, so that
205 the relevant metadata keywords are stripped).
207 Parameters
208 ----------
209 visitInfo : `~lsst.afw.image.VisitInfo`
210 The information about the telescope boresight and camera
211 orientation angle for this exposure.
212 detector : `~lsst.afw.cameraGeom.Detector`
213 The detector used to acquire this exposure.
215 Returns
216 -------
217 skyWcs : `~lsst.afw.geom.SkyWcs`
218 Reversible mapping from pixel coordinates to sky coordinates.
220 Raises
221 ------
222 InitialSkyWcsError
223 Raised if there is an error generating the SkyWcs, chained from the
224 lower-level exception if available.
225 """
226 if not self.isOnSky():
227 # This is not an on-sky observation
228 return None
230 if visitInfo is None:
231 msg = "No VisitInfo; cannot access boresight information. Defaulting to metadata-based SkyWcs."
232 log.warning(msg)
233 skyWcs = self._createSkyWcsFromMetadata()
234 if skyWcs is None:
235 raise InitialSkyWcsError(
236 "Failed to create both metadata and boresight-based SkyWcs."
237 "See warnings in log messages for details."
238 )
239 return skyWcs
241 return self.makeRawSkyWcsFromBoresight(
242 visitInfo.getBoresightRaDec(), visitInfo.getBoresightRotAngle(), detector
243 )
245 @classmethod
246 def makeRawSkyWcsFromBoresight(cls, boresight, orientation, detector):
247 """Class method to make a raw sky WCS from boresight and detector.
249 Parameters
250 ----------
251 boresight : `lsst.geom.SpherePoint`
252 The ICRS boresight RA/Dec
253 orientation : `lsst.geom.Angle`
254 The rotation angle of the focal plane on the sky.
255 detector : `lsst.afw.cameraGeom.Detector`
256 Where to get the camera geomtry from.
258 Returns
259 -------
260 skyWcs : `~lsst.afw.geom.SkyWcs`
261 Reversible mapping from pixel coordinates to sky coordinates.
262 """
263 return createInitialSkyWcsFromBoresight(boresight, orientation, detector, flipX=cls.wcsFlipX)
265 def _createSkyWcsFromMetadata(self):
266 """Create a SkyWcs from the FITS header metadata in an Exposure.
268 Returns
269 -------
270 skyWcs: `lsst.afw.geom.SkyWcs`, or None
271 The WCS that was created from ``self.metadata``, or None if that
272 creation fails due to invalid metadata.
273 """
274 if not self.isOnSky():
275 # This is not an on-sky observation
276 return None
278 try:
279 return lsst.afw.geom.makeSkyWcs(self.metadata, strip=True)
280 except TypeError as e:
281 log.warning("Cannot create a valid WCS from metadata: %s", e.args[0])
282 return None
284 def makeFilterLabel(self):
285 """Construct a FilterLabel from metadata.
287 Returns
288 -------
289 filter : `~lsst.afw.image.FilterLabel`
290 Object that identifies the filter for this image.
291 """
292 physical = self.observationInfo.physical_filter
293 band = self.filterDefinitions.physical_to_band[physical]
294 return lsst.afw.image.FilterLabel(physical=physical, band=band)
296 def readComponent(self, component):
297 # Docstring inherited.
298 _ = self.checked_parameters # just for checking; no supported parameters.
299 if component == "image":
300 return self.readImage()
301 elif component == "filter":
302 return self.makeFilterLabel()
303 elif component == "visitInfo":
304 return self.makeVisitInfo()
305 elif component == "detector":
306 return self.getDetector(self.observationInfo.detector_num)
307 elif component == "wcs":
308 detector = self.getDetector(self.observationInfo.detector_num)
309 visitInfo = self.makeVisitInfo()
310 return self.makeWcs(visitInfo, detector)
311 elif component == "metadata":
312 self.stripMetadata()
313 return self.metadata
314 return None
316 def readFull(self):
317 # Docstring inherited.
318 amplifier, detector, _ = standardizeAmplifierParameters(
319 self.checked_parameters,
320 self.getDetector(self.observationInfo.detector_num),
321 )
322 if amplifier is not None:
323 reader = lsst.afw.image.ImageFitsReader(self.fileDescriptor.location.path)
324 amplifier_isolator = lsst.afw.cameraGeom.AmplifierIsolator(
325 amplifier,
326 reader.readBBox(),
327 detector,
328 )
329 subimage = amplifier_isolator.transform_subimage(
330 reader.read(bbox=amplifier_isolator.subimage_bbox)
331 )
332 exposure = lsst.afw.image.makeExposure(lsst.afw.image.makeMaskedImage(subimage))
333 exposure.setDetector(amplifier_isolator.make_detector())
334 else:
335 exposure = lsst.afw.image.makeExposure(lsst.afw.image.makeMaskedImage(self.readImage()))
336 exposure.setDetector(detector)
337 self.attachComponentsFromMetadata(exposure)
338 return exposure
340 def write(self, inMemoryDataset):
341 """Write a Python object to a file.
343 Parameters
344 ----------
345 inMemoryDataset : `object`
346 The Python object to store.
348 Returns
349 -------
350 path : `str`
351 The `URI` where the primary file is stored.
352 """
353 raise NotImplementedError("Raw data cannot be `put`.")
355 @property
356 def observationInfo(self):
357 """The `~astro_metadata_translator.ObservationInfo` extracted from
358 this file's metadata (`~astro_metadata_translator.ObservationInfo`,
359 read-only).
360 """
361 if self._observationInfo is None:
362 location = self.fileDescriptor.location
363 path = location.path if location is not None else None
364 self._observationInfo = ObservationInfo(
365 self.metadata, translator_class=self.translatorClass, filename=path
366 )
367 return self._observationInfo
369 def attachComponentsFromMetadata(self, exposure):
370 """Attach all `lsst.afw.image.Exposure` components derived from
371 metadata (including the stripped metadata itself).
373 Parameters
374 ----------
375 exposure : `lsst.afw.image.Exposure`
376 Exposure to attach components to (modified in place). Must already
377 have a detector attached.
378 """
379 info = exposure.getInfo()
380 info.id = self.observationInfo.detector_exposure_id
381 info.setFilter(self.makeFilterLabel())
382 info.setVisitInfo(self.makeVisitInfo())
383 info.setWcs(self.makeWcs(info.getVisitInfo(), info.getDetector()))
385 self.stripMetadata()
386 exposure.setMetadata(self.metadata)