APT Aladin Viewer

The JWST Aladin visualization tool has been integrated into APT to allow users to visualize their observations onto the celestial sphere.

On this page

Brief overview 

  Aladin Overview in APT Video Tutorial,   Using Aladin and APT Visit Planner Video Tutorial

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

The Aladin Visualization tool is software from the Centre de Données astronomiques de Strasbourg that has been integrated into APT to assist users with visualizing their proposed observations onto various sky views such as the Palomar Digitized Sky Survey, 2MASS, Galex, SDSS, or a number of other selectable options. The Aladin tool is accessed in APT by selecting one or more visits or observations in the tree editor on the left side of the APT GUI and selecting the View in Aladin icon on the APT top tool menu bar. The APT GUI changes to show Aladin control options and a separate window opens to show the visualization. Users can move back and forth between the form editor and the APT Aladin control panel as needed to change what is being displayed, but the visualization display window stays open until closed by the user.
Figure 1. The screen view after opening Aladin and displaying the DSS image for a particular visit from a mosaic of M82

The screen view showing the APT Aladin control panel at left and the Aladin display window at right. The windows are separate and can be moved and resized independently. The Load DSS box is highlighted on the left, and the background display options are highlighted in the right panel.

Interactions between Aladin and APT

Our goal here is not to provide a complete overview of this tool, but rather highlight a few aspects that should be most useful to proposers. The implementation in APT is largely the same for the HST and JWST branches of APT, but there are aspects that are specific to one or the other branches. Video training help is available and recommended for learning some of the ins and outs of Aladin, but many features are intuitive. You are encouraged to play around with the many options provided by the Aladin tool itself and the APT interface to it.

Hint: after opening the View in Aladin tool and selecting an observation or visit, click the Load DSS box in the APT Aladin control window (see Fig. 1) to see the background image in the Aladin display window. If a different sky survey is desired for the display, the options are selected directly from within the Aladin display window. also highlighted in Fig. 1.

Note: The target shown in the Aladin display does not update automatically when observations or visits from a different target are selected in the APT tree editor. The user must click the Load DSS box in the APT Aladin control window for each new target to force the display to update. Switching between multiple observations or visits on the same target does not require an update. For further details and special cases, refer to this Knowledge article in the JWST Help Desk.

The APT Aladin control window in the APT GUI contains a number of helpful features that can be turned on and off as desired, depending on the application (see Figure 2). The Load DSS box has already been mentioned, but a few others of special interest include:

  • FoV button: toggles the entire set of JWST instrument footprints, showing the the entire JWST focal plane. Of course, unless the position angle of the selected observation or visit has been set, this is just provisional. But if the position angle has been fixed (or a range provided), this display will show the actual expected relative positions of the different instrument FoVs with respect to the selected visit or observation. This can be useful for planning coordinated parallel observations with a second instrument, for example.

  • Orient Ranges button: When a position angle or range has been set on a given observation, this display is useful for showing the allowed range of motion for the reference angle of the selected instrument. A circle is displayed, where the green portion indicates the selected PA or range and the red portion shows disallowed ranges. If a PA range was given, the display will show the orientation at the middle of the range.

  • Coverage Circles button: this display simply shows what happens when the selected field of view is rotated on the sky. So for example, if an imaging mosaic has been specified, but the position angle has not been restricted, this display shows the full area that in principle might be within the field of view at the time of the observation.

  • Grid button: simply projects a coordinate grip over the Aladin display.

  • Single Aperture button: For certain instrument modes, this button toggles to a simplified view of the field overlay. For example, if a complicated dither pattern has been selected, choosing Single Aperture simplifies the display to show a single dither step.

Figure 2 shows a particular example of the Aladin display resulting from selecting a few of these options.

Figure 2. The APT Aladin Display window showing several of the optional display features described in this article

The positions of other JWST instrument FoVs (gray boxes) can be seen relative to the selected NIRCam visit (shown in blue). A coordinate grid is overlaid on the display. The green portion of the circle shows that an orient range has been selected for this visit (147°-167°). The display is shown at the midpoint of the range. There are many additional Aladin display controls along the right side of the image window that are not described here.

Adjusting a target's coordinates

One of the most useful interactions between the Aladin display and APT is the ability to move a displayed JWST field of view by grabbing it with the cursor. For example, if a provisional coordinate of an extended source was entered initially, a given instrument FoV can be repositioned to optimize the spatial coverage.  

By choosing the Select option in the Aladin display panel, click and drag a given displayed FoV to the desired position. This manual adjustment shows up in the APT Aladin Control GUI, as shown in Figure 3. If you decide to keep the indicated change, you can either commit a particular selected change or commit all listed changes back into your proposal by selecting the appropriate button on the left side of the APT Aladin control window.  Note that by doing this you are changing the actual coordinate of the target. (This can be confirmed by reviewing the target information in the Target section of the tree editor.)  If this target is used in other observations, the positional change will impact them as well. It is the user's responsibility to verify this is the intended effect.

If a mosaic observation is displayed, grabbing any mosaic tile and rotating it to a new position angle is followed very shortly by a repositioning of the entire mosaic pattern in the display. This is a result of the way mosaic observations are defined. See the APT Mosaics article for more information.

Figure 3. The APT Aladin Control window showing several of the features described in the article

This example shows the Aladin control window for a selected observation.  A potential change in position of the target in this observation has been made in the display, resulting in the red information in the Pending Changes GUI. This change will not be saved unless you use one of the Commit buttons at left, in which case the change is fed back into this target information in the proposal. Use the appropriate Clear button to negate the potential change and reset the display. Note the control buttons for FoV, Orient Ranges, and Grid, across the top of the figure, which are the options that have been turned on in Figure 2 to show their effects on the display.

Adjusting an observation's position angle

By default, if the desired position angle of a given observation or visit has not been constrained to a specific value or range using a special requirement, the selected instrument footprint will be shown in the Aladin display at a reference angle of V3PA = 0°. However, recall that the allowed position angles for a given target depend strongly on the ecliptic latitude of the target, and will also vary as a function of time through the target's visibility window(s). The actual allowed position angles and ranges for a target can be determined using the General Target Visibility Tool or by running the APT Visit Planner and inspecting the resulting Total Roll Analysis for Visit report.

A word of caution: Aladin will allow you to rotate a given field of view through the entire 360° range, but this does not mean that all angles are necessarily allowed for JWST observations of a particular target. Running the APT Visit Planner with a given position angle (or range) specified as a special requirement is the best way to verify the actual schedulability.

If the science case requires a specific position angle or restricted range of position angle, this can be set with the position angle special requirement in the APT observation GUI. Figure 2 above shows an example where a PA range of 147°–167° has been set, and the Orient Ranges option has been selected. The reference position for the NIRCam observation selected is shown at the midpoint of the range (157°). Hovering the cursor over a corner of the instrument FoV in the Aladin display, one can rotate the FoV to see how the spatial coverage changes over the selected PA range.

A Caveat: timing constraints vs. position angle constraints

For JWST observing, there is a correlation between the time of a target's observation and the expected range of position angle available for the field of view on the sky at that time. However, Aladin in APT does not translate timing constraints into position angle constraints automatically. That is, as described above, if you set a position angle range on an observation, the allowed range can be viewed in the Aladin display using the Orient Ranges button (see Fig. 2). If you instead set a time range special requirement on the observation, the Aladin display does not update but rather still shows the selected field of view overlay at the default (V3PA = 0°).

Note: this is different than users of the Spitzer Space Telescope's SPOT tool will have experienced. SPOT did update the display of the field of view when a timing constraint was added; APT Aladin does not. 

There are 2 workarounds for this situation, both of which involve inspection of the Total Roll Analysis for Visit report in the APT Visit Planner. After setting the desired timing special requirement on an observation, run the Visit Planner to check the schedulability. Then, open the Total Roll Analysis for Visit report as described in the APT Visit Planner article (see Figure 4 in that article), which shows the V3PA angle as a function of date. With this information, you can either (a) return to the Aladin display and manually adjust the displayed FoV to the allowed angle(s) for inspection, or (b) you can consider translating the timing constraint into the equivalent position angle constraint and specifying that instead of the timing constraint. Then, the display will be shown as described above, using the Orient Ranges button.

A convenient alternative to using the Visit Planner for converting a timing window into a position angle range would be to run the General Target Visibility Tool, which provides this information in both tabular and graphical forms.

Aladin visualization tool information

Aladin Desktop & Aladin Lite are developed by the Centre de Données astronomiques de Strasbourg.
Both are distributed under GPL v3 licence. 


If the Aladin Sky Atlas was helpful for your research work, the following citation would be appreciated: This research has made use of "Aladin sky atlas" developed at CDS, Strasbourg Observatory, France → 2000A&AS..143...33B and 2014ASPC..485..277B.

Latest updates
    New figures and revised and expanded text to address comments.

  • Added revised video help links.

    Updated for APT 27.1 release, including figures

    Added links to three new Aladin tutorial videos

  • Figures 2 and 3 updated to APT 25.4.1.
Originally published