ExposureInjectTask¶
Inject Synthetic Sources Into Single-Frame Exposures¶
ExposureInjectTask injects synthetic sources into single-frame exposures.
A user-supplied input catalog defines the positions and characteristics for
synthetic sources to be generated.
If the user opts instead to inject pre-built FITS postage stamp images, the
path to these must be supplied.
The GalSim software package is used to generate synthetic postage stamps
(if required) before performing source injection into an image.
As an output, an injected_ variant of the input dataset type will be created.
For exposure-level imaging, the default input is a postISRCCD dataset type,
producing an injected_postISRCCD output.
Processing Summary¶
ExposureInjectTask runs this sequence of operations:
the input injection catalog is loaded and column names standardized;
injection sources are cleaned according to certain criteria, including:
missing or erroneous magnitude information;
centroids that do not fall close to the injection area;
sources not selected by virtue of their visit or selection flag;
a source type which is not a supported GSObject class;
extreme Sérsic indices (i.e., outside the range \(0.3 \le n \le 6.2\));
the input source is converted into a GalSim object:
no attempt at source injection will be made if the fully realized bounding box does not overlap with the injection image;
sources are injected into the exposure injection image using GalSim;
provenance metadata is added to the resultant source injected dataset;
the injected image and associated injected catalog are output.
Python API Summary¶
from lsst.source.injection.inject_exposure import ExposureInjectTask
-
class
ExposureInjectTask(*, config=None, log=None, initInputs=None, **kwargs) Exposure-level class for injecting sources into images
...
- attributeconfig
Access configuration fields and retargetable subtasks.
-
method
run(injection_catalogs, input_exposure, psf, photo_calib, wcs) Inject sources into an image
...
See also
See the ExposureInjectTask API reference for complete details.
Configuration Fields¶
calib_flux_radius¶
Aperture radius (in pixels) that was used to define the calibration for this image+catalog. This will be used to produce the correct instrumental fluxes within the radius. This value should match that of the field defined in slot_CalibFlux_instFlux.
col_dec¶
Column name for declination (in degrees).
col_draw_size¶
Column name providing pixel size of the region into which the source profile will be drawn. If this column is not provided as an input, the GalSim method getGoodImageSize will be used instead.
col_mag¶
Column name for magnitude.
col_ra¶
Column name for right ascension (in degrees).
col_source_type¶
Column name for the source type used in the input catalog. Must match one of the surface brightness profiles defined by GalSim.
col_stamp¶
Column name to identify FITS file postage stamps for direct injection. The strings in this column will be prefixed with a string given in stamp_prefix, to assist in providing the full path to a FITS file.
col_trail_length¶
Column name for specifying a satellite trail length (in pixels).
connections¶
- Data type
lsst.pipe.base.config.ExposureInjectConfigConnections- Field type
Configurations describing the connections of the PipelineTask to datatypes
external_photo_calib¶
If True, use the photometric calibration from a visit summary table. If False (default), use the photometric calibration attached to the input exposure.
external_psf¶
If True, use the PSF model from a visit summary table. If False (default), use the PSF model attached to the input exposure.
external_wcs¶
If True, use the astrometric calibration from a visit summary table. If False (default), use the astrometric calibration attached to the input exposure.
fits_alignment¶
- Default
'pixel'- Field type
strChoiceField(optional)- Choices
'wcs'Input image will be transformed such that the local WCS in the FITS header matches the local WCS in the target image. I.e., North, East, and angular distances in the input image will match North, East, and angular distances in the target image.
'pixel'Input image will **not** be transformed. Up, right, and pixel distances in the input image will match up, right and pixel distances in the target image.
NoneField is optional
How should injections from FITS files be aligned?
mask_plane_name¶
Name assigned to the injected mask plane which is attached to the output exposure.
process_all_data_ids¶
If True, all input data IDs will be processed, even those where no synthetic sources were identified for injection. In such an eventuality this returns a clone of the input image, renamed to the output_exposure connection name and with an empty mask_plane_name mask plane attached.
saveLogOutput¶
Flag to enable/disable saving of log output for a task, enabled by default.
selection¶
A string that can be evaluated as a boolean expression to select rows in the input injection catalog. To make use of this configuration option, the internal object name injection_catalog must be used. For example, to select all sources with a magnitude in the range 20.0 < mag < 25.0, set selection="(injection_catalog['mag'] > 20.0) & (injection_catalog['mag'] < 25.0)". The {visit} field will be substituted for the current visit ID of the exposure being processed. For example, to select only visits that match a user-supplied visit column in the input injection catalog, set selection="np.isin(injection_catalog['visit'], {visit})".
stamp_prefix¶
String to prefix to the entries in the col_stamp column, for example, a directory path.
trim_padding¶
Size of the pixel padding surrounding the image. Only those synthetic sources with a centroid falling within the image + trim_padding region will be considered for source injection.
Examples¶
An example calling this task from the command line using pipetask run:
pipetask --long-log --log-file $LOGFILE \
run --register-dataset-types \
-b $REPO \
-i $INPUT_DATA_COLL,$INJECTION_CATALOG_COLL \
-o $OUTPUT_COLL \
-p $SOURCE_INJECTION_DIR/pipelines/inject_exposure.yaml \
-d "instrument='HSC' AND exposure=1228 AND detector=51"
where
$LOGFILEThe full path to a user-defined output log file.
$REPOThe path to the butler repository.
$INPUT_DATA_COLLThe name of the input data collection.
$INJECTION_CATALOG_COLLThe name of the input injection catalog collection.
$OUTPUT_COLLThe name of the injected output collection.
$SOURCE_INJECTION_DIRThe path to the source injection module directory.
Debugging¶
Additional debug-level log information may be shown by setting the log-level option to DEBUG at runtime:
pipetask --log-level DEBUG ...