The unified GuideCam Tool

What is the unified GuideCam tool?

The unified GUideCam Tool (GUCT) is a Java-based observation preparation tool currently offered for VISIR, HAWK-I, and MUSE. The tool makes use of the Aladin desktop application (v9.0) and allows the user to visualize the instrument Field-of-View on a sky image, define the central pointing of the telescope, plan observations that involve a sequence of telescope offsets, select telescope guide stars, tip-tilt stars and/or AO guide stars, and create ESO compliant finding charts. Furthermore, GUCT v2.3.1 can directly interact with the web-based application p2 in order to attach finding charts or to propagate template parameters, such as guide star coordinates and/or observing offsets to the OB.

IMPORTANT note for VISIR users: GUCT replaced the VISIR-specific GuideCam tool.

Supported Platforms

The unified Guidecam Tool is platform independent and works on macOS and Linux operating systems. But, it has not been tested under Windows, and compatibility tests under Windows are also not foreseen.

Latest release

The current version of the unified GuideCam tool is v2.3.1 released on 20 December 2018. The current version supports the instruments VISIR, HAWK-I and MUSE. With respect to the previous version (v.2.2.2) this release includes the support of HAWK-I Fast Phot and MUSE narrow-field mode (NFM) observation preparation, as well as some general improvements and bug fixes. It only interacts with the web-based application p2. All P103 users should use the latest release (v.2.3.x). 

Guidecam Installation

To install the unified GuideCam tool, you can either use the ESO Mac & Linux software repositories, or you can retrieve the tarball and install it via the instructions provided below.

ESO Mac & Linux software repositories

GuideCam requires Java (version 1.8, note GuideCam is currenty not compatile with Java > 8). Java is automatically pulled in for installation as needed for installation via any of the Linux software repositories, but for installation on macOS please make sure that the Java executable can be found by the system (try the command "java -version" from the command line), or alternatively define the environment variable JAVA_HOME to point to the installation directory of Java, e.g. with a command such as:

export JAVA_HOME=/home/someuser/jre

Otherwise an appropriate JDK should be installed from Oracle, or similar.

To install the relevant repository, please follow the relevant instructions at ESO Mac & Linux software repositories. In the final instruction for each OS/distribution replace the generic <package_name> with eso-guidecamtool. i.e. one of the following, as appropriate for your OS/distribution (see below for temporary MacPorts instructions):

sudo dnf install eso-guidecamtool
sudo yum install eso-guidecamtool
sudo apt-get install eso-guidecamtool

Once installed simply issue the command GuideCamTool to run the software.

Temporary MacPorts instructions

Currently, a technical issue prevents ESO from creating new MacPorts packages via its standard infrastructure. In the meantime, please follow the instruction below to install/upgarde to the latest version of the GuideCam Tool in MacPorts:

cd /tmp
curl -O
sudo port install


Installation from tarball

GuideCam requires Java (version 1.8, note GuideCam is currenty not compatile with Java > 8). Please make sure that the Java executable can be found by the system (try the command "java -version" from the command line), or alternatively define the environment variable JAVA_HOME to point to the installation directory of Java, e.g. with a command such as:

export JAVA_HOME=/home/someuser/jre

Otherwise an appropriate JDK should be installed via your package management system or from Oracle, or similar.

Once Java is installed, please follow these steps:

  • Move to the directory where you want to install GUCT.
  • Download the following tarball to the chosen directory:
  • Unpack the tarball gunzip -c GuideCamTool[Version].tar.gz | tar xvf -

    This creates a directory structure that starts with:

  • Move to the GUCT directory:  cd GuideCamTool[Version]
  • STRONGLY RECOMMENDED: if you had previously GUCT version 1.x installed on your computer, first remove the default configuration file from your home directory: rm $HOME/.GuideCamTool/preferences/default.json
  • Start-up the software ./bin/GuideCamTool

    If the GUCT control panel and the Aladin sky view panel appear, you have successfully installed GUCT. You can delete the compressed TAR file.

Unified Guidecam tool Users' Manual


  • The Unified Guidecam tool (GUCT) Users Manual is available for download (PDF file)



VIMOS specific comments on the unified GuideCam tool

In view of the experience obtained during the previous semesters of VIMOS operations, the selection of a guide star by the user with the unified Guidecam tool (GUCT) is mandatory for all (pre-)imaging observations. The user must select a guide star which does not vignet the field of view or, in case this is not possible, a guide star that produces acceptable vignetting, for example by blocking only those regions of the detector array where no objects of scientific interest are found. It is recommended to select, in addition to the first selected guide star, an alternate guide star. GUCT will save the information for the alternate guide star in the associated finding chart metadata.

Once the user has selected a suitable guide star (plus an alternative one), the following parameters of the first guide star are automatically transfered to the acquisition template (e.g. VIMOS_img_acq_Preset) via the "pass setup to P2PP" action in GUCT: coordinates of the guide star ('Guide Star RA' and 'Guide Star DEC' template keywords) and guide probe orientation (PPOS keyword either POS or NEG value). The 'Get Guide Star from' entry field in the acquisition template will be set to SETUPFILE, and the 'Rotator angle on sky' is transfered as well.

Please select the guide star carefully, especially in the case of imaging observations involving offsets! It is the responsibility of the user to check with GUCT that the chosen guide star does not produce unacceptable vignetting in any of the frames to be produced by the execution of an OB. ESO will consider as executed within specifications an OB producing vignetted frames, implicitly assuming that such vignetting was already verified by the user and found to be acceptable.

In case that the selected guide star turns out to be inaccessible during the execution of the OB, the telescope operator will try to select the defined alternative guide star and use it for the observation, even if it produces vignetting. ESO reserves the right to charge to the time allocated to the run the time spent in identifying and setting up the alternative guide star.

Observation preparation with PILMOS

Upgrades to VIMOS between 2010 and 2012 have improved its stability and a detailed investigation into the accuracy to which slit positions could be predicted concluded that for many realistic observing programmes it would be possible to skip pre-imaging and directly produce the VIMOS MOS masks based on contributed catalogues. As of June 2012 Pre-ImageLess Multi Object Spectroscopy (PILMOS) is being offered as an option to VIMOS users.

To use the PILMOS mode, the contributed catalogues must have:

  • Very good (<0.2") relative astrometric precision for targets coordinates (RA,DEC) on a single astrometric
  • The list of targets must include some relatively bright reference stellar sources used to align the MOS masks.
  • Absolute astrometry must have <2" accuracy with respect to the guide star catalogue from which the guide star is selected.

The PILMOS observations have the following restrictions:

  • The slit width must be 1" or larger.
  • The position angle must be 90 degrees, or 0 degree for targets with -45<DEC<-5 deg (same rule as for MOS observations).
  • The airmass restriction is the same as for MOS observations: it is not allowed to observe beyond +/-3h (if declination within -45<DEC<-5 deg and rotator at 0 deg) or +/-2h (if rotator at 90 deg) from the meridian.
  • No curved or tilted slits.

Observations that cannot be made within these constraints must use the conventional pre-image approach.

The observation preparation for PILMOS mode is performed with the GUCT tool. The user must select a suitable guide star and the guide probe orientation, and then run the PILMOS mode of GUCT for creation of the fake pre-images and VIMOS catalogues that are then fed to the standard VIMOS mask preparation software VMMPS. If you want to change the names of the fake images and VIMOS catalogues please make sure that they still contain the string 'pilmos' in their names. Else, they are not valid.

The GUCT/PILMOS mode allows the user to upload his/her contributed catalogue, which contains accurate and precise coordinates of potential spectroscopic targets and reference stars, and to transform it into a VIMOS catalogue suitable for mask design in VMMPS. In addition, it generates four fake images, one per quadrant, that are used together with the transformed catalogue as input to VMMPS. More information about the format of the contributed catalogues you can find in the chapter 'PILMOS tutorial' in the VIMOS User Manual.

Please note that PILMOS OBs must have a finding chart created with the GUCT tool attached, in addition to the 4 finding charts created with VMMPS, one per quadrant, showing the slits mask design. The VMMPS finding charts must be based on the fake PILMOS images. Do not use true-sky images for the finding charts!

Instrument selector