Coverage for python/lsst/obs/base/_fitsRawFormatterBase.py: 29%
135 statements
« prev ^ index » next coverage.py v6.5.0, created at 2023-03-04 02:09 -0800
« prev ^ index » next coverage.py v6.5.0, created at 2023-03-04 02:09 -0800
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)
165 return md
167 def stripMetadata(self):
168 """Remove metadata entries that are parsed into components."""
169 self._createSkyWcsFromMetadata()
171 def makeVisitInfo(self):
172 """Construct a VisitInfo from metadata.
174 Returns
175 -------
176 visitInfo : `~lsst.afw.image.VisitInfo`
177 Structured metadata about the observation.
178 """
179 return MakeRawVisitInfoViaObsInfo.observationInfo2visitInfo(self.observationInfo)
181 @abstractmethod
182 def getDetector(self, id):
183 """Return the detector that acquired this raw exposure.
185 Parameters
186 ----------
187 id : `int`
188 The identifying number of the detector to get.
190 Returns
191 -------
192 detector : `~lsst.afw.cameraGeom.Detector`
193 The detector associated with that ``id``.
194 """
195 raise NotImplementedError("Must be implemented by subclasses.")
197 def makeWcs(self, visitInfo, detector):
198 """Create a SkyWcs from information about the exposure.
200 If VisitInfo is not None, use it and the detector to create a SkyWcs,
201 otherwise return the metadata-based SkyWcs (always created, so that
202 the relevant metadata keywords are stripped).
204 Parameters
205 ----------
206 visitInfo : `~lsst.afw.image.VisitInfo`
207 The information about the telescope boresight and camera
208 orientation angle for this exposure.
209 detector : `~lsst.afw.cameraGeom.Detector`
210 The detector used to acquire this exposure.
212 Returns
213 -------
214 skyWcs : `~lsst.afw.geom.SkyWcs`
215 Reversible mapping from pixel coordinates to sky coordinates.
217 Raises
218 ------
219 InitialSkyWcsError
220 Raised if there is an error generating the SkyWcs, chained from the
221 lower-level exception if available.
222 """
223 if not self.isOnSky():
224 # This is not an on-sky observation
225 return None
227 skyWcs = self._createSkyWcsFromMetadata()
229 if visitInfo is None:
230 msg = "No VisitInfo; cannot access boresight information. Defaulting to metadata-based SkyWcs."
231 log.warning(msg)
232 if skyWcs is None:
233 raise InitialSkyWcsError(
234 "Failed to create both metadata and boresight-based SkyWcs."
235 "See warnings in log messages for details."
236 )
237 return skyWcs
239 return self.makeRawSkyWcsFromBoresight(
240 visitInfo.getBoresightRaDec(), visitInfo.getBoresightRotAngle(), detector
241 )
243 @classmethod
244 def makeRawSkyWcsFromBoresight(cls, boresight, orientation, detector):
245 """Class method to make a raw sky WCS from boresight and detector.
247 Parameters
248 ----------
249 boresight : `lsst.geom.SpherePoint`
250 The ICRS boresight RA/Dec
251 orientation : `lsst.geom.Angle`
252 The rotation angle of the focal plane on the sky.
253 detector : `lsst.afw.cameraGeom.Detector`
254 Where to get the camera geomtry from.
256 Returns
257 -------
258 skyWcs : `~lsst.afw.geom.SkyWcs`
259 Reversible mapping from pixel coordinates to sky coordinates.
260 """
261 return createInitialSkyWcsFromBoresight(boresight, orientation, detector, flipX=cls.wcsFlipX)
263 def _createSkyWcsFromMetadata(self):
264 """Create a SkyWcs from the FITS header metadata in an Exposure.
266 Returns
267 -------
268 skyWcs: `lsst.afw.geom.SkyWcs`, or None
269 The WCS that was created from ``self.metadata``, or None if that
270 creation fails due to invalid metadata.
271 """
272 if not self.isOnSky():
273 # This is not an on-sky observation
274 return None
276 try:
277 return lsst.afw.geom.makeSkyWcs(self.metadata, strip=True)
278 except TypeError as e:
279 log.warning("Cannot create a valid WCS from metadata: %s", e.args[0])
280 return None
282 def makeFilterLabel(self):
283 """Construct a FilterLabel from metadata.
285 Returns
286 -------
287 filter : `~lsst.afw.image.FilterLabel`
288 Object that identifies the filter for this image.
289 """
290 physical = self.observationInfo.physical_filter
291 band = self.filterDefinitions.physical_to_band[physical]
292 return lsst.afw.image.FilterLabel(physical=physical, band=band)
294 def readComponent(self, component):
295 # Docstring inherited.
296 self.checked_parameters # just for checking; no supported parameters.
297 if component == "image":
298 return self.readImage()
299 elif component == "filter":
300 return self.makeFilterLabel()
301 elif component == "visitInfo":
302 return self.makeVisitInfo()
303 elif component == "detector":
304 return self.getDetector(self.observationInfo.detector_num)
305 elif component == "wcs":
306 detector = self.getDetector(self.observationInfo.detector_num)
307 visitInfo = self.makeVisitInfo()
308 return self.makeWcs(visitInfo, detector)
309 elif component == "metadata":
310 self.stripMetadata()
311 return self.metadata
312 return None
314 def readFull(self):
315 # Docstring inherited.
316 amplifier, detector, _ = standardizeAmplifierParameters(
317 self.checked_parameters,
318 self.getDetector(self.observationInfo.detector_num),
319 )
320 if amplifier is not None:
321 reader = lsst.afw.image.ImageFitsReader(self.fileDescriptor.location.path)
322 amplifier_isolator = lsst.afw.cameraGeom.AmplifierIsolator(
323 amplifier,
324 reader.readBBox(),
325 detector,
326 )
327 subimage = amplifier_isolator.transform_subimage(
328 reader.read(bbox=amplifier_isolator.subimage_bbox)
329 )
330 exposure = lsst.afw.image.makeExposure(lsst.afw.image.makeMaskedImage(subimage))
331 exposure.setDetector(amplifier_isolator.make_detector())
332 else:
333 exposure = lsst.afw.image.makeExposure(lsst.afw.image.makeMaskedImage(self.readImage()))
334 exposure.setDetector(detector)
335 self.attachComponentsFromMetadata(exposure)
336 return exposure
338 def write(self, inMemoryDataset):
339 """Write a Python object to a file.
341 Parameters
342 ----------
343 inMemoryDataset : `object`
344 The Python object to store.
346 Returns
347 -------
348 path : `str`
349 The `URI` where the primary file is stored.
350 """
351 raise NotImplementedError("Raw data cannot be `put`.")
353 @property
354 def observationInfo(self):
355 """The `~astro_metadata_translator.ObservationInfo` extracted from
356 this file's metadata (`~astro_metadata_translator.ObservationInfo`,
357 read-only).
358 """
359 if self._observationInfo is None:
360 location = self.fileDescriptor.location
361 path = location.path if location is not None else None
362 self._observationInfo = ObservationInfo(
363 self.metadata, translator_class=self.translatorClass, filename=path
364 )
365 return self._observationInfo
367 def attachComponentsFromMetadata(self, exposure):
368 """Attach all `lsst.afw.image.Exposure` components derived from
369 metadata (including the stripped metadata itself).
371 Parameters
372 ----------
373 exposure : `lsst.afw.image.Exposure`
374 Exposure to attach components to (modified in place). Must already
375 have a detector attached.
376 """
377 info = exposure.getInfo()
378 info.id = self.observationInfo.detector_exposure_id
379 info.setFilter(self.makeFilterLabel())
380 info.setVisitInfo(self.makeVisitInfo())
381 info.setWcs(self.makeWcs(info.getVisitInfo(), info.getDetector()))
382 # We don't need to call stripMetadata() here because it has already
383 # been stripped during creation of the WCS.
384 exposure.setMetadata(self.metadata)