User Background Images

As of Phase 2 for P106, we have implemented the possibility for users to upload their own FITS files to be used as the background image for ObsPrep and p2fc.

Currently, from the p2 web interface, this is only available via ObsPrep and so currently only for the limited number of instruments supported by ObsPrep (i.e. ESPRESSO, HAWKI, MUSE, UVES, VISIR and XSHOOTER).

p2 web support for user background images for instruments not yet supported by ObsPrep is... coming soon... hopefully in time for P106 Phase 2 (August 2020).

User background images are fully supported by the Python p2api package.

Supported file formats

Only FITS files can be used as user background images. The FITS files must satify the following requirements:

  • the file must contain an image. BOTH single HDU and Multi-Extension FITS files can be handled. In particular it can handle ESO instrument RAW images, pipepline products and ADPs from the Science Archive Facility.
  • each image HDU must contain a valid WCS
  • the target of the OB must be locate within the field of view of the image
  • if the OB includes a Blind Offset Acquisition [BOA], the BOA reference star must also be within the field of view of the image.

In the case of MEF 'paw-print' type files, the check for the location of the target and the reference star of the Blind Offset Acqusition (if defined) is done within each extension, i.e. if the target or BOA reference fall within a gap between chips, this check will fail.

How does it work?

The basic steps of the User Background Image upload process is as follows:

  1. The FITS file is uploaded to the p2fc server via HTTPS, this can take anywhere from seconds to minutes, depending on the size of the image and the user's upload bandwidth to ESO HQ in Garching, DE.
  2. Once the image has arrived it is checked for:
    • at least one HDU containing an image or images (note all image type HDUs are assumed to be "displayable", i.e. things will probably go horribly wrong if the file contains an image HDU and a bad-pixel map HDU (as an image) for example)
    • compatibility with the OB (coordinates of target and BOA reference star are within the field of view)
    • either the BANDPASS or FILTER keyword in the header (or in the case of many ESO and GEMINI images "appropriate" header keywords from which the filter can be derived in general ESO RAW, pipeline product and SAF-ADP images should work 'out-of the box', as should GEMINI archive images).
    If any of these tests fail, the process stops here and no data is stored on the p2fc server. An error message is sent back to the p2 web server.
  3. If the uploaded file is a MEF, a 'tiled' version is generated using SWarp.
  4. A HiPS represetation is generated for use by ObsPrep.
  5. The FITS and HiPS representations are written to disk for future use. A successfully uploaded image is then available for use in any run and any compatible OB of the user who uploaded the image.
  6. If the image was uploaded via ObsPrep it is displayed in the Aladin Lite window.

Delegation

The owner of an image is the user who uploaded the image. When the image is first uploaded it is associated only with the run of the OB that the image was uploaded for. But the image is available for use in any run owned by the owner, or delegated to the owner.

If an already-uploaded image is subsequetly "used" by an OB in another run owned by the image owner, or delegated to the image owner, then that image becomes associated to that secondary run. In this context "using" an image means simply once selecting it from the list of "My images" in the ObsPrep Background Image selector window.

Once an image has been associated to a run by the image owner, (either via direct upload to an OB in that run, or by subsequent use of an already uploaded image in an OB of that run) it is then accessible to all users who have access to that run, either by owning the run or by being a Phase 2 delegate for that run.

A Phase 2 delegate then has access to all of their own images plus any and all images associated with any and all runs owned by or delegated to them. However when a delegate uses an image in a run that the image owner has not used it in, the image does NOT become associated to that run -- only the image owner can associate an image with an additional run. This means that a delegate of the delegate (who is not also delegated one or more runs of that the image owner used the image in) can not use the image, even though they can see it in the ObsPrep Aladin Lite window.

Deleting uploaded images

The image owner can delete an uploaded image by clicking on the trash can icon in the "My Images" section of the ObsPrep "Background image" manager popup window. This will unasscociate the image with all runs it is currently associated with. Subsequently re-uploading the image will then associate it with only the run of the OB it is uploaded for. It will have to be used in the OBs of other runs to (re-)associate it with those runs.

Disk space and culling

The p2fc server has limited storage for uploaded user background images. Disk space is managed automatically and as the disk usage nears maximum capacity images will be automatically "culled" (i.e. removed from the disk). Images used longest ago are culled first.

We hope that the available disk space will be sufficient to retain the user background images of a given period for the duration of that period.


Instrument selector