lsst.ip.isr  17.0.1-19-g1d02dc0+3
crosstalk.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 # Copyright 2008-2017 AURA/LSST.
4 #
5 # This product includes software developed by the
6 # LSST Project (http://www.lsst.org/).
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the LSST License Statement and
19 # the GNU General Public License along with this program. If not,
20 # see <https://www.lsstcorp.org/LegalNotices/>.
21 #
22 """
23 Apply intra-CCD crosstalk corrections
24 """
25 
26 import lsst.afw.math
27 import lsst.afw.table
28 import lsst.afw.detection
29 from lsst.pex.config import Config, Field, ChoiceField
30 from lsst.pipe.base import Task
31 
32 __all__ = ["CrosstalkConfig", "CrosstalkTask", "subtractCrosstalk", "writeCrosstalkCoeffs",
33  "NullCrosstalkTask"]
34 
35 
36 class CrosstalkConfig(Config):
37  """Configuration for intra-CCD crosstalk removal"""
38  minPixelToMask = Field(
39  dtype=float,
40  doc="Set crosstalk mask plane for pixels over this value.",
41  default=45000
42  )
43  crosstalkMaskPlane = Field(
44  dtype=str,
45  doc="Name for crosstalk mask plane.",
46  default="CROSSTALK"
47  )
48  crosstalkBackgroundMethod = ChoiceField(
49  dtype=str,
50  doc="Type of background subtraction to use when applying correction.",
51  default="None",
52  allowed={
53  "None": "Do no background subtraction.",
54  "AMP": "Subtract amplifier-by-amplifier background levels.",
55  "DETECTOR": "Subtract detector level background."
56  },
57  )
58 
59 
60 class CrosstalkTask(Task):
61  """Apply intra-CCD crosstalk correction"""
62  ConfigClass = CrosstalkConfig
63  _DefaultName = 'isrCrosstalk'
64 
65  def prepCrosstalk(self, dataRef):
66  """Placeholder for crosstalk preparation method, e.g., for inter-CCD crosstalk.
67 
68  Parameters
69  ----------
70  dataRef : `daf.persistence.butlerSubset.ButlerDataRef`
71  Butler reference of the detector data to be processed.
72 
73  See also
74  --------
75  lsst.obs.decam.crosstalk.DecamCrosstalkTask.prepCrosstalk
76  """
77  return
78 
79  def run(self, exposure, crosstalkSources=None, isTrimmed=False):
80  """Apply intra-CCD crosstalk correction
81 
82  Parameters
83  ----------
84  exposure : `lsst.afw.image.Exposure`
85  Exposure for which to remove crosstalk.
86  crosstalkSources : `defaultdict`, optional
87  Image data and crosstalk coefficients from other CCDs/amps that are
88  sources of crosstalk in exposure.
89  The default for intra-CCD crosstalk here is None.
90  isTrimmed : `bool`
91  The image is already trimmed.
92  This should no longer be needed once DM-15409 is resolved.
93 
94  Raises
95  ------
96  RuntimeError
97  Raised if called for a detector that does not have a
98  crosstalk correction
99  """
100  detector = exposure.getDetector()
101  if not detector.hasCrosstalk():
102  raise RuntimeError("Attempted to correct crosstalk without crosstalk coefficients")
103  self.log.info("Applying crosstalk correction")
104  subtractCrosstalk(exposure, minPixelToMask=self.config.minPixelToMask,
105  crosstalkStr=self.config.crosstalkMaskPlane, isTrimmed=isTrimmed,
106  backgroundMethod=self.config.crosstalkBackgroundMethod)
107 
108 
109 # Flips required to get the corner to the lower-left
110 # (an arbitrary choice; flips are relative, so the choice of reference here is not important)
111 X_FLIP = {lsst.afw.table.LL: False, lsst.afw.table.LR: True,
112  lsst.afw.table.UL: False, lsst.afw.table.UR: True}
113 Y_FLIP = {lsst.afw.table.LL: False, lsst.afw.table.LR: False,
114  lsst.afw.table.UL: True, lsst.afw.table.UR: True}
115 
116 
118  def run(self, exposure, crosstalkSources=None):
119  self.log.info("Not performing any crosstalk correction")
120 
121 
122 def extractAmp(image, amp, corner, isTrimmed=False):
123  """Return an image of the amp
124 
125  The returned image will have the amp's readout corner in the
126  nominated `corner`.
127 
128  Parameters
129  ----------
130  image : `lsst.afw.image.Image` or `lsst.afw.image.MaskedImage`
131  Image containing the amplifier of interest.
132  amp : `lsst.afw.table.AmpInfoRecord`
133  Amplifier information.
134  corner : `lsst.afw.table.ReadoutCorner` or `None`
135  Corner in which to put the amp's readout corner, or `None` for
136  no flipping.
137  isTrimmed : `bool`
138  The image is already trimmed.
139  This should no longer be needed once DM-15409 is resolved.
140 
141  Returns
142  -------
143  output : `lsst.afw.image.Image`
144  Image of the amplifier in the standard configuration.
145  """
146  output = image[amp.getBBox() if isTrimmed else amp.getRawDataBBox()]
147  ampCorner = amp.getReadoutCorner()
148  # Flipping is necessary only if the desired configuration doesn't match what we currently have
149  xFlip = X_FLIP[corner] ^ X_FLIP[ampCorner]
150  yFlip = Y_FLIP[corner] ^ Y_FLIP[ampCorner]
151  return lsst.afw.math.flipImage(output, xFlip, yFlip)
152 
153 
154 def calculateBackground(mi, badPixels=["BAD"]):
155  """Calculate median background in image
156 
157  Getting a great background model isn't important for crosstalk correction,
158  since the crosstalk is at a low level. The median should be sufficient.
159 
160  Parameters
161  ----------
162  mi : `lsst.afw.image.MaskedImage`
163  MaskedImage for which to measure background.
164  badPixels : `list` of `str`
165  Mask planes to ignore.
166 
167  Returns
168  -------
169  bg : `float`
170  Median background level.
171  """
172  mask = mi.getMask()
174  stats.setAndMask(mask.getPlaneBitMask(badPixels))
175  return lsst.afw.math.makeStatistics(mi, lsst.afw.math.MEDIAN, stats).getValue()
176 
177 
178 def subtractCrosstalk(exposure, badPixels=["BAD"], minPixelToMask=45000,
179  crosstalkStr="CROSSTALK", isTrimmed=False,
180  backgroundMethod="None"):
181  """Subtract the intra-CCD crosstalk from an exposure
182 
183  We set the mask plane indicated by ``crosstalkStr`` in a target amplifier
184  for pixels in a source amplifier that exceed `minPixelToMask`. Note that
185  the correction is applied to all pixels in the amplifier, but only those
186  that have a substantial crosstalk are masked with ``crosstalkStr``.
187 
188  The uncorrected image is used as a template for correction. This is good
189  enough if the crosstalk is small (e.g., coefficients < ~ 1e-3), but if it's
190  larger you may want to iterate.
191 
192  This method needs unittests (DM-18876), but such testing requires
193  DM-18610 to allow the test detector to have the crosstalk
194  parameters set.
195 
196  Parameters
197  ----------
198  exposure : `lsst.afw.image.Exposure`
199  Exposure for which to subtract crosstalk.
200  badPixels : `list` of `str`
201  Mask planes to ignore.
202  minPixelToMask : `float`
203  Minimum pixel value (relative to the background level) in
204  source amplifier for which to set ``crosstalkStr`` mask plane
205  in target amplifier.
206  crosstalkStr : `str`
207  Mask plane name for pixels greatly modified by crosstalk.
208  isTrimmed : `bool`
209  The image is already trimmed.
210  This should no longer be needed once DM-15409 is resolved.
211  backgroundMethod : `str`
212  Method used to subtract the background. "AMP" uses
213  amplifier-by-amplifier background levels, "DETECTOR" uses full
214  exposure/maskedImage levels. Any other value results in no
215  background subtraction.
216  """
217  mi = exposure.getMaskedImage()
218  mask = mi.getMask()
219 
220  ccd = exposure.getDetector()
221  numAmps = len(ccd)
222  coeffs = ccd.getCrosstalk()
223  assert coeffs.shape == (numAmps, numAmps)
224 
225  # Set background level based on the requested method. The
226  # thresholdBackground holds the offset needed so that we only mask
227  # pixels high relative to the background, not in an absolute
228  # sense.
229  thresholdBackground = calculateBackground(mi, badPixels)
230 
231  backgrounds = [0.0 for amp in ccd]
232  if backgroundMethod is None:
233  pass
234  elif backgroundMethod == "AMP":
235  backgrounds = [calculateBackground(mi[amp.getBBox()], badPixels) for amp in ccd]
236  elif backgroundMethod == "DETECTOR":
237  backgrounds = [calculateBackground(mi, badPixels) for amp in ccd]
238 
239  # Set the crosstalkStr bit for the bright pixels (those which will have significant crosstalk correction)
240  crosstalkPlane = mask.addMaskPlane(crosstalkStr)
241  footprints = lsst.afw.detection.FootprintSet(mi, lsst.afw.detection.Threshold(minPixelToMask +
242  thresholdBackground))
243  footprints.setMask(mask, crosstalkStr)
244  crosstalk = mask.getPlaneBitMask(crosstalkStr)
245 
246  # Do pixel level crosstalk correction.
247  subtrahend = mi.Factory(mi.getBBox())
248  subtrahend.set((0, 0, 0))
249  for ii, iAmp in enumerate(ccd):
250  iImage = subtrahend[iAmp.getBBox() if isTrimmed else iAmp.getRawDataBBox()]
251  for jj, jAmp in enumerate(ccd):
252  if ii == jj:
253  assert coeffs[ii, jj] == 0.0
254  if coeffs[ii, jj] == 0.0:
255  continue
256 
257  jImage = extractAmp(mi, jAmp, iAmp.getReadoutCorner(), isTrimmed)
258  jImage.getMask().getArray()[:] &= crosstalk # Remove all other masks
259  jImage -= backgrounds[jj]
260 
261  iImage.scaledPlus(coeffs[ii, jj], jImage)
262 
263  # Set crosstalkStr bit only for those pixels that have been significantly modified (i.e., those
264  # masked as such in 'subtrahend'), not necessarily those that are bright originally.
265  mask.clearMaskPlane(crosstalkPlane)
266  mi -= subtrahend # also sets crosstalkStr bit for bright pixels
267 
268 
269 def writeCrosstalkCoeffs(outputFileName, coeff, det=None, crosstalkName="Unknown", indent=2):
270  """Write a yaml file containing the crosstalk coefficients
271 
272  The coeff array is indexed by [i, j] where i and j are amplifiers
273  corresponding to the amplifiers in det
274 
275  Parameters
276  ----------
277  outputFileName : `str`
278  Name of output yaml file
279  coeff : `numpy.array(namp, namp)`
280  numpy array of coefficients
281  det : `lsst.afw.cameraGeom.Detector`
282  Used to provide the list of amplifier names;
283  if None use ['0', '1', ...]
284  ccdType : `str`
285  Name of CCD, used to index the yaml file
286  If all CCDs are identical could be the type (e.g. ITL)
287  indent : `int`
288  Indent width to use when writing the yaml file
289  """
290 
291  if det is None:
292  ampNames = [str(i) for i in range(coeff.shape[0])]
293  else:
294  ampNames = [a.getName() for a in det]
295 
296  assert coeff.shape == (len(ampNames), len(ampNames))
297 
298  dIndent = indent
299  indent = 0
300  with open(outputFileName, "w") as fd:
301  print(indent*" " + "crosstalk :", file=fd)
302  indent += dIndent
303  print(indent*" " + "%s :" % crosstalkName, file=fd)
304  indent += dIndent
305 
306  for i, ampNameI in enumerate(ampNames):
307  print(indent*" " + "%s : {" % ampNameI, file=fd)
308  indent += dIndent
309  print(indent*" ", file=fd, end='')
310 
311  for j, ampNameJ in enumerate(ampNames):
312  print("%s : %11.4e, " % (ampNameJ, coeff[i, j]), file=fd,
313  end='\n' + indent*" " if j%4 == 3 else '')
314  print("}", file=fd)
315 
316  indent -= dIndent
def run(self, exposure, crosstalkSources=None, isTrimmed=False)
Definition: crosstalk.py:79
std::shared_ptr< ImageT > flipImage(ImageT const &inImage, bool flipLR, bool flipTB)
def subtractCrosstalk(exposure, badPixels=["BAD"], minPixelToMask=45000, crosstalkStr="CROSSTALK", isTrimmed=False, backgroundMethod="None")
Definition: crosstalk.py:180
def run(self, exposure, crosstalkSources=None)
Definition: crosstalk.py:118
Statistics makeStatistics(lsst::afw::math::MaskedVector< EntryT > const &mv, std::vector< WeightPixel > const &vweights, int const flags, StatisticsControl const &sctrl=StatisticsControl())
def calculateBackground(mi, badPixels=["BAD"])
Definition: crosstalk.py:154
def extractAmp(image, amp, corner, isTrimmed=False)
Definition: crosstalk.py:122
def prepCrosstalk(self, dataRef)
Definition: crosstalk.py:65
def writeCrosstalkCoeffs(outputFileName, coeff, det=None, crosstalkName="Unknown", indent=2)
Definition: crosstalk.py:269